# Video Sync Multi-Session Mockup · 复盘（2026-05-19 → 05-20）

> **目的**：内部分享 — 跟 AI 用 `@TVU mockup` 做 UX 设计任务的真实过程复盘 + 高效对话建议。
> **场景**：UX 设计师 Nancy 用 Claude Code 完成 Video Sync 多 session 新功能从 PRD 到 Figma mockup 完整交付。

---

## TL;DR

- **总轮次**：~25 轮 user feedback + ~50+ use_figma calls + ~3 MB Figma 节点变化
- **最终交付**：1 PRD section + 1 Plan A section (4 frames + Design Rules 11 条) + 1 Plan B section (Switch alt) + 1 partial v8 frame，全 TVU library 合规
- **核心 process gap 数**：~13 条新规则回流到 TVU 设计真源（M36-M40 + Q9-Q12 + R17-R19）
- **关键 insight**：**架构决策一旦错，后续每一轮都返工成本累积**。前 3 轮内确认对象 cardinality + 状态模型，能避开 60% 的返工。

---

## 1. Session 概览

### 任务起点

UX 需求：bein sports 客户希望 Video Sync 界面内直接看到多 session 运行状态 + 实时差值，避免切到 PP 端查 slot delay。基于现有 Plan B 单 session 设计，新增多 session 支持。

### 最终落地

**Figma**（fileKey `DtZcMkhNy6qh6jbQQnhreQ`，page `4083:8424`）：
- PRD spec section（5 卡片双语）
- Plan A mockup section（4 frames + 1 在做 + 双语 Design Rules card 11 条）
- Plan B mockup section（Switch alternative，独立 section）

**Process artifacts**：
- 1 个 handoff doc（v0 → v3.2 全版本变更履历）
- 1 个 next-session pickup doc
- 13+ 条新规则回流到 tvu-design-system 真源（mockup-conventions / code-conventions / figma-technical-reference）
- ~10 条 phase0-ledger entries 记录每轮变更 + 实证

---

## 2. 时间线 / 主要迭代（按用户 feedback 顺序）

| # | 版本 | 用户 feedback 触发 | 改动量 |
|---|---|---|---|
| 1 | v0 spec | 把 OQ 推荐放 PRD 里 | 删 OQ 卡片 + 推荐落到 mockup decisions |
| 2 | v0 mockup | "你这个是按 TVU 设计规范来吗？"| 暴露 v0 全 file-local 非合规 |
| 3 | v1 → v2 | 重做用 TVU library 实例 + 调色板对齐 | 19 个 library instance + 全 hex 对齐 dark palette |
| 4 | v2 | "没参考 Micro Apps 通用布局规则"+ 给 Standard Conversion 参考图 | 写 §5.5 LEFT/RIGHT 硬规则 + 删 sub-header + PP 上提到页面级 |
| 5 | v3 | "状态只有 2 个不是 5 个" | 5-state → 2-state ON/OFF |
| 6 | v3.1 | "Parameters 应该 per-session"| RIGHT panel header session 名 BRAND 绑定 |
| 7 | v3.2 | "之前的任务没看到"| OFF rows meta 加历史时间段 |
| 8 | v3.2 | "Section 没包住 frames"| Section auto-fit (Q9 新规则) |
| 9 | v4 | 7 项 batch feedback（LEFT/RIGHT 高度 / selected = BRAND / Sync 按钮 / OFF state 帧 / 字体 grid / 间距 / 连线）| 一轮做全 + Figma 200+ 节点改动 |
| 10 | v4.1 | "Switch 作 Plan B 演示"| 加 Plan B Switch frame |
| 11 | v5 | "Page state label 不需要 / 规则归属分类"| 删 label + 写规则归属 taxonomy |
| 12 | v5.1 | 8 项细化（适用范围 / Code mirror / 重复模块抽组件 / 参考图分析 / PRD e.g.）| 5 条新规则 + 双写到 code-conventions |
| 13 | v6 | "ON/OFF 还是太像按钮"+ 给 State Pill 参考图 | Badge → MicroApps file-local State Pill |
| 14 | v6.1 | "rules card 标题缺中文 / Slot > Ch 二级菜单 / 同步用 Synced 图标"| 11 标题加 ZH + route 重构 |
| 15 | v6.2 | "客户需要 sync done 通知"| v8 M4 加 Toast 设计（待用 TVU Notification 库优化） |
| 16 | v6.3 | "Toast 视觉太重 + close 应用 icon + 需要 drop shadow"| 待用 TVU Notification side-pop variant 重做 |
| 17 | v6.4 | "你自查走查过吗？"| 触发设计 walkthrough（待补） |

---

## 3. Top 5 process gap（按返工成本排序）

### Gap 1: **没在前 3 轮确认对象 cardinality 和状态模型**

**实证**:
- PP-to-Session: 1:N（页面级共享）— v0-v2 我当成 per-session，user 第 4 轮纠正 → 整 LEFT panel 结构推翻重做
- Sessions: 状态数 2 不是 5 — v0-v2 按 5 状态实施完整 UI（Badge 颜色/Failed Retry/Done ✓/Idle 等），user 第 5 轮纠正 → 删一半视觉
- Parameters: per-session 不是 page-shared — v0-v3 当 page-shared，user 第 6 轮纠正 → RIGHT panel binding 重做
- Sessions persistence: list 包含历史（不只 running）— v0-v3.2 当 transient running-only，user 第 7 轮纠正 → OFF rows meta 重写

**返工成本**: 4 个 cardinality 错都重新做一遍 Figma — 约 12 轮 use_figma calls。**前置 5 个 cardinality 问题成本 0**。

**原因**：AI 起手没有"对象建模 → cardinality / 状态机 / 持久化语义"的强制 probe 步骤，默认按"PRD 字面 + 现有 mockup 视觉"猜，遇到 1:N / state count / per-session vs page-shared 这种架构级别决策只能等用户后续轮纠正。

**✅ 解决方案**：
- **当下修复**：4 个 cardinality 错全部翻盘重做 — LEFT panel PP 上提到页面级（v4）/ 5-state → 2-state ON/OFF（v3）/ RIGHT panel session 名 BRAND 绑定 per-session（v3.1）/ OFF rows meta 加历史时间段持久化语义（v3.2）；之后每帧统一 cardinality 一致
- **长期防护**：mockup session 起手必问 5 个 cardinality 问题：(1) 对象之间 1:1 / 1:N / N:N？(2) 状态机几个 state，PRD "e.g." 是 in-scope 还是对比参考？(3) 参数 per-session 还是 page-shared？(4) list 是 transient running-only 还是持久含历史？(5) 切换 parent 时 children 是 reload 还是 preserve？— 不答完不画图
- **真源落地**：⏳ M-CARDINALITY 待回流到 `design-process.md`（累积证据：本 session + MicroApps Console 已 2 例，再 1 例触发回流）

### Gap 2: **没在画图前先做 IA 文本确认**

**实证**: v0-v3 我直接画 Figma，每一轮 user 看到画了才发现"不对，应该 X"。第 8 轮 user 明确说"先用文本的方式来呈现页面布局，确认后再去画图"——之后效率显著上升。

**返工成本**: 前 8 轮所有 Figma 改动如果先走 IA 文本确认能减少 50%。

**原因**：AI 默认把"画 Figma"当成 user 看到的第一交付物，跳过文本 IA 阶段直接进 use_figma。大 redesign / 多 cardinality 未确认场景下，画图 = 把假设固化成视觉，user 看到视觉才能反应"不对"——文本阶段几句话能挡掉的歧义被推后到几十个节点之后。

**✅ 解决方案**：
- **当下修复**：第 8 轮起改为「先文本 outline (LEFT panel 结构 / RIGHT panel binding / state 列表 / row meta 字段) → user verify → 再 use_figma 画」，效率显著上升；剩余 17 轮迭代用这个模式
- **长期防护**：`@TVU mockup` skill 起手协议默认走 IA-first 路径 — 凡是「新页面 / 大 redesign / 架构未定」的任务，AI 必须先产出文本 IA 提案（分栏 / 模块 / 状态 / 字段 4 项）贴给 user，verify 后才允许调用 use_figma；只有 minor polish 才豁免
- **真源落地**：⏳ M-IA-FIRST 待回流到 `tvu-design-mockup` skill 起手协议（同 batch 跟 M-CARDINALITY）

### Gap 3: **`@TVU mockup` skill 存在的意义是起手就用 library + token，我把它当 polish-pass**

**实证**: v0 全 file-local Badge/Button/Tab/icon + 全自造 hex 色（不在 TVU palette 内）+ Unicode → ↓ ↑ ✓ 当 icon 用。"v0 file-local OK，dev 阶段 swap"思路违反 M32 + 硬规则 #4。User 第 2 轮明确点破。

**返工成本**: v0 整套视觉重做 → v2/v3 全 library 实例 + 对齐 dark palette。约 6 轮 use_figma calls。

**原因**：AI 把 `@TVU mockup` skill 误解为「最后用来 polish 视觉」的工具，默认 v0 sketch 阶段可以 file-local 自由发挥（Badge/Button/Tab/icon/hex 都自造），等结构稳定再 swap。实际上 skill 的硬约束是「起手第一个节点就用 library + token」，自造越早成本越低。

**✅ 解决方案**：
- **当下修复**：v0 全套 file-local 视觉作废重做 — 19 个 library instance swap（Badge / Button / Tab / icon）+ 全 hex 重新对齐 dark palette + Unicode 字符 (→ ↓ ↑ ✓) 全部替换为 TVU library icon component
- **长期防护**：起手即用 library；任何 mockup 任务 v0 第一个节点就必须是 library instance + token，禁止"先 file-local 后期 swap"思路；build 完跑 M-TXT-ICON-AUDIT 扫 Unicode-as-icon + M-FONT 扫 off-grid 字号
- **真源落地**：✅ 已落 TVU 真源 [`mockup-conventions.md`](../../../tvu-design-system/docs/internal/mockup-conventions.md) M-FONT (textStyle grid 12/14/16/18/20/22/24) + M-TXT-ICON-AUDIT (Unicode-as-icon 扫描)

### Gap 4: **没分析用户给的参考图就开始造**

**实证**: User 给了 Plan B Default 截图 + Standard Conversion 截图（统一 Micro Apps 布局模式）。我没结构化提取这些 reference 的 layout contract（LEFT/RIGHT 分栏 / sub-header 模式 / page label 模式），自己造了一个 sub-header strip → user 第 4 轮点破"统一布局没有 sub-header"。

**返工成本**: sub-header 整段删 + 重建 — 约 3 轮 use_figma calls。

**原因**：AI 看到参考图默认"凭印象参考"——记住大致风格就开始画，没把参考图当成结构化合同来 probe。结果自造的 sub-header strip 等模式跟既有 MicroApps 统一布局冲突，user 第 4 轮才点破。

**✅ 解决方案**：
- **当下修复**：sub-header 整段删 + PP selector 上提到页面级 header 区；按 Standard Conversion 参考图的 LEFT/RIGHT 分栏模式重建 v2 布局；产出 §5.5 LEFT 1216 / RIGHT 680 硬规则
- **长期防护**：user 给参考图时**强制 5-row probe table**（layout 分栏 / body pattern / components / interactions / spacing），AI 必须先填表贴给 user verify，禁止"凭印象参考"直接画
- **真源落地**：✅ 已落 TVU 真源 [`mockup-conventions.md`](../../../tvu-design-system/docs/internal/mockup-conventions.md) M37 Reference-image probe（5-row table 强制 deliverable）+ [`code-conventions.md`](../../../tvu-design-system/docs/internal/code-conventions.md) R18 code mirror

### Gap 5: **多页重复模块没抽 file-local component**

**实证**: session row 模式在 M0/M1/M2/M3/M4/Plan B 6 帧重复，每帧独立 clone 而非 instance 同一个 file-local component。State Pill 反向实证——产品文件内本来就有 `MicroApps Monitor — Local Components > State Pill`，但我自画 Badge 没看 → user 抓"为什么不用既存 State Pill"。

**返工成本**: 没立即抽，但 6 帧 clone 后任何改动要 ×6（如 BRAND 色 swap、Tag=Filled→Line swap、ON→Syncing text swap），每次都 16-20 处批量操作。

**原因**：AI 看到重复模块时默认"clone 节省时间"，没做"出现 2+ 次 → 抽 file-local component"的强制判定；同时没扫产品文件内既存的 file-local component（State Pill 已存在却自画 Badge）。

**✅ 解决方案**：
- **当下修复**：v6 起 Badge → 改用产品文件内既存的 `MicroApps Monitor — Local Components > State Pill` component instance；后续 BRAND 色 swap / Tag variant 切换从 ×6 clone 操作降为 1 处 master 改 + 自动传播
- **长期防护**：mockup build 起手先扫产品文件 `Local Components` section 列已有 file-local component；任何模块出现 ≥2 次必须抽 file-local component（不是 clone）；TVU promotion audit — file-local component 累积证据后评估 promote 到 TVU library
- **真源落地**：✅ 已落 TVU 真源 [`mockup-conventions.md`](../../../tvu-design-system/docs/internal/mockup-conventions.md) M36 Multi-page reuse → file-local component → TVU promotion audit + [`code-conventions.md`](../../../tvu-design-system/docs/internal/code-conventions.md) R17 code mirror

---

## 4. 高效对话 10 条建议（按 ROI 排序）

### 给 UX 设计师 / Product Manager（提需求方）

#### (1) 起手 1 段话用 5 问题 brief AI

> 直接在 PRD 后面贴这段：
>
> **架构 brief**: PP 与 Session 是 1:N / Parameters 与 Session 是 1:1 / 状态只有 ON|OFF 两种 / 历史 sessions 持久保留在 list / PP 切换重新加载 sessions list。
>
> AI 起手 cardinality 问题就一次性回答完，省 3-4 轮纠正。

#### (2) PRD 用 "例如/e.g." 时显式说 "其中 X 和 Y 是 in-scope"

> 反例：R3 写 "例如：Syncing / In Progress / Done / Failed / Idle" — AI 当全 mandatory。
> 正例：R3 写 "只有 2 个状态：Syncing / Inactive。PRD 后面列出其它术语仅为对比参考。"

#### (3) 给参考图同时说 **"先 probe 提取布局合同再画"**

> 反例：扔截图给 AI 让它"参考"。AI 凭印象造。
> 正例："请先用表格列出这个 reference 的：layout 分栏 / body pattern / components / interactions / spacing 5 项，确认后再画。"

#### (4) 大 redesign 先要 **IA 文本提案再画**

> 1 句话指令： "先用文本的方式描述页面布局 + 信息架构，确认后再开始画 Figma。"
> 这一句话能减少前几轮 50% 返工。

### 给 AI 协作流程

#### (5) 任何 mockup 任务起手 dispatch Opus 做架构推理

Opus 比 Sonnet 更能：
- 自审承认错误（"我没看 PRD 里的 e.g."）
- 跨文件综合回流
- 检测 cardinality 不一致
- 长 session 内记住前轮决策不漂移

执行（已 plan 好的批量 swap / probe）切 Sonnet subagent 省 ~70% 成本。详见单独 model 对比段。

#### (6) 用户给 feedback 时 AI 必须先 probe / 反问 / 确认

反模式："好的我改" — 然后改错方向。
正模式：先 probe（看现状）+ 反问（"你说 X 错，具体是 X1 还是 X2？"）+ 确认（"我打算 Y，对吗"）再动手。

#### (7) AI post-build 必须自走查

不要等 user 问 "你自查了吗"。Build 完跑 6 项 audit：
1. Layout (M31, filter viewport/overlay/library)
2. Library compliance (M32)
3. Font grid (M-FONT 12/14/16/18/20/22/24)
4. Text-as-icon (Unicode 扫描)
5. Component reuse (出现 2+ 次的 module 抽 file-local)
6. Selected indicator (1-side left rail unified)

每项有 audit script 可直接跑 (mockup-conventions.md 已有)。

#### (8) AI 用户 pushback 要承认错根因，不只是 surface fix

反模式: "好的我改" + 改了表面就完。
正模式: 修复同时**反思根因 → 转化为可回流的规则**。
本 session ~13 条规则全是这样产生的——user 抓错 → AI 分析根因 → 写规则进 mockup-conventions / code-conventions / figma-technical-reference。

### 给 PM / Stakeholder（review 方）

#### (9) 用 checklist review 而不是凭感觉

提供给 PM 6 项 quick audit 表（用户走查 + AI 走查同样这 6 项）：
- [ ] 布局符合 §5.5（LEFT 1216 / RIGHT 680 / vertical center）
- [ ] 状态视觉一致（selected indicator 1-side left rail）
- [ ] 状态语言对齐（Badge 文字跟 RIGHT 按钮语义一致）
- [ ] 历史信息可见（OFF rows 带 last ran / last delta meta）
- [ ] PRD 客户场景覆盖（sync done 通知 + offset 值可见）
- [ ] 库合规（无 self-built Badge/Button/Icon/Color）

#### (10) PRD 加 "Out of scope" 必显式枚举

避免 AI 把"PRD 没说的"当 "PRD 没禁止可以加"。本 session AI 多次加了 PRD 没要求的（如 sub-header、page label、5 个 filter chips），都被删。

---

## 5. 13 条已回流 / 待回流的新规则清单

### ✅ 已回流到 TVU 真源（本 session 写入）

| 规则 | 真源文件 | 简述 |
|---|---|---|
| Q9 | `figma-technical-reference.md` | Section 不自动 fit children，必须显式 resize |
| Q10 | 同上 | Mixed-font TEXT 操作哪些需 font load |
| Q11 | 同上 | Clone instance 继承 status=disable 等 variant |
| Q12 | 同上 | Section children 负 y 坐标处理 |
| M36 | `mockup-conventions.md` | Multi-page reuse → file-local component → TVU library audit |
| M37 | 同上 | Reference-image probe before design (5-row table) |
| M38 | 同上 | Selected indicator 1-side left accent rail |
| M-FONT | 同上 | TVU textStyles grid (12/14/16/18/20/22/24) |
| M-TXT-ICON-AUDIT | 同上 | Unicode-as-icon post-build mandatory scan |
| M31 增补 | 同上 | Page-level viewport 不算 absolute 违规 |
| R17 | `code-conventions.md` | M36 code mirror |
| R18 | 同上 | M37 code mirror |
| R19 | 同上 | M38 code mirror (Selected CSS spec) |

### ⏳ 待 batch 回流（下 session 完成）

| 规则 | 目标真源 | 简述 |
|---|---|---|
| M-PRD-EG | `design-process.md` | PRD "e.g." 必显式问 in-scope |
| M-CARDINALITY | `design-process.md` | 5 个 cardinality / lifecycle 起手必问 |
| M-IA-FIRST | `tvu-design-mockup` skill 起手协议 | 大 redesign 默认走 IA 文本确认 |
| Badge Extension scenarios 增补 | `figma-component-catalog.md` | ON status = BRAND Green + Tag=Line for read-only |
| `MICROAPPS_PRODUCT_CONTEXT.md §5.5` ref 改 | 改双写为 reference link 指 TVU 真源 | 避免漂移 |

---

## 6. Model 选型推荐（基于本 session 实证）

| 模型 | 适合场景 | 在本 session 起作用的时刻 |
|---|---|---|
| **Opus 4.7** | 主对话 / 架构推理 / 自审 / 多轮 pushback / 跨文件回流 | (a) 检测 PP 1:N (b) 承认 v0 全 file-local 是 anti-pattern (c) 2-state 根因分析 (d) M31 audit 准确性自审 (e) 客户原话遗漏检测 |
| **Sonnet 4.6** | 执行 batch 改动（已 plan 好）/ probe / 简单文本 swap | 适合本 session 的 50+ use_figma 执行 calls |
| **Haiku 4.5** | probe / 简单查询 | 不适合主对话 |

**Hybrid 推荐**：Opus 做 plan owner（决策 + 回流），Sonnet subagent 做 executor（批量执行）。对应 Codex/Claude Code 已有的 plan-executor 工作流。

**纯 Sonnet 推算**：若本 session 全 Sonnet，估计:
- 50% 概率漏 PP cardinality 问题
- 80% 概率回流 doc 缺 history 实证段（结构化但 boilerplate）
- 高概率 M31 audit 不会主动二审 (false-positive 不会主动反思)
- **实际成本（返工轮数 × token）反而高**

---

## 7. 给团队的 3 个 action items

1. **PRD 模板增 "架构 brief" 段**——填 cardinality + state count + 持久化语义。直接节省 3-4 轮 AI 纠错。
2. **`@TVU mockup` skill 协议增起手 5 问题 + IA-first** 选项——确保 AI 在大 redesign 默认走文本 IA 路径。
3. **TVU 库 maintainer 收集本 session 未抽出的 component 候选**：session row pattern / Stream A/B column / Add session placeholder / Toast 自建 frame（已知 TVU 有 Notification side-pop） — 评估是否 promote。

---

## 8. 附录：本 session use_figma 实际改动统计

| 改动类型 | 次数 |
|---|---|
| 创建 frame / panel / row / chip | ~30 |
| Badge swap (Tag/Color/text) | 23 swaps |
| Button reset (status=disable→default) | 2 |
| icon swap (text → library icon) | 18 |
| Font normalize (off-grid → grid) | 33 |
| Section auto-fit | 5+ |
| Route restructure (Slot > Ch + sync icon) | 17 routes + 6 dropdowns |
| Rules card title bilingual | 10 |
| 删除（sub-header / page label / OQ card / etc.）| ~8 |

**总 use_figma calls**: ~50+ rounds across ~25 user feedback iterations.

---

> **复盘人**：Claude Opus 4.7 + Nancy Zeng (UX)
> **复盘时间**：2026-05-20
> **目标受众**：TVU 内部 — UX team + AI 协作流程改进
> **联系**: 本文件提到的真源文件全部在 `tvu-design-system` repo 内可查