docs/08-agent-api-contract.md
用采购人员能理解和操作的方式确定以下闭环,并先通过交互原型验证:
syb_products
shopee_products
pdd_products
purchase_tasks
syb_products N ──> 1 shopee_products N ──> 1 pdd_products │ └──────────> N purchase_tasks
货运单号 + 来源商品ID
syb_product
order_submit_started
order_result_unknown
task_id + task_attempt_id
PDD App中维护固定收货地址。每次创建订单前,Agent修改当前使用的详细地址:
后缀格式:_cg{采购任务自增ID} 示例:广东省广州市天园街道骏景花园骏晖轩1202_cg11
处理规则:
(?:-|_)cg\d+$
-
_
1-1202
_cg{task.id}
syb_products.effective_purchase_task_id
使用 QuantUX MCP 创建可点击原型,至少覆盖:
原型审核通过并拆分实施工单后,预计更新:
docs/00-project-profile.md
docs/02-architecture-and-code-map.md
docs/03-business-rules-and-glossary.md
_cg{采购任务ID}
拆分原则:#32继续作为总体QuantUX原型与用户审核门禁。以上工单当前均为待实施;用户未明确验收#32原型前,不修改数据库、服务端、Web、Android或共享API。Admin和Android分别实施,物流服务端与Android采集也分别实施,最后由独立真机验收工单收口。
用户确认PDD、Shopee和SYB商品档案必须独立于采购任务。工单现调整为:
依赖关系:
ext #31 PDD商品 ──────────┐ #40 Shopee商品 ──────┼─> #33 采购任务模型/API ─> #34~#39采购实现 #41 SYB商品 ───────────┘
#32仍只负责把完整业务流程做成QuantUX原型供用户审核;它不再代表这些数据模块必须在同一实施工单中开发。原型未明确验收前,所有相关代码工单继续保持待实施。
新增 #42 $(@{id=181; url=#42; html_url=#42; number=42; user=; original_author=; original_author_id=0; title=T40 Android 采购演练规则与持久执行基线; body=## 基本信息
类型:需求 / Android采购演练 / 持久执行基线
所属总体设计:#32
阶段:待实施(受 #32 QuantUX 原型审核门禁阻塞)
cmautobuy已经验证了商品、规格、数量、价格复核和本地Outbox等采购安全规则,但其PDD页面判断大量写死在Windows Client中,每次兼容新控件树都要更新Client。GoAuto第一步应保留手机直连云端架构,把可变化的页面证据和操作顺序放入服务端规则,并在不创建订单的演练流程中验证。
cmautobuy
task_id
attempt_id
rehearsal_completed
仅修改服务端规则即可处理:文字/ID/层级证据变化、同义文字、等待时间、有限滑动次数、已知弹窗分支和最近可点击父节点策略。
必须升级Agent的情况:新增通用动作类型、新的复杂遍历算法、系统级OEM浮层能力、无障碍API边界或新的本地可靠性机制。服务端下发任意脚本不在范围内。
AGENT_CAPABILITY_MISMATCH
本工单不得包含任何真实下单动作。采购演练能力与采集能力按任务类型隔离;出现问题可停用采购演练规则并回退APK,不影响现有采集闭环。; ref=; assets=System.Object[]; labels=System.Object[]; milestone=; projects=; assignee=; assignees=; state=open; is_locked=False; comments=0; created_at=08/17/2026 10:24:50; updated_at=08/17/2026 10:24:50; closed_at=; due_date=; time_estimate=0; pull_request=; repository=; pin_order=0; content_version=0}.title):第一阶段只做规则驱动的采购演练、Room执行记录和Outbox,止于规格/数量/总价复核,禁止修改地址和创建订单。
#36 已收缩并更名为 $(@{id=174; url=#36; html_url=#36; number=36; user=; original_author=; original_author_id=0; title=T34 Android 地址后缀、不可逆门禁与创建订单; body=## 基本信息
类型:需求 / Android / 高风险真实订单动作
live
rehearsal
shipping_address_update_failed
irreversible_action_at
本工单会修改真实PDD地址并创建真实待付款订单,属于高风险。真机阶段再次等待人工确认;可停用live采购能力并回退APK,演练和现有采集能力保持可用。; ref=; assets=System.Object[]; labels=System.Object[]; milestone=; projects=; assignee=; assignees=; state=open; is_locked=False; comments=0; created_at=08/17/2026 10:00:49; updated_at=08/17/2026 10:24:54; closed_at=; due_date=; time_estimate=0; pull_request=; repository=; pin_order=0; content_version=1}.title):依赖#42,只负责第二阶段的地址修改、不可逆标记、唯一一次创建订单和只读核单。
#42的核心验收是:修改服务端按钮同义文字、等待时间或滑动次数后,不升级Android APK即可让新任务执行新规则;旧任务继续执行旧规则快照。#32原型未通过前,以上工单均保持待实施。
GoAuto - 采购闭环交互原型
6a827440191a826306a7eddd
favicon.ico
工单保持打开。只有用户明确回复“#32 原型通过”后,才允许进入子工单的数据库、接口、Web 和 Android 实施。
已同步修改 App 6a827440191a826306a7eddd 的“选择现有 PDD 商品”页面:
972800403573
719834019024
731370706977
商品ID、标题和店铺现与 #31 PDD 商品原型完全一致。#32结构仍为10页、677个控件、25条有效跳转,无越界、孤立控件或无效跳转。
原型链接:http://124.222.27.183:8082/#/apps/6a827440191a826306a7eddd.html
工单继续等待用户审核,不进入代码实施。
已使用 QuantUX MCP 将线上 App 6a827440191a826306a7eddd 导出为本地单文件离线 HTML:
prototypes/quantux-procurement-flow-6a827440191a826306a7eddd.html
34b5e0c7ccce2021ba92ee03ce252ff0bcc47fc4
本次只保存线上草稿的可追溯离线快照,不改变原型审核状态,也不授权采购生产代码实施。
本轮用户确认 #32 原型需要按“采购、人工支付、订单同步、SYB回填彼此独立”重新设计。原型仍为草稿;用户审核通过前禁止进入生产代码。
pending
running
_cg{taskId}
pending/running/completed/failed
taskId + orderNo
order_use_status
active/closed
closed
20%~150%
0.2~1.5
单价=商品总价/数量
18d96c7
quantux_verify_export
PASS
script/link
main
origin/main
工单继续保持打开和“原型待审核”。用户明确回复“#32 原型通过”之前,不实施采购数据库、服务端、Web 或 Android 生产代码。
用户确认旧原型中“进入 SYB 商品详情后创建采购任务”的流程过于复杂。本轮调整如下,替代 #32 中冲突的旧交互:
SYB商品列表
SYB商品详情
已按本工单最新确认修改 QuantUX App 6a827440191a826306a7eddd:
验证:
f5c1096
工单继续保持原型待审核;用户明确通过前不实施采购生产代码。
本轮继续更新 QuantUX 原型:
原型继续保持待审核;本轮只修改线上 QuantUX 和本地离线 HTML,不实施生产代码。
7df4546
覆盖 SYB 当前页多选、已知不可采购行禁用、批量创建独立采购任务,以及“规格未映射 → 去匹配 → Shopee/PDD规格映射 → 保存/返回SYB列表”。批量确认和结果均按行展示。工单仍为原型待审核,不授权生产实现。
用户 2026-08-18 明确回复「验收通过 #32」,Stage A QuantUX 原型确认通过,可作为采购实施依据。
原型证据
任务归档
文档同步(Wiki-first,镜像已导出并检查一致)
Product-Requirements-Overview
Delivery-Issues
prototypes/README.md
相关提交
a3ef9cb
23464ec
未验证部分
后续门禁
子工单 #33 已完成采购任务数据模型与共享 API 契约实现,源码提交 978f428,MySQL 8.4 迁移和服务端全量验证通过,当前等待用户验收。后续 #34 仍不得在 #33 验收前开始。
978f428
子工单 #33 已于 2026-08-20 验收关闭;#34 服务端采购任务状态机开始实施。当前仍不执行 Android 下单或支付。
子工单 #34 已完成服务端采购任务状态机并进入待验收:创建/快照、设备与可选账号租约、两趟规格探测、attempt 结果幂等、结果未知人工解除、一次性重新采购授权和人工处置接口均已落地。源码 65ae41f;未执行真实下单或支付。
65ae41f
#34 已于 2026-08-20 通过用户验收并关闭。采购数据契约和服务端状态机已完成;按既定依赖顺序,下一实施单元为 #42 Android 无副作用采购演练,然后是 #35 Admin 人工处理页面,最后才进入 #36 高风险正式创建订单。
采购子工单 #53 已验收关闭,补齐了 #42 所需的参数化动作契约;#42 已恢复实施。
基于本原型实施的 #35 Admin 采购任务与人工处理页面,以及其接口支撑 #55、#56,已于 2026-08-21 通过用户验收并关闭。后续采购任务创建入口仍由 #44 独立实施。
子工单 #36 已于 2026-08-22 由用户明确验收并关闭。正式采购已验证到 order_created,订单号和下单时间已保存,未执行支付。#32 保持已关闭状态。
order_created
No dependencies set.
The note is not visible to the blocked user.
基本信息
依赖与并行
子项目影响
docs/08-agent-api-contract.md原始需求
要解决什么
用采购人员能理解和操作的方式确定以下闭环,并先通过交互原型验证:
syb_products、shopee_products、pdd_products和purchase_tasks之间的关系。已确认的数据关系
货运单号 + 来源商品ID作为唯一键。syb_products代表一个明确的 Shopee 商品、颜色、尺码和数量采购明细。shopee_products维护;Agent不得猜测缺失映射。syb_product允许因失败或人工重新采购产生多个purchase_tasks。已确认的采购与订单规则
order_submit_started;进入该状态后不得自动再次点击创建订单。order_result_unknown并交由人工处理。task_id + task_attempt_id保证幂等。收货地址后缀规则
PDD App中维护固定收货地址。每次创建订单前,Agent修改当前使用的详细地址:
处理规则:
(?:-|_)cg\d+$的旧系统后缀。-或_直接分割并取下标0,避免破坏1-1202等真实门牌号。_cg{task.id}。重新采购与有效订单
syb_product默认不能再次创建采购任务。order_submit_started或order_result_unknown必须先人工核查。syb_products.effective_purchase_task_id指向它。快递单号采集与回填
purchase_tasks,不作为syb_products的唯一事实字段。Stage A:先行 QuantUX 原型(本次唯一实施范围)
使用 QuantUX MCP 创建可点击原型,至少覆盖:
原型审核门禁
本工单不做
文档影响
原型审核通过并拆分实施工单后,预计更新:
docs/00-project-profile.mddocs/02-architecture-and-code-map.mddocs/03-business-rules-and-glossary.mddocs/08-agent-api-contract.mdStage A验收标准
_cg{采购任务ID},并展示修改失败禁止创建订单。验证方式
风险和回退
-,只能清理系统末尾标识,不能通用分割。ila referenced this issue2026-08-17 10:00:47 +08:00
ila referenced this issue2026-08-17 10:00:47 +08:00
实施子工单索引(2026-08-17拆分)
拆分原则:#32继续作为总体QuantUX原型与用户审核门禁。以上工单当前均为待实施;用户未明确验收#32原型前,不修改数据库、服务端、Web、Android或共享API。Admin和Android分别实施,物流服务端与Android采集也分别实施,最后由独立真机验收工单收口。
ila referenced this issue2026-08-17 10:08:08 +08:00
ila referenced this issue2026-08-17 10:08:10 +08:00
商品域与采购域解耦调整(2026-08-17)
用户确认PDD、Shopee和SYB商品档案必须独立于采购任务。工单现调整为:
依赖关系:
ext #31 PDD商品 ──────────┐ #40 Shopee商品 ──────┼─> #33 采购任务模型/API ─> #34~#39采购实现 #41 SYB商品 ───────────┘#32仍只负责把完整业务流程做成QuantUX原型供用户审核;它不再代表这些数据模块必须在同一实施工单中开发。原型未明确验收前,所有相关代码工单继续保持待实施。
最小吸收cmautobuy优点的工单调整(2026-08-17)
新增 #42 $(@{id=181; url=#42; html_url=#42; number=42; user=; original_author=; original_author_id=0; title=T40 Android 采购演练规则与持久执行基线; body=## 基本信息
类型:需求 / Android采购演练 / 持久执行基线
所属总体设计:#32
阶段:待实施(受 #32 QuantUX 原型审核门禁阻塞)
依赖与并行
子项目影响
原始需求
cmautobuy已经验证了商品、规格、数量、价格复核和本地Outbox等采购安全规则,但其PDD页面判断大量写死在Windows Client中,每次兼容新控件树都要更新Client。GoAuto第一步应保留手机直连云端架构,把可变化的页面证据和操作顺序放入服务端规则,并在不创建订单的演练流程中验证。做什么
task_id、attempt_id、规则快照哈希、当前步骤、状态、结果、上报状态和时间。rehearsal_completed,不得进入地址修改和订单创建。cmautobuy提取已验证的页面证据、唯一候选、精确规格、数量和价格保护测试场景;不复制Windows Client、ADB或Python线程架构。规则与Agent边界
仅修改服务端规则即可处理:文字/ID/层级证据变化、同义文字、等待时间、有限滑动次数、已知弹窗分支和最近可点击父节点策略。
必须升级Agent的情况:新增通用动作类型、新的复杂遍历算法、系统级OEM浮层能力、无障碍API边界或新的本地可靠性机制。服务端下发任意脚本不在范围内。
不做什么
验收标准
AGENT_CAPABILITY_MISMATCH。风险和回退
本工单不得包含任何真实下单动作。采购演练能力与采集能力按任务类型隔离;出现问题可停用采购演练规则并回退APK,不影响现有采集闭环。; ref=; assets=System.Object[]; labels=System.Object[]; milestone=; projects=; assignee=; assignees=; state=open; is_locked=False; comments=0; created_at=08/17/2026 10:24:50; updated_at=08/17/2026 10:24:50; closed_at=; due_date=; time_estimate=0; pull_request=; repository=; pin_order=0; content_version=0}.title):第一阶段只做规则驱动的采购演练、Room执行记录和Outbox,止于规格/数量/总价复核,禁止修改地址和创建订单。
#36 已收缩并更名为 $(@{id=174; url=#36; html_url=#36; number=36; user=; original_author=; original_author_id=0; title=T34 Android 地址后缀、不可逆门禁与创建订单; body=## 基本信息
类型:需求 / Android / 高风险真实订单动作
所属总体设计:#32
阶段:待实施(受 #32 QuantUX 原型审核门禁阻塞)
依赖与并行
子项目影响
做什么
live采购规则可以进入PDD确认订单和地址步骤;rehearsal在服务端和Agent双重拒绝。(?:-|_)cg\d+$旧后缀,追加_cg{task.id};禁止破坏真实地址主体。shipping_address_update_failed并禁止创建订单。order_submit_started/irreversible_action_at及最终确认快照。order_result_unknown并交由人工处理。不做什么
验收标准
风险和回退
本工单会修改真实PDD地址并创建真实待付款订单,属于高风险。真机阶段再次等待人工确认;可停用
live采购能力并回退APK,演练和现有采集能力保持可用。; ref=; assets=System.Object[]; labels=System.Object[]; milestone=; projects=; assignee=; assignees=; state=open; is_locked=False; comments=0; created_at=08/17/2026 10:00:49; updated_at=08/17/2026 10:24:54; closed_at=; due_date=; time_estimate=0; pull_request=; repository=; pin_order=0; content_version=1}.title):依赖#42,只负责第二阶段的地址修改、不可逆标记、唯一一次创建订单和只读核单。ehearsal/live执行模式、规则快照、能力协商和本地持久化契约边界。
ehearsal_completed状态。
#42的核心验收是:修改服务端按钮同义文字、等待时间或滑动次数后,不升级Android APK即可让新任务执行新规则;旧任务继续执行旧规则快照。#32原型未通过前,以上工单均保持待实施。
Stage A:QuantUX 可点击原型已完成,等待用户审核
GoAuto - 采购闭环交互原型6a827440191a826306a7eddd原型边界
已覆盖交互
验证结果
favicon.ico的 404,不影响原型。门禁状态
工单保持打开。只有用户明确回复“#32 原型通过”后,才允许进入子工单的数据库、接口、Web 和 Android 实施。
QuantUX 原型同步修正:PDD 商品选择状态
已同步修改 App
6a827440191a826306a7eddd的“选择现有 PDD 商品”页面:972800403573:正常且规格完整,允许选择;719834019024:待完善,明确显示“不可选”;731370706977:已停用 / 数据不完整,明确显示“不可选”。商品ID、标题和店铺现与 #31 PDD 商品原型完全一致。#32结构仍为10页、677个控件、25条有效跳转,无越界、孤立控件或无效跳转。
原型链接:http://124.222.27.183:8082/#/apps/6a827440191a826306a7eddd.html
工单继续等待用户审核,不进入代码实施。
已使用 QuantUX MCP 将线上 App
6a827440191a826306a7eddd导出为本地单文件离线 HTML:prototypes/quantux-procurement-flow-6a827440191a826306a7eddd.html34b5e0c7ccce2021ba92ee03ce252ff0bcc47fc4本次只保存线上草稿的可追溯离线快照,不改变原型审核状态,也不授权采购生产代码实施。
采购流程解耦与价格门禁修订(2026-08-17,替代工单正文中冲突的旧规则)
本轮用户确认 #32 原型需要按“采购、人工支付、订单同步、SYB回填彼此独立”重新设计。原型仍为草稿;用户审核通过前禁止进入生产代码。
一、采购任务只负责创建未付款订单
syb_products明细;同一明细不能同时存在pending/running任务。_cg{taskId},创建未付款订单,并取回 PDD 订单号和下单时间后提交 Admin。pending/running/completed/failed。失败后人工创建新任务,保留旧任务,不重置覆盖历史。taskId + orderNo幂等接收;同任务出现冲突订单号转人工处理。二、人工付款与订单状态独立
_cg{taskId}仅作兜底;无匹配或多候选转人工,不能把“本设备未找到”解释成订单不存在或已取消。三、重新采购从 SYB 商品页发起
syb_products保存最新采购投影:最新任务、PDD订单号、下单时间、支付状态、订单使用状态、首个快递单号和最后回填状态;历史尝试仍保存在采购任务。order_use_status与支付状态独立,只有active/closed。closed后才允许再次采购。四、订单同步与 SYB 回填独立
syb_products批量勾选;必须已有 PDD 订单号和快递单号,回填的是快递单号。五、全局价格范围门禁
20%~150%(内部倍率0.2~1.5,可调整)。单价=商品总价/数量,运费不计入,优惠券来源不单独处理。六、本轮 QuantUX 更新范围
门禁状态
6a827440191a826306a7eddd#32 QuantUX 原型已按解耦方案更新,等待用户审核
6a827440191a826306a7edddprototypes/quantux-procurement-flow-6a827440191a826306a7eddd.html18d96c7新版页面(11页)
本轮关键调整
20%~150%和普通金额示例;采购人员只看参考价、允许价、当前价和是否正常。验证
quantux_verify_export:PASS;navigation、inputsEditable、toggleWorks 均通过。script/link依赖;9个关键页面名称全部检查存在。main,工作区与origin/main一致。门禁
工单继续保持打开和“原型待审核”。用户明确回复“#32 原型通过”之前,不实施采购数据库、服务端、Web 或 Android 生产代码。
SYB 商品批量创建采购任务入口修订(2026-08-17)
用户确认旧原型中“进入 SYB 商品详情后创建采购任务”的流程过于复杂。本轮调整如下,替代 #32 中冲突的旧交互:
SYB商品列表。SYB商品详情改为只读查看:商品关系、最新采购结果和历史采购任务;清除“创建采购任务”按钮及相关说明、卡片和跳转。SYB 商品列表批量创建交互已更新,等待用户审核
已按本工单最新确认修改 QuantUX App
6a827440191a826306a7eddd:验证:
quantux_verify_export:PASS;runtimeErrors=0,unsupportedTypes=0。prototypes/quantux-procurement-flow-6a827440191a826306a7eddd.html,416114 bytes,无外部 script/link 依赖。f5c1096,已推送main。工单继续保持原型待审核;用户明确通过前不实施采购生产代码。
多选、禁用状态与“去匹配”交互补充(2026-08-17)
本轮继续更新 QuantUX 原型:
原型继续保持待审核;本轮只修改线上 QuantUX 和本地离线 HTML,不实施生产代码。
ila referenced this issue2026-08-17 15:16:46 +08:00
SYB 多选与规格映射快捷入口原型已更新,等待审核
6a827440191a826306a7edddprototypes/quantux-procurement-flow-6a827440191a826306a7eddd.html7df4546覆盖 SYB 当前页多选、已知不可采购行禁用、批量创建独立采购任务,以及“规格未映射 → 去匹配 → Shopee/PDD规格映射 → 保存/返回SYB列表”。批量确认和结果均按行展示。工单仍为原型待审核,不授权生产实现。
验收结论
用户 2026-08-18 明确回复「验收通过 #32」,Stage A QuantUX 原型确认通过,可作为采购实施依据。
原型证据
6a827440191a826306a7eddd,12 个页面、770 个控件、31 条流程线,MCP 导出验证PASSprototypes/quantux-procurement-flow-6a827440191a826306a7eddd.html任务归档
文档同步(Wiki-first,镜像已导出并检查一致)
Product-Requirements-Overview:#32 原型状态改为「2026-08-18 已确认」Delivery-Issues:T30 标记已验收;#33 依赖改为「#32 原型已通过」;#40、#41 标注各自 Stage A 原型门禁prototypes/README.md:原型审核状态由草稿改为已确认相关提交
a3ef9cbdocs(#40,#41): mirror stage A prototype gate23464ecdocs(#32): record procurement prototype acceptance未验证部分
后续门禁
子工单 #33 已完成采购任务数据模型与共享 API 契约实现,源码提交
978f428,MySQL 8.4 迁移和服务端全量验证通过,当前等待用户验收。后续 #34 仍不得在 #33 验收前开始。子工单 #33 已于 2026-08-20 验收关闭;#34 服务端采购任务状态机开始实施。当前仍不执行 Android 下单或支付。
子工单 #34 已完成服务端采购任务状态机并进入待验收:创建/快照、设备与可选账号租约、两趟规格探测、attempt 结果幂等、结果未知人工解除、一次性重新采购授权和人工处置接口均已落地。源码
65ae41f;未执行真实下单或支付。#34 已于 2026-08-20 通过用户验收并关闭。采购数据契约和服务端状态机已完成;按既定依赖顺序,下一实施单元为 #42 Android 无副作用采购演练,然后是 #35 Admin 人工处理页面,最后才进入 #36 高风险正式创建订单。
采购子工单 #53 已验收关闭,补齐了 #42 所需的参数化动作契约;#42 已恢复实施。
基于本原型实施的 #35 Admin 采购任务与人工处理页面,以及其接口支撑 #55、#56,已于 2026-08-21 通过用户验收并关闭。后续采购任务创建入口仍由 #44 独立实施。
子工单 #36 已于 2026-08-22 由用户明确验收并关闭。正式采购已验证到
order_created,订单号和下单时间已保存,未执行支付。#32 保持已关闭状态。