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
@@ -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 个测试全部通过

 ---