feat(saas): P2 增强 — TOTP 2FA、Relay 重试、配置同步升级

- TOTP 2FA: totp-rs v5.7.1 + data-encoding Base32, setup/verify/disable 流程, 登录时 TOTP 验证集成, SaasError::Totp 返回 400 - Relay 重试: 指数退避 (base_delay_ms * 2^attempt), 错误分类 (4xx 不重试), Admin POST /tasks/:id/retry 端点 - 配置同步: push (客户端覆盖) / merge (SaaS 优先) / diff (只读对比), 实际写入 config_items 表 - 集成测试: 27 个测试全部通过 (新增 6 个 P2 测试) - 文档: 更新 SaaS 平台总览 (模块完成度 + API 端点列表)
2026-03-27 17:58:14 +08:00
parent bc12f6899a
commit 452ff45a5f
15 changed files with 876 additions and 68 deletions
--- a/docs/features/08-saas-platform/00-saas-overview.md
+++ b/docs/features/08-saas-platform/00-saas-overview.md
@@ -0,0 +1,140 @@
+# ZCLAW SaaS 平台 — 总览
+
+> 最后更新: 2026-03-27 | 实施状态: Phase 1-4 + P2 全部完成
+
+## 架构概述
+
+ZCLAW SaaS 平台为桌面端用户提供云端能力，包括模型中转、账号管理、配置同步和团队协作。
+
+```text
+桌面端 (Tauri/React)
+    │
+    ├── Mode A: Tauri Kernel (本地直连)
+    ├── Mode B: Gateway WebSocket
+    └── Mode C: SaaS Cloud ──→ Rust/Axum 后端 ──→ 上游 LLM Provider
+                                │
+                                ├── Admin Web (Next.js 管理后台)
+                                └── SQLite WAL (数据持久化)
+```
+
+## 技术栈
+
+| 层级 | 技术 | 说明 |
+|------|------|------|
+| 后端 | Rust + Axum + sqlx + SQLite WAL | JWT + API Token 双认证 |
+| Admin | Next.js 14 + shadcn/ui + Tailwind | 暗色 OLED 主题 |
+| 桌面端 | React 18 + Zustand + TypeScript | saas-client.ts HTTP 通信 |
+| 安全 | argon2 + TOTP 2FA + RBAC | 速率限制 + 操作审计 |
+
+## 功能模块
+
+| 模块 | 完成度 | 核心能力 |
+|------|--------|----------|
+| 认证 (Auth) | 100% | JWT + API Token + 密码修改 + /me + TOTP 2FA |
+| 账号 (Account) | 100% | CRUD + 角色管理 + 自角色限制 + 设备管理 |
+| 模型配置 (Model Config) | 95% | Provider/Model/Key CRUD + 用量记录 |
+| 中转 (Relay) | 95% | SSE 流式 + 任务记录 + 指数退避重试 + Admin 重试 |
+| 配置迁移 (Migration) | 90% | CRUD + 同步日志 + push/merge + diff |
+| Admin UI | 95% | 10 个 CRUD 页面 + Dashboard |
+| 桌面端集成 | 95% | 登录/注册/状态/密码/设备/离线/迁移向导 |
+
+## API 端点一览
+
+### 公开端点 (无需认证)
+- `POST /api/v1/auth/register` — 注册
+- `POST /api/v1/auth/login` — 登录
+- `GET /api/health` — 健康检查
+
+### 认证端点
+- `GET /api/v1/auth/me` — 当前用户信息
+- `POST /api/v1/auth/refresh` — 刷新 Token
+- `PUT /api/v1/auth/password` — 修改密码
+
+### TOTP 双因素认证 (P2)
+- `POST /api/v1/auth/totp/setup` — 生成 TOTP 密钥，返回 otpauth:// URI
+- `POST /api/v1/auth/totp/verify` — 验证 TOTP 码并启用 2FA
+- `POST /api/v1/auth/totp/disable` — 禁用 2FA (需密码确认)
+
+### 账号管理
+- `GET /api/v1/accounts` — 列出账号 (admin)
+- `GET /api/v1/accounts/:id` — 获取账号
+- `PUT /api/v1/accounts/:id` — 更新账号
+- `PATCH /api/v1/accounts/:id/status` — 更新状态 (admin)
+- `GET /api/v1/stats/dashboard` — 仪表盘统计 (admin)
+
+### API Token
+- `GET /api/v1/tokens` — 列出 Token
+- `POST /api/v1/tokens` — 创建 Token
+- `DELETE /api/v1/tokens/:id` — 撤销 Token
+
+### 设备管理
+- `POST /api/v1/devices/register` — 注册/更新设备 (UPSERT)
+- `POST /api/v1/devices/heartbeat` — 设备心跳
+- `GET /api/v1/devices` — 列出设备
+
+### 模型配置
+- `GET/POST /api/v1/providers` — Provider CRUD
+- `GET/POST/PUT/DELETE /api/v1/providers/:id` — 单个 Provider
+- `GET/POST /api/v1/models` — Model CRUD
+- `GET/POST/PUT/DELETE /api/v1/models/:id` — 单个 Model
+- `GET/POST/DELETE /api/v1/keys` — API Key CRUD
+
+### 中转 (Relay)
+- `GET /api/v1/relay/models` — 可用中转模型
+- `POST /api/v1/relay/chat/completions` — 聊天中转 (SSE/JSON)
+- `GET /api/v1/relay/tasks` — 中转任务列表
+- `GET /api/v1/relay/tasks/:id` — 获取单个任务
+- `POST /api/v1/relay/tasks/:id/retry` — 重试失败任务 (admin)
+
+### 配置
+- `GET /api/v1/config/items` — 列出配置项
+- `POST /api/v1/config/items` — 创建配置项
+- `GET /api/v1/config/items/:id` — 获取配置项
+- `PUT /api/v1/config/items/:id` — 更新配置项 (admin)
+- `DELETE /api/v1/config/items/:id` — 删除配置项 (admin)
+- `GET /api/v1/config/analysis` — 配置分析
+- `POST /api/v1/config/seed` — 种子配置 (admin)
+- `POST /api/v1/config/sync` — 配置同步 (push/merge)
+- `POST /api/v1/config/diff` — 配置差异对比 (只读)
+- `GET /api/v1/config/sync-logs` — 同步日志
+
+### 审计
+- `GET /api/v1/logs/operations` — 操作日志 (admin)
+- `GET /api/v1/usage` — 用量统计
+
+## 关键文件索引
+
+### 后端 (crates/zclaw-saas/)
+| 文件 | 职责 |
+|------|------|
+| `src/main.rs` | 服务启动 + ConnectInfo 注入 |
+| `src/db.rs` | 数据库初始化 + Schema + Admin 引导 |
+| `src/state.rs` | AppState (DB + Config) |
+| `src/config.rs` | 配置结构体 |
+| `src/error.rs` | SaasError 枚举 + IntoResponse |
+| `src/middleware.rs` | 速率限制中间件 |
+| `src/auth/mod.rs` | JWT + API Token 中间件 + 路由 |
+| `src/auth/handlers.rs` | 登录/注册/刷新/me/密码 (含 TOTP 登录验证) |
+| `src/auth/totp.rs` | TOTP 2FA (setup/verify/disable) |
+| `src/auth/types.rs` | AuthContext + Request/Response 类型 |
+| `src/account/handlers.rs` | 账号 CRUD + Dashboard + 设备 |
+| `src/model_config/handlers.rs` | Provider/Model/Key CRUD |
+| `src/relay/handlers.rs` + `service.rs` | SSE 中转 + 任务管理 + 指数退避重试 |
+| `src/migration/handlers.rs` + `service.rs` | 配置 CRUD + 同步 |
+
+### Admin (admin/)
+| 文件 | 职责 |
+|------|------|
+| `src/lib/api-client.ts` | 类型化 HTTP 客户端 |
+| `src/lib/auth.ts` | JWT 管理 |
+| `src/app/(dashboard)/` | 10 个 CRUD 页面 |
+
+### 桌面端 (desktop/src/)
+| 文件 | 职责 |
+|------|------|
+| `lib/saas-client.ts` | SaaS HTTP 客户端 (重试 + 离线检测) |
+| `store/saasStore.ts` | SaaS 状态 (登录/设备/心跳) |
+| `components/SaaS/SaaSLogin.tsx` | 登录/注册 UI |
+| `components/SaaS/SaaSStatus.tsx` | 连接状态 + 可用模型 |
+| `components/SaaS/SaaSSettings.tsx` | 设置页 (密码/迁移) |
+| `components/SaaS/ConfigMigrationWizard.tsx` | 3 步配置迁移向导 |