docs: 归档任务 #245

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)