Table of Contents

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

背景与目标
最终方案
修改文件
验收结果
测试
遗留问题
相关提交
用户验收

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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

类型：需求
所属总体设计：#32
所属 MVP / 版本：采购闭环
状态：已完成
日期：2026-08-20
Gitea 工单：#33
Wiki 页面：Task-33-purchase-task-contract

背景与目标

在 PDD、虾皮和 SYB 三个独立商品域之外建立采购任务事实，固定演练/正式模式、不可变业务快照、任务尝试幂等、设备与可选账号串行、订单结果未知和后续物流回填边界，同时保证系统永远不支付。

最终方案

新增 purchase_task：消费三个商品域外键并固化身份、规格、数量、价格边界、币种、URL、goods_id、规则、设备和可选账号快照。
新增 purchase_task_attempt：使用稳定 attempt_id、任务内序号、阶段和结果幂等键记录每次 Agent 执行，不保存控件树或截图。
新增可选 pdd_account 调度引用，只保存人工名称和状态，不保存凭据；Android 无法识别账号时允许为空。
使用可空 guard 复合唯一索引限制同一 SYB 明细最多一个活动任务、同一设备最多一个执行中任务，以及已知账号最多一个执行中任务；终态历史完整保留。
正式 live 任务必须关联 SYB；无副作用 rehearsal 可不关联。MySQL 8.4 不允许外键列同时参与跨字段 CHECK，因此该条件由模型钩子和后续 #34 创建服务校验。
采购规则仅接受白名单类型化动作。演练拒绝改地址、创建订单和核单；任何模式拒绝支付与未知动作；正式高风险动作要求独立版本化能力。
地址后缀固定为 _cg{task.id}；价格使用参考/最低/最高单价整数分与币种；PDD 商品实际单价越界时明确失败。
Wiki-first 更新共享 API、业务规则、架构、项目档案与交付索引；HTTP 路由、状态机服务、Admin 页面和 Android 执行仍属于后续工单。

修改文件

server/app/goauto/models/purchase.go：采购任务、尝试和可选 PDD 账号引用模型及 guard 派生。
server/app/goauto/purchasecontract/：采购规则类型化动作、模式和能力校验。
server/app/goauto/migrations/：迁移清单与采购约束回归测试。
server/cmd/migrate/migration/version-local/1786701100000_purchase_contract.go：追加型版本迁移。
docs/00、02、03、08、09：Wiki revision f9245c8 的只读镜像。

验收结果

验收标准	结果
追加迁移在既有商品表环境执行并可幂等复跑	通过；MySQL 8.4 版本只登记一次
演练与正式规则能力隔离，所有模式禁止支付	通过
商品域只通过外键与快照被消费	通过
同一 SYB 可保留多个历史任务且最多一个活动任务	通过
商品档案修改不改变已创建任务快照	通过
契约包含能力、幂等、租约、结果未知和回填状态	通过
三个商品表没有采购订单或物流字段	通过；MySQL 查询为 0

测试

go test ./app/goauto/purchasecontract ./app/goauto/migrations：通过。
go test ./...：通过。
powershell -ExecutionPolicy Bypass -File scripts/verify.ps1 -Component server：全量测试与构建通过。
python dev_scripts/harness.py check --strict：通过。
本地 MySQL 8.4：迁移 1786701100000 成功且幂等复跑通过；pdd_account、purchase_task、purchase_task_attempt 均存在，采购任务为 0 条，三个 guard 唯一索引正确。
未验证部分：#33 不实现 HTTP 状态机、Admin 页面、Android 执行、真实地址修改、创建订单、人工支付或物流回填；没有执行任何 PDD 下单或支付动作。

遗留问题

Gitea 迁移后的 Wiki REST API 返回 404；本次按已经验证的 Wiki Git 仓库完成 Wiki-first 更新和归档，核心镜像内容已逐页一致性比较。该环境问题不影响 #33 产品契约。
#34 必须在创建服务事务中回写 _cg{task.id}，并再次强制校验正式任务的 SYB 引用、规则能力和状态转换。

用户验收

2026-08-20：用户明确回复“通过验收 #33”。