Files

T

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

本次提交完成了项目核心基础架构升级：
1. 新增动态API中间件与权限控制系统，支持匿名/鉴权接口分离
2. 搭建云同步服务体系，包含认证、任务同步、安全策略等核心模块
3. 实现语音控制全链路，从STT/意图解析到命令执行
4. 新增任务类型、附件实体与相关仓储接口
5. 重构前端配置与代理规则，统一后端端口为5057
6. 新增多平台测试项目与CI脚本优化
7. 完善项目文档与代码注释规范

移除了旧版迁移文件与冗余代理配置，调整项目结构适配跨平台部署需求。

2026-06-21 03:26:04 +08:00

5.2 KiB

Raw Blame History

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 中 WebServer 节点缺少 CloudSyncUrl 字段
CloudSyncProxyService.CloudSyncUrl 默认值为空字符串，setter 中 string.IsNullOrWhiteSpace 将其转为 null
CloudSyncProxyService.cs 在 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 配置

打开云同步设置弹窗
输入服务端地址：http://localhost:5173
点击"保存并探测"
后续云同步请求经 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-设计层面的潜在改进点

默认值优化：在 dev 模式下，CloudSyncUrl 可默认指向 http://localhost:5173（Host 默认端口），减少首次手动配置。
错误提示增强：503 响应可携带更友好的错误信息，前端弹窗提示用户去云同步设置中配置服务端地址。
端口冲突风险：当 Host(5173) + MAUI(5057) + Avalonia(5057) 同时运行时，需注意数据库隔离与端口分配。

5.2 KiB Raw Blame History Unescape Escape