# Retrospect — Media Service UR「Multi-channnel to 1 output」Source 稿修正（MPTS program 映射）

- **日期**：2026-07-30
- **产品**：Media Service UR（消费侧，Figma file `HvU7TXVvJGQ8AoS9Z1Jd10`，无本地 repo）
- **落点节点**：page `Multi-channnel to 1 output`（`1373:74`）
- **触发**：Slack 讨论（Scripps POC，MPTS 多节目输出）→ 用户指出 source 稿 program id / PID 展示错，要求修正

---

## 1. TL;DR

- **最根本的错（Source vs Destination）**：整个 session 都当作 **Source** 侧在做（改 `Source_multi-channels` 弹窗），但 MPTS 多节目输出实际是 **Destination（输出）侧** 的功能。**Source 与 Destination 在 TVU 产品里是两个不同的东西、不同的编辑器**。最终稿把功能落在真实的 `Destination_srt listener` / `Destination_issp pull` 全功能编辑器里，且被 `Multi Channels` 开关 gating。这是比后面所有颜色/字号问题都更前置、更贵的误读。
- **第二类错（把简化 mock 当真实屏 + 需求臆造）**：我在一个简化壳里自造，臆造了 Video/Audio PID 列（实际最终稿只有 Channels / Service ID 两列），删掉了本该改对的下拉子行（最终稿保留为 Master/Backup X/Y 主备）。详见 §3 对比表。
- **第三类错（保真度执行）**：颜色写死 hex、字号拍脑袋、文字样式没绑，多轮返工。用户明确"这个问题我们说过很多次了"。
- 关键 insight：**Phase 0 起手必须先确认 (a) 这功能属于 Source 还是 Destination、(b) 落在哪个真实编辑器/入口、(c) 有没有 gating——再动手**；建文字节点前必须先 `search_design_system` 拉齐 color variables + text styles。而不是拿到一个 node 就在简化壳里闭门造、先写死值等 review 逐条纠。

## 2. 时间线（主要迭代）

| # | 阶段 | 用户 feedback 触发 | 改动量 |
|---|---|---|---|
| 1 | 诊断 + 方案 | program id 搞错 | 定位 GUID/非法 PID 问题，方案 B（下拉多选 + 表格） |
| 2 | 首次落地 | — | 下拉瘦身 + Programs 表 + 两态 + 校验 + M23 注释 |
| 3 | 布局细化 | 列太挤 / 要多选 chip / 空态占位 | 列间距、chip 态、空态占位行 |
| 4 | 分隔线 + 空态语义 | 行要分隔线 / 空态别占两行 / 校验要背景色 | 行分隔线、空态提示文案、校验暗底卡 |
| 5 | **颜色绑定（返工）** | 所有字体色号要绑 TVU 变量 | 12 个节点从写死 hex 改绑语义变量 |
| 6 | **排版绑定（再返工）** | 提示 12号 / 表格文字没绑规范 / 字号哪来的 | 全部改绑 `Roboto/14 body`·`Roboto/12 tips` 文字样式 |
| 7 | 术语 + 占位修正 | Channel→Program、Program Number→Service ID、有值态别显占位 | 重命名 + 占位/实值语义修正 |

## 3. Top 过程 gap（按返工成本 / 根本性排序）

### 我的版本 vs 最终稿（对比）

| 方面 | 我做的 | 最终稿 | 误读 |
|---|---|---|---|
| **Source / Destination** | 当 Source 做（`Source_multi-channels` 弹窗） | **Destination** 全功能编辑器（`Destination_srt listener` / `issp pull`） | 搞错了功能归属的产品侧 |
| **落地上下文** | 简化壳里自造 | 真实编辑器 + `Multi Channels` 开关 gating（Server/Passphrase/Multi Receiver SRT/Seamless Switching/Encoding Profile/Media Analyzer…） | 没对到真实屏、漏了 gating 开关 |
| **下拉子行** | 整行删掉 → 纯「Channel 1」复选 | 保留子行 → 「Master: Channel 1 · Backup: Channel Y1」（X/Y 主备源对） | "内容错"当"删元素"，丢了该改对的结构 |
| **表格列** | 4 列 Program / Service ID / **Video PID / Audio PID** | **2 列 Channels / Service ID** | 从 Slack 技术讨论臆造 PID 列，超范围 |
| **第一列命名** | Program / Program 1、2 | Channels / Channel 1、2 | Channel→Program 改反 |
| **状态区分** | 空态 / 有值态 | `Multi Channels` 开关 on/off 门控 | 没识别 gating 交互 |
| **校验** | 仅 duplicate | duplicate + invalid（越界 1-255） | 场景不全 |

### 根因（按根本性排序）

1. **没在起手确认功能属于 Source 还是 Destination（最根本）**。Source 与 Destination 是 TVU 产品里两个不同的编辑器/概念。用户初始随口说"source 稿"，我照单全收，且没把"MPTS 是输出概念 → 更可能是 Destination"这个我自己都意识到的点提出来核对。**结果整条链路搭在错误的产品侧。**
2. **把简化 mock 当成真实产品屏 + 从相邻对话臆造 UI**。拿到一个 node 就在简化壳里闭门造，没先扫整页 / 问"是否进真实编辑器、有没有 gating"；把 Slack 里 Mateus 提的 PID（技术存在）直接映射成 UI 列（本版不要）。"技术存在 ≠ 本次 UI 范围"。
3. **"内容错"的反射是"删"而非"改对"**：下拉子行该保留并改成 Master/Backup，我却清空成裸复选。
4. **保真度执行（次要但反复）**：文字颜色写死 hex、字号拍脑袋(13/16)、表格 cell 只绑色未绑文字样式。根因=建节点前没 `search_design_system` 拉齐 color variables + text styles。
5. **占位/空态语义反复**：placeholder(1-255) 一度放进有值态；空态先做 2 行 `—` 占位再改提示文案。

## 4. 工程踩坑（可复用）

- **组件文本字体 = Helvetica Neue，本机无此字体** → 编辑组件实例文本前必须先把 fontName 覆盖为 Roboto（全稿字体），否则 `loadFontAsync` 抛错。
- **`component_set` 必须用 `importComponentSetByKeyAsync`**，误用 `importComponentByKeyAsync` 报 "Component not found"。catalog 里记的 "Library key" 实为 set key。
- **`createAutoLayout()` 默认白色底** → 叠在暗色容器上要 `fills=[]`（已在 STATUS 多次记录，本次又踩）。
- **vector 连线**：更新已存在 vector 的 `vectorPaths`（绝对坐标）前必须先 `node.x=0; node.y=0`，否则新坐标叠加旧 offset → 线飘走。
- **实例 slot 投影节点不可删只能 `visible=false`**：下拉瘦身靠隐藏 + auto-layout 自动收拢，不是删除。
- **instance slot 内改 fontName 会使文本节点句柄失效** → 设 fontName 后需重新 `findOne` 再设 characters。

## 5. 给团队的高效对话建议

- **提需求方（UX/PM）**：一次把"术语 + 状态(空/有值) + 字段类型(只读/可编辑) + 占位规则"讲清，能省 3-4 轮往返（本次这些是逐轮挤出来的）。
- **AI 协作**：涉及 TVU 产品文字，AI 起手第一步应是 `search_design_system` 拉 text styles + color variables，先建"规范映射表"再落地节点。本次教训已回流 STATUS + 本文件。

## 6. 待回流规则

| 规则 | 真源文件 | 简述 | 状态 |
|---|---|---|---|
| **Source/Destination 前置确认** | ✅ `Mediahub/docs/PRODUCT_CONTEXT.md §0`（起手须知 callout） | Mockup 起手必须先确认功能属于 **Source 还是 Destination**（MediaHub 里是两个不同编辑器/字段/动作语义）+ 落在哪个真实编辑器 + 有无 gating，再动手。不拿用户随口的"source/destination"字面照单全收——尤其"输出/MPTS/推流"类默认是 Destination。**属产品级规则（非通用 TVU），归 Mediahub 而非 design-process.md。** | ✅ 已回流 2026-07-30 |
| 文字双绑（text style + color variable） | ✅ `mockup-conventions.md §M-COLOR C7`（+ 共用 Acceptance 人工核查 + Quick Reference 触发行） | 文字节点必须同时绑库文字样式与颜色变量，缺一违规 | ✅ 已回流 2026-07-30（**本条在原分支上编号为 C6；2026-08-11 并入 master 时因 master 的 C5/C6 已被占用而重编号为 C7**） |

## 7. Model 选型

本 session 用 Opus，胜在长链路多轮迭代 + 大量 use_figma 增量修正下保持上下文一致；短板是保真度纪律需靠规则强约束（起手 discovery），否则会先产出再返工。

## 8. use_figma 改动统计（约数）

- 下拉隐藏节点：6 行 × 2 = 12
- 新建/绑定：Programs 表 3 张（有值/空/校验）× 4 列、helper/hint/错误文案、多选 chip、M23 注释 2 条 + 连线 2 条
- 颜色变量绑定：~14 文字 + 描边；文字样式绑定：24 cell + 4 提示文