docs: update independent spread filter flow

2026-07-10 17:57:36 +08:00
parent 9326d676b7
commit 5c21f631d7
1 changed files with 29 additions and 28 deletions
@@ -12,14 +12,14 @@
 - 使用者在页面上勾选的达人；
 - 使用者粘贴的达人星图 ID；
 - 使用者填写的批次名称；
- 使用者选择的导出字段和传播指标筛选阈值；
+- 使用者选择的导出字段和传播指标筛选规则；
 - 当前插件登录用户的 Logto 身份和访问令牌。

 项目处理过程包括：

 - 在星图达人市场页面挂载插件工具栏；
 - 读取当前页面或星图列表接口返回的达人数据；
- 根据勾选范围、分页范围、阈值筛选规则确定最终达人集合；
+- 根据勾选范围、分页范围、传播指标规则确定最终达人集合；
 - 调用星图接口补充看后搜率、画像、商业能力、传播指标等信息；
 - 调用公司后端接口补充秒思 api 指标；
 - 生成 CSV 文件，或组装批次 payload 提交到后端。
@@ -55,7 +55,7 @@
 3. 打开巨量星图达人市场页面；
 4. 插件读取登录状态并挂载工具栏；
 5. 插件读取当前星图达人列表，并补充页面展示指标；
-6. 使用者选择达人、字段、传播指标筛选条件或输入星图 ID；
+6. 使用者选择达人、字段、传播指标筛选规则或输入星图 ID；
 7. 使用者触发导出或提交批次；
 8. 插件收集达人数据，按规则过滤、去重、补充字段；
 9. 插件调用星图接口和公司后端接口补充数据；
@@ -105,7 +105,7 @@
 ### 2.5 导出选中达人数据

 - 触发者：使用者点击 `导出选中达人数据`。
- 输入：当前勾选达人、当前导出范围、字段选择配置、传播指标筛选条件。
+- 输入：当前勾选达人、当前导出范围、字段选择配置、传播指标筛选规则。
 - 处理：必须先勾选达人；插件收集导出范围内的达人，只保留该范围内已勾选的达人，然后补充内容数据、效果预估、画像、秒思指标等字段。
 - 输出：CSV 文件下载到浏览器默认下载目录。
 - 下一步：使用者检查 CSV 内容。
@@ -126,7 +126,7 @@

 - 触发者：使用者点击 `提交批次`。
 - 输入：当前范围或已勾选达人、批次名称、登录用户信息。
- 处理：插件先要求输入批次名称，再收集达人数据，应用传播指标阈值筛选和选中规则，检查登录状态，组装批次 payload，提交到后端。
+- 处理：插件先要求输入批次名称，再收集达人数据，应用传播指标规则和选中规则，检查登录状态，组装批次 payload，提交到后端。
 - 输出：后端生成批次；页面显示 `批次提交成功` 或失败原因。
 - 下一步：在后端系统中继续处理批次。
 - 人工操作：需要使用者输入批次名称。
@@ -211,7 +211,7 @@
 ### 3.6 导出选中达人数据

 - 步骤目的：把使用者选定的达人数据导出为 CSV。
- 输入内容：已勾选达人、当前导出范围、字段选择配置、传播指标筛选条件。
+- 输入内容：已勾选达人、当前导出范围、字段选择配置、传播指标筛选规则。
 - 处理规则：
  - 必须先勾选达人；
  - 先按导出范围收集达人；
@@ -248,23 +248,23 @@
  - 整体流程异常：提示按 ID 导出失败。
 - 是否影响后续步骤：不写入外部系统，不影响批次。

-### 3.8 传播指标阈值筛选
+### 3.8 传播指标规则筛选

 - 步骤目的：在导出或提交前按内容传播表现过滤达人。
- 输入内容：视频类别、是否只看指派、是否排除营销流量、时间范围、七个指标阈值。
+- 输入内容：可选的完播率、互动率规则；每条已选规则包含非负阈值和独立的视频类别、是否只看指派、是否排除营销流量、时间范围。
 - 处理规则：
-  - 没有填写任何阈值时，不启用该筛选；
-  - 填写多个阈值时必须全部满足；
-  - 个人视频固定为不限指派、不排除营销流量；
-  - 星图视频可选择只看指派、不限指派、排除营销流量或不排除营销流量；
+  - 默认不选择任何指标，不启用二次筛选；
+  - 选择指标后必须填写该指标阈值，并为该指标选择一套独立视频口径；
+  - 同时选择完播率和互动率时，两条规则必须全部满足；
+  - 两条规则口径相同时，同一达人复用一次接口响应；口径不同时分别请求；
+  - 每条个人视频规则固定为不限指派、不排除营销流量；
+  - 每条星图视频规则可独立选择只看指派、不限指派、排除营销流量或不排除营销流量；
  - 完播率和互动率按显示百分数比较，例如 `30` 表示 `30%`；
-  - 平均时长按秒比较；
-  - 播放量、评论、点赞、转发按普通数字比较；
-  - 请求失败或缺少被启用指标的达人视为不满足筛选。
+  - 请求失败、缺少传播指标请求 ID 或缺少已选指标的达人视为不满足筛选。
 - 输出结果：过滤后的达人集合。
 - 外部依赖：星图传播指标接口。
 - 失败后如何处理：
-  - 阈值非法：阻止导出或提交并提示；
+  - 已选指标阈值为空或非法：阻止导出或提交，并提示具体指标；
  - 单个达人筛选请求失败：跳过该达人；
  - 全部不满足：导出时可能生成只有表头的 CSV；提交批次时会按空记录继续组装并提交，后端是否接受未确认。
 - 是否影响后续步骤：影响。过滤后的结果才进入 CSV 或批次 payload。
@@ -320,7 +320,7 @@
 | `get_author_fans_distribution` | 获取粉丝画像和铁粉画像 | 导出选中达人、按 ID 导出 | `o_author_id`、`platform_source=1`、`author_type=1 或 5` | 粉丝或铁粉分布 | 否 | 未确认 | 单个达人内多个画像请求串行执行；达人之间串行处理 | 8 秒 | 无自动重试 | 0 | 无 | 任意失败、超时、响应缺字段 | 星图网页登录态和 cookie | 未确认 | 单项失败写入失败原因 |
 | `get_author_base_info` | 按 ID 导出时获取达人基础信息 | 按星图 ID 导出 | `o_author_id`、`platform_source=1`、`platform_channel=1`、`recommend=true` 等 | 达人名称等基础信息 | 否 | 未确认 | 按 ID 导出中与看后搜率并发；不同 ID 串行处理 | 8 秒 | 无自动重试 | 0 | 无 | 任意失败、超时、响应缺字段 | 星图网页登录态和 cookie | 未确认 | 单个 ID 基础信息失败，CSV 中记录失败 |
 | `get_author_commerce_spread_info` | 获取商业能力和效果预估 | 导出选中达人、按 ID 导出 | `o_author_id` | 预期 CPM、预期 CPE、预期播放量、爆文率 | 否 | 未确认 | 与画像请求并发；达人之间串行处理 | 8 秒 | 无自动重试 | 0 | 无 | 任意失败或超时 | 星图网页登录态和 cookie | 未确认 | 单项失败写入失败原因，其他数据继续 |
-| `get_author_spread_info` | 获取内容传播指标，并用于阈值筛选 | 内容数据导出、阈值筛选 | `o_author_id`、`platform_source=1`、`platform_channel=1`、`type`、`flow_type`、`only_assign`、`range` | 完播率、播放量中位数、互动率、平均时长、平均评论、平均点赞、平均转发 | 否 | 未确认 | 指标补充对达人并发；单个达人内多组参数串行；筛选对达人并发 | 8 秒 | 无自动重试 | 0 | 无 | 任意失败、超时、响应缺字段 | 星图网页登录态和 cookie | 未确认 | 指标补充失败时字段留空；筛选请求失败时该达人不满足筛选 |
+| `get_author_spread_info` | 获取内容传播指标，并用于规则筛选 | 内容数据导出、传播指标筛选 | `o_author_id`、`platform_source=1`、`platform_channel=1`、`type`、`flow_type`、`only_assign`、`range` | 完播率、播放量中位数、互动率、平均时长、平均评论、平均点赞、平均转发 | 否 | 未确认 | 指标补充对达人并发；单个达人内多组参数串行；筛选对达人并发，同一达人相同口径的规则复用一次响应 | 8 秒 | 无自动重试 | 0 | 无 | 任意失败、超时、响应缺字段 | 星图网页登录态和 cookie | 未确认 | 指标补充失败时字段留空；筛选请求失败、缺少请求 ID 或缺少已选指标时该达人不满足筛选 |
 | talent-search 后端 `POST /api/v1/history/talents/search` | 查询秒思 api 指标 | 页面增强、CSV 导出、按 ID 导出 | Bearer token、`type=star_id`、`values`、`page=1`、`size=max(20, ID数量)` | 看后搜率、看后搜数、新增 A3、CPA3、cp_search 等 | 请求固定第一页；接口本身是否支持更多页未确认 | 未确认 | 按页面或导出集合批量请求；同一批只有一个请求 | 未确认 | 无自动重试 | 0 | 无 | token 失败、请求失败、响应结构异常 | Logto access token，当前 resource 为 talent-search | 未确认 | 页面增强中失败标记后端指标失败；导出中失败则相关字段为空 |
 | 批次提交后端 `POST /api/v1/batch-status/batches` | 创建达人批次 | 提交批次 | Bearer token、批次名称、创建人、达人列表 | 成功标志和后端数据 | 否 | 未确认 | 每次点击提交只发一个请求；按钮忙碌态防止流程内重复点击 | 未确认 | 无自动重试 | 0 | 无 | 401、403、非 2xx、后端 `success` 非 true、网络失败 | Logto access token；写权限 scope 是否足够未确认 | 未确认 | 401/403 或非成功响应会终止本次提交 |
 | Logto | 插件登录和获取访问 token | 登录、后端接口调用 | appId、resource、scope、Chrome redirect URL | 登录态、ID claims、access token | 否 | 未确认 | 由 Logto SDK 管理，项目内未设并发规则 | 未确认 | 项目内无自动重试；SDK 内部是否重试未确认 | 未确认 | 未确认 | 登录失败、token 不可用、授权不足 | 公司 Logto 账号和 Chrome identity 回调权限 | 未确认 | 登录失败或 token 不可用时不进入业务流程，或后端调用失败 |
@@ -344,7 +344,7 @@
 - 星图市场页面和列表接口：达人 ID、名称、地区、报价、粉丝、内容主题、预期播放、互动率、完播率等基础字段；
 - 星图详情类接口：看后搜率、画像、商业能力、传播指标；
 - 公司 talent-search 后端：秒思 api 指标；
- 使用者输入：勾选状态、星图 ID、批次名称、字段选择和阈值筛选条件。
+- 使用者输入：勾选状态、星图 ID、批次名称、字段选择和传播指标筛选规则。

 ### 5.2 保留规则

@@ -360,7 +360,7 @@
 - 画像导出只保留当前导出范围内的已勾选达人；
 - 普通导出或提交批次如果存在已选达人，会优先保留当前范围内的已选达人；
 - 如果当前范围内没有任何已选达人，普通导出或提交批次会回退为当前范围全部达人；
- 传播指标阈值筛选启用后，不满足全部阈值的达人会被过滤；
+- 传播指标规则启用后，不满足全部已选规则的达人会被过滤；
 - 按 ID 导出时，非 16 到 20 位纯数字 token 会过滤。

 ### 5.4 去重规则
@@ -423,7 +423,7 @@
 - 浏览器刷新、插件重载或页面关闭会丢失内存中的中间状态。
 - 多页导出按达人 ID 去重，重复分页读取同一达人不会在 CSV 中重复出现。
 - 按 ID 导出对输入 ID 去重，重复输入同一 ID 不会产生重复行。
- 阈值筛选没有持久状态，重新执行时按当前页面输入框值重新判断。
+- 传播指标规则没有持久状态，重新执行时按当前页面选择和输入值重新判断。

 重复执行相对安全的操作：

@@ -438,7 +438,7 @@
 - 重复点击提交批次；
 - 修改后端地址后提交批次；
 - 使用不同星图筛选条件或不同字段选择重复导出后，拿多个 CSV 混用；
- 阈值输入为空或变化后重复提交，可能导致提交达人集合变化。
+- 指标选择、视频口径或阈值变化后重复提交，可能导致提交达人集合变化。

 未确认项：

@@ -487,7 +487,7 @@
 2. 等待页面列表加载完成；
 3. 勾选需要导出的达人；
 4. 可选：点击 `选择字段` 调整 CSV 字段；
-5. 可选：填写传播指标阈值；
+5. 可选：选择完播率、互动率筛选指标，并分别填写阈值和视频口径；
 6. 点击 `导出选中达人数据`；
 7. 等待状态提示从导出中消失或浏览器下载完成；
 8. 在下载目录或 Chrome 下载列表中查看 CSV；
@@ -506,7 +506,7 @@

 1. 在星图市场中完成筛选；
 2. 可选：勾选需要提交的达人；
-3. 可选：填写传播指标阈值；
+3. 可选：选择完播率、互动率筛选指标，并分别填写阈值和视频口径；
 4. 点击 `提交批次`；
 5. 输入批次名称；
 6. 等待页面提示 `批次提交成功`；
@@ -541,7 +541,7 @@
 - 删除正在被 Chrome 加载的 `dist` 文件夹；
 - 随意修改 Logto 配置、后端地址、scope 或 manifest key；
 - 在未确认星图筛选条件的情况下提交全部范围达人；
- 阈值筛选填错导致提交集合被大幅改变。
+- 传播指标、视频口径或阈值选择错误，导致提交集合被大幅改变。

 ### 7.10 不能随便改的参数

@@ -590,7 +590,7 @@
 | 后端指标服务地址 | 查询秒思 api 指标 | `https://talent-search.intelligrow.cn` | 未确认 | 影响页面增强列和 CSV 秒思字段 | 需要重新构建并重新加载插件 | 指标为空、权限错误或消耗错误环境额度 |
 | COS 更新清单 URL | 插件弹窗检查新版本 | `https://wksgx-1343191620.cos.ap-nanjing.myqcloud.com/star-chart-search-enhancer/latest.json` | 其他 HTTPS URL | 影响更新提示和安装包下载 | 需要重新构建并重新加载插件 | 用户无法更新或下载错误包 |
 | 导出范围 | 决定收集哪些页面达人 | 当前工具栏默认隐藏，默认值为前 5 页；当前用户主入口通常要求勾选达人 | 当前页、前 5 页、前 10 页、全部、自定义 | 影响导出或提交的达人集合 | 不需要重启 | 范围过大增加接口调用量 |
-| 传播指标阈值 | 导出或提交前二次过滤达人 | 空 | 非负数字 | 影响最终保留达人集合 | 不需要重启 | 填错会过滤掉目标达人 |
+| 传播指标规则 | 导出或提交前二次过滤达人 | 默认不选择任何指标 | 完播率、互动率；每个已选指标填写非负阈值并选择独立视频口径 | 影响最终保留达人集合和星图接口请求口径 | 不需要重启 | 指标、口径或阈值选错会过滤掉目标达人 |
 | 字段选择 | 控制 CSV 可选字段 | 默认全选 | 可选字段集合 | 影响 CSV 列 | 不需要重启，会本地保存 | 漏导业务字段 |

 ## 9. 任务执行和结果确认
@@ -635,6 +635,7 @@
 - 全部画像失败：提示画像导出失败，不下载 CSV；
 - 按 ID 没有有效 ID：提示请输入有效的达人星图 ID；
 - 批次提交失败：状态区显示接口错误或通用失败提示；
+- 已选传播指标未填写合法阈值：状态区提示具体指标，导出或提交不会开始；
 - 更新清单失败：弹窗显示暂时无法检查更新或错误信息。

 ### 9.6 最终结果查看位置
@@ -666,7 +667,7 @@
 - 批次提交接口幂等规则：未确认。
 - 项目没有持久任务状态记录，不支持真正断点续跑。
 - 导出范围过大时，会产生大量星图接口请求，运行时间会变长。
- 当前传播指标补充和筛选存在并发请求；是否有显式并发上限未确认，当前未看到稳定的业务级并发限制配置。
+- 当前传播指标补充和筛选存在并发请求；筛选会复用同一达人相同视频口径的响应，但是否有显式并发上限未确认，当前未看到稳定的业务级并发限制配置。
 - 星图页面结构变化可能导致工具栏挂载、列表读取或翻页失效。
 - 星图网页登录态过期会导致接口失败。
 - Logto token 不可用会导致后端指标和批次提交失败。
@@ -678,7 +679,7 @@
 - 扩展 ID、Logto 回调和 manifest key 强相关，改错会导致登录失败。
 - `http://localhost:8083` 作为批次提交默认地址时，只适合本机后端可用的场景；生产或同事环境是否适用未确认。
 - 下载 CSV 不会自动校验业务完整性，需要使用者或管理者检查导出状态和关键字段。
- 传播指标阈值填错会改变导出或提交达人集合。
+- 传播指标、视频口径或阈值选错会改变导出或提交达人集合。

 ## 11. 未确认项清单

@@ -699,7 +700,7 @@
 - 插件是否有统一日志、错误上报或审计记录：未确认。
 - 页面增强指标是否有跨页面或跨浏览器持久缓存：未确认；当前仅确认有页面会话内记录。
 - 导出全部页面时最多导出多少页：后台静默导出当前最多尝试 200 页；真实星图侧上限未确认。
- 传播指标请求是否应该限制并发：需求文档曾提出需要限制，但当前真实业务级并发控制未确认。
+- 传播指标请求是否应该限制并发：当前筛选已按同一达人相同口径去重，但真实业务级并发上限仍未确认。
 - 后续业务系统如何消费批次：未确认。

 ## 12. 文档维护规则