docs(t215): freeze admin order authorization contract
This commit is contained in:
@@ -58,7 +58,7 @@ T-205 原子领取/租约状态机、T-206 Android 登录/有限离线、T-207
|
||||
证据回传、T-211 参考图召回和 SKU 硬匹配、T-212 候选身份映射,以及 T-213 受控
|
||||
规格组合/价格核验均已完成。T-208 的原始候选观测、模型评估、确定性推荐、逐候选
|
||||
结构化人工理由和修订历史也已完成。T-214 商品持久身份和重新定位指纹也已完成;
|
||||
下一步实现 T-215 Admin 下单授权,不得直接把候选链接或列表 ordinal 当成授权。
|
||||
当前正在实现 T-215 Admin 下单授权,不得直接把候选链接或列表 ordinal 当成授权。
|
||||
手机从管理后端领取任务并回传结果,VLM、拼多多自动化和人工确认在 App 本地完成。
|
||||
T-206 增加有限离线执行;T-207 已复用 Roubao 端上 OpenAI 兼容适配器并加密本地 Key。
|
||||
管理后端不保存/代理 VLM,后台任务不能覆盖手机 provider 配置。
|
||||
|
||||
+17
-11
@@ -30,9 +30,10 @@
|
||||
| F-003 | 手动领取任务 | 空闲且就绪的 App 点击后只领取一条待处理任务。 | P0 | US-003 |
|
||||
| F-004 | 解析采购需求 | 系统从图片和文字提取搜索词、属性及约束,并保留原始输入。 | P0 | US-004 |
|
||||
| F-005 | 参考图搜索与规格候选判断 | App 用参考图在拼多多召回商品,以 SKU 颜色/尺码硬约束检查最多 5 个结果,回传匹配候选或明确无匹配。 | P0 | US-004 |
|
||||
| F-006 | 人工确认停止点 | 自动化停在候选/订单确认位置,采购员确认结果或拒绝候选。 | P0 | US-005 |
|
||||
| F-006 | Admin 人工选品 | 候选回传后自动化停止,Admin 查看证据并明确选择或拒绝候选。 | P0 | US-005、US-010 |
|
||||
| F-007 | 结果与异常回传 | 管理员和采购员看到成功、失败、取消及可恢复建议。 | P0 | US-002、US-006 |
|
||||
| F-009 | 手机独立执行与 VLM | App 本地完成模型判断和自动化,后端只控制任务并接收结果。 | P0 | US-009 |
|
||||
| F-010 | 授权创建待付款订单 | Admin 选品后签发一次性授权,Roubao 选择已确认 SKU/数量并创建待付款订单;付款始终人工完成。 | P0 | US-010 |
|
||||
|
||||
### F-009 手机独立执行与 VLM
|
||||
|
||||
@@ -100,8 +101,8 @@ T-206/T-207 已跑通领取、执行、候选/证据和最小结果回传;T-20
|
||||
活跃任务都必须说明原因。
|
||||
7. 遇到验证码、登录失效、风控提示、页面未知、预算不满足或模型低置信度时停止,
|
||||
不猜测点击。
|
||||
8. MVP 的“成功”表示完成验证闭环并得到人工确认的候选结果,
|
||||
`order_submitted` 必须为 `false`。
|
||||
8. 候选采集阶段 `order_submitted=false`。只有 Admin 对当前 candidate key 签发的
|
||||
一次性授权可进入订单创建;创建后必须停在待付款状态,禁止自动支付。
|
||||
9. 取消和失败不得自动转成新任务;是否重试由人员显式决定。
|
||||
10. 管理页面和管理 API 只允许有效 ADMIN 会话;App 执行接口只允许有效 BUYER 与
|
||||
预授权设备联合身份,两种凭证不能互换。
|
||||
@@ -127,6 +128,10 @@ T-206/T-207 已跑通领取、执行、候选/证据和最小结果回传;T-20
|
||||
20. 拼多多候选召回必须使用当前任务参考图;标题和 SKU 不能替代图片作为召回输入。
|
||||
SKU 中可唯一识别的颜色、尺码是候选硬约束:任一不匹配或无法确认时不得进入自动
|
||||
Top 5。回传可以少于 5 个,禁止用弱匹配凑数。
|
||||
21. Admin 下单授权必须绑定 task、execution、task content hash、candidate key、
|
||||
review version、原始 SKU 和数量;URL、列表 ordinal 或模型推荐均不能单独授权。
|
||||
22. 一个授权最多创建一个拼多多订单。网络超时或页面不确定时必须先对账,不能重按
|
||||
提交;系统不保存支付凭证,不点击付款。
|
||||
|
||||
## 六、第一层本地样本约定
|
||||
|
||||
@@ -179,15 +184,16 @@ T-004 已固定首版规则:推荐私有目录为被 Git 忽略的 `private-fi
|
||||
搜索输入,进入结果并检查最多 5 个候选;候选只有在原始 SKU 的颜色、尺码硬约束
|
||||
均确认匹配时才能进入回传列表。匹配项按评估结果排序且最多 5 个,不足时不得凑数;
|
||||
无合理候选时明确结束而不是随意选择。
|
||||
- F-006/US-005/IX-007:流程到达人工确认点后停止;MVP 任意路径都不能触发最终
|
||||
提交订单或支付。T-104 的本地确认只允许标记建议候选可用或拒绝本次候选,
|
||||
`order_submitted` 固定为 `false`。
|
||||
- F-006/US-005/US-010/IX-011:候选回传后进入 `WAITING_CONFIRMATION`;Admin 必须
|
||||
按 candidate key 查看证据并为接受项及所有拒绝项选择结构化理由。
|
||||
- F-007/US-006/IX-008:失败包含稳定错误码、失败步骤、可读说明和必要截图;重新
|
||||
打开任务后证据仍可查看。
|
||||
- US-007/IX-001/IX-004:管理员可登录和退出,采购员可用预授权设备取得 1 小时
|
||||
Bearer token;匿名、角色错误、禁用、过期、篡改和跨端凭证替代均被拒绝。
|
||||
- F-009/US-009/IX-010:后台任务不能覆盖手机 VLM 配置;断开管理后端超过 90 秒后,
|
||||
App 仍可在服务端下发的有限授权内执行,授权到期安全停止且任务不被重复分配。
|
||||
- F-010/US-010/IX-011:只有当前 Admin 一次性授权可驱动 Roubao 创建一笔待付款
|
||||
订单;SKU、数量和价格重新核验,订单号/下单时间回传后提醒人员去拼多多付款。
|
||||
|
||||
### 试验验收
|
||||
|
||||
@@ -195,7 +201,7 @@ T-004 已固定首版规则:推荐私有目录为被 Git 忽略的 `private-fi
|
||||
|
||||
- 至少 80% 能自动到达合理候选商品页或给出正确的“无匹配/需人工”结论。
|
||||
- 至少 70% 的首选候选被采购人员判定可接受。
|
||||
- 不发生重复领取、重复执行导致的不可逆操作或订单提交。
|
||||
- 不发生重复领取、未授权订单、重复订单或自动付款。
|
||||
- 每条失败任务都能定位到具体步骤和错误类别。
|
||||
- 记录每条任务的耗时、人工介入点和候选接受结果,用于决定是否进入 V2。
|
||||
- 同时记录实际曝光候选、模型预测、系统推荐和人工结构化理由;准确率以人工结论为
|
||||
@@ -211,7 +217,7 @@ T-004 已固定首版规则:推荐私有目录为被 Git 忽略的 `private-fi
|
||||
| 任务到达 | MVP 由 App 手动领取;后续通知只作唤醒/提示。 |
|
||||
| 搜索方式 | 正式候选召回使用当前任务参考图进入拼多多原生以图搜图;关键词只保留为开发诊断能力,不作为该业务链路的召回输入。 |
|
||||
| 搜索结果 | 最多检查图片搜索返回的前 5 个可见候选,以 SKU 颜色/尺码硬约束过滤后回传 `0..5` 个,避免无界遍历和凑数。 |
|
||||
| 下单边界 | MVP 停在候选或订单确认页,不提交订单、不支付。 |
|
||||
| 下单边界 | Admin 明确选品后只允许创建一笔待付款订单;订单号回传后由人员在拼多多确认并付款,系统不自动支付。 |
|
||||
| 账号边界 | 验证版为 ADMIN 会话 + BUYER/预授权设备联合身份;完整人员 RBAC 后置。 |
|
||||
| 第一层任务输入 | 从本机私有蝦皮订单文件生成测试任务,不先建设 Go-Gin。 |
|
||||
| 执行边界 | 手机本地完成 VLM、拼多多自动化和人工确认;后端负责身份、任务控制和结果审计。 |
|
||||
@@ -231,6 +237,6 @@ T-004 已固定首版规则:推荐私有目录为被 Git 忽略的 `private-fi
|
||||
模型、测试凭证、成本上限、数据留存地区和图片隐私规则仍待确认。候选评估契约和
|
||||
本机 mock 集成已实现,但尚无真实模型质量证据。
|
||||
- 拼多多平台条款、自动化允许范围和账号风控需要业务方确认;项目不实现绕过措施。
|
||||
- 后续若允许提交订单,必须先明确 SKU、收货地址、运费、优惠、发票、金额审批、
|
||||
幂等和人工确认规则,并单独更新需求。
|
||||
- “最终产品是否自动支付”没有定案,当前明确排除。
|
||||
- 创建待付款订单前必须在 T-215 至 T-218 固定 SKU、数量、价格、地址可见性、运费/
|
||||
优惠不确定性、一次性提交和订单列表对账规则;不满足时安全停止。
|
||||
- 自动支付明确排除;人员必须在拼多多订单列表复核后付款。
|
||||
|
||||
@@ -568,6 +568,27 @@ evidence asset ID;后端逐一核对其实际 SHA-256 后才接受候选。Adm
|
||||
key、四个指纹和受控截图;后续选品授权必须引用 key 并绑定任务内容 hash 和 review
|
||||
版本,不能只信 URL 或列表 ordinal。
|
||||
|
||||
### Admin 下单授权(T-215)
|
||||
|
||||
非空候选保存后,任务从 `RUNNING` 进入 `WAITING_CONFIRMATION`。Admin 选择不会调用
|
||||
Android 或拼多多,而是在后端追加一版 human review 和一条
|
||||
`order_authorizations`:
|
||||
|
||||
```text
|
||||
Admin task detail
|
||||
-> candidate key + 全候选结构化理由
|
||||
-> 校验 task/execution/content hash/version
|
||||
-> candidate key 映射原 observation
|
||||
-> 追加 admin human review
|
||||
-> 生成 PENDING_DELIVERY authorization 快照
|
||||
-> T-216 device command pull
|
||||
```
|
||||
|
||||
授权快照固定原始任务 SKU/数量、候选规格/价格、review 版本和 T-214 四个身份指纹;
|
||||
请求不能覆盖这些字段。一次 execution 最多一条 active 授权;设备领取前改选只能
|
||||
追加新版本并把旧记录标记为 `SUPERSEDED`,设备领取后必须走显式停止/撤销协议。
|
||||
浏览器不持有设备 claim token,授权表也不保存拼多多登录、支付或收货凭证。
|
||||
|
||||
人工理由使用版本化 allowlist。接受或拒绝至少有一个理由且指定主要理由;
|
||||
`OTHER` 才要求 4-200 字备注。拒绝推荐后改选必须同时产生一条原推荐项负标签和一条
|
||||
替代项正标签;全部无匹配时每个曝光候选都有负标签。人工修正追加新 review 并引用
|
||||
|
||||
@@ -47,6 +47,7 @@
|
||||
| T-212 | 修复 Top 5 ordinal 与证据映射 | T-211 | 重排、推荐、证据和人工接受引用同一原始候选 |
|
||||
| T-213 | 拼多多候选 SKU 组合与价格核验 | T-212 | 受控选择唯一颜色/尺码并读取组合价;不确认购买,不进入订单或支付 |
|
||||
| T-214 | 建立候选商品持久身份与重新定位指纹 | T-208、T-213 | candidate key 绑定原 observation、卡片/详情/双证据指纹;不伪造平台链接 |
|
||||
| T-215 | Admin 候选确认与一次性下单授权 | T-214 | 非空候选进入等待确认;Admin 按 candidate key 提交逐项理由并生成不可变待投递授权 |
|
||||
|
||||
## Phase 3:端到端验证
|
||||
|
||||
|
||||
@@ -16,6 +16,7 @@
|
||||
| US-007 | 建立受控会话和设备身份 | P0 | 采购管理员、采购执行员 | 未授权人员和设备不能接触任务 | F-001、F-003 | IX-001、IX-004 | 已定 |
|
||||
| US-008 | 积累可信的候选决策样本 | P1 | 采购执行员、优化人员 | 用真实曝光和人工理由评估并改进模型 | F-008 | IX-009 | 已定,T-208 后置 |
|
||||
| US-009 | 手机独立完成采购任务 | P0 | 采购执行员 | 后端短时不可用时仍在有限授权内安全执行 | F-009 | IX-010 | 已定,T-206/T-207 |
|
||||
| US-010 | 审批并创建待付款订单 | P0 | 采购管理员、采购执行员 | Admin 选定候选后只创建一笔可核对的待付款订单 | F-006、F-010 | IX-011 | 已定,T-215 至 T-219 |
|
||||
|
||||
## US-001 创建清晰的采购任务
|
||||
|
||||
@@ -208,6 +209,30 @@
|
||||
两种模式都停在人工确认且 `order_submitted=false`。
|
||||
5. 离线完成的结果恢复联网后幂等补报;离线期间的取消在恢复后的首个同步点处理。
|
||||
|
||||
## US-010 审批并创建待付款订单
|
||||
|
||||
- 关联页面:管理 Web“任务详情/候选确认”、Android“等待授权/订单执行”。
|
||||
- 前置条件:当前 execution 已回传带持久 candidate key 的候选和双证据。
|
||||
|
||||
作为采购管理员,我希望查看候选证据、给选择和拒绝填写理由并签发一次性授权,从而
|
||||
让 Roubao 只按我确认的商品、SKU 和数量创建一笔待付款订单;作为采购执行员,我希望
|
||||
订单号和下单时间自动回传,随后由人员在拼多多复核并付款。
|
||||
|
||||
**范围**
|
||||
|
||||
- 包含:Admin 选品、逐候选理由、不可变授权、设备命令、重新定位、SKU/数量复核、
|
||||
单次提交、订单列表对账和待付款提醒。
|
||||
- 不包含:自动支付、验证码/风控绕过、自动修改地址、无界重试或仅凭 URL 下单。
|
||||
|
||||
**验收场景**
|
||||
|
||||
1. 非空候选回传后任务进入等待 Admin 确认,手机不会自行选定或提交。
|
||||
2. Admin 只能按当前 candidate key 授权,数量来自原任务;改选保留旧 review 和授权。
|
||||
3. Roubao 领取授权后重新用参考图定位候选,并复核详情/规格指纹、SKU、数量和价格。
|
||||
4. 每个授权最多执行一次提交;响应不确定时先去订单列表对账,不能再次点击。
|
||||
5. 找到新订单后回传拼多多订单号和下单时间,Admin 显示“待人工确认付款”。
|
||||
6. 任意流程都不点击付款,不保存支付密码或验证码。
|
||||
|
||||
## 待确认
|
||||
|
||||
- 密码重置流程后置;T-204 使用本地 `authctl` 显式创建种子 ADMIN/BUYER 和预授权
|
||||
|
||||
@@ -17,6 +17,7 @@
|
||||
| IX-008 | US-006 | App/管理端错误状态 | 自动失败、取消、重试上传 | 显示结构化原因和恢复动作 | P0 | 已定 |
|
||||
| IX-009 | US-008 | App 候选理由/管理端决策详情 | 接受、拒绝、改选或修正 | 保存逐候选结构化人工标签 | P1 | T-208 已实现 |
|
||||
| IX-010 | US-009 | App 独立执行设置/同步状态 | 配置模式、离线执行或补报 | 授权内独立执行并可审计同步 | P0 | T-206 离线控制已实现,结果补报待 T-207 |
|
||||
| IX-011 | US-010 | Admin 候选授权/App 订单执行 | 选择候选并授权、设备领取执行 | 创建一笔可对账的待付款订单并提醒人工付款 | P0 | T-215 至 T-219 |
|
||||
|
||||
## IX-001 管理 Web 登录
|
||||
|
||||
@@ -307,6 +308,40 @@
|
||||
- 结果补报失败保留加密本地记录和原幂等 key;不能恢复终态后的自动化。
|
||||
- App 可以显示 provider 名称和模型,但不得回显 Key、Authorization 或完整敏感 URL。
|
||||
|
||||
## IX-011 Admin 候选授权与待付款订单
|
||||
|
||||
- 页面:管理 Web“任务详情/候选确认”、Android“等待授权/订单执行”。
|
||||
- 角色:采购管理员、采购执行员。
|
||||
- 服务依赖:T-215 order authorization、T-216 device command、T-217/T-218
|
||||
订单自动化与对账。
|
||||
|
||||
**正常路径**
|
||||
|
||||
1. 任务进入 `WAITING_CONFIRMATION` 后,Admin 查看原始要求、候选标题/SKU/组合价格、
|
||||
模型理由、candidate key 和详情/规格截图。
|
||||
2. Admin 单选一个候选,为接受项和其余拒绝项选择结构化理由,并确认“只创建待付款
|
||||
订单,不授权付款”。
|
||||
3. 后端生成不可变 `PENDING_DELIVERY` 授权;设备领取后页面显示投递/执行进度。
|
||||
4. Roubao 重新定位商品,复核 SKU/数量/价格后只提交一次,再从订单列表读取订单号
|
||||
和下单时间。
|
||||
5. Admin 显示“待人工确认付款”,提供订单号、时间和审计证据;人员切换拼多多付款。
|
||||
|
||||
**状态与异常**
|
||||
|
||||
- 候选证据不完整、任务版本变化、取消已请求或授权过期时禁用授权。
|
||||
- 授权尚未投递时改选会创建修订版本;旧授权显示 `SUPERSEDED`,不能覆盖。
|
||||
- 投递后不能静默改选;必须先走设备停止/撤销协议。
|
||||
- 商品无法重新定位、SKU/数量/价格不一致、地址/运费/优惠导致金额不确定时停止,
|
||||
不提交订单。
|
||||
- 提交响应超时或页面未知时显示“正在对账”,禁止再次提交;没有唯一新订单时转人工。
|
||||
- 页面和 App 都不能提供自动付款按钮。
|
||||
|
||||
**可访问性**
|
||||
|
||||
- 候选使用带完整 label 的 radio;理由用 select/radio,不依赖颜色或图片顺序。
|
||||
- 授权按钮文案包含动作结果,确认对话框默认焦点在取消。
|
||||
- 状态更新不改变候选卡和按钮尺寸,错误与待付款提醒可被读屏读取。
|
||||
|
||||
## 通用交互约束
|
||||
|
||||
- Web 和 App 的所有提交都防重复,网络超时后以服务端状态为准。
|
||||
|
||||
+20
@@ -259,6 +259,26 @@ T-204 已实现的 `TASK_CREATED`、`TASK_CANCELED` 事件包含可空
|
||||
`cancel_requested=true`,只有 App 在安全检查点调用 `cancel-ack` 后才进入
|
||||
`CANCELED` 并结束 execution。
|
||||
|
||||
### `POST /api/v1/tasks/{task_id}/order-authorizations`
|
||||
|
||||
T-215 起由有效 ADMIN 会话对当前 `WAITING_CONFIRMATION` execution 创建一次性待投递
|
||||
授权。Cookie API 请求必须带 `X-CSRF-Token` 和 `Idempotency-Key`;请求体见
|
||||
[`T-215`](tasks/T-215.md)。关键规则:
|
||||
|
||||
- 顶层和每个 item 只引用 v7 `candidate_key`,不得用 ordinal 或 URL 选品。
|
||||
- `items` 恰好覆盖当前 execution 全部 observation,只有顶层 key 对应项为
|
||||
`ACCEPT`;所有项必须包含 T-208 schema v1 合法理由。
|
||||
- `execution_id`、task content hash 和 expected task version 必须同时匹配;服务端
|
||||
从任务/observation 读取 SKU、数量、候选规格、价格和身份指纹写入授权快照。
|
||||
- 首次成功返回 `201` 和 `PENDING_DELIVERY` 授权;同 key 同 body 重放返回相同
|
||||
授权并带 `replayed=true`,同 key 不同 body 返回 `409`。
|
||||
- 未投递前改选必须引用当前 `supersedes_authorization_id`;旧授权变为
|
||||
`SUPERSEDED`。已投递或不是最新授权时返回 `409`。
|
||||
|
||||
Admin `GET /api/v1/tasks/{task_id}` 同时返回当前及历史
|
||||
`order_authorizations`。授权仅允许 T-216 设备命令领取,不代表浏览器可以直接操作
|
||||
手机,也不授权付款。
|
||||
|
||||
## 设备与领取
|
||||
|
||||
### `POST /api/v1/devices/heartbeat`
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
## 当前快照
|
||||
|
||||
- 日期:2026-07-28
|
||||
- 阶段:T-214 已完成;下一步 T-215 Admin 候选确认与下单授权
|
||||
- 阶段:T-215 Admin 候选确认与一次性下单授权进行中
|
||||
- Git:当前分支为 `main`;T-001 至 T-004、T-101 至 T-104、T-201 至 T-207、T-209、
|
||||
T-208、T-210、T-211、T-212、T-213、T-214 均已纳入 Git 历史
|
||||
- 生产代码:`android-buyer/` 已接入 Roubao Android 源码
|
||||
@@ -123,6 +123,7 @@
|
||||
| `docs/tasks/T-213.md` | DONE | 真机选择目标 SKU、读取组合价并安全返回 |
|
||||
| `docs/tasks/T-208.md` | DONE | 归一化候选决策数据并增加结构化人工 review |
|
||||
| `docs/tasks/T-214.md` | DONE | 建立 execution-scoped candidate key 与设备采集指纹 |
|
||||
| `docs/tasks/T-215.md` | DOING | Admin 按 candidate key 选择并创建不可变待投递授权 |
|
||||
| `docs/design/` | 已确认 | T-202 原型索引、4 个管理页和 7 个 Android 页面 |
|
||||
| `deepseek总结.txt` | 已有 | 历史讨论摘要,不是正式需求权威 |
|
||||
| `android-buyer/` | 已有 | Roubao `main` 固定 commit 的 Android 基线 |
|
||||
@@ -134,8 +135,8 @@
|
||||
## 任务摘要
|
||||
|
||||
- 已完成:T-001 至 T-004、T-101 至 T-104、T-201 至 T-214。
|
||||
- 正在进行:无。
|
||||
- 下一步:依次实现 T-215 Admin 下单授权、设备命令、订单 dry-run、单次提交对账和
|
||||
- 正在进行:T-215 Admin 候选确认与一次性下单授权。
|
||||
- 下一步:依次实现设备命令、订单 dry-run、单次提交对账和
|
||||
付款提醒。
|
||||
|
||||
## 当前可运行内容
|
||||
|
||||
+2
-1
@@ -10,7 +10,7 @@ T-202 的离线 P0 页面入口见[原型索引](design/index.html)。原型仅
|
||||
| `/login` | 管理登录 | 建立服务端管理会话 | US-007 | IX-001 |
|
||||
| `/tasks` | 任务列表 | 查看状态、筛选并进入详情 | US-002 | IX-003 |
|
||||
| `/tasks/new` | 新建任务 | 提交图片和采购约束 | US-001 | IX-002 |
|
||||
| `/tasks/{id}` | 任务详情 | 查看原始输入、时间线、候选和证据 | US-002、US-006 | IX-003、IX-008 |
|
||||
| `/tasks/{id}` | 任务详情 | 查看输入/候选/证据,并按 candidate key 创建待投递下单授权 | US-002、US-006、US-010 | IX-003、IX-008、IX-011 |
|
||||
|
||||
MVP 登录后默认进入 `/tasks`。未登录访问受保护页面时跳转 `/login` 并携带安全的
|
||||
站内返回路径;只接受 `/tasks` 及其本站子路径,拒绝绝对 URL、`//` 和反斜杠。
|
||||
@@ -45,6 +45,7 @@ Android 导航名称是逻辑目的地,具体 Compose/Fragment 形式待接入
|
||||
| `POST /api/v1/tasks/{id}/cancel-ack` | 安全停止后确认 `CANCELED` 并结束 execution |
|
||||
| `POST /api/v1/tasks/{id}/events` | 幂等补报本地执行事件 |
|
||||
| `POST /api/v1/tasks/{id}/candidates` | 保存最多 5 个候选、模型判断和本地推荐 |
|
||||
| `POST /api/v1/tasks/{id}/commands/next` | T-216 起领取 Admin 已创建的设备命令 |
|
||||
| `POST /api/v1/tasks/{id}/complete` | 提交人工结果,强制 `order_submitted=false` |
|
||||
| `POST /api/v1/tasks/{id}/fail` | 提交结构化失败和受控证据 |
|
||||
|
||||
|
||||
@@ -0,0 +1,146 @@
|
||||
---
|
||||
id: T-215
|
||||
title: Admin 候选确认与一次性下单授权
|
||||
phase: 2
|
||||
deps:
|
||||
- T-214
|
||||
status: DOING
|
||||
created: 2026-07-28
|
||||
context_ref: 56e7a2b
|
||||
work_branch: null
|
||||
write_paths:
|
||||
- docs/tasks/T-215.md
|
||||
- docs/00-ai-start-here.md
|
||||
- docs/02-requirements.md
|
||||
- docs/04-architecture.md
|
||||
- docs/06-tasks.md
|
||||
- docs/07-user-stories.md
|
||||
- docs/08-interaction-checklist.md
|
||||
- docs/api.md
|
||||
- docs/current-state.md
|
||||
- docs/routes.md
|
||||
- backend-api/migrations/**
|
||||
- backend-api/internal/domain/**
|
||||
- backend-api/internal/usecase/**
|
||||
- backend-api/internal/repository/sqlite/**
|
||||
- backend-api/internal/transport/httpapi/**
|
||||
- backend-api/internal/transport/webui/**
|
||||
---
|
||||
|
||||
## 问题 / 背景
|
||||
|
||||
T-214 已给每个候选建立 execution-scoped `candidate_key`,但任务仍由手机上的采购员
|
||||
提交 human review 并结束。新需求要求 Admin 采购员查看 Top 5 后选择商品,再把明确
|
||||
授权同步给同一台 Roubao 设备;候选列表或 URL 本身不能成为下单许可。
|
||||
|
||||
本任务实现后台选择、逐候选理由和不可变的一次性授权。它不实现设备拉取或拼多多
|
||||
点击;T-216 才把待投递授权转换为设备命令。
|
||||
|
||||
## 冻结合约
|
||||
|
||||
### 等待确认
|
||||
|
||||
1. 当前 execution 首次成功保存非空候选批次后,任务在同一事务从 `RUNNING` 进入
|
||||
`WAITING_CONFIRMATION`,增加 task version,并追加 `CANDIDATES_READY` 事件。
|
||||
2. 设备 heartbeat 在该状态继续有效,但不能凭候选回传重新开始页面动作。空候选
|
||||
仍允许现有 `NO_MATCH/MANUAL_REQUIRED` 终态,不创建授权。
|
||||
3. Admin 只能为当前活跃 execution、当前 task content hash 和 v7 identity 完整的
|
||||
observation 授权;取消已请求、授权到期、终态或旧 execution 一律拒绝。
|
||||
|
||||
### Admin 决策与授权
|
||||
|
||||
新增管理会话鉴权、CSRF/幂等保护的
|
||||
`POST /api/v1/tasks/{task_id}/order-authorizations`:
|
||||
|
||||
```json
|
||||
{
|
||||
"execution_id": "uuid",
|
||||
"task_content_sha256": "64-char-lowercase-hex",
|
||||
"expected_task_version": 4,
|
||||
"candidate_key": "64-char-lowercase-hex",
|
||||
"reason_schema_version": 1,
|
||||
"primary_reason_code": "SELECTED_BEST_MATCH",
|
||||
"note": "",
|
||||
"supersedes_authorization_id": null,
|
||||
"items": [
|
||||
{
|
||||
"candidate_key": "selected-key",
|
||||
"label": "ACCEPT",
|
||||
"primary_reason_code": "SKU_MATCH",
|
||||
"reason_codes": ["SKU_MATCH", "IMAGE_MATCH"],
|
||||
"note": ""
|
||||
},
|
||||
{
|
||||
"candidate_key": "rejected-key",
|
||||
"label": "REJECT",
|
||||
"primary_reason_code": "NOT_BEST_MATCH",
|
||||
"reason_codes": ["NOT_BEST_MATCH"],
|
||||
"note": ""
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
1. `items` 必须按 candidate key 恰好覆盖当前 execution 的全部 observation,且只有
|
||||
顶层 `candidate_key` 对应项为 `ACCEPT`。理由沿用 T-208 schema v1 allowlist 和
|
||||
`OTHER` 备注规则;无预算任务仍禁止价格类理由。
|
||||
2. 仓储在一个 immediate transaction 内把 candidate key 映射回原 ordinal,追加一版
|
||||
`candidate_human_reviews`(`actor_device_id=NULL`),再创建一条不可变
|
||||
`order_authorizations`。不得信任请求传入的 ordinal、SKU、数量、价格或 URL。
|
||||
3. 授权快照由服务端读取:task/execution/content hash、candidate key、review ID/
|
||||
version、原始 SKU、任务数量、候选规格摘要、组合价格和四个身份指纹。数量只能来自
|
||||
原始任务,Admin 不能在选品表单中改写。
|
||||
4. 授权初始状态为 `PENDING_DELIVERY`,版本从 1 递增;同一 execution 同时最多一条
|
||||
active 授权。相同幂等键和请求返回原结果,不新增 review、授权或事件。
|
||||
5. 设备领取前允许 Admin 改选,但请求必须引用当前 active
|
||||
`supersedes_authorization_id`;旧授权原子变为 `SUPERSEDED`,review/授权历史均不
|
||||
覆盖。非当前引用、已投递或已执行授权拒绝修改。
|
||||
6. 每次创建或改选追加 `ORDER_AUTHORIZATION_CREATED` 任务事件,事件只记录授权 ID、
|
||||
版本和 candidate key 的短前缀,不记录第三方 URL 或页面全文。
|
||||
|
||||
### Admin API/Web
|
||||
|
||||
1. Admin 任务详情返回结构化 observations、当前/历史 review 和 order authorization,
|
||||
每项展示标题、SKU 摘要、组合价格、受控详情/规格截图、candidate key 和模型理由。
|
||||
2. `WAITING_CONFIRMATION` 且存在候选时显示单选候选、选择理由、对其余候选批量拒绝
|
||||
理由、可选备注和“确认商品并授权下单”按钮。表单服务端展开为逐候选 items。
|
||||
3. 页面必须明确“仅授权创建待付款订单,不授权付款”;没有可授权候选、数据版本冲突
|
||||
或已有不可修改授权时禁用提交并给出可操作状态。
|
||||
4. Admin API/Web 不请求第三方商品/图片 URL,也不提供由浏览器直接触发设备动作的
|
||||
通道。
|
||||
|
||||
## 数据模型
|
||||
|
||||
v8 新增:
|
||||
|
||||
- `order_authorizations`:授权 ID、task/execution、版本、candidate key、内容 hash、
|
||||
review、原始 SKU/数量、候选 SKU/价格、四个指纹、状态、创建人、时间和可空
|
||||
supersedes ID。
|
||||
- `admin_order_authorization_requests`:管理员、幂等键、请求 hash、task 和授权引用。
|
||||
|
||||
状态预留 `PENDING_DELIVERY/DELIVERED/ACKNOWLEDGED/EXECUTING/CONSUMED/FAILED/
|
||||
REVOKED/SUPERSEDED`;T-215 只产生 `PENDING_DELIVERY` 和 `SUPERSEDED`。存在授权数据
|
||||
时 v8 destructive down 必须失败。
|
||||
|
||||
## 验收要点
|
||||
|
||||
- [ ] 非空候选批次原子进入 `WAITING_CONFIRMATION`,重复回传不重复增加事件/version。
|
||||
- [ ] Admin 请求只用 candidate key,完整覆盖候选且每项接受/拒绝都有合法理由。
|
||||
- [ ] review、授权、旧授权 supersede、任务事件和幂等记录原子提交。
|
||||
- [ ] 跨任务/execution、旧 hash/version、伪造 key、缺 identity 和并发双授权被拒绝。
|
||||
- [ ] 授权数量/SKU/价格/指纹均由服务端快照,Admin 不能篡改。
|
||||
- [ ] Admin API/Web 可选候选、查看证据和理由,明确只创建待付款订单且不授权付款。
|
||||
- [ ] v8 migration、Go test/race/vet、根验证和管理页面桌面/移动视口通过。
|
||||
|
||||
## 边界
|
||||
|
||||
- 不让设备拉取或确认授权;属于 T-216。
|
||||
- 不重新打开拼多多、选择 SKU/数量或进入订单确认页;属于 T-217。
|
||||
- 不提交订单、读取订单号或付款;属于 T-218/T-219。
|
||||
- 不使用 URL、ordinal、模型推荐或旧手机 review 直接代替 Admin 明确授权。
|
||||
|
||||
## 执行记录
|
||||
|
||||
- 2026-07-28:T-214 实现提交 `56e7a2b` 后领取。决定复用
|
||||
`WAITING_CONFIRMATION`,并把 Admin review 与一次性授权放在同一事务;设备投递和
|
||||
页面动作继续保持为后续独立权限层。
|
||||
Reference in New Issue
Block a user