cmautobuy/docs/task/245-档口入库码直查顺运宝.md

245 Admin：档口入库码按货运单号直查顺运宝

• 类型：缺陷
• 父级大工单：#14
• 所属 MVP / 版本：#224
• 状态：已完成
• 日期：2026-08-15
• Gitea 工单：#245

背景与目标

档口入库码匹配原先先从本地 syb_orders 解析货运单 ID。本地尚未同步、被 SYB 店铺准入规则过滤或快照缺字段时，即使顺运宝能按货运单号找到记录，也会错误 提示本地没有货运单。

本任务将货运单定位恢复为原 Python 流程和 HAR 已确认的行为：对 Excel 货运单号 去重后，使用顺运宝 t_stock.allcode 直接查询远端货运单，再读取最新商品明细并 执行既有规格、档口和安全门禁。

最终方案

• 顺运宝 Go 客户端新增按货运单号查询：先调用 listTotal，再以 20 条分页调用 list，查询条件固定为 allcode。
• 对返回结果严格核对 code、货运单 ID、页大小、重复 ID 和安全上限；协议异常 不进入匹配。
• 规划服务按勾选记录中的不同货运单号顺序查询远端。零命中和多命中生成明确的 逐行结果；网络或协议错误中止整批，不保存半批计划。
• 唯一命中的货运单 ID 继续按每批最多 100 个调用详情接口；现有规格、档口、 采购字段、明细占用和回写安全规则不变。
• 删除本地 syb_orders 快照查询和 JSON stock.id 解析代码。远端查询结果不写入 SYB 数据模块，也不受店铺入库过滤影响。

改了哪些

• admin/syb/client.go：新增 allcode 货运单查询、分页和协议校验。
• admin/syb/client_test.go：覆盖请求契约、分页、零命中、安全上限和异常响应。
• admin/service/inner_code_match.go：规划改为直查远端货运单并调整零命中提示。
• admin/service/inner_code_match_test.go：覆盖订单去重、整批失败和无本地 SYB 数据 仍能生成计划。
• admin/repository/inner_code.go：删除不再使用的本地 SYB 快照查询。

验收结果

验收标准	结果
本地没有 syb_orders 记录时，远端唯一命中仍可生成可回写计划	通过
同一批相同货运单号只查询一次，详情按最多 100 个 ID 分批	通过
零命中和多命中不猜测，并保存明确结果	通过
错误 code、短页、重复 ID、超限和远端错误可诊断	通过
规划阶段不调用顺运宝写接口、不写入 syb_orders	通过
固定 Go 1.23.0 的 vet、构建和全量测试通过	通过

测试

• 执行的命令：
  • go test ./syb ./service -run 'ListByOrderNumber|InnerCode' -count=1
  • $env:GOTOOLCHAIN='go1.23.0'; go vet ./...; go build ./...; go test ./... -count=1
• 结果：全部通过。
• 没验证到的部分：未连接真实顺运宝执行生产货运单查询，未部署到生产服务器， 未执行任何顺运宝删除或更新操作。

相关提交

• b47e7ed fix: 档口入库码按货运单号直查顺运宝 (#245)