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

New Issue

2026-08-22T11:36:32+08:00

ila commented

2026-08-22 11:36:32 +08:00

基本信息

类型：缺陷
父级大工单：#14
所属 MVP / 版本：#224 / 档口入库码回写 MVP
阶段：多件商品远端明细形态兼容

要解决什么

2026-08-22 的档口入库码文件中，订单 260820SS6E61GG 有两条相同业务键、两个不同单件入库码。导入器按既有规则将其聚合为一条记录，source_duplicate_count=2。

顺运宝实时详情却已存在两条独立商品明细：两条规格、sku、variationSku 完全相同，每条 productQty=1，且采购平台、采购单号和快递单号均为空。现有匹配代码在原始 SKU 命中两条候选时直接返回“原始 SKU 候选重复，不能自动选择”，没有识别“两个码恰好对应两条现成明细”的可确定场景。

复现：导入 Shopee线下档口入库码映射_20260822_V3.3-R5-M1.xlsx，选择该订单的聚合记录执行匹配，记录进入 skipped。

做什么 / 不做什么

做：兼容一个聚合记录对应多条现成顺运宝明细；候选数量、候选总件数和单件码数量完全一致��身份、安全状态均一致时，生成逐件确定性规划。
做：按稳定的远端明细 ID 顺序与 Excel 单件码原始顺序一一绑定，把逐件绑定保存到现有 remote_items_json；回写前逐条复读核验，复用现成明细，不新增占位商品。
做：保留单条顺运宝明细 productQty=N 时由 #250 创建额外占位明细的既有路径。
不做：不修改 Excel 业务键和聚合方式，不增加数据库字段或新表，不修改顺运宝接口和页面交互。
不做：候选数不等、数量不等、身份冲突、已有采购信息或已有非目标快递单号时仍必须阻断；未知写结果仍不得自动重试。

怎么做

admin/service/inner_code_match.go：把重复原始 SKU 候选细分为“可确定的多明细逐件分配”和“真实歧义”；仅在单件码数、源行数、候选总数量均一致，且候选均为数量 1、同一规格/原始 SKU/档口身份、无采购信息时生成稳定逐件规划。
admin/service/inner_code_apply.go：读取规划阶段保存的逐件明细绑定；回写前重新获取整张货运单，核对每个 detail ID 的身份、安全状态和数量，再逐件写入并回读确认。现成空白明细标记为 existing_matched，不得走创建占位明细路径。
admin/repository/inner_code.go：保存只读规划时允许写入已经验证的 remote_items_json，重新规划继续原子替换旧规划。
admin/service/inner_code_match_test.go、admin/service/inner_code_apply_test.go：覆盖两个相同候选对应两个码、候选数量不等、候选身份变化、已有远端值及原有单明细多件路径。
更新稳定基线文档，明确两种远端明细形态及安全门禁。

验收标准

两个不同入库码、两条身份相同且各数量为 1 的空白远端明细可生成唯一逐件规划，不再报“原始 SKU 候选重复”。
逐件规划按稳定 detail ID 顺序绑定 Excel 原始码顺序，并持久化到现有 remote_items_json。
回写前任一明细的规格、SKU、数量、采购状态或快递单号变化时停止写入，不创建新明细、不自动重试。
两条现成明细分别写入一个码并逐件回读确认；该路径不会调用创建占位明细接口。
候选数量与单件码数量不等、总数量不等或仍存在真实歧义时继续阻断。
#250 的“单条明细数量为 N，额外创建占位明细”行为保持不变。
固定 Go 1.23.0 下定向测试、全量测试、build、vet 和 git diff --check 通过。

怎么验证

从 admin/ 执行：

$env:GOTOOLCHAIN="go1.23.0"
go test ./service ./repository ./syb -run InnerCode -count=1
go test ./... -count=1
go build ./...
go vet ./...
Remove-Item Env:GOTOOLCHAIN
git diff --check

使用脱敏测试数据模拟订单内两条相同身份、数量各 1 的远端明细；生产样本只做只读核对，不在自动化测试中发送真实回写请求。

风险和回退

风险：若把真实歧义误认为多件分配，可能把单件码写到错误明细。修复必须要求数量完全守恒、身份一致，并在写前对全部绑定明细重新核验；任一条件不满足整条记录停止。
回退：回退本工单代码和文档提交即可恢复旧的保守阻断；无数据库迁移。已经逐件回读确认的远端值不自动删除。

实施记录（2026-08-22）

状态：已完成，待用户验收。
实现提交：18ad85d。
归档提交：a61d97b。
归档文档：docs/task/289-多个相同顺运宝明细逐件匹配.md。
最终实现：数量守恒且身份完全一致的多个现成数量 1 明细，按目标码顺序保存 existing_matched 逐件绑定；后台写前和写后复读全部绑定，复用现成明细且不调用创建接口。其他重复候选继续阻断。
验证：固定 Go 1.23.0 的档口入库码定向测试、全量 test、build、vet 和差异检查通过。
未验证：未部署生产；未对真实顺运宝发送重新匹配、创建、删除或写码请求，生产样本仍保持原 skipped 状态。

## 基本信息 - 类型：缺陷 - 父级大工单：#14 - 所属 MVP / 版本：#224 / 档口入库码回写 MVP - 阶段：多件商品远端明细形态兼容 ## 要解决什么 2026-08-22 的档口入库码文件中，订单 `260820SS6E61GG` 有两条相同业务键、两个不同单件入库码。导入器按既有规则将其聚合为一条记录，`source_duplicate_count=2`。顺运宝实时详情却已存在两条独立商品明细：两条规格、`sku`、`variationSku` 完全相同，每条 `productQty=1`，且采购平台、采购单号和快递单号均为空。现有匹配代码在原始 SKU 命中两条候选时直接返回“原始 SKU 候选重复，不能自动选择”，没有识别“两个码恰好对应两条现成明细”的可确定场景。复现：导入 `Shopee线下档口入库码映射_20260822_V3.3-R5-M1.xlsx`，选择该订单的聚合记录执行匹配，记录进入 `skipped`。 ## 做什么 / 不做什么 - 做：兼容一个聚合记录对应多条现成顺运宝明细；候选数量、候选总件数和单件码数量完全一致��身份、安全状态均一致时，生成逐件确定性规划。 - 做：按稳定的远端明细 ID 顺序与 Excel 单件码原始顺序一一绑定，把逐件绑定保存到现有 `remote_items_json`；回写前逐条复读核验，复用现成明细，不新增占位商品。 - 做：保留单条顺运宝明细 `productQty=N` 时由 #250 创建额外占位明细的既有路径。 - 不做：不修改 Excel 业务键和聚合方式，不增加数据库字段或新表，不修改顺运宝接口和页面交互。 - 不做：候选数不等、数量不等、身份冲突、已有采购信息或已有非目标快递单号时仍必须阻断；未知写结果仍不得自动重试。 ## 怎么做 - `admin/service/inner_code_match.go`：把重复原始 SKU 候选细分为“可确定的多明细逐件分配”和“真实歧义”；仅在单件码数、源行数、候选总数量均一致，且候选均为数量 1、同一规格/原始 SKU/档口身份、无采购信息时生成稳定逐件规划。 - `admin/service/inner_code_apply.go`：读取规划阶段保存的逐件明细绑定；回写前重新获取整张货运单，核对每个 detail ID 的身份、安全状态和数量，再逐件写入并回读确认。现成空白明细标记为 `existing_matched`，不得走创建占位明细路径。 - `admin/repository/inner_code.go`：保存只读规划时允许写入已经验证的 `remote_items_json`，重新规划继续原子替换旧规划。 - `admin/service/inner_code_match_test.go`、`admin/service/inner_code_apply_test.go`：覆盖两个相同候选对应两个码、候选数量不等、候选身份变化、已有远端值及原有单明细多件路径。 - 更新稳定基线文档，明确两种远端明细形态及安全门禁。 ## 验收标准 - [x] 两个不同入库码、两条身份相同且各数量为 1 的空白远端明细可生成唯一逐件规划，不再报“原始 SKU 候选重复”。 - [x] 逐件规划按稳定 detail ID 顺序绑定 Excel 原始码顺序，并持久化到现有 `remote_items_json`。 - [x] 回写前任一明细的规格、SKU、数量、采购状态或快递单号变化时停止写入，不创建新明细、不自动重试。 - [x] 两条现成明细分别写入一个码并逐件回读确认；该路径不会调用创建占位明细接口。 - [x] 候选数量与单件码数量不等、总数量不等或仍存在真实歧义时继续阻断。 - [x] #250 的“单条明细数量为 N，额外创建占位明细”行为保持不变。 - [x] 固定 Go 1.23.0 下定向测试、全量测试、build、vet 和 `git diff --check` 通过。 ## 怎么验证从 `admin/` 执行： ```powershell $env:GOTOOLCHAIN="go1.23.0" go test ./service ./repository ./syb -run InnerCode -count=1 go test ./... -count=1 go build ./... go vet ./... Remove-Item Env:GOTOOLCHAIN git diff --check ``` 使用脱敏测试数据模拟订单内两条相同身份、数量各 1 的远端明细；生产样本只做只读核对，不在自动化测试中发送真实回写请求。 ## 风险和回退 - 风险：若把真实歧义误认为多件分配，可能把单件码写到错误明细。修复必须要求数量完全守恒、身份一致，并在写前对全部绑定明细重新核验；任一条件不满足整条记录停止。 - 回退：回退本工单代码和文档提交即可恢复旧的保守阻断；无数据库迁移。已经逐件回读确认的远端值不自动删除。 ## 实施记录（2026-08-22） - 状态：已完成，待用户验收。 - 实现提交：`18ad85d`。 - 归档提交：`a61d97b`。 - 归档文档：`docs/task/289-多个相同顺运宝明细逐件匹配.md`。 - 最终实现：数量守恒且身份完全一致的多个现成数量 1 明细，按目标码顺序保存 `existing_matched` 逐件绑定；后台写前和写后复读全部绑定，复用现成明细且不调用创建接口。其他重复候选继续阻断。 - 验证：固定 Go 1.23.0 的档口入库码定向测试、全量 test、build、vet 和差异检查通过。 - 未验证：未部署生产；未对真实顺运宝发送重新匹配、创建、删除或写码请求，生产样本仍保持原 `skipped` 状态。

ila referenced this issue

2026-08-22 11:36:34 +08:00

[MVP] Admin 档口入库码回写 #224

ila referenced this issue

2026-08-22 11:47:56 +08:00

[Epic] Admin 采集采购管理端 #14

ila referenced this issue

2026-08-22 11:51:18 +08:00

Admin：部署多个相同顺运宝明细逐件匹配修复到生产 #290

ila commented

2026-08-22 11:58:52 +08:00