289 Admin：兼容多个相同顺运宝明细的档口入库码逐件匹配

类型：缺陷
父级大工单：#14
所属 MVP / 版本：#224 / 档口入库码回写 MVP
状态：已完成
日期：2026-08-22
Gitea 工单：#289

背景与目标

2026-08-22 的档口入库码文件中，订单 260820SS6E61GG 有两个相同业务键、两个不同单件入库码。导入器将其正确聚合为一条记录；顺运宝实时详情却已用两条数量均为 1、规格和 SKU 身份完全相同的商品明细表达这两件商品。旧匹配器看到原始 SKU 命中两条候选后直接按歧义阻断，无法利用“两个码恰好对应两条现成明细”的确定关系。

本任务让这种远端形态可以生成逐件规划、复用现成明细安全回写，同时继续阻断数量不守恒、身份冲突和状态变化等真实歧义。

最终方案

原始 SKU 重复命中后，不直接放宽选择。只有单件码数、Excel 源行数和候选数相等，且每条候选数量均为 1、规格和 sku/variationSku 完全一致、档口身份匹配、采购字段为空时，才进入现成多明细逐件规划。
已经存在的目标入库码优先保留原远端绑定；其余空白候选按稳定 detail_id 顺序与 Excel 单件码顺序一一配对。规划使用现有 remote_items_json 持久化，source 为 existing_matched，不增加表或字段。
后台执行读取持久化规划并复读整张货运单，逐条核对 detail ID、数量、规格、SKU、采购状态和快递单号。任一变化均在远端写请求前停止；该路径只写现成明细，不调用新增占位明细接口。
每写入一个码后继续复读整单并核对全部绑定。结果未知时沿用既有检查点和 needs_check 门禁，只允许只读核对，不自动重试。
单条顺运宝明细 productQty=N 时由 #250 创建额外占位明细的原有流程保持不变。

改了哪些

admin/service/inner_code_match.go：识别数量守恒的相同现成明细，生成稳定逐件绑定并预留全部 detail ID；真实重复候选继续阻断。
admin/service/inner_code_apply.go：解析、复核和执行 existing_matched 规划，支持中断后的只读核对，禁止该路径创建占位明细。
admin/repository/inner_code.go：保存匹配阶段已经验证的 remote_items_json 逐件规划。
admin/service/inner_code_match_test.go、admin/service/inner_code_apply_test.go：覆盖生产形态、稳定绑定、持久化、数量不一致、身份变化零写入和不新增占位明细。
docs/admin/03-data-model.md、docs/admin/08-顺运宝接口.md：记录现成多明细的数据表达和安全门禁。

验收结果

验收标准	结果
两个码与两条身份相同、数量各 1 的空白明细可生成唯一逐件规划	通过
按稳定 detail ID 和 Excel 码顺序绑定并持久化到 `remote_items_json`	通过
写前身份、数量、采购状态或快递单号变化时零写入	通过
两条现成明细分别写入一个码且不创建占位明细	通过
候选数量或总件数不一致、真实歧义继续阻断	通过
#250 单明细多件流程保持不变	通过
固定 Go 1.23.0 自动化验证通过	通过

测试

执行的命令：
- $env:GOTOOLCHAIN="go1.23.0"; go test ./service ./repository ./syb -run InnerCode -count=1
- $env:GOTOOLCHAIN="go1.23.0"; go test ./... -count=1; go build ./...; go vet ./...
- git diff --check（仅核对本工单文件）
结果：定向测试、全量测试、构建、静态检查和差异检查全部通过。另对生产数据库和顺运宝实时详情做了只读核对，确认样本为两个不同入库码对应两条身份相同、数量各 1 的空白明细。
没验证到的部分：没有把修复版本部署到生产；没有在真实顺运宝执行重新匹配或回写，因而没有发送新增、删除或写码请求。生产样本目前仍保持原 skipped 状态。

4.1 KiB Raw Blame History

289 Admin：兼容多个相同顺运宝明细的档口入库码逐件匹配

背景与目标

最终方案

改了哪些

验收结果

测试

相关提交

4.1 KiB

Raw Blame History