feat: make audience export fields selective

2026-07-27 15:37:35 +08:00
parent e062be6431
commit e15bc0657a
9 changed files with 858 additions and 1979 deletions
@@ -106,17 +106,17 @@

 - 触发者：使用者点击 `导出选中达人数据`。
 - 输入：当前勾选达人、当前导出范围、字段选择配置、传播指标筛选规则。
- 处理：必须先勾选达人；插件收集导出范围内的达人，只保留该范围内已勾选的达人，然后补充内容数据、效果预估、画像、秒思指标等字段。
+- 处理：必须先勾选达人；插件收集导出范围内的达人，只保留该范围内已勾选的达人，然后按字段选择配置补充内容数据、效果预估、画像、看后搜率和秒思指标。未勾选的数据类别不会调用对应补充接口；从未保存过字段配置时保持默认全量导出。
 - 输出：CSV 文件下载到浏览器默认下载目录。
 - 下一步：使用者检查 CSV 内容。
 - 人工操作：需要使用者勾选达人并点击按钮。
- 条件分支：如果当前导出范围内没有选中的达人，则不下载 CSV 并提示。
+- 条件分支：如果当前导出范围内没有选中的达人，则不下载 CSV 并提示；单项补充失败不阻止下载，CSV 的 `导出状态` 和 `失败原因` 会标明部分成功及失败来源。

 ### 2.6 按星图 ID 导出

 - 触发者：使用者点击 `按星图ID导出`。
 - 输入：弹窗中粘贴的达人星图 ID。
- 处理：插件校验 ID 格式、去重、忽略非法 token，然后逐个 ID 请求基础信息、看后搜率、传播指标、画像、商业能力和后端秒思指标。
+- 处理：插件校验 ID 格式、去重、忽略非法 token，然后逐个 ID 获取基础信息，并按字段选择配置请求看后搜率、传播指标、画像、效果预估和后端秒思指标。未勾选的数据类别不调用对应补充接口。
 - 输出：CSV 文件下载到浏览器默认下载目录。
 - 下一步：使用者检查 CSV 中每个 ID 的导出状态和失败原因。
 - 人工操作：需要使用者粘贴 ID 并确认。
@@ -216,9 +216,9 @@
  - 必须先勾选达人；
  - 先按导出范围收集达人；
  - 再严格保留当前导出范围内已勾选的达人；
-  - 对每个达人补充画像、商业能力、传播指标、看后搜率、秒思指标；
-  - 字段选择只控制可选字段，基础字段、导出状态和失败原因等固定保留；
-  - 如果全部画像请求失败，则不下载 CSV 并提示画像导出失败；
+  - 只补充已选字段对应的画像、效果预估、传播指标、看后搜率和秒思指标，未选数据类别不调用对应接口；
+  - 基础字段、导出状态和失败原因等固定保留；
+  - 画像请求全部失败时仍下载 CSV，已成功的效果预估等字段正常写入；
  - 单个达人部分接口失败时，CSV 保留该行，并写入导出状态和失败原因。
 - 输出结果：CSV 文件。
 - 外部依赖：星图画像接口、商业能力接口、传播指标接口、公司后端指标接口、浏览器下载能力。
@@ -226,7 +226,7 @@
  - 没有勾选达人：提示并停止；
  - 当前范围内无选中达人：提示并停止；
  - 单个达人部分失败：记录为部分成功或失败；
-  - 全部画像失败：不下载 CSV。
+  - 画像失败：对应画像单元格留空，失败来源写入 `失败原因`，其他成功数据仍保留并下载。
 - 是否影响后续步骤：不影响外部系统写入；只影响本次下载结果。

 ### 3.7 按星图 ID 导出
@@ -238,7 +238,7 @@
  - 只接受 16 到 20 位纯数字；
  - 重复 ID 会去重；
  - 非法 token 会计入提示，但不会进入导出；
-  - 对有效 ID 逐个补齐基础信息、看后搜率、传播指标、画像、商业能力和后端秒思指标；
+  - 对有效 ID 逐个获取基础信息，只补齐已选字段对应的看后搜率、传播指标、画像、效果预估和后端秒思指标；
  - 每个 ID 生成一行 CSV，并标记成功、部分成功或失败。
 - 输出结果：按 ID 导出的 CSV 文件。
 - 外部依赖：星图基础信息接口、星图指标接口、公司后端指标接口、浏览器下载能力。
@@ -301,7 +301,7 @@
  - 优先通过 Chrome 扩展后台下载；
  - 如果扩展下载通道不可用，则使用页面中的临时下载链接；
  - CSV 带 UTF-8 BOM，方便表格软件识别中文；
-  - 普通导出文件名使用插件名加时间戳；
+  - 选中达人导出文件名使用画像导出标识加时间戳；
  - 按 ID 导出文件名包含按 ID 导出标识。
 - 输出结果：浏览器下载列表中出现 CSV 文件。
 - 外部依赖：Chrome downloads 能力或浏览器下载能力。
@@ -316,11 +316,11 @@
 | `search_for_author_square` | 获取星图达人市场列表数据 | 后台分页导出、读取达人基础字段 | 当前星图列表请求参数、页码 | 达人列表、分页信息、基础字段 | 是 | 未确认 | 后台分页串行请求；`全部` 最多尝试 200 页 | 未单独设置 fetch 超时 | 无自动重试 | 0 | 无 | 请求失败、响应结构异常、解析失败 | 星图网页登录态和 cookie | 未确认 | 请求失败或解析失败时退回页面翻页读取 |
 | `get_author_commerce_seed_base_info` | 优先获取看后搜率 | 页面增强、导出补充 | `o_author_id`、`range=90` | 商单视频/个人视频看后搜率相关字段 | 否 | 未确认 | 页面增强按当前页达人并发请求；导出补充按达人串行处理 | 8 秒 | 有备用接口回退，但不是同接口重试 | 0 | 非超时失败且未成功时转备用接口 | 超时、备用接口也失败 | 星图网页登录态和 cookie | 未确认 | 请求失败时转备用接口；超时直接记为失败 |
 | `get_author_ase_info` | 备用获取看后搜率 | 页面增强、导出补充 | `author_id`、`range=30` | 看后搜率相关字段 | 否 | 未确认 | 页面增强按当前页达人并发请求；导出补充按达人串行处理 | 8 秒 | 无自动重试 | 0 | 无 | 任意失败、超时、缺少指标 | 星图网页登录态和 cookie | 未确认 | 失败后标记该达人看后搜率失败 |
-| `author_audience_distribution` | 获取观众画像 | 导出选中达人、按 ID 导出 | `o_author_id`、`platform_source=1`、`platform_channel=1`、`link_type=5` | 性别、年龄、省份、城市、兴趣、人群等分布 | 否 | 未确认 | 单个达人内画像和商业能力并发；达人之间串行处理 | 8 秒 | 无自动重试 | 0 | 无 | 任意失败、超时、响应缺字段 | 星图网页登录态和 cookie | 未确认 | 单项失败写入失败原因；全部画像失败时不下载选中导出 CSV |
-| `get_author_fans_distribution` | 获取粉丝画像和铁粉画像 | 导出选中达人、按 ID 导出 | `o_author_id`、`platform_source=1`、`author_type=1 或 5` | 粉丝或铁粉分布 | 否 | 未确认 | 单个达人内多个画像请求串行执行；达人之间串行处理 | 8 秒 | 无自动重试 | 0 | 无 | 任意失败、超时、响应缺字段 | 星图网页登录态和 cookie | 未确认 | 单项失败写入失败原因 |
+| `author_audience_distribution` | 获取观众画像 | 导出选中达人、按 ID 导出 | `o_author_id`、`platform_source=1`、`platform_channel=1`、`link_type=5` | 性别、年龄、省份、城市、兴趣、人群等分布 | 否 | 未确认 | 仅选择观众画像字段时调用；单个达人内与其他已选数据源并发；达人之间串行处理 | 8 秒 | 无自动重试 | 0 | 无 | 任意失败、超时、响应缺字段 | 星图网页登录态和 cookie | 未确认 | 单项失败写入该行失败原因，其他已选数据继续并下载 CSV |
+| `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_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 或缺少已选指标时该达人不满足筛选 |
 | 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 不可用时不进入业务流程，或后端调用失败 |
@@ -358,8 +358,8 @@
 - 星图页面中缺少达人 ID 或达人名称的行会跳过；
 - 导出选中达人数据必须有已勾选达人；
 - 画像导出只保留当前导出范围内的已勾选达人；
- 普通导出或提交批次如果存在已选达人，会优先保留当前范围内的已选达人；
- 如果当前范围内没有任何已选达人，普通导出或提交批次会回退为当前范围全部达人；
+- 提交批次如果存在已选达人，会优先保留当前范围内的已选达人；
+- 如果当前范围内没有任何已选达人，提交批次会回退为当前范围全部达人；
 - 传播指标规则启用后，不满足全部已选规则的达人会被过滤；
 - 按 ID 导出时，非 16 到 20 位纯数字 token 会过滤。

@@ -376,7 +376,7 @@
 - 看后搜率优先使用列表中已有值，不完整时再请求星图指标接口；
 - 秒思指标按 star_id 从后端补充；
 - 传播指标按多组参数生成不同列，不合并同名业务指标；
- `代表视频`可能被读取，但不会进入最终普通市场 CSV；
+- `代表视频`可能被读取，但不会进入最终达人数据 CSV；
 - 画像和商业能力字段追加在基础字段之后；
 - 传播指标字段追加在基础字段、看后搜率和秒思 api 字段之后。

@@ -624,7 +624,7 @@
 - 单个达人部分接口失败时，CSV 中该行 `导出状态` 为部分成功或失败，并在 `失败原因` 中列明失败项；
 - 秒思 api 指标失败时，对应字段为空或页面显示失败，不一定影响 CSV 下载；
 - 传播指标某组参数失败时，对应字段为空；
- 画像部分失败时，其他画像或商业能力字段仍可保留；
+- 画像部分或全部失败时，对应单元格留空并写入失败原因，其他画像或效果预估字段仍可保留；
 - 后端指标查询不到某个达人时显示暂无数据。

 ### 9.5 失败表现
@@ -632,7 +632,7 @@
 - 未登录：星图页面显示登录提示，不出现业务工具栏；
 - 没勾选就导出选中达人数据：提示请先勾选；
 - 当前范围无选中达人：提示当前导出范围内没有选中的达人；
- 全部画像失败：提示画像导出失败，不下载 CSV；
+- 全部已选补充数据都失败：CSV 仍会下载，该行标记为部分成功或失败并列明失败原因；
 - 按 ID 没有有效 ID：提示请输入有效的达人星图 ID；
 - 批次提交失败：状态区显示接口错误或通用失败提示；
 - 已选传播指标未填写合法阈值：状态区提示具体指标，导出或提交不会开始；