# Source Delay & Bitrate Settings Mockup — AI × UX 协作复盘

> **复盘人**：Claude Sonnet 5 + Lora (UX)
> **复盘时间**：2026-07-14
> **目标受众**：TVU 内部 — UX team + AI 协作流程改进
> **关联需求**：EDPP-1970（后端已 merge）· Slack 讨论 [CV6NGH745/p1783934891974019](https://tvunetworks.slack.com/archives/CV6NGH745/p1783934891974019)
> **Figma**：[PP-2025-2026 · program delay & bitrate setting](https://www.figma.com/design/tmVCFjx1BCfb7EP5OPD1AP/PP-2025-2026?node-id=3193-786)

---

## 1 · TL;DR

- **总轮次**：1 次初版实现 + 4 轮用户 feedback（含本篇复盘请求共 6 轮对话）· 约 55-60 次 `use_figma` 调用
- **最终交付**：Producer Program Settings 弹窗新增 `Bitrate (kbps)` 下拉框（Format 区块下）+ `Source delay control` 勾选后在标签下方缩进显示 `Delay [2000] ms`；配套双态对比图 + M23 格式 UX 交付卡
- **核心 insight**：

> **约一半的 `use_figma` 调用不是在满足用户需求，而是在修复我自己引入的 Figma API 陷阱**（白底盖白字、`figma.group()` 坐标错位、忘记 `setCurrentPageAsync` 导致内容建到错误 page）。这些不是"用户体验没做好"，是纯技术执行纪律问题——本该通过更严格的"改动后立刻用真实背景截图验证"来提前拦截，而不是事后一路排查。

---

## 2 · Session 概览

**起点**：用户贴了一条 Slack 讨论链接（dolphin 报告 EDPP-1970 后端已 merge：统一 delay/bitrate 跨设备源的 API；Mateus 提议在 Settings 加全局控制），要求先总结，再在 PP-2025-2026 的 Settings 页面里做出这个需求的 mockup。

**最终落地**：
- 📋 Figma node `3193:794`（Settings 弹窗）：Format 区块新增 `Bitrate (kbps)` Dropdown（16px 间距，无图标）；`Source delay control` 勾选后缩进显示 `Delay [2000] ms`（unit 在输入框后）
- 🎨 状态对比图（node `3196:49741`）：Default（未勾选）vs Enabled（勾选+显示 Delay）双态 + connector
- 🎨 M23 格式 UX 交付卡（node `3199:1008`）：Why / Changes / Data Contract / Interaction / Acceptance，双语
- 🔀 **未做**（用户主动选择跳过）：Jira 组件实例、独立 Section、F1 走查、F2 persona 模拟、journey map

**Process 产物**：本篇复盘 1 份；无 handoff doc（未走完整 8 步流程）；无新 backlog entry

---

## 3 · 时间线（4 轮关键 feedback）

| # | 版本 | 用户 feedback 触发 | 改动量 | 性质 |
|---|---|---|---|---|
| 1 | v1 初版 | "这是setting页面，在这个页面做出上面的需求" | Bitrate 输入框(带图标+stepper) + Delay 内联字段 + 双态对比图 + UX 卡；~30 次 `use_figma`（其中近一半是修白底盖白字 / group 坐标错位 / 错误 page 等自制 bug） | 首版实现，技术纪律 gap 多 |
| 2 | v2 | "bitrate不要加图标，距离format 16px，用下拉框" | Bitrate 从 Input+stepper 改为 Dropdown 克隆、去图标、Format 区块拆两个子块拿到 16px 间距 | 用户视觉规范纠正 |
| 2 | v2 | "delay的设置没有对齐，你自己看看排版整齐吗" | Delay 行 `counterAxisAlignItems` 改 `CENTER`，输入框高度从 28 统一到 20 | **AI 自查纪律 gap**——验收前应自己截图核对，不该等用户点破 |
| 3 | v3 | "delay的设置和source delay control的位置再考虑一下，现在影响阅读" | Delay 字段从"同一行内联"改为"标签下方缩进 28px 独立行" | AI 设计判断需要迭代——inline 不算错，但不是这个场景的最优布局 |
| 4 | v4 | "字体色号优先使用pp-lora的规范" | 发现文件已订阅团队库 **PP-Lora**（`get_libraries` 才查到），把所有自建元素的填充从 raw hex 改绑 PP-Lora 的 published style（white / Black1 313436 / Black3 979DA3） | **AI 资源复用弱**——没有主动查文件真实绑定的库，就凭视觉估算写死颜色 |
| 4 | v4 | "delay的单位放输入框后面，默认值2000" | unit "ms" 挪到输入框后（原在 label 里）；默认值 0 → 2000 | 内容细节调整 |

---

## 4 · Top 3 Process Gap（按返工成本排序）

### Gap 1 · 建新元素前没有主动核实目标文件的团队库/颜色规范

**实证**：
- v1 建 Bitrate/Delay 相关文字与色块时，全部用了肉眼估算的 raw hex（`#FFFFFF` / `#313436` / `#979da3` 等），虽然凑巧和真实值数值上一致，但没有绑定到 Figma Style 对象
- 用户第 4 轮反馈 "字体色号优先使用pp-lora的规范" 后才去查，一查发现文件本来就订阅了 **PP-Lora** 团队库（`get_libraries` 一次调用即可发现），且已有的所有原生元素（如 "Source delay control" 文字、Input 背景矩形）早就绑定了这个库的 published style，只有我自己新建的元素是裸 hex

**返工成本**：~6 次 `use_figma` 调用（发现库 → 查 style key → 逐个重新绑定 fillStyleId）

**原因**：我在"读取/核对已有元素"时会认真查真实数据（这次也确实读对了颜色数值），但在"新建元素"时切换成了"凭记忆/估算写死数值"的模式，没有把同一套"查真源"的纪律用到创建动作上。

**✅ 解决方案**：
- **当下修复**：本 session 内用 `get_libraries` 找到 PP-Lora（libraryKey `lk-1785...4e2`），`search_design_system` 找到具体 style key，`importStyleByKeyAsync` + `setFillStyleIdAsync` 重绑了 Bitrate 标题、Delay 标签、Delay 数值框/文字、单位文字
- **长期防护**：任何在 TVU 产品 Figma 文件里新建带颜色/文字的元素前，第一步先跑 `get_libraries` 确认该文件订阅了哪些团队库，再用 `search_design_system` 按颜色/组件语义查现成 style，只有查不到才允许 raw hex（并在交付卡里显式标注"无 style 源，纯估算"）
- **真源落地**：⏳ 待回流——建议加进 `tvu-design-system/docs/internal/mockup-conventions.md` 的 `M-COLOR` umbrella 作为新 sub-clause（如 §C4"新建元素颜色必须先查文件订阅库"），触发条件：累计再遇到 1-2 次同类漏查即可拍板成规则

### Gap 2 · Figma Plugin API 的几个隐蔽陷阱吃掉了大量返工成本

**实证**：
- `figma.createAutoLayout()` / `figma.createFrame()` 默认白色背景，白字放进去在"暗色父容器"里其实全遮住了看不见——花了 3-4 次调用才定位到是"新建 frame 默认白底"而不是文字属性错
- `figma.group([rect, t], parent)` 如果 rect/t 在 group 前没有先 `appendChild` 到目标 parent，坐标系是按创建时的父级（page）算的，group 后位置整体错位几百 px——花了 2-3 次调用才定位
- 忘记在脚本开头 `await figma.setCurrentPageAsync(page)`，导致 UX 交付卡建到了文件的**另一个无关页面**（"PMPP-1119..."），还顺带用一个"临时 review section"扫了一遍差点误删别的内容（虽然最后确认没有实际损失）

**返工成本**：~12-15 次 `use_figma` 调用（3 个 bug 加起来的排查+修复+验证）

**原因**：这些都是"确认结果时只看 isolated node 截图"暴露不出来的问题——isolated screenshot 会把 transparent 背景渲成白色，掩盖了"真实父容器背景是什么色"这类问题；page-context 类 bug 则是因为没有把"每次 use_figma 调用先检查/设置 currentPage"当作强制起手动作。

**✅ 解决方案**：
- **当下修复**：本 session 内已修正全部 3 处（cluster/group 补 fill=[]、group 前先 appendChild、把误建到错误 page 的卡片 reparent 回正确 page）
- **长期防护**：(a) 验证新建元素颜色/文字可见性时，优先截图**真实父容器**（如整个 dialog）而不是孤立截图刚建的小节点；(b) 每个 `use_figma` 调用开头，只要涉及跨调用的节点操作，第一行代码固定 `await figma.setCurrentPageAsync(page)`，不依赖"应该还在同一页"的假设
- **真源落地**：⏳ 待回流——这 3 条是纯 Figma Plugin API 技术细节，跟具体产品无关，建议整理成 `figma-technical-reference.md` 的新 Q&A 条目（如 Q18 白底盖白字 / Q19 group 坐标系 / Q20 page 状态重置），供任何 AI 工具在这个仓库里画 mockup 时提前避坑。**本 session 未落地，需要用户拍板是否现在写入。**

### Gap 3 · 复用最近的视觉兄弟组件，没有先评估字段语义

**实证**：
- Bitrate 是"预设常用值"性质的字段（常见 bitrate 挡位如 3000/6000/8000），我却直接照抄旁边"Number of Live Slots"这类"自由范围计数"字段用的 Input+stepper 组件，还顺带带上了它的装饰图标——用户纠正为 Dropdown 且去图标
- Delay 字段揭示位置也是先做了"和 checkbox 同一行内联"的判断，读起来才发现这行明显比其它 checklist 行长很多、打断阅读节奏，用户点出后才改成缩进独立行

**返工成本**：~10 次 `use_figma` 调用（Bitrate 组件类型重建 + Format 区块间距重构 + Delay 行结构重排 + 联动更新对比图和交付卡文案）

**原因**：两次都是"就近复用视觉最像的邻居元素"，但没有先问一句"这个字段的实际交互语义是什么/这一行放得下吗"，属于 M16"Deliverable Defaults Must Be Evaluated"该做而没做到位。

**✅ 解决方案**：
- **当下修复**：Bitrate 改绑 Dropdown 组件实例；Delay 字段改为标签下方缩进 28px 的独立行
- **长期防护**：新建/克隆字段前，先用一句话写清楚该字段的语义（"预设挡位"用 Dropdown，"自由计数"用 Input+stepper，"checkbox 揭示的从属字段"默认走"标签下方缩进"而不是"同行内联"），再决定复用哪个视觉兄弟，而不是选"看起来最像"的那个
- **真源落地**：⏳ 待回流——建议在 `mockup-conventions.md` M32（Library-First）下补一句"选源组件前先判断字段语义类别"，或在 M16.1 补一条"checkbox 揭示字段默认走缩进子行"的具体范式；触发条件同 Gap 1，累计遇到同类案例再拍板

---

## 5 · 高效对话建议

### 给 UX / PM（提需求方）

**(1) 简短、具体、一次一个点的纠正效率最高**
> 本 session 里 "bitrate不要加图标，距离format 16px，用下拉框" 这类三个具体指令堆在一句话里，我能一次性精准修复，不需要来回确认。反例是模糊反馈（如"感觉不太对"）——会逼 AI 猜测范围，容易改多或改少。

**(2) 遇到"这是不是有现成规范"的疑问，直接给来源比让 AI 猜更快**
> "pp-lora的规范"这句话如果一开始就带上"在 Assets 里搜 PP-Lora"这个线索，能省掉 2 轮澄清提问。

**(3) 明确要不要走完整流程，能显著控制交付节奏**
> 本次一开始就问清楚"轻量 mockup+卡片" vs "完整 8 步 Jira 流程"，双方对交付范围预期一致，后续没有因为"该不该建 Jira 组件"这类问题反复。

### 给 AI 协作流程

**(4) 新建元素前，先用同样严格的"查真源"纪律，不要只在核对已有元素时严格**
> 反模式：读取已有颜色时认真核对 hex，新建颜色时凭记忆写死。正模式：新建前先 `get_libraries` / `search_design_system` 扫一遍。

**(5) 验证截图要用"真实使用场景"的容器，不要只看孤立节点**
> 孤立截图的透明背景默认渲染成白色，会让"白字在暗色父容器里其实没问题"这类判断失真，也会让"新建 frame 意外带白底"这类真 bug 被掩盖。两种情况都得靠"在真实父容器里截图"才能分辨。

**(6) 每次 Figma 写操作前默认设置好 currentPage，不要假设"还在上次的页面"**
> `figma.currentPage` 在每次 `use_figma` 调用开头会重置，跨调用不能假设页面状态延续。

### 给 PM / Stakeholder（review 方）

**(7) 用 checklist 而不是通读全篇 review 交付卡**
- [ ] 颜色/字体是否绑定了发布库的 style（而非估算 hex）
- [ ] 每个 checkbox 揭示的从属字段是否有清晰的"默认态/揭示态"两版展示
- [ ] 交付卡 Data Contract 段是否精确对应真实 API 字段名
- [ ] 交付卡是否只覆盖本期改动（没有夹带 persona / out-of-scope 等无关内容）

---

## 6 · 规则回流清单

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

（无——本 session 走的是轻量交付路径，未触发 `docs/internal/backlog.md` / `mockup-conventions.md` 的正式回流写入）

### ⏳ 待回流

| 规则 | 目标真源 | 触发条件 |
|---|---|---|
| 新建颜色/文字元素前先查文件订阅库（`get_libraries` + `search_design_system`） | `tvu-design-system/docs/internal/mockup-conventions.md` §M-COLOR 新 sub-clause | 累计 2-3 次同类"漏查库、凭估算写色"实证后拍板 |
| Figma 技术陷阱 3 条（白底盖白字 / group 坐标系 / page 状态重置）| `tvu-design-system/docs/internal/figma-technical-reference.md` 新 Q&A 条目 | 用户拍板是否现在写入（本篇复盘已列出具体内容，可直接誊抄） |
| 字段语义先行 → 再选源组件（预设挡位用 Dropdown / 自由计数用 stepper / checkbox 揭示字段默认缩进子行）| `mockup-conventions.md` M16.1 或 M32 | 累计 2-3 次同类案例后拍板 |

---

## 7 · Model 选型实证

| 模型 | 适合场景 | 本 session 起作用时刻 |
|---|---|---|
| **Sonnet 5**（本 session 实际使用） | 主对话 + 架构判断 + Figma API 调试 + 自审 + 跨轮次一致性维护 | 全程独任：读取 6-step onboarding 材料、澄清式提问（放置位置/流程深度）、Figma 构建与调试、多轮细节修正、本篇复盘写作 |
| **Opus 4.8** | 更复杂的多方案设计判断 / 需要更强 self-review 的场景 | 未使用；如果 Bitrate vs Delay 的组件语义判断（Gap 3）一开始就走一轮"先列 2-3 个方案 + 推荐 + why"的显式设计阶段，可能更适合上 Opus 做该判断 |
| **Haiku 4.5** | 机械性 probe / 简单查询 | 未使用；像"逐个截图核对对齐"这类重复验证步骤理论上可以委托给更轻量模型，但本 session 全程单线程操作，没有拆分并行任务的机会 |

**Hybrid 推荐**：本 session 规模（1 个 Figma 页面、~4 轮反馈）用单一 Sonnet 5 主线程足够；如果未来同类任务需要"多个候选布局方案对比"（如 Delay 揭示位置这类判断），值得在动手前插入一次 Opus 做"设计选项 + 推荐"的独立判断步骤，而不是直接上手建。

---

## 8 · 给团队的 3 个 Action Items

**1. 把"新建元素前查文件订阅库"做成 Figma mockup 任务的强制起手步骤**
> 本 session 的最大返工点（Gap 1）完全可以在 Phase 0 阶段用一次 `get_libraries` 调用规避。建议加进 `tvu-design-mockup` skill 的起手协议（当前只提到"library-first"原则，未显式要求先查订阅库列表）。

**2. 把本篇复盘里的 3 条 Figma 技术陷阱正式写入 `figma-technical-reference.md`**
> 这些是纯技术细节，跟本次产品需求无关，但会在任何未来的 mockup session 里重复出现，属于最该沉淀到仓库真源的那类知识。当前状态是"只活在这篇复盘里"，需要显式拍板才会真正防住下次重犯。

**3. 建立"checkbox 揭示从属字段"的标准范式（缩进子行 vs 同行内联）**
> Gap 3 里 Delay 字段的两次布局判断本可以用一条明确的范式一次性做对。建议在 `mockup-conventions.md` 补一条具体规则，避免同类判断每次都靠现场感觉。

---

## 附录 A · 改动统计

| 改动类型 | 次数（约） |
|---|---|
| 新建/克隆 Figma 节点 | ~15 |
| 因自制 bug 而做的调试/修复调用 | ~15-20 |
| 因用户反馈而做的调整调用 | ~20 |
| 澄清性提问（AskUserQuestion） | 4 |

## 附录 B · 关联文档

- Slack 讨论：[CV6NGH745/p1783934891974019](https://tvunetworks.slack.com/archives/CV6NGH745/p1783934891974019)
- Figma：[PP-2025-2026 Settings 页](https://www.figma.com/design/tmVCFjx1BCfb7EP5OPD1AP/PP-2025-2026?node-id=3193-786)
- Producer 产品上下文：`docs/PRODUCT_CONTEXT.md`（Management Center → Settings / Program 配置 弹窗已有记录，本次改动落在后者）

---

> **复盘人**：Claude Sonnet 5 + Lora (UX)
> **复盘时间**：2026-07-14
> **目标受众**：TVU 内部 — UX team + AI 协作流程改进
> **联系**：真源文件全部在 `tvu-design-system` repo 内可查