# System Design Review — TVU 设计系统「元层合理性」审计

> **性质**：审整个设计系统的**流程 / 规则 / 逻辑 / 引用方式 / 场景覆盖**是否合理 —— **不是** code-review（不找代码 bug）。
> **用法**：新 session，模型 **Opus 4.8 + High**（不需要 Extra High，见 §4）。起手粘：
> `按 docs/internal/_prompts/system-design-review.prompt.md 执行`
> **产出后 STOP，不直接改任何东西** —— review 与 fix 分离，改不改由 owner 拍板。

---

## 0. 起手（mandatory）

1. 跑 STATUS §起手必读链路 两层 onboarding（L-core 全读：FIGMA_SOT → STATUS → PROJECT_GOAL → pickup[本类 review 无对应可跳]；L-ref 本任务必中：AGENTS §硬规则表+Gate、tracker §排期原则、meta-rules 反模式清单）。
2. **把 onboarding 本身当第一个审计对象**：起手必读链路是否真能让一个全新 AI/人走通？哪一步卡？哪份文档过期/断链/循环引用？卡点直接记成 finding（这是"流程是否合理"的实测，不是凭空判断）。
3. 全程纪律：**先读真源再判断**（deterministic 证据，禁启发式臆断）；Figma-as-truth 原则照旧；每个 finding 必带 `文件:行` 证据。

---

## 1. 模型 + 并行策略（owner 已定：High + Workflow，不切 Extra High）

- **默认档 = High**。这个 review 的瓶颈是「广度 + 判断 + 交叉引用」，不是「推理深度」，High 足够。
- **维度审计用 Workflow 并行**（owner 已授权 workflow）：把 §2 的各维度 fan-out 给独立 reader agent（每维一路，子 agent 用 High Opus 即可，**不需 per-agent Extra High**）→ 各自产结构化 map → 汇总去重 → 对抗性复核。
  - 这是 owner 显式 opt-in 的 workflow 授权；按需 `Workflow` 工具 fan-out。
- **验证友好型硬点**（误报边界数学 / SoT 循环依赖 / gate 互锁逻辑）→ 用**对抗 verify panel**：N 个 agent 各自**造反例去打破结论**，幸存才算数。对这类问题，3 个 High agent 对抗 > 1 个 Extra High 单跑（单跑再深也是一个视角，易自洽地错）。

---

## 2. 审计维度（每块先读真源 → 判断 → finding）

### 维度 A · 流程 flows
onboarding gate / `sync:figma-library` 14-step / mockup 工作流(Path A) / 代码工作流(Path B) / release+changeset / 消费 setup(setup-tvu-consumer)。
**问**：步骤是否冗余 / 有死步（如曾经的 library-origin 从不跑）/ 能否被静默绕过 / 中断与并行 session 下是否安全。

### 维度 B · 规则 rules
AGENTS 硬规则 / meta-rules 触发器 / code-conventions R-rules / mockup-conventions M-rules / FIGMA_AS_SOURCE_OF_TRUTH。
**问**：规则是「被强制（有 audit/lint/gate）」还是「只写文档没人跑」？有无互相矛盾 / 重复 / 过期 / 适用边界不清？
> ⭐ **重点盲点 #1（最高优先）——「文档化 ≠ 强制化」**：本 session 实证系统病灶（eslint config 存在但不接线、library-origin audit 无 npm script）。逐条 R/M 规则对照"有无对应机械 gate"，列出"只文档无强制"的规则清单。

### 维度 C · 逻辑 logic
canonical vs base 双层 / translation divergences / audit gates 分层（pre-commit / prepublish / sprint self-audit D-J / CI）。
**问**：分层是否清晰、职责不重叠？gate 覆盖有无洞？audit 之间有无矛盾（如 figma-vs-canonical 说"全 mapped"但 render-coverage 说"缺 mapping" —— 2026-06-10 已遇并 whitelist 解，查同类）。

### 维度 D · 引用 / SoT 关系（重点盲点 #2）
STATUS(镜像) vs tracker(排期真源) vs memory(AI 缓存) vs 代码 vs translation 层。
**问**：是否真单一真源还是已分叉漂移（CLAUDE.md 自记版本号曾冻结 7 版）？文档交叉引用有无断链 / 循环 / 过期？memory 与仓库真源有无冲突？

### 维度 E · 场景覆盖（核心 —— 见 §3 场景矩阵）
对照 §3 每个使用场景，查"该场景是否被流程/规则/gate 覆盖且强制"。

### 维度 F · 合理性总评
哪些是历史包袱可精简、哪些缺失该补、哪些过度工程（rule/audit 多到没人遵守也是反模式）。

---

## 3. 场景覆盖矩阵（逐场景查 = 覆盖? + 强制?）

> review 对每个场景回答两问：**(1) 系统有没有覆盖它的流程/规则？(2) 覆盖是被强制还是只是文档建议？**

### 高频核心
- AI 做 mockup（文字/PRD/截图 → Figma，Path A / M-rules）
- AI 写产品代码（Figma/截图/文字 → Vue，Path B / R-rules）
- 改既有 mockup / clone 迭代（M46）
- 同步 Figma 库（sync:figma-library 14-step）
- canonical 保真度修正（fidelity audit + render-verification）
- 跨 session 续跑（onboarding gate + pickup/handoff）

### 系统契约（PROJECT_GOAL 5 能力）
- 能力1 开发 npm 消费（文档站 + import + 类型 + tree-shaking）
- 能力2 Figma URL → code 1:1（canonical SoT + 硬规则#6 + 确定性还原验证）
- **能力3 code → Figma 效果图** ⭐ **owner 保留为真实场景**：不是"确认 deferred 合理"，而是**实审 bypass 路径是否真可用 / 有文档 / 能产出**，还是名存实亡。`CAPABILITY_3_BYPASS.md` 实际可操作吗？
- 能力4 多模态（文字/链接/**截图**/代码任一组合 → mockup + code）：查"截图输入""任意组合"是否真覆盖，还是只测过文字
- 能力5 溯源（figma-to-code-mapping 双向；code→Figma 反查是否真能用）
- 消费产品接入 + enforcement（setup + eslint/audit，2026-06-10 G1-G4 刚补，查场景感知是否到位）
- release / 版本迁移（changesets + CI + migration guide + Packages 实物验证）

### 重点盲点（健壮性 / 延展性，按优先级深审 → 轻量）
1. ⭐ **文档化 ≠ 强制化**（见维度 B；最高优先）
2. ⭐ **SoT 漂移**（见维度 D）
3. ⭐ **非开发受众覆盖**：PROJECT_GOAL 承诺设计(Design Spec/变体网格) / QA(Status Matrix: hover/disabled/error/empty/loading 全态) / 产品(Use Cases/何时用哪个) —— 文档站是否每个组件都有这三类视图，还是只做了开发视角？（延展性：缺则每个新组件复制缺口）
4. ⭐ **组件状态完整性**：空 / 加载 / 错误 / 边界（超长文本、0 数据）—— 系统性覆盖还是逐组件随缘？（健壮性：缺态=下游真 bug）
5. **降级 / 无 Figma token 场景**：大量 audit 依赖 token / 预取数据，无 token 时静默跳过还是明确报告（G4 已让 mockup-conformance 报 ERROR 非静默 pass，查同类）
6. **a11y / 主题 / i18n**（验证现有 gate 是否系统性全覆盖，非新建）：键盘+ARIA+contrast / dark·light toggle 全页正确 / EN·ZH（R16）
7. **错误恢复 / 中断安全 / 并行 session**（窄范围）：pipeline 中途失败、owner 多 session 并行的 dirty 文件/stash 冲突

---

## 4. DEPTH-FLAG 约束（硬推理子问题处理）

> reasoning effort 是 owner 的旋钮，模型不能自我提升。所以遇到把握不足的硬点，**标记 + 暂停**，不要默默 best-effort 蒙过去。

遇到任何**把握 < 90% 的硬推理子问题**（误报边界数学 / SoT 循环依赖 / gate 逻辑互锁等）：
- 打 `⚠️ DEPTH-FLAG` 标记，单列出来；
- 写清"难在哪 / 当前 High 档下我的初判 / 不确定点";
- **STOP 该子项**，等 owner 决定：(a) owner 开 Extra High + 让你重做这一项，或 (b) 起 workflow 对抗 verify panel 解它；
- **绝不用"看起来合理"的推断填这种洞**（违反 deterministic 纪律）。

---

## 5. 产出

写 `docs/internal/_reports/system-review-<YYYY-MM-DD>.md`：
- 每个 finding：`P0 / P1 / P2` + 证据 `文件:行` + 具体建议（精简/补强/重构/接 gate）；
- 维度 F 给一段总评（系统当前健康度 + top 3 该动的）；
- `⚠️ DEPTH-FLAG` 子项单列等 owner 拍板；
- **先给报告，STOP，不改任何代码/文档/配置**。