# 协作复盘 · V4-1827 移除 Source Name 字段（Round 3.2）

- **日期**：2026-07-27
- **任务**：Config-T `rJJjWWs51n2iFOlCIC7aYG` — 从 NDI 单源表单移除 `Source Name` 字段，同步 mockup + UX 说明 + PRD
- **受众**：UX 团队 / PM 内部分享（AI 协作过程复盘，非交付物本身）

---

## 1. TL;DR

- **总轮次**：1 轮用户指令（+1 条中途补充），零返工性质的方向变更。
- **最终交付**：8 个产品帧删字段 + 14 节点重排 + 10 个注释节点改写 + 2 处上轮遗留修正；design-record §7.6 / handoff §7 / ledger / memory / in-file 机检 report 全部落盘。
- **核心 process gap**：2 个（1 个 Figma API 样式继承坑造成一轮内部返工，1 个"删元素的连带影响"预判不足，靠机检兜住）。
- **关键 insight**：**用户给的"为什么"直接决定了交付质量**。这次的指令是「把 Source Name 去掉，**因为没有地方来体现 Source Name**」——正是这半句 why，让 AI 能自主判断出三件不在字面要求里的事：PRD/验收要**补一条显式条目**（否则下游会把删字段读成遗漏）、Data Contract 要从"存字符串"改成"不存储"、caption ⑩ 的 "Long source name" 要加限定词区分「发现列表里的源名」与「已删的输入字段」。只说"删掉 X"做不到这些。

## 2. Session 概览

| 项 | 内容 |
|---|---|
| 起点 | 续跑 prompt（Round 3.1 已完成）+ 用户一句话需求 |
| 中途补充 | 「相关的 Mockup、UX 说明和 PRD 都需要更新一下」——与 AI 已推断的范围一致，起到确认作用 |
| 落地 | Figma 8 帧 + 4 张注释卡 + 2 条 caption；4 份文档 |
| Process artifacts | M48 起手 self-check 清单 · stale sweep · in-file 机检 report · 6 张截图亲验 |

## 3. 时间线 / 主要迭代

| # | 阶段 | 触发 | 改动量 |
|---|---|---|---|
| 1 | 起手协议 + 勘察 | skill 起手 gate | 读真源、探 8 帧结构（确认同构）、stale sweep 定位 30 处命中 |
| 2 | 产品区删除 | — | 8 帧删 `Frame 38`，浮层/Tooltip 上移 56px（2 次调用，各 4 帧） |
| 3 | 注释层改写 | — | 10 个节点，替换 + 追加 |
| 4 | **字体污染修复** | 自查逐行字体发现 | 3 次调用：审计 → 精查参考行 → 回灌样式 |
| 5 | 布局回收 | 截图 + overlap 机检发现 | PRD 压到 WebR 参考（下移 72）、AFTER 帧③间距、states 7 组级联上移 |
| 6 | 机检 + 文档 | M-DISCIPLINE.SYNC | report 落盘 + 4 份文档同步 |

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

### G1（中）— `insertCharacters(..., 'BEFORE')` 在行首继承了上一行的整套样式

**实证**：Journey 卡 stage 3 的 `Actions:` / `Touchpoints:` 行原本是「label = Roboto Medium 12 cyan + body = Roboto Regular 12 white」双段结构。用 `deleteCharacters` + `insertCharacters(i, s, 'BEFORE')` 替换整行后，整行变成 Noto Sans SC 13 cyan——因为 `'BEFORE'` 继承的是**前一个字符**，而行首的前一个字符是**上一行的换行符**，那一行是中文。font / fontSize / lineHeight / **fill** 四项一起被带过来，双段结构被抹平。

**返工成本**：3 次 use_figma 调用（逐行审计 → 精查参考行分段 → 回灌）。

**对策（已写进 handoff / memory）**：行级替换后**必须逐行复检字体**，并用同节点内**未被触碰的同类行**作基准回灌 `setRangeFontName/FontSize/LineHeight/Fills`——不要硬编码字号，不同卡的字号体系不一样。另注意 `getRangeFontName` 返回 `figma.mixed`（`.family === undefined`）往往是 label+body 双段的**设计本意**，不是违例。

**回流落点建议**：`tvu-design-system/docs/internal/figma-technical-reference.md` 的 Q 系列（纯 Figma API quirk），或并入 `mockup-conventions.md §M47`（字体相关）。**待 owner 拍板**是否升为规则。

### G2（低）— 删元素后的"连带影响"预判不足，靠机检兜住

删掉一行后，auto-layout 帧会自己收缩，但**三类东西不会跟着走**：① 帧内 `layoutPositioning='ABSOLUTE'` 的浮层 / Tooltip（会脱离锚点）② 下游 sibling 帧与 caption（留出空洞，破坏 I1 间距一致性）③ 反向：注释卡文本变长会**向上游传导**，本轮 PRD 增高 72px 直接压到下方 WebR 参考帧。

第 ① 项在删除时就一起处理了；②③ 是截图 + overlap 机检抓出来的。流程是有效的（机检确实兜住了），但更好的做法是**删除前就列出"谁靠它定位"清单**，一次算完 delta。

### G3（低，非本轮引入）— 上一轮（Round 3.1）的两处样式不一致，本轮才发现

UX 卡 Acceptance 末条 EN+ZH 挤在同一行且字号 11（sibling 是 13）、Journey stage 5 Opportunities 正文误配 cyan——**都是 Round 3.1 用同样的文本追加手法留下的**，当时只检查了 caption 级字体，没做逐行审计。本轮顺手修掉。

**教训**：同一个坑第二次踩才被发现，说明**上一轮的自检粒度不够**。文本类改动的自检单位应该是"行"，不是"节点"。

## 5. 高效对话建议（按 ROI）

**给 UX / PM 提需求方**

1. **删字段类需求，请带一句"为什么"**（ROI 最高）。本次「因为没有地方来体现」这半句，直接决定了 PRD 要不要补显式条目、数据契约怎么改、相关措辞要不要加限定词。只说"删掉 X" 会得到一个字面正确但下游会误读的交付。
2. **顺带说一句"这个数据别处有没有消费方"**。它决定这是纯 UI 删除，还是要动 Data Contract（本轮是后者：从"存字符串"变成"不存储"）。
3. 「相关的 mockup / UX 说明 / PRD 都更新」这类范围确认可以给，但**不给也不会漏**——交付层同步已经是流程硬规则（M-DISCIPLINE.SYNC）。省这句话没风险。

**给 AI 协作流程**

4. 文本类批量改动后，自检单位必须是**行**，且要用**同文件的未触碰同类行**做基准，不凭记忆写字号（见 G1/G3）。
5. 删除 / 缩小任何元素前，先列"谁靠它定位"（绝对定位子节点 / 下游 sibling / 上游容器），一次算完位移（见 G2）。

**给 review 方**

6. 本轮交付的验收锚点：NDI 表单只剩 `URL: ndi://` combobox + `Apply` 两件；PRD 功能需求 + 验收标准各有一条**显式**说明"不设源名称字段"；caption ⑩ 说的 "discovered source name" 指发现列表里的源名，与被删字段无关。

## 6. 已回流 / 待回流规则

| 规则 | 真源文件 | 状态 |
|---|---|---|
| `insertCharacters('BEFORE')` 行首继承上一行整套样式（含 fill） | `figma-technical-reference.md` Q 系列 或 `mockup-conventions.md §M47` | **待 owner 拍板**（已先记入本任务 handoff §7 + memory） |
| 文本改动自检粒度 = 行，且用同节点未触碰同类行做基准 | 同上 | 待 owner 拍板 |
| 删除/缩小元素前列"谁靠它定位"清单 | `mockup-conventions.md §I5`（可作 sub-clause） | 待 owner 拍板 |

> 按 skill 回流入口第 1 条，规则级沉淀需用户拍板；本轮先落在任务级文档（handoff / memory / 本复盘），不擅自改真源。

## 7. Model 选型推荐

本 session 用 **Opus 5**。任务本身机械（删一个字段），但**判断密度不低**：要从"没有地方体现"推出数据契约层改动、要识别 `figma.mixed` 是设计本意而非违例、要在样式污染后反推继承规则。中途若换低配模型，最可能的失败点是 G1——把整行刷成单一字体后"看起来正常"就收工。**建议同类任务（改既有交付 + 需要跨层同步语义）继续用 Opus。**

## 8. 给团队的 action items

1. **owner**：决定 §6 三条是否升为 tvu-design-system 规则真源。
2. **owner**：NDI 真实发现源名清单——拿到后可程序化批量替换 combobox 选项（仍 backlog）。
3. **owner**：4-Tx 绑定总览是否要做（新视图，与单路配置流有权衡）。
4. **owner**：是否就 Round 3.2 回 Jira 评论（默认不发）。

### 附录 · use_figma 改动统计（约数）

| 项 | 数 |
|---|---|
| use_figma 调用 | 11（含 3 次只读勘察 / 2 次机检） |
| 删除节点 | 8（`Frame 38` ×8，连同其 label + Input instance 子树） |
| 位移节点 | 14 + 4（WebR 参考） |
| 改写文本节点 | 10 |
| resize | 2（UX 卡 973→978、states Section 3367→2975） |
| 截图亲验 | 6 |