feat: streamline export field selection

2026-07-29 10:51:24 +08:00
parent 53db9b0777
commit d121849d3e
12 changed files with 1157 additions and 1700 deletions
@@ -12,14 +12,14 @@
 - 使用者在页面上勾选的达人（可选）；
 - 使用者粘贴的达人星图 ID；
 - 使用者填写的批次名称；
- 使用者选择的导出字段和传播指标筛选规则；
+- 使用者选择的导出字段；
 - 当前插件登录用户的 Logto 身份和访问令牌。

 项目处理过程包括：

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

 - 触发者：使用者点击 `导出选中达人数据`。
- 输入：可选的当前勾选达人、当前导出范围、字段选择配置、传播指标筛选规则。
+- 输入：可选的当前勾选达人、当前导出范围和字段选择配置。
 - 处理：选择 `全部` 且没有勾选达人时，插件从第 1 页收集当前筛选结果的全部分页并全部导出；只要存在勾选达人，则勾选优先，只保留导出范围内已勾选的达人。其他范围仍需要勾选达人。随后按字段选择配置补充内容数据、效果预估、画像、看后搜率和秒思指标。未勾选的数据类别不会调用对应补充接口；从未保存过字段配置时保持默认全量导出。
 - 输出：CSV 文件下载到浏览器默认下载目录。
 - 下一步：使用者检查 CSV 内容。
@@ -126,7 +126,7 @@

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

 - 步骤目的：把使用者选定的达人数据导出为 CSV。
- 输入内容：可选的已勾选达人、当前导出范围、字段选择配置、传播指标筛选规则。
+- 输入内容：可选的已勾选达人、当前导出范围和字段选择配置。
 - 处理规则：
  - 选择 `全部` 且没有勾选达人时，从第 1 页收集并导出当前筛选结果的全部分页；
  - 存在勾选达人时，勾选优先，严格保留导出范围内已勾选的达人；
@@ -248,31 +248,10 @@
  - 整体流程异常：提示按 ID 导出失败。
 - 是否影响后续步骤：不写入外部系统，不影响批次。

-### 3.8 传播指标规则筛选
-
- 步骤目的：在导出或提交前按内容传播表现过滤达人。
- 输入内容：可选的完播率、互动率规则；每条已选规则包含非负阈值和独立的视频类别、是否只看指派、是否排除营销流量、时间范围。
- 处理规则：
-  - 默认不选择任何指标，不启用二次筛选；
-  - 选择指标后必须填写该指标阈值，并为该指标选择一套独立视频口径；
-  - 同时选择完播率和互动率时，两条规则必须全部满足；
-  - 两条规则口径相同时，同一达人复用一次接口响应；口径不同时分别请求；
-  - 每条个人视频规则固定为不限指派、不排除营销流量；
-  - 每条星图视频规则可独立选择只看指派、不限指派、排除营销流量或不排除营销流量；
-  - 完播率和互动率按显示百分数比较，例如 `30` 表示 `30%`；
-  - 请求失败、缺少传播指标请求 ID 或缺少已选指标的达人视为不满足筛选。
- 输出结果：过滤后的达人集合。
- 外部依赖：星图传播指标接口。
- 失败后如何处理：
-  - 已选指标阈值为空或非法：阻止导出或提交，并提示具体指标；
-  - 单个达人筛选请求失败：跳过该达人；
-  - 全部不满足：导出时可能生成只有表头的 CSV；提交批次时会按空记录继续组装并提交，后端是否接受未确认。
- 是否影响后续步骤：影响。过滤后的结果才进入 CSV 或批次 payload。
-
-### 3.9 批次提交
+### 3.8 批次提交

 - 步骤目的：把达人集合提交给后续业务系统。
- 输入内容：导出范围内达人、已选达人、传播指标筛选结果、批次名称、登录用户信息。
+- 输入内容：导出范围内达人、已选达人、批次名称和登录用户信息。
 - 处理规则：
  - 点击后先输入批次名称；
  - 取消输入则停止；
@@ -293,7 +272,7 @@
  - 网络失败：提交失败。
 - 是否影响后续步骤：影响外部后端数据。是否会重复创建批次取决于后端，当前项目前端没有确认幂等机制。

-### 3.10 CSV 下载
+### 3.9 CSV 下载

 - 步骤目的：把导出结果交付给使用者。
 - 输入内容：生成好的 CSV 字符串和文件名。
@@ -320,7 +299,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 | 未确认 | 指标补充失败时字段留空；筛选请求失败、缺少请求 ID 或缺少已选指标时该达人不满足筛选 |
+| `get_author_spread_info` | 获取内容传播指标 | 内容数据导出 | `o_author_id`、`platform_source=1`、`platform_channel=1`、`type`、`flow_type`、`only_assign`、`range` | 完播率、播放量中位数、互动率、平均时长、平均评论、平均点赞、平均转发 | 否 | 未确认 | 只请求已勾选内容字段所属的参数组合；同一参数组合下勾选多个字段仍只请求一次；单个达人的多组已选参数串行，达人之间并发 | 8 秒 | 无自动重试 | 0 | 无 | 任意失败、超时、响应缺字段 | 星图网页登录态和 cookie | 未确认 | 指标补充失败时对应字段留空并记录失败来源 |
 | 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,14 +323,15 @@
 - 星图市场页面和列表接口：达人 ID、名称、地区、报价、粉丝、内容主题、预期播放、互动率、完播率等基础字段；
 - 星图详情类接口：看后搜率、画像、商业能力、传播指标；
 - 公司 talent-search 后端：秒思 api 指标；
- 使用者输入：勾选状态、星图 ID、批次名称、字段选择和传播指标筛选规则。
+- 使用者输入：勾选状态、星图 ID、批次名称和字段选择。

 ### 5.2 保留规则

 - 有有效达人 ID 和达人名称的记录会进入页面记录集合；
 - 按 ID 导出时，有效 ID 即使部分接口失败也会生成 CSV 行；
 - CSV 基础字段、导出状态、失败原因等固定字段会保留；
- 字段选择只影响可选数据字段，不删除固定标识字段。
+- 字段选择只影响可选数据字段，不删除固定标识字段；
+- 字段弹窗左侧持续展示已选字段，右侧支持按字段名或分类检索，并实时同步勾选状态。

 ### 5.3 过滤规则

@@ -359,7 +339,6 @@
 - 导出选中达人数据在选择 `全部` 且没有勾选时，保留当前筛选结果的全部分页；其他范围必须有已勾选达人；
 - 选择 `全部` 且存在勾选达人时，画像导出和提交批次都只保留全部范围内已勾选达人；
 - 选择 `全部` 时，勾选达人不在当前筛选结果内则不回退为全部达人；
- 传播指标规则启用后，不满足全部已选规则的达人会被过滤；
 - 按 ID 导出时，非 16 到 20 位纯数字 token 会过滤。

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

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

@@ -485,12 +463,11 @@
 1. 在星图市场中完成筛选；
 2. 等待页面列表加载完成；
 3. 选择 `全部` 时可不勾选；选择其他范围时勾选需要导出的达人；
-4. 可选：点击 `选择字段` 调整 CSV 字段；
-5. 可选：选择完播率、互动率筛选指标，并分别填写阈值和视频口径；
-6. 点击 `导出选中达人数据`；
-7. 等待状态提示从导出中消失或浏览器下载完成；
-8. 在下载目录或 Chrome 下载列表中查看 CSV；
-9. 检查 `导出状态` 和 `失败原因` 字段。
+4. 可选：点击 `选择字段`，通过关键词检索字段，并在已选区域确认最终字段；
+5. 点击 `导出选中达人数据`；
+6. 等待状态提示从导出中消失或浏览器下载完成；
+7. 在下载目录或 Chrome 下载列表中查看 CSV；
+8. 检查 `导出状态` 和 `失败原因` 字段。

 ### 7.4 按 ID 执行导出任务

@@ -505,11 +482,10 @@

 1. 在星图市场中完成筛选；
 2. 可选：勾选需要提交的达人；
-3. 可选：选择完播率、互动率筛选指标，并分别填写阈值和视频口径；
-4. 点击 `提交批次`；
-5. 输入批次名称；
-6. 等待页面提示 `批次提交成功`；
-7. 到后端系统确认批次是否生成。
+3. 点击 `提交批次`；
+4. 输入批次名称；
+5. 等待页面提示 `批次提交成功`；
+6. 到后端系统确认批次是否生成。

 ### 7.6 只执行某个子流程

@@ -589,8 +565,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 列 | 不需要重启，会本地保存 | 漏导业务字段 |
+| 字段选择 | 控制 CSV 可选字段 | 默认全选 | 支持按字段名或分类搜索；左侧显示已选字段 | 影响 CSV 列 | 不需要重启，会本地保存 | 漏导业务字段 |

 ## 9. 任务执行和结果确认