feat: filter exports by spread thresholds

2026-06-29 16:11:52 +08:00
parent 121977fd0d
commit 9eb1fe43cc
8 changed files with 803 additions and 24 deletions
@@ -0,0 +1,33 @@
+# 星图达人传播指标阈值筛选 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 在导出 CSV 和提交批次前，按用户选择的 spread-info 参数组合和指标阈值过滤达人。
+
+**Architecture:** 工具栏负责读取筛选配置；`spread-info.ts` 提供单参数组合加载与阈值比较；`index.ts` 在 export range 收集后、CSV/批次 payload 生成前统一应用筛选。
+
+**Tech Stack:** TypeScript, Chrome MV3 content script, Vitest, jsdom.
+
+---
+
+### Task 1: Toolbar Filter State
+
+- [ ] 增加视频类别、指派、营销流量、数据范围和 7 个阈值输入控件。
+- [ ] 增加 `readToolbarSpreadFilter` 读取并校验筛选配置。
+- [ ] 测试个人视频时固定并禁用指派/营销流量。
+
+### Task 2: Spread Filter Logic
+
+- [ ] 在 `spread-info.ts` 增加单配置请求与阈值比较。
+- [ ] 测试百分比显示值、秒、普通数字比较。
+
+### Task 3: Export And Batch Integration
+
+- [ ] 在导出和提交批次流程中调用筛选逻辑。
+- [ ] 空阈值不触发筛选请求。
+- [ ] 测试导出和提交批次都只保留满足阈值的达人。
+
+### Task 4: Verification
+
+- [ ] 运行 focused tests。
+- [ ] 运行 `npm run build`。
@@ -0,0 +1,101 @@
+# 星图达人传播指标阈值筛选需求文档
+
+## 目标
+
+在导出 CSV 或提交批次之前，允许用户按一组视频传播数据参数和指标阈值对达人做二次筛选。
+
+只有满足筛选条件的达人，才进入最终导出或提交批次。
+
+## 筛选维度
+
+筛选维度对应 `get_author_spread_info` 的请求参数：
+
+| UI 维度 | 接口参数 | 可选值 |
+| --- | --- | --- |
+| 视频类别 | `type` | 个人视频 / 星图视频 |
+| 是否指派 | `only_assign` | 只看指派 / 不限指派 |
+| 是否排除营销流量 | `flow_type` | 排除营销流量 / 不排除营销流量 |
+| 数据范围 | `range` | 近30天 / 近90天 |
+
+个人视频的参数约束：
+
+- `type=1`
+- `only_assign=false`
+- `flow_type=0`
+- `range` 可选近30天或近90天
+
+星图视频的参数约束：
+
+- `type=2`
+- `only_assign` 可选
+- `flow_type` 可选
+- `range` 可选近30天或近90天
+
+## 指标阈值
+
+支持下面 7 个指标阈值：
+
+- 完播率 >=
+- 播放量中位数 >=
+- 互动率 >=
+- 作品平均时长 >=
+- 作品平均评论数 >=
+- 作品平均点赞数 >=
+- 作品平均转发数 >=
+
+规则：
+
+- 没填的阈值不参与筛选。
+- 填了多个阈值时，必须全部满足才保留达人。
+- 完播率和互动率使用百分数显示值，例如填 `30` 表示 `30%`。
+- 作品平均时长使用秒，例如填 `56` 表示 `56秒`。
+- 播放量、评论、点赞、转发使用普通数字。
+- 如果某个达人在所选参数组合下接口请求失败或缺少被启用的指标，则视为不满足筛选。
+
+## 生效范围
+
+阈值筛选同时作用于：
+
+- 导出 CSV
+- 提交批次
+
+处理顺序：
+
+1. 先按现有导出范围收集达人，例如当前页、前5页、前10页、全部或自定义页数。
+2. 如果用户没有填写任何阈值，保持现有导出/提交行为。
+3. 如果用户填写了阈值，对收集到的每个达人按当前筛选维度调用一次 `get_author_spread_info`。
+4. 将接口响应映射为显示值。
+5. 用已填写的阈值过滤达人。
+6. 过滤后的达人进入导出 CSV 或提交批次。
+
+## UI 设计
+
+在现有插件操作区中增加一组紧凑控件：
+
+- 视频类别下拉框
+- 指派下拉框
+- 营销流量下拉框
+- 数据范围下拉框
+- 7 个数字输入框
+
+当视频类别选择“个人视频”时：
+
+- 指派固定为“不限指派”
+- 营销流量固定为“不排除营销流量”
+- 对应控件禁用
+
+## 失败处理
+
+- 单个达人筛选请求失败：该达人不满足筛选。
+- 全部达人都不满足：导出空 CSV 表头；提交批次时按现有空记录处理。
+- 阈值输入非法：阻止导出/提交，并提示用户修正。
+
+## 测试要求
+
+- 读取 toolbar 中的筛选参数和阈值。
+- 个人视频禁用指派和营销流量控件。
+- 空阈值时不触发二次筛选。
+- 有阈值时按所选参数调用 `get_author_spread_info`。
+- 百分比阈值按显示值比较。
+- 多个阈值按 AND 关系过滤。
+- 导出 CSV 和提交批次都应用二次筛选。