# Phase 0 Ledger

记录每次执行 Phase 0 mapping 的指标。**Append-only**——只追加，不修改既有 entry。

## 维护规则

- 由执行 Phase 0 的 AI session **wrap-up 时**追加一行（[`code-conventions.md`](../code-conventions.md) R5 §7 强制）
- Trivial 任务（element < 3，按 R0 / M0 跳过 Phase 0）不 append
- Pre-Phase 0 后才进 Phase 0 的任务，按 Phase 0 一行 append（Pre-Phase 0 自身不单独 append）
- US-4（Figma frame → code mirror）走了 Phase 0 → 同样 append

## 列说明

| 列 | 含义 |
|---|---|
| 日期 | 任务完成日期 (YYYY-MM-DD) |
| 产品 | 消费 TVU 库的产品名 (如 `MicroApps Console`) |
| 类型 | `code` / `mockup` |
| 任务简述 | 1 句话 |
| Element 数 | Phase 0 mapping table 行数 |
| 🟡 命中 | catalog 命中 🟡 skeleton 状态的 element 数 |
| 🟡→✅ 升级 | 本任务实证后回填 [`figma-component-catalog.md`](../figma-component-catalog.md) 升级 ✅ verified 的数量 |
| ⚠️ 真 gap | catalog + Figma MCP 双层都 miss、最终自画的 element 数 |
| 备注 | 1-2 句关键发现 / 异常 |

## 异常启发式（AI 在每次 session 起手扫末 5 行后主动提醒）

| 异常 | 暗示 |
|---|---|
| **表完全空（0 行 entry）** | **首次使用，不报警**——AI 仅提示 "Ledger 完全空，本次会是首条 entry" |
| 末 5 条 `🟡→✅ 升级` 全是 0 | Phase 0 可能没系统性查 catalog，只走形式 |
| 末 5 条 `Element 数` 全 < 3 | 都触发了 trivial 跳过，Phase 0 没真跑过 |
| 最近 entry > 60 天前（且非空表） | ledger 失修，可能 wrap-up 没在 append |
| `⚠️ 真 gap` 占比 > 30% | 自画门槛松了或 Figma library 有真覆盖空洞，需 sync 提速 |

提醒话术示例：

> "扫了一下 ledger 末 5 条，🟡→✅ 升级都是 0——可能上几次 Phase 0 没真去 grep catalog。本次我会把 grep query 都打印出来给你看。"

## Entry log

| 日期 | 产品 | 类型 | 任务简述 | Element 数 | 🟡 命中 | 🟡→✅ 升级 | ⚠️ 真 gap | 备注 |
|---|---|---|---|---|---|---|---|---|
| 2026-05-11 | TVU SaaS Dashboard (Usage Service) | mockup | US-3 增量：新建 Cost per Token Trend dashboard page，build Option 2 (hero margin chip) + Option 3 (subtitle business summary) 留 PM Review；含 sidebar 注释面板 + connector sharedPluginData registry 模式 | ~12 | 1 (Compare Item/YTD file-local 实证) | 0 | 1 (chart vector ad-hoc — chart primitives 不在 library scope) | Triple rule birth session: M21 + R6（增量优先复用 local）+ M22（user design ask Pre-Phase 0 gate）；规则 self-test 失败实证（立完 M21 当天违 sibling 视觉合同）；annotation-connector registry 模式可复用。详 retrospect 2 篇：trifecta-rule-update + saas-dashboard-2-option-pm-review |
| 2026-05-14 | MicroApps Console | mockup | US-3 增量：Plan B Figma 完整交付 — 5 frames (1920) + 8 新 file-local 组件 (PlanB 前缀) + 9 M23 navy bilingual annotations；Plan A 视觉合同 mirror (Card #1f1f1f / Counter Pill / line-deep stroke) | ~22 | 5 (Counter Pill / State Pill / Action Cluster × 3 / APP Icons — Plan A file-local 实证 verified) | 1 (TVU library `Pagination` 经 search_design_system 找到并替换 file-local `MicroApp PlanB Pagination` → 后者已删) | 4 (library 缺：bg-layer2 hex token / brand-bg-18 alpha token / left-chevron icon / empty-tray + pause icon) + 1 (Top bar 默认 Right_content 无通知铃铛) | Q2 (M18) + Q3 (M19) 完整应用；实证嵌套 instance `paint.opacity` 失效新 edge case → solution: child Rectangle + `node.opacity` 替代 paint.opacity（可传嵌套 instance）；建议回流 figma-technical-reference.md 新增 Q-rule。Handoff: `MicroApps Console/docs/2026-05-14-plan-b-figma-handoff.md` |
| 2026-05-14 | MicroApps Console | mockup | US-3 retrofit：Plan B Figma M23 完整化收尾 — 拆 3 个 row 容器、9 annotations 重排到 frame 列下方对应位置（F1 列 5 个：#2/#6/#9/#1/#4；F2 列：#7；F3 列：#5；F5+F6 跨：#8；#3 在 F1/F2 间）；建 18 VECTOR connectors（手画 arrowhead per Q6）；建 2 state-group GROUPs `_flow-state-1/2` for #4 Sidebar Collapse + 1 内部转换箭头 + condition label；建 3 condition label GROUPs `_` for #5 三种 scope；写 reconnect map JSON (9363 bytes) 到 page sharedPluginData ns=`ux_annotation` key=`plan_b_reconnect_map` | 0 (无新 element mapping，纯 retrofit) | 0 | 0 | 0 | 验收：18 connectors + 6 GROUPs + 6 ZH ranges 全部 Noto Sans SC@9px opacity≈0.45 + Roboto Medium@11px@#33A4FD ✓。所有 connector 严格在 Plan B section 内部。前一 session "M23 connectors 缺失" 缺口闭环。Pickup: `MicroApps Console/docs/2026-05-14-plan-b-figma-connectors-pickup.md` |
| 2026-05-14 | MicroApps Console | mockup | **Layout refactor v2** ("annotation 贴效果图" 用户反馈)：上一 retrofit 用横向 1 行 6 frames（13332 wide）造成 connectors 全是穿越整个 section 的长对角线。重构为**纵向 stack**：6 frames 全部纵向排列在左栏 (sec x=40)，9 annotations 全部在右栏 (sec x=2080) 紧贴对应 frame y。Section 从 13332×5417 改为 3280×9806。Connectors 全部短水平 / L 形（vertical-first L 用于跨行：垂直段走右栏 margin、水平段进入 target frame）。删 #3→F1 + #5→F1 长跨行 + orphan cond-#5-F1，14 VECTORs + 3 cond labels + 2 state groups。Reconnect map v2 (9634 bytes) 写入 page sharedPluginData | 0 | 0 | 0 | 0 | 新增工程经验：**M23 layout 约定 — annotation 模块必须放效果图旁边、用短水平 / 折线（vertical-first L 适合跨 frame 行）连接、严禁长对角穿越 section**。建议回流到 mockup-conventions M23 章节 "layout 选择" 子段。验收：14 connectors stroke #33A4FD 2px ✓ + 跨行 L 形垂直段走 sec x=2080 右栏 margin (annotation 左缘) 不穿越 frame 内容 ✓。Pickup: `MicroApps Console/docs/2026-05-14-plan-b-figma-connectors-pickup.md` |
| 2026-05-14 | MicroApps Console | mockup | **Layout refactor v3** ("Plan A 横向流程 / 检查 overlap" 用户反馈)：v2 纵向 stack 错了方向 + 拉到 y=18195 压到 sibling section "MicroApps PlanB — Local Components" (y=15463-17663) — **double-bug session-end check 没做**。重构为 **Plan A 风格 horizontal pair**：3 rows × 2 cols 按 view 配对（Row1 Overview=F1 Admin+F3 User / Row2 AppDetail=F2+F4 / Row3 Empty=F6+F5），annotations 在 frames **上下左右**（参考 Plan A）：#1 header 左上 / #2 #6 #9 ABOVE F1 / #4 + state group LEFT of F1 / #3 #5 BETWEEN F1↔F3 / #7 BETWEEN F2↔F4 / #8 BETWEEN F6↔F5。Section 6080×5340，与 PlanB Local Components gap 1734 px ✓。14 VECTORs + 2 state groups + 3 cond labels (rebuilt) + reconnect map v3 (8090 bytes) | 0 | 0 | 0 | 0 | **2 个 layout 经验同源**：(1) **Plan A 是 source of truth** 用户 Plan B 跟 Plan A 一致是核心需求 — 设计 layout 前必须先 probe Plan A；(2) **session-end 必须 probe 所有 sibling sections 检查 overlap** — section.resize 后 bounds 变化可能压到邻居。**建议回流**：mockup-conventions M23 "layout 选择" 子段 + 起手协议加 "若产品已有 sibling Plan/version section，必先 probe 其 layout 风格当 source of truth" + wrap-up 协议加 "section.resize 后 mandatory probe sibling sections overlap"。Pickup: `MicroApps Console/docs/2026-05-14-plan-b-figma-connectors-pickup.md` |
| 2026-05-14 | MicroApps Console | mockup | **F1 Walkthrough audit via subagent + v3.1 + v4 闭环** (用户提出 "design 后需 dev/QA 视角自检走查 / 推荐 skill")：发现 `tvu-design-mockup` skill **完全没含 pre/post-design gate**。Dispatch subagent (Sonnet) 跑 `design-walkthrough` skill 做 F1 6-section audit (72K tokens, $0.22) — 抓出 5 个 P0/P1 (3 个被 self-review 漏)：empty states ~43% PRD 覆盖 / App Picker mid-state 缺 / A11y 缺 / Action Cluster matrix 缺 / M25 hover silent-reverted。**用户进一步抓 connector flow 问题**——v3 有 3 个 connector tip 错位 (#6 偏 58px / #8 偏 68-89px) + #5 两条横段穿 F3/F4 frame 内容。**v3.1 修复**：3 tip 重对位 + #5 改用 U-3seg routing 绕开 frame；并 verify Q7 M25 hover paint.opacity 跨 context 持久 (0.10 ✓)。**v4 补图**：Row 4 加 6 个 variant-state mini-frames (Empty B/C/D instance 现成 variants + Loading skeleton + Sort-active + App Picker dropdown) 闭环 P0-1 + P0-2。Section 6090×6050，gap 1024 to Local Components ✓ | 0 | 0 | 0 | 0 | **3 条 process gap 实证 + 建议回流**：(1) **subagent F1 audit ROI 极高** ($0.22 抓 5 P0/P1)，建议 `tvu-design-mockup` skill 协议加 step 8.5 mandatory post-design audit via subagent；(2) **design-walkthrough skill 6-section checklist 漏 "Connector tip accuracy" 第 7 section** — 即"每条 declared connector tip 实际是否落 target element bbox 内 (容差 AH)"，本次靠用户抓出；(3) **wrap-up 协议加 sibling section overlap probe**（v2 → v3 因此犯错）。详 audit report: `MicroApps Console/docs/audits/2026-05-14-plan-b-f1-walkthrough.md` |
| 2026-05-14 | MicroApps Console | mockup | **M2 Library-first audit + V1-V5 修复** (用户抓 5 处 M2 违例 + 1 处 stale handoff debt)：(V1) Sidebar count badge × 12 处手画 Frame+TEXT → TVU `Badge` (key `4db5246d...`) instance；**架构教训**：第一版把 Badge 嵌入 19×15 旧 Frame → 视觉撑爆，redo 删 Frame 让 Badge 作 row 子节点直接替代槽位。(V2) App Picker 8 placeholder rect → file-local `APP Icons` (3:14402) Green variants instance。(V3) TEXT "↑" → TVU `icon/Arrow/Sorting` (key `36c09416...`) instance。(V4→V5) 6 处 Unicode `‹/›` TEXT chevron → V4 误用 `icon/Arrow/Left/Right` (大箭头语义) → V5 改 `icon/Arrow/Previous/Next` (小 chevron 正确语义)；并修 breadcrumb auto-layout bug (`parent.appendChild` 把 icon 排到 horizontal layout 末尾 — 改用 `insertChild(0, ...)`)。(staleDebt) BRIDGE-MOCKUP-003 stale claim "chevron 未发布" → search_design_system 实际有 → handoff doc void + M15.1 新规则 (handoff debt 必 re-verify) | 0 | 0 | 0 | 0 | **4 条 process gap 实证 + 已回流**：(1) **M0 scope clarification** (mockup-conventions.md): variant state minis / state group 内嵌 UI / annotation 内嵌 UI 全不算 trivial，必须做 M0 mapping (Row 4 mini-frames 跳 M0 是 V1-V4 的根因)。(2) **M15.1 (design-process.md)**: 继承前 session handoff doc "library debt" claim 必须 re-verify search_design_system — stale claim 在 session 间传递会变接受的事实。(3) **Auto-layout child positioning bug**: HORIZONTAL auto-layout 用 `appendChild` 排末尾，必须 `insertChild(index)` 显式指定位置。这是 figma-technical-reference 候选新 Q-rule。(4) **Icon 语义先 swap menu 看命名再选**: Left/Right (大箭头, back/return 语义) ≠ Previous/Next (小 chevron, navigation 语义) — 工程师 vs 设计师术语对齐 |
| 2026-05-14 | MicroApps Console | mockup | **Session-end 完整回流批次** (用户最终指令："session 中出现的问题，总结出规则，回流到 TVU 设计规范")：基于本 session 完整问题清单 — 与已有规范交叉对照后只回流**新规则不重复**。Copy icon table cell pattern (text hug content + `icon/Edit/Copy` 紧跟 + Icon/Default 色绑定) + empty placeholder ("—" 不可复制，用 Text/Placeholder & Button 色) + center-ellipsis truncation spec | 0 | 0 | 0 | 0 | **5 条新规则全部 committed**：(1) **Q8** (`figma-technical-reference.md`) — HORIZONTAL auto-layout 子节点必用 `insertChild(index, n)` 而非 `appendChild`（appendChild 排末尾被 auto-layout 接管，x/y 无效）。(2) **M27** (`mockup-conventions.md`) — Sibling Plan/Version Layout Consistency：同 page 多 plan/version section 时，新 section 必 mirror sibling layout 风格（横/纵 / pair 方式 / annotation 位置 / connector 形态 / 长宽比 5 维度）。违例 history: Plan B v1-v3 三轮 retrofit。(3) **M28** (`mockup-conventions.md`) — Sibling Section Overlap Probe：section.resize 后 mandatory probe 所有 page 上其他 SECTION 检查无 bounds 重叠，handoff doc 必含 gap 数。违例 history: Plan B v2 压 PlanB Local Components 2200px。(4) **M29** (`mockup-conventions.md`) — Table Cell Content Pattern：Copyable (text hug + `icon/Edit/Copy` 紧贴 + Icon/Default 绑定) vs Empty Placeholder ("—" 不加 icon + Text/Placeholder & Button 色)，自动检测 text.characters.trim() ∈ {"—","-","–"} 走 Form 2。center-ellipsis dev-side。(5) **M23.6** (`mockup-conventions.md`, M23 extension) — Connector Tip Accuracy + Frame Content Avoidance：tip 必落 target bbox 容差 ≤ AH (8px)；中间路径不穿 frame 内 UI 内容（horizontal-first / vertical-first / U-3seg 决策树）；reconnect map 必含 `tipCanvas: {x, y}` 字段供 audit。违例 history: Plan B v3 #6/#8 tip 偏 58-89px + #5 横段穿 F3/F4。(6) **M14.1** (`design-process.md`, M14 extension) — Icon 按 use-case 语义选不按 name 字面匹配：Arrow namespace 内 Left/Right (back/return 大箭头) ≠ Previous/Next (navigation 小 chevron) ≠ Sorting/Dropdown/Double up 等，看 Figma swap menu 命名 + import sample 视觉双 verify。违例 history: V4 用 Left 当 chevron 错 6 处 → V5 改 Previous |