Add Chinese project and user documentation

2026-04-29 18:46:17 +08:00
parent 376c7b510e
commit b308b49368
2 changed files with 676 additions and 116 deletions
@@ -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`