docs: 归档任务 #289

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)