---
id: v4-2285-2286-embedded-audio-routing
title: "V4-2285 + V4-2286 Embedded Audio：手搓色绑库现成变量收尾"
doc_type: handoff
status: QA
last_updated: 2026-06-22
sources:
  - { type: jira, ref: "V4-2285", url: "https://tvunetworks.atlassian.net/browse/V4-2285" }
  - { type: jira, ref: "V4-2286", url: "https://tvunetworks.atlassian.net/browse/V4-2286" }
figma:
  file: rJJjWWs51n2iFOlCIC7aYG
  nodes:
    - { id: "6748:443", label: "Embedded Audio delivery section", url: "https://www.figma.com/design/rJJjWWs51n2iFOlCIC7aYG/Config-T---Local-UI---v7.7---8.0--20240220?node-id=6748-443" }
    - { id: "7333:1296", label: "Embedded Audio X/Y matrix", url: "https://www.figma.com/design/rJJjWWs51n2iFOlCIC7aYG/Config-T---Local-UI---v7.7---8.0--20240220?node-id=7333-1296" }
---

# Handoff — V4-2285 + V4-2286 Embedded Audio：手搓色绑库现成变量收尾

> **Jira**: V4-2285（外部音频嵌入任意 SDI）+ V4-2286（4/8CH 外接设备）
> **Figma**: `rJJjWWs51n2iFOlCIC7aYG` · page `6716:2`（V4 → To be confirmed，index 5）· 集成页 `6716:288` · 主矩阵 `7333:1296`
> **日期**: 2026-06-22（续 2026-06-18 X/Y 矩阵 session）· consumer 无 git repo，落 `TVU Pack/docs/`
> **配套**: design-record `specs/2026-06-04-v4-2285-2286-embedded-audio-routing-design-record.md` · 复盘 `docs/2026-06-22-...-retrospect-internal-share.md`

---

## 1. 背景 / 上下文

X/Y 矩阵交付已接近完成（7 矩阵全撑宽 480 对齐 Audio Mapping dropdown）。本次续跑专项 = 把三处**手搓颜色**改绑 TVU DS **库现成变量**（用户决策：「用其他现成的颜色变量」，不手搓 hex / 不建 local / 不推库新增）。X/Y 锁定模型、文字范式（`CH 1-2` 带空格、无 Src/Output 前缀）不变。

---

## 2. 改动清单（use_figma，全经 get_metadata 验证）

库变量来源 = [`binding-source-map.json`](../../../tvu-design-system/figma-data/normalized/binding-source-map.json)（collection `TVU Design System` 1558:94780，Dark/Light 双模），经 `figma.teamLibrary.getVariablesInLibraryCollectionAsync` + `importVariableByKeyAsync` 导入产品文件后绑定。

| 用途 | 节点 | 绑定的库变量 | paint opacity | 状态 |
|---|---|---|---|---|
| Hover 十字白（竖+横条） | `7417:1175` `7417:1176` | `UX/Grey/grey-1 #FFFFFF` | **0.10** | ✅ 本次绑定 |
| 选中绿底 cell（Hover 卡 6 + state2 1） | `7349:685/696/698/732/743/784` + `7364:770` | `UX/Brand/Brand`（#2fb54e/Dark） | **0.12** | ✅ 本次绑定 |
| Tips 灰文字（Audio device / Transmitter / N pairs / 状态说明） | 34 处（全文件） | `Color Type/Text/Tips`（=`--text-tips`，#9e9e9e/Dark） | 1 | ✅ 扫描证**早已绑定**，无需改 |

> checkbox 组件实例内部的 `Rectangle 4`（`I…;4600:14666;374:446`，绿勾标记）已绑库变量、属组件自带，**未动**。

**⚠️ 工程坑（回流候选）**：`figma.variables.setBoundVariableForPaint(paint,'color',v)` 返回的新 paint **把 opacity 重置为 1**，且**同一脚本内** `fills[i] = {...boundPaint, opacity:0.12}` 的 spread 覆盖**也不生效**（写回后读仍为 1）。必须**绑定完成后、用独立赋值** `fills[i].opacity = x; node.fills = fills` 设回——hover(0.10) 与绿底(0.12) 两次独立复现。

---

## 3. Rule checklist（机器输出 — 局部 `--node` audit，绕 conformance 总闸 sync 撑爆）

```
# audit-mockup-colors.mjs --file rJJjWWs51n2iFOlCIC7aYG --node 7349:661
Warning: /variables/local returned 403 (likely non-Enterprise plan).
         Bound-variable names will be unresolved; C2/C3 may under-report.
✅ M-COLOR audit pass
   C1 icon-fill-bound-variable     scanned, 0 violations
   C2 hover-state-bound-variable   scanned, 0 violations   ← 本次 hover 十字 + 绿底绑定合规验证
   C3 bg-vs-text-grey-discipline   scanned, 0 violations

# audit-mockup-binding-fidelity.mjs --file rJJjWWs51n2iFOlCIC7aYG --node 7349:661
Warning: /variables/local 403 (non-Enterprise); B-SEM 将 under-report.
❌ D16 binding-fidelity audit FAIL (§M49.1 / §C5)
   B-TYPO  — text-style (21)   — 文字裸 fontSize 未套 Text Style（CH 1-2 / Transmitter N / N pairs / 列头…）
   B-SCALE — off-scale (63)    — spacing/radius 未绑变量（itemSpacing=6 / radius=6 / padding=10·6 …
                                  含大量 checkbox 组件实例内部 Rectangle radius 1.2/0.4/10 = consumer 不可改）
```

**判读**：
- ✅ **M-COLOR 全 0 违例** = 本次颜色绑定改动**自检通过**（C2 hover-state 正是验证目标）。
- ❌ **binding-fidelity 的 B-TYPO/B-SCALE 是预存项，与本次颜色改动无关**（本次只改 fill 颜色，未碰文字/间距）。值得注意：记忆里 binding-fidelity 因「sync 撑爆跑不了」被 defer，但**局部 `--node` audit 成功跑通**绕过了 sync，首次暴露这些预存缺口。
- 403 non-Enterprise → C2/C3/B-SEM under-report，是已知 plan 限制。

---

## 4. 遗留 / 已知问题

1. **binding-fidelity B-TYPO(21) + B-SCALE(63)** — 预存、属 §M49.1 更大「binding 完整度」scope（文字套库 Text Style + 间距/圆角绑 Number Var）。非本次颜色任务 scope；部分 B-SCALE 为组件实例内部不可改。**待 owner 拍是否另开任务**（`binding-source-map.json` 含 textStyles key 可 `setTextStyleIdAsync`）。
2. **conformance 总闸 `audit:mockup-conformance`** — 对 66-page 超大产品文件 `JSON.stringify` 撑爆（RangeError），本次用局部 `--node` audit 绕过；design-system 侧已知 backlog（局部同步支持，maintainer scope）。
3. **overlap dialog × state2** — DS Notification 弹窗居中 state2 = modal 合法叠加，机检 false positive（工具不识 modal），继承自上 session，接受。
4. **F2 次要建议 defer** — 16px checkbox 点击热区 → dev handoff；N pairs 改「used/total」动态计数。
5. **凭证会过期** — `.env` `FIGMA_TOKEN`（PAT）/ MCP OAuth 均会过期；起手 `whoami` 测活。

---

## 5. 续跑入口

- **交付 PM（6-JIRA gate）**：@PM Slack `UX design (mockup) updated — please review` + Figma **Section** smart link（`6748:443`）+ FYI 待开发负责人 + ADF + accountId 真 mention；关联 V4-2285 / V4-2286（Jira 组件 `6750:11` / `6750:21`）。草稿先给 owner 过目再发。
- **或** owner 拍 §4.1 binding-fidelity 是否另开任务补 binding 完整度。
- 起手纪律见记忆 `embedded-audio-xy-matrix-progress.md`（只信 get_metadata + 自截图 / 脚本只 return 不 throw / page 移位检查 / 局部 audit 跑法）。

---

## 6. 2026-06-23 设计迭代增量（外接未接入 = 内置音频 + 8CH 展示）

用户两个设计反馈，已落地 + 自检全绿：

- **① state1 → 内置音频默认态**（`7364:661`）：外接 Audio Device 未接入不再报 warning，回退内置音频继续可用。删 warning 条、super-head 改 `Built-in audio`、2列→1列 CH 1-2 撑宽 312 保持卡 480、cell opacity 0.35→1 恢复可交互、内容上移卡高 597。
- **② 8CH = 4 列示意**（`7445:1116`）并入 UX 卡 `7350:877`「Source channels」小节：super-head `8-channel device` + 列头 CH 1-2/3-4/5-6/7-8（各78）+ Tx1 代表行 4×4 checkbox。clone state1 改列数（继承库 checkbox/字体/颜色绑定）；UX 卡 auto-layout 自动排版增高 807→1115。
- **③ state5 → 也回退内置音频**（`7388:1062`，用户拍板与 state1 统一）：删 CH3-4 列+单列撑宽、super-head `Built-in audio`、清 2 绿勾（原嵌入清除）、提示条去橙框+icon hidden+中性灰文字 `External device disconnected — switched to Built-in audio; previous embedding cleared.`（绑 Color Type/Text/Tips）。
- **④ UX 卡 states 文字**（7350:884 EN / 885 ZH）"Device disconnected → warning" 改为"外接未接入 → 回退内置音频(2CH→1列)不告警"。
- **至此 V4-2286「2/4/8CH 动态列数」三态全可视化**：2CH=state1 / 4CH=主矩阵 7333:1296 / 8CH=UX 卡示意。

**Rule checklist（机器输出）**：`audit-mockup-colors --node` state1 `7364:661` / 8CH `7445:1116` / state5 `7388:1062` 均 ✅ M-COLOR C1/C2/C3 0 违例；`audit-mockup-library-origin --node 7445:1116` = 16 checkbox 全库组件（key c9339f0db1…）。

**工程坑（回流候选）**：① 矩阵行 = HORIZONTAL auto-layout，删列后容器 HUG 收缩 → 须先 `container.layoutSizingHorizontal='FILL'`(456) 内部 cell 才撑到 312；个别行 FILL 误算成 156 → 改 FIXED 312 强制（checkbox absX 一致验证对齐）。② root `counterAxisSizingMode=AUTO`(HUG) 时长文字撑宽整卡到 636 → 须设 FIXED 480。③ `throw` 回滚不彻底实证：findAll 撞 checkbox 内嵌实例触发未捕获报错致脚本 throw，但其中部分 `remove()` 已落地未回滚（删 CH3-4 时 6/10 已删）→ 印证"脚本只 return 不 throw" + 操作后 get_metadata 盘点真实状态。

**design-record 已同步**内置音频回退 + 2/4/8CH 动态列数（`specs/2026-06-04-…-design-record.md §7`）。