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

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 改造。之后运行
 相关市场页测试、项目类型检查和构建，并在桌面与窄屏实测添加、删除、重复选择和导出
 前校验。现有独立口径筛选的回归用例必须全部继续通过。