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