feat: 定义运行时规格解析契约与审计模型 (#254)
This commit is contained in:
chengma
@@ -8,20 +8,25 @@
|
||||
|
||||
本文档中 `[必须]` / `[建议]` / `[待定]` 的含义见 [文档索引](../README.md#文档标注说明)。
|
||||
|
||||
## 1. 一共四个接口
|
||||
## 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 提交失败/需人工
|
||||
POST /api/v1/client/tasks/{task_id}/spec-resolution 一次性解析当前规格候选
|
||||
```
|
||||
|
||||
#254 冻结第五个接口的契约和审计模型；Handler、路由和匹配服务由 #255 实现。在 #255
|
||||
完成前，旧 Client 仍只使用原四个接口，新 Client 不得把路由尚未提供误判为可重试的 AI 失败。
|
||||
|
||||
`task_id` 是不透明的稳定字符串，当前采集任务为 `cjN`、采购任务为
|
||||
`cgN`。Client 必须原样保存和回传，不校验旧前缀，不从编号推导类型；
|
||||
业务类型始终以响应中的 `type` 为准。
|
||||
|
||||
`[必须]` **不得新增"让 Client 查询状态"类接口**，也不得加回租约和心跳。
|
||||
第五个接口只接收 Client 当下观察到的规格候选并同步返回一份持久化决策，不读取或返回
|
||||
任务调度状态。`[必须]` **不得新增“让 Client 查询状态”类接口**，也不得加回租约和心跳。
|
||||
理由见 Client 契约 §1.1：本项目人工付款，重复下单只产生重复的**未付款**订单，
|
||||
不值得为它引入一整套中断逻辑。
|
||||
|
||||
@@ -167,7 +172,7 @@ upsert clients：
|
||||
实现上就是 `ON CONFLICT ... DO UPDATE SET` 里**不包含 `name`**，
|
||||
不需要额外加"是否人工改过"的标记列。
|
||||
|
||||
`[必须]` `result` 和 `failure` 接口**也要刷新 `last_seen_at`**。
|
||||
`[必须]` `result`、`failure` 和 `spec-resolution` 接口**也要刷新 `last_seen_at`**。
|
||||
否则客户端执行长任务期间不调 claim，会被误判成离线。
|
||||
|
||||
新客户端直接调用 claim 时，`204` 是正常的无任务结果，Client 必须正常处理；如果已经预先分配任务，也可能首次调用就返回 `200`。
|
||||
@@ -247,6 +252,52 @@ Client `SubmissionReceipt` 的统一确认字段，不能只返回 `task_status`
|
||||
|
||||
`[必须]` §4.1 的无条件接受**同样适用于本接口**。
|
||||
|
||||
### 5.1 采购运行时规格解析
|
||||
|
||||
权威 HTTP schema、长度限制、哈希算法和错误代码见 Client 契约 §7.1。Admin 侧路由为：
|
||||
|
||||
```http
|
||||
POST /api/v1/client/tasks/{task_id}/spec-resolution
|
||||
Idempotency-Key: spec-resolution-v1:<identity-sha256>
|
||||
```
|
||||
|
||||
本命令只在 Client 已进入采购规格面板、选中颜色后仍无法精确匹配任务尺码时使用。请求
|
||||
schema v1 只包含：`task_version`、`attempt_id`、`pdd_goods_id`、领取任务时的
|
||||
`original_options`、`selected_color`、`target_size`、当前颜色下 1～100 条可购买候选、
|
||||
候选快照哈希和观测时间。整个请求体最多 64 KiB。候选编号必须按页面顺序严格使用
|
||||
`c1`～`c100`，每条只保存页面原文及原始 `color/size`；禁止原始控件树和截图。
|
||||
|
||||
处理顺序：
|
||||
|
||||
1. 限制请求体大小并校验 schema、字段长度、候选数量、连续短编号、原文和 options；
|
||||
2. 按 Client 契约 §7.1 的长度前缀算法重新计算候选快照哈希和确定性幂等键；
|
||||
3. 核对任务存在、类型为采购、版本和 PDD 商品一致，并确认 `X-Client-Id` 在
|
||||
`task_claims` 中领取过该任务；任务当前是否取消、重派或结束不作为状态查询条件；
|
||||
4. 计算完整规范请求的 `request_hash`。先按
|
||||
`(task_id, attempt_id, candidate_snapshot_hash)` 复查 `purchase_spec_resolutions`：
|
||||
相同 `request_hash` 复用旧记录，不同 `request_hash` 返回 `409 IDEMPOTENCY_CONFLICT`；
|
||||
5. 用短事务保存 pending 候选观察，事务外执行后续工单提供的规则/AI 服务，只允许选择
|
||||
请求中已有候选；再用一个短事务完成解析记录并把可安全重放的响应写入
|
||||
`idempotency_keys`。Admin 崩溃留下的 pending 记录由相同请求恢复，不另建记录；
|
||||
6. 返回 `200`，不更新 `tasks.status`、`tasks.result_data` 或
|
||||
`pdd_products.skus_json`，刷新 Client `last_seen_at`。
|
||||
|
||||
业务响应固定为 `matched/uncertain/rejected/failed`。只有 `matched` 返回非空 `match`，
|
||||
且 `candidate_id`、`raw_text`、`options` 必须是请求候选的逐字副本；`source` 只允许
|
||||
`rule/ai/reused/null`，`confidence_bps` 为 `0～10000` 或 NULL。NULL 表示来源没有可比较
|
||||
置信度，不能当作 0。`failed` 是已落库、可幂等重放的业务结论，仍返回 HTTP 200；只有
|
||||
记录尚未落库时的基础设施故障才返回可有限重试的 `503 SPEC_RESOLUTION_UNAVAILABLE`。
|
||||
|
||||
稳定校验错误与 Client 契约保持一致：`INVALID_BODY`、
|
||||
`INVALID_SPEC_RESOLUTION_SCHEMA`、`INVALID_SPEC_RESOLUTION_REQUEST`、
|
||||
`SPEC_RESOLUTION_HASH_MISMATCH`、`TASK_NOT_FOUND`、`TASK_NOT_PURCHASE`、
|
||||
`TASK_VERSION_CONFLICT`、`PDD_GOODS_MISMATCH`、`TASK_NOT_CLAIMED_BY_CLIENT`、
|
||||
`IDEMPOTENCY_CONFLICT`。所有错误使用本文 §7 的统一 JSON 结构。
|
||||
|
||||
解析表只保存候选观察、最终决策、非敏感服务商/模型指纹和审计时间。不保存模型 API
|
||||
Key、完整提示词/响应、原始 XML、订单号、收货信息、Cookie 或 Token。旧 Client 不调用
|
||||
本命令，原四个接口的路径和语义不变。本命令不提供 GET、进度查询、心跳或轮询能力。
|
||||
|
||||
## 6. 幂等怎么做
|
||||
|
||||
`[必须]` 建一张表记录处理过的键：
|
||||
@@ -264,7 +315,9 @@ CREATE TABLE idempotency_keys (
|
||||
- 键相同、哈希不同 → 返回 `409 IDEMPOTENCY_CONFLICT`；
|
||||
- 键不存在 → 正常处理，然后连同响应一起写入，**和业务写入在同一事务**。
|
||||
|
||||
不这么做的话，Client 网络超时重发就会产生两条结果。
|
||||
不这么做的话，Client 网络超时重发就会产生两条结果。规格解析还要同时依靠
|
||||
`purchase_spec_resolutions` 的业务唯一键防止换一个 HTTP 键重复决策；观察、决策和
|
||||
`idempotency_keys` 必须在同一事务收敛。
|
||||
|
||||
## 7. 错误格式
|
||||
|
||||
@@ -318,10 +371,17 @@ Client 契约里散落的 Admin 侧硬要求，汇总在这里，**可以直接
|
||||
- [ ] 采购任务的 `quantity`、`max_price_cent` 必有值，后者是人民币订单总价上限的分整数
|
||||
- [ ] 可以预先指派 live 任务给可见 Client，但领取时不向只声明 `dry_run` 的客户端返回 live 任务
|
||||
- [ ] `result` / `failure` 幂等：同键同内容返回同结果
|
||||
- [ ] `spec-resolution` 校验 64 KiB、schema、字段长度、1～100 候选和连续短编号
|
||||
- [ ] 重新计算候选快照哈希和确定性幂等键，不信任 Client 自报哈希
|
||||
- [ ] 相同任务、尝试、候选快照只保存一条解析记录；同内容返回首次响应，不同内容返回 `409`
|
||||
- [ ] 只有 matched 返回请求内候选的逐字副本；不接受模型生成规格
|
||||
- [ ] uncertain / rejected / failed 安全停止且可幂等重放，置信度保留 NULL 语义
|
||||
- [ ] 规格解析不修改任务状态和 PDD 主数据，不提供 GET、轮询、租约或心跳
|
||||
- [ ] 规格解析审计不含原始 XML、订单、收货信息和任何凭据
|
||||
- [ ] 同键不同内容返回 `409`
|
||||
- [ ] **任务已取消，仍接受结果**
|
||||
- [ ] **任务已重派，仍接受结果**
|
||||
- [ ] **同一任务接受多个客户端的多份结果**
|
||||
- [ ] 只有从未分配过的任务才返回 `403`
|
||||
- [ ] `claim` / `result` / `failure` 都刷新 `last_seen_at`
|
||||
- [ ] `claim` / `result` / `failure` / `spec-resolution` 都刷新 `last_seen_at`
|
||||
- [ ] token 不进日志
|
||||
|
||||
Reference in New Issue
Block a user