Add Chinese project and user documentation

README.md

@@ -1,133 +1,191 @@
-# Star Chart Search Enhancer
+# 星图增强插件
 
-Chrome MV3 extension for the Xingtu creator market page.
+这是一个供公司内部使用的 Chrome MV3 插件，用于增强巨量星图达人市场页面的使用体验。
 
-## Development
+主要功能：
+
+- 在星图达人列表页补充插件侧数据列
+- 支持勾选部分达人后导出 CSV
+- 支持将达人数据提交为批次
+- 集成 Logto 登录
+- 支持内部压缩包分发后通过 `Load unpacked` 安装
+
+当前固定扩展 ID：
+
+- `pkjopdibdnomhogjheclhnknmejccffg`
+
+---
+
+## 一、项目目录
+
+- `src/`
+  - 插件源码
+- `dist/`
+  - 开发构建产物
+- `dist-release/`
+  - 内部分发构建产物
+- `release/`
+  - 打包后的内部交付压缩包
+- `docs/`
+  - 项目说明文档
+- `tests/`
+  - 自动化测试
+- `scripts/`
+  - 构建和打包脚本
+
+---
+
+## 二、开发环境
+
+安装依赖：
+
+```bash
+npm install
+```
+
+运行测试：
+
+```bash
+npm test
+```
+
+开发构建：
+
+```bash
+npm run build
+```
+
+说明：
+
+- `npm run build` 会生成开发版到 `dist/`
+- 开发版包含本地调试需要的宽权限
+
+---
+
+## 三、内部交付构建
+
+生成内部使用构建：
+
+```bash
+npm run build:release
+```
+
+生成内部压缩包：
+
+```bash
+npm run package:internal
+```
+
+生成结果：
+
+- 构建目录：`dist-release/`
+- 压缩包：`release/star-chart-search-enhancer-internal.zip`
+
+说明：
+
+- 这个压缩包不是给 Chrome 商店上传的
+- 它是发给公司内部同事使用的交付包
+- 同事收到后需要解压，再到 `chrome://extensions` 中 `Load unpacked`
+
+---
+
+## 四、插件安装方式
+
+本项目当前采用公司内部手工安装方式：
+
+1. 解压内部压缩包
+2. 打开 `chrome://extensions`
+3. 打开右上角 `开发者模式`
+4. 点击 `加载已解压的扩展程序`
+5. 选择解压后的插件文件夹
+
+安装后请确认扩展 ID 是：
+
+- `pkjopdibdnomhogjheclhnknmejccffg`
+
+---
+
+## 五、认证与配置
+
+插件使用 Logto 登录。
+
+认证配置位于：
+
+- `src/shared/auth-config.ts`
+
+当前主要配置包括：
+
+- `logtoEndpoint`
+- `appId`
+- `apiResource`
+- `scopes`
+
+说明：
+
+- popup 中的开发调试面板默认关闭
+- 如果需要本地调试受保护接口，可以手动把 `enableDevAuthPanel` 改为 `true`
+
+---
+
+## 六、批次提交说明
+
+提交批次时，前端当前会提交以下核心字段：
+
+- `logtoUserId`
+- `creatorName`
+- `resource`
+- `batchName`
+- `createdAt`
+- `authors`
+
+说明：
+
+- `batchId` 不再由前端生成
+- 现在由后端生成 7 位数字批次 ID
+
+---
+
+## 七、重要文档
+
+给内部同事的安装与使用说明：
+
+- `docs/aigc-user-guide.md`
+
+内部压缩包分发说明：
+
+- `docs/internal-extension-distribution.md`
+
+---
+
+## 八、常用命令
 
 ```bash
 npm install
 npm test
 npm run build
-```
-
-## Release Build
-
-```bash
 npm run build:release
 npm run package:internal
 ```
 
-- `npm run build` outputs the development bundle to `dist/`
+---
-- `npm run build:release` outputs the internal distribution bundle to `dist-release/`
-- `npm run package:internal` creates `release/star-chart-search-enhancer-internal.zip`
-- The extension ID is fixed to `pkjopdibdnomhogjheclhnknmejccffg`
 
-## Load The Extension
+## 九、维护注意事项
 
-1. Run `npm run build`
+- 扩展 ID 已通过 `manifest.key` 固定
-2. Open `chrome://extensions`
+- 不要泄露本地私钥文件 `.local/extension-key.pem`
-3. Enable developer mode
+- 如果后端地址发生变化，需要同步更新：
-4. Choose `Load unpacked`
+  - `scripts/manifest.mjs`
-5. Select the `dist/` directory
+  - 对应后端配置文件
+  - 相关文档
 
-## Current Scope
+---
 
-- Adds two after-search-rate columns to the Xingtu market list
+## 十、当前状态
-- Adds a popup-based Logto auth entry
-- Hydrates the current page immediately
-- Provides plugin-owned filter, sort, and CSV export controls
-- Gates the market tools until auth is available
-- Triggers full-scan flow only when filter, sort, or export is used
 
-## Auth Configuration
+当前项目已经支持：
 
-The Logto integration is wired with placeholder values in `src/shared/auth-config.ts`.
+- 新固定扩展 ID
-Replace these before real sign-in testing:
+- 内部压缩包分发
-
+- 自定义批次名称弹窗
-- `logtoEndpoint`
+- 后台静默导出
-- `appId`
+- 批次提交不再由前端生成 `batchId`
-- `apiResource`
-- Any extra scopes beyond `openid`, `profile`, and `offline_access`
-
-The popup dev panel is controlled by `enableDevAuthPanel` and is disabled by default.
-
-## Popup Behavior
-
-1. Load the unpacked extension from `dist/`
-2. Click the extension icon
-3. Confirm the popup shows `登录 Logto` when unauthenticated
-4. After real Logto config is added, use the popup to sign in and sign out
-
-## Protected API Mock Test
-
-1. Set `enableDevAuthPanel` to `true` in `src/shared/auth-config.ts`
-2. Run `npm run mock:protected-api`
-3. Run `npm run build`
-4. Reload the unpacked extension from `dist/`
-5. Open the popup and log in
-6. Click `测试受保护接口`
-7. Confirm the popup shows JSON containing `"source": "mock-protected-api"` and `"message": "authorized"`
-
-## Batch Submit Mock Test
-
-1. Run `npm run mock:protected-api`
-2. Run `npm run build`
-3. Reload the unpacked extension from `dist/`
-4. Open `https://xingtu.cn/ad/creator/market`
-5. Choose an export range in the plugin toolbar
-6. Click `提交批次`
-7. Enter a batch name in the browser prompt
-8. Confirm the toolbar shows `批次提交成功`
-9. Confirm the mock batch response accepts the payload
-
-## Market Auth Gate
-
-When the market page is opened without a valid auth state, the content script renders
-`请先登录插件` and does not boot the filter, sort, or export toolbar.
-
-## Manual Verification
-
-1. Load the unpacked extension from `dist/`
-2. Open `https://xingtu.cn/ad/creator/market`
-3. Confirm the page shows the auth gate until login is available
-4. After authentication is wired, confirm the two new columns appear
-5. Confirm current-page rows move through loading and then render values or failure states
-6. Apply a threshold filter and confirm the list hides unmatched rows
-7. Apply a sort and confirm row order changes
-8. Export CSV and confirm the file includes plugin status and after-search-rate fields
-
-提交的数据格式
-```json
-{
-    "logtoUserId": "p7pdhhtde8kj",
-    "creatorName": "王少卿",
-    "resource": "https://talent-search.intelligrow.cn",
-    "batchName": "自动验证批次",
-    "createdAt": "<提交当时的 ISO 时间戳>",
-    "authors": [
-      { "authorId": "7041184989643276324", "authorName": "旖旖小虎🐯" },
-      { "authorId": "7021245050621263906", "authorName": "瑶一瑶小肉包" },
-      { "authorId": "6629722292110753806", "authorName": "陈翔六点半" },
-      { "authorId": "7065613279053217829", "authorName": "小花花的每一天" },
-      { "authorId": "7254389871895117885", "authorName": "疯铲姐妹" },
-      { "authorId": "7294473194298146854", "authorName": "奇奇de海洋" },
-      { "authorId": "6834119701379940360", "authorName": "任志达" },
-      { "authorId": "6870159718216630285", "authorName": "大师兄的表哥" },
-      { "authorId": "6833914516833566727", "authorName": "旺仔是三七分" },
-      { "authorId": "7401565089431552037", "authorName": "笑典动物园" },
-      { "authorId": "7120107426002501639", "authorName": "嘻哈不拆" },
-      { "authorId": "7015813716650393630", "authorName": "周星伦" },
-      { "authorId": "6870170568893661197", "authorName": "周周的周" },
-      { "authorId": "6839989503663276045", "authorName": "潇潇学姐" },
-      { "authorId": "7023032374749298718", "authorName": "大自然奇观" },
-      { "authorId": "6870164079617523719", "authorName": "王小怪" },
-      { "authorId": "6969058840033624100", "authorName": "周三拾" },
-      { "authorId": "6825383642127138829", "authorName": "罗臣臣" },
-      { "authorId": "6684403430837977100", "authorName": "段炼丶Exercise" },
-      { "authorId": "7319160797236559882", "authorName": "郑皓文" }
-    ]
-  }
-```
-
-Internal distribution steps are documented in
-`docs/internal-extension-distribution.md`.

docs/aigc-user-guide.md

@@ -0,0 +1,502 @@
+# 星图增强插件使用说明
+
+适用对象：AIGC 部门同事，默认不需要任何编程基础。
+
+这份说明会教你：
+
+- 如何安装插件
+- 如何登录插件
+- 如何在星图页面使用导出和提交批次功能
+- 如何更新插件
+- 遇到问题时应该怎么处理
+
+---
+
+## 一、这是什么
+
+这是一个给巨量星图达人列表页使用的 Chrome 插件。
+
+它的主要作用是：
+
+- 在星图达人列表页面提供增强数据
+- 支持勾选部分达人后导出 CSV
+- 支持把达人列表提交为批次
+
+插件名称：
+
+- `Star Chart Search Enhancer`
+
+当前固定扩展 ID：
+
+- `pkjopdibdnomhogjheclhnknmejccffg`
+
+如果你在 Chrome 扩展页里看到这个 ID，说明装的是正确版本。
+
+---
+
+## 二、安装前准备
+
+开始前请先确认：
+
+1. 你使用的是 `Google Chrome` 浏览器。
+2. 你已经拿到了同事发给你的插件压缩包：
+   - `star-chart-search-enhancer-internal.zip`
+3. 你可以正常访问：
+   - 巨量星图
+   - 公司登录系统
+
+注意：
+
+- 这个插件不是从 Chrome 网上应用店安装的。
+- 你必须手动解压并加载。
+
+---
+
+## 三、第一次安装
+
+### 第 1 步：解压压缩包
+
+找到收到的压缩包：
+
+- `star-chart-search-enhancer-internal.zip`
+
+右键解压。
+
+解压后你会得到一个文件夹。请记住这个文件夹的位置，不要删除。
+
+建议放在：
+
+- 桌面
+- 下载目录
+- 或者一个不会随手清理掉的位置
+
+不要放在：
+
+- 临时目录
+- 会被自动清理的文件夹
+
+原因：
+
+- Chrome 加载的是这个文件夹本身
+- 如果文件夹被删了，插件就失效了
+
+### 第 2 步：打开 Chrome 扩展页面
+
+在 Chrome 地址栏输入：
+
+```text
+chrome://extensions
+```
+
+然后按回车。
+
+### 第 3 步：打开开发者模式
+
+在扩展页面右上角，找到：
+
+- `开发者模式`
+
+把它打开。
+
+### 第 4 步：加载插件
+
+点击左上角或页面上的：
+
+- `加载已解压的扩展程序`
+
+然后选择刚才解压出来的那个文件夹。
+
+选择后，Chrome 会自动加载插件。
+
+### 第 5 步：确认是否安装成功
+
+在扩展列表中找到：
+
+- `Star Chart Search Enhancer`
+
+点击 `详情` 后，确认扩展 ID 是：
+
+- `pkjopdibdnomhogjheclhnknmejccffg`
+
+如果是这个 ID，说明安装的是正确版本。
+
+---
+
+## 四、固定到浏览器工具栏
+
+为了后续登录方便，建议把插件固定到工具栏。
+
+操作方法：
+
+1. 点击 Chrome 右上角的拼图图标
+2. 找到 `Star Chart Search Enhancer`
+3. 点击右边的图钉
+
+固定后，浏览器右上角就能直接看到插件图标。
+
+---
+
+## 五、如何登录
+
+### 第 1 步：打开插件弹窗
+
+点击 Chrome 右上角工具栏中的插件图标。
+
+### 第 2 步：点击登录
+
+如果当前未登录，你会看到登录按钮。
+
+点击：
+
+- `登录 Logto`
+
+### 第 3 步：完成登录
+
+系统会自动跳转到公司登录流程。
+
+按页面提示完成登录。
+
+### 第 4 步：确认登录成功
+
+登录成功后，再次点击插件图标。
+
+你会看到：
+
+- 已登录状态
+- 你的用户名信息
+- 退出登录按钮
+
+如果这里能正常显示，说明登录已经成功。
+
+---
+
+## 六、进入星图页面
+
+插件只在巨量星图达人市场页面生效。
+
+请打开类似下面的页面：
+
+```text
+https://xingtu.cn/ad/creator/market
+```
+
+进入后，等待页面加载完成。
+
+如果你已经登录插件，页面上会出现插件自己的工具栏和增强列。
+
+---
+
+## 七、页面上你会看到什么
+
+在星图页面中，插件会新增一组自己的操作区，常见元素包括：
+
+- 导出范围下拉框
+- `导出CSV` 按钮
+- `提交批次` 按钮
+- 状态提示文字
+- 每一行达人前面的勾选框
+
+其中：
+
+- `导出CSV`：把当前选择的数据导出为表格文件
+- `提交批次`：把当前选择的数据提交为批次
+
+---
+
+## 八、如何选择达人
+
+页面上每个达人前面都有一个勾选框。
+
+你可以：
+
+- 单独勾选某几个达人
+- 勾选表头复选框，快速全选当前页
+
+规则说明：
+
+- 如果你勾选了达人，再点击导出或提交，系统会优先处理你勾选的这些达人
+- 如果你没有勾选任何达人，则默认按当前导出范围处理全部达人
+
+---
+
+## 九、导出 CSV 的方法
+
+### 1. 选择导出范围
+
+在插件工具栏中，你会看到导出范围下拉框，可选：
+
+- `当前页`
+- `前5页`
+- `前10页`
+- `全部`
+- `自定义`
+
+如果选择 `自定义`，需要再输入页数。
+
+### 2. 如果只想导出部分达人
+
+先勾选你想要的达人，再点击导出。
+
+这样导出的 CSV 只会包含你勾选的人。
+
+### 3. 点击导出
+
+点击：
+
+- `导出CSV`
+
+### 4. 等待导出完成
+
+页面上会显示状态，例如：
+
+- `导出中...`
+
+导出完成后，浏览器会自动下载 CSV 文件。
+
+### 5. 去哪里找文件
+
+通常会在浏览器默认下载目录里找到。
+
+如果你不确定下载到了哪里：
+
+1. 打开 Chrome 下载列表
+2. 找到最新下载的 CSV 文件
+
+---
+
+## 十、提交批次的方法
+
+### 1. 选择范围
+
+和导出一样，先选择导出范围：
+
+- 当前页
+- 前5页
+- 前10页
+- 全部
+- 自定义
+
+### 2. 如果只想提交部分达人
+
+先勾选想提交的达人。
+
+### 3. 点击提交
+
+点击：
+
+- `提交批次`
+
+### 4. 输入批次名称
+
+这时会弹出一个自定义输入框，不再是浏览器原生弹窗。
+
+你会看到：
+
+- 标题
+- 输入框
+- `取消`
+- `确认提交`
+
+建议批次名称写得清楚一些，例如：
+
+- `618达人筛选第一批`
+- `食品饮料-KOL测试批次`
+- `5月女装达人候选`
+
+### 5. 确认提交
+
+输入后点击：
+
+- `确认提交`
+
+也可以直接按回车提交。
+
+### 6. 提交成功的提示
+
+如果成功，页面状态会显示：
+
+- `批次提交成功`
+
+如果失败，会看到错误提示。
+
+---
+
+## 十一、批次名称填写建议
+
+建议使用容易看懂的命名方式：
+
+- 时间 + 主题
+- 项目 + 人群
+- 场景 + 顺序编号
+
+推荐示例：
+
+- `2026-05-电商零食达人初筛`
+- `AIGC视频合作达人第一批`
+- `母婴品类候选达人-第1批`
+
+不推荐示例：
+
+- `测试`
+- `aaa`
+- `批次1`
+
+原因：
+
+- 后续回看时不容易分辨
+- 团队协作时不方便沟通
+
+---
+
+## 十二、如何更新插件
+
+当你收到新的插件压缩包时，不需要重新从零安装。
+
+按照下面做：
+
+### 方法一：替换文件夹后重新加载
+
+1. 删除旧的解压文件夹，或用新的内容覆盖旧文件夹
+2. 打开：
+   - `chrome://extensions`
+3. 找到：
+   - `Star Chart Search Enhancer`
+4. 点击：
+   - `重新加载`
+
+### 方法二：重新解压到新文件夹再重新加载
+
+1. 解压新的压缩包
+2. 打开：
+   - `chrome://extensions`
+3. 如果扩展还在，先看它当前对应的文件夹是否还是旧目录
+4. 如有需要，移除旧插件，再重新 `加载已解压的扩展程序`
+
+更新后请确认扩展 ID 仍然是：
+
+- `pkjopdibdnomhogjheclhnknmejccffg`
+
+如果 ID 不是这个，说明装错版本了。
+
+---
+
+## 十三、常见问题
+
+### 1. 看不到插件按钮
+
+处理方法：
+
+1. 点击浏览器右上角拼图图标
+2. 找到 `Star Chart Search Enhancer`
+3. 点击图钉固定
+
+### 2. 打开星图页面后没有出现插件工具栏
+
+先检查：
+
+1. 是否已经登录插件
+2. 是否打开的是星图达人市场页
+3. 插件是否启用
+
+如果还不行：
+
+1. 打开 `chrome://extensions`
+2. 找到插件
+3. 点击 `重新加载`
+4. 刷新星图页面
+
+### 3. 点击登录后没反应或登录失败
+
+先尝试：
+
+1. 关闭登录弹窗
+2. 再次点击插件图标
+3. 重新登录
+
+如果仍然失败，请把下面信息发给维护同事：
+
+- 出错时间
+- 浏览器截图
+- 是否能打开星图
+- 是否能看到插件图标
+
+### 4. 提交批次失败
+
+请先确认：
+
+1. 你已经登录插件
+2. 批次名称不是空的
+3. 当前页面数据已经加载出来
+
+如果还是失败，请把：
+
+- 页面提示内容
+- 提交时的截图
+- 使用的批次名称
+
+发给维护同事。
+
+### 5. 导出 CSV 没下载
+
+先检查：
+
+1. 浏览器是否拦截下载
+2. 默认下载目录里是否已有文件
+3. Chrome 下载列表里是否能看到记录
+
+### 6. 扩展列表里出现两个同名插件
+
+正确处理方式：
+
+1. 打开 `chrome://extensions`
+2. 查看两个扩展的 ID
+3. 保留：
+   - `pkjopdibdnomhogjheclhnknmejccffg`
+4. 删除不是这个 ID 的旧版本
+
+---
+
+## 十四、建议的日常使用流程
+
+推荐按下面顺序使用：
+
+1. 打开 Chrome
+2. 确认插件已启用
+3. 点击插件图标确认登录状态
+4. 打开星图达人市场页
+5. 等待页面数据加载完成
+6. 先勾选需要的人，或直接选择范围
+7. 需要表格时点 `导出CSV`
+8. 需要进入后续流程时点 `提交批次`
+
+---
+
+## 十五、遇到问题时请这样反馈
+
+如果需要找维护同事帮忙，请尽量一次性提供以下信息：
+
+- 你在做什么操作
+- 出问题的时间
+- 页面截图
+- 浏览器里看到的提示文字
+- 扩展 ID 是否为 `pkjopdibdnomhogjheclhnknmejccffg`
+
+这样能更快定位问题。
+
+---
+
+## 十六、给安装同事的一句话版本
+
+如果你要把最短说明发给同事，可以直接复制下面这段：
+
+```text
+1. 解压收到的插件压缩包
+2. 打开 chrome://extensions
+3. 打开右上角“开发者模式”
+4. 点击“加载已解压的扩展程序”
+5. 选择解压后的文件夹
+6. 确认插件名称是 Star Chart Search Enhancer
+7. 确认扩展 ID 是 pkjopdibdnomhogjheclhnknmejccffg
+8. 点击右上角插件图标完成登录
+9. 打开巨量星图达人市场页面开始使用
+```