Hua/Hua.Todo
1
0
Fork 0
Code Issues Wiki Activity

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

Browse Source
This commit is contained in:
ShaoHua
2026-06-15 23:24:02 +08:00
parent cf96c56bed
commit 2317c3c456
9 changed files with 345 additions and 1217 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/project/Android_NotFound_排查计划.md
-92
View File
@@ -1,92 +0,0 @@
# Android 端显示 “Not Found” 排查计划（Hua.Todo.Maui）
## 目标
- 找出 Android 模拟器里只显示 `Not Found` 的根因（是 Web 资源缺失、内嵌 Web Server 路由/解析问题，还是 WebView 加载了错误地址）
- 给出可验证的修复方案，并确保修复后能在 Android 上正常加载前端页面
## 背景（当前实现快速定位）
- Android 使用自建 TCP HTTP Server，静态资源从 APK 的 `Assets/wwwroot/*` 读取：[MobileEmbeddedWebServerService](file:///d:/Proj/Hua.Todo/src/Hua.Todo.Maui/Platforms/Android/MobileEmbeddedWebServerService.cs)
- WebView 默认加载内嵌服务器地址（`IsUsingStatic=true` 时）：[MainPage.xaml.cs](file:///d:/Proj/Hua.Todo/src/Hua.Todo.Maui/Views/MainPage.xaml.cs)
- Android 端静态文件找不到时返回纯文本 `Not Found`：[HandleStaticAsync](file:///d:/Proj/Hua.Todo/src/Hua.Todo.Maui/Platforms/Android/MobileEmbeddedWebServerService.cs#L214-L255)
## 排查顺序（从“最可能 & 最省时间”到“深入原因”）
### 1) 确认 WebView 实际加载的 URL
- 在 Android Debug 输出里确认 WebView Source（期望是 `http://localhost:5057` 或 `http://localhost:5057/`）
- 如果不是内嵌地址，检查 `appsettings.json` 的 `WebServer.IsUsingStatic` 与 `ForEndUrl` 配置：[appsettings.json](file:///d:/Proj/Hua.Todo/src/Hua.Todo.Maui/appsettings.json)
判定：
- 若加载的是内嵌地址 → 继续第 2 步
- 若加载的是外部地址（ForEndUrl）→ 重点查 ForEndUrl 对应服务是否启动/路由是否正确
### 2) 确认前端 dist 是否存在且可用于打包
- 检查 `src/Hua.Todo.Web/dist/index.html` 是否存在
- 如果不存在：在 `src/Hua.Todo.Web` 下执行 `npm ci` + `npm run build`，确保产物生成
判定：
- dist 不存在/为空 → “Not Found”高概率来自 Android 静态资源根本没被构建或没被打进 APK
### 3) 确认 Android APK 内是否真的包含 `Assets/wwwroot/index.html`
- 重点验证打包结果是否存在：
- `assets/wwwroot/index.html`
- `assets/wwwroot/assets/*`（至少有 js/css）
- 项目里通过 MSBuild 目标把 `Hua.Todo.Web/dist` 映射为 AndroidAsset（Link 到 `wwwroot/...`）：[Hua.Todo.Maui.csproj](file:///d:/Proj/Hua.Todo/src/Hua.Todo.Maui/Hua.Todo.Maui.csproj#L150-L175)
判定：
- APK 内没有 `wwwroot/index.html` → 修复构建/打包流程（第 6 步会给方案）
- APK 内有 `wwwroot/index.html` → 继续第 4 步
### 4) 记录 Android 内嵌服务器的“收到的请求 Path”与“找不到的 assetPath”
目的：判断是否是“请求行解析不兼容”或“路径格式异常”导致找不到资源。
- 在 `ReadRequestAsync`、`HandleStaticAsync` 临时输出：
- requestLine / target / path
- 计算出的 assetPath
- TryOpenAsset 失败的 assetPath
高频根因候选：
- WebView 请求行使用 absolute-form（例如 `GET http://localhost:5057/ HTTP/1.1`），当前解析逻辑会把整个 URL 当作 path，最终拼成无效 `wwwroothttp://...`，导致 404
### 5) 排除 WebView/网络限制类问题（只在必要时做）
- 如果看到的不是纯文本 `Not Found`，而是加载错误/空白：
- 检查 Android 明文 HTTP（`http://localhost`）是否被允许
- 检查 `network_security_config.xml` 与 Manifest 配置：[network_security_config.xml](file:///d:/Proj/Hua.Todo/src/Hua.Todo.Maui/Platforms/Android/Resources/xml/network_security_config.xml)、[AndroidManifest.xml](file:///d:/Proj/Hua.Todo/src/Hua.Todo.Maui/Platforms/Android/AndroidManifest.xml)
### 6) 修复与验证（根据前面判定选择）
#### A. 资源缺失/未打包
- 让构建流程更“硬性”：
- 若 dist 不存在则强制构建，或在 Debug 也保证 `AndroidAsset` 包含 dist
- 可选：把 dist 复制进 `Hua.Todo.Maui/wwwroot` 再用 `<Content Include="wwwroot\**" />`/`<MauiAsset />` 统一打包（减少条件目标的不确定性）
验证：
- APK 内能看到 `assets/wwwroot/index.html`，启动后不再返回 `Not Found`
#### B. 请求路径解析不兼容（absolute-form 等）
- 改进 `ReadRequestAsync`：当 target 是 `http(s)://...` 时解析出其中的 Path + Query，再走现有逻辑
验证：
- 记录到的 path 变为 `/` 或 `/index.html`，能成功打开 `wwwroot/index.html`
#### C. 资源引用路径问题（js/css 请求 404）
- 检查 dist 中 `index.html` 对 `assets/*` 的引用路径是否与 AndroidAsset 的 Link 一致
- 若 Vite 输出含子目录（例如 `assets/chunks/...`），需要在 csproj 里用 `dist\**\*` 并保留 `%(RecursiveDir)`，避免扁平化导致引用断裂
验证：
- WebView 网络请求里 js/css 全部 200，页面正常渲染
## 本次排查的“最短闭环”
- 先确认 dist 是否存在 + APK 是否包含 `assets/wwwroot/index.html`
- 若存在仍 Not Found，再用日志确认 requestLine/target/path 是否被解析成异常值（absolute-form 是最高优先级怀疑点）
docs/project/研发工单-v1.3.0/00-工单总览.md
+107
View File
@@ -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
docs/project/研发工单-v1.3.0/01-HTTP服务转换MCP服务.md
+104
View File
@@ -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
docs/project/研发工单-v1.3.0/02-语音通话与语音控制.md
+134
View File
@@ -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