docs: 建立 Admin 子项目的文档基线
仓库从单子项目变成两个：client（Python + PyQt5 桌面端）和 admin（Go + Gin + HTML 模板 Web 管理端）。两者技术栈完全不同， 规则各自独立，只通过三个 HTTP 接口交互。 新增 admin/AGENTS.md 和 docs/admin/ 共 9 份文档，结构与 docs/client/ 对齐。 关键设计决策（均已与用户确认） - 四模块：蝦皮数据 / 顺运宝数据 / 采购任务 / 客户端列表， 统一三段式布局（工具条 / 带勾选的表格 / 状态条） - 蝦皮数据拆成商品表 + SKU 表：报表本身就是两层结构， 且 PDD 链接是商品级的，放 SKU 级会重复维护 - pdd_data 存商品级，一个 PDD 商品采一次，所有订单共用 - SKU 映射独立成表且可复用，同一蝦皮 SKU 只需人工匹配一次 - PDD 链接人工填写，采集按钮就放在填链接的编辑弹窗里 - 任务分配给指定客户端；不加心跳，注册在领取时完成， 在线状态由 last_seen_at 派生 - SQLite 驱动固定 modernc.org/sqlite（纯 Go 免 cgo，go build 直接出 exe） - 不引入前端框架和 npm 构建，只允许原生 JS 或 htmx 基于样本文件 raw_data/蝦皮数据样本.xlsx 实测得出的约束 - 11287 行 = 5195 商品汇总行 + 6092 SKU 行，导入必须分开处理 - 商品規格ID 零重复，是天然主键 - 规格原文两种格式各占 53.4% / 46.6%，只解析【】会漏掉一半 - 平均每商品仅 1.17 个 SKU，报表不是全量目录， 因此必须支持手动新增，且货运单外键不能加硬约束 同步更新 - 根 AGENTS.md 开头的指针改为两个子项目对照表 - docs/README.md 重构为双子项目索引 - .gitignore 加 admin/data/、admin.exe、Excel 锁文件 说明：Gitea 尚未配置，本次无对应工单号。 raw_data/ 未提交，含台币销售额等商业数据，待用户决定。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
chengma
@@ -0,0 +1,237 @@
|
||||
# 04 Admin 侧的 Client 接口实现
|
||||
|
||||
- 文档状态：基线草案，待联合评审
|
||||
- 适用范围：`admin/handler/api/`
|
||||
|
||||
> **权威契约在 Client 那边：**[docs/client/04-admin-api-contract.md](../client/04-admin-api-contract.md)。
|
||||
> 本文只讲**Admin 这边怎么实现**。两边说法不一致时**以 Client 契约为准**，要改先走工单。
|
||||
|
||||
本文档中 `[必须]` / `[建议]` / `[待定]` 的含义见 [文档索引](../README.md#文档标注说明)。
|
||||
|
||||
## 1. 一共只有三个接口
|
||||
|
||||
```http
|
||||
POST /api/v1/client/tasks/claim 领一个任务
|
||||
POST /api/v1/client/tasks/{task_id}/result 提交成功结果
|
||||
POST /api/v1/client/tasks/{task_id}/failure 提交失败/需人工
|
||||
```
|
||||
|
||||
`[必须]` **不得新增"让 Client 查询状态"类接口**，也不得加回租约和心跳。
|
||||
理由见 Client 契约 §1.1：本项目人工付款，重复下单只产生重复的**未付款**订单，
|
||||
不值得为它引入一整套中断逻辑。
|
||||
|
||||
## 2. 领取任务
|
||||
|
||||
```http
|
||||
POST /api/v1/client/tasks/claim
|
||||
X-Client-Id: client-001
|
||||
```
|
||||
|
||||
请求体里有设备信息和能力声明，还有客户端名称（见 §3）。
|
||||
|
||||
**处理步骤：**
|
||||
|
||||
1. 先做客户端注册/更新（§3）；
|
||||
2. 查 `tasks`：`assigned_client = X-Client-Id` 且 `status = 'assigned'`，
|
||||
按 `priority DESC, created_at` 取**一条**；
|
||||
3. 没有就返回 `204 No Content`；
|
||||
4. 有就把 `status` 改成 `claimed`、记 `claimed_at`，返回任务。
|
||||
|
||||
`[必须]` 第 2 步只返回**分配给这个客户端**的任务。这是已定案的分配模型
|
||||
（Client 契约 §5.1），不要做成谁都能抢。
|
||||
|
||||
`[必须]` 第 4 步的查询和更新要在**同一个事务**里，用条件更新防并发：
|
||||
|
||||
```sql
|
||||
UPDATE tasks SET status = 'claimed', claimed_at = ?, updated_at = ?
|
||||
WHERE task_id = ? AND status = 'assigned';
|
||||
-- 检查影响行数，为 0 说明被别人抢先了，重新取下一条
|
||||
```
|
||||
|
||||
**响应体：**
|
||||
|
||||
```json
|
||||
{
|
||||
"task": {
|
||||
"id": "PDD-20260806-0001",
|
||||
"type": "purchase",
|
||||
"version": 1,
|
||||
"priority": 10,
|
||||
"payload": {
|
||||
"goods_id": "737116531267",
|
||||
"goods_url": "https://mobile.yangkeduo.com/goods.html?goods_id=737116531267",
|
||||
"options": { "color": "黑色", "size": "M码" },
|
||||
"quantity": 2,
|
||||
"max_price_cent": 4200
|
||||
},
|
||||
"created_at": "2026-08-06T07:00:00Z",
|
||||
"updated_at": "2026-08-06T07:05:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`[必须]` **响应里不含租约**，也不含 Admin 侧状态。Client 不关心这些。
|
||||
|
||||
`[必须]` `payload.goods_url` 必须有值；采购任务的 `quantity` 和 `max_price_cent` 必须有值。
|
||||
这些在建任务时就该校验住（见 [01 需求](01-requirements.md) §5），
|
||||
不要等到这里才发现发不出去。
|
||||
|
||||
## 3. 客户端注册就在领取里做
|
||||
|
||||
`[必须]` **不设单独的注册接口，也不设心跳接口。**
|
||||
|
||||
`claim` 请求里已经带齐了初始化需要的东西：
|
||||
|
||||
```http
|
||||
X-Client-Id: client-001 ← 序列号，主键
|
||||
```
|
||||
```json
|
||||
{
|
||||
"client": { "name": "办公室-01" },
|
||||
"supported_types": ["collect", "purchase"],
|
||||
"device": { "address": "192.168.0.173:5555",
|
||||
"platform": "android",
|
||||
"pdd_package": "com.xunmeng.pinduoduo" },
|
||||
"capabilities": { "purchase_mode": "dry_run", "schema_versions": [1] }
|
||||
}
|
||||
```
|
||||
|
||||
> `[待定]` `client.name` 是对 Client 契约 §5 的一处小扩展，需在联合评审时确认。
|
||||
> 未确认前 Admin 要容忍它缺失：没有就用 `X-Client-Id` 当显示名。
|
||||
|
||||
处理：
|
||||
|
||||
```text
|
||||
upsert clients：
|
||||
没有该 client_id → 新增，name 用上报的（没有就用 client_id）
|
||||
已有 → 更新 device/capabilities/last_seen_at
|
||||
name 若已被人工改过，不要覆盖
|
||||
```
|
||||
|
||||
`[必须]` `result` 和 `failure` 接口**也要刷新 `last_seen_at`**。
|
||||
否则客户端执行长任务期间不调 claim，会被误判成离线。
|
||||
|
||||
**新客户端第一次来必然拿不到任务**（还没人给它分配），返回 `204` 是正常的。
|
||||
它这时已经登记进列表了，操作员就能给它分配任务。
|
||||
|
||||
## 4. 提交结果
|
||||
|
||||
```http
|
||||
POST /api/v1/client/tasks/{task_id}/result
|
||||
Idempotency-Key: <task_id>:<attempt_id>:result-v1
|
||||
```
|
||||
|
||||
处理：
|
||||
|
||||
1. 用 `Idempotency-Key` 查是否处理过 → 处理过就返回上次的结果，**不重复落库**；
|
||||
2. 把 `pdd_data` 写进 `tasks.result_data`；
|
||||
3. 采集任务：同时写进 `shopee_products.pdd_data`，`collect_status` 置 `collected`；
|
||||
4. `tasks.status` 置 `succeeded`；
|
||||
5. 刷新客户端 `last_seen_at`；
|
||||
6. 返回 `{"accepted": true, "result_id": "...", "accepted_at": "..."}`。
|
||||
|
||||
第 2~4 步 `[必须]` 在**同一个事务**里。
|
||||
|
||||
### 4.1 无条件接受 —— 最容易写错的一条
|
||||
|
||||
`[必须]` 下面每一条都不允许违反：
|
||||
|
||||
- **不得**因为任务已取消而拒绝结果；
|
||||
- **不得**因为任务已重派给别的客户端而拒绝结果；
|
||||
- **必须**能接受同一任务来自**多个客户端**的多份结果；
|
||||
- 只有**从未分配给该客户端**的任务才返回 `403`。
|
||||
|
||||
原因：Client 中途不查任务状态（契约 §1），所以它**必然**会提交一些
|
||||
"Admin 这边已经不要了"的结果。而它可能真的已经下单了，这些数据必须能交上来留痕。
|
||||
|
||||
`accepted: true` 的意思是"**我收到并存下了**"，不代表这个任务还算数。
|
||||
任务算不算数由人工审核决定。
|
||||
|
||||
`[建议]` 已取消任务收到的结果，落库时标记出来，在界面上让操作员能看到"这单已取消但客户端还是买了"。
|
||||
|
||||
## 5. 提交失败
|
||||
|
||||
```http
|
||||
POST /api/v1/client/tasks/{task_id}/failure
|
||||
Idempotency-Key: <task_id>:<attempt_id>:failure-v1
|
||||
```
|
||||
|
||||
`status` 只会是 `retry_wait`、`manual_review`、`failed`、`cancelled` 之一，按下表落地：
|
||||
|
||||
| Client 报告 | Admin 置为 | 说明 |
|
||||
|---|---|---|
|
||||
| `retry_wait` | `assigned` | 放回去，等它再来领 |
|
||||
| `manual_review` | `manual_review` | 等人处理 |
|
||||
| `failed` | `failed` | |
|
||||
| `cancelled` | `cancelled` | |
|
||||
|
||||
采集任务失败时，同步把 `shopee_products.collect_status` 置 `failed`，
|
||||
并把错误信息写进 `collect_error`，界面上要看得见。
|
||||
|
||||
`[必须]` §4.1 的无条件接受**同样适用于本接口**。
|
||||
|
||||
## 6. 幂等怎么做
|
||||
|
||||
`[必须]` 建一张表记录处理过的键：
|
||||
|
||||
```sql
|
||||
CREATE TABLE idempotency_keys (
|
||||
key TEXT PRIMARY KEY,
|
||||
request_hash TEXT NOT NULL, -- 请求体的哈希
|
||||
response_body TEXT NOT NULL, -- 上次返回了什么
|
||||
created_at TEXT NOT NULL
|
||||
);
|
||||
```
|
||||
|
||||
- 键相同、哈希相同 → 直接返回 `response_body`，不再处理；
|
||||
- 键相同、哈希不同 → 返回 `409 IDEMPOTENCY_CONFLICT`；
|
||||
- 键不存在 → 正常处理，然后连同响应一起写入，**和业务写入在同一事务**。
|
||||
|
||||
不这么做的话，Client 网络超时重发就会产生两条结果。
|
||||
|
||||
## 7. 错误格式
|
||||
|
||||
页面出错渲染错误页，**接口出错返回 JSON**，两者不要混：
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "IDEMPOTENCY_CONFLICT",
|
||||
"message": "相同幂等键提交了不同内容",
|
||||
"retryable": false,
|
||||
"request_id": "7a5d...",
|
||||
"details": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
状态码用法见 Client 契约 §3。注意 `403` 的含义：**只有从未分配给该客户端的任务**才返回它。
|
||||
|
||||
## 8. 认证
|
||||
|
||||
`[待定]` 认证方式尚未定案（Client 契约 §10 待确认 #1）。
|
||||
|
||||
临时默认：接口读 `Authorization: Bearer <token>` 请求头但**不校验**，
|
||||
MVP 阶段只在内网/本机运行。
|
||||
|
||||
`[必须]` 无论最终怎么做，**token 不得写进日志**。
|
||||
|
||||
## 9. Admin 侧实现清单
|
||||
|
||||
Client 契约里散落的 Admin 侧硬要求，汇总在这里，**可以直接当验收标准用**：
|
||||
|
||||
- [ ] `claim` 一次只返回一个任务，且只返回分配给该客户端的
|
||||
- [ ] `claim` 原子完成，并发下不会把同一任务发给两个客户端
|
||||
- [ ] `claim` 无任务时返回 `204`，不是 `200` 加空对象
|
||||
- [ ] 响应不含租约、不含 Admin 侧状态
|
||||
- [ ] `payload.goods_url` 必有值
|
||||
- [ ] 采购任务的 `quantity`、`max_price_cent` 必有值，且是人民币分整数
|
||||
- [ ] 不向只声明 `dry_run` 的客户端分配需要真实下单的任务
|
||||
- [ ] `result` / `failure` 幂等：同键同内容返回同结果
|
||||
- [ ] 同键不同内容返回 `409`
|
||||
- [ ] **任务已取消，仍接受结果**
|
||||
- [ ] **任务已重派，仍接受结果**
|
||||
- [ ] **同一任务接受多个客户端的多份结果**
|
||||
- [ ] 只有从未分配过的任务才返回 `403`
|
||||
- [ ] `claim` / `result` / `failure` 都刷新 `last_seen_at`
|
||||
- [ ] token 不进日志
|
||||
Reference in New Issue
Block a user