From 4ada1149e734e8e8ba22b9801b26e49a6921911e Mon Sep 17 00:00:00 2001
From: tony.cheng <chengmingwei_1984122@126.com>
Date: Tue, 17 Mar 2026 10:54:27 +0800
Subject: [PATCH] feat: 实现AI调解状态控制功能（终止/恢复）OpenSpec提案及API完善
---
openspec/changes/implement-mediation-state-control/tasks.md | 48 ++++++++
web-app/src/services/ProcessAPIService.js | 20 +++
openspec/changes/implement-mediation-state-control/specs/mediation-state-control/spec.md | 100 ++++++++++++++++
openspec/changes/implement-mediation-state-control/design.md | 111 ++++++++++++++++++
openspec/changes/implement-mediation-state-control/proposal.md | 55 +++++++++
5 files changed, 334 insertions(+), 0 deletions(-)
diff --git a/openspec/changes/implement-mediation-state-control/design.md b/openspec/changes/implement-mediation-state-control/design.md
new file mode 100644
index 0000000..2e0d4dc
--- /dev/null
+++ b/openspec/changes/implement-mediation-state-control/design.md
@@ -0,0 +1,111 @@
+# Design Document: AI调解状态控制功能
+
+## 架构概述
+本功能将在现有的调解看板界面中添加状态控制能力，允许用户暂停或恢复AI自动调解流程。设计遵循现有系统的组件结构和交互模式。
+
+## 组件设计
+
+### 1. 状态控制按钮组件
+**位置**：位于人工接管按钮右侧
+**显示逻辑**：
+```
+if (caseState === 0 || caseState === 1) {
+ // 显示"终止"按钮，蓝色样式
+ buttonText = "终止";
+ buttonStyle = "primary";
+} else if (caseState === 5) {
+ // 显示"恢复"按钮，绿色样式
+ buttonText = "恢复";
+ buttonStyle = "success";
+} else {
+ // 不显示按钮
+ showButton = false;
+}
+```
+
+### 2. 确认对话框设计
+**触发条件**：用户点击状态控制按钮
+**内容结构**：
+- 标题：根据操作类型显示"确认终止调解"或"确认恢复调解"
+- 描述文本：说明操作的影响
+- 输入框：可选的备注信息
+- 操作按钮：确认/取消
+
+### 3. 状态管理集成
+**数据来源**：从localStorage中的`case_data_timeline`获取案件状态
+**更新机制**：API调用成功后重新加载案件数据
+
+## API集成设计
+
+### 请求流程
+```
+1. 用户点击按钮
+2. 显示确认对话框
+3. 用户确认操作
+4. 调用ProcessAPIService.updateMediationState
+5. 处理API响应
+6. 成功：刷新页面数据
+7. 失败：显示错误提示
+```
+
+### 错误处理策略
+- 网络错误：显示通用网络错误提示
+- 业务错误：显示具体的错误信息
+- 状态冲突：提示当前状态不允许该操作
+
+## UI/UX设计
+
+### 视觉设计
+**终止按钮**：
+- 背景色：#1A6FB8（项目主题蓝色，与人工接管按钮相同）
+- 文字颜色：白色
+- 悬停效果：背景色加深至#0d4a8a
+
+**恢复按钮**：
+- 背景色：#52c41a（Ant Design success green，区别于人工接管的蓝色）
+- 文字颜色：白色
+- 悬停效果：背景色加深
+
+### 交互设计
+**加载状态**：
+- 按钮显示loading状态
+- 禁用其他相关操作
+- 显示操作进度提示
+
+**反馈机制**：
+- 操作成功：显示成功消息，自动刷新数据
+- 操作失败：显示错误消息，保持当前界面状态
+
+## 技术实现考虑
+
+### 性能优化
+- 状态检查在组件渲染时进行，避免不必要的重渲染
+- API调用使用现有的请求拦截器和错误处理机制
+- 页面刷新采用增量更新而非全页面重载
+
+### 安全考虑
+- 操作前进行身份验证检查
+- 记录操作日志用于审计
+- 防止重复提交同一操作
+
+### 可维护性
+- 遵循现有的组件命名和结构规范
+- 复用现有的样式和交互组件
+- 保持与人工接管功能的一致性
+
+## 测试策略
+
+### 单元测试
+- 按钮显示逻辑的边界条件测试
+- API调用成功/失败场景测试
+- 状态转换的正确性验证
+
+### 集成测试
+- 完整的用户操作流程测试
+- 与现有功能的兼容性测试
+- 异常场景的恢复能力测试
+
+### 用户验收测试
+- 实际调解场景下的功能验证
+- 易用性和直观性评估
+- 性能影响评估
\ No newline at end of file
diff --git a/openspec/changes/implement-mediation-state-control/proposal.md b/openspec/changes/implement-mediation-state-control/proposal.md
new file mode 100644
index 0000000..f0fbbe4
--- /dev/null
+++ b/openspec/changes/implement-mediation-state-control/proposal.md
@@ -0,0 +1,55 @@
+# Proposal: 实现AI调解状态控制功能（终止/恢复）
+
+## Change ID
+`implement-mediation-state-control`
+
+## Summary
+在调解看板页面增加"终止"或"恢复"功能按钮，允许用户对正在进行的AI自动调解进行暂停和恢复操作。按钮位于人工接管按钮右侧，根据案件当前状态动态显示不同的文本和样式。
+
+## Motivation
+当前系统缺乏对AI自动调解过程的灵活控制机制。当调解遇到特殊情况（如需要人工干预、当事人临时沟通等）时，调解员需要能够暂停AI调解流程，并在适当时机恢复调解。此功能将提升系统的实用性和用户体验。
+
+## Requirements Overview
+- 在调解看板页面添加状态控制按钮
+- 根据案件状态动态显示按钮文本和样式
+- 实现确认对话框机制
+- 调用后端API进行状态变更
+- 状态变更后自动刷新页面数据
+
+## Stakeholders
+- 调解员：主要使用者，需要灵活控制调解流程
+- 系统管理员：关注功能稳定性和安全性
+- 产品负责人：确保功能符合业务需求
+
+## Success Criteria
+- 按钮正确显示在人工接管按钮右侧
+- 状态为0或1时显示"终止"按钮（蓝色样式）
+- 状态为5时显示"恢复"按钮（绿色样式）
+- 其他状态下不显示该按钮
+- 点击按钮后正确显示确认对话框
+- API调用成功后页面数据正确刷新
+- API调用失败时显示相应错误提示
+
+## Risks & Mitigations
+- **风险**：频繁的状态变更可能影响调解流程的一致性
+ - **缓解**：添加操作日志记录，便于追踪状态变更历史
+- **风险**：并发操作可能导致状态不一致
+ - **缓解**：在后端实现状态变更的原子性控制
+
+## Dependencies
+- 已存在的`ProcessAPIService.updateMediationState` API
+- 案件状态管理机制
+- 现有的人工接管功能实现
+
+## Timeline
+预计开发时间：2-3个工作日
+- 设计和评审：0.5天
+- 前端实现：1.5天
+- 测试和验证：1天
+
+## Alternatives Considered
+1. **在独立页面管理调解状态**：增加了用户操作复杂度，不符合当前一体化界面设计理念
+2. **通过右键菜单实现**：隐藏了重要功能，不利于用户发现和使用
+3. **自动状态检测和恢复**：缺乏人工控制灵活性，可能在不适当的时候触发状态变更
+
+选择在现有界面中直接添加按钮的方式，既保持了界面的一致性，又提供了直观的操作方式。
\ No newline at end of file
diff --git a/openspec/changes/implement-mediation-state-control/specs/mediation-state-control/spec.md b/openspec/changes/implement-mediation-state-control/specs/mediation-state-control/spec.md
new file mode 100644
index 0000000..601ac74
--- /dev/null
+++ b/openspec/changes/implement-mediation-state-control/specs/mediation-state-control/spec.md
@@ -0,0 +1,100 @@
+# Mediation State Control Specification
+
+## ADDED Requirements
+
+### Requirement: 状态控制按钮显示逻辑
+系统 SHALL 根据案件当前状态动态显示状态控制按钮。
+
+#### Scenario: 案件处于初始或进行中状态
+Given 案件状态为0（初始）或1（进行中）
+When 页面加载时
+Then 应显示"终止"按钮，样式为主题蓝色
+
+#### Scenario: 案件处于暂停状态
+Given 案件状态为5（暂停）
+When 页面加载时
+Then 应显示"恢复"按钮，样式为主题绿色
+
+#### Scenario: 案件处于其他状态
+Given 案件状态为2（成功）、3（失败）、4（终止）或其他状态
+When 页面加载时
+Then 不应显示状态控制按钮
+
+### Requirement: 确认对话框机制
+用户点击状态控制按钮时 SHALL 显示确认对话框。
+
+#### Scenario: 用户点击终止按钮
+Given 用户看到"终止"按钮
+When 用户点击该按钮
+Then 应显示确认对话框，标题为"确认终止调解"
+And 对话框应包含操作说明文本
+And 应提供确认和取消按钮
+
+#### Scenario: 用户点击恢复按钮
+Given 用户看到"恢复"按钮
+When 用户点击该按钮
+Then 应显示确认对话框，标题为"确认恢复调解"
+And 对话框应包含操作说明文本
+And 应提供确认和取消按钮
+
+### Requirement: API调用和状态更新
+确认操作后 SHALL 调用API并更新页面状态。
+
+#### Scenario: 成功终止调解
+Given 用户确认终止操作
+When 系统调用ProcessAPIService.updateMediationState({action: 0})
+And API返回成功响应
+Then 应显示成功消息"案件状态更新成功"
+And 应重新加载当前页面数据
+And 按钮状态应相应更新
+
+#### Scenario: 成功恢复调解
+Given 用户确认恢复操作
+When 系统调用ProcessAPIService.updateMediationState({action: 1})
+And API返回成功响应
+Then 应显示成功消息"案件状态更新成功"
+And 应重新加载当前页面数据
+And 按钮状态应相应更新
+
+#### Scenario: API调用失败
+Given 用户确认操作
+When 系统调用API失败
+Then 应显示相应的错误消息
+And 页面状态应保持不变
+And 按钮应恢复到可点击状态
+
+### Requirement: 加载状态管理
+操作过程中 SHALL 提供适当的加载状态反馈。
+
+#### Scenario: API调用期间
+Given 用户已确认操作
+When 系统正在调用API
+Then 状态控制按钮应显示loading状态
+And 应禁用相关操作按钮
+And 应显示操作进度提示
+
+#### Scenario: 页面刷新期间
+Given API调用成功
+When 系统正在刷新页面数据
+Then 应显示数据加载指示器
+And 应暂时禁用用户交互
+
+## MODIFIED Requirements
+
+### Requirement: 现有按钮布局调整
+人工接管按钮的布局 SHALL 为新按钮预留空间。
+
+#### Scenario: 按钮容器布局
+Given 页面包含人工接管按钮
+When 添加状态控制按钮后
+Then 两个按钮应水平排列
+And 状态控制按钮应位于人工接管按钮右侧
+And 按钮间应有适当的间距
+
+## REMOVED Requirements
+无
+
+## Related Capabilities
+- 人工接管功能 (implement-manual-takeover)
+- 案件状态管理 (case-state-management)
+- API集成规范 (api-integration-spec)
\ No newline at end of file
diff --git a/openspec/changes/implement-mediation-state-control/tasks.md b/openspec/changes/implement-mediation-state-control/tasks.md
new file mode 100644
index 0000000..d22dbc3
--- /dev/null
+++ b/openspec/changes/implement-mediation-state-control/tasks.md
@@ -0,0 +1,48 @@
+# Tasks for implement-mediation-state-control
+
+## Task List
+
+### Phase 1: 设计和准备工作
+- [ ] 创建功能规格说明文档
+- [ ] 确认UI设计细节（按钮样式、位置、交互效果）
+- [ ] 评审技术实现方案
+
+### Phase 2: 前端实现
+- [ ] 在TabContainer组件中添加状态控制按钮
+- [ ] 实现按钮显示逻辑（根据案件状态动态显示）
+- [ ] 添加确认对话框组件
+- [ ] 实现API调用逻辑
+- [ ] 添加页面刷新机制
+- [ ] 实现错误处理和提示
+
+### Phase 3: 样式和交互优化
+- [ ] 调整按钮样式（终止按钮蓝色，恢复按钮绿色）
+- [ ] 优化确认对话框的用户体验
+- [ ] 添加加载状态指示
+- [ ] 确保响应式设计兼容性
+
+### Phase 4: 测试和验证
+- [ ] 单元测试按钮显示逻辑
+- [ ] 集成测试API调用流程
+- [ ] 用户验收测试
+- [ ] 性能测试（确保不会影响页面加载速度）
+- [ ] 跨浏览器兼容性测试
+
+### Phase 5: 文档和部署
+- [ ] 更新用户手册
+- [ ] 编写开发文档
+- [ ] 部署到测试环境
+- [ ] 生产环境部署
+
+## Dependencies
+- Task 2 依赖 Task 1 的完成
+- Task 3 依赖 Task 2 的完成
+- Task 4 依赖 Task 3 的完成
+- Tasks 5-6 可以并行进行
+
+## Validation Criteria
+每个任务完成后需要满足：
+- 代码通过ESLint检查
+- 功能在本地开发环境中正常工作
+- 不引入新的编译警告或错误
+- 符合现有的代码风格和架构模式
\ No newline at end of file
diff --git a/web-app/src/services/ProcessAPIService.js b/web-app/src/services/ProcessAPIService.js
index 7b1b67e..bad9165 100644
--- a/web-app/src/services/ProcessAPIService.js
+++ b/web-app/src/services/ProcessAPIService.js
@@ -143,6 +143,26 @@
return request.put(`/api/v1/mediation-timeline/v2/case/${caseId}/takeover`, data);
}
+ /**
+ * AI调解状态控制API（终止/恢复）
+ * PUT /api/v1/mediation-timeline/v2/case/{caseId}/state
+ * @param {string} caseId - 案件ID
+ * @param {Object} data - 请求数据
+ * @param {number} data.action - 操作类型：0-终止，1-恢复
+ * @param {string} data.userName - 操作人姓名（可选）
+ * @returns {Promise} 状态更新结果
+ *
+ * @example
+ * // 终止调解
+ * ProcessAPIService.updateMediationState('1001', { action: 0, userName: '张三' });
+ *
+ * // 恢复调解
+ * ProcessAPIService.updateMediationState('1001', { action: 1, userName: '李四' });
+ */
+ static updateMediationState(caseId, data) {
+ return request.put(`/api/v1/mediation-timeline/v2/case/${caseId}/state`, data);
+ }
+
}
export default ProcessAPIService;
\ No newline at end of file
--
Gitblit v1.8.0