docs: sync SYB order writeback contracts (#305)

2026-09-18 10:20:03 +08:00
parent e89de1a085
commit 7e257ca153
5 changed files with 71 additions and 10 deletions
@@ -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: d192f3976c44b15a53221211eaed903bdec4fcd6
-synchronized_at: 2026-09-18T01:23:50Z
+wiki_revision: c8dd6b1f25bf367d065e0969a4de858d857a3181
+synchronized_at: 2026-09-18T02:18:10Z
 <!-- gitea-wiki-mirror:end -->

 # 架构与代码地图
@@ -473,3 +473,15 @@ Web 唯一展示位置为“采集采购 → SYB 同步记录”：列表状态
 - 本次不修改 SYB 客户端或 #305，金额不进入 SYB 请求。

 验证覆盖 Android 解析/载荷/回执缓存、Server 幂等/冲突/旧请求和局部 SQLite 迁移、Web 金额/空值展示；真机端到端、实际 MySQL 迁移和发布须另行授权，不能以本地测试替代。
+
+## SYB 单号回填持久队列（#305）
+
+实现绑定 e89de1a（2026-09-18，未部署），仅 Server/Web；Android 复用现有普通结果与人工订单回填。
+
+- purchase/lifecycle.go、purchase/order_backfill.go → ensureOrderWriteback：与订单事实同事务建立 pending，purchase_task_id 唯一；外部失败不撤销已提交的订单事实。
+- models/purchase_order_writeback.go：purchase_order_writeback 保存不可变 stock/detail/单号快照、状态、attempt_count、write_started、租约、脱敏错误和完成时间；purchase_order_writeback_command 保存 requestId/输入摘要/逐项接受结果；purchase_order_writeback_lease 保存全局单例租约。追加迁移 1789800200000，不改旧物流字段，不批量排入历史订单。
+- purchase/order_writeback.go：批量命令事务/幂等/条件校验和 Admin 状态投影；order_writeback_handler.go/router.go 暴露 Admin 补偿；access/purchaser.go 纳入原采购权限启动对账目录。
+- purchase/order_writeback_worker.go：由 cmd/api/server.go 每数据库启动一个3秒轮询 worker；数据库2分钟单例租约使跨进程及不同任务的相同SYB明细写入串行。写前核对当前任务/关联快照，持久化写入起始标记，并验证租约所有者/剩余时间；不持有数据库事务跨网络请求。失联running恢复只回读，unknown不自动调度；其他同目标未确认写入阻止新写。
+- sybclient/order_number.go：一次 POST updateDetailPurchaseCode，不跟随重定向、不使用读接口重试策略。会话仅从现有 SessionStore 恢复，不在 worker 自动登录/OCR；外部原始错误不写入任务原因。
+- Web purchase-tasks API/页面：共享勾选、按动作筛选、独立状态列/详情及逐项接受结果；付款和物流流程保持原样。
+- 验证入口：go test ./app/goauto/purchase ./app/goauto/sybclient ./app/goauto/access ./app/goauto/migrations ./cmd/migrate/migration/version-local；Web tests/e2e/purchase-order-writeback.spec.ts。测试只使用隔离SQLite和fake/httptest，不代表MySQL多实例或真实SYB验收。
@@ -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: d11ff945f559869ad638de2c0da198cbf6f31d7e
-synchronized_at: 2026-09-18T01:23:55Z
+wiki_revision: f353b476add5081d4d7a1493e5454b6400518923
+synchronized_at: 2026-09-18T02:18:13Z
 <!-- gitea-wiki-mirror:end -->

 # 业务规则与术语
@@ -618,3 +618,15 @@ Web 唯一展示位置为“采集采购 → SYB 同步记录”：列表状态
 不判断是否付款，不改变人工支付复核状态。没看到实付、格式异常或多个不同实付值时，仅跳过金额，订单号和时间照常按原规则回填。采购员可稍后再点既有“回填”，为空金额补写；已有相同值幂等，不同值保留旧值并返回金额冲突提示，不撤销正确订单事实。只允许当前设备自己的、原有允许状态的任务；不新增 attempt 或采购动作。

 金额仅保存 Admin；#305 订单号回写 SYB 的数据流不得使用该字段或将其映射为 cost，金额缺失/冲突不得成为订单号回写的前置条件。本单不代表 #305 已实现。Admin 现有订单详情卡片增加“实付价格”，缺失显示“尚未获取”，不新增列表列、入口或支付动作。安全点击集合及不保存原始控件树/个人信息的规则不变。
+
+## PDD 订单号自动回填 SYB（#305）
+
+实现绑定 e89de1a（2026-09-18），代码与隔离测试已完成，真实迁移/发布/SYB写入尚未验证。以下补充 #306 的单号后续流程，不改变其金额规则。
+
+正式 SYB 订单采购取得 PDD 单号（普通结果或人工遍历回填）后，在订单事实的同一个数据库事务中保存独立回填记录，后台异步写入对应 stock_id + detail_id。已人工回填相同单号也幂等确保记录存在；不重新采购，不等待支付复核。备货、演练、未取得单号或关联失效不回填；不自动扫描历史单据，历史补偿由采购管理勾选发起。
+
+写前精确回读唯一目标明细：同单号且 purchasePlatform=pdd 直接成功；非空不同单号/不兼容平台标记 conflict，不覆盖。远端为空才允许一次写请求，写后回读确认才成功。未知结果不得自动重复写；重启恢复的 running 只回读，不能因租约过期盲重发。失败/unknown 可人工补偿，仍先回读，且在途租约未到期时不能再发起。
+
+订单回填状态独立于采购成功、支付复核及物流 writeback_status。实付金额只存 Admin，SYB cost=0 为接口固定参数，不以金额推断付款。SYB 接口会同时更新采购状态/平台/时间，不能视作纯展示修改。
+
+采购管理增加独立状态列、批量回填和详情补偿；复用既有访问权限，不增支付确认或审批。批量受理与最终成功分开展示；重试采购和回填分别筛选勾选项。远端无原子CAS，对系统外人工并发修改/超长延迟请求不能承诺绝对互斥；有冲突应人工核对，禁止强制覆盖。
@@ -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: 05441afb3c22828b8d17d4b9dcf2592075092076
-synchronized_at: 2026-09-18T01:24:22Z
+wiki_revision: 5a61e4f2cf2bb33b824ca722e9cee03071e1dffd
+synchronized_at: 2026-09-18T02:18:33Z
 <!-- gitea-wiki-mirror:end -->

 <!-- gitea-wiki-mirror:start -->
@@ -1345,3 +1345,17 @@ POST /api/agent/v1/purchase-tasks/order-backfill 的 items 可增加 pddOrderAmo
 Android 仅人工“回填”扫描识别单节点“实付”标签，兼容实付:,金额元,(免运费)及中英文冒号/逗号/空格，金额整数或最多两位小数，以十进制定点转换。不使用裸人民币数字、不跨节点拼金额；缺失、无效、溢出或多个不同金额时只省略金额。同一订单跨视口去重，切换订单清空。并不据此判断已付款。

 追加迁移：1789800100000_purchase_order_amount.go，仅扩展 purchase_task 的可空非负 pdd_order_amount_cent；旧行 NULL，不推算单价×数量。先授权迁移并发布新 Server，再升级 Agent；旧 Server 严格拒绝未知字段，不能先装新 Agent 后向旧 Server 发送金额。本单不扩展普通采购 readOrderResult，也不增加 SYB cost 数据流。
+
+## SYB 采购单号回填（#305）
+
+实现绑定 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。
+- 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，不能以重放响应判断最终成功。
+- Admin 列表/详情 task 新增 orderWriteback={status,reason?,completedAt?,canSubmit}。无队列时符合资格显示 not_started，否则 not_applicable；队列状态 pending/running/succeeded/failed/conflict/unknown。仅未发起、failed/unknown 且任务仍有资格、租约已过期时 canSubmit=true；running/pending/succeeded/conflict 不提供重复发起。
+- 回填只写 PDD 订单号；cost 固定0，created为空，绝不传 pddOrderAmountCent 或 actualUnitPriceCent。旧 writebackStatus/支付/物流字段不复用，旧物流 paid 规则不扩展到本接口。
+- 批量勾选取“可采购重试 OR 可单号回填”的并集，两个按钮各自过滤子集；不得把 order_created 任务送入采购重试。冲突只查看，不提供覆盖。unknown 人工补偿仍先回读，成功仅指回读确认相同单号与 pdd 平台。
+
+追加迁移 1789800200000_purchase_order_writeback.go 建立独立记录、命令和单例租约表。先授权迁移及权限对账后再运行新版 Server/Web；本实现基于 #306，发布时同时核验其金额列迁移依赖。历史记录不在迁移时自动入队。
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: SYB-ERP-Interface-Contract
 wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/SYB-ERP-Interface-Contract.-
-wiki_revision: f1792b7fe35925480c25b890e85fa5e551744812
-synchronized_at: 2026-09-11T09:11:21Z
+wiki_revision: 432e392ebe428ea19c0aa260f8e5938f36e4c3f0
+synchronized_at: 2026-09-18T02:18:53Z
 <!-- gitea-wiki-mirror:end -->

 # 12 顺云宝（SYB）ERP 接口契约
@@ -679,3 +679,15 @@ settings:
 `orderCount` 是已验证页的原始列表读取数量；`detailCount`、`created`、`updated` 为已提交明细及其新增/覆盖数量；`daysProcessed` 是完整通过的日期数，不是已尝试日期数。失败日期/页码/阶段写入现有脱敏限长 errorMessage。部分成功不刷新店铺的完整同步统计。

 Web 唯一展示位置为“采集采购 → SYB 同步记录”：列表状态、状态筛选及详情支持部分成功，详情保留已保存数量、错误原因与重新同步补齐提示。定时任务日志只表示异步任务受理，不等于最终业务同步成功。
+
+## PDD 采购单号写入（#305）
+
+实现绑定 e89de1a（2026-09-18，未部署）。协议依据用户本地 update_syb_pdd_order_number.har 单次样本；HAR/真实标识/Cookie不进入源码、Wiki或工单。本节不宣称远端幂等或原子比较写入。
+
+POST /am/stock/detail/updateDetailPurchaseCode，无JSON body；query：id=<stock.id>、detailId=<details[].id>、code=<PDD单号>、type=pdd、created=""、cost=0。ID必须为正整数，单号非空、无首尾空白/控制换行、最多100字符。cost是抓包确认的固定参数，不是实际金额；不得传Agent实付价格。
+
+样本成功信封 HTTP200、status=true；随后 listByStock?hist=0 对应明细 purchaseCode 等于提交单号、purchasePlatform=pdd、purchaseStatus=1，purchaseTime由SYB生成。更新存在采购状态/时间副作用。
+
+客户端每次处理最多一次写请求，并拒绝HTTP重定向重发；超时/连接中断/5xx/损坏响应作为结果未知。无论写响应成功或未知，都须按 stockId + detailId 唯一回读目标；相同单号+pdd才确认为成功，不同已有单号或其他非空平台记冲突且不覆盖。写前为空才写；目标缺失/重复/字段类型异常不得猜测选择。未知且未回读确认时持久化unknown，人工补偿前再次回读，不使用自动写重试。
+
+GoAuto自身通过持久租约串行，但SYB没有CAS证据，无法原子隔离系统外客户端；不能保证任意迟到请求已终止。真实接口写入需另行明确授权；当前验证仅fake/httptest。
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Deployment-and-Operations
 wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Deployment-and-Operations.-
-wiki_revision: a8da51a554b9c43da4b72104d707d3c72c5cd534
-synchronized_at: 2026-09-17T08:57:51Z
+wiki_revision: a630bab8f1c775ce9ed29cac990777b6760eeda4
+synchronized_at: 2026-09-18T02:18:19Z
 <!-- gitea-wiki-mirror:end -->

 # 部署与运维
@@ -113,3 +113,14 @@ Provider 故障日志只允许记录调用关联 ID、操作类型、耗时、
 - Admin Web 由 `scripts/start-web.ps1` 启动，监听 `0.0.0.0` 的 `ports.web`，因此同一局域网设备可通过 `http://<本机局域网IP>:<web端口>/` 访问。
 - 浏览器使用同源相对 API；Vite 将 `/api` 与 `/static` 代理到本机 `127.0.0.1:<server端口>`，避免局域网客户端错误访问自身的 `127.0.0.1`。
 - 修改脚本或配置后，只需重启 Supervisor 的 `goauto-admin-ui`；API 未变化时无需重启 `goauto-admin-api`。若局域网仍无法连接，检查 Windows 防火墙是否允许 `ports.web` 的 TCP 入站。
+
+## SYB 订单号回填 worker 部署与排错（#305）
+
+代码绑定 e89de1a（2026-09-18），基于 #306 的07a3817；本节是部署要求，不表示已发布或业务库已迁移。
+
+1. 另行取得明确目标环境的数据库迁移、权限对账和发布授权。核对 #306 的1789800100000金额列前置；本单追加1789800200000_purchase_order_writeback.go，建立purchase_order_writeback、purchase_order_writeback_command、purchase_order_writeback_lease三表和单例行，不改任务/付款事实，不排入历史回填、不修改定时任务开关。
+2. 配套构建并发布Server/Web，沿用现有启动权限对账为管理员/采购员登记POST /api/admin/v1/purchase-tasks/syb-order-writeback。不新增角色、菜单或支付门槛。旧常驻实例使用SkipMigration时，仅重启并不能替代授权迁移。
+3. API启动后每数据库恢复一个3秒轮询的持久队列worker，独立于Admin定时任务列表；只处理已排入pending及租约过期running。正式采购结果、人工订单回填成功/同号回放会排队；历史补偿仅用户勾选发起。部署重启后已有pending会执行真实SYB写入，必须包含在发布授权范围内。
+4. 全局租约2分钟；会话恢复预算25秒，每次外部读/写20秒（只读客户端重试亦受该context限制），写前再次核验租约。崩溃恢复只回读，不盲目重写；unknown不自动重试，等租约到期再人工核对/补偿。同目标其他未确认写入先解决，不能删除记录规避保护。
+5. 排错先看采购管理的“SYB 单号回填”状态、脱敏原因、完成时间；需要结构诊断时查询记录的taskId/status/attempt_count/error_code/lease_expires_at，不输出单号、Cookie或完整原始响应。SYB会话失败应先恢复既有登录，再勾选失败任务补偿；按钮受理不等于SYB成功。conflict只核对，不强制覆盖。
+6. 不执行真实支付；实付金额只存Admin，SYB请求cost固定0。停止新版API可停止新轮询，但不保证已发送远端请求取消；回滚保留追加表和未知状态，不删除记录、不回退采购事实。迁移/多实例MySQL/真实SYB端到端仍需授权验收。