chengma/cmautobuy
2
0
Fork 0
Code Issues 89 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0f24165ee2cef099767a9ea2308a28a1f732fb6e
cmautobuy/docs/admin/04-client-api.md
T

13 KiB
Raw Blame History

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  提交失败/需人工

task_id 是不透明的稳定字符串，当前采集任务为 cjN、采购任务为 cgN。Client 必须原样保存和回传，不校验旧前缀，不从编号推导类型； 业务类型始终以响应中的 type 为准。

[必须] 不得新增"让 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'
    • 无主的：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 步的查询和更新要在同一个事务里，用条件更新防并发：

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 说明被别人抢先了，重新取下一条

响应体：

{
  "task": {
    "id": "cg1",
    "type": "purchase",
    "execution_mode": "dry_run",
    "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 不关心这些。

execution_mode 只允许 dry_run / live；Admin Web 新建采购任务固定为 live，历史任务和接口缺省兼容值仍为 dry_run。领取查询必须按 Client 上报的 capabilities.purchase_mode 过滤：dry_run Client 只能看到演练任务， live Client 可以看到两种；过滤只决定能否领取，绝不改变任务自身模式。 Admin Web 可以把 live 任务预先指派给当前账号可见的任意 Client，不在创建时按该字段 拒绝；尚未就绪的指定 Client 不会领取，待其设备与真实采购执行器就绪并自动上报 live 后领取。

[必须] 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. 采集任务：校验返回的 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 数据模型 §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. 提交失败

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，界面上要看得见。

成功响应：

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

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

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 一次只返回一个任务
  • 能领到无主任务（assigned_client IS NULL + pending），领取时写入领取者
  • 指定给本机的任务优先于无主任务
  • 不会返回指定给别的客户端的任务
  • claim 原子完成，并发下不会把同一任务发给两个客户端
  • claim 无任务时返回 204，不是 200 加空对象
  • 响应不含租约、不含 Admin 侧状态
  • payload.goods_url 必有值
  • 采购任务的 quantity、max_price_cent 必有值，且是人民币分整数
  • 可以预先指派 live 任务给可见 Client，但领取时不向只声明 dry_run 的客户端返回 live 任务
  • result / failure 幂等：同键同内容返回同结果
  • 同键不同内容返回 409
  • 任务已取消，仍接受结果
  • 任务已重派，仍接受结果
  • 同一任务接受多个客户端的多份结果
  • 只有从未分配过的任务才返回 403
  • claim / result / failure 都刷新 last_seen_at
  • token 不进日志
Reference in New Issue View Git Blame Copy Permalink