# zclaw-saas 架构重构完成记录

> 记录时间: 2026-03-29
> 本文档记录借鉴 loco-rs 模式对 zclaw-saas 后端进行的架构重构和性能优化。

## 重构概要

### Phase 0: 知识库
- `docs/knowledge-base/loco-rs-patterns.md` — loco-rs 10 个可借鉴模式研究

### Phase 1: 数据层重构
- `crates/zclaw-saas/src/models/` — 15 个 `#[derive(sqlx::FromRow)]` 类型化模型文件
  - 替代了所有 `(String, String, ...)` 元组解构
  - 编译期字段检查，消除运行时字段错位风险
- 3 次登录查询合并为 1 次 `AccountLoginRow` 查询
- Relay handler N+1 查询修复（精准 SQL 替代全量加载）

### Phase 2: Worker + Scheduler 系统
- `crates/zclaw-saas/src/workers/` — Worker trait + 5 个具体实现
  - `LogOperationWorker` — 异步操作日志
  - `CleanupRefreshTokensWorker` — 过期 token 清理
  - `CleanupRateLimitWorker` — 限流条目清理
  - `RecordUsageWorker` — 异步使用量记录
  - `UpdateLastUsedWorker` — API token last_used_at 更新
- `crates/zclaw-saas/src/scheduler.rs` — TOML 声明式调度器
  - 支持 `5m`/`1h`/`24h` 时间间隔格式
  - 从配置文件加载，无需改代码调整调度
- `crates/zclaw-saas/src/tasks/` — CLI 任务系统

### Phase 3: 性能修复
| 问题 | 修复 | 文件 |
|------|------|------|
| Relay N+1 查询 | 精准 SQL 替代 `list_models()` 全量加载 | `relay/handlers.rs` |
| Config RwLock 竞争 | `Arc<AtomicU32>` 无锁 rate limit 读取 | `state.rs`, `middleware.rs` |
| SSE `std::sync::Mutex` | `tokio::sync::Mutex` 异步安全 | `relay/service.rs` |
| Login 3 次查询 | 合并为 1 次 `AccountLoginRow` 查询 | `auth/handlers.rs` |
| `/auth/refresh` 阻塞清理 | 迁移到 Scheduler 定期执行 | `auth/handlers.rs` |

### Phase 4: 多环境配置
- `config/saas-development.toml` — 开发环境
- `config/saas-production.toml` — 生产环境
- `config/saas-test.toml` — 测试环境
- `ZCLAW_ENV` 环境变量选择配置
- `ZCLAW_SAAS_CONFIG` 精确路径覆盖（最高优先级）

## 配置加载优先级

```
ZCLAW_SAAS_CONFIG (精确路径)
  > ZCLAW_ENV (环境选择 config/saas-{env}.toml)
    > saas-config.toml (默认)
```

## Scheduler 配置示例

```toml
[scheduler]
jobs = [
  { name = "cleanup_refresh_tokens", interval = "1h", task = "cleanup_refresh_tokens", run_on_start = false },
  { name = "cleanup_devices", interval = "24h", task = "cleanup_devices", run_on_start = true },
]
```

## 已知限制 / 待改进
- `log_operation()` 仍为同步调用（操作日志不是性能瓶颈，后续可按需迁移）
- TEXT 时间戳未迁移到 TIMESTAMPTZ（需要 SQL 迁移系统，影响范围大）
- 内联 SQL schema 未迁移到 `sqlx-cli` migrations