From a61d97ba4553785f089fc1f0d0454ab54c20ef05 Mon Sep 17 00:00:00 2001 From: chengma Date: Sat, 22 Aug 2026 11:47:16 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=E4=BB=BB=E5=8A=A1=20?= =?UTF-8?q?#289?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/task/289-多个相同顺运宝明细逐件匹配.md | 72 +++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 docs/task/289-多个相同顺运宝明细逐件匹配.md diff --git a/docs/task/289-多个相同顺运宝明细逐件匹配.md b/docs/task/289-多个相同顺运宝明细逐件匹配.md new file mode 100644 index 0000000..9625095 --- /dev/null +++ b/docs/task/289-多个相同顺运宝明细逐件匹配.md @@ -0,0 +1,72 @@ +# 289 Admin：兼容多个相同顺运宝明细的档口入库码逐件匹配 + +- 类型：缺陷 +- 父级大工单：#14 +- 所属 MVP / 版本：#224 / 档口入库码回写 MVP +- 状态：已完成 +- 日期：2026-08-22 +- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/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` 状态。 + +## 相关提交 + +- `18ad85d` fix: 兼容相同顺运宝明细逐件回写 (#289)