feat: 定义运行时规格解析契约与审计模型 (#254)
This commit is contained in:
chengma
@@ -127,6 +127,8 @@ v18（#208）新增 `shops` 业务店铺和 `shop_channel_aliases` 渠道名称
|
||||
名称精确回填，无法确认的记录保持未关联。
|
||||
v19（#212）将产品概念收敛为唯一店铺名称和唯一启停状态。迁移按“任一旧开关停用
|
||||
则保持停用”的安全规则合并 v18 状态，重建由 `shops` 派生的兼容数据和两侧关联。
|
||||
v26（#254）新增 `purchase_spec_resolutions`，用一张表保存采购执行中的候选观察、
|
||||
幂等身份和最终规格决策；不修改历史 SQLite migration，也不覆盖 PDD 商品主数据。
|
||||
|
||||
**v3 为什么丢弃旧 `sku_mappings` 数据（见 #20）：** 新主键需要 `pdd_option_key`，
|
||||
这是 Go 的 `service.OptionKey()` 用 `json.Marshal` 算出来的规范化键，SQL 语句
|
||||
@@ -884,8 +886,8 @@ syb_orders ─(shopee_goods_id, spec_key)─┘
|
||||
（skus_json 里是所有规格和价格）
|
||||
|
||||
syb_orders ──创建──→ tasks ──分配──→ clients
|
||||
↑
|
||||
users（采购员）──1:N 当前归属──────────┘
|
||||
└──1:N──→ purchase_spec_resolutions
|
||||
users（采购员）──1:N 当前归属──────────→ clients
|
||||
```
|
||||
|
||||
两条关联都可以变，这是有意的：
|
||||
@@ -906,6 +908,7 @@ Admin 使用集中 MySQL 8.4，Client 仍使用各自的本地 SQLite；两者
|
||||
| 任务编号 | `tasks.task_id` | `pdd_tasks.remote_task_id` |
|
||||
| 任务状态 | 7 个（§6） | 8 个，是本机执行状态 |
|
||||
| 采集结果 | `pdd_products.skus_json` | `pdd_tasks.pdd_data` |
|
||||
| 运行时规格解析 | `purchase_spec_resolutions` 候选观察与最终决策 | #257 在本地保存请求、幂等键和响应；原任务 payload 不覆盖 |
|
||||
|
||||
`[必须]` **两边的状态是两套，不要试图同步。**
|
||||
Admin 只知道"发出去了 / 收到结果了"，中间过程看不到，这是有意的设计。
|
||||
@@ -1052,3 +1055,93 @@ CREATE UNIQUE INDEX idx_client_assignment_current
|
||||
不新增批次表：提交时所选 `ready` 记录必须在同一事务内全部转为 `queued`；后台每次最多
|
||||
读取 20 条并逐条领取为 `applying`。页面按 `apply_batch_id` 聚合当前批次进度。Admin
|
||||
重启时，`queued` 恢复为 `ready` 且不会自动写远端，`applying` 转为 `needs_check`。
|
||||
|
||||
## 18. `purchase_spec_resolutions` 采购运行时规格解析（MySQL v26）
|
||||
|
||||
Client 在同一次采购中选中颜色后，如果任务尺码和 PDD 页面尺码无法精确对应，就通过
|
||||
[Client 接口契约](../client/04-admin-api-contract.md) §7.1 提交当前可购买候选。本表用
|
||||
**一条记录**同时保存候选观察、幂等身份和最终决策，不拆观察表、决策表或模型响应表。
|
||||
|
||||
```sql
|
||||
CREATE TABLE purchase_spec_resolutions (
|
||||
resolution_id VARCHAR(191) COLLATE utf8mb4_bin PRIMARY KEY,
|
||||
task_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL,
|
||||
attempt_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL,
|
||||
client_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL,
|
||||
task_version BIGINT NOT NULL CHECK (task_version > 0),
|
||||
pdd_goods_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL,
|
||||
original_options_json JSON NOT NULL,
|
||||
selected_color VARCHAR(191) NOT NULL,
|
||||
target_size VARCHAR(191) NOT NULL,
|
||||
candidates_json JSON NOT NULL,
|
||||
candidate_snapshot_hash CHAR(64) COLLATE utf8mb4_bin NOT NULL,
|
||||
request_hash CHAR(64) COLLATE utf8mb4_bin NOT NULL,
|
||||
observed_at VARCHAR(35) NOT NULL,
|
||||
|
||||
outcome VARCHAR(16) NOT NULL DEFAULT 'pending',
|
||||
decision_source VARCHAR(16),
|
||||
chosen_candidate_id VARCHAR(16) COLLATE utf8mb4_bin,
|
||||
resolved_options_json JSON,
|
||||
confidence_bps INT,
|
||||
reason VARCHAR(500),
|
||||
provider_id VARCHAR(191) COLLATE utf8mb4_bin,
|
||||
source_model VARCHAR(191),
|
||||
config_fingerprint CHAR(64) COLLATE utf8mb4_bin,
|
||||
rules_version VARCHAR(32),
|
||||
prompt_version VARCHAR(32),
|
||||
created_at VARCHAR(35) NOT NULL,
|
||||
decided_at VARCHAR(35),
|
||||
|
||||
UNIQUE KEY uq_purchase_spec_resolution_identity
|
||||
(task_id, attempt_id, candidate_snapshot_hash),
|
||||
KEY idx_purchase_spec_resolution_task
|
||||
(task_id, created_at DESC, resolution_id),
|
||||
KEY idx_purchase_spec_resolution_outcome
|
||||
(outcome, created_at, resolution_id),
|
||||
CONSTRAINT chk_purchase_spec_resolution_options CHECK (
|
||||
JSON_TYPE(original_options_json) = 'OBJECT'
|
||||
AND JSON_LENGTH(original_options_json) BETWEEN 1 AND 16
|
||||
AND JSON_TYPE(candidates_json) = 'ARRAY'
|
||||
AND JSON_LENGTH(candidates_json) BETWEEN 1 AND 100
|
||||
AND (resolved_options_json IS NULL
|
||||
OR JSON_TYPE(resolved_options_json) = 'OBJECT')),
|
||||
CONSTRAINT chk_purchase_spec_resolution_outcome CHECK (
|
||||
outcome IN ('pending', 'matched', 'uncertain', 'rejected', 'failed')),
|
||||
CONSTRAINT chk_purchase_spec_resolution_source CHECK (
|
||||
decision_source IS NULL OR decision_source IN ('rule', 'ai', 'reused')),
|
||||
CONSTRAINT chk_purchase_spec_resolution_confidence CHECK (
|
||||
confidence_bps IS NULL OR confidence_bps BETWEEN 0 AND 10000),
|
||||
CONSTRAINT chk_purchase_spec_resolution_decision CHECK (
|
||||
(outcome = 'pending' AND decided_at IS NULL
|
||||
AND decision_source IS NULL AND chosen_candidate_id IS NULL
|
||||
AND resolved_options_json IS NULL)
|
||||
OR (outcome = 'matched' AND decided_at IS NOT NULL
|
||||
AND decision_source IS NOT NULL AND chosen_candidate_id IS NOT NULL
|
||||
AND resolved_options_json IS NOT NULL AND reason IS NOT NULL)
|
||||
OR (outcome IN ('uncertain', 'rejected', 'failed')
|
||||
AND decided_at IS NOT NULL AND chosen_candidate_id IS NULL
|
||||
AND resolved_options_json IS NULL AND reason IS NOT NULL))
|
||||
);
|
||||
```
|
||||
|
||||
- `(task_id, attempt_id, candidate_snapshot_hash)` 是业务唯一身份；`request_hash` 用于发现
|
||||
同一身份改了目标尺码、候选原文或其他内容。HTTP 的 `idempotency_keys` 仍保存可安全
|
||||
重放的完整响应，两层幂等不能互相替代。
|
||||
- `pending` 是内部恢复状态，不返回给 Client。先用短事务写候选观察，规则或 AI 调用在
|
||||
事务外执行；最终 outcome 与 `idempotency_keys.response_body` 在另一个短事务一起提交。
|
||||
崩溃留下 pending 时，相同请求读取原记录继续恢复，不能新建第二条。
|
||||
- `matched` 必须有来源、候选短编号、原始 options、原因和决定时间；候选必须逐字来自
|
||||
`candidates_json`。`uncertain/rejected/failed` 不得填写候选和 resolved options，避免
|
||||
Client 把不确定结果当作可点击规格。
|
||||
- `confidence_bps` 可空。NULL 表示规则或复用路径没有可比较分数，不得转换成 0；AI
|
||||
分数使用 0～10000 基点。服务商、模型、配置指纹和规则/提示版本都是非敏感快照，
|
||||
表中没有 API Key、完整提示词或完整模型响应。
|
||||
- 本表故意不设指向 `tasks` 或 `clients` 的外键。现有页面允许硬删除任务和临时 Client
|
||||
清单记录，规格决策审计不能因此阻塞原流程或被级联删除；Repository 查询始终使用稳定
|
||||
ID，不把缺少主表记录解释成新的业务状态。
|
||||
- 本表不参与任务状态机，不更新 `tasks.status/result_data`，也不写
|
||||
`pdd_products.skus_json` 或长期 `spec_mappings`。它只回答这一执行尝试在这一候选快照下
|
||||
可以安全选择哪个原始候选。
|
||||
- `original_options_json`、`candidates_json` 和 `resolved_options_json` 只保存接口定义的
|
||||
颜色/尺码字符串。不得保存原始无障碍 XML、截图、订单号、收货信息、Cookie、Token、
|
||||
密码或 API Key；时间统一保存为 UTC ISO 8601。
|
||||
|
||||
@@ -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