feat: 完成云同步、语音控制与多平台扩展基础架构搭建

本次提交完成了项目核心基础架构升级： 1. 新增动态API中间件与权限控制系统，支持匿名/鉴权接口分离 2. 搭建云同步服务体系，包含认证、任务同步、安全策略等核心模块 3. 实现语音控制全链路，从STT/意图解析到命令执行 4. 新增任务类型、附件实体与相关仓储接口 5. 重构前端配置与代理规则，统一后端端口为5057 6. 新增多平台测试项目与CI脚本优化 7. 完善项目文档与代码注释规范移除了旧版迁移文件与冗余代理配置，调整项目结构适配跨平台部署需求。
2026-06-21 03:26:04 +08:00
parent 65cee20006
commit 4fe0b5a963
200 changed files with 12728 additions and 3550 deletions
@@ -0,0 +1 @@
+{}
@@ -63,7 +63,7 @@

 | 子目录 | 当前最大序号 | 下一个可用 |
 |---|---|---|
-| `rules/全局/` | 06 | 07 |
+| `rules/全局/` | 07 | 08 |
 | `rules/项目/` | 05 | 06 |
 | `memory/` | 01 | 02 |
 | `coordination/` | 02 | 03 |
@@ -17,9 +17,11 @@ description: 强制项目注释规范（C# / TypeScript）：新增或修改代
 ## C#（.NET / MAUI）

 - 所有 `public` / `protected` 的 **类、接口、方法、属性** 必须提供 XML 文档注释，至少包含：
-  - `summary`：一句话说明用途
-  - 对关键参数/返回值：`param` / `returns`
+  - `summary`：一句话说明用途，不允许重复嵌套 `<summary>` 标签
+  - 对参数/返回值：构造函数和方法的每个参数都必须有对应 `param`，包括可选参数、`logger` 等基础设施参数；有返回值时补充 `returns`
  - 对异常或副作用：在 `summary` 中明确说明（例如会注册系统钩子/会启动后台服务）
+- XML 文档注释必须紧贴被说明的语言元素；若元素还有特性（如 `[AttributeUsage]`），顺序必须是 XML 注释、特性、类型/成员声明，避免 `///` 落在特性之后导致 CS1587。
+- `<see cref="..."/>` 只引用当前项目能解析的类型/成员；跨程序集或未引入命名空间时改用普通文本，避免 CS1574。
 - 对 **跨平台逻辑**：
  - 禁止在同一文件内混写多个平台的大段 `#if` 实现；应优先使用 `partial`、接口与平台目录分离。
  - 平台分离后的公共入口处必须说明"平台差异在哪里、默认实现是什么、为什么这么做"。
@@ -138,4 +138,6 @@ NN-NN-标题.md

 ---

-**关联规则**：[05-并行窗口冲突规约.md](./05-并行窗口冲突规约.md)
+**关联规则**：[05-并行窗口冲突规约.md](./05-并行窗口冲突规约.md)、[07-代码实现与测试先行规范.md](./07-代码实现与测试先行规范.md)
+
+> 工单进入代码实现阶段时，必须遵循"测试先行（ATDD）"工作流：先依据本规范的验收标准编写验收测试用例，再实现代码，测试全部通过后才算工单完成。详见 [07-代码实现与测试先行规范.md](./07-代码实现与测试先行规范.md)。
@@ -0,0 +1,87 @@
+# 代码实现与测试先行规范（必须遵守）
+
+> 全局规则。规定何时必须写测试 + 怎么写（ATDD：验收测试驱动开发）。与 [04-研发工单全流程规范.md](./04-研发工单全流程规范.md) 配套：04 管工单拆分，本规范管实现与验收。
+
+---
+
+## 一、触发条件（什么时候必须写测试）
+
+用户表述满足以下任一条件时，**必须**执行测试先行：
+
+| 触发条件 | 示例 |
+|---|---|
+| 明确指出 bug（"修正"/"修复"/"不应该"/"404"） | "登录按钮点不了""/sync 404""数据丢了" |
+| 要求新增功能 | "加一个导出按钮""新增 XX 端点" |
+| 要求修改现有行为 | "把优先级改成默认高""去掉确认弹窗" |
+
+**豁免**（无需测试先行，但改动后必须跑已有测试）：
+
+| 场景 | 示例 |
+|---|---|
+| 纯配置 | `appsettings.json` 默认值、连接字符串 |
+| 纯格式化/注释 | ESLint 自动修复、XML doc 补充 |
+| 依赖升级无 API 变更 | NuGet/npm 补丁版本 |
+| 文档/规则更新 | 新增 `.trae/rules/` 文件 |
+
+> 判定原则：改动出错用户能感知 → 不可豁免。
+
+---
+
+## 二、强制流程
+
+1. **提炼验收点**：从用户描述提取 Given-When-Then 验收场景（主:分支:异常 ≈ 1:2:2）
+2. **RED**：写验收测试，实跑确认失败（失败原因 = 被测功能缺失，非 setup 错误）
+3. **GREEN**：写最小量代码使测试通过
+4. **REFACTOR**：重构优化，重跑测试仍 GREEN
+
+**不得跳过任何步骤。**
+
+## 三、验收测试用例规范
+
+格式（Given-When-Then）：
+
+```
+Given [前置条件]
+When  [操作]
+Then  [预期结果]
+```
+
+示例：`Given 本地 3 个未完成待办 / When POST /api/task 创建"写周报" / Then 返回 201 且共 4 条`
+
+要求：
+- 命名体现场景：`CreateTask_EmptyTitle_Returns400`
+- 一个测试只验证一个行为点
+- 断言可量化
+- 至少覆盖集成测试层（不满足于纯单元测试）
+
+## 四、工单完成判定（全部满足才标记"已完成"）
+
+1. 所有验收测试通过
+2. 原有测试无回归
+3. [04-即时状态记忆.md](../项目/04-即时状态记忆.md) 或 `00-工单总览.md` 待验证表标注"已验证"
+4. 按 [03-文档同步规范.md](./03-文档同步规范.md) 同步文档
+
+## 五、Git Checkpoint 提交（推荐）
+
+| 阶段 | 提交信息 |
+|---|---|
+| RED | `test(workitem): 为 <工单> 添加失败的验收测试` |
+| GREEN | `feat(workitem): 实现 <工单> 使验收测试通过` |
+| REFACTOR | `refactor(workitem): 重构 <模块> 保持测试通过` |
+
+流程完成前不得 squash。提交信息禁用歧义"任务"二字。
+
+## 六、检查清单
+
+- [ ] 触发条件满足？豁免类是否确认无行为变更？
+- [ ] 提炼了 Given-When-Then 验收场景？
+- [ ] RED 实跑确认失败，失败原因 = 功能缺失？
+- [ ] GREEN 最小代码通过测试？
+- [ ] REFACTOR 后测试仍 GREEN？
+- [ ] 场景覆盖主/分支/异常？
+- [ ] 原有测试无回归？
+- [ ] 工单完成四条件全部满足？
+
+---
+
+**关联**：[04-研发工单全流程规范.md](./04-研发工单全流程规范.md)、[03-文档同步规范.md](./03-文档同步规范.md)、[05-并行窗口冲突规约.md](./05-并行窗口冲突规约.md)
@@ -73,3 +73,32 @@ Hua.Todo.Web (无 .NET 依赖；通过 HTTP/同源调用上述任一宿主)
 - Inno Setup 安装包：`src/Hua.Todo.Maui/setup.iss`、`src/Hua.Todo.Avalonia/setup.iss`
 - Linux：`publish-linux.ps1` 产出 `.tar.gz`；`pack/linux/` 含 Flatpak 基础结构
 - 详见 [docs/project/研发工单-v1.2.0/02.1-版本统一与打包方案.md](../../../docs/project/研发工单-v1.2.0/02.1-版本统一与打包方案.md)
+
+## 七、测试项目架构
+
+### 7.1 目录结构
+
+```
+test/                                     ← 项目根目录下的顶层测试目录
+├── Hua.Todo.Host.Tests/                  ← 服务端/Application 层集成测试
+│   ├── CloudSync/                        ← 云同步模块
+│   ├── Meeting/                          ← 会议模块
+│   └── Attachments/                      ← 附件模块
+├── Hua.Todo.Maui.Tests/                  ← MAUI 平台测试（骨架）
+└── Hua.Todo.Avalonia.Tests/              ← Avalonia 平台测试（骨架）
+```
+
+### 7.2 分层规则（严禁跨层）
+
+| 测试项目 | 可引用的被测项目 | 不得引用 |
+|---|---|---|
+| `Hua.Todo.Host.Tests` | `Hua.Todo.Host` / `Application` / `Core` | MAUI / Avalonia 宿主 |
+| `Hua.Todo.Maui.Tests` | `Hua.Todo.Maui` / `Application` / `Core` | Avalonia 宿主 |
+| `Hua.Todo.Avalonia.Tests` | `Hua.Todo.Avalonia` / `Application` / `Core` | MAUI 宿主 |
+
+### 7.3 技术栈与规范
+
+- 框架：xUnit 2.9+，SQLite In-Memory 模拟 DB
+- 测试层次：直接测 Application 服务层（DI 测试），必要时用 `WebApplicationFactory`
+- 命名：类 `{被测类}Tests`、方法 `{方法名}_{场景}_{预期结果}`、命名空间 `Hua.Todo.Host.Tests.{模块名}`
+- 文件组织：每个模块新建子目录，模块级共用测试放根目录
@@ -42,8 +42,8 @@
 | 03-01 - 会议数据模型与 API | 待开始 | 待验证 | TaskType 枚举、MeetingNotes/AudioDuration 字段、MeetingController |
 | 03-02 - 音频录制与转写 | 待开始 | 待验证 | 前端 MediaRecorder 录音 + 后端 STT 转写 |
 | 03-03 - AI 任务拆分服务 | 待开始 | 待验证 | 会议专用 LLM prompt + 批量创建子任务 |
-| 03-04 | 任务建议与确认 UI | 待开始 | 待验证 | 录音/纪要/审阅对话框 + Meeting 类型条件渲染 |
-| 04 | 富文本描述、附件与外部链接 | 待开始 | 待验证 | 多行描述 + 附件上传下载删除 + 外部链接 + 桌面端 Process.Start/xdg-open |
+| 03-04 | 任务建议与确认 UI | 已完成 | 待验证 | MeetingBreakdownDialog.vue + meeting.ts 拆分/确认 API；待集成到 TaskItem |
+| 04 | 富文本描述、附件与外部链接 | 已完成 | 待验证 | Description 字段 + AttachmentEntity 模型 + 附件 CRUD API + 外部链接 + 平台文件打开器（Maui/Avalonia）+ 前端类型和 API 模块完善 + EF 迁移 + 19 个单元测试通过 |

 ## 四、关键临时决策

@@ -62,6 +62,33 @@

 - [x] v1.3.0 工单01 - MCP 服务转换已完成（2026-06-16）：DynamicMcpToolExtensions 自动扫描所有 IDynamicApiService 接口并生成 MCP 工具；当前覆盖 ITaskService（9 个工具）+ IVoiceService（4 个工具）= 13 个 MCP 工具；新增 4 个测试（描述验证、InputSchema 验证、服务调用、工具调用端到端），共计 17 个测试全部通过；CloudSync 服务因未实现 IDynamicApiService 暂未覆盖，记录为已知缺口

+- [x] MAUI 平台编译修复（2026-06-16）：(1) Application.csproj 非 net10.0 目标新增排除 CloudSync/**/*.cs（其依赖 Microsoft.AspNetCore.App）；(2) 新增 Microsoft.Extensions.Http 包引用（Voice 服务使用 AddHttpClient）；(3) MobileEmbeddedWebServerService.cs Android 平台 int→Guid 适配（TaskEntity ABP 重构遗留）；验证通过：MAUI Android/Windows + Host 均 0 错误
+
+- [x] 测试项目重构（2026-06-17）：原 src/Hua.Todo.Tests 拆分为三个宿主对应测试项目，放入 src/test/ 目录：Hua.Todo.Host.Tests（后端服务测试，144 个用例全过）、Hua.Todo.Maui.Tests（骨架）、Hua.Todo.Avalonia.Tests（骨架）；更新 .slnx 与 docs 引用
+
+- [x] EF Core 迁移合并（2026-06-17）：10 个历史迁移合并为单一 `20260616203619_InitialCreate`，Migrations 目录从 21 个文件减至 3 个；DatabaseMigrationTests 断言同步更新；157 个测试全部通过
+
+- [x] MAUI Windows 云同步代理功能修复（2026-06-17）：
+  - **问题**：`Hua.Todo.Application.csproj` 第 14-18 行在非 net10.0 目标上排除了整个 CloudSync 目录，导致 MAUI Windows 编译时 CloudSync 代码不存在
+  - **影响**：MAUI Windows 的 `EmbeddedWebServerService` 缺少云同步代理支持（`AddCloudSyncProxy()`、`UseCloudSyncProxy()`、`MapCloudSyncProxySettings()`），前端云同步设置弹窗无法工作
+  - **修复**：
+    1. 从 Application.csproj 移除 CloudSync 的自动排除（保留 SkipCloudSync=true 手动开关）
+    2. MAUI Windows `EmbeddedWebServerService` 添加云同步代理支持（参考 Avalonia 实现）
+    3. `WebServerSettings` 新增 `CloudSyncUrl` 属性
+  - **验证**：MAUI Windows + Host + 152 个测试 全部通过
+
+- [x] DynamicApi/Mcp/CloudSync ASP.NET Core 依赖隔离（2026-06-17）：
+  - **问题**：Application.csproj 在非 net10.0 目标上整体排除 DynamicApi/**/*.cs 和 Mcp/**/*.cs，并用桩文件（Compatibility/DynamicApiStubs.cs）替代；CloudSync 通过 SkipCloudSync=true 手动排除；核心属性类（HttpAttributes、RemoteServiceAttribute 等）在移动平台不可用
+  - **修复**：
+    1. 移除 csproj 中 DynamicApi/Mcp 的整体排除、桩文件排除、SkipCloudSync 开关
+    2. 新增 `ASPNETCORE` 编译符号（仅 net10.0 目标定义）
+    3. DynamicApi 核心属性文件（HttpAttributes.cs、ParameterBindingAttributes.cs、RemoteServiceAttribute.cs）全平台编译
+    4. DynamicApi/Mcp/CloudSync 中 13 个 ASP.NET Core 依赖文件用 `#if ASPNETCORE` 包裹
+    5. ClaimsPrincipalExtensions.cs 用 `FindFirst()?.Value` 替代 ASP.NET Core 的 `FindFirstValue` 扩展方法
+    6. 删除 Compatibility/DynamicApiStubs.cs 桩文件
+    7. 清理测试项目中的 SkipCloudSync 排除
+  - **验证**：Application(net10.0 + net10.0-android) + Host + MAUI(Windows + Android) 全部 0 错误；152 个测试全部通过
+
 ## 六、最近一次重大重构（如有）

 - **术语统一与目录中文化**（2026-06）：
@@ -77,6 +104,53 @@
  - 拆分用户面与开发者面：01-02 为用户安装使用；05-10 为开发者架构/构建/规范
  - 合并重叠与过时内容，精简用户文档篇幅
  - 同步更新 README.md 与 `.trae/rules/项目/` 中的交叉引用
+- **全局 Serilog 文件日志**（2026-06-16）：
+  - Application 层新增 `LoggingConfiguration.cs` 统一日志配置（Console + 按天滚动文件）
+  - Host / MAUI / Avalonia 宿主层全部接入 Serilog，日志目录 `logs/`（Host）或 `{LocalApplicationData}/Hua.Todo/logs/`（客户端）
+  - 修复 `DynamicApiMiddleware` 及 Application 层 8 个服务类的 catch 块（原静默吞异常→记日志）
+  - 修复 MAUI 端 2 个 WebServer 文件 + Avalonia 端 `App.axaml.cs` / `EmbeddedWebServerService` 的 Console/Debug→Serilog
+  - 修复 `CloudTaskSyncService` SQL UNIQUE 约束冲突重试日志
+  - 144 个测试全部通过
+
+- **Host 云同步端点补齐 + 测试目录迁移 + 规则新增**（2026-06-17）：
+  - **问题**：`Hua.Todo.Host/Program.cs` 未调用 `AddCloudSyncServer()` 和 `MapCloudSyncEndpoints()`，导致 `/auth/*` `/tasks/*` `/sync/*` `/security/*` `/cloud-sync/*` 全部 404
+  - **修复**：Program.cs 新增 `AddCloudSyncServer()` + `MapCloudSyncEndpoints()` + `MapCloudSyncProxySettings()`；`vite.config.ts` 新增 6 条云同步路径代理
+  - **测试**：`CloudSyncEndpointRegistrationTests.cs` 新增 5 个 DI 注册测试（完整 AddApplicationServices + AddCloudSyncServer 链路验证），157→157 全部通过
+  - **目录迁移**：`src/test/` → `test/`（上移一级），更新 3 个 `.csproj` 的 `<ProjectReference>` 路径 + `.slnx`
+  - **规则新增**：
+    - `.trae/rules/全局/08-修正与新功能自动测试门禁.md`：用户明确要求修正 bug 或新功能时自动触发测试先行
+    - `.trae/rules/项目/06-测试项目分层规范.md`：测试目录结构、分层规则（禁止跨层）、技术栈与命名规范
+  - **前端默认值**：`CloudSyncSettingsDialog` 默认地址 `http://localhost:5173`、默认账号 `admin`/`123456`
+  - **前端云同步入口**：`TaskList.vue` 新增登录/登出/同步按钮 + 用户信息 + 服务器地址显示；`App.vue` 修复 `CloudSyncSettingsDialog` 缺少 import 导致弹窗不打开
+
+- **前端大量补齐**（2026-06-17 v1.3.0）：
+  - 新增 7 个文件（AttachmentList/LinkInputDialog/useAttachments/voice.ts/useVoiceInput/规则2个）
+  - 修改 5 个文件（TaskEditDialog/TaskItem/TaskList/tasks.ts/localStorageService）
+  - 删除 1 个无用文件（HelloWorld.vue）
+  - 编译 0 错误，105 个模块构建成功
+
+- **CloudSync 端点 DynamicApi 化**（2026-06-17）：
+  - **问题**：`CloudSyncEndpointExtensions.MapCloudSyncEndpoints()` 手动映射 16 个端点（auth/tasks/sync/security/admin/probe），与项目中 ITaskService 等通过 IDynamicApiService 自动暴露的模式不一致
+  - **修复**：
+    1. 新增 `DynamicApiRouteAttribute`（服务级路由前缀覆盖）和 `RequirePermissionAttribute`（权限检查）
+    2. 扩展 `DynamicApiMiddleware`：支持 `DynamicApiRoute` 自定义路由前缀、`AllowAnonymous` / `RequirePermission` 权限检查、统一错误响应（401/403）
+    3. 创建 5 个 IDynamicApiService 接口：`ICloudAuthService`（`/api/auth`）、`ICloudTaskSyncService`（`/api/tasks`）、`ISecurityPolicyService`（`/api/security`）、`ICloudAdminService`（`/api/admin`）、`ICloudProbeService`（`/api/cloud-sync`）
+    4. 修改 5 个 Service 实现类：添加 `IHttpContextAccessor` 支持、接口方法（无 CancellationToken）、保留原有方法（Guided by CancellationToken）向后兼容
+    5. 移除 `MapCloudSyncEndpoints()` 入口和 16 个 handler 方法，`CloudSyncEndpointExtensions` 仅保留 `MapCloudSyncProxySettings()`
+    6. Host `Program.cs` 新增 `app.UseAuthentication()` 确保 SessionAuthenticationHandler 在 DynamicApi 前运行
+    7. `ResetPasswordRequest` 新增 `UserId` 字段（admin 重置密码路由扁平化）
+    8. `DynamicMcpToolExtensions` 新增 `RemoteServiceAttribute` 过滤（CloudSync 接口标记 `IsEnabled=false` 排除 MCP 暴露）
+    9. 4 个 Service 文件（CloudTaskSync/SecurityPolicy/CloudProbe/CloudAuth-接口方法）新增 `#if ASPNETCORE` 条件编译
+  - **验证**：Application(net10.0+android+ios+maccatalyst) + Host + Tests 全部编译通过，161 个测试全部通过
+
+- [x] CloudSync Swagger + DynamicApi 路由修复（2026-06-17）：
+  - **问题1**：所有 CloudSync 接口标记 `[RemoteService(IsEnabled=false)]`，`DynamicApiSwaggerDocumentFilter` 用 `IsEnabled` 过滤 → CloudSync 接口在 Swagger 中完全不可见（只有 DTO Schema 没有 Path）
+  - **问题2**：同样的 `IsEnabled=false` 导致 `DynamicApiMiddleware` 跳过 CloudSync 请求 → `/auth/*` `/tasks/*` `/security/*` `/admin/*` `/cloud-sync/*` 全部 404
+  - **修复**：
+    1. `DynamicApiSwaggerDocumentFilter.IsRemoteServiceEnabled` 改为检查 `IsMetadataEnabled`（与 `IsEnabled` 解耦：原 `IsEnabled=false` 的接口 Swagger 仍可见）
+    2. 移除 6 个 CloudSync 接口 + `ICloudSyncProxySettingsService` 的 `[RemoteService(IsEnabled=false)]`
+    3. MCP 工具改为命名空间过滤：`IsCloudSyncService(type)` 排除 `Hua.Todo.Application.CloudSync.*` 命名空间
+  - **验证**：编译 0 错误，161 个测试全部通过

 ---

@@ -38,6 +38,7 @@
 | [04-研发工单全流程规范.md](./rules/全局/04-研发工单全流程规范.md) | 研发工单术语定义 + 拆分输出规范 + 新增工单约束（合并原 05/06/09） |
 | [05-并行窗口冲突规约.md](./rules/全局/05-并行窗口冲突规约.md) | 并行 solo 窗口下的 Touch List / Writer / 绿线策略 |
 | [06-AI沟通记录规范.md](./rules/全局/06-AI沟通记录规范.md) | 用户与智能体沟通记录的存储目录、序号管理与内容规范 |
+| [07-代码实现与测试先行规范.md](./rules/全局/07-代码实现与测试先行规范.md) | 触发条件 + ATDD 工作流（RED→GREEN→REFACTOR）+ 验收测试用例规范 + 工单完成判定（合并原 07+08） |

 ---

@@ -45,11 +46,12 @@

 | 文件 | 职责 |
 |---|---|
-| [01-项目架构.md](./rules/项目/01-项目架构.md) | src/ 五大项目划分、依赖方向、两种运行模式 |
+| [01-项目架构.md](./rules/项目/01-项目架构.md) | src/ 项目清单、依赖方向、两种运行模式、跨平台原则、关键扩展点、测试项目架构 |
 | [02-业务命名规范.md](./rules/项目/02-业务命名规范.md) | `Task`/`SubTask`/`TaskEntity` 等代码标识符与"研发工单"边界 |
 | [03-数据模型与迁移约束.md](./rules/项目/03-数据模型与迁移约束.md) | EF Core 实体清单、迁移历史、改 schema 纪律 |
 | [04-即时状态记忆.md](./rules/项目/04-即时状态记忆.md) | 当前活跃版本 / 工单状态快照 / 临时决策 / 未完结事项 |
 | [05-多入口功能同步规范.md](./rules/项目/05-多入口功能同步规范.md) | 新增功能时必须同步确认 UI 入口与语音控制入口的覆盖情况 |
+| [06-测试项目分层规范.md](./rules/项目/06-测试项目分层规范.md) | 测试项目目录结构、分层规则（禁止跨层）、技术栈与命名规范 |

 ---