ShaoHua
3213d4c718
- 重构架构：抽离AddCloudSyncServer到扩展类，补全中间层文档对齐 - 修复根路径404与鉴权跳转：新增中间件处理浏览器请求302跳转 - 实现种子数据初始化：添加默认管理员账号自动创建逻辑 - 优化前端代理与构建：新增Vite代理配置与自动构建Target - 补全测试与文档：新增集成测试，更新开发与部署文档
275 lines
17 KiB
Markdown
275 lines
17 KiB
Markdown
# 研发工单 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 | **语音控制与 AI 辅助** | 通过语音指令操作 Todo 待办项（CRUD + 子任务），通过 LLM 提供 AI 辅助任务拆分建议 |
|
||
| 3 | **会议任务拆分** | 以"会议"为入口记录会议内容（录音/文字），通过 AI 分析自动生成待办项拆分建议，用户确认后批量创建 |
|
||
|
||
---
|
||
|
||
## 二、工单拆分
|
||
|
||
### 2.1 并行工单（可同步执行）
|
||
|
||
| 工单编号 | 标题 | 负责人 | 状态 |
|
||
|---|---|---|---|---|---|---|
|
||
| 01 | HTTP 服务转换为 MCP 服务 | - | 已完成 |
|
||
| 02 | 语音控制与 AI 辅助 | - | 已完成 |
|
||
| 03 | 会议任务拆分 | - | 待开始 |
|
||
| 04 | 富文本描述、附件与外部链接 | - | 已完成 |
|
||
|
||
### 2.2 03 子工单拆分
|
||
|
||
| 子工单 | 标题 | 依赖 | 状态 |
|
||
|---|---|---|---|
|
||
| 03-01 | 会议数据模型与 API | 无 | 待开始 |
|
||
| 03-02 | 音频录制与转写 | 03-01 | 待开始 |
|
||
| 03-03 | AI 任务拆分服务 | 03-01、工单 02 LlmClientService | 待开始 |
|
||
| 03-04 | 任务建议与确认 UI | 03-01、03-03 | 已完成 |
|
||
|
||
### 2.3 串行工单（依赖前置工单完成）
|
||
|
||
当前版本暂无串行工单依赖。
|
||
|
||
### 2.4 补充工单（架构对齐，2026-08-08 新增）
|
||
|
||
> 按 [04-研发工单全流程规范.md](../../../.trae/rules/全局/04-研发工单全流程规范.md) §2.3「新增工单约束」：已有条目不可改写，本章节为本次**新增**。触发原因：本次 307 修复后重写 [01-项目架构.md](../../../.trae/rules/项目/01-项目架构.md) §3/§5，对照代码发现 2 处架构缺口（文档遗漏 HttpApi.AspNetCore 层、Web 端根路径无前端托管）。
|
||
|
||
| 工单编号 | 标题 | 负责人 | 状态 | 并行性 |
|
||
|---|---|---|---|---|
|
||
| 05 | 架构文档与代码实际路径对齐 | - | 待开始 | 与 03/06 并行 |
|
||
| 06 | Web 端根路径托管前端 | - | 待开始 | 与 03/05 并行（建议 05 缺口 D 先落，再推 06 Program.cs 集成） |
|
||
| 07 - 数据库初始化默认管理员 | 待实现 | 待验证 | Host 服务端 DB Migrate 后自动创建默认管理员账号；仅 Host 模式；配置驱动 + 幂等 + 强制首登改密；作为 06.1 Bootstrap 的自动前置项。详见 [10-数据库初始化默认管理员.md](10-数据库初始化默认管理员.md) |
|
||
|
||
---
|
||
|
||
## 三、各子工单摘要
|
||
|
||
### 3.1 工单 01 - HTTP 服务转换为 MCP 服务
|
||
|
||
**目标**：基于 C# 现有映射框架，将 Hua.Todo 的 HTTP API 转换为 MCP 服务
|
||
|
||
**核心需求**：
|
||
- 将现有的 HTTP API 端点映射为 MCP 工具描述符
|
||
- 生成符合 MCP 规范的契约文档
|
||
- 验证 MCP 服务的可用性与正确性
|
||
|
||
**验收标准**：
|
||
- MCP 服务可正常对外提供接口
|
||
- 所有原有 HTTP API 功能在 MCP 服务中可正常使用
|
||
|
||
### 3.2 工单 02 - 语音控制与 AI 辅助
|
||
|
||
**目标**：实现语音控制 Todo 待办项能力与 AI 辅助任务拆分功能
|
||
|
||
**核心需求**：
|
||
- 语音输入（STT）：平台原生语音识别 → 文字
|
||
- 语音播报（TTS）：执行结果语音反馈
|
||
- 语音指令解析与执行（CRUD + 子任务 + 歧义处理）
|
||
- AI 辅助任务拆分（LLM 生成子任务建议，用户确认后批量创建）
|
||
|
||
**不包含**：
|
||
- 语音通话功能（场景不明确，本期不做）
|
||
|
||
**验收标准**：
|
||
- 各平台 STT/TTS 可正常工作
|
||
- 语音指令可准确执行 Todo 业务操作
|
||
- 歧义场景返回候选列表而非直接执行
|
||
- AI 拆分建议需用户确认后才创建子任务
|
||
|
||
### 3.3 工单 03 - 会议任务拆分
|
||
|
||
**目标**：以"会议"为入口，通过录音/文字记录会议内容，AI 自动提取行动项生成待办项建议
|
||
|
||
**核心需求**：
|
||
- 新增"会议"类型标记（TaskType.Meeting）
|
||
- 录音：前端 MediaRecorder → 后端 STT 转写
|
||
- 文字：直接输入/粘贴会议纪要
|
||
- AI 会议拆分（LLM 分析会议内容 → 待办项建议列表）
|
||
- 建议审阅与确认 UI（勾选、编辑、批量创建子任务）
|
||
|
||
**不包含**：
|
||
- 实时语音转写（本期不做）
|
||
- 音频持久存储（转写完成后删除音频）
|
||
|
||
**验收标准**：
|
||
- 可通过"会议"类型创建待办项，显示会议图标
|
||
- 录音可正常录制并提交转写
|
||
- 文字纪要可保存/编辑
|
||
- AI 拆分返回 3-10 条结构化建议，含优先级和原因
|
||
- 用户可审阅、勾选、编辑建议后批量创建为子任务
|
||
- 离线模式拒绝 AI 拆分（提示降级）
|
||
|
||
### 3.4 工单 04 - 富文本描述、附件与外部链接
|
||
|
||
**目标**：为 Todo 待办项新增多行描述、文件附件管理与外部程序/链接启动能力（仅桌面端）
|
||
|
||
**核心需求**：
|
||
- `TaskEntity` 新增 `Description` 多行描述字段
|
||
- 新增 `AttachmentEntity` 数据模型，支持本地文件上传、下载、删除
|
||
- 支持外部链接（URL）作为附件，点击在默认浏览器打开
|
||
- 桌面端通过系统关联程序打开本地附件（`Process.Start` / `xdg-open`）
|
||
- 前端编辑对话框扩展描述 textarea + 附件管理区域
|
||
|
||
**不包含**：
|
||
- 移动端附件管理（本期仅 Windows/Linux 桌面端）
|
||
- 附件云同步（后续版本规划）
|
||
- 附件预览（如图片缩略图，本期不做）
|
||
- 富文本编辑器（本期仅纯文本）
|
||
|
||
**验收标准**：
|
||
- 描述字段可正常编辑和保存
|
||
- 附件可上传、下载、删除，文件完整性校验
|
||
- 外部链接可添加并在浏览器中打开
|
||
- 本地附件可通过系统关联程序打开
|
||
- 附件数量（20个）和大小（50MB）限制生效
|
||
|
||
### 3.5 工单 05 - 架构文档与代码实际路径对齐
|
||
|
||
**目标**：修正 01-项目架构.md §1/§2/§5 共 5 处与实际代码结构不一致的描述，使规则文档成为代码的单一事实来源。
|
||
|
||
**核心需求**：
|
||
- **文档侧**：§1 项目清单补 `Hua.Todo.HttpApi.AspNetCore` 条目；§2 ASCII 依赖图加该中间层；§5 路径修正 Mcp 描述
|
||
- **代码侧**：`CloudSyncServerService.cs` 抽离 `AddCloudSyncServer()` 到新文件 `CloudSyncServiceCollectionExtensions.cs`；新建 `CloudSyncEndpointExtensions.cs` 还原 `MapCloudSyncProxySettings()`
|
||
- **回归**：Host 编译 + 161 个既有测试全部通过
|
||
|
||
**不包含**：业务逻辑变更、公共 API 签名修改、v1.2.0 工单 10（DataSeeder）
|
||
|
||
**验收标准**：详细 5 条 Given-When-Then 见 [05-架构文档与代码实际路径对齐.md](./05-架构文档与代码实际路径对齐.md) §五。
|
||
|
||
### 3.6 工单 06 - Web 端根路径托管前端
|
||
|
||
**目标**：补齐模式 B（Hua.Todo.Host Web 端）的前端静态页托管链路，使 `dotnet publish Hua.Todo.Host` 产出一个「页面 + API + Admin 占位」完整可部署的服务。
|
||
|
||
**核心需求**：
|
||
- Host `Program.cs`：`UseDefaultFiles` + `UseStaticFiles` + `MapFallbackToFile("index.html")`（支持 SPA 路由）
|
||
- Host `csproj`：新增 `BuildHuaTodoWebWebRoot` Target（`npm install`/`npm run build`/`copy dist → wwwroot`，Inputs/Outputs 支持增量构建）
|
||
- 文档：`docs/manual/08-构建与开发指南.md` 追加模式 B 开发双开步骤 + 生产发布步骤
|
||
- 测试：`WebRootStaticFileTests.cs` 验证根路径 `/` 与 SPA fallback 不覆盖 `/api/*`
|
||
|
||
**不包含**：Admin 管理后台前端实现（v1.2.0 工单 06.1）、嵌入式模式前端托管（`EmbeddedWebServerService` 各自管理）
|
||
|
||
**验收标准**：详细 6 条 Given-When-Then 见 [06-Web端根路径托管前端.md](./06-Web端根路径托管前端.md) §四。
|
||
|
||
---
|
||
|
||
## 四、待验证表
|
||
|
||
| 子工单 | 验证项 | 状态 | 备注 |
|
||
|---|---|---|---|
|
||
| 01 | MCP 服务契约文档生成 | 已验证 | 动态工具自动生成，工具名/描述/参数 schema 均已覆盖 |
|
||
| 01 | MCP 服务可用性测试 | 已验证 | 17 个单元测试全部通过（含工具调用端到端验证） |
|
||
| 01 | 原有 API 功能兼容性 | 已验证 | 所有 ITaskService 方法均生成 MCP 工具，覆盖 CRUD 全部 9 个 API |
|
||
| 01 | CloudSync MCP 工具 | 已知缺口 | CloudSync 服务未实现 IDynamicApiService，需手动映射或重构 |
|
||
| 02 | STT/TTS 平台适配 | 待验证 | Windows 优先，其他平台后续 |
|
||
| 02 | 语音指令识别准确率 | 待验证 | - |
|
||
| 02 | 歧义处理正确性 | 待验证 | - |
|
||
| 02 | AI 拆分建议质量 | 待验证 | - |
|
||
| 02 | Todo 业务操作覆盖度 | 待验证 | CRUD + 子任务 + 取消完成 |
|
||
| 03 | 会议数据模型迁移 | 待验证 | TaskType 字段 + DB 迁移 |
|
||
| 03 | 录音与转写链路 | 待验证 | 录制 → 上传 → 转写 → 保存 |
|
||
| 03 | AI 会议拆分质量 | 待验证 | 建议含标题+优先级+原因 |
|
||
| 03 | 建议审阅与批量创建 | 待验证 | MeetingBreakdownDialog 已实现：勾选/编辑/确认后创建子任务 |
|
||
| 04 | 描述字段编辑与保存 | 待验证 | - |
|
||
| 04 | 附件上传/下载/删除 | 待验证 | - |
|
||
| 04 | 外部链接添加与打开 | 待验证 | - |
|
||
| 04 | 本地文件通过系统程序打开 | 待验证 | Process.Start / xdg-open |
|
||
| 04 | 附件数量/大小限制 | 待验证 | 20 个 / 50MB |
|
||
| 04 | 待办项删除时附件级联清理 | 待验证 | - |
|
||
| 04 | 跨平台编辑安全（移动端不覆盖描述/附件） | 待验证 | 桌面设值 → 移动端改标题 → 桌面验证不丢失 |
|
||
| 05 | 规则文档 §1/§2 补 HttpApi.AspNetCore 条目与依赖图 | 待验证 | Glob 到项目 + 规则描述一致 |
|
||
| 05 | §5 扩展点 AddCloudSyncServer / MapCloudSyncProxySettings / Mcp 3 个路径修复 | 待验证 | 规则路径 = Grep 实际路径；Host 编译 0 错误 |
|
||
| 05 | 既有 AddCloudSyncServer 回归测试 | 待验证 | `CloudSyncEndpointRegistrationTests` 5 个用例全部通过 |
|
||
| 06 | Host `/` 返回 Hua.Todo.Web index.html（200 + div#app） | 待验证 | `WebRootStaticFileTests.Root_Get_ReturnsIndexHtml` 通过 |
|
||
| 06 | SPA 路由 `/settings` fallback 到 index.html | 待验证 | 不 404；不覆盖 `/api/*` 动态 API |
|
||
| 06 | `dotnet publish Hua.Todo.Host` 产出包含前端静态资源 | 待验证 | publish/wwwroot/index.html 存在 + 资源齐全 |
|
||
| 06 | 增量构建前端未变时跳过 npm build | 待验证 | MSBuild Inputs/Outputs 检测 Skipping target 提示 |
|
||
| 06 | 模式 B 开发双开文档可执行性 | 待验证 | 从零 clone → 文档 step by step 跑通页面 + API |
|
||
|
||
---
|
||
|
||
## 五、关键决策
|
||
|
||
| 决策点 | 结论 |
|
||
|---|---|
|
||
| MCP 框架选择 | 使用 TRAE 平台内置的 MCP 服务框架 |
|
||
| STT/TTS 分层 | 接口在 Core，实现在各平台目录（同全局快捷键模式） |
|
||
| 语音指令解析 | A+C 混合方案：在线走 LLM 意图解析（LlmIntentParser），离线降级到规则匹配（RuleIntentParser），双策略通过 HybridVoiceIntentParser 自动切换 |
|
||
| 歧义处理策略 | 目标不唯一时返回候选列表；LLM confidence < 0.8 时触发确认；confidence < 0.5 按 UNKNOWN 处理 |
|
||
| AI 拆分安全性 | LLM 调用在 Host 端，建议需用户确认后才创建 |
|
||
| LLM 复用 | 意图解析与 AI 拆分共用同一 LLM 基础设施（LlmClientService） |
|
||
| 语音通话 | 本期不做，场景不明确 |
|
||
| 会议类型 | 新增 `TaskType` 枚举区分普通待办项与会议，会议有专属录音/纪要/拆分 UI |
|
||
| 录音存储 | 转写完成后删除原始音频文件，节省空间 |
|
||
| 音频转写 | 优先服务端 Whisper API；后续补各平台原生 STT |
|
||
| LLM 拆分 prompt | 会议专用 prompt，侧重"提取行动项"，输出优先级+原因 |
|
||
| 工单 02 复用 | `LlmClientService` 直接复用；会议拆分 prompt 独立于语音意图解析 |
|
||
| 多入口覆盖规则 | 后续每项新增功能必须在需求阶段确认 UI 入口 + 语音控制入口覆盖情况，详见 [05-多入口功能同步规范.md](../../../.trae/rules/项目/05-多入口功能同步规范.md) |
|
||
| 附件存储策略 | 附件存储在应用数据目录 `Attachments/` 子目录；外部链接不复制文件仅存 URL；单文件 50MB / 每待办项 20 个上限 |
|
||
| 外部程序启动 | 通过 `IPlatformAttachmentOpener` 接口实现平台差异：Windows 用 `Process.Start`，Linux 用 `xdg-open` |
|
||
| 工单 04 与 03 共享文件 | `TaskEntity.cs`、`TodoDbContext.cs`、`task.ts`、`TaskEditDialog.vue` 为共享文件，工单 03 先写入，04 后续追加 |
|
||
| **架构文档 ↔ 代码一致性强制策略** | 后续凡改 01-项目架构.md 任何一节，改后必须立即对 §1/§2/§5 所有提到的文件路径做一次 Glob/Grep 校验；不一致 → 先开对齐工单，不直接碰业务代码（本次 05 工单即为策略首次落地案例） |
|
||
| **Host 中间件顺序固定模板** | Swagger → UseDefaultFiles/UseStaticFiles → CORS → Authentication → Authorization → UseDynamicApi → MapMcpServer → MapFallbackToFile → Run（顺序错误直接判作编译/验收失败） |
|
||
| **MSBuild 前端构建 Target 命名与增量** | Host 前端构建 Target 固定名 `BuildHuaTodoWebWebRoot`；必须显式写 `Inputs="$(HuaTodoWebSrc);$(HuaTodoWebPkgJson)" Outputs="$(WebRoot)/index.html"` 支持增量；Node/npm 不存在时只 Warning 不阻塞 API 层 build |
|
||
|
||
---
|
||
|
||
## 六、依赖与前置条件
|
||
|
||
| 依赖项 | 状态 | 来源 |
|
||
|---|---|---|
|
||
| TRAE MCP SDK | 已就绪 | 平台内置 |
|
||
| 各平台原生 STT/TTS API | 已就绪 | 平台内置 |
|
||
| Hua.Todo v1.2.0 | 已完成 | 上一版本 |
|
||
| LLM API（AI 拆分） | 待确认 | Host 端调用 |
|
||
| 浏览器 MediaRecorder API | 已就绪 | 前端录音 |
|
||
| 工单 02 LlmClientService | 待实现 | 会议拆分复用 |
|
||
| 工单 05 前置（缺口 D） | 待完成 | 建议先还原 `CloudSyncEndpointExtensions.cs`（MapCloudSyncProxySettings），再推 06 Program.cs 集成 |
|
||
| Node.js + npm（构建机器） | 外部依赖 | 构建 Hua.Todo.Web 必备；缺失时 Host csproj Target 仅 Warning |
|
||
| 01-项目架构.md §3 模式 B 端点划分表 | 已固化 | 本批次工单 05/06 的对齐基准 |
|
||
|
||
---
|
||
|
||
## 七、风险与回滚
|
||
|
||
| 风险 | 影响 | 应对策略 |
|
||
|---|---|---|
|
||
| MCP 服务注册失败 | 无法对外提供服务 | 保留 HTTP API 作为降级方案 |
|
||
| 平台 STT 识别准确率不足 | 用户体验下降 | 提供文字输入作为备选方案 |
|
||
| Linux STT 可用性差 | Linux 语音控制不可用 | Web Speech API 降级；或 `vosk` 离线模型 |
|
||
| LLM API 不稳定 | AI 拆分功能不可用 | 功能降级，语音指令其他部分不受影响 |
|
||
| 会议录音文件过大 | 上传超时/存储压力 | 前端限制最长 2 小时；压缩音频格式 |
|
||
| 浏览器 MediaRecorder 兼容性 | 部分平台录音不可用 | 降级提示使用文字输入 |
|
||
| STT 转写准确率不足 | 会议纪要质量差 | 转写后支持用户编辑修正 |
|
||
| **工单 05 风险：架构文档与代码路径反复漂移** | 后续智能体又按旧路径改错文件 | 05 验收完成后，01-项目架构.md §2 ASCII 图顶部加"最后一次代码对齐时间戳"；后续改架构章节必须更新时间戳 + 走 Glob 校验 |
|
||
| **工单 05 风险：抽离 AddCloudSyncServer 时丢 using/命名空间** | Host 编译失败 | 改动范围严格控制在 CloudSync 两个文件；Program.cs 仅补 using；单步 build 验证后再提交 |
|
||
| **工单 06 风险：MapFallbackToFile 覆盖 /api 或 /swagger** | API/Swagger 全 404 | 中间件顺序严格按 §5 固定模板；集成测试同时验证 `/`、`/settings`（fallback）、`/api/cloud-sync/probe`（DynamicApi）、`/swagger`（Swagger UI）四个端点 |
|
||
| **工单 06 风险：CI 环境 npm 网络差/无 Node** | publish 超时或失败 | MSBuild Target 加 Node 缺失检测 → Warning + 跳过；生产部署可在外层 CI 先 build 前端再 publish Host |
|
||
| **工单 06 风险：增量构建 Inputs/Outputs 粗粒度** | 前端代码改了不重 build 或每次都重 build | Inputs 精确到 `**/*.{ts,vue,css,html}` + `package.json`；Outputs 精确到 `wwwroot/index.html`，首次过 CI 后人工改一行 .vue 验证是否触发 rebuild |
|
||
|
||
---
|
||
|
||
## 补充工单（追加于 2026-08-08）
|
||
|
||
### 工单 10 - 数据库初始化默认管理员
|
||
|
||
- **目标**：Host 服务端 DB Migrate 完成后自动创建默认管理员账号，免去手动调用 Bootstrap API
|
||
- **范围**：仅 `Hua.Todo.Host`；嵌入式模式（MAUI/Avalonia）不涉及
|
||
- **关联**：作为 06.1 服务端安全设计 Bootstrap 的自动前置项；与现有 `BootstrapAdmin` API 共存
|
||
- **详见**：[10-数据库初始化默认管理员.md](10-数据库初始化默认管理员.md)
|
||
---
|
||
|
||
**创建日期**：2026-06-15
|
||
**修订日期**：2026-08-08
|
||
**版本**：v1.3.0
|
||
**修订说明（2026-08-08）**：新增架构对齐补充工单 05/06（01-项目架构.md §3 模式 B 端点划分表与代码实际不一致触发）；所有新增条目均以"追加末尾"形式写入，未改动 2026-06-16 版本已有表格行和章节结构（符合 04-研发工单全流程规范 §2.1 已有文件不可触碰）。
|