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,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