Table of Contents

34 服务端采购任务、租约、幂等与状态机

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

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.

34 服务端采购任务、租约、幂等与状态机

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

背景与目标

在 #33 数据与规则契约上实现服务端采购任务状态机，让后续 Admin 和 Android 能通过稳定接口创建、领取、执行和提交采购任务，同时隔离演练与正式能力、阻止设备/已知账号并发、避免重复订单事实，并保证系统不执行支付。

最终方案

新增 server/app/goauto/purchase/，实现从单条 SYB 明细创建正式任务，以及从 PDD 商品创建无副作用演练任务。创建时固化商品、规格、数量、价格、币种、规则、设备、可选账号和 _cg{taskId} 地址后缀。
正式任务校验 SYB → 虾皮 → PDD 关联和已确认规格映射；映射不完整、PDD 档案待采集或无规格时要求 purchase.spec-probe.v1 并进入两趟执行。
创建、下一任务、领取和开始四个边界均校验版本化能力。领取通过数据库 guard 同时占用设备和可选 PDD 账号租约，并检查该设备没有采集任务。
start 创建唯一 attempt；规格探测第一趟提交后释放租约，服务端对同一 attempt 固化一次 AI/人工决策，第二趟使用新 attempt 派发。无匹配结果明确失败。
正式任务必须先提交 order-submit-started 才能提交订单号；order_result_unknown 不自动重试，只能人工解除。
attempt 最终结果保存请求 ID 和内容哈希；相同内容重放返回原事实，不同内容拒绝覆盖。
一次性重新采购授权在新任务创建事务中消耗，旧任务和旧订单保留；人工支付复核、取消、结果未知解除和回填候选选择均有请求审计。后选的已支付订单覆盖同一 SYB 明细的旧回填候选。
演练规则在服务端拒绝改地址、创建订单和核单；任何规则拒绝支付。Admin 页面、Android 页面动作、物流和回填不在本工单。

修改文件

server/app/goauto/purchase/：创建、租约、状态转换、结果幂等、人工处置、HTTP 路由和回归测试。
server/app/goauto/models/purchase.go：状态审计、请求幂等、规格决策和取消字段；演练任务的虾皮关联改为可空。
server/cmd/migrate/migration/version-local/1786701200000_purchase_state_machine.go：既有数据库追加迁移。
server/app/admin/router/init_router.go：注册采购任务路由。
docs/00、02、03、08、09：Wiki revision 5da7f225 的只读镜像。

验收结果

验收标准	结果
演练规则不能获得改地址、创建订单和支付能力	通过；规则契约回归覆盖
创建、next、claim、start 均执行能力校验	通过；不兼容 next 会跳过，其他边界明确拒绝
同一设备或已知 PDD 账号只能有一个领取/执行租约	通过；查询校验加数据库唯一 guard
同一 attempt 相同结果重放不重复写，不同结果不能覆盖	通过
成功任务默认不能重建，一次授权只产生一条新任务并自动消耗	通过
结果未知不自动重派且必须人工解除	通过
状态事务化并保存审计字段，不记录敏感信息	通过

测试

go test ./...：服务端全量通过。
go vet ./app/goauto/purchase ./app/goauto/models ./app/admin/router：通过。
powershell -ExecutionPolicy Bypass -File scripts/verify.ps1 -Component server：全量测试与构建通过。
python dev_scripts/harness.py check --strict：通过。
本地 MySQL 8.4：迁移 1786701200000 成功登记；purchase_task 的状态、规格决策和订单提交幂等字段存在。
未验证部分：未实现或验证 Admin 页面、Android 规则执行、真实修改地址、创建 PDD 订单、人工支付、物流采集和 SYB 回填；没有执行任何真实下单或支付动作。

遗留问题

Gitea Wiki REST API 仍返回 404；本次通过可正常读写的 Wiki Git 仓库完成 Wiki-first 更新，并逐页比对核心 docs/ 镜像。
Admin 列表、详情和批量创建交互由 #35 实现；Android 演练和正式动作分别由 #42、#36 实现。

用户验收

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