OPC/goauto
2
0
Fork 0
Code Issues 192 Pull Requests Actions Packages Projects Releases Wiki Activity

T31 采购任务数据模型与共享 API 契约 #33

New Issue
Closed
opened 2026-08-17 10:00:46 +08:00 by ila · 2 comments
ila commented 2026-08-17 10:00:46 +08:00
Owner
Copy Link
Copy Source

基本信息

  • 类型：需求 / 采购任务数据库 / 共享契约
  • 所属总体设计：#32
  • 阶段：已实施，等待用户验收

依赖与并行

  • 前置工单：#31、#40、#41，以及#32原型经用户明确验收
  • 是否允许并行：前置商品域契约稳定后，作为其他采购实施工单的共同前置
  • 原因：采购模块只消费独立商品域，不拥有或迁移PDD、Shopee、SYB商品表

子项目影响

  • 交付单元：server / shared-docs
  • 是否跨子项目：是
  • 是否修改共享接口：是；同步更新docs/08-agent-api-contract.md
  • 验证：MySQL迁移、Go测试、契约示例和状态约束测试

原始需求

采购任务从一条结构化syb_product创建，读取其Shopee商品、PDD商品和规格映射。第一阶段允许使用人工输入创建无副作用的采购演练任务；后续Android可以创建PDD订单但永不支付。任务需要保存规则和业务快照、执行尝试、地址后缀、订单、物流及回填事实。

做什么

  • 仅定义和迁移采购域表，例如purchase_tasks及必要的任务尝试/PDD账号引用；不创建或修改三个独立商品主表的业务字段。
  • 定义不可变execution_mode：rehearsal只允许复核后安全停止，live才允许后续地址修改和创建订单能力；任何模式都禁止支付。
  • purchase_tasks.syb_product_id允许演练阶段为空；正式采购必须引用SYB明细。
  • 创建任务时固化Shopee商品、PDD商品、规格映射、数量、总价上限、URL、goods_id、完整规则和PDD账号快照。
  • 规则快照包含类型、schema版本、required_capabilities和类型化动作；服务端禁止下发任意脚本。
  • 一个SYB明细可产生多个采购任务；采购记录不反写进syb_products业务字段。
  • 当前有效关系保存在采购域：同一个syb_product_id在事务约束下最多只有一个有效采购任务。
  • 保存_cg{task.id}地址后缀、task_attempt_id、执行状态、PDD订单号、下单时间、人工支付确认、物流和回填状态。
  • 定义演练结果、真实采购、重新采购、支付确认、回填候选、物流和自动回填所需API契约与错误码。
  • 明确Agent本地任务/尝试/Outbox与服务端最终事实的职责边界。

不做什么

  • 不定义pdd_products、shopee_products或syb_products的建表和管理接口。
  • 不实现Admin页面、Android自动化或货运宝真实调用。
  • 不保存PDD凭据、完整收货地址、原始控件树或截图；不实现自动支付。

验收标准

  • 采购迁移可在商品域表已存在时执行和安全回退。
  • 演练与真实采购权限在数据和契约层隔离，演练规则无法调用地址或创建订单动作。
  • 采购任务只通过外键和不可变快照消费商品域数据。
  • 一个SYB明细可保留多个任务和订单，且最多一个任务为当前有效。
  • 删除或修改商品档案不会改变已创建采购任务的解释性快照。
  • 共享契约包含能力协商、规则快照、幂等键、设备/账号租约、结果未知和回填状态。
  • 三个商品表没有采购订单或物流字段。

风险和回退

采购迁移依赖三个商品域契约；实施前再次核对#32已验收。不得以方便查询为由把采购状态反向塞入商品表，也不得让演练模式获得真实订单能力。

## 基本信息 - 类型：需求 / 采购任务数据库 / 共享契约 - 所属总体设计：#32 - 阶段：已实施，等待用户验收 ## 依赖与并行 - 前置工单：#31、#40、#41，以及#32原型经用户明确验收 - 是否允许并行：前置商品域契约稳定后，作为其他采购实施工单的共同前置 - 原因：采购模块只消费独立商品域，不拥有或迁移PDD、Shopee、SYB商品表 ## 子项目影响 - 交付单元：server / shared-docs - 是否跨子项目：是 - 是否修改共享接口：是；同步更新`docs/08-agent-api-contract.md` - 验证：MySQL迁移、Go测试、契约示例和状态约束测试 ## 原始需求 采购任务从一条结构化`syb_product`创建，读取其Shopee商品、PDD商品和规格映射。第一阶段允许使用人工输入创建无副作用的采购演练任务；后续Android可以创建PDD订单但永不支付。任务需要保存规则和业务快照、执行尝试、地址后缀、订单、物流及回填事实。 ## 做什么 - 仅定义和迁移采购域表，例如`purchase_tasks`及必要的任务尝试/PDD账号引用；不创建或修改三个独立商品主表的业务字段。 - 定义不可变`execution_mode`：`rehearsal`只允许复核后安全停止，`live`才允许后续地址修改和创建订单能力；任何模式都禁止支付。 - `purchase_tasks.syb_product_id`允许演练阶段为空；正式采购必须引用SYB明细。 - 创建任务时固化Shopee商品、PDD商品、规格映射、数量、总价上限、URL、goods_id、完整规则和PDD账号快照。 - 规则快照包含类型、schema版本、`required_capabilities`和类型化动作；服务端禁止下发任意脚本。 - 一个SYB明细可产生多个采购任务；采购记录不反写进`syb_products`业务字段。 - 当前有效关系保存在采购域：同一个`syb_product_id`在事务约束下最多只有一个有效采购任务。 - 保存`_cg{task.id}`地址后缀、`task_attempt_id`、执行状态、PDD订单号、下单时间、人工支付确认、物流和回填状态。 - 定义演练结果、真实采购、重新采购、支付确认、回填候选、物流和自动回填所需API契约与错误码。 - 明确Agent本地任务/尝试/Outbox与服务端最终事实的职责边界。 ## 不做什么 - 不定义`pdd_products`、`shopee_products`或`syb_products`的建表和管理接口。 - 不实现Admin页面、Android自动化或货运宝真实调用。 - 不保存PDD凭据、完整收货地址、原始控件树或截图；不实现自动支付。 ## 验收标准 - [ ] 采购迁移可在商品域表已存在时执行和安全回退。 - [ ] 演练与真实采购权限在数据和契约层隔离，演练规则无法调用地址或创建订单动作。 - [ ] 采购任务只通过外键和不可变快照消费商品域数据。 - [ ] 一个SYB明细可保留多个任务和订单，且最多一个任务为当前有效。 - [ ] 删除或修改商品档案不会改变已创建采购任务的解释性快照。 - [ ] 共享契约包含能力协商、规则快照、幂等键、设备/账号租约、结果未知和回填状态。 - [ ] 三个商品表没有采购订单或物流字段。 ## 风险和回退 采购迁移依赖三个商品域契约；实施前再次核对#32已验收。不得以方便查询为由把采购状态反向塞入商品表，也不得让演练模式获得真实订单能力。
ila changed title from T31 采购数据模型与共享 API 契约 to T31 采购任务数据模型与共享 API 契约 2026-08-17 10:08:10 +08:00
ila commented 2026-08-20 16:52:46 +08:00
Author
Owner
Copy Link
Copy Source

实施完成，等待用户验收

实现

  • 新增 pdd_account、purchase_task、purchase_task_attempt 三张独立采购域表；商品域未加入采购、订单、支付或物流字段。
  • 固化商品、规格、数量、价格区间、币种、URL、goods_id、规则、设备与可选账号快照。
  • 同一 SYB 最多一个活动任务；设备串行；账号已知时账号串行，账号未知不阻止任务。
  • 新增采购规则契约：演练不能改地址、创建订单或核单；所有模式禁止支付和未知动作。
  • 定义任务/attempt 状态、幂等键、租约、_cg{task.id}、结果未知、人工支付复核、物流和回填共享契约。

真实验证

  • MySQL 8.4 迁移 1786701100000 成功，幂等复跑后版本记录仍为 1 条。
  • 三张采购表存在且当前 purchase_task=0；三个 guard 唯一索引字段正确。
  • 三个商品表中采购/订单/支付/物流字段数量为 0。
  • 首次 MySQL 验证发现外键列与跨字段 CHECK 的 8.4 限制，已按最小方案改为模型钩子 + 后续 #34 服务校验并增加回归测试。

自动验证

  • go test ./...：通过。
  • scripts/verify.ps1 -Component server：全量测试和构建通过。
  • harness.py check --strict：通过。

证据

  • 源码提交：978f42806a9d649236a1476c5a831d2b02dfc16a（已推送 main）。
  • 长期 Wiki 契约 revision：f9245c856a45c10dfbae7fe32b365ca11b008782。
  • 任务归档：Task-33-purchase-task-contract，Wiki revision 20a0fce2d4805390d52a265c275eb183af324a6e。

未验证/不在范围

未实现或执行 HTTP 状态机、Admin 页面、Android 采购、地址修改、创建订单、支付或物流回填；本工单没有产生 PDD 订单和任何支付动作。

## 实施完成，等待用户验收 ### 实现 - 新增 `pdd_account`、`purchase_task`、`purchase_task_attempt` 三张独立采购域表；商品域未加入采购、订单、支付或物流字段。 - 固化商品、规格、数量、价格区间、币种、URL、goods_id、规则、设备与可选账号快照。 - 同一 SYB 最多一个活动任务；设备串行；账号已知时账号串行，账号未知不阻止任务。 - 新增采购规则契约：演练不能改地址、创建订单或核单；所有模式禁止支付和未知动作。 - 定义任务/attempt 状态、幂等键、租约、`_cg{task.id}`、结果未知、人工支付复核、物流和回填共享契约。 ### 真实验证 - MySQL 8.4 迁移 `1786701100000` 成功，幂等复跑后版本记录仍为 1 条。 - 三张采购表存在且当前 `purchase_task=0`；三个 guard 唯一索引字段正确。 - 三个商品表中采购/订单/支付/物流字段数量为 0。 - 首次 MySQL 验证发现外键列与跨字段 CHECK 的 8.4 限制，已按最小方案改为模型钩子 + 后续 #34 服务校验并增加回归测试。 ### 自动验证 - `go test ./...`：通过。 - `scripts/verify.ps1 -Component server`：全量测试和构建通过。 - `harness.py check --strict`：通过。 ### 证据 - 源码提交：`978f42806a9d649236a1476c5a831d2b02dfc16a`（已推送 main）。 - 长期 Wiki 契约 revision：`f9245c856a45c10dfbae7fe32b365ca11b008782`。 - 任务归档：`Task-33-purchase-task-contract`，Wiki revision `20a0fce2d4805390d52a265c275eb183af324a6e`。 ### 未验证/不在范围 未实现或执行 HTTP 状态机、Admin 页面、Android 采购、地址修改、创建订单、支付或物流回填；本工单没有产生 PDD 订单和任何支付动作。
ila commented 2026-08-20 16:58:36 +08:00
Author
Owner
Copy Link
Copy Source

用户于 2026-08-20 明确验收通过。任务归档已更新为“已完成”；Wiki revision：7dfa7b7b7ef38133eb4ff32b8888b347a503ee90。工单关闭。

用户于 2026-08-20 明确验收通过。任务归档已更新为“已完成”；Wiki revision：`7dfa7b7b7ef38133eb4ff32b8888b347a503ee90`。工单关闭。
ila closed this issue 2026-08-20 16:58:38 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin ila
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: OPC/goauto#33