raisfast/docs/architecture-audit.md

# 架构审计报告

> 审计时间：2026-04-15
>
> 基于 Phase 8-14 全部完成后的代码状态。

## 1. 总体评估

**评级：中等偏上**——骨架扎实，Schema-driven 扩展能力强，但缺少生产级配套（审计、可观测性、缓存）。

### 做得好的

| 领域 | 评价 | 关键文件 |
|------|------|----------|
| 分层架构 | Handler→Service→Repository 三层清晰一致 | `src/handlers/` `src/services/` `src/repositories/` |
| Content Type 引擎 | TOML 定义即得自动建表 + CRUD API + Admin UI | `src/content_type/` |
| 多租户隔离 | `tenant_id` 贯穿 repo/service/handler 三层，`ResolvedTenant` 中间件统一解析 | `src/db/tenant.rs` `src/middleware/tenant.rs` |
| 插件系统 | WASM/JS/Lua 三引擎，HookPoint 泛化，VFS 隔离 | `src/plugins/` |
| 错误处理 | 统一 `AppError` 枚举 + i18n + JSON envelope | `src/errors/app_error.rs` |
| 输入校验 | `validator` crate + DTO 层一致调用 `validation::validate()` | `src/handlers/dto.rs` `src/errors/validation.rs` |
| 事件驱动 | EventBus + Worker + Cron 完整闭环 | `src/eventbus/` `src/worker/` |
| RBAC | 细粒度权限矩阵，条件权限（`author_id == $user.id`） | `src/services/rbac.rs` `src/middleware/permission.rs` |

### 成为复杂系统的关键短板

| 短板 | 严重度 | 说明 |
|------|--------|------|
| 审计日志 | **高** | EventBus 有事件但无持久化订阅者，admin 操作无 "谁做了什么" 记录 |
| 可观测性 | **高** | 无 `#[instrument]`、无 metrics、无 request ID 串联 |
| 缓存层不完整 | **高** | 只有 posts 有缓存，worker 缓存失效 handler 是 stub |
| 事务覆盖 | 中 | media 删除（DB+文件）非原子，options 批量更新无事务 |
| API 版本策略 | 中 | 只有 `/api/v1`，无 v2 迁移计划 |
| Webhook 不完整 | 中 | 无订阅管理、无 HMAC 签名、无事件过滤 |
| 测试覆盖 | 中 | Options/Plugin/RBAC/Stats/Tenant Admin 无集成测试 |
| 限流策略 | 低 | 内存级，无法多实例共享，admin 无独立限流 |

---

## 2. 详细分析

### 2.1 错误处理

**状态：强——设计完善，有少量缺口**

`AppError` 枚举（`src/errors/app_error.rs:49`）有 6 个变体：`BadRequest`、`Unauthorized`、`Forbidden`、`NotFound`、`Conflict`、`Internal`，带 `#[non_exhaustive]` 防止破坏性变更。

`From<sqlx::Error>` 自动映射：`RowNotFound` → `NotFound`，唯一约束违反 → `Conflict`。

`IntoResponse` impl 将每个变体映射到 HTTP 状态码 + i18n 消息 + 结构化 JSON body。

**缺口：**

- **缺少 `TooManyRequests`（429）变体。** 限流中间件（`src/middleware/rate_limit.rs:246-259`）手动构造 JSON 响应，绕过了 `AppError` 管线和 i18n。
- **缺少 `PayloadTooLarge`（413）变体。** `RequestBodyLimitLayer` 产生默认 Axum 响应，不走 `AppError` 格式。
- **缺少 `MethodNotAllowed`（405）和 `ServiceUnavailable`（503）变体。**
- **`sqlx::Error::RowNotFound` 映射到 `NotFound("resource")`**（`src/errors/app_error.rs:227`）丢失了具体资源类型上下文。

### 2.2 事务支持

**状态：关键路径有事务，部分多步操作缺失**

已有事务的操作：

| 文件 | 行号 | 操作 |
|------|------|------|
| `src/repositories/sqlx_post.rs` | 104, 116 | Post 创建/更新 + tag 同步 |
| `src/services/auth.rs` | 316 | Refresh token 轮换（删除旧 + 插入新） |
| `src/worker/sqlite_queue.rs` | 113 | Job 出队 |
| `src/worker/scheduler.rs` | 370, 633 | Cron 清理和种子数据 |

**缺失事务但需要的场景：**

- **Media 删除**（`src/services/media.rs`）— 先删 DB 记录再删磁盘文件，两步非原子
- **Options 批量更新**（`src/services/options.rs`）— 逐条执行，无整体事务
- **Content Type 字段校验 + 写入** — 校验通过后写入，中间无事务保护

### 2.3 分页一致性

**状态：基本一致，两个端点缺少分页**

`PaginationParams`（`src/utils/pagination.rs`）统一用于 6 个列表端点：posts（公开+admin）、comments、media、users。

**不一致：**

- **`tag::list`** 和 **`category::list`** 返回 `Vec<T>` 无分页，数据量大时成为性能瓶颈
- Post 列表 handler 手动构造分页参数（`.max(1)` `.clamp()`），其他 handler 直接用 `Query(mut params)`
- `PaginatedData` 无 `total_pages` 字段或 `Link` header

### 2.4 输入校验

**状态：强——模式一致，有少量缺口**

所有接受 body 的 handler 统一调用 `validation::validate(&req)?`（`src/errors/validation.rs:42`），DTO 用 `validator` crate 注解。

**缺口：**

- Post/Comment 的 `status` 字段无枚举校验，任意字符串（如 `"hacked"`）都会被接受
- `category_id`、`tag_ids[]` 等 UUID 字段无格式校验
- Media 上传无 MIME 类型/扩展名白名单
- `RefreshRequest.refresh_token` 无 `length(min = 1)` 校验

### 2.5 可观测性

**状态：日志良好，无 metrics，无分布式追踪**

**已有：**

- `tower_http::TraceLayer` 记录请求/响应（method, URI, status, latency）
- 业务逻辑关键点有 `tracing::info!` / `tracing::error!`
- `AppError::into_response` 用 `tracing::warn!`（4xx）和 `tracing::error!`（5xx）

**缺失：**

- **无 `#[instrument]`**——全代码库 0 使用，无法 span 级关联 handler→service→repository 调用链
- **无 metrics**——无 Prometheus / OpenTelemetry，无法追踪请求率、错误率、P95/P99 延迟
- **无 request ID**——`TraceLayer` 不注入 `X-Request-ID`，无法跨服务关联
- **无 pool utilization 监控**——无法知道连接池使用率
- **日志字段不一致**——部分用格式化字符串，部分用结构化字段

### 2.6 限流

**状态：可用但有限**

`RateLimiterSet`（`src/middleware/rate_limit.rs:153`）包含 4 个命名限流器：`global`、`register`、`login`、`comment`，滑动窗口算法。

**限制：**

- **纯内存**——多实例部署时限流独立，等效于倍增限额
- **4 个限流器硬编码**——新增需改 struct + `from_config()` + 中间件函数
- **Admin 端点无独立限流**——全局 60 req/min 覆盖，持有 admin token 的攻击者可暴力请求
- **IP 提取信任 `X-Forwarded-For`**——无配置化信任代理
- **响应无 `Retry-After` / `X-RateLimit-*` header**
- **RateLimitStore trait 已定义但只有 MemoryStore 实现**

### 2.7 缓存

**状态：仅 posts 有缓存，失效 handler 是 stub**

`CacheStore` trait + `MemoryCache` 实现（`src/cache/mod.rs`）。`CachedPostRepository<P>` 装饰器（`src/repositories/cached_post.rs`）为 posts 提供读穿透缓存 + 写穿透失效，租户感知 cache key。

**缺口：**

- **`InvalidateCacheHandler` 是 stub**——`src/worker/handlers/cache.rs:35` 只有 `// TODO` 注释和日志，不实际删除缓存
- **只有 posts 有缓存**——categories、tags、users、comments、media、options 无缓存
- **Options 缓存无 TTL 刷新**——启动时加载到 HashMap，更新时写穿透，但无定期刷新机制
- **MemoryCache 无后台清理线程**——过期条目仅在 get/set 时惰性跳过
- **无 Redis 后端**——CacheStore trait 可扩展但只有内存实现

### 2.8 数据库连接管理

**状态：可用但配置最小**

`init_pool`（`src/db/connection.rs:14`）配置 `max_connections`，SQLite 设置 `journal_mode = WAL` + `foreign_keys = ON`。

**缺失：**

- 无 `min_connections` 配置
- 无 `acquire_timeout`——请求可能无限等待连接
- 无 `idle_timeout` / `max_lifetime`
- 无连接池利用率监控
- SQLite WAL 模式仅在启动时设置一次，非 per-connection
- 无数据库重连逻辑

### 2.9 测试覆盖

**状态：覆盖面广，深度中等**

| Handler | 有集成测试？ | 测试数 |
|---------|-------------|--------|
| health | 有 | 1 |
| auth | 有 | 9 |
| user | 有 | 7 |
| category | 有 | 5 |
| tag | 有 | 4 |
| post | 有 | 12 |
| comment | 有 | 8 |
| media | 有 | 4 |
| rss | 有 | 2 |
| cron | 有 | 6 |
| sse | 有 | 2 |
| tenant_e2e | 有 | 4 |
| **options** | **无** | 0 |
| **plugin** | **无** | 0 |
| **rbac** | **无** | 0 |
| **stats** | **无** | 0 |
| **tenant admin** | **部分**（仅 e2e 间接测试） | — |

单元测试总计 422 个，覆盖 content_type、plugins、search、worker 等核心模块。

**缺口：**

- Options、Plugin、RBAC、Stats、Tenant Admin CRUD 无集成测试
- 无负面/边界测试（限流溢出、并发请求等）
- 无负载/压力测试
- `src/cache/mod.rs`、`src/errors/validation.rs` 无单元测试

### 2.10 API 版本策略

**状态：单版本，无迁移策略**

所有路由嵌套在 `/api/v1`（`src/server/mod.rs:335`），无版本中间件、无 Accept header 协商、无版本感知序列化。

添加 `/api/v2` 需要复制或重构整个路由注册块（204-315 行）。无版本迁移策略文档。

### 2.11 Webhook 系统

**状态：基础出站 webhook**

`WebhookNotifyHandler`（`src/worker/handlers/webhook.rs`）通过 job queue 发起 HTTP POST，10 秒超时，非 2xx 触发重试。

**缺口：**

- 无 webhook 订阅管理 API（无法动态注册/注销 URL）
- 无 HMAC 签名（接收方无法验证真实性）
- 无事件类型过滤（无法订阅特定事件）
- 无死信队列 UI（永久失败的 webhook 无检查/重放界面）
- 无出站限流

### 2.12 审计日志

**状态：缺失——无持久化审计轨迹**

- **无 `audit_log` 表**——所有 migration 中均不存在
- **无 audit 模块**——`src/` 中无任何 audit 相关文件
- **EventBus 无持久化订阅者**——唯一订阅者转发给插件系统，不做审计持久化
- **Admin 操作无日志记录**——用户角色变更、插件启停、配置修改、租户 CRUD、RBAC 变更、Cron 调度变更均无审计记录
- **无 "谁做了什么、什么时候" 追踪**

---

## 3. 快速扩展能力评估

### 能快速扩展的

| 扩展方向 | 说明 |
|----------|------|
| 新 Content Type | 创建 TOML 文件即得自动建表 + CRUD API + Admin 页面 |
| 新插件 | 写 plugin.toml + 入口文件，自动加载 |
| 新租户 | INSERT 一行数据即生效 |
| 前端新页面 | Admin 页面复用统一 layout + API client |
| 新字段类型 | FieldType 枚举加一个变体 + 前端一个组件 |

### 扩展时会卡住的

| 场景 | 卡点 |
|------|------|
| 高并发 | 缓存不完整 + 无 Redis 后端 |
| 多实例部署 | 限流/缓存全内存不共享 |
| 安全合规 | 无审计日志 |
| 运维排查 | 无分布式追踪、无 metrics |
| API 演进 | 无版本策略 |
| 外部集成 | Webhook 无订阅管理 |

---

## 4. 改进优先级建议

| 优先级 | 改进项 | 工作量估计 | 收益 |
|--------|--------|-----------|------|
| **P0** | 审计日志（EventBus 持久化订阅者 + audit_log 表） | 2-3 天 | 安全合规必需 |
| **P0** | 可观测性（`#[instrument]` + Prometheus metrics + request ID） | 3-5 天 | 运维必需 |
| **P0** | 缓存补全（Category/Tag/Options 缓存 + InvalidateCacheHandler 实现） | 2-3 天 | 性能扩展基础 |
| **P1** | 测试补全（Options/RBAC/Stats/Plugin/Tenant 集成测试） | 3-5 天 | 质量保障 |
| **P1** | Webhook 订阅管理 API + HMAC 签名 | 2-3 天 | 外部集成能力 |
| **P2** | AppError 补全（429/413/405 变体） | 0.5 天 | 一致性 |
| **P2** | 事务补全（media 删除、options 批量、content type 校验+写入） | 1-2 天 | 数据一致性 |
| **P2** | Redis 缓存/限流后端 | 3-5 天 | 多实例部署 |
| **P2** | API 版本策略文档 + v2 路由架构 | 1-2 天 | 长期演进 |
| **P3** | 分页补全（tags/categories 加分页） | 0.5 天 | 性能 |
| **P3** | 输入校验补全（status 枚举、UUID 格式、MIME 白名单） | 1 天 | 安全 |
| **P3** | DB 连接池配置完善（acquire_timeout、min_connections） | 0.5 天 | 稳定性 |

---

## 5. 与同类系统对比

| 能力 | 本系统 | Strapi | WordPress |
|------|--------|--------|-----------|
| Schema-driven Content Type | TOML → 自动建表/API | JSON Schema → 自动建表/API | PHP 注册 → 自动建表 |
| 插件系统 | WASM/JS/Lua 三引擎沙箱 | JS 插件（无沙箱） | PHP 插件（无沙箱） |
| 多租户 | tenant_id 隔离 | 单租户（Enterprise 有） | Multisite |
| RBAC | 细粒度 + 条件权限 | 细粒度 | 基于角色 |
| 全文搜索 | Tantivy（内置） | 外部 | 外部 |
| 审计日志 | 缺失 | 有 | 有插件 |
| 可观测性 | 缺失 | 有 | 有插件 |
| API 版本 | 无 | 无 | 无 |
| Webhook | 基础出站 | 有 | 有插件 |
| 缓存 | 仅 posts | 内存 + Redis 可选 | 对象缓存 + Redis |
| Admin UI | Next.js（前后端分离） | React SPA | PHP SSR |
| 性能（RPS） | Rust 级（待压测） | Node.js 级 | PHP 级 |