完善传播指标筛选布局设计

2026-07-13 12:18:40 +08:00
parent 5c21f631d7
commit 961fb33e9e
1 changed files with 102 additions and 0 deletions
@@ -0,0 +1,102 @@
+# 传播指标筛选布局重设计
+
+## 定位
+
+本文件是 [传播指标独立视频口径筛选设计](2026-07-10-independent-spread-metric-filter-design.md)
+的界面补充。它只重做星图插件市场页工具栏中“传播指标筛选”的展示和选取方式，
+不改变已实现的独立指标口径、规则数组、筛选执行、CSV 导出或批次提交。
+
+当前 `plugin-toolbar.ts` 已通过 `SPREAD_FILTER_DEFINITIONS` 提供完播率和互动率，
+并让 `SpreadMetricRuleDom` 为每个已选指标保留独立阈值和视频口径。本次继续使用这
+套状态和 DOM 规则，不重建筛选数据模型。
+
+## 目标
+
+避免在工具栏初始状态平铺全部可筛选指标和完整条件。用户只在需要时选择指标，主区
+只展示已经生效的指标规则。
+
+即使未来 `SPREAD_FILTER_DEFINITIONS` 增加更多指标，工具栏高度也只随已选规则增加，
+不会随可选指标总数线性增长。
+
+## 桌面端交互
+
+“传播指标筛选”标题行由以下内容组成：
+
+1. “添加筛选指标”按钮。
+2. 已选规则数量，例如“已选 2 项”。
+3. 仅在同时有两条及以上规则时显示“全部规则都达标才保留达人”。
+
+点击“添加筛选指标”后，打开锚定按钮的指标目录。目录提供搜索框和分组列表；当前
+完播率、互动率归在“传播表现”分组。未选择的指标显示添加操作，已选择的指标显示
+“已添加”且不可重复选取。
+
+选择一个指标后关闭目录，并在下方追加该指标现有的完整规则行。规则行继续包含：
+
+1. 指标名称。
+2. `>=` 阈值输入和 `%` 单位。
+3. 视频类型。
+4. 是否只看指派。
+5. 是否排除营销流量。
+6. 时间范围。
+7. 删除按钮。
+
+删除按钮取消该指标的现有 `enabledInput` 状态、移除规则行，并使指标在目录中重新
+可选。初始无选项时不显示任何规则行，只保留添加入口和简短空状态。
+
+## 窄屏交互
+
+窄屏时，指标目录不占用固定侧栏空间。点击“添加筛选指标”后，目录作为标题行下方
+的可收起抽屉展开；选择、搜索或关闭后恢复收起状态。规则行保留指标、阈值和视频
+类型，指派、营销和时间范围进入同一行的二级展开区，避免横向挤压或遮挡。
+
+桌面端使用按钮锚定浮层，窄屏使用抽屉；两种视图读取同一组 `enabledInput` 和
+`SpreadMetricRuleDom`，不能分别保存选择状态。
+
+## 代码边界
+
+### 修改范围
+
+- `src/content/market/plugin-toolbar.ts`
+  - 用 `MetricCatalog` 替代常驻复选框式 `createSpreadMetricSelector()`。
+  - 保留 `createSpreadMetricRuleDom()`、`syncSpreadMetricRuleState()`、
+    `readToolbarSpreadFilter()` 和 `SpreadMetricRuleDomMap` 的规则读写职责。
+  - 在添加、删除、初始化和工具栏重挂载时，同步目录中的已选状态和规则数量。
+
+- `tests/market-content-entry.test.ts`
+  - 覆盖初始空状态、从目录添加、重复项不可添加、删除后恢复可选、窄屏抽屉开关。
+
+### 不修改范围
+
+- `src/content/market/types.ts` 中的 `SpreadFilterMetric`、`SpreadMetricFilterRule`、
+  `SpreadThresholdFilter` 和 `SpreadInfoConfig`。
+- `src/content/market/index.ts` 中的 `applySpreadThresholdFilter()`、规则 AND 判定、
+  相同口径请求复用、CSV 导出和批次提交流程。
+- `src/content/market/spread-info.ts` 的星图接口参数、字段映射和百分比比较。
+
+## 状态约束
+
+1. `SPREAD_FILTER_DEFINITIONS` 是可选指标目录的唯一来源；目录不得再维护一份独立
+   的指标清单。
+2. 一个 `SpreadFilterMetric` 至多有一条规则，目录已选状态由对应
+   `enabledInput.checked` 推导。
+3. 从目录添加指标时，沿用既有默认口径：个人视频、不限指派、不排除营销、近 30 天；
+   阈值为空，必须由用户填写。
+4. 删除后重新添加同一指标，按上述默认值创建，不恢复已删除的阈值或口径。
+5. 未选指标不参与 `readToolbarSpreadFilter()` 校验，也不能触发传播指标请求。
+
+## 验收标准
+
+1. 初始工具栏不再显示一排常驻指标复选框和空规则行，只显示“添加筛选指标”入口。
+2. 选中完播率后，页面只增加一条完播率规则；选中互动率后才增加第二条规则。
+3. 指标目录内已添加项不可再次添加；删除后立即恢复可选。
+4. 已选数量、规则行、`enabledInput` 和 `readToolbarSpreadFilter()` 返回的规则数组
+   始终一致。
+5. 已选规则的阈值校验、个人视频联动、不同口径请求、规则 AND 筛选、CSV 导出和
+   批次提交结果与改版前保持一致。
+6. 窄屏打开和关闭指标抽屉时不发生内容重叠、横向溢出或大块无效留白。
+
+## 验证
+
+实现阶段先新增工具栏交互测试并观察其在旧布局下失败，再完成最小 UI 改造。之后运行
+相关市场页测试、项目类型检查和构建，并在桌面与窄屏实测添加、删除、重复选择和导出
+前校验。现有独立口径筛选的回归用例必须全部继续通过。