diff --git a/docs/task/245-档口入库码直查顺运宝.md b/docs/task/245-档口入库码直查顺运宝.md new file mode 100644 index 0000000..6f588b5 --- /dev/null +++ b/docs/task/245-档口入库码直查顺运宝.md @@ -0,0 +1,64 @@ +# 245 Admin:档口入库码按货运单号直查顺运宝 + +- 类型:缺陷 +- 父级大工单:#14 +- 所属 MVP / 版本:#224 +- 状态:已完成 +- 日期:2026-08-15 +- Gitea 工单:http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/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)