# MicroApps Console — 产品上下文（AI Session Handoff）

> **用途**：新 AI session onboard 时**第一份必读**。把 MicroApps Console 产品的领域知识、UX 决策、组件库引用、关联文档串起来。
>
> **最后更新**：2026-05-09（Figma mockup 4 frame 交付完成 + 设计规约 M11-M20 落仓库 commit `68fc376c`）。
>
> **互补文档**：本目录另有 [`2026-05-09-design.md`](./2026-05-09-design.md) — 单 HTML demo 的工程实现 spec。本文件偏**产品领域 + UX 决策**，那份偏**实现细节**。

---

## 0. 起手 30 秒概览

- **产品**：MicroApps Console = TVU 直播 / 媒体处理基础设施的**监控 + 操控台**
- **用户**：广播工程师 / 制作公司 / 直播运营 admin（不是消费级）
- **核心场景**：实时监控 N 个 MicroApp 服务跑的 sessions（输入流/输出流/分析任务），做启停 / 切播 / 故障处理
- **当前阶段**：UX mockup 完成（Figma 4 frame），HTML demo 在做（PM 预览）
- **关键产物**：
  - Figma 文件：[`Micro-Apps-20250923`](https://www.figma.com/design/DtZcMkhNy6qh6jbQQnhreQ/) (fileKey `DtZcMkhNy6qh6jbQQnhreQ`)
  - 4 mockup frame：MC 1920/1440 + MS 1920/1440（详见第 6 节）
  - 8 file-local 组件（详见第 8 节）
  - 设计系统：TVU UX Design System (libraryKey `lk-057f6ba0...`)

---

## 1. MicroApp 产品分类（按数据流方向 3 类）

| 类型 | 含义 | 数据流 | 当前已有的 MicroApp |
|---|---|---|---|
| **A. Bidirectional 双向广播** | 拿一路输入 → 加工 → 推一路输出 | input → process → output | AV Sync · Color Correction · Audio Remapping · Graphics Insertion · SCTE Insertion · Standard Conversion |
| **B. Input-only 仅输入分析** | 读一路输入做分析，不外送 | input → analyze | Media Analyzer |
| **C. Output-only 仅输出生成** | 凭空生成一路信号外送 | generate → output | Test Pattern Generator |

**Figma 数据现状（per [`mockup-conventions.md`](../../tvu-design-system/docs/internal/mockup-conventions.md) "已知 file-local 组件" 段）**：
- TVU library APP Icons set 已含：AV Sync / Color Correction（待补）/ Audio Remapping / Graphics Insertion（待补）/ SCTE Insertion / Standard Conversion / Media Analyzer / Test Pattern Generator（待补）
- 缺 3 个 variants（Color Correction / Graphics Insertion / Test Pattern Generator）— 当前 mockup 用 TVU placeholder logo，等设计师补

---

## 2. 状态机（per type）

| 类型 | 可能状态 | 状态语义 | 颜色 |
|---|---|---|---|
| A. 双向 | `Inactive` / `Preview` / `On-air` | Inactive=空闲；Preview=配置完成预演；On-air=正式外送 | grey / brand-green / red |
| B. Analyzer | `Inactive` / `Analyzing` | Inactive=未启动；Analyzing=正在读取分析 | grey / **info-blue**（区分于 broadcast，"在跑但不外送"）|
| C. Generator | `Inactive` / `On-air` | Inactive=未启动；On-air=正在生成并外送 | grey / red |

**关键 UX 原则（M3 from mockup-conventions）**：广播行业 ON AIR 惯例 — **Live=红 / Preview=绿 / Inactive=灰**，不用 SaaS 默认（绿=活跃）。Analyzing 是新引入的"在跑但不外送"语义，蓝色避免与 On-air 混淆。

---

## 3. 操作矩阵（Action Cluster per state）

每行所有操作排序：**Clone Session（左固定）→ Open in MicroApp（左固定）→ State Actions（右浮动）**。Clone+Open 跨所有 state 在同一 X 位置，operator 视线扫描有固定锚点。

### Type A 双向

| State | Visible Actions | 颜色 / 视觉 |
|---|---|---|
| Inactive | Clone · Open · `Preview` · `Go Live` | gray gray ghost-green filled-green |
| Preview | Clone · Open · `Go Live` · `Stop` | gray gray filled-green ghost-red |
| On-air | Clone · Open · `Stop` | gray gray ghost-red |

### Type B Analyzer

| State | Visible Actions |
|---|---|
| Inactive | Clone · Open · `Start Analysis` (ghost-green) |
| Analyzing | Clone · Open · `Stop Analysis` (ghost-red) |

### Type C Generator

| State | Visible Actions |
|---|---|
| Inactive | Clone · Open · `Start Stream` (filled-green，因为 Generator 启动即外送)|
| On-air | Clone · Open · `Stop Stream` (ghost-red) |

### 操作语义

| Action | 行为 |
|---|---|
| **Clone Session** | 复制当前 session 配置，跳转到 Open 页面用 cloned 值二次编辑 |
| **Open in MicroApp** | 跳转到该 MicroApp 详情页，进行完整编辑（替代了行内 Edit）|
| Preview | Type A：进入预览模式（不外送，本地核对画面）|
| Go Live | Type A：从 Inactive/Preview 切到正式 broadcast |
| Stop | 停止当前活动状态（preview + live 都停）|
| Start Analysis | Type B：开始读取输入做分析 |
| Stop Analysis | Type B：停止分析 |
| Start Stream | Type C：开始生成 + 外送（直接进 On-air）|
| Stop Stream | Type C：停止生成 |
| **+ New Session**（Card Header 上）| 该 MicroApp 创建一个全新 session（与上方 Clone 区分：从 0 开始 vs 复制现有）|

### Page-scoped restriction（2026-05-09 update）

**`+ New Session` 和 `Clone Session` 仅在 My Sessions 提供。**

- **Master Console** = read-only monitor + control surface。Operator 可以做 state actions（Preview / Go Live / Stop / Start Analysis / Stop Analysis / Start Stream / Stop Stream），但**不能 create / clone / 编辑 URL**。
- **My Sessions** = self-scope authoring。Create（per-card `+ New Session`）/ Clone / URL 编辑 / state actions 全部支持。
- URL 字段在 MC 不可编辑，未设置时显示 `—`（不是 placeholder "Click to set...")。
- 决策出处：[`decisions/2026-05-09-master-console-readonly.md`](./decisions/2026-05-09-master-console-readonly.md)

### Per-session Health Indicator（2026-05-09 update）

State 列在 State Pill + 时长后追加一个 16px 健康图标，表示该 session 是否有异常。**全部用 TVU UX Design System 库的 message icon + 内绑色变量**：

| Health | TVU 库图标 | Component key | 绑色变量 | Hex |
|---|---|---|---|---|
| Healthy | `icon/Message/Success 1` | `85588a1ace60a5430f45a4fe7aab9faaf52ad8dd` | `UX/Brand/Brand` | `#2fb54e` |
| Warning | `icon/Message/warning 1` | `cefe48b9e79a32f8386939be5febb9c2c983e91d` | `UX/Orange/Default` | `#f68512` |
| Error | `icon/Message/Error 3` | `164c7c224a9089f9bc5ec9be61bae3718103cb04` | `UX/Red/Default` | `#ea4233` |

- 每个 session row 都显示
- hover 用设计系统 Tooltip 给短描述（如 "Bitrate fluctuation detected"）
- 点击非交互（v1）
- 三色复用规则 + 跨上下文歧义：详见 [`decisions/2026-05-09-session-health-indicator.md`](./decisions/2026-05-09-session-health-indicator.md)

### 视觉规约（M11-M20 from mockup-conventions）

- 所有 action button 用 **naked icon**（库 Button/dark M `style=rimless`），Hover 显示 tooltip
- 不再用 ⋮ overflow（1920 空间充足，所有操作 inline 展示；1440 隐藏 Clone 节省空间）
- icon 必须 import 自 TVU library（不用文字 "+" / "..." 凑合）

---

## 4. 角色矩阵 × 页面 / 列可见性

### 4 级角色（多租户）

| 角色 | 范围 |
|---|---|
| **Super Admin** | TVU 内部员工，跨所有 Company / Personal 用户，全平台可见 |
| **Company Admin**（前用 "Enterprise Admin"）| 客户公司管理员，仅本公司内全部 sessions |
| **Company User**（前用 "Enterprise User"）| 客户公司普通用户，仅自己 sessions |
| **Personal User** | 单人订阅用户，自己 = 自己的 tenant，仅自己 sessions |

### 多租户

- **Tenant 词**：UI 里**不出现** "Tenant"，统一用 **Company** 一词（库 `user/company` icon 实证 + Personal-tier 用户在 Company 列显示灰 `---`）
- 角色 → 列可见性矩阵：

| 列 | Super Admin | Company Admin | Company User | Personal User |
|---|---|---|---|---|
| `#`（行号）| ✅ | ✅ | ✅ | ✅ |
| Event Name | ✅ | ✅ | ✅ | ✅ |
| **Event Owner** | ✅ | ✅ | ❌ My Sessions = self-scope，列冗余 | ❌ |
| **Company** | ✅ | ❌ 隐藏（永远本公司，列冗余）| ❌ | ❌ |
| Object ID | ✅ | ✅ | ✅ | ✅ |
| Input URL / Output URL / State / Actions | ✅ | ✅ | ✅ | ✅ |

### 角色 × 页面访问

| 角色 | Master Console | My Sessions |
|---|---|---|
| Super Admin | ✅ 全平台 | ✅ 自己 sessions |
| Company Admin | ✅ 仅本公司 | ✅ 自己 sessions |
| Company User | ❌ 路由 403 → 重定向 /my-sessions | ✅ 自己 sessions |
| Personal User | ❌ 同上 | ✅ 自己 sessions |

---

## 5. 两个页面架构

### Master Console（admin 全局态势）

- Top bar: TVU logo + "MicroApps" + Menu tabs `[Master Console (active)] [My Sessions]` + 时区 + Account
- Filter bar:
  - Search input（placeholder："Event Name / Object ID / Company / Event Owner"）
  - Radio Group：`All` / `Active` / `Inactive`（替代 Tab/Item — 单选 filter 语义匹配 Radio）
  - Counter pills（4 桶）：`On-air: N` / `Preview: N` / `Analyzing: N` / `Inactive: N` — **可点击当 filter shortcut**
  - Auto-refresh widget：默认 30s，间隔可选 10s/30s/1m/5m/Off + 倒计时 + 进度条 + **手动 pause/play 图标**（在倒计时和下拉之间，双 affordance：dropdown=长期关闭语义、icon=临时暂停语义；详见 [`decisions/2026-05-09-auto-refresh-pause-button.md`](./decisions/2026-05-09-auto-refresh-pause-button.md)）
- Cards List（按 MicroApp 类型分组的 8 个 cards）：
  - Card Header: APP icon + title + counter badge `X active` / `X sessions` + (`input-only`/`output-only` chip if applicable) + spacer + chevron *(注：MC 不显示 `+ New Session` — 详见第 3 节 Page-scoped restriction；MS 保留)*
  - Expanded card: Card Header + divider + Table Header + divider + N session rows + dividers
  - Collapsed card: only Card Header（per [`mockup-conventions.md`](../../tvu-design-system/docs/internal/mockup-conventions.md) M8：≥1 active = expanded + 绿 badge / 全 inactive = collapsed + 灰 badge + chevron 朝下）
- Active 口径：`Active = On-air ∪ Preview ∪ Analyzing`（任何非 Inactive 态）

### My Sessions（用户自己的活动流水）

- 同一份页面骨架，scope = 自己 sessions
- 列差异：隐藏 Company + Event Owner（self-scope 隐含）
- Search placeholder 调整：`Event Name / Object ID`（无 Company/Event Owner term — 但 placeholder 内容不应在不同分辨率下变化，**只布局变**）
- 4 角色 UX 一致（视觉无区别，差异在后端 scope）

### Phase 1 不实现

- Logs / Delete / View Report 按钮
- 历史数据时间过滤（默认实时 Live-only）
- Sort indicator default desc state（库需补 Sort Descending icon）

---

## 6. 4 frame mockup 索引

页面 `Monitor for all of Micro Apps 20260430` (id `2956:4544`)：

| 名称 | id | 尺寸 |
|---|---|---|
| MicroApps · Master Console / 1920 | `3278:1835` | 1920 × ~1480 |
| MicroApps · Master Console / 1440 | `3289:2530` | 1440 × ~1480 |
| MicroApps · My Sessions / 1920 | `3289:2726` | 1920 × ~1480 |
| MicroApps · My Sessions / 1440 | `3289:2922` | 1440 × ~1480 |

### 响应式断点（per M20 列宽分类）

| 列 | 策略 | 1920 width | 1440 width |
|---|---|---|---|
| `#` | FIXED | 40 | 40 |
| Event Name | FILL grow=1 + truncation=ENDING | ~254 | ~167 |
| **Event Owner** | FIXED，**不支持排序**（角色可见性依赖后端 scope，前端列排序语义不清晰）| 140 | 140 (MC) / 隐藏 (MS) |
| Company | FIXED | 110 | 隐藏 |
| Object ID | **FILL grow=1** + truncation=ENDING + textAutoResize=TRUNCATE（大屏多显示 hash 字符）| ~254 | ~167 |
| Input URL | FILL grow=1 + truncation=ENDING | ~254 | ~167 |
| Output URL | FILL grow=1 + truncation=ENDING | ~254 | ~167 |
| State | FIXED 220 | 220 | 220 |
| Actions | FIXED 130 | 130 | 130 |

### 1440 specific 行为

- Tenant/Company 列隐藏
- Action 列仍 130 fixed，但 **Clone 按钮在 1440 隐藏**（节省空间）
- Open + state actions 维持

---

## 7. file-local 组件（在产品 Figma 文件 SECTION `MicroApps Monitor — Local Components` id `3261:1467`）

| 组件名 | id | Variants |
|---|---|---|
| MicroApp State Pill | `3261:1480` | 4（Inactive / Preview / On-air / Analyzing）|
| MicroApp Counter Pill | `3264:1484` | 4（kind 4 状态）|
| MicroApp Action Cluster (Bidirectional) | `3267:1510` | 3（state Inactive/Preview/On-air）|
| MicroApp Action Cluster (Analyzer) | `3268:1517` | 2（Inactive/Analyzing）|
| MicroApp Action Cluster (Generator) | `3268:1528` | 2（Inactive/On-air）|
| MicroApp Card Header | `3272:1821` | 6（pipeline × status）|
| MicroApp Table Header | `3273:1889` | 3（Role=Super/Enterprise/Self）|
| MicroApp Auto-refresh Widget | `3274:1856` | 2（Running/Paused）|

**库债提案**（已登记 [`backlog.md`](../../tvu-design-system/docs/internal/backlog.md) BRIDGE-MOCKUP-003）：
- `MicroApp State Pill` → 库 `Pill/Status`（去产品化）
- `MicroApp Counter Pill` → 库 `Pill/Counter`

---

## 8. 库引用清单（TVU UX Design System）

import key 与 fileKey：
- **Library**：TVU UX Design System
- **libraryKey**：`lk-057f6ba0f771bfa7f63a6a197502999462c2974f995488b381708ca5faadb7f9f6675e04aa442b3a5ffb31732150a7f5aa8ca3102073ab210edc684022fc6c21`
- **Variable Collection key**：`8a4c04e26943548d206eb123b5991607edcfd293`

### 用到的 components（component_set / component keys）

| 组件 | key |
|---|---|
| Top bar | `918b928e4541f1573de5c98c32b408af663d7f2f` |
| Button/dark M | `12b38c8b68cd67dd3978e0d68712bc646f1e97c1` |
| Tab/Item（已被 radio 替换）| `2267405386cb3186ba920b0d0b790d54e65a1529` |
| radio | `9f07746f19d962fe8b0ac31e6697a5b8f242d8b0` |
| input box/line | `fb1c1b49e6350a1a556fbd69a8149e10ed03004f` |
| Tooltips | `40c9daafd174d0f4d7005eacc566570ef381fde5` |
| Drop down List/Select | `12602e73b9682f9a9c45ec1e9373e8ac80bb489a` |
| Drop down List/Item | `8773f1adb923a4f4a01aa8e951d38bfdd5ba24b6` |

### 用到的 icons

| icon | key |
|---|---|
| icon/Video/Play（Preview / Start X）| `2d6554466c261ed90a3fab0444a49044fe011e83` |
| icon/Video/Record stop（Stop / Stop X）| `baad5b54b75daf6e82cf8647a6d741c5e041d093` |
| icon/indicator/live 1（Go Live / Start Stream）| `a18cfde2367f222299d895e53eb78869ffa504a1` |
| icon/Menu/More（⋮ overflow，目前未用）| `47afb54c12b4b4f401e4ed0b6b3425d6c430bbdb` |
| icon/share/open link（Open in MicroApp）| `1575db8f647f6063a303102b4516f645d7eca480` |
| icon/Edit/Copy（Clone Session + URL/ObjID copy）| `75d48adc6f57f176bf3b4c4560e9f5ab8bd79e92` |
| icon/Edit/Add 1（+ New Session）| `b55b65cce73c6dc552b44769025770d4025d6056` |
| icon/Arrow/Sorting | `36c09416aa4fef6c139b05dd9e4683884acbeea7` |
| icon/Arrow/Double up（Card Header chevron 展开态）| `2be13b82bf5bb8e32142e82d06bc20a14cfb79c2` |
| icon/Arrow/Double down（折叠态）| `9b7938b81ceba8cb1a55661a9fbbfaa5980a6493` |
| icon/Arrow/Dropdown | `eba15c0b438d16e88b86ffebe86423aabef212e9` |
| icon/load/refresh | `6a3fadaf85377a5417eb53ea0eb3acb4baa9b67e` |

### 用到的 color variables

| variable | key（library import key）| Dark / Light |
|---|---|---|
| UX/Red/Default | `a3f82a4b2c6c4610650cc136428e83cbd9b65736` | #ea4233 / #dc2717 |
| UX/Brand/Brand | `ea8c23833b46a0c9905a5aed05bf668593a611ce` | #2fb54e / #299f45 |
| UX/Blue/Default | `d3c9eebb83fefb56eaff2d7a40f6e584999d633f` | #3892f3 / #0473d5 |
| UX/Grey/grey-7 | `722ad30ede6ffee9dede9d5187150f3178346775` | #7B7B7B / 同 |
| Color Type/Text/Tips | `b3b5983a60f92902d446e8e25d3445fb4711eb16` | （pill text 用）|
| Color Type/Background/Disable Grey Button | `8172a49eb02798d5bb705c77081054384b7a813d` | #434343 / #dbdbdb |

### 库债（pill bg 当前 hardcoded RGB at 0.18 — 等库补 4 个 Msg-bg-dark token）

详见 [`tvu-design-system/docs/internal/backlog.md`](../../tvu-design-system/docs/internal/backlog.md) BRIDGE-MOCKUP-001。

---

## 9. 关键 UX 决策（理解了再上手，不要硬抄上一版）

| 决策点 | 当前选择 | 理由 |
|---|---|---|
| Edit 按钮是否独立 | **删除** | 通过 Open in MicroApp 跳转编辑，避免"看见问题→点 Edit→不知道编辑什么"的歧义 |
| Add Session 入口 | **per-card `+ New Session`，仅 My Sessions** | 全局 + New 多余一步；per-card contextual 无歧义；Console 是 monitor 视图，authoring 隔离到 self-scope MS（防误操作 + 权限收敛）|
| Master Console 编辑能力 | **read-only monitor + control**（无 `+ New Session` / `Clone` / URL edit；保留 state actions） | 视图与操作分离：监控 ≠ 修改；URL 错误编辑会影响在线 broadcast |
| Clone Session 位置 | 行内 Action Cluster 第 1 位置（固定左锚），**仅 My Sessions** | Clone 比 Edit 更普世（MS 每行都有），固定位置便于视线扫描；Console 不提供 |
| Auto-refresh 暂停方式 | **dropdown `Off` 选项 + 倒计时旁手动 pause/play 图标** 双 affordance | dropdown = "长期关闭" 语义；行内 icon = "临时暂停" 语义。高频 monitoring 场景需要快速暂停查 details 而不切换 dropdown |
| Per-session Health Indicator | **State 列右端 16px 图标**（healthy/warning/error 3 态 + hover tooltip 给原因）| State Pill 只表达"什么状态"，Health 表达"是否有问题"；Operator 监控 30+ 行需要 preattentive 视觉信号；颜色复用沿用 State 色系（绿/红）但形状不同（✓/×）避免和 Pill 混淆 |
| State pill 颜色 | On-air 红 / Preview 绿 / Analyzing 蓝 / Inactive 灰 | 广播行业惯例（红=Live）+ Analyzing 区别于"在外送"|
| Action button 形式 | naked icon（rimless）+ tooltip | 1920 空间够，icon 密度高；hover 通过 tooltip 给文字（M9 合规）|
| Action 排序 | Clone → Open → state actions | 固定操作左锚，状态相关右浮动 |
| ⋮ overflow | **不用**（1920+ 全 inline；1440 隐藏 Clone 节省空间）| 空间充足时藏在 ⋮ 里反而增加点击成本 |
| Filter chip 组件 | **radio**（替代 Tab/Item）| Tab 语义=换 view；filter 语义=单选，Radio 匹配更准 |
| Counter pill 双用途 | 显示 + 可点击 filter shortcut | 用户视线扫描 counter 时本能想点击过滤；不增加 UI 元素 |
| Auto-refresh 默认 | 30s + 5 档可选 + 倒计时 | broadcaster 实时性需求 ≠ 后台报表 |
| 1440 vs 1920 placeholder | **placeholder 文本不变**（同页面同内容，只布局变）| 搜索可搜哪些字段不该因屏幕变化 |
| Object ID 列宽策略 | FILL + truncation（大屏多显示 hash）| 内容定长（hash）但 display 宽度 responsive — M20 第 3 类 |
| Action / State 列宽 | **FIXED**（不 FILL）| 内容定长（icon 集合 / pill+时长），FILL 会留大段空白 |

---

## 10. 关联文档

> ⚠️ 这些都在**邻近** project `tvu-design-system`，路径相对于本文件位置：

- **方法论硬规则**：[`../../tvu-design-system/docs/internal/mockup-conventions.md`](../../tvu-design-system/docs/internal/mockup-conventions.md) — M1-M20 全部 mockup 规则（M11-M20 是 plan-owner 方法论纪律）
- **本次 session 复盘**：[`../../tvu-design-system/docs/internal/retrospection/2026-05-09-microapps-mockup-retrospect.md`](../../tvu-design-system/docs/internal/retrospection/2026-05-09-microapps-mockup-retrospect.md) — 8 类错误 + 3 root cause 详细
- **库债 backlog**：[`../../tvu-design-system/docs/internal/backlog.md`](../../tvu-design-system/docs/internal/backlog.md) — BRIDGE-MOCKUP-001/002/003 段
- **跨工具入口**：[`../../tvu-design-system/AGENTS.md`](../../tvu-design-system/AGENTS.md) — 任何 AI 工作前必读
- **HTML demo 设计 spec**：[`./2026-05-09-design.md`](./2026-05-09-design.md) — 与本文件互补（实现细节）

---

## 10.5 当前 implementation 状态 + 已知 gap（handoff to next session）

**当前产物**：`microapps-console-demo.html`（2300 行单 HTML，Vue 3 CDN + 内联 TVU SVG + token copy）。**这是 PoC，不是 bridge stress test**——见下方 Gap。

### 已落实

- ✅ Token 值正确（手抄自 `tvu-design-system/src/tokens/variables.css`，值一致但是 copy，不是 import）
- ✅ Icon 全部来自 TVU library（17 个 symbol，每个顶部带 `<!-- icon/<Category>/<name> -->` 注释；具体见 [`code-conventions.md`](../../tvu-design-system/docs/internal/code-conventions.md) R1 反模式记录表）
- ✅ App icon 8 张：5 张真 Figma icon（PNG base64，从 Card Header 截 + crop）+ 3 张 TVU placeholder logo（per doc §1，待设计师补）
- ✅ 状态机 / Action matrix / Type × State / 角色矩阵 都按 §2-§4 实现
- ✅ Stop confirmation dialog / Auto-refresh countdown / Hash routing / Mock data 19+ sessions / M8 默认展开规则 / Master Console read-only / My Sessions sort-by-recent / Inactive 数据变体齐全

### 已知 gap（next session 拿起来做）

| Gap | 严重度 | 解决路径 |
|---|---|---|
| **Canonical components 完全旁路** — TopBar / Tab / Button / Badge / Input / Radio / Modal / Notification 全部手写，0 个用 `tvu-design-system/src/canonical/*.vue` | 🔴 高 — 这意味着 demo 没真正测试 TVU library 作为 Figma↔Code bridge 的能力 | 切到 Vue + Vite + `file:../tvu-design-system` 项目（per "A+B 双 build" 提案）：A 模式真消费 canonical；B 模式用 `vite-plugin-singlefile` 出单 HTML 给 PM |
| **Token copy 不是 import** — 如果 TVU 改 token，demo 不会自动同步 | 🟡 中 | 同上，A+B 都通过 npm 链路 import `style.css` |
| **App icon 是 PNG base64**（非 scalable，非 currentColor） | 🟡 中 | TVU library 中 5 个 App icon 已发布 → 改 import 真 SVG（per code-conventions R1）；3 个待补的等设计师 |
| **新 session bootstrap rule 缺位** | 🟡 中 — 已知问题，user 已规划在新 session 加入 `~/.claude/CLAUDE.md` 跨项目 TVU 规则 | user 在新 session 主导 |

### 接手 next session 的最小起手序列

```
1. cd "MicroApps Console/"
2. Read ./docs/MICROAPPS_PRODUCT_CONTEXT.md (本文件)
3. Read ../tvu-design-system/AGENTS.md
4. Read ../tvu-design-system/docs/internal/code-conventions.md  (R1-R4)
5. ls ../tvu-design-system/dist/icons/svg/                       (R1 mandatory)
6. ls ../tvu-design-system/src/canonical/                        (R3 mandatory)
7. cat ../tvu-design-system/src/tokens/variables.css | head -100 (R2 mandatory)
```

完成上面 7 步 = onboard 完成。

---

## 11. Implementation 规则（指向真源）

> **本项目不重复造规则**——所有"消费 TVU library 写代码"的约束（图标 / token / canonical 组件等）真源在 tvu-design-system 仓库：
>
> → **[`../../tvu-design-system/docs/internal/code-conventions.md`](../../tvu-design-system/docs/internal/code-conventions.md)**（R1-R4）
>
> 与 [`mockup-conventions.md`](../../tvu-design-system/docs/internal/mockup-conventions.md)（M1-M20，Figma 写）分文件，作用域不交叉。
>
> 新 session 做本项目 code implementation 起手必须先读 code-conventions.md。

---

## 12. 关联文档

> ⚠️ 这些都在**邻近** project `tvu-design-system`，路径相对于本文件位置：

- **Figma mockup 硬规则**：[`../../tvu-design-system/docs/internal/mockup-conventions.md`](../../tvu-design-system/docs/internal/mockup-conventions.md) — M1-M20（M11-M20 plan-owner 方法论纪律）
- **Code implementation 硬规则**：[`../../tvu-design-system/docs/internal/code-conventions.md`](../../tvu-design-system/docs/internal/code-conventions.md) — R1-R4（图标 / token / canonical 必须来自 TVU library）
- **复盘**：[`../../tvu-design-system/docs/internal/retrospection/2026-05-09-microapps-mockup-retrospect.md`](../../tvu-design-system/docs/internal/retrospection/2026-05-09-microapps-mockup-retrospect.md)
- **库债 backlog**：[`../../tvu-design-system/docs/internal/backlog.md`](../../tvu-design-system/docs/internal/backlog.md)
- **跨工具入口**：[`../../tvu-design-system/AGENTS.md`](../../tvu-design-system/AGENTS.md) — 任何 AI 工作前必读

---

## 13. 新 session onboard 起手 checklist

新 session 的 AI 按任务类型分支读：

| 任务类型 | 必读顺序 |
|---|---|
| **任何任务起手** | 本文件 §0-10 + §12 关联文档（5 min） |
| **Code implementation** | + [`code-conventions.md`](../../tvu-design-system/docs/internal/code-conventions.md) R1-R4，然后 `ls tvu-design-system/dist/icons/svg/` 拿全库 catalog |
| **Figma mockup 写** | + [`mockup-conventions.md`](../../tvu-design-system/docs/internal/mockup-conventions.md) **全文**（**真源/优先级段** + **M1**：`search_design_system` 必须 `includeLibraryKeys: ["lk-057f6ba0..."]` 过滤；**同名旧库 TVU UX Library 陷阱**见 M1 注意 ⚠️ + **M10**：绑 Color Variable 禁写 hex literal + **M2**：库优先实证 + **M11-M20** plan-owner 纪律） |
| **困惑 / 选择题** | + [`retrospection/2026-05-09-microapps-mockup-retrospect.md`](../../tvu-design-system/docs/internal/retrospection/2026-05-09-microapps-mockup-retrospect.md)（看上次踩过的坑）|

**红线（最大元教训）**：写完规则下一秒会违反规则——每次说"完成了"前先 probe（per `mockup-conventions` M11 / `code-conventions` R4）。