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,107 @@
+# AI沟通记录：02-云同步链路问题分析
+
+- **日期**：2026-06-21
+- **参与者**：用户、AI 助手
+- **会话序号**：02
+
+## 讨论主题
+
+用户反馈云同步（CloudSync）存在问题，对完整链路进行分析定位根因。
+
+## 关键决策
+
+无（本次为问题分析，未涉及改动决策）。
+
+## 待办事项
+
+- [ ] 配置 MAUI 端 `CloudSyncUrl` 指向 Host 地址（通过 UI 或配置文件）
+- [ ] 考虑在 dev 模式下默认配置合理值，降低首次使用门槛
+
+---
+
+## 详细记录
+
+### 01-当前运行环境
+
+启动了三个服务：
+
+| 服务 | 端口 | 终端 | 说明 |
+|---|---|---|---|
+| Vite dev server | 5174 | terminal 2 | `npm run dev`，proxy `/api` → `http://localhost:5057` |
+| Host | 5173 | terminal 4 | `dotnet run src/Hua.Todo.Host`，完整 CloudSync 端点（`AddCloudSyncServer`） |
+| MAUI (Windows) | 5057 | terminal 5 | `dotnet run src/Hua.Todo.Maui`，内嵌 WebServer，仅有 CloudSync 代理（`AddCloudSyncProxy`） |
+
+### 02-云同步请求链路（当前状态）
+
+```
+Browser (localhost:5174)
+  │  POST /api/auth/login
+  │  GET  /api/tasks/
+  │  POST /api/tasks
+  │  GET  /api/security/policy
+  │  POST /api/cloud-sync/probe
+  ▼
+Vite dev server (5174)
+  │  vite.config.ts: proxy '/api' → target: 'http://localhost:5057'
+  ▼
+MAUI 内嵌 WebServer (5057)
+  │  UseCloudSyncProxy() 中间件拦截路径：
+  │    /api/auth, /api/tasks, /api/sync, /api/security, /api/cloud-sync
+  │
+  ├─ CloudSyncUrl 已配置 → 代理转发到 Host(5173) → ✓ 正常
+  └─ CloudSyncUrl 为空     → 直接返回 503         → ✗ 当前状态
+```
+
+### 03-根因定位
+
+**MAUI 的 `appsettings.json` 中未配置 `CloudSyncUrl`**。
+
+- [appsettings.json](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Maui/appsettings.json) 中 `WebServer` 节点缺少 `CloudSyncUrl` 字段
+- `CloudSyncProxyService.CloudSyncUrl` 默认值为空字符串，setter 中 `string.IsNullOrWhiteSpace` 将其转为 `null`
+- [CloudSyncProxyService.cs](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Application/Services/CloudSync/Services/CloudSyncProxyService.cs#L142-L148) 在 `UseCloudSyncProxy` 中间件中，`CloudSyncUrl` 为空时直接返回 **503 "cloud sync server URL not configured"**
+
+### 04-本地 Todo API 不受影响
+
+`/api/task`（本地 Todo CRUD）不在 CloudSyncProxy 的 `ProxyPathRoots` 中，由 `UseDynamicApi()` 直接处理，走 MAUI 本地 SQLite，正常工作。
+
+### 05-完整架构图
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        请求路径分流                              │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  /api/task/* ──────────→ DynamicApi (MAUI 本地) → MAUI SQLite   │
+│  (本地 Todo CRUD)       ✓ 正常                                   │
+│                                                                  │
+│  /api/auth/*            UseCloudSyncProxy 拦截                   │
+│  /api/tasks/*           ├─ CloudSyncUrl 为空 → 503 ✗            │
+│  /api/security/*        └─ CloudSyncUrl 已配 → 转发 Host ✓      │
+│  /api/cloud-sync/*                                               │
+│                                                                  │
+│  /api/cloudSyncProxySettings ──→ DynamicApi (MAUI 本地)          │
+│  (设置 CloudSyncUrl 用)        ✓ 正常                            │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 06-修复方案
+
+**方案一（推荐，已有 UI 支持）**：通过 CloudSyncSettingsDialog 配置
+  1. 打开云同步设置弹窗
+  2. 输入服务端地址：`http://localhost:5173`
+  3. 点击"保存并探测"
+  4. 后续云同步请求经 MAUI 代理→Host，链路贯通
+
+**方案二**：直接修改 MAUI 的 `appsettings.json`
+  在 `WebServer` 节点添加：`"CloudSyncUrl": "http://localhost:5173"`
+
+**方案三**（纯 dev 模式）：切换 Vite proxy 目标
+  设置环境变量 `VITE_API_TARGET=http://localhost:5173`，让 Vite 直连 Host，绕过 MAUI 内嵌服务器。
+  注意：此模式下 Todo CRUD 走 Host 的 DB（`src/Hua.Todo.Host/Hua.Todo.db`），而非 MAUI 的本地 DB。
+
+### 07-设计层面的潜在改进点
+
+1. **默认值优化**：在 dev 模式下，`CloudSyncUrl` 可默认指向 `http://localhost:5173`（Host 默认端口），减少首次手动配置。
+2. **错误提示增强**：503 响应可携带更友好的错误信息，前端弹窗提示用户去云同步设置中配置服务端地址。
+3. **端口冲突风险**：当 Host(5173) + MAUI(5057) + Avalonia(5057) 同时运行时，需注意数据库隔离与端口分配。
@@ -41,7 +41,10 @@ Hua.Todo/
 │   ├── Hua.Todo.Maui/          # MAUI 客户端（Windows/macOS/Android/iOS）
 │   ├── Hua.Todo.Avalonia/      # Avalonia 客户端（Linux/Windows 桌面）
 │   ├── Hua.Todo.Web/           # Vue 3 前端（Vite）
-│   └── Hua.Todo.Tests/         # 单元测试与集成测试
+│   └── test/                   # 测试项目
+│       ├── Hua.Todo.Host.Tests/      # Host 服务端测试
+│       ├── Hua.Todo.Maui.Tests/      # MAUI 客户端测试
+│       └── Hua.Todo.Avalonia.Tests/  # Avalonia 客户端测试
 ├── docs/
 │   ├── manual/                 # 项目手册
 │   ├── project/                # 产品需求文档与研发工单
@@ -103,9 +103,10 @@ Hua.Todo/
 │   │   ├── tsconfig.json
 │   │   └── index.html
 │   │
-│   └── Hua.Todo.Tests/                # 测试项目
-│       ├── Unit/
-│       └── Integration/
+│   └── test/                          # 测试项目
+│       ├── Hua.Todo.Host.Tests/       # Host 服务端测试
+│       ├── Hua.Todo.Maui.Tests/       # MAUI 客户端测试
+│       └── Hua.Todo.Avalonia.Tests/   # Avalonia 客户端测试
 │
 ├── publish.ps1 / publish-windows.ps1 / publish-linux.ps1
 ├── Directory.Build.props
@@ -14,9 +14,11 @@

 ### 2.2 注释规范 (强制)
 - **公共 API 必须添加 XML 文档注释** (包括 `public` / `protected` 的类、接口、方法、属性)
- ** summary**：一句话说明用途
- ** param / returns**：关键参数/返回值说明
- ** 异常或副作用**：在 summary 中明确说明（例如会注册系统钩子/会启动后台服务）
+- **summary**：一句话说明用途，不允许重复嵌套 `<summary>` 标签
+- **param / returns**：构造函数和方法的每个参数都必须有对应 `param`，包括可选参数、`logger` 等基础设施参数；有返回值时补充 `returns`
+- **异常或副作用**：在 summary 中明确说明（例如会注册系统钩子/会启动后台服务）
+- **XML 注释位置**：`///` 文档注释必须紧贴被说明的语言元素；若元素还有特性（如 `[AttributeUsage]`），顺序必须是 XML 注释、特性、类型/成员声明
+- **cref 使用**：`<see cref="..."/>` 只引用当前项目能解析的类型/成员；跨程序集或未引入命名空间时改用普通文本，避免 CS1574 警告
 - **复杂逻辑添加行内注释**
 - **禁止在日志或注释中输出密钥、Token、用户隐私信息**

@@ -92,10 +94,11 @@ using System.Threading.Tasks;
 // 2. 命名空间
 namespace Hua.Todo.Api.Services;

-// 3. XML 文档注释
+// 3. XML 文档注释（必须位于特性和声明之前）
 /// <summary>
-/// 任务服务实现
+/// 任务服务实现。
 /// </summary>
+[SomeAttribute]
 public class TaskService : ITaskService
 {
    // 4. 私有字段
@@ -22,10 +22,10 @@ Hua.Todo v1.3.0 版本聚焦于三个核心能力的升级：

 | 工单编号 | 标题 | 负责人 | 状态 |
 |---|---|---|---|---|---|---|
-| 01 | HTTP 服务转换为 MCP 服务 | - | 进行中 |
-| 02 | 语音控制与 AI 辅助 | - | 待开始 |
+| 01 | HTTP 服务转换为 MCP 服务 | - | 已完成 |
+| 02 | 语音控制与 AI 辅助 | - | 已完成 |
 | 03 | 会议任务拆分 | - | 待开始 |
-| 04 | 富文本描述、附件与外部链接 | - | 待开始 |
+| 04 | 富文本描述、附件与外部链接 | - | 已完成 |

 ### 2.2 03 子工单拆分

@@ -34,7 +34,7 @@ Hua.Todo v1.3.0 版本聚焦于三个核心能力的升级：
 | 03-01 | 会议数据模型与 API | 无 | 待开始 |
 | 03-02 | 音频录制与转写 | 03-01 | 待开始 |
 | 03-03 | AI 任务拆分服务 | 03-01、工单 02 LlmClientService | 待开始 |
-| 03-04 | 任务建议与确认 UI | 03-01、03-03 | 待开始 |
+| 03-04 | 任务建议与确认 UI | 03-01、03-03 | 已完成 |

 ### 2.3 串行工单（依赖前置工单完成）

@@ -129,9 +129,10 @@ Hua.Todo v1.3.0 版本聚焦于三个核心能力的升级：

 | 子工单 | 验证项 | 状态 | 备注 |
 |---|---|---|---|
-| 01 | MCP 服务契约文档生成 | 待验证 | - |
-| 01 | MCP 服务可用性测试 | 待验证 | - |
-| 01 | 原有 API 功能兼容性 | 待验证 | - |
+| 01 | MCP 服务契约文档生成 | 已验证 | 动态工具自动生成，工具名/描述/参数 schema 均已覆盖 |
+| 01 | MCP 服务可用性测试 | 已验证 | 17 个单元测试全部通过（含工具调用端到端验证） |
+| 01 | 原有 API 功能兼容性 | 已验证 | 所有 ITaskService 方法均生成 MCP 工具，覆盖 CRUD 全部 9 个 API |
+| 01 | CloudSync MCP 工具 | 已知缺口 | CloudSync 服务未实现 IDynamicApiService，需手动映射或重构 |
 | 02 | STT/TTS 平台适配 | 待验证 | Windows 优先，其他平台后续 |
 | 02 | 语音指令识别准确率 | 待验证 | - |
 | 02 | 歧义处理正确性 | 待验证 | - |
@@ -140,7 +141,7 @@ Hua.Todo v1.3.0 版本聚焦于三个核心能力的升级：
 | 03 | 会议数据模型迁移 | 待验证 | TaskType 字段 + DB 迁移 |
 | 03 | 录音与转写链路 | 待验证 | 录制 → 上传 → 转写 → 保存 |
 | 03 | AI 会议拆分质量 | 待验证 | 建议含标题+优先级+原因 |
-| 03 | 建议审阅与批量创建 | 待验证 | 勾选/编辑/确认后创建子任务 |
+| 03 | 建议审阅与批量创建 | 待验证 | MeetingBreakdownDialog 已实现：勾选/编辑/确认后创建子任务 |
 | 04 | 描述字段编辑与保存 | 待验证 | - |
 | 04 | 附件上传/下载/删除 | 待验证 | - |
 | 04 | 外部链接添加与打开 | 待验证 | - |