| 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 质量自检
接力
架构设计完成，输出 docs/arch-decision.md + docs/security-baseline.md + docs/traceability-matrix.md 后：
→ 通知 Orchestrator 推进到 CEO_REVIEW（CEO/创始人视角审视）→ 然后 DESIGN_PHASE
