docs: record order information completion and SYB eligibility (#326)
This commit is contained in:
QiuSW
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Architecture-and-Code-Map
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Architecture-and-Code-Map.-
|
||||
wiki_revision: a0ad0d4ed6b71676b56276d84d713e85c6b206b8
|
||||
synchronized_at: 2026-09-19T03:52:01Z
|
||||
wiki_revision: 46067d78327476f14e6cfd202458a53f295bf763
|
||||
synchronized_at: 2026-09-19T07:18:28Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 架构与代码地图
|
||||
@@ -498,3 +498,12 @@ Web 唯一展示位置为“采集采购 → SYB 同步记录”：列表状态
|
||||
分支 fix/325-order-result，2026-09-19，尚未发布及真实下单验收。PurchaseLiveAutomation.readOrderResult 采用25次支付页返回后采样、首次待付款页独立30次采样/最多4次按需滑动；原过渡60次与总90次采样上限保留有界终止。parsePayableAmount只从本次只读标签集合提取明确应付总额。
|
||||
|
||||
数据链路：PurchaseOrderEvidence.pddOrderAmountCent → PurchaseExecutionOutcome → service/PurchaseResultPayload.kt → purchase.ResultRequest → lifecycle.go 的 order_created 分支 → 既有 purchase_task.pdd_order_amount_cent。重启只读核单也沿用同一可选字段。复用已有结果Outbox、幂等哈希和订单号唯一性；不新增表、配置、任务或SYB金额字段。未修改我的订单回填、Chrome扩展和Web，不能将旧入口的实付含义描述为本次已改成应付。
|
||||
|
||||
## Admin 订单资料补全与一致回填资格（#326）
|
||||
|
||||
实现3a2472d（2026-09-19），Server/Web，未合并发布；无迁移、无Android/插件改动。
|
||||
|
||||
- purchase/types.go ManualRequest 增加可选 pddOrderAmountCent；manual.go ResolveUnknown 复用既有行锁事务和模型单号保护，扩展为未知结果确认或已创建订单补缺。仅此操作启用新增重放内容校验和事务内 ensureOrderWriteback，其他人工付款/取消/授权流程不新增入队副作用。
|
||||
- order_writeback.go 的任务资格去掉 order_created 限制；validOrderWritebackTarget 统一有效 stock/detail 边界。OrderWritebackViews 一次批量读取关联而非逐行查询，RequestOrderWriteback 和 worker 执行前再次检查。队列结构、租约、外部写入协议不变。
|
||||
- web/src/views/goauto/purchase-tasks/index.vue 沿用原详情/弹窗/resolve-unknown API，新增缺字段补录入口、整数分转换、完整性展示及失败保留输入，不增加数据库状态或新的权限资源。旧未知结果请求不带金额继续兼容。
|
||||
- 回归：server go test -p 1 ./app/goauto/purchase ./app/goauto/clientapi ./app/goauto/sybclient；Web 生产构建及 tests/e2e/purchase-order-writeback.spec.ts 的6项隔离浏览器测试。真实SYB接口用fake/httptest替代，未执行付款、采购或线上写入。
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Business-Rules-and-Glossary
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Business-Rules-and-Glossary.-
|
||||
wiki_revision: 9320ce910ddb26881aafc4dfa4b497d62c144b5b
|
||||
synchronized_at: 2026-09-19T03:52:04Z
|
||||
wiki_revision: 975633525ff82f4be77b37b3d41f08aa05de6822
|
||||
synchronized_at: 2026-09-19T07:18:31Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 业务规则与术语
|
||||
@@ -644,3 +644,15 @@ Web 唯一展示位置为“采集采购 → SYB 同步记录”：列表状态
|
||||
过渡阶段最多60次采样。首次识别到待付款证据后单独分配30次采样预算，不被之前绕路消耗，不因文字反复出现重置；核单总采样上限90次。缺少唯一订单号或时间时立即向上滑动读取下方内容，最多4次、手势400ms、每次后等500ms；读全立即停止，已有完整字段不滑动。该待付款读取分支不点击任何控件，也不点击付款。纯支付页不使用该滑动分支；出现可读待付款证据优先于复用的 Activity 名称。按采样间隔约18秒加有限手势/额外等待，实际耗时还含capture等调用；未改变2分钟任务租约或5分钟唤醒锁，也不宣称新增了执行器总体墙钟超时机制。
|
||||
|
||||
应付金额从同一订单的可见标签集合中读取，兼容“应付:,13元”等标点；不跨无关联节点拼接，不读拼单价、优惠或实付。父子重复同金额去重，多值/缺失/无效/溢出省略，不因金额失败丢弃订单号与时间。仅存Admin，不推断支付、不改SYB金额、不修改地址行为。历史回填及界面语义未在本单统一，详见API契约#325补充。
|
||||
|
||||
## 采购订单资料完整性及简化单号回填（#326）
|
||||
|
||||
用户2026-09-19确认内部系统简化流程，原型v1通过。实现3a2472d，尚未发布或真实SYB验收。
|
||||
|
||||
采购任务保存 PDD 订单号、下单时间和订单金额即为资料完整，不检查是否已付款；金额0元有效。复用 pddOrderNo/orderSubmittedAt/pddOrderAmountCent，金额以人民币分存储。order_created 不改义，仍是已创建订单事实；缺金额展示“订单信息待补全”，不能当作采购失败再次下单。页面统一称“订单金额”，其来源可能是#325应付或既有回填实付，不能将历史值统一称已付金额。
|
||||
|
||||
Admin 复用未知结果处理弹窗增加金额输入，并为 live 已创建且缺资料任务提供“补全订单信息”；已有字段只读、缺项可填。保存中禁用提交，失败保留输入；沿用既有权限，不增加审批。非执行中的未知结果人工确认与已有订单资料补全都会事务内保证单号回填记录，不修改支付复核或触发设备操作。
|
||||
|
||||
SYB 回填与资料完整性独立：正式SYB任务已有单号且仍关联有效明细即可入队，不要求 order_created 状态、时间、金额、付款确认或地址后缀。只有订单号上传SYB；沿用同号成功、异号冲突不覆盖及既有在途防重复规则，不倒扫历史任务。历史补偿仍手动勾选，已成功或在途任务不可重复发起。
|
||||
|
||||
自动下单读取和Admin补录是后续目标来源；本单尚未删除插件或Agent我的订单回填，不能宣称上游地址后缀已取消或历史错误归属已修复。金额缺失不得自动采购，订单号唯一归属保护和永久不付款规则不变。
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Android-Agent-API-Contract
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Android-Agent-API-Contract.-
|
||||
wiki_revision: 17d42cfee87b84a306bfd991b24ca3f3948f1354
|
||||
synchronized_at: 2026-09-19T03:52:23Z
|
||||
wiki_revision: e43e83af5442005139b3234963afd317609b44ac
|
||||
synchronized_at: 2026-09-19T07:18:51Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
<!-- gitea-wiki-mirror:start -->
|
||||
@@ -1350,7 +1350,7 @@ Android 仅人工“回填”扫描识别单节点“实付”标签，兼容实
|
||||
|
||||
实现绑定 e89de1a（2026-09-18，feat/305-syb-order-writeback），已完成代码及隔离测试；未合并、未部署、未执行业务库迁移或真实 SYB 写入。
|
||||
|
||||
- 普通 Agent order_created 结果和人工 order-backfill 首次成功/同单号 already_backfilled 共用事务内 ensureOrderWriteback。仅 live + syb_order + order_created + 有效 PDD 单号与 SYB stock/detail 关联时建立唯一 pending 记录；网络写入由事务外 worker 执行。不改变 Agent 请求/响应字段；金额缺失/冲突不阻止单号入队，不依赖 paymentReviewStatus。
|
||||
- 普通 Agent order_created 结果和人工 order-backfill 首次成功/同单号 already_backfilled 共用事务内 ensureOrderWriteback。仅 live + syb_order + 有效 PDD 单号与 SYB stock/detail 关联时建立唯一 pending 记录（#326 起不限制任务状态）；网络写入由事务外 worker 执行。不改变 Agent 请求/响应字段；金额缺失/冲突不阻止单号入队，不依赖 paymentReviewStatus。
|
||||
- POST /api/admin/v1/purchase-tasks/syb-order-writeback：沿用管理员/采购员采购管理权限；body 为 {requestId: UUID, purchaseTaskIds: 正整数数组}，1～100条，不允许重复ID。单条补偿也使用本接口。
|
||||
- 返回 HTTP 200、{code:200,data:{items:[{taskId,result,reason?}]}}；result 为 pending/succeeded/skipped/conflict。pending 仅表示受理，不代表远端已写入。无资格或不存在的条目独立 skipped，其他条目继续；数据库事务故障整次命令回滚。服务端校验与冲突错误沿用采购错误信封。
|
||||
- requestId 持久幂等：对排序后的 ID 集合取摘要，相同 requestId/集合返回原接受结果，即使后台状态已推进；改变集合返回422。查询当前完成状态应重新GET，不能以重放响应判断最终成功。
|
||||
@@ -1377,3 +1377,17 @@ Android 仅人工“回填”扫描识别单节点“实付”标签，兼容实
|
||||
服务端只为已成功确认且无订单号占用冲突的任务补写空 pdd_order_amount_cent；省略、null 或已有非空值均不清空/覆盖。字段纳入现有结果哈希，相同 requestId/attempt/载荷幂等，不同载荷拒绝。不改支付状态，不传金额到 SYB。原列已存在，无追加迁移；新 Agent 上报前须先发布此 Server，旧 Server 不接受新结果字段。
|
||||
|
||||
本单不修改 #306 人工订单回填、#316 Chrome 回填、Web“实付价格”显示或历史值：这些路径仍沿用原语义，不能据此宣称全局金额已统一为应付。此节仅定义新增采购结果入口。
|
||||
|
||||
## Admin 订单资料补全与字段型 SYB 入队（#326）
|
||||
|
||||
实现提交 3a2472d，2026-09-19，feat/326-order-information；隔离测试及构建通过，未合并 main、未发布、未执行真实 SYB 写入。
|
||||
|
||||
复用 POST /api/admin/v1/purchase-tasks/:id/resolve-unknown 及其原有管理员/采购员权限：live 的 order_result_unknown 可人工确认订单或取消；live 的 order_created 可补全订单信息，但不能通过此接口改成 cancelled。status=order_created 时沿用 pddOrderNo、orderSubmittedAt，增加可选非负整数分 pddOrderAmountCent，复用原数据库列。订单号非空、无首尾空白/换行且不超过100字符，时间须为有效非零时间；旧客户端省略金额仍接受并保留已有值。新 Admin 补录表单要求金额，0元合法，最多两位小数，转换为整数分后提交。
|
||||
|
||||
已保存非空字段只补缺，不覆盖不同单号、时间或金额；订单号唯一归属仍由原模型保护。相同 requestId/已保存内容重放不重复保存，改变处理结果或已保存字段返回原采购冲突错误。前端网络失败保留输入及相同载荷的 requestId；修改载荷使用新 requestId。复用原审计字段 UnknownResolveRequestID，无新增表或持久化状态。
|
||||
|
||||
资料完整性由订单号、有效下单时间和非空非负订单金额推导，页面显示“信息完整”或“订单信息待补全”。order_created 仍表示已创建订单，缺金额不转 failed，不代表已付款，不重新采购。
|
||||
|
||||
人工确认/补录订单在同一事务中 ensureOrderWriteback；原 Agent order_created 与插件/Agent order-backfill 保持兼容。SYB 回填仅要求 live + syb_order + 非空订单号 + 有效关联 stock/detail；不检查任务状态、时间、金额、支付复核或地址后缀。列表批量读取有效关联，提交与 worker 校验相同目标范围。既有 pending/running/succeeded 不重复入队，conflict 不覆盖，unknown 保留原回读及租约规则。字段补全不恢复已失败队列，失败队列仍通过原“回填 SYB 单号”补偿操作处理。
|
||||
|
||||
仅回填单号，cost=0/created为空；金额、时间只存 Admin。旧物流 paid 候选流程不改，Android 与 Chrome 上传定位契约未改；今后停用插件和 Agent 回填须另行实施。本次无需数据库迁移；先发布新 Server 再发布发送金额字段的新 Web。
|
||||
|
||||
Reference in New Issue
Block a user