# 协作复盘 · V4-1827 NDI 状态态补充（Round 3.1）+ 画布主题规则回流

> AI–用户协作过程复盘（内部分享用）。区别于实现层 handoff 与 TVU 工程 retrospect，本篇聚焦「人与 AI 怎么配合把这批状态态高效画出来 + 一条规则怎么回流」。
> 日期 2026-07-22 · 文件 Config-T `rJJjWWs51n2iFOlCIC7aYG` · 设计 Nancy + Claude (Opus 4.8)

---

## 1. TL;DR

- **总轮次**：~28 次 `use_figma` 写/读 + ~13 次截图亲验 + 2 次 `search_design_system`。
- **最终交付**：7 个 NDI 状态态帧（新 Section `7917:839`）+ 7 cyan caption + 交付层同步（Journey/UX 卡）+ 画布主题自适配 + 规则回流 commit `b30c8133`。
- **核心 process gap 数**：1 个高成本（坐标定位反复错，根因未探 frame `layoutMode`）+ 1 个中成本（icon slot 折腾）。
- **关键 insight**：**clone 来的 mockup 帧多是 auto-layout**——往里放绝对定位元素前必须先探 `layoutMode` 并用 `layoutPositioning='ABSOLUTE'`，否则 `absoluteBoundingBox` 相对坐标全错。这一个认知能省掉本 session 一半的返工。

---

## 2. Session 概览

- **起点**：用户问 backlog 还剩什么要补 → 确认「只补状态态」，4-Tx 总览与真实源名拎出。
- **中段**：起手协议（TodoWrite + 读真源 + M0/M48/M49 + 计划文件）→ brainstorm 拍板（组织形式 + 4-Tx 性质 + 反馈控件 + 注释粒度）→ 逐帧画 + 每帧截图亲验 → 交付层同步。
- **收尾追加**：用户发现画布是白色（异类）→ 引出「画布跟随 mockup 主题自适配」诉求 → 查证 M23.18 → 回流 §M23.18.1 + commit。
- **过程产物**：plan / design-record §7.5 / handoff §6 / STATUS §6 / memory / 本复盘。

---

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

| # | 阶段 | 用户 feedback 触发 | 改动量 |
|---|---|---|---|
| 1 | 范围确认 | "backlog 还有要补的吗" → "全补状态,4-Tx 拎出" | 7 态定稿、4-Tx 出局 |
| 2 | brainstorm 拍板 | 用户质疑 4-Tx 总览会割裂配置流 | 拆性质→拎出;反馈控件选 Message;注释用 caption |
| 3 | 骨架 + 7 帧内容 | （AI 每帧截图自查） | clone 7 帧 + 逐帧改；中途 3 次坐标错位自查修 |
| 4 | 交付层同步 | — | Journey/UX 卡 range 替换、design-record |
| 5 | 画布主题 | "为什么画布没用深色" → "根据主题自适配不写死" → "混合默认深色" | 画布 0.418 + 规则 §M23.18.1 回流 commit |

---

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

### G1（高）— 坐标定位反复错：没先探 frame `layoutMode`
- **实证**：帧④空态文本、帧⑤⑥ icon、帧⑧⑨ Message 三处都出现「设了 y=10 却落到 y=383 帧外」。
- **根因**：clone 自 NDI 帧②的态帧是 **VERTICAL auto-layout**；`appendChild` 的节点被 auto-layout 排到末尾，我却用 `absoluteBoundingBox`（含浮层溢出/塌缩）反推相对坐标，值不可靠。
- **返工成本**：帧④文本删重做、帧⑤⑥ icon 加了又删、Message 两次定位修 ≈ 4-5 次额外 `use_figma`。
- **回流落点（候选）**：figma-use gotchas 或 mockup-conventions —— **「往 clone 帧内放绝对定位元素前，先 `get_metadata`/probe `layoutMode`；auto-layout 帧内自由定位必须 `layoutPositioning='ABSOLUTE'`；不要用含溢出的 `absoluteBoundingBox` 反推相对坐标」**。（待 owner 判定是否够格回流；本 session 已在 memory 记为技术坑。）

### G2（中）— radio Icon slot 折腾后弃用
- **实证**：扫描/失败态想在 Drop down Item 的 Icon slot 放 loading/warning icon，swap 后 icon 不显示，来回 3 次，最终弃用改纯文案。
- **教训**：库组件的嵌套 slot（尤其 nested instance 内）swap 行为不稳时，**早点判断降级方案**（纯文案 + 状态色），而不是硬啃 slot。反馈态的 spinner/icon 本就属动效实现细节、可交 dev。

---

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

**给提需求方（UX/PM）**：
- **像 4-Tx 那样先抛 UX 顾虑**——用户一句「有了总览表再切单路会不会不流畅」直接避免了一个"做出来反而有害"的功能。**顾虑比需求更有价值**。
- 主题/皮肤类要求**一次说清适配规则**（"跟主题自适配、混合默认深色"）而不是只说结果（"用深色"），AI 能直接回流成规则、以后不再问。

**给 AI 协作流程**：
- **每帧截图亲验**是本 session 抓错的主力（3 次坐标错位全靠截图发现）——不要采信 use_figma 的"成功"返回。
- **用户提规则先查证真源、不凭记忆**：这次 M23.18 用户记成"画布匹配效果图"，AI 查证后厘清实际是"注释卡跟随所在区明暗"，避免了按错误记忆行事。

**给 review 方**：
- 状态态这类边界交付，最快的 review 是看那张 Section 全图（7 帧一屏）+ 对照 caption，不必逐帧点开。

---

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

| 规则 | 真源文件 | 简述 | 状态 |
|---|---|---|---|
| §M23.18.1 画布底色跟随 mockup 主题 | `tvu-design-system/docs/internal/mockup-conventions.md` | 探测 frame 主题 → dark→0.418 / light→#F5F5F5 / 混合→深色；禁写死禁留白画布 | ✅ commit `b30c8133` |
| clone 帧内绝对定位前探 `layoutMode` + 用 `ABSOLUTE` | figma-use gotchas / mockup-conventions（候选） | G1 根因；`absoluteBoundingBox` 含溢出不可靠 | 🟡 待 owner 判是否回流（暂记 memory 技术坑） |

---

## 7. Model 选型推荐

本 session 全程 **Opus 4.8 (1M)**。判断合适：涉及 ① 设计取舍（4-Tx 性质拆解、反馈控件同源）② 复杂 Figma Plugin API（auto-layout/slot/variant/range 字体）③ 规则查证 + 回流措辞。这些都需要较强推理 + 长上下文（跨 skill/真源/多轮截图），未见需要降级的机械段落。

---

## 8. 给团队的 action items

- [ ] **owner 定**：G1 的「探 layoutMode + ABSOLUTE」是否够格回流到 figma 域规则（够格则并入 figma-use gotchas / mockup-conventions）。
- [ ] **owner 定**：浅色主题画布基准 `#F5F5F5` 是否 OK（本 session AI 定的，缺浅色主题 mockup 样本佐证）。
- [ ] **owner 定**：Jira 是否就 Round 3.1 补一条评论（默认未发）。
- [ ] backlog 仍挂：NDI 真实源名清单（owner/域知识）· 4-Tx 绑定总览（新视图，待确认诉求）· LCD 侧 V4-2261。

### 附录 · use_figma 改动统计（约数）
- 写操作：建 Section 1 · clone 骨架 2 · 帧内容（④-⑩）~11 · caption 1 · resize/overlap 1 · Journey/UX 卡 2 · 画布 1 ≈ **19 写**
- 只读/probe：结构探查 ~5 · in-file 机检 1 · 画布/section 背景 probe 2 ≈ **8 读**
- 截图亲验 ~13 · `search_design_system` 2（Message / Tooltips / refresh icon）