From 5c21f631d7e8e7227a226492922b12c7b2c23b42 Mon Sep 17 00:00:00 2001 From: wxs Date: Fri, 10 Jul 2026 17:57:36 +0800 Subject: [PATCH] docs: update independent spread filter flow --- docs/项目流程说明文档.md | 57 ++++++++++++++++++++-------------------- 1 file changed, 29 insertions(+), 28 deletions(-) diff --git a/docs/项目流程说明文档.md b/docs/项目流程说明文档.md index 3857210..bb39288 100644 --- a/docs/项目流程说明文档.md +++ b/docs/项目流程说明文档.md @@ -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. 文档维护规则