docs: 新增v1.3.0研发工单文档，清理旧文档引用

2026-06-15 23:24:02 +08:00
parent cf96c56bed
commit 2317c3c456
9 changed files with 345 additions and 1217 deletions
@@ -0,0 +1,107 @@
+# 研发工单 v1.3.0 - 总览
+
+> 术语澄清：本文件中"研发工单"指智能体/开发者执行的**编码工作项**，与业务侧的 Todo 待办项无关。详见 [.trae/rules/全局/05-研发工单规则.md](../../../.trae/rules/全局/05-研发工单规则.md)。
+
+---
+
+## 一、背景与目标
+
+Hua.Todo v1.3.0 版本聚焦于两个核心能力的升级：
+
+| 序号 | 能力 | 描述 |
+|---|---|---|
+| 1 | **MCP 服务映射** | 将现有 HTTP 服务转换为 MCP（Model Context Protocol）服务，提升服务调用效率与可扩展性 |
+| 2 | **语音交互** | 实现语音通话数据传输与语音控制功能，支持通过语音指令操作 Todo 待办项 |
+
+---
+
+## 二、工单拆分
+
+### 2.1 并行工单（可同步执行）
+
+| 工单编号 | 标题 | 负责人 | 状态 |
+|---|---|---|---|
+| 01 | HTTP 服务转换为 MCP 服务 | - | 待开始 |
+| 02 | 语音通话与语音控制功能 | - | 待开始 |
+
+### 2.2 串行工单（依赖前置工单完成）
+
+当前版本暂无串行工单依赖。
+
+---
+
+## 三、各子工单摘要
+
+### 3.1 工单 01 - HTTP 服务转换为 MCP 服务
+
+**目标**：基于 C# 现有映射框架，将 Hua.Todo 的 HTTP API 转换为 MCP 服务
+
+**核心需求**：
+- 将现有的 HTTP API 端点映射为 MCP 工具描述符
+- 生成符合 MCP 规范的契约文档
+- 验证 MCP 服务的可用性与正确性
+
+**验收标准**：
+- MCP 服务可正常对外提供接口
+- 所有原有 HTTP API 功能在 MCP 服务中可正常使用
+
+### 3.2 工单 02 - 语音通话与语音控制功能
+
+**目标**：实现语音通话数据传输与语音控制功能
+
+**核心需求**：
+- 语音通话数据传输能力
+- 语音指令识别与解析
+- 语音控制 Todo 待办项操作（创建、编辑、删除、完成等）
+- 与现有业务系统对接
+
+**验收标准**：
+- 语音通话功能可正常使用
+- 语音控制可准确执行 Todo 业务操作
+
+---
+
+## 四、待验证表
+
+| 子工单 | 验证项 | 状态 | 备注 |
+|---|---|---|---|
+| 01 | MCP 服务契约文档生成 | 待验证 | - |
+| 01 | MCP 服务可用性测试 | 待验证 | - |
+| 01 | 原有 API 功能兼容性 | 待验证 | - |
+| 02 | 语音通话连接测试 | 待验证 | - |
+| 02 | 语音指令识别准确率 | 待验证 | - |
+| 02 | Todo 业务操作覆盖度 | 待验证 | - |
+
+---
+
+## 五、关键决策
+
+| 决策点 | 结论 |
+|---|---|
+| MCP 框架选择 | 使用 TRAE 平台内置的 MCP 服务框架 |
+| 语音识别方案 | 集成平台语音识别能力 |
+| 服务注册方式 | 遵循平台标准注册流程 |
+
+---
+
+## 六、依赖与前置条件
+
+| 依赖项 | 状态 | 来源 |
+|---|---|---|
+| TRAE MCP SDK | 已就绪 | 平台内置 |
+| 语音识别服务 | 已就绪 | 平台内置 |
+| Hua.Todo v1.2.0 | 已完成 | 上一版本 |
+
+---
+
+## 七、风险与回滚
+
+| 风险 | 影响 | 应对策略 |
+|---|---|---|
+| MCP 服务注册失败 | 无法对外提供服务 | 保留 HTTP API 作为降级方案 |
+| 语音识别准确率不足 | 用户体验下降 | 提供文字输入作为备选方案 |
+
+---
+
+**创建日期**：2026-06-15
+**版本**：v1.3.0
@@ -0,0 +1,104 @@
+# 研发工单 v1.3.0 - 01 HTTP 服务转换为 MCP 服务
+
+---
+
+## 一、目标与范围
+
+### 1.1 目标
+基于 C# 现有映射框架，将 Hua.Todo 的 HTTP API 转换为 MCP（Model Context Protocol）服务，提升服务调用效率与可扩展性。
+
+### 1.2 范围
+
+**包含**：
+- 任务管理 API 的 MCP 映射
+- 云同步 API 的 MCP 映射
+- MCP 服务契约文档生成
+- MCP 服务可用性验证
+
+**不包含**：
+- 新增业务功能开发
+- 前端 UI 修改
+
+---
+
+## 二、前置条件
+
+| 条件 | 说明 |
+|---|---|
+| Hua.Todo v1.2.0 | 已完成，提供基础 HTTP API |
+| TRAE MCP SDK | 平台内置，已就绪 |
+| 现有 API 文档 | 参考 [README.md](../../../README.md) |
+
+---
+
+## 三、需求规格
+
+### 3.1 MCP 服务描述符生成
+
+为以下 HTTP API 端点生成 MCP 工具描述符：
+
+#### 任务管理 API
+| HTTP 端点 | MCP 工具名 | 功能描述 |
+|---|---|---|
+| `GET /api/task` | `getTaskList` | 获取任务列表 |
+| `GET /api/task/{id}` | `getTaskById` | 获取单个任务 |
+| `POST /api/task` | `createTask` | 创建任务 |
+| `PUT /api/task` | `updateTask` | 更新任务 |
+| `PATCH /api/task/{id}/toggle` | `toggleTaskStatus` | 切换完成状态 |
+| `DELETE /api/task/{id}` | `deleteTask` | 删除任务 |
+| `GET /api/task/{parentTaskId}/subtasks` | `getSubtasks` | 获取子任务列表 |
+
+#### 云同步 API（Host 模式）
+| HTTP 端点 | MCP 工具名 | 功能描述 |
+|---|---|---|
+| `POST /auth/login` | `cloudLogin` | 用户登录 |
+| `POST /auth/logout` | `cloudLogout` | 用户注销 |
+| `GET /tasks/` | `getCloudTasks` | 获取云端任务 |
+| `POST /sync/` | `syncTasks` | 推送/拉取合并同步 |
+| `GET /security/policy` | `getSecurityPolicy` | 获取安全策略 |
+
+### 3.2 契约文档生成
+
+生成符合 MCP 规范的 JSON 契约文档，包含：
+- 工具名称
+- 参数定义（名称、类型、是否必填）
+- 返回值定义
+- 错误处理说明
+
+### 3.3 服务注册与验证
+
+- 按照平台标准流程注册 MCP 服务
+- 验证所有工具的调用可用性
+
+---
+
+## 四、验收标准
+
+| 验收项 | 验证方法 | 预期结果 |
+|---|---|---|
+| MCP 服务注册 | 检查服务列表 | 服务成功注册 |
+| 工具描述符生成 | 查看 JSON 输出 | 所有工具描述符生成完整 |
+| getTaskList | 调用工具 | 返回任务列表 |
+| createTask | 调用工具 | 创建成功，返回任务 ID |
+| updateTask | 调用工具 | 更新成功 |
+| deleteTask | 调用工具 | 删除成功 |
+| cloudLogin | 调用工具 | 登录成功，返回 Token |
+| syncTasks | 调用工具 | 同步成功 |
+
+---
+
+## 五、Touch List
+
+| 文件路径 | 修改类型 | 说明 |
+|---|---|---|
+| `src/Hua.Todo.Application/Mcp/` | 新增 | MCP 服务实现目录 |
+| `src/Hua.Todo.Application/Mcp/McpServiceCollectionExtensions.cs` | 新增 | MCP 服务注册扩展 |
+| `src/Hua.Todo.Application/Mcp/TaskMcpService.cs` | 新增 | 任务管理 MCP 服务 |
+| `src/Hua.Todo.Application/Mcp/CloudSyncMcpService.cs` | 新增 | 云同步 MCP 服务 |
+| `src/Hua.Todo.Application/Mcp/Models/` | 新增 | MCP DTO 模型 |
+
+---
+
+**工单编号**：01
+**标题**：HTTP 服务转换为 MCP 服务
+**版本**：v1.3.0
@@ -0,0 +1,134 @@
+# 研发工单 v1.3.0 - 02 语音通话与语音控制功能
+
+---
+
+## 一、目标与范围
+
+### 1.1 目标
+实现语音通话数据传输与语音控制功能，支持通过语音指令操作 Todo 待办项，提升用户交互体验。
+
+### 1.2 范围
+
+**包含**：
+- 语音通话数据传输能力
+- 语音指令识别与解析
+- 语音控制 Todo 待办项操作
+- 与现有业务系统对接
+
+**不包含**：
+- 语音通话 UI 界面设计（仅提供能力层）
+- 第三方语音服务集成（使用平台内置能力）
+
+---
+
+## 二、前置条件
+
+| 条件 | 说明 |
+|---|---|
+| Hua.Todo v1.2.0 | 已完成，提供基础业务能力 |
+| 平台语音服务 | 已就绪 |
+| 工单 01（可选） | MCP 服务就绪后可通过 MCP 调用 |
+
+---
+
+## 三、需求规格
+
+### 3.1 语音通话数据传输
+
+**功能描述**：支持语音通话数据的实时传输
+
+**接口设计**：
+```
+工具名：startVoiceCall
+参数：
+  - target: string - 通话目标标识
+返回：
+  - callId: string - 通话 ID
+  - status: string - 通话状态（connected/disconnected）
+```
+
+```
+工具名：endVoiceCall
+参数：
+  - callId: string - 通话 ID
+返回：
+  - success: boolean - 是否成功结束
+```
+
+### 3.2 语音指令控制
+
+**功能描述**：支持通过语音指令操作 Todo 待办项
+
+**支持的语音指令**：
+
+| 指令类型 | 示例指令 | 对应操作 |
+|---|---|---|
+| 创建任务 | "创建任务 开会" | 创建标题为"开会"的任务 |
+| 创建任务（带优先级） | "创建高优先级任务 提交报告" | 创建高优先级任务 |
+| 完成任务 | "完成任务 开会" | 标记任务"开会"为已完成 |
+| 删除任务 | "删除任务 开会" | 删除任务"开会" |
+| 更新任务 | "更新任务 开会 改为 团队会议" | 更新任务标题 |
+| 查询任务 | "查询未完成任务" | 获取未完成任务列表 |
+| 添加子任务 | "给任务开会添加子任务 准备PPT" | 为任务添加子任务 |
+
+**接口设计**：
+```
+工具名：executeVoiceCommand
+参数：
+  - command: string - 语音指令文本
+返回：
+  - success: boolean - 是否执行成功
+  - message: string - 执行结果描述
+  - data: object - 返回数据（如任务列表）
+```
+
+### 3.3 语音状态管理
+
+**接口设计**：
+```
+工具名：getVoiceStatus
+参数：无
+返回：
+  - isListening: boolean - 是否正在监听
+  - isSpeaking: boolean - 是否正在播报
+```
+
+```
+工具名：speakText
+参数：
+  - text: string - 要播报的文本
+返回：
+  - success: boolean - 是否成功
+```
+
+---
+
+## 四、验收标准
+
+| 验收项 | 验证方法 | 预期结果 |
+|---|---|---|
+| 创建任务指令 | 说出"创建任务 测试" | 成功创建标题为"测试"的任务 |
+| 创建带优先级任务 | 说出"创建高优先级任务 紧急" | 成功创建高优先级任务 |
+| 完成任务指令 | 说出"完成任务 测试" | 任务状态变为已完成 |
+| 删除任务指令 | 说出"删除任务 测试" | 任务被成功删除 |
+| 查询任务指令 | 说出"查询未完成任务" | 返回未完成任务列表 |
+| 语音播报 | 调用 speakText | 成功播放指定文本 |
+| 语音通话 | 调用 startVoiceCall | 通话连接成功 |
+
+---
+
+## 五、Touch List
+
+| 文件路径 | 修改类型 | 说明 |
+|---|---|---|
+| `src/Hua.Todo.Application/Voice/` | 新增 | 语音服务目录 |
+| `src/Hua.Todo.Application/Voice/VoiceService.cs` | 新增 | 语音服务实现 |
+| `src/Hua.Todo.Application/Voice/VoiceCommandParser.cs` | 新增 | 语音指令解析器 |
+| `src/Hua.Todo.Application/Voice/Models/` | 新增 | 语音相关 DTO |
+| `src/Hua.Todo.Application/Voice/VoiceServiceCollectionExtensions.cs` | 新增 | 服务注册扩展 |
+
+---
+
+**工单编号**：02
+**标题**：语音通话与语音控制功能
+**版本**：v1.3.0