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) 同时运行时，需注意数据库隔离与端口分配。