From 58f5de03f2d62f8826d41a390314249950ba2517 Mon Sep 17 00:00:00 2001
From: admin123 <wangshaoqing@intelligrow.cn>
Date: Wed, 22 Apr 2026 13:37:32 +0800
Subject: [PATCH] docs: add market batch submit design

---
 .../2026-04-22-market-batch-submit-design.md  | 305 ++++++++++++++++++
 1 file changed, 305 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-04-22-market-batch-submit-design.md

diff --git a/docs/superpowers/specs/2026-04-22-market-batch-submit-design.md b/docs/superpowers/specs/2026-04-22-market-batch-submit-design.md
new file mode 100644
index 0000000..fbcde63
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-22-market-batch-submit-design.md
@@ -0,0 +1,305 @@
+# 星图达人批次提交设计
+
+## 背景
+
+当前插件已经具备以下能力：
+
+- 使用 Logto 登录并获取访问 `https://talent-search.intelligrow.cn` 的 access token
+- 读取星图市场页中的达人列表数据
+- 支持按当前页、前 5 页、前 10 页、全部、自定义页数进行多页采集
+- 支持导出 CSV
+
+下一阶段需要把“当前采集范围内的一批达人”提交给其他同学维护的后端接口，而不是逐条发送。用户期望在现有导出范围逻辑基础上，新增一个独立的“提交批次”动作，用来测试整批提交流程。
+
+## 目标
+
+- 在现有工具栏中新增一个独立的 `提交批次` 按钮
+- 提交动作复用当前导出范围逻辑，支持多页达人数据采集
+- 提交前通过浏览器 `prompt()` 让用户输入批次名称
+- 自动生成 `batchId = 批次名称 + 时间戳`
+- 将以下信息整合为单个批次 payload 发送给后端：
+  - Logto 用户 ID
+  - 星图达人 ID 列表
+  - 用户输入的批次名称
+  - 自动生成的批次 ID
+
+## 非目标
+
+- 不改造为逐条提交达人
+- 不移除或替代现有 `导出 CSV`
+- 不在首版实现复杂弹窗或表单 UI
+- 不在首版实现批次列表管理、重试历史、草稿保存
+
+## 方案对比
+
+### 方案 A：只提交当前页
+
+- 新按钮只处理当前页达人
+- 优点：实现最简单
+- 缺点：与现有多页导出/采集使用方式不一致，不符合真实业务需求
+
+### 方案 B：提交当前导出范围内的一整批达人
+
+- 复用现有导出范围控制器，提交当前选择范围内的所有达人
+- 优点：与用户当前使用习惯一致，便于从测试过渡到真实业务
+- 缺点：比只提交当前页多一层批次组装逻辑
+
+### 方案 C：先导出 CSV，再从 CSV 结果提交
+
+- 先走导出逻辑，再把导出结果转换为提交 payload
+- 优点：数据来源统一
+- 缺点：流程绕、耦合高，不适合作为长期模式
+
+推荐采用方案 B。
+
+## 交互设计
+
+### 工具栏按钮
+
+在现有工具栏中保留 `导出 CSV`，并新增：
+
+- `提交批次`
+
+两个按钮共享现有导出范围控件：
+
+- 当前页
+- 前 5 页
+- 前 10 页
+- 全部
+- 自定义
+
+### 批次名称输入
+
+用户点击 `提交批次` 时：
+
+1. 弹出浏览器 `prompt()`
+2. 提示文案建议为：`请输入批次名称`
+3. 用户输入如：`618 达人筛选第一批`
+
+处理规则：
+
+- 用户取消：直接终止，不报错
+- 输入为空或仅空格：提示 `请输入批次名称`
+- 输入有效：继续批次提交流程
+
+### 提交状态
+
+批次提交过程中：
+
+- `提交批次` 按钮禁用
+- `导出 CSV` 按钮与范围选择器一并禁用
+- 状态文案可复用现有导出状态区域
+
+建议状态文案：
+
+- 当前页：`提交中...`
+- 前 N 页：`提交中 3/5 页...`
+- 全部：`提交中 第 3 页...`
+
+### 成功与失败反馈
+
+成功：
+
+- 提示 `批次提交成功`
+
+失败：
+
+- 未登录：`请先登录插件`
+- 批次名为空：`请输入批次名称`
+- 接口失败：`批次提交失败，请稍后重试`
+
+## 批次数据模型
+
+首版建议 payload 结构如下：
+
+```json
+{
+  "logtoUserId": "p7pdhhtde8kj",
+  "creatorName": "王少卿",
+  "resource": "https://talent-search.intelligrow.cn",
+  "batchName": "618达人筛选第一批",
+  "batchId": "618达人筛选第一批-2026-04-22T12:30:00.000Z",
+  "createdAt": "2026-04-22T12:30:00.000Z",
+  "authors": [
+    {
+      "authorId": "111",
+      "authorName": "达人A"
+    },
+    {
+      "authorId": "222",
+      "authorName": "达人B"
+    }
+  ]
+}
+```
+
+### 字段来源
+
+- `logtoUserId`
+  - 来源：当前登录用户的 Logto `sub`
+- `creatorName`
+  - 来源：当前登录用户 `name` 或 `username`
+- `resource`
+  - 来源：当前认证配置中的 API resource
+- `batchName`
+  - 来源：用户在 `prompt()` 中输入
+- `createdAt`
+  - 来源：当前时间的 ISO 字符串
+- `batchId`
+  - 规则：`${batchName}-${createdAt}`
+- `authors`
+  - 来源：当前导出范围内采集出的达人记录
+
+### 达人字段
+
+首版只要求最小字段：
+
+- `authorId`
+- `authorName`
+
+后续如有需要，可增加：
+
+- `price21To60s`
+- 看后搜率字段
+- 城市/地区等补充信息
+
+## 数据流
+
+完整流程如下：
+
+1. 用户在工具栏选择导出范围
+2. 用户点击 `提交批次`
+3. 插件弹出 `prompt()` 请求输入批次名称
+4. 插件检查登录状态与用户信息
+5. 插件复用当前多页采集逻辑，获取当前范围内达人记录
+6. 插件读取 Logto 用户 ID
+7. 插件生成 `createdAt` 和 `batchId`
+8. 插件组装整批 payload
+9. 插件使用带 Bearer token 的客户端提交到后端
+10. 插件显示成功或失败状态
+
+## 模块边界
+
+建议按以下边界实现：
+
+### 工具栏层
+
+职责：
+
+- 渲染 `提交批次` 按钮
+- 管理按钮禁用态
+- 回传点击事件
+
+### 市场控制器层
+
+职责：
+
+- 响应 `提交批次` 点击
+- 调用 `prompt()` 获取批次名称
+- 复用现有导出范围采集逻辑
+- 调用批次 payload 组装器和提交客户端
+
+### 批次 payload 组装层
+
+职责：
+
+- 接收用户信息、批次名、时间戳、达人记录
+- 生成标准批次对象
+
+该层不负责网络请求，方便后续根据后端要求调整结构。
+
+### 批次提交客户端
+
+职责：
+
+- 获取 access token
+- 附带 `Authorization: Bearer <token>` 请求头
+- 向后端提交整批 JSON
+
+后续从 mock 接口切到真实接口时，应主要修改这一层。
+
+## 认证与授权
+
+当前系统已具备：
+
+- Logto 登录能力
+- 请求 `https://talent-search.intelligrow.cn` resource 的 access token
+- `talent-search:read` scope
+
+首版批次提交如果是写操作，后端后续可能需要新增写权限，例如：
+
+- `talent-search:write`
+- 或 `talent-search:batch:submit`
+
+如果后端要求新的写权限，则前端需要同步更新 `auth-config.ts` 中的 `scopes`。
+
+## 错误处理
+
+### 用户取消输入
+
+- 直接停止，不提示错误
+
+### 批次名为空
+
+- 不发请求
+- 直接提示 `请输入批次名称`
+
+### 未登录或取不到用户信息
+
+- 不发请求
+- 提示 `请先登录插件`
+
+### 采集失败
+
+- 复用当前导出多页采集失败逻辑
+- 不生成不完整 payload
+
+### 接口失败
+
+- 提示 `批次提交失败，请稍后重试`
+
+## 测试策略
+
+### 单元测试
+
+- 点击 `提交批次` 时会弹出 `prompt()`
+- 用户取消输入时不会继续提交
+- 空白批次名会报错
+- `batchId` 按 `批次名 + ISO 时间戳` 生成
+- payload 中包含：
+  - `logtoUserId`
+  - `batchName`
+  - `batchId`
+  - `authors[]`
+
+### 集成测试
+
+- `提交批次` 复用当前导出范围采集逻辑
+- 当前页模式只提交当前页达人
+- 多页模式会合并多页达人
+- 接口调用时带 Bearer token
+- 成功时显示成功状态
+- 失败时显示失败状态
+
+## 手动验证
+
+1. 登录插件
+2. 选择导出范围
+3. 点击 `提交批次`
+4. 在 `prompt()` 中输入批次名
+5. 确认请求 payload 中包含：
+   - Logto 用户 ID
+   - 多个达人 ID
+   - 批次名
+   - 批次 ID
+6. 确认后端返回成功
+
+## 后续扩展
+
+当真实接口稳定后，可以继续扩展：
+
+- 批次提交结果详情展示
+- 最近提交批次列表
+- 批次重试
+- 批次备注、标签
+- 写权限 scope 单独拆分