# 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 管理后台)
                                └── PostgreSQL (数据持久化)
```

## 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| 后端 | Rust + Axum + sqlx + PostgreSQL | 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 步配置迁移向导 |