ShaoHua
3213d4c718
- 重构架构：抽离AddCloudSyncServer到扩展类，补全中间层文档对齐 - 修复根路径404与鉴权跳转：新增中间件处理浏览器请求302跳转 - 实现种子数据初始化：添加默认管理员账号自动创建逻辑 - 优化前端代理与构建：新增Vite代理配置与自动构建Target - 补全测试与文档：新增集成测试，更新开发与部署文档
17 KiB
17 KiB
研发工单 v1.3.0 - 总览
术语澄清：本文件中"研发工单"指智能体/开发者执行的编码工作项，与业务侧的 Todo 待办项无关。详见 .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 §2.3「新增工单约束」：已有条目不可改写，本章节为本次新增。触发原因：本次 307 修复后重写 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 |
三、各子工单摘要
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 §五。
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：新增BuildHuaTodoWebWebRootTarget（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 §四。
四、待验证表
| 子工单 | 验证项 | 状态 | 备注 |
|---|---|---|---|
| 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 |
| 附件存储策略 | 附件存储在应用数据目录 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 的自动前置项；与现有
BootstrapAdminAPI 共存 - 详见：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 已有文件不可触碰）。