Add Chinese project and user documentation

This commit is contained in:
admin123 2026-04-29 18:46:17 +08:00
parent 376c7b510e
commit b308b49368
2 changed files with 676 additions and 116 deletions

290
README.md
View File

@ -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`
2. Open `chrome://extensions`
3. Enable developer mode
4. Choose `Load unpacked`
5. Select the `dist/` directory
- 扩展 ID 已通过 `manifest.key` 固定
- 不要泄露本地私钥文件 `.local/extension-key.pem`
- 如果后端地址发生变化,需要同步更新:
- `scripts/manifest.mjs`
- 对应后端配置文件
- 相关文档
## 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`.
Replace these before real sign-in testing:
- `logtoEndpoint`
- `appId`
- `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`.
- 新固定扩展 ID
- 内部压缩包分发
- 自定义批次名称弹窗
- 后台静默导出
- 批次提交不再由前端生成 `batchId`

502
docs/aigc-user-guide.md Normal file
View File

@ -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. 打开巨量星图达人市场页面开始使用
```