# 项目流程说明文档

## 1. 项目用途

本项目是公司内部使用的 Chrome 插件，用于增强巨量星图达人市场页面的达人筛选、数据导出和批次提交效率。

它解决的业务问题是：使用者在星图达人市场中筛选达人后，可以直接在页面上补充查看看后搜率、秒思后台指标等数据，并把选中的达人导出为 CSV，或提交为后续业务处理批次。

项目输入包括：

- 巨量星图达人市场页面中的达人列表、筛选条件和分页结果；
- 使用者在页面上勾选的达人；
- 使用者粘贴的达人星图 ID；
- 使用者填写的批次名称；
- 使用者选择的导出字段和传播指标筛选阈值；
- 当前插件登录用户的 Logto 身份和访问令牌。

项目处理过程包括：

- 在星图达人市场页面挂载插件工具栏；
- 读取当前页面或星图列表接口返回的达人数据；
- 根据勾选范围、分页范围、阈值筛选规则确定最终达人集合；
- 调用星图接口补充看后搜率、画像、商业能力、传播指标等信息；
- 调用公司后端接口补充秒思 api 指标；
- 生成 CSV 文件，或组装批次 payload 提交到后端。

项目输出包括：

- 页面上新增的数据列和状态提示；
- 下载到本地的 CSV 文件；
- 提交到后端的达人批次；
- 插件弹窗中的登录状态和更新状态。

项目依赖的外部平台、数据源或服务包括：

- 巨量星图网页和星图接口；
- 公司 Logto 登录系统；
- 公司 talent-search 后端服务；
- 本地或内网批次提交后端；
- COS 上的插件更新清单和安装包。

主要使用者是 AIGC 部门或相关业务同事。通常在以下场景使用：

- 在星图市场中筛选达人后，需要快速导出达人数据；
- 已知一批星图 ID，需要批量补齐画像、效果预估和内容指标；
- 需要把一批达人提交给后续业务系统继续处理；
- 需要检查或更新内部插件版本。

## 2. 整体流程总览

完整主流程按真实使用顺序如下：

1. 安装或更新插件；
2. 登录插件；
3. 打开巨量星图达人市场页面；
4. 插件读取登录状态并挂载工具栏；
5. 插件读取当前星图达人列表，并补充页面展示指标；
6. 使用者选择达人、字段、传播指标筛选条件或输入星图 ID；
7. 使用者触发导出或提交批次；
8. 插件收集达人数据，按规则过滤、去重、补充字段；
9. 插件调用星图接口和公司后端接口补充数据；
10. 插件下载 CSV，或把批次提交给后端；
11. 使用者通过状态提示、下载文件或后端批次结果确认任务完成。

### 2.1 安装或更新插件

- 触发者：使用者或管理员。
- 输入：内部 ZIP 安装包，或插件弹窗中发现的新版本安装包。
- 处理：解压 ZIP，在 Chrome 扩展页加载 `dist` 文件夹；更新时下载新版 ZIP 后人工重新加载插件。
- 输出：Chrome 中安装好的 `Star Chart Search Enhancer` 插件。
- 下一步：登录插件。
- 人工操作：需要人工解压、加载或重新加载插件。
- 条件分支：如果旧版本无法检查更新，需要做一次手动过桥升级。

### 2.2 登录插件

- 触发者：使用者点击插件弹窗中的登录按钮。
- 输入：公司账号登录态。
- 处理：通过 Logto 完成 Chrome 扩展登录，并获取访问后端资源的 token。
- 输出：插件弹窗显示已登录状态，内容脚本后续可以挂载业务工具栏。
- 下一步：打开星图达人市场页面。
- 人工操作：需要使用者完成登录。
- 条件分支：未登录或登录过期时，星图页面不会进入导出/提交流程，只显示登录提示。

### 2.3 打开星图达人市场页面

- 触发者：使用者访问星图市场页面。
- 输入：星图网页登录态、当前页面筛选条件、星图市场列表。
- 处理：插件仅在 `xingtu.cn` 域名下的达人市场页面生效；进入页面后先安装页面桥接逻辑，再检查插件登录状态。
- 输出：页面上出现插件工具栏和增强列。
- 下一步：读取达人列表并补充数据。
- 人工操作：使用者需要在星图网页中完成筛选、搜索、翻页或勾选。
- 条件分支：如果页面不是星图达人市场页面，插件不启动主流程。

### 2.4 页面增强和数据补充

- 触发者：星图页面加载、翻页、列表变化或插件同步周期。
- 输入：页面可见达人行、星图列表接口返回值、当前登录用户 token。
- 处理：插件读取达人 ID、名称、地区、报价等基础数据，补充看后搜率列和秒思指标列。
- 输出：页面上显示加载中、成功、失败或暂无数据等状态。
- 下一步：使用者选择导出、按 ID 导出或提交批次。
- 人工操作：无。
- 条件分支：如果某个指标加载失败，只影响该达人对应指标，不影响页面整体使用。

### 2.5 导出选中达人数据

- 触发者：使用者点击 `导出选中达人数据`。
- 输入：当前勾选达人、当前导出范围、字段选择配置、传播指标筛选条件。
- 处理：必须先勾选达人；插件收集导出范围内的达人，只保留该范围内已勾选的达人，然后补充内容数据、效果预估、画像、秒思指标等字段。
- 输出：CSV 文件下载到浏览器默认下载目录。
- 下一步：使用者检查 CSV 内容。
- 人工操作：需要使用者勾选达人并点击按钮。
- 条件分支：如果当前导出范围内没有选中的达人，则不下载 CSV 并提示。

### 2.6 按星图 ID 导出

- 触发者：使用者点击 `按星图ID导出`。
- 输入：弹窗中粘贴的达人星图 ID。
- 处理：插件校验 ID 格式、去重、忽略非法 token，然后逐个 ID 请求基础信息、看后搜率、传播指标、画像、商业能力和后端秒思指标。
- 输出：CSV 文件下载到浏览器默认下载目录。
- 下一步：使用者检查 CSV 中每个 ID 的导出状态和失败原因。
- 人工操作：需要使用者粘贴 ID 并确认。
- 条件分支：如果没有有效 ID，不执行导出并提示。

### 2.7 提交批次

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

## 3. 详细流程说明

### 3.1 插件安装与更新

- 步骤目的：让使用者在 Chrome 中获得可运行的内部插件。
- 输入内容：内部发布 ZIP、安装说明 PDF、Chrome 浏览器。
- 处理规则：
  - 首次安装需要解压 ZIP；
  - Chrome 加载的是解压后的 `dist` 文件夹；
  - 更新时仍然需要人工下载、解压并重新加载；
  - 扩展 ID 应为 `pkjopdibdnomhogjheclhnknmejccffg`。
- 输出结果：Chrome 扩展列表中出现正确插件。
- 外部依赖：Chrome 扩展能力；COS 更新文件。
- 失败后如何处理：安装失败不会影响外部数据；使用者无法进入后续流程。
- 是否影响后续步骤：影响。未安装或安装版本不正确时，后续导出和提交不可用。

### 3.2 插件登录

- 步骤目的：获得访问公司后端和受保护接口所需的用户身份。
- 输入内容：公司登录账号、Logto 登录配置。
- 处理规则：
  - 登录通过 Chrome identity 回调完成；
  - 插件读取用户 `sub`、用户名、资源地址和 scope；
  - 内容脚本进入星图页面时会先读取登录状态。
- 输出结果：已登录状态、可用 access token。
- 外部依赖：Logto 登录系统。
- 失败后如何处理：星图页面显示登录提示；不挂载业务工具栏。
- 是否影响后续步骤：影响。批次提交和后端指标查询都依赖 token。

### 3.3 星图市场页面启动

- 步骤目的：只在正确页面启用插件能力。
- 输入内容：当前浏览器 URL、页面 DOM、星图页面列表请求。
- 处理规则：
  - 只匹配巨量星图达人市场页面；
  - 进入页面后先安装桥接逻辑，用于捕获星图市场列表请求和页面列表数据；
  - 未登录时不进入业务控制流程；
  - 已登录时挂载工具栏和新增列。
- 输出结果：插件工具栏、选择框、增强数据列。
- 外部依赖：星图网页结构和浏览器内容脚本能力。
- 失败后如何处理：如果页面结构变化导致无法挂载，相关功能不可用；未确认是否有统一错误上报。
- 是否影响后续步骤：影响。工具栏未挂载时无法导出或提交。

### 3.4 读取达人列表

- 步骤目的：确定当前页面或导出范围内有哪些达人。
- 输入内容：星图页面列表行、星图列表接口返回值、当前分页状态。
- 处理规则：
  - 优先从星图市场列表接口返回中读取达人；
  - 关键字段包括达人 ID、达人名称、星图内部传播接口 ID、核心用户 ID、地区、报价和页面可导出字段；
  - 如果没有捕获到接口请求，则从页面 DOM 读取可见行；
  - 页面翻页导出时等待页面稳定后再读取；
  - 同一个达人重复出现时按达人 ID 合并。
- 输出结果：标准化后的达人记录集合。
- 外部依赖：星图市场列表接口和页面 DOM。
- 失败后如何处理：
  - 单页加载超时会终止本次范围导出；
  - 单条达人缺少 ID 或名称会被跳过；
  - 捕获接口失败时退回页面翻页读取。
- 是否影响后续步骤：影响。没有达人记录时，导出或提交结果为空或失败。

### 3.5 页面指标补充

- 步骤目的：在列表页直接显示补充指标，方便筛选和排序。
- 输入内容：当前页面达人 ID。
- 处理规则：
  - 看后搜率优先使用星图列表中已有值；
  - 如果列表值不完整，再调用星图看后搜率相关接口；
  - 秒思指标按当前页达人 ID 批量查询后端；
  - 已成功或已判定缺失的后端指标在当前页面会话中不重复查询；
  - 指标列支持页面内排序。
- 输出结果：页面增强列显示成功值、加载中、加载失败或暂无数据。
- 外部依赖：星图接口、公司后端指标接口。
- 失败后如何处理：单个达人指标失败只显示失败，不阻塞其他达人。
- 是否影响后续步骤：部分影响。导出时会复用已缓存指标，缺失时可能再次补充。

### 3.6 导出选中达人数据

- 步骤目的：把使用者选定的达人数据导出为 CSV。
- 输入内容：已勾选达人、当前导出范围、字段选择配置、传播指标筛选条件。
- 处理规则：
  - 必须先勾选达人；
  - 先按导出范围收集达人；
  - 再严格保留当前导出范围内已勾选的达人；
  - 对每个达人补充画像、商业能力、传播指标、看后搜率、秒思指标；
  - 字段选择只控制可选字段，基础字段、导出状态和失败原因等固定保留；
  - 如果全部画像请求失败，则不下载 CSV 并提示画像导出失败；
  - 单个达人部分接口失败时，CSV 保留该行，并写入导出状态和失败原因。
- 输出结果：CSV 文件。
- 外部依赖：星图画像接口、商业能力接口、传播指标接口、公司后端指标接口、浏览器下载能力。
- 失败后如何处理：
  - 没有勾选达人：提示并停止；
  - 当前范围内无选中达人：提示并停止；
  - 单个达人部分失败：记录为部分成功或失败；
  - 全部画像失败：不下载 CSV。
- 是否影响后续步骤：不影响外部系统写入；只影响本次下载结果。

### 3.7 按星图 ID 导出

- 步骤目的：在不依赖当前星图列表勾选的情况下，批量导出指定 ID 的达人数据。
- 输入内容：使用者粘贴的星图 ID 文本。
- 处理规则：
  - 支持用空格、换行、英文逗号、中文逗号、英文分号、中文分号分隔；
  - 只接受 16 到 20 位纯数字；
  - 重复 ID 会去重；
  - 非法 token 会计入提示，但不会进入导出；
  - 对有效 ID 逐个补齐基础信息、看后搜率、传播指标、画像、商业能力和后端秒思指标；
  - 每个 ID 生成一行 CSV，并标记成功、部分成功或失败。
- 输出结果：按 ID 导出的 CSV 文件。
- 外部依赖：星图基础信息接口、星图指标接口、公司后端指标接口、浏览器下载能力。
- 失败后如何处理：
  - 没有有效 ID：提示并停止；
  - 单个 ID 的部分接口失败：保留该行并写失败原因；
  - 整体流程异常：提示按 ID 导出失败。
- 是否影响后续步骤：不写入外部系统，不影响批次。

### 3.8 传播指标阈值筛选

- 步骤目的：在导出或提交前按内容传播表现过滤达人。
- 输入内容：视频类别、是否只看指派、是否排除营销流量、时间范围、七个指标阈值。
- 处理规则：
  - 没有填写任何阈值时，不启用该筛选；
  - 填写多个阈值时必须全部满足；
  - 个人视频固定为不限指派、不排除营销流量；
  - 星图视频可选择只看指派、不限指派、排除营销流量或不排除营销流量；
  - 完播率和互动率按显示百分数比较，例如 `30` 表示 `30%`；
  - 平均时长按秒比较；
  - 播放量、评论、点赞、转发按普通数字比较；
  - 请求失败或缺少被启用指标的达人视为不满足筛选。
- 输出结果：过滤后的达人集合。
- 外部依赖：星图传播指标接口。
- 失败后如何处理：
  - 阈值非法：阻止导出或提交并提示；
  - 单个达人筛选请求失败：跳过该达人；
  - 全部不满足：导出时可能生成只有表头的 CSV；提交批次时会按空记录继续组装并提交，后端是否接受未确认。
- 是否影响后续步骤：影响。过滤后的结果才进入 CSV 或批次 payload。

### 3.9 批次提交

- 步骤目的：把达人集合提交给后续业务系统。
- 输入内容：导出范围内达人、已选达人、传播指标筛选结果、批次名称、登录用户信息。
- 处理规则：
  - 点击后先输入批次名称；
  - 取消输入则停止；
  - 批次名为空则提示并停止；
  - 如果存在已勾选达人，则优先提交当前范围内已勾选达人；
  - 如果没有勾选达人，则提交当前范围内所有达人；
  - 如果已勾选达人不在当前范围内，则回退为提交当前范围内所有达人；
  - 前端不生成批次 ID，批次 ID 由后端生成；
  - payload 包含登录用户 ID、创建人名称、资源地址、批次名称、创建时间和达人列表；
  - 达人列表包含达人 ID、达人名称，存在核心用户 ID 时额外带上。
- 输出结果：后端批次记录；页面提示提交成功或失败。
- 外部依赖：Logto token、批次提交后端。
- 失败后如何处理：
  - 未登录：提示请先登录插件；
  - token 不可用：提交失败；
  - 401 或 403：提交失败并返回未授权错误；
  - 后端返回非成功：提交失败并显示错误；
  - 网络失败：提交失败。
- 是否影响后续步骤：影响外部后端数据。是否会重复创建批次取决于后端，当前项目前端没有确认幂等机制。

### 3.10 CSV 下载

- 步骤目的：把导出结果交付给使用者。
- 输入内容：生成好的 CSV 字符串和文件名。
- 处理规则：
  - 优先通过 Chrome 扩展后台下载；
  - 如果扩展下载通道不可用，则使用页面中的临时下载链接；
  - CSV 带 UTF-8 BOM，方便表格软件识别中文；
  - 普通导出文件名使用插件名加时间戳；
  - 按 ID 导出文件名包含按 ID 导出标识。
- 输出结果：浏览器下载列表中出现 CSV 文件。
- 外部依赖：Chrome downloads 能力或浏览器下载能力。
- 失败后如何处理：下载失败会提示；已生成数据不会写入外部系统。
- 是否影响后续步骤：不影响外部系统。

## 4. 接口和外部服务说明

| 接口/服务 | 用途 | 使用环节 | 核心入参 | 核心返回 | 分页 | 限流 | 并发控制 | 超时 | 重试机制 | 重试次数 | 会重试的情况 | 不会重试的情况 | 凭证/权限 | 额度/成本 | 失败处理 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 巨量星图网页 | 提供达人市场页面和当前筛选结果 | 页面启动、读取达人列表、人工筛选 | 星图网页登录态、页面筛选条件 | 达人列表页面 | 通过页面分页 | 未确认 | 页面翻页串行执行 | 页面翻页等待约 3 秒，页面稳定等待约 12 秒 | 无自动重试 | 0 | 无 | 页面结构异常、未登录、加载失败 | 星图账号和 cookie | 未确认 | 页面不匹配或结构异常时插件功能不可用 |
| `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 | 未确认 | 单项失败写入失败原因 |
| `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 | 未确认 | 指标补充失败时字段留空；筛选请求失败时该达人不满足筛选 |
| 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 不可用时不进入业务流程，或后端调用失败 |
| COS 更新清单 | 检查插件新版本 | 插件弹窗 | `latest.json` URL | 最新版本、ZIP URL、说明 PDF URL、发布时间、更新说明 | 否 | 未确认 | 弹窗打开后单次检查 | 未确认 | 无自动重试 | 0 | 无 | 请求失败、清单格式错误、URL 非 HTTPS | 清单和安装包需公开可读 | COS 存储和流量成本未确认 | 检查失败时弹窗显示无法检查更新，不影响已安装插件主功能 |
| Chrome downloads | 下载 CSV、更新包和说明 PDF | CSV 导出、插件更新 | 文件名、下载 URL 或 data URL | 浏览器下载任务 | 否 | 浏览器自身规则，未确认 | 由浏览器管理 | 未确认 | 无自动重试 | 0 | 无 | 下载权限不可用、浏览器拦截、URL 无效 | Chrome `downloads` 权限 | 未确认 | CSV 下载失败时回退页面链接下载；更新包下载失败时显示错误 |

凭证和权限说明：

- 星图接口依赖当前浏览器中的星图网页登录态和 cookie；
- 公司后端指标查询和批次提交依赖 Logto access token；
- 插件需要 Chrome `downloads`、`identity`、`storage` 权限；
- COS 更新包需要公开可读；
- 具体接口额度、调用成本、账号级限制均未确认。

## 5. 数据处理规则

### 5.1 数据来源

数据主要来自四类来源：

- 星图市场页面和列表接口：达人 ID、名称、地区、报价、粉丝、内容主题、预期播放、互动率、完播率等基础字段；
- 星图详情类接口：看后搜率、画像、商业能力、传播指标；
- 公司 talent-search 后端：秒思 api 指标；
- 使用者输入：勾选状态、星图 ID、批次名称、字段选择和阈值筛选条件。

### 5.2 保留规则

- 有有效达人 ID 和达人名称的记录会进入页面记录集合；
- 按 ID 导出时，有效 ID 即使部分接口失败也会生成 CSV 行；
- CSV 基础字段、导出状态、失败原因等固定字段会保留；
- 字段选择只影响可选数据字段，不删除固定标识字段。

### 5.3 过滤规则

- 星图页面中缺少达人 ID 或达人名称的行会跳过；
- 导出选中达人数据必须有已勾选达人；
- 画像导出只保留当前导出范围内的已勾选达人；
- 普通导出或提交批次如果存在已选达人，会优先保留当前范围内的已选达人；
- 如果当前范围内没有任何已选达人，普通导出或提交批次会回退为当前范围全部达人；
- 传播指标阈值筛选启用后，不满足全部阈值的达人会被过滤；
- 按 ID 导出时，非 16 到 20 位纯数字 token 会过滤。

### 5.4 去重规则

- 多页导出和后台分页导出按达人 ID 合并去重；
- 按 ID 导出对输入 ID 去重；
- 合并时优先保留已有的非空字段；
- 指标字段会在有新非空值时补充。

### 5.5 字段补充和合并规则

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

### 5.6 覆盖规则

- 当前页面会话内的内存记录会被补充和合并；
- 项目不会把 CSV 导出结果写回星图；
- 批次提交会向后端创建或提交数据，是否覆盖已有批次未确认；
- 字段选择配置会保存到浏览器 localStorage，下次导出沿用。

### 5.7 写入位置

- CSV 写入浏览器下载目录；
- 批次数据写入批次提交后端；
- 字段选择写入浏览器 localStorage；
- 登录状态由 Logto Chrome 扩展 SDK 管理；
- 项目本身不维护持久任务数据库。

### 5.8 写入失败处理

- CSV 下载失败会提示或使用备用下载方式；
- 批次提交失败会提示失败原因，本次提交不视为成功；
- 字段选择保存失败会被忽略，后续可能恢复默认全选字段；
- 后端指标补充失败不会阻止 CSV 生成，只会导致字段为空。

### 5.9 重复运行时数据变化

- 重复导出会重新生成新的 CSV 文件；
- 重复按 ID 导出不会写入外部业务系统；
- 重复提交批次可能在后端产生重复批次，是否由后端去重未确认；
- 页面内已缓存的成功指标可能在当前会话中复用，刷新页面后会重新读取。

## 6. 重复执行、中断恢复和幂等性

- 任务可以重复执行。
- CSV 导出重复执行会产生新的下载文件，不会覆盖星图或后端数据。
- 按 ID 导出重复执行会重新请求接口并生成新 CSV，不会写入后端批次。
- 字段选择重复保存会覆盖浏览器本地保存的字段选择。
- 批次提交重复执行是否会重复创建批次：未确认。当前前端没有批次幂等键，也不生成 batchId。
- 批次提交是否覆盖已有结果：未确认，取决于后端。
- 任务跑到一半失败后，当前项目没有持久任务状态记录。
- 导出中断后再次执行会从本次流程开头重新收集和请求，不会从上次中断点恢复。
- 页面会话中的指标缓存可以减少同一页面内重复请求，但不等同于断点续跑。
- 浏览器刷新、插件重载或页面关闭会丢失内存中的中间状态。
- 多页导出按达人 ID 去重，重复分页读取同一达人不会在 CSV 中重复出现。
- 按 ID 导出对输入 ID 去重，重复输入同一 ID 不会产生重复行。
- 阈值筛选没有持久状态，重新执行时按当前页面输入框值重新判断。

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

- 重新打开页面；
- 重新导出 CSV；
- 重新按 ID 导出；
- 重新检查更新；
- 重新保存字段选择。

重复执行可能有风险的操作：

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

未确认项：

- 后端批次接口是否按批次名称、用户或达人集合去重；
- 后端批次接口是否允许空达人列表；
- 后端是否有任务状态、失败重试或重复提交保护；
- Logto token 刷新失败后是否有 SDK 内部重试。

## 7. 项目使用方式

### 7.1 使用前准备

使用前需要准备：

- Google Chrome 浏览器；
- 内部发布的 `star-chart-search-enhancer-internal.zip`；
- 可访问巨量星图的账号；
- 可访问公司 Logto 登录系统的账号；
- 如果要提交批次，需要批次提交后端可访问；
- 如果要查询秒思 api 指标，需要 talent-search 后端授权可用。

需要的权限和凭证：

- Chrome 扩展加载权限；
- 星图网页登录态；
- Logto 登录态；
- talent-search 后端读取权限；
- 批次提交后端所需权限，具体 scope 是否只需当前配置未确认。

### 7.2 本地安装使用

1. 解压内部 ZIP；
2. 打开 `chrome://extensions`；
3. 开启开发者模式；
4. 点击加载已解压的扩展程序；
5. 选择解压后的 `dist` 文件夹；
6. 确认扩展 ID 为 `pkjopdibdnomhogjheclhnknmejccffg`；
7. 固定插件图标；
8. 点击插件图标并登录；
9. 打开 `https://xingtu.cn/ad/creator/market`；
10. 等待插件工具栏出现。

### 7.3 执行一次完整导出任务

1. 在星图市场中完成筛选；
2. 等待页面列表加载完成；
3. 勾选需要导出的达人；
4. 可选：点击 `选择字段` 调整 CSV 字段；
5. 可选：填写传播指标阈值；
6. 点击 `导出选中达人数据`；
7. 等待状态提示从导出中消失或浏览器下载完成；
8. 在下载目录或 Chrome 下载列表中查看 CSV；
9. 检查 `导出状态` 和 `失败原因` 字段。

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

1. 点击 `按星图ID导出`；
2. 粘贴达人星图 ID，每行一个或用分隔符隔开；
3. 点击确认；
4. 查看识别数量、去重后数量和非法数量提示；
5. 等待 CSV 下载；
6. 检查每行导出状态和失败原因。

### 7.5 执行一次批次提交

1. 在星图市场中完成筛选；
2. 可选：勾选需要提交的达人；
3. 可选：填写传播指标阈值；
4. 点击 `提交批次`；
5. 输入批次名称；
6. 等待页面提示 `批次提交成功`；
7. 到后端系统确认批次是否生成。

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

- 只登录：打开插件弹窗并登录；
- 只检查更新：登录后打开插件弹窗查看版本更新区域；
- 只选择字段：在星图市场页点击 `选择字段` 并保存；
- 只按 ID 导出：不需要勾选页面达人，直接点击 `按星图ID导出`；
- 只提交批次：不需要先导出 CSV，但需要登录并输入批次名称。

### 7.7 重新执行任务

- 重新导出：直接再次点击导出按钮；
- 重新按 ID 导出：再次打开 ID 输入弹窗并确认；
- 重新提交批次：再次点击提交批次并输入批次名称。注意可能创建重复批次，后端幂等未确认；
- 页面异常后重试：刷新星图页面，等待工具栏重新出现后再执行。

### 7.8 确认任务完成

- 导出任务：浏览器下载列表出现 CSV 文件；
- 按 ID 导出：CSV 文件名包含按 ID 导出标识，且文件中有导出状态列；
- 批次提交：页面显示 `批次提交成功`，并在后端系统中能看到对应批次；
- 插件更新：重新加载后插件版本显示为新版本。

### 7.9 危险操作

- 重复点击 `提交批次`；
- 修改后端地址后未验证就发给同事使用；
- 删除正在被 Chrome 加载的 `dist` 文件夹；
- 随意修改 Logto 配置、后端地址、scope 或 manifest key；
- 在未确认星图筛选条件的情况下提交全部范围达人；
- 阈值筛选填错导致提交集合被大幅改变。

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

- 固定扩展 ID 相关配置；
- Logto appId、endpoint、resource、scope；
- 批次提交后端地址；
- talent-search 后端地址；
- COS 更新清单 URL；
- 星图接口参数含义；
- 传播指标列名规则；
- 批次 payload 字段。

### 7.11 运行和发布方式

本地开发运行：

- 安装依赖：`npm install`；
- 运行测试：`npm test`；
- 开发构建：`npm run build`；
- 然后在 Chrome 中加载 `dist`。

内部发布构建：

- 运行测试；
- 执行内部打包；
- 生成 ZIP 和更新清单；
- 上传或分发给同事；
- 同事仍需人工解压和加载。

定时任务运行：

- 当前项目未确认存在服务端定时任务。
- 插件更新发布可通过 tag 触发 Drone 发布流程。

## 8. 运行参数和配置说明

| 配置名称 | 作用 | 默认值 | 可选值 | 修改影响 | 是否需要重启/重载 | 风险 |
|---|---|---|---|---|---|---|
| 扩展 ID / manifest key | 固定 Chrome 扩展身份 | `pkjopdibdnomhogjheclhnknmejccffg` | 未确认 | 影响 Logto 回调、用户安装识别、更新连续性 | 需要重新构建并重新加载插件 | 改错会导致登录失败或同事装到不同插件 |
| Logto endpoint | 登录服务地址 | `https://login-api.intelligrow.cn` | 未确认 | 影响登录和 token 获取 | 需要重新构建并重新加载插件 | 登录不可用 |
| Logto appId | 插件登录应用 ID | `i4jkllbvih0554r4n0fd3` | 未确认 | 影响登录应用和回调校验 | 需要重新构建并重新加载插件 | 登录不可用 |
| apiResource | token 资源地址 | `https://talent-search.intelligrow.cn` | 未确认 | 影响后端 token audience/resource | 需要重新构建并重新加载插件 | 后端接口 401/403 |
| scopes | 登录申请权限 | `openid`、`profile`、`offline_access`、`talent-search:read` | 未确认 | 影响 token 权限 | 需要重新登录；通常也需重新构建 | 后端读写权限不足 |
| enableDevAuthPanel | 是否显示开发调试面板 | `false` | `true` / `false` | 影响插件弹窗是否显示调试入口 | 需要重新构建并重新加载插件 | 暴露调试入口 |
| 批次提交后端地址 | 提交达人批次的目标服务 | 当前工作区为 `http://localhost:8083` | 其他后端地址未确认 | 影响批次提交去向 | 需要重新构建并重新加载插件 | 提交到错误环境、重复或丢失业务数据 |
| 后端指标服务地址 | 查询秒思 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. 任务执行和结果确认

### 9.1 任务开始标志

- 插件登录任务：点击插件弹窗登录按钮后跳转登录；
- 页面增强任务：星图市场页面出现插件工具栏和新增列；
- 导出任务：状态区出现 `画像导出中`、`按ID画像导出中` 或类似导出中提示；
- 批次提交任务：点击提交并输入批次名称后，状态区出现提交中提示；
- 更新检查任务：插件弹窗显示正在检查更新。

### 9.2 执行中状态

- 工具栏按钮会被禁用，防止同一流程中重复点击；
- 多页收集时会显示页码进度；
- 画像和按 ID 导出会显示当前处理序号；
- 页面指标列可能显示 `加载中...`；
- 后端指标可能显示暂无数据或加载失败。

### 9.3 成功完成标志

- CSV 导出：浏览器下载列表出现 CSV 文件；
- 按 ID 导出：下载完成，CSV 中每行有导出状态；
- 批次提交：页面提示 `批次提交成功`；
- 更新下载：弹窗提示已触发下载；
- 页面增强：指标列显示具体数值或明确的暂无数据状态。

### 9.4 部分成功表现

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

### 9.5 失败表现

- 未登录：星图页面显示登录提示，不出现业务工具栏；
- 没勾选就导出选中达人数据：提示请先勾选；
- 当前范围无选中达人：提示当前导出范围内没有选中的达人；
- 全部画像失败：提示画像导出失败，不下载 CSV；
- 按 ID 没有有效 ID：提示请输入有效的达人星图 ID；
- 批次提交失败：状态区显示接口错误或通用失败提示；
- 更新清单失败：弹窗显示暂时无法检查更新或错误信息。

### 9.6 最终结果查看位置

- CSV：浏览器默认下载目录或 Chrome 下载列表；
- 批次：批次提交后端系统，具体查看入口未确认；
- 插件版本：插件弹窗或 Chrome 扩展详情页；
- 登录状态：插件弹窗；
- 页面增强结果：星图达人市场页面新增列。

### 9.7 管理者确认标准

管理者确认一次任务是否达到预期时，应关注：

- 使用者是否登录了正确插件；
- 星图筛选条件是否符合业务目标；
- 导出的 CSV 行数是否符合已选达人或输入 ID 数量；
- CSV 中 `导出状态` 是否大部分为成功；
- 关键业务字段是否有值，例如内容数据、效果预估、画像、秒思 api 数据；
- 批次提交是否在后端生成对应批次；
- 批次名称、创建人和达人数量是否符合预期；
- 是否存在重复提交批次。

## 10. 重要限制和风险

- 星图接口调用额度限制：未确认。
- 星图接口限流规则：未确认。
- 公司后端接口额度限制：未确认。
- 批次提交接口幂等规则：未确认。
- 项目没有持久任务状态记录，不支持真正断点续跑。
- 导出范围过大时，会产生大量星图接口请求，运行时间会变长。
- 当前传播指标补充和筛选存在并发请求；是否有显式并发上限未确认，当前未看到稳定的业务级并发限制配置。
- 星图页面结构变化可能导致工具栏挂载、列表读取或翻页失效。
- 星图网页登录态过期会导致接口失败。
- Logto token 不可用会导致后端指标和批次提交失败。
- 批次提交重复执行可能产生重复批次。
- 修改后端地址可能把数据提交到错误环境。
- 字段选择保存到本地浏览器，换浏览器或清理数据后会恢复默认。
- 更新包仍需人工解压和重载，下载新版本不等于插件已更新。
- 删除或移动本地 `dist` 文件夹会导致已加载插件失效。
- 扩展 ID、Logto 回调和 manifest key 强相关，改错会导致登录失败。
- `http://localhost:8083` 作为批次提交默认地址时，只适合本机后端可用的场景；生产或同事环境是否适用未确认。
- 下载 CSV 不会自动校验业务完整性，需要使用者或管理者检查导出状态和关键字段。
- 传播指标阈值填错会改变导出或提交达人集合。

## 11. 未确认项清单

- 星图各接口是否存在明确限流：未确认。
- 星图各接口账号级、IP 级或 cookie 级调用额度：未确认。
- 星图各接口失败后是否由浏览器或服务端内部重试：未确认。
- 公司后端 `history/talents/search` 是否有分页上限、查询数量上限或限流：未确认。
- 公司后端 `history/talents/search` 的接口超时时间：未确认。
- 批次提交后端的生产地址：未确认；当前工作区配置为 `http://localhost:8083`。
- 批次提交后端是否支持幂等：未确认。
- 批次提交后端是否允许空达人列表：未确认。
- 批次提交后端是否会覆盖同名批次：未确认。
- 批次提交后端生成的 7 位数字批次 ID 的具体规则：未确认。
- 批次提交后端的查看入口和管理流程：未确认。
- 当前 Logto scope 是否足够覆盖批次写操作：未确认。
- COS 更新清单的权限、缓存和发布审核规则：未确认。
- Drone 发布是否为唯一正式发布方式：未确认。
- 插件是否有统一日志、错误上报或审计记录：未确认。
- 页面增强指标是否有跨页面或跨浏览器持久缓存：未确认；当前仅确认有页面会话内记录。
- 导出全部页面时最多导出多少页：后台静默导出当前最多尝试 200 页；真实星图侧上限未确认。
- 传播指标请求是否应该限制并发：需求文档曾提出需要限制，但当前真实业务级并发控制未确认。
- 后续业务系统如何消费批次：未确认。

## 12. 文档维护规则

从现在开始，任何模型或工程师在修改本项目代码时，都必须遵守以下规则：

1. 修改代码前，先检查本流程文档是否描述了相关流程；
2. 如果代码改动影响流程、接口、配置、数据处理规则、使用方式、任务执行方式、结果确认方式、限流、重试、超时、并发或幂等性，必须同步更新本文档；
3. 如果代码行为和文档描述发生冲突，必须以当前真实行为为准更新文档；
4. 如果改动较大，但判断不需要更新文档，必须说明原因；
5. 每次完成较大代码改动后，最终回复必须明确说明：
   - 是否检查了流程文档；
   - 是否更新了流程文档；
   - 更新了哪些部分；
   - 如果没有更新，为什么不需要更新。

以下情况都视为必须检查文档的较大改动：

- 改变整体流程顺序；
- 新增、删除或调整流程步骤；
- 新增、删除或替换外部接口；
- 修改接口参数、鉴权方式、分页方式、限流方式、重试方式、超时规则或并发规则；
- 修改数据过滤、去重、合并、覆盖、写入规则；
- 修改任务启动方式、运行参数或配置项；
- 修改任务成功、失败、部分成功的判断方式；
- 修改重复执行、中断恢复或幂等性行为；
- 修改最终结果的产出位置或格式；
- 修改会影响项目使用者操作方式的任何内容。