# MicroApps Console · Figma Mockup 复盘（2026-05-09） > **目的**：内部分享 — UX 设计师用 `@TVU mockup` 在 Figma 里画 Master Console / My Sessions 监控页 mockup + 交付标注的真实过程复盘 + 高效对话建议。 > **场景**：Master Console (MC) / My Sessions (MS) 是 MicroApps 产品的两个核心页面，单 session 一天内完成从 mockup 调整到 10 条 UX 交付标注 v1 → v8 重写。 --- ## TL;DR - **总轮次**：~8 轮 user feedback（v1 → v8 重写） + 50+ use_figma calls + 24 个 health wrapper component swap - **最终交付**：MC + MS 双页 Figma mockup（fileKey `DtZcMkhNy6qh6jbQQnhreQ` node `2956:4544` 区域）+ 10 条 UX 交付标注（7 MC + 2 MS + 1 global Responsive）+ 13 条 polyline 折线连接器 + Health Indicator 全部对齐 TVU UX Design System 库色 token - **核心 process gap 数**：4 条核心规则回流到 TVU 真源（library key 显式 filter / 颜色含义不假设 / spec 真源先看再画 / connector half-auto pattern） - **关键 insight**： > **画 mockup 前没读 PRODUCT_CONTEXT.md spec 真源，前 7 轮全部是"先画再被纠正"。v8 拿到 spec 后一次全量重写 10 条标注 — 前 7 轮的细节工作其实大部分作废**。 --- ## 1 · Session 概览 ### 任务起点 MC / MS 已有早期 mockup，但 UX 交付标注是中文 / 内部提案混合的散框，连接线乱、内容陈旧。需要：(1) 全英化、(2) 加锚点连接线指到具体 UI 元素、(3) 按真实 PRD 内容重写、(4) Health Indicator 颜色对齐 TVU 真源库。 ### 最终落地 **Figma**： - 删 11 个旧框（5 原始 + 6 遗漏的中文/内部提案） - 新建 10 个 anchored 卡片：A1 Page Access / A2 Filter+Defaults / A3 Column Visibility / A4 Action Icons / A5 Auto-refresh / A6 MS Page Access / A7 Search / A8 Responsive / A_State / A_MicroAppsOrder - 13 条 polyline 折线连接器（VECTOR + vectorNetwork，端点 ARROW_LINES）— 设计 mode 不支持原生 Connector 的 workaround - 24 个 health wrapper component swap 到 TVU UX Design System 库 **Process artifacts**： - 3 份 decisions 文档落地（[2026-05-09-master-console-readonly.md](../decisions/2026-05-09-master-console-readonly.md) / [auto-refresh-pause-button.md](../decisions/2026-05-09-auto-refresh-pause-button.md) / [session-health-indicator.md](../decisions/2026-05-09-session-health-indicator.md)） - [docs/specs/2026-05-09-design.md](../specs/2026-05-09-design.md) — 设计快照 - 1 条关键规则回流到 TVU 真源（library 搜索必须 `includeLibraryKeys` filter） --- ## 2 · 时间线 / 主要迭代（按用户 feedback 顺序） | # | 版本 | 用户 feedback 触发 | 改动量 | 性质 | |---|---|---|---|---| | 1 | v1 | "把交付说明全英化、加 anchor 连接线" | 删 11 旧框 + 建 8 anchored 卡片 + 10 VECTOR connector | 起手清场 | | 2 | v2 | "连接线全是直线对角穿越 UI 太乱" | 删 10 直线 + 改折线（水平→垂直→水平 elbow）+ 每标注独立 exitX 通道 | AI 默认偷懒走直线 | | 3 | v3 | "标注还缺 6 项" | 补 A2 default filter / A4 7-action inventory / 新建 A_State / A_MicroAppsOrder | AI 漏读需求列表 | | 4 | v4 | "连接线 abs 位置错位" | 用 relativeTransform 替代 v.x/y 修绝对坐标 bug + 标注加宽 30% + 间距 3x | AI 工程化 bug | | 5 | v5 | "A_State 颜色完全写反了"（用户验收抓出）| 从页面真实组件抓 fill 真值 + setRangeFills 渲染 ● dot 为真色 | **AI 凭印象写颜色，没 probe 真值** | | 6 | v6 | "Console 是纯查看，没 New Session / 没 Clone / URL 不可编辑" | 隐藏 8 个 + New Session 按钮 + 16 个 Clone 图标 + 5 个 URL placeholder → "—" | **架构理解错：MC 不是编辑器** | | 7 | v7 | "Health Indicator 颜色源对齐 TVU UX Design System 库（不是 TVU UX Library）" | 24 个 health wrapper 全 swap + 绑色 variable（Brand/Orange/Red） | **库混淆：两个库名很像** | | 8 | v8 | "按 PRODUCT_CONTEXT.md spec 真源全量重写 10 条标注" | A1-A8 + A_State + A_Order 全部重写 | **AI 前 7 轮都没看 spec 真源** | --- ## 3 · Top 5 Process Gap（按返工成本排序） ### Gap 1 · **画图前没有 read spec 真源，前 7 轮在猜** **实证**： - v1-v7 我按"已有 mockup + 用户口头反馈"画图，没有主动去读 [`MICROAPPS_PRODUCT_CONTEXT.md`](../MICROAPPS_PRODUCT_CONTEXT.md) - 直到第 8 轮用户明说"按 PRODUCT_CONTEXT.md 全量重写"，10 条标注全部推翻： - Enterprise → Company（产品术语错） - 状态机当 4 状态平铺 → 实际是 3 个 type-specific 状态机（A 红/绿/灰、B 蓝/灰、C 红/灰） - Action 当通用图标组 → 实际是 3-type Action Cluster matrix（Bidirectional / Analyzer / Generator） - 伪造 default sort 规则 / 伪造 XL/L/M 4 挡 breakpoint - 用户原话："spec 真源帮我对齐了所有这些" **返工成本**：~6 轮迭代的标注内容作废（v1-v7 的细节工作约 80% 在 v8 重写中被覆盖） **原因**：AI 默认信任"在场 UI + 用户口头" > "未读 spec 文件"。`@TVU mockup` skill 没有在 Phase 0 强制 read product context 真源。 **✅ 解决方案**： - **当下修复**：v8 一次性按 PRODUCT_CONTEXT.md 全量重写 10 条标注 — 术语对齐（Enterprise→Company）/ 状态机重做（3 个 type-specific）/ Action matrix 重写（3-type Cluster）/ 删除伪造的 default sort + 4 挡 breakpoint - **长期防护**：`@TVU mockup` skill Phase 0 加强制步骤「**Pre-mockup spec read**」 — 消费 product 必须先读 `docs/MICROAPPS_PRODUCT_CONTEXT.md` 或同等真源，把"产品术语 / 状态机 / cardinality"清单写出来贴给 user verify 后再开始画；未读 spec 不允许调用 `use_figma` - **真源落地**：⏳ 待回流到 `tvu-design-mockup` skill SKILL.md（累积证据：Video Sync + 本 session 已 2 例） --- ### Gap 2 · **A_State 颜色凭印象写，没从页面抓真值** **实证**：v3 我新建 A_State 标注块，把每个状态对应颜色凭"应该是 X"写进去 — 红=危险=on-air、绿=安全=preview。用户验收（v5）抓出"颜色完全写反了"： - On-air = **#ea4233 红**（高危直播） - Preview = **#2fb54e 绿**（彩排预览） 我自己之前默认 on-air = 绿（运行中）— 错。修复时用 `getFills` 从页面 Counter Pills / State Pill / Card badge 抓真色，再 setRangeFills 让 ● dot 渲染真色。 **返工成本**：A_State 整段内容重写 + cross-context 红绿色复用警告补段 **原因**：在 UX 交付里写"颜色含义"等同于在写产品规范 — 不允许凭印象。颜色 token 是产品决策，不是 AI 猜测。 **✅ 解决方案**： - **当下修复**：从页面真实组件 `getFills` 抓 4 个状态色（On-air=#ea4233 / Preview=#2fb54e / Analyzing=#3892f3 / Inactive=#7b7b7b），用 `setRangeFills` 让每行 ● dot 渲染为该状态真色；补 Card-badge 不同调色板说明 + cross-context 红绿色复用警告（State Pill vs Action Icon 红色含义不同） - **长期防护**：写任何产品语义颜色描述前**强制 probe**目标节点真值，禁止凭"应该是 X"或 UX 常识填空；probe 完贴出"我抓到的真值是 X"给 user verify 再写进交付 - **真源落地**：✅ 已落 TVU 真源 [`mockup-conventions.md`](../../../tvu-design-system/docs/internal/mockup-conventions.md) "颜色含义不假设"规则 --- ### Gap 3 · **TVU library key 混淆：两个名字很像的独立库** **实证**：v7 Health Indicator 改色，我搜 library 默认拿到结果就用，没注意到结果跨"TVU UX Library"（旧）和"TVU UX Design System"（新）两个 library 实例。两者 component 名几乎一样但 `libraryKey` 不同，混用会导致 swap 失败 + 引用错库 component。 24 个 health wrapper 全 swap 一遍才矫正。 **返工成本**：24 个 component instance swap + decision log + PRODUCT_CONTEXT 双向更新 **原因**：search_design_system 默认跨库返回结果，没默认锁定单库。AI 不会自动校验 libraryKey。 **✅ 解决方案**： - **当下修复**：24 个 health wrapper 全 swap 到 TVU UX Design System 库的 component instance；Success/warning/Error 三态绑色 variable（`UX/Brand/Brand` / `UX/Orange/Default` / `UX/Red/Default`） - **长期防护**：`search_design_system` 任何写操作前必须**显式传 `includeLibraryKeys`** 锁库；search 后写"我从 `` 库拿到 X" 给 user verify - **真源落地**：✅ 已落 TVU 真源 retrospection [`2026-05-11-library-key-confusion.md`](../../../tvu-design-system/docs/internal/retrospection/2026-05-11-library-key-confusion.md) + `figma-technical-reference.md` --- ### Gap 4 · **Master Console = 监控页**这件事我做完 mockup 才被纠正** **实证**：v1-v5 我把 MC 当成"和 MS 一样的 session 管理页"画，留了 8 个 + New Session 按钮 + 16 个 Clone 图标 + URL 可编辑 placeholder。v6 用户纠正："Console 是纯查看 / 监控 + 不可编辑 URL；New Session 和 Clone 只在 My Sessions 提供"。 **返工成本**：隐藏 8 + 16 + 5 共 29 个元素 + A4 标注重写 7-action inventory（按 MC vs MS 差异分列） **原因**：MC / MS 是 1:1 镜像还是 N:1 viewer/editor 这个 cardinality 问题，前 5 轮我当 1:1 镜像处理。和 [Video Sync 复盘 Gap 1](2026-05-20-video-sync-mockup-retrospect-internal-share.md) 完全同模式 — **架构 cardinality 必须前 3 轮内确认**。 **✅ 解决方案**： - **当下修复**：隐藏 8 个 + New Session 按钮 + 16 个 Clone 图标 + 5 个 URL placeholder → "—"；A4 标注重写为 MC（read-only viewer）vs MS（CRUD editor）两栏差异表 - **长期防护**：mockup session 起手必问 5 个 cardinality 问题：(1) 这页是 viewer 还是 editor？(2) 对象之间 1:1 / 1:N / N:N？(3) 状态机几个 state，谁能触发？(4) 默认排序 / 过滤是产品决策还是 AI 推理？(5) MC vs MS / Plan A vs Plan B 之间是镜像还是 viewer/editor？— 不答完不画图 - **真源落地**：✅ 产品 decision 已落 [`MicroApps/docs/decisions/2026-05-09-master-console-readonly.md`](../decisions/2026-05-09-master-console-readonly.md)；⏳ M-CARDINALITY 5 问规则待累积第 3 例 session 后写入 TVU `design-process.md`（已 2 例：Video Sync + 本 session） --- ### Gap 5 · **Figma design mode 不支持原生 Connector — 半自动 workaround 反复重做** **实证**：v2 改折线连接器，v4 发现 abs 位置错位（用 v.x/y 直接设导致页级绝对坐标错），改用 `relativeTransform` 修。13 条连接线后续在卡片移位时还要重画一次。 **返工成本**：~3 轮 connector 重绘 + 1 轮 abs 坐标 bug 修复 **原因**：Figma plugin API 在 design mode 不允许 `CONNECTOR` 节点（只 FigJam 支持），只能用 VECTOR + vectorNetwork 模拟。AI 第一次做时不知道这个限制，按 FigJam 经验直接试 Connector 报错才转向。 **✅ 解决方案**： - **当下修复**：用 VECTOR + vectorNetwork 双 vertex + 端点 `strokeCap = ARROW_LINES` 模拟 connector；abs 坐标用 `relativeTransform` 替代 v.x/y 直设（保证页级绝对坐标正确）；每条连接线用 `setSharedPluginData('uxAnno', 'meta', JSON)` 存 anchor 元数据 - **长期防护**：design mode 写 connector 类需求时**先查 `figma-technical-reference.md` Connector workaround 段** — 不允许凭"FigJam 经验"直接试 CONNECTOR；半自动 routing pattern（"用户拖节点 + 跟我说 rebuild" → 脚本读 metadata → fetch 当前位置 → 重画）成为标准模式 - **真源落地**：✅ 已落 TVU 真源 `figma-technical-reference.md` "Connector workaround" 段 --- ## 4 · 高效对话 5 条建议（按 ROI 排序） ### 给 UX / PM（提需求方） **(1) 第一句话就交 spec 真源文件路径** — 不要等 AI 画完 7 轮再说"按 PRODUCT_CONTEXT.md 重写"。 - ❌ 反例："给 MC / MS 加交付标注，全英化" - ✅ 正例："给 MC / MS 加交付标注，全英化，**先读 docs/MICROAPPS_PRODUCT_CONTEXT.md §3-5 的产品术语 / 状态机 / 3-type action matrix，确认理解后再画**" **(2) 颜色 / 术语 / 状态机是产品规范，要求 AI probe 真源**，不允许"AI 凭设计直觉填值"。 - ❌ 反例：让 AI 自己决定 on-air = 红还是绿 - ✅ 正例："State 列颜色从页面 Counter Pills 节点 getFills 抓真值，不要凭印象写" --- ### 给 AI 协作流程 **(3) Phase 0 强制 read product context 真源** — `@TVU mockup` skill 应在画图前一步检查 cwd `docs/` 下是否有 product spec 文档，有就先读，没有就询问。 **(4) 凡是写产品语义（颜色含义 / 状态名 / 术语）都必须 probe 现有节点真值** — 不允许"based on common UX patterns" 这种推理填空。 --- ### 给 PM / Stakeholder（review 方） **(5) Review checklist 必含 4 项 cardinality** — 不依赖 AI 自检： 1. 这页是 viewer 还是 editor？（read-only vs CRUD） 2. 对象之间是 1:1 / 1:N / N:N？ 3. 状态机有几个 state？每个 state 谁能触发？ 4. 默认排序 / 默认过滤是产品决策还是 AI 推理？ --- ## 5 · 规则回流清单 ### ✅ 已落回流（本 session 写入真源） | 规则 | 真源文件 | 简述 | |---|---|---| | Library 搜索必须 `includeLibraryKeys` filter | `tvu-design-system/docs/internal/retrospection/2026-05-11-library-key-confusion.md` + `figma-technical-reference.md` | search_design_system 跨库返回，写操作前必须显式锁库 | | 颜色含义不假设 / 必须 probe | `tvu-design-system/docs/internal/mockup-conventions.md` | 写产品语义前 getFills 抓真值 | | Design mode Connector workaround | `tvu-design-system/docs/internal/figma-technical-reference.md` | VECTOR + vectorNetwork + ARROW_LINES + plugin metadata | | Master Console = read-only viewer | `MicroApps/docs/decisions/2026-05-09-master-console-readonly.md` | 产品层 decision，非通用规则 | ### ⏳ 待回流（下 session 完成 / 等触发条件） | 规则 | 目标真源 | 触发条件 | |---|---|---| | Phase 0 强制 read product context | `tvu-design-mockup` skill SKILL.md | 累积 2+ session 印证（Video Sync 已有，本 session 第 2 例）→ 可上 | | M-CARDINALITY 起手必问 5 问题 | `design-process.md` | 累积 3+ session 印证（Video Sync + 本 session 已 2 例）| --- ## 6 · Model 选型实证 | 模型 | 适合场景 | 本 session 起作用时刻 | |---|---|---| | **Opus 4.7** | 主对话 / 架构推理 / 自审 / 跨文件回流 | v8 重写 — Opus 一次扫完 PRODUCT_CONTEXT spec 后能同时对齐 10 条标注的术语 / 状态机 / cardinality / 排序规则 | | **Sonnet 4.6** | 执行 batch 改动 / probe / 简单 swap | v2 改 10 条直线 → 折线、v7 swap 24 个 health wrapper component，纯执行步骤可委托 Sonnet | | **Haiku 4.5** | probe / 简单查询 | 不适合主对话；可用于"读 spec 真源摘 5 个术语"这种轻 probe | **Hybrid 推荐**：Opus 做 plan owner（v8 全量重写 + 颜色含义 / cardinality 决策） + Sonnet subagent 做 executor（component swap、connector 重绘、坐标 batch fix）。本 session 全 Opus 跑，估计 Hybrid 可省 40% Opus token。 --- ## 7 · 给团队的 3 个 Action Items **1. 任何 `@TVU mockup` session 起手交付 spec 真源** > UX / PM 在 task 第一句话里给 `docs/MICROAPPS_PRODUCT_CONTEXT.md` 或同等 spec 的具体路径 + 段号。不依赖 AI 主动找。 **2. UX 交付标注的颜色 / 状态 / 术语字段全部走 probe，不允许凭印象** > AI 写产品语义前必须 `getFills` / `getCharacters` 抓现有节点真值，写完贴出"我抓到的真值是 X"给 user verify。 **3. Cardinality checklist 上墙** > Review session 时先过 4 问（viewer/editor、1:1/1:N、状态机数、默认规则来源），不在 v6 / v7 / v8 时才发现。 --- ## 附录 A · 改动统计 | 改动类型 | 次数 | |---|---| | Figma anchored 标注卡片（建/重写）| 10 | | Polyline 连接器（建/重画）| 13 | | Component instance swap (health wrapper) | 24 | | 颜色 token 绑定（Brand / Orange / Red） | 3 | | Decision 文档 | 3 | | Library key 修正 | 1 库（24 instance）| ## 附录 B · 关联文档 - [MicroApps Console Code 复盘 — 2026-05-13](2026-05-13-microapps-console-code-retrospect-internal-share.md) — 配对的 code session（HTML demo + Plan B Vue） - [Video Sync 多 session 复盘 — 2026-05-20](2026-05-20-video-sync-mockup-retrospect-internal-share.md) — 同模式的 cardinality / spec-first 教训第 2 例 - [`docs/MICROAPPS_PRODUCT_CONTEXT.md`](../MICROAPPS_PRODUCT_CONTEXT.md) — v8 全量重写的 spec 真源 - [`docs/handoffs/2026-05-11-handoff.md`](../handoffs/2026-05-11-handoff.md) — 配对的 code session handoff --- > **复盘人**：Claude Opus 4.7 (1M context) + nancyzeng (UX) > **复盘时间**：2026-05-21 > **目标受众**：TVU 内部 — UX team + AI 协作流程改进 > **联系**：真源文件全部在 `tvu-design-system` repo 内可查