cmautobuy/docs/admin/04-client-api.md

04 Admin 侧的 Client 接口实现

• 文档状态：基线草案，待联合评审
• 适用范围：admin/handler/api/

权威契约在 Client 那边：docs/client/04-admin-api-contract.md。 本文只讲Admin 这边怎么实现。两边说法不一致时以 Client 契约为准，要改先走工单。

本文档中 [必须] / [建议] / [待定] 的含义见 文档索引。

1. 一共四个接口

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 独立登记接口

设置页保存当前设备时调用：

PUT /api/v1/client/registration
X-Client-Id: <stable-client-id>

请求体与 claim 的 Client、设备和能力部分相同。相同 X-Client-Id 重复调用执行 upsert，统一返回 200 OK：

{
  "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. 领取任务

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 步的查询和更新要在同一个事务里，用条件更新防并发：

UPDATE tasks SET status = 'claimed', claimed_at = ?, updated_at = ?
WHERE task_id = ? AND status = 'assigned';
-- 检查影响行数，为 0 说明被别人抢先了，重新取下一条

响应体：

{
  "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 需求 §5）， 不要等到这里才发现发不出去。

3. claim 保留隐式登记作为兼容兜底

[必须] 有独立登记接口，但不设心跳接口。

旧 Client 可能直接调用 claim，其请求里已经带齐初始化需要的信息：

X-Client-Id: client-001          ← 序列号，主键

{
  "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 设备登记联调手册。

claim 的兼容登记处理：

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. 提交结果

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. 提交失败

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. 幂等怎么做

[必须] 建一张表记录处理过的键：

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，两者不要混：

{
  "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，不创建重复记录
• 登记接口不读取、领取或修改任务
• 显式登记更新非空名称，空名称更新保留已有名称
• 登记接口校验名称、任务类型、执行模式和结构版本
• PUT /registration 幂等：重复调用不产生重复记录
• 登记不读取、不领取、不修改任何任务，响应不含 task
• 显式登记带非空名称更新名称；空名称保留原名；新建时用 client_id 兜底
• claim 隐式登记不更新名称
• 登记和 claim 共用同一套字段校验，非法内容返回 422 INVALID_CLIENT_PROFILE
• 校验不通过时不写库
• 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 不进日志