317 lines
12 KiB
Markdown
317 lines
12 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
|
||
PUT /api/v1/client/registration 登记或更新 Client
|
||
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：本项目人工付款，重复下单只产生重复的**未付款**订单，
|
||
不值得为它引入一整套中断逻辑。
|
||
|
||
### 1.1 独立登记接口
|
||
|
||
设置页保存当前设备时调用：
|
||
|
||
```http
|
||
PUT /api/v1/client/registration
|
||
X-Client-Id: <stable-client-id>
|
||
```
|
||
|
||
请求体与 claim 的 Client、设备和能力部分相同。相同 `X-Client-Id` 重复调用执行 upsert，统一返回 `200 OK`：
|
||
|
||
```json
|
||
{
|
||
"registered": true,
|
||
"client_id": "CLIENT-123456",
|
||
"registered_at": "2026-08-06T09:00:00Z"
|
||
}
|
||
```
|
||
|
||
`[必须]` 本接口只登记 Client，不查询、领取或修改任务，也不返回任务。
|
||
|
||
`[必须]` 显式登记携带非空名称时允许更新名称；空名称更新保留现有名称，新建时使用 Client ID 兜底。设备、能力、`last_seen_at` 和 `updated_at` 正常更新。
|
||
|
||
`[必须]` 校验 `client.name` 最多 50 字、任务类型、执行模式和结构版本。错误使用统一 JSON 结构，至少覆盖 `MISSING_CLIENT_ID`、`INVALID_BODY`、`INVALID_CLIENT_PROFILE` 和 `CLIENT_REGISTER_FAILED`。
|
||
|
||
## 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'`
|
||
- 无主的：`assigned_client IS NULL` 且 `status = 'pending'`
|
||
|
||
排序 `ORDER BY (assigned_client IS NULL), priority DESC, created_at`
|
||
—— **指定给本机的优先**；
|
||
|
||
网页创建的采购任务固定走第一种：创建前已经校验当前账号对客户端的可见范围，
|
||
并写入 `pdd_options`、`quantity` 和人民币 `max_price_cent`。这不改变 Client 接口字段。
|
||
3. 没有就返回 `204 No Content`；
|
||
4. 有就把 `status` 改成 `claimed`、记 `claimed_at`，返回任务。
|
||
|
||
`[必须]` 第 2 步只返回**分配给这个客户端**的任务。这是已定案的分配模型
|
||
（Client 契约 §5.1），不要做成谁都能抢。
|
||
|
||
`[必须]` 第 4 步的查询和更新要在**同一个事务**里，用条件更新防并发：
|
||
|
||
```sql
|
||
UPDATE tasks
|
||
SET status = 'claimed', assigned_client = ?, claimed_at = ?, updated_at = ?
|
||
WHERE task_id = ?
|
||
AND ( (status = 'assigned' AND assigned_client = ?)
|
||
OR (status = 'pending' AND assigned_client IS NULL) );
|
||
-- 两种情况合成一条：对"指定给我的"，写 assigned_client 是写同一个值，无副作用。
|
||
-- 检查影响行数，为 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 保留隐式登记作为兼容兜底
|
||
|
||
`[必须]` **有独立登记接口，但不设心跳接口。**
|
||
|
||
旧 Client 可能直接调用 `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` 同时用于显式登记和 claim 兼容登记。
|
||
> Client 的设置页本来就有「设备名」输入框（`deviceNameInput`，50 字上限），
|
||
> 显式登记会更新非空名称；claim 对已有 Client 不覆盖名称。
|
||
> Admin 容忍名称缺失，新建时用 `X-Client-Id` 当显示名。
|
||
>
|
||
> 登记流程的完整说明见 [07 设备登记联调手册](07-设备登记联调手册.md)。
|
||
|
||
claim 的兼容登记处理：
|
||
|
||
```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，会被误判成离线。
|
||
|
||
新客户端直接调用 claim 时，`204` 是正常的无任务结果，Client 必须正常处理；如果已经预先分配任务，也可能首次调用就返回 `200`。
|
||
|
||
## 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. 采集任务：校验返回的 `goods_id` 与请求一致（不一致返回 `422 COLLECT_GOODS_MISMATCH`），
|
||
将 `shop_name` 写进 `pdd_products.shop_name`，完整 `pdd_data` 写进
|
||
`pdd_products.skus_json`，`collect_status` 置 `collected`；
|
||
没有 `shop_name` 或值为空时保留已有店铺名；
|
||
`price_granularity` 非空时只能是 `color` 或 `sku`；
|
||
**`skus` 为空要置 `failed` 而不是 `collected`**，见 [03 数据模型](03-data-model.md) §4.3；
|
||
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` | |
|
||
|
||
采集任务失败时，同步把 `pdd_products.collect_status` 置 `failed`，
|
||
错误信息写进 `collect_msg`、诊断产物位置写进 `artifact_ref`，界面上要看得见。
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"accepted": true,
|
||
"result_id": "result-uuid",
|
||
"task_status": "assigned",
|
||
"accepted_at": "2026-08-06T08:03:01Z"
|
||
}
|
||
```
|
||
|
||
`[必须]` `result_id` 非空，并与同一幂等键保存的响应一起返回。失败提交也使用
|
||
Client `SubmissionReceipt` 的统一确认字段，不能只返回 `task_status`。
|
||
|
||
`[必须]` §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 侧硬要求，汇总在这里，**可以直接当验收标准用**：
|
||
|
||
- [ ] `PUT /registration` 相同 Client ID 幂等 upsert，不创建重复记录
|
||
- [ ] 登记接口不读取、领取或修改任务
|
||
- [ ] 显式登记更新非空名称，空名称更新保留已有名称
|
||
- [ ] 登记接口校验名称、任务类型、执行模式和结构版本
|
||
- [x] `PUT /registration` 幂等：重复调用不产生重复记录
|
||
- [x] 登记**不读取、不领取、不修改任何任务**，响应不含 `task`
|
||
- [x] 显式登记带非空名称更新名称；空名称保留原名；新建时用 client_id 兜底
|
||
- [x] claim 隐式登记**不更新名称**
|
||
- [x] 登记和 claim **共用同一套字段校验**，非法内容返回 `422 INVALID_CLIENT_PROFILE`
|
||
- [x] 校验不通过时不写库
|
||
- [ ] `claim` 一次只返回一个任务
|
||
- [ ] 能领到无主任务（`assigned_client IS NULL` + `pending`），领取时写入领取者
|
||
- [ ] 指定给本机的任务优先于无主任务
|
||
- [ ] 不会返回指定给别的客户端的任务
|
||
- [ ] `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 不进日志
|