wangshaoqing/star-chart-search-enhancer

Fork 0

admin123 58f5de03f2 docs: add market batch submit design

2026-04-22 13:37:32 +08:00

7.1 KiB

Raw Blame History

星图达人批次提交设计

背景

当前插件已经具备以下能力：

使用 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 页
全部
自定义

批次名称输入

用户点击 提交批次 时：

弹出浏览器 prompt()
提示文案建议为：请输入批次名称
用户输入如：618 达人筛选第一批

处理规则：

用户取消：直接终止，不报错
输入为空或仅空格：提示 请输入批次名称
输入有效：继续批次提交流程

提交状态

批次提交过程中：

提交批次 按钮禁用
导出 CSV 按钮与范围选择器一并禁用
状态文案可复用现有导出状态区域

建议状态文案：

当前页：提交中...
前 N 页：提交中 3/5 页...
全部：提交中第 3 页...

成功与失败反馈

成功：

提示 批次提交成功

失败：

未登录：请先登录插件
批次名为空：请输入批次名称
接口失败：批次提交失败，请稍后重试

批次数据模型

首版建议 payload 结构如下：

{
  "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
看后搜率字段
城市/地区等补充信息

数据流

完整流程如下：

用户在工具栏选择导出范围
用户点击 提交批次
插件弹出 prompt() 请求输入批次名称
插件检查登录状态与用户信息
插件复用当前多页采集逻辑，获取当前范围内达人记录
插件读取 Logto 用户 ID
插件生成 createdAt 和 batchId
插件组装整批 payload
插件使用带 Bearer token 的客户端提交到后端
插件显示成功或失败状态

模块边界

建议按以下边界实现：

工具栏层

职责：

渲染 提交批次 按钮
管理按钮禁用态
回传点击事件

市场控制器层

职责：

响应 提交批次 点击
调用 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
成功时显示成功状态
失败时显示失败状态

手动验证

登录插件
选择导出范围
点击 提交批次
在 prompt() 中输入批次名
确认请求 payload 中包含：
- Logto 用户 ID
- 多个达人 ID
- 批次名
- 批次 ID
确认后端返回成功

后续扩展

当真实接口稳定后，可以继续扩展：

批次提交结果详情展示
最近提交批次列表
批次重试
批次备注、标签
写权限 scope 单独拆分

7.1 KiB Raw Blame History Unescape Escape