arch-review

name	arch-review
description	Full ADR generation with mandatory ASCII diagrams (data flow, state machine, sequence, error paths), tech debt radar, and security baseline. Used by Architect agent after PRD approval.

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