# MH-3296 — Filter by Resource Pool（设计 spec）

- **Jira**: [MH-3296](https://tvunetworks.atlassian.net/browse/MH-3296) — Filter by Resource Pool（Task / Backlog / reporter Robin Wu）
- **日期**: 2026-07-22
- **状态**: 设计已定，待终审 → 进 Figma 构建
- **交付目标页**: MH-2026 文件 `node-id=2175-10026`（页面 "MH-3296 Filter by Resource Pool"，当前空白）
- **基底源（MH-Lora 文件 `ZXm4ClRDgGm2M3pU64NC4A`）**:
  - Filter 面板 — `node-id=428-68726`
  - Resources 选择窗 — `node-id=581-36845`

---

## 1. 背景 / 现状（线上实测）

Mediahub home 页左右两栏（Source / Destination）各有独立 Filter 浮层。经线上实测确认的当前行为：

- Filter 浮层由工具条 `Filter` 按钮触发，浮层内含：搜索框 + `Created By Me`（单 toggle）+ `Tag`（多选）+ `Source Type`（**组内单选**）。
- **选中即时生效，无 Apply 按钮**；`Filter` 按钮上用绿色徽标显示"生效类别数"。
- **不同类别之间是 AND（交集）**（实测：Tag #111 ∩ Grid-MediaHub = 0，非并集 4）。
- Resources 是两层：全局 `Default Resource Configuration`（齿轮）+ 对象级 `Settings → Resources`（继承+可覆盖）。核心字段 `Resources = TVU-Hosted / Self-Hosted`；TVU-Hosted 带 Server Location（15 个 region），Self-Hosted 带 Box Pool（如 MH-Test 150/2000）。对象级/全局的 Resources 选择当前均为**单选**。

> 注：Figma 基底版（428-68726）比线上多了 `All / Folder / Destination` 分段 + 各区块计数 —— 以 Figma 基底为视觉真源。

## 2. 需求（MH-3296 原文要点）

给 Filter 增加"按 resource pool 过滤对象"的能力：
1. `Created by Me` 区块标题 → 改名 `Special Filters`。
2. 在该区块（截图红框位置：`Created By Me` chip 旁）加按钮 `Filter by Resource Pool`。
3. 点击 → 弹出一个 resource management 窗口，用户选资源。
4. 只返回配置在所选资源上的对象。

## 3. 设计决策（brainstorm 结论）

| # | 决策点 | 结论 |
|---|---|---|
| D1 | 区块改名 | `Created By Me` → **`Special Filters`** |
| D2 | 新按钮 | 在 Special Filters 区块内、`Created By Me` chip 旁加 **`Filter by Resource Pool`** 按钮 |
| D3 | 选择器形态 | **独立弹窗**（照工单字面 "window"），**样式复用 object resources 编辑窗** |
| D4 | 弹窗内容 | 复用编辑窗结构：顶部 `Resources` 下拉（TVU-Hosted / Self-Hosted）→ 选 TVU-Hosted 出 **region 多选** / 选 Self-Hosted 出 **Box Pool 多选** |
| D5 | 跨类型混选 | **不限制一次只能选一类**：边选边把已选项累积显示在弹窗内某处，可同时含 region + pool；底部 **Confirm** 统一提交 |
| D6 | 过滤维度 | 既能筛 Self-Hosted 的 box pool，也能筛 **TVU-Hosted 的 region**（B3） |
| D7 | 布尔逻辑 | 已选的多个 region/pool 之间 **OR**；Resource Pool 这一类与其它筛选类别（Tag / Source Type）之间 **AND**（对齐现状） |
| D8 | 覆盖范围 | Source 和 Destination 两侧都做；**本轮先交 Source，OK 后补 Destination** |

## 4. 待定项（构建时定，需 review）

- **[已定] A**：已选项累积区 = **弹窗底部一条已选 chip 行**（紧挨 Confirm），边选边累积，每个 chip 可 × 移除。
- **[已定] B**：Confirm 后回显 = `Filter by Resource Pool` 按钮默认收起只显计数（如 `· 2`）+ chevron 展开箭头；**展开后在 Special Filters 区内内联列出已选 region/pool chips（每个可 × 移除）**；`Filter` 总徽标 +1（对齐现状"徽标计类别数"）。

## 5. 构建计划（Figma，Source 侧）

1. 读全套 M 规则真源（AGENTS.md + mockup-conventions.md）。
2. Phase 0（M0）：把 Filter 面板 + 新按钮 + 弹窗各元素映射到 TVU 库组件（M32 library-first + M35 affordance trace）。
3. 从基底复制 Filter 面板 → 改标题为 Special Filters + 加按钮。
4. 用编辑窗样式 + 库组件搭 `Filter by Resource Pool` 多选弹窗（含 Confirm、已选累积区、复选态）。
5. 加 M23 UX 交付注释（多状态流程：默认 → 打开弹窗 → 选择 → Confirm → 激活态）。
6. 自检：跑 audit-mockup-integrity + audit-mockup-colors。

## 5.1 M37 Reference Probe（基底 428-68726 + resources 窗 581-36845）

| 维度 | 提取 |
|---|---|
| Layout 分栏 | Filter = 单列浮层 popover（~320 宽）；新弹窗 = 独立居中窗，复用 object resources 编辑窗样式（精简版：标题 + Resources 下拉 + 多选列表 + 底部已选 chip 行 + Confirm） |
| Body content 模式 | Filter：搜索框 + 分段(All/Folder/Destination) + 分区 chip 组(Special Filters / Tag / Source Type，每区带 count)；弹窗：dropdown + 多选 list rows + 底部已选 chip 行 |
| Component patterns | filter chip=`Tab/Item Filled`；搜索=`input box/filled`；count=`Badge`；弹窗 dropdown=`select box/filled` 或 `Drop down List/Select`；多选 list=`Drop down List/Item`(Checked 轴)；按钮=`Button/dark M`；箭头=`icon/Arrow` |
| Interaction affordances | chip 可点；搜索即时；弹窗 dropdown 切 region/pool 列表；list row 复选多选；Confirm 提交；主面板 `Filter by Resource Pool` 按钮 chevron 可展开看已选 |
| Spacing/padding | 以基底 428-68726 实际值为准（import 后取） |

## 5.2 M0 Phase 0 — Element → Component 映射表

| # | Element | TVU 库组件 | Variant/说明 | Status |
|---|---|---|---|---|
| 1 | Filter 浮层容器 | 复制基底 `428-68726` | file-local frame，改造 | ✅ base |
| 2 | 搜索框 Enter Content | `input box/filled` | Search field variant | 🟡 import 验 |
| 3 | 分段 All/Folder/Destination | `Tab List` + `Tab/Item` | Type=Filled | ✅ verified |
| 4 | Special Filters 区标题 | `Text` | fontSize∈grid | ✅ |
| 5 | Created By Me chip | `Tab/Item` | Type=Filled | ✅ verified |
| 6 | **Filter by Resource Pool 按钮（新）** | `Button/dark M` | + chevron(展开) + Badge(计数) | 🟡 import 验 |
| 7 | Tag chips | `Tab/Item` | Type=Filled | ✅ |
| 8 | Source Type chips | `Tab/Item` | Type=Filled | ✅ |
| 9 | 区块 count badge | `Badge` | 只读 indicator | ✅ verified |
| 10 | **弹窗容器（新）** | `prompt message` 或 mirror resources 编辑窗 | 需 import 对比选型 | 🟡 import 验 |
| 11 | Resources 下拉 | `select box/filled` / `Drop down List/Select` | TVU-Hosted/Self-Hosted | 🟡 import 验 |
| 12 | region/pool 多选 list rows | `Drop down List/Item` | **Checked 轴**（多选核心） | 🟡 import 验 |
| 13 | 已选 chip 行（底部） | `Tab/Item` Filled | 带 × 移除 | ✅ |
| 14 | Confirm 按钮 | `Button/dark M` | primary | ✅ |
| 15 | 世界地图(TVU-Hosted region) | 复用 resources 窗素材 | 非库组件 | ⚠️ 复用 |

## 5.3 M35 Affordance Trace（基本语义元素）

**a) 多选指示(checkbox)** — Affordance: `selection-multi`(intent: 多选 region/pool)；Vocabulary scan: [`Drop down List/Item` Checked 轴, `radio`, `switch`, check/tick]；Chosen: `Drop down List/Item` Checked variant（库原生多选行，优于自画 checkbox）。

**b) 展开箭头(主面板回显)** — Affordance: `directional-vertical`(intent: 展开查看已选 pool/region)；Vocabulary scan: [`icon/Arrow/Dropdown` eba15c0b, `Arrow/Double down`(折叠↓), `Arrow/Double up`(展开↑), chevron, expand]；Chosen: `icon/Arrow/Double down`↔`Double up` 切换（展开/收起语义最贴）。

**c) 关闭/移除(弹窗 X + chip ×)** — Affordance: `dismissive`(intent: 关闭弹窗 / 移除已选 chip)；Vocabulary scan: [close, x, cancel, clear, remove]；Chosen: 待 `search_design_system` 确认 `icon/close`（construction 时验，miss 则 flag）。

## 6. 交付后

- 写 handoff 到 Mediahub `docs/handoffs/`。
- 更新 tvu-design-system `STATUS.md`。
- Destination 侧同构复用后补齐。

---

## 7. Figma Build — Draft v1（2026-07-23，待评审 / pending review）

> ⚠️ 本节记录 Source 侧 mockup **初稿**，尚未评审通过。正式 handoff / phase0-ledger / STATUS「shipped」待评审后补。

**交付位置**：MH-2026 文件 [node 2175-10026](https://www.figma.com/design/BvqvqRXPEBlWFbl1jOC6mh/MH-2026?node-id=2175-10026)。

**命名**：功能对外名定为 **"Filter by Resources"**（原 "Filter by Resource Pool" 弃用）。

**3 态流程**：
1. **Default** — "Created by Me" 区改名 **Special Filters**；区内新增 **`Filter by Resources ⌄`** 线框按钮（`Button/dark XS` `style=ghost` + `icon/Arrow/Dropdown` 外置于按钮右侧），独立一行；无选择时不显 well。
2. **Open popup** — 弹窗 "Filter by Resources"，**两资源字段同屏**（不做切换，防"切换误以为清空"）：
   - `Box Pool`（Self-Hosted，label 右带 `icon/others/resource`）多选字段
   - `TVU Hosted Server Location`（TVU-Hosted，label 右带 `icon/others/cloud resource` + 小字 "ai"）多选字段 + 世界地图（selected 绿 pin / unselected 空心 pin）
   - 多选值 = `select box/filled status=multi select` 的 badge（× 在标签内 = `icon/Edit/Clear 2`）
   - 字段用 `Form Item`（Label & Selector, 2 lines, Dark）；行距 / footer 间距 16px（原稿实测）
   - 底部 **Cancel + Confirm**（`Button/dark M`，Confirm 绿）
3. **Applied** — 面板回显：统一**带边框 well**（`grey-13` 底 + `grey-8` 1px 边框）内含 `Filter by Resources (2) ⌄ 🧹`（ghost 绿按钮 + 计数 + chevron + 一次清除 🧹）+ 绿色可移除 chips（`Button/dark XS` green `icon=right`→swap `Clear 2`）；`Special Filters (1)`。

**布尔逻辑**：多个 region/pool 之间 OR；Resource 类与 Tag / Type 类之间 AND（对齐现状）。

**Destination 侧**：**不单独出 mockup** —— 交互与数据契约同 Source，仅 `Destination Type` chip 列表不同（Youtube / Facebook / RTP-FEC / UDP / GRID / ISSP / HLS Push·Pull / RTSP Push·Pull / RTMP(s) Push·Pull / NDI / SDI / SRT Listener）。Source 规则卡一句 scope 覆盖。

**待确认 / 遗留**：
- 全稿待评审
- HLS Push 复用 HLS 图标（`icon/input` 无独立 push 字形）
- 可移除 chip 由 `Button` + `Clear` 图标组合（库无独立 "closable tag" 组件）→ 潜在入库候选
- 少量 Figma 图层名仍含 "Resource Pool"（cosmetic）

**过程规则回流**：tvu-design-system `mockup-conventions.md` **M32.3**（Spec-Value Fidelity + Confirm-Before-Deviation）。