chengmaandClaude Opus 5
62d46bf10a
面向 Client 开发者的实操文档，目标是让一台新设备出现在 Admin 的 客户端列表里。文中所有请求和响应都是在真实运行的 Admin 上跑出来的。 新增 docs/admin/07-设备登记联调手册.md - 先讲清"没有注册接口，登记是 claim 的副作用" - **重点提示 204 不是错误**：新设备第一次 claim 必然 204， 它同时意味着登记成功。这是最容易被 Client 误判成失败的地方 - 设备号必须持久化、永不变——变了 Admin 会当成新机器， 列表里会堆一串僵尸记录 - 设备名只在首次登记时采纳，之后 Admin 侧改名不会被覆盖。 这个行为会让人困惑（"我改了 Client 怎么 Admin 没变"），先说清楚 - 四步验证流程 + 可直接复制的 curl + 手工插测试任务的 SQL - 7 条常见问题，含"列表里多出好几台一样的机器"这类实际会碰到的 - 列出 Client 侧待办清单，标明前两条做完就能登记成功 定案 client.name（原 [待定]） Client 设置页本来就有「设备名」输入框（deviceNameInput，50 字上限）， 只是没接进 ClientInfo。Admin 仍容忍它缺失，缺了用 X-Client-Id 兜底， 所以 Client 先不发也不影响登记。 同步更新 - docs/client/04-admin-api-contract.md §5：请求示例补 client 字段， 加"204 不是错误"的必须项，并指向本手册 - docs/README.md：两处导航加入口，Client 侧"对接 Admin"那行也指过来 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
249 lines
8.9 KiB
Markdown
249 lines
8.9 KiB
Markdown
# 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 的一处小扩展。
|
||
> Client 的设置页本来就有「设备名」输入框（`deviceNameInput`，50 字上限），
|
||
> 把它带上即可。**Admin 仍然容忍它缺失**——没有就用 `X-Client-Id` 当显示名，
|
||
> 所以 Client 先不发也不影响登记。
|
||
>
|
||
> 登记流程的完整说明见 [07 设备登记联调手册](07-设备登记联调手册.md)。
|
||
|
||
处理：
|
||
|
||
```text
|
||
upsert clients：
|
||
没有该 client_id → 新增，name 用上报的（没有就用 client_id 兜底）
|
||
已有 → 更新 device / capabilities / last_seen_at
|
||
**name 不更新**
|
||
```
|
||
|
||
`[必须]` `name` **只在第一次注册时写入，之后的 claim 一律不更新它**。
|
||
|
||
这样操作员在界面上改成好记的名字（"仓库那台"）之后，
|
||
客户端每次 claim 都不会把它覆盖回上报的默认名。
|
||
实现上就是 `ON CONFLICT ... DO UPDATE SET` 里**不包含 `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 不进日志
|