arch-review

Arch Review — 完整执行流程

前置：可行性快速扫描

在做任何设计之前，先扫描 PRD 中所有技术需求：

评级	说明
✅ 可行	标准方案，团队能力范围内
⚠️ 有条件可行	可行，但需要特定假设或额外工作
❌ 不可行	在合理约束内无法实现

发现 ❌：立即打回 PM，不继续架构设计。

---

图表 A：系统架构图

复制此模板，填入实际组件：

┌──────────────────────────────────────────────────────────────┐
│                         Client Layer                          │
│  ┌──────────────────────┐   ┌──────────────────────┐        │
│  │   Server Components  │   │   Client Components  │        │
│  │   (Next.js RSC)      │   │   (React + Zustand)  │        │
│  └──────────┬───────────┘   └──────────┬───────────┘        │
└─────────────┼──────────────────────────┼────────────────────┘
              │ tRPC / Server Actions    │ tRPC
              ▼                          ▼
┌──────────────────────────────────────────────────────────────┐
│                        API Layer (Hono/Bun)                   │
│  ┌────────────┐  ┌────────────┐  ┌────────────────────────┐ │
│  │   better-  │  │   Rate     │  │   Zod Validation       │ │
│  │   auth     │  │   Limit    │  │                        │ │
│  └──────┬─────┘  └─────┬──────┘  └────────────┬───────────┘ │
│         └──────────────┼──────────────────────┘             │
│                        ▼                                      │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              Business Logic / Routers                  │   │
│  └──────────────────────────────────┬─────────────────────┘  │
└──────────────────────────────────────┼────────────────────────┘
                                        │
          ┌─────────────────────────────┼─────────────────┐
          ▼                             ▼                  ▼
   ┌─────────────┐            ┌──────────────┐   ┌──────────────┐
   │  PostgreSQL │            │    Redis      │   │  External    │
   │  (Drizzle)  │            │  (BullMQ)    │   │  APIs        │
   └─────────────┘            └──────────────┘   └──────────────┘

填写要求：替换组件、标注协议、标注存储、列出所有第三方集成点。

---

图表 B：状态机

{业务对象} 状态机：

               ┌──────────────────┐
               │  INITIAL_STATE   │
               └─────────┬────────┘
                          │ {转换条件}
           ┌──────────────┼──────────────┐
           ▼              ▼              ▼
  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
  │  STATE_A     │ │  STATE_B     │ │  TERMINAL    │
  └──────┬───────┘ └──────┬───────┘ │  (终态)      │
         │                │          └──────────────┘
         ▼                ▼
  ┌──────────────┐ ┌──────────────┐
  │  FINAL       │ │  ERROR       │
  │  (终态)      │ │  (可重试)    │
  └──────────────┘ └──────┬───────┘
                           │ 重试成功→[对应状态]

必填：所有状态（含错误态）、转换条件、终态标注、超时处理。

---

图表 C：序列图（最复杂操作）

{操作名称}：

Actor         API Server    Auth/MW    Database    External
  │               │             │           │          │
  │─{操作请求}──▶│             │           │          │
  │               │─verify─────▶│           │          │
  │               │◀─{结果}─────│           │          │
  │               │─BEGIN TXN──────────────▶│          │
  │               │─{写操作}───────────────▶│          │
  │               │─COMMIT─────────────────▶│          │
  │               │─enqueue job─────────────────────▶  │
  │◀─{响应}───────│             │           │          │

错误分支：
  ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
  │        (Auth 失败)                 │
  │◀─401──────────────────────────── │
  ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
  │        (DB 事务失败)               │
  │               │─ROLLBACK──────▶  │
  │◀─500────────────────────────────  │

必填：同步/异步标注、事务边界、至少 2 个错误分支。

---

图表 D：错误路径地图

## 错误路径地图 — {操作名}

### 正常路径
{步骤 1} → {步骤 2} → {步骤 3} → ✅

| # | 错误类型 | 发生位置 | 用户看到 | 系统状态 | 数据安全 |
|---|---------|---------|---------|---------|---------|
| E1 | 输入验证失败 | 请求接收 | 字段错误提示 | 无变化 | ✅ |
| E2 | 认证失效 | Auth MW | 跳转登录 | 无变化 | ✅ |
| E3 | DB 写入失败 | 事务中 | 通用错误+重试 | 回滚 | ✅ |
| E4 | 外部 API 超时 | 调用第三方 | "处理中，稍后查看" | 进入重试队列 | ⚠️ |

### 数据一致性说明
{如有 ⚠️，说明如何保证最终一致性}

---

技术债雷达

## 技术债登记

| 债务项 | 影响 | 接受原因 | 还清时间 | 逾期后果 |
|--------|------|---------|---------|---------|
| 缺少 E2E 测试 | 中 | MVP 阶段 | v1.2 | Bug 难发现 |
| AI 决策无持久化 | 高 | 架构复杂度 | v2.0 | 重启丢失状态 |

**总债务等级**：低 / 中 / 高

---

技术选型参考

层级	首选	不推荐	原因
运行时	Bun 1.x	Node.js	性能 3-4x
后端框架	Hono	Express	无类型
ORM	Drizzle	Prisma	需 generate 步骤
数据库	PostgreSQL 16+	MySQL	JSON 支持弱
前端	Next.js 15	Vite SPA	无 SSR
组件库	shadcn/ui	MUI	黑盒，包体大
接口	tRPC v11	REST+OpenAPI	维护成本高
认证	better-auth	NextAuth v4	类型弱
验证	Zod v4	Joi	无 TS 推断
Lint	Biome	ESLint+Prettier	慢，两套配置

---

安全基线模板 docs/security-baseline.md

# 安全基线 — {项目名}
建立时间：{date}

## 认证方案
- 实现：better-auth
- Token 存储：HttpOnly Cookie（严禁 localStorage）
- 有效期：访问 Token 15 分钟，Refresh Token 7 天，自动轮换

## API 端点权限表
| 端点 | Method | 权限 | 说明 |
|------|--------|------|------|
| /api/auth/* | * | 公开 | better-auth 内置 |
| /api/{resource} | GET | user | 只返回自己的数据 |
| /api/{resource}/:id | DELETE | user + owner | 需验证所有权 |
| /api/admin/* | * | admin | 需 role = admin |

## 数据分类
| 数据 | 分类 | 保护方式 |
|------|------|---------|
| 密码 | 机密 | Argon2id 哈希 |
| 邮箱 | PII | 日志脱敏 |
| 业务数据 | 一般 | 标准访问控制 |

## FE/BE 硬性约束（违反 = Code Review FAIL）

FE：
- [ ] 禁止 localStorage / sessionStorage 存 Token
- [ ] 禁止 URL 参数传递敏感信息

BE：
- [ ] 禁止日志中打印密码、完整 JWT
- [ ] 禁止原始 SQL 字符串拼接
- [ ] 需登录的路由第一行必须 session 验证
- [ ] 资源操作必须验证所有权
- [ ] 所有 API 入参通过 Zod 验证

## 速率限制
| 端点类型 | 限制 |
|---------|------|
| 认证端点 | 10次/分钟/IP |
| 普通 API | 100次/分钟/用户 |

---

ADR 质量自检

• 可行性扫描完成，无 ❌（或已打回 PM）
• 图表 A：系统架构图完整，含存储层
• 图表 B：状态机，含终态和超时处理
• 图表 C：序列图，含事务边界和错误分支
• 图表 D：错误路径地图，含数据一致性分析
• 技术选型：每个有放弃方案及理由
• 数据模型草图：核心实体和关系
• API 契约：tRPC 路由或 REST 端点全列
• 技术债雷达：诚实登记
• 安全基线：docs/security-baseline.md 已输出
• 风险矩阵：至少 3 条

---

接力

架构设计完成，输出 docs/arch-decision.md + docs/security-baseline.md + docs/traceability-matrix.md 后： → 通知 Orchestrator 推进到 CEO_REVIEW（CEO/创始人视角审视）→ 然后 DESIGN_PHASE