# Proposal: implement-manual-takeover

## 概述

实现首页"人工接管"按钮的完整功能，包括API对接、状态更新、UI反馈和状态持久化。

## 背景

当前首页已存在"人工接管"按钮（位于 `FloatingControlPanel` 组件），但仅有简单的确认对话框和提示，未对接真实API，也未实现状态持久化和UI状态展示。

## 目标

- 对接 `ProcessAPIService.takeover` API 实现真实的人工接管功能
- 实现接管成功后的"印章效果"状态展示，替换原按钮
- 支持状态持久化，页面刷新后保持"已人工接管"状态显示
- 完善错误处理和用户交互体验

## 用户价值

- **调解员**：可以通过点击按钮快速将AI调解案件转为人工处理
- **系统管理员**：能够追踪案件接管状态，避免重复接管
- **用户体验**：清晰的状态展示和友好的错误提示

## 技术方案

### 1. API参数获取

**caseId 获取策略（按优先级）：**
1. URL 参数 `caseId`
2. localStorage `case_data_timeline.case_id`
3. Context `caseData.case_id`

**userName 获取策略：**
- localStorage `currentUser.user_name`，不存在时默认 `"No User"`

### 2. 状态判断逻辑

根据案件 `state` 字段判断按钮显示状态：
- `state === 1`（调解中）：显示"人工接管"按钮
- `state === 2`（调解成功）：隐藏按钮
- `state === 3`（调解失败）：隐藏按钮
- `state === 4`（人工接管）：显示"已人工接管"印章

### 3. 印章效果 UI 设计

**CSS 实现方案：**
```css
.takeover-stamp {
  position: relative;
  display: inline-flex;
  align-items: center;
  justify-content: center;
  padding: 10px 24px;
  font-size: 1rem;
  font-weight: 600;
  color: #e63946;
  background: linear-gradient(135deg, #ffeaea 0%, #ffe0e0 100%);
  border: 3px solid #e63946;
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(230, 57, 70, 0.2);
  transform: rotate(-3deg);
  user-select: none;
  cursor: default;
}

.takeover-stamp::before {
  content: '';
  position: absolute;
  inset: 2px;
  border: 1px solid rgba(230, 57, 70, 0.3);
  border-radius: 6px;
}

.takeover-stamp-text {
  display: flex;
  align-items: center;
  gap: 8px;
  letter-spacing: 2px;
}
```

**HTML 结构：**
```jsx
<div className="takeover-stamp">
  <span className="takeover-stamp-text">
    <i className="fas fa-stamp"></i>
    已人工接管
  </span>
</div>
```

### 4. 交互流程

```mermaid
graph TD
    A[用户点击人工接管按钮] --> B{显示确认对话框}
    B -->|取消| Z[结束]
    B -->|确认| C[显示Loading状态]
    C --> D[调用ProcessAPIService.takeover]
    D --> E{API响应}
    E -->|成功200| F[隐藏按钮]
    F --> G[显示印章效果]
    G --> H[刷新案件数据]
    H --> I[显示成功提示]
    E -->|失败400| J{错误类型判断}
    J -->|已被接管| K[隐藏按钮]
    K --> L[重新加载页面]
    J -->|其他错误| M[显示错误提示]
    M --> N[恢复按钮状态]
```

### 5. 错误处理策略

| 错误场景 | HTTP状态码 | 处理方式 |
|---------|-----------|---------|
| 案件已被接管 | 400 | 隐藏按钮 + 重新加载页面 |
| 调解已成功/失败 | 400 | 隐藏按钮（不提示） |
| 网络错误 | - | 显示错误提示 + 恢复按钮 |
| 其他错误 | 4xx/5xx | 显示错误提示 + 恢复按钮 |

## 影响范围

### 修改文件
- `web-app/src/components/dashboard/FloatingControlPanel.jsx` - 核心逻辑实现
- `web-app/src/App.css` - 新增印章样式

### 依赖组件
- `web-app/src/contexts/CaseDataContext.jsx` - 案件数据Context
- `web-app/src/services/ProcessAPIService.js` - API服务（已存在）
- `web-app/src/utils/stateTranslator.js` - 状态翻译工具

## 风险评估

### 低风险
- ✅ API已经实现（`ProcessAPIService.takeover`）
- ✅ 组件结构清晰，改动范围小
- ✅ 状态字段已在案件数据中存在

### 需要注意
- ⚠️ 确保 localStorage 数据格式一致性
- ⚠️ 页面刷新时的状态同步时序
- ⚠️ 多标签页场景下的状态一致性

## 验收标准

- [ ] 点击"人工接管"按钮显示确认对话框，文案为"确定人工接管本调解案件吗？"
- [ ] 确认后显示 Loading 状态，并调用 API
- [ ] API 调用成功后，按钮替换为印章效果，显示"已人工接管"
- [ ] 接管成功后刷新案件数据
- [ ] 页面刷新后，state=4 的案件显示印章而非按钮
- [ ] state=2/3 的案件隐藏按钮
- [ ] 400 错误（已被接管）时隐藏按钮并重新加载页面
- [ ] 其他错误时显示友好的错误提示
- [ ] 印章效果符合设计规范，有明显的视觉区分

## 待办任务

见 [tasks.md](./tasks.md)

## 相关文档

- API文档: `API文档.md` - `PUT /api/v1/mediation-timeline/v2/case/{caseId}/takeover`
- 组件设计: `web-app/src/components/dashboard/FloatingControlPanel.jsx`
- 状态管理: `web-app/src/contexts/CaseDataContext.jsx`