cmautobuy/docs/task/259-原始SKU辅助档口匹配.md

259 Admin：档口入库码使用原始 SKU 辅助确定性匹配

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

背景与目标

17 号 Excel 的档口名称和货号经过拼接后带 #，而顺运宝候选 variationSku 使用源 Excel 的原始排列，导致规格正确的目标商品被档口规则排除。本次增加原始 SKU 精确证据，不放宽已有安全门禁。

最终方案

• MySQL v28 在原业务表追加可空二进制排序字段 source_sku_raw VARCHAR(500)；v29 兼容已被中间版本按表默认排序规则创建并记录 v28 的数据库，把字段规范为 utf8mb4_bin。
• 导入器兼容“原始SKU”“原始sku”“原始 SKU”和带来源说明的表头。数据库保留单元格原文，比较时只去除两端空白。
• 重复导入补充原始 SKU；已回写、回写中或需核对记录仍保留原状态和远端审计。
• 先执行订单、采购字段和规格门禁，再把原始 SKU 与候选 sku/variationSku 完全相等比较。唯一命中时允许覆盖分隔符不同造成的档口零命中。
• 原始 SKU 重复命中、档口证据重复，或两项证据唯一指向不同候选时停止自动选择。原始 SKU 缺失或零命中继续使用原档口规则。
• 没有增加去 #、包含匹配、短货号或 AI 猜测。

改了哪些

• admin/repository/mysql_db.go：增加 MySQL v28 字段迁移、v29 兼容迁移和结构自检。
• admin/model/inner_code.go、admin/repository/inner_code.go：贯通原始 SKU 的插入、幂等更新、扫描和终态审计保留。
• admin/service/inner_code_import.go：兼容可选表头、保留原文、校验长度及同业务键源值一致性。
• admin/service/inner_code_match.go：增加精确原始 SKU 证据、旧规则兜底和证据冲突阻断。
• 对应测试覆盖表头变体、原文保留、SKU/variationSku 命中、旧规则兜底、重复和冲突。
• docs/admin/03-data-model.md：记录 v28 字段和确定性规则。

验收结果

验收标准	结果
v28/v29 可重放迁移及结构自检	通过
17 号 Excel 第 31、32 行读出目标原始 SKU	通过
原始 SKU 精确命中 sku 或 variationSku	通过
原始 SKU 缺失或零命中时保留旧档口规则	通过
原始 SKU 重复或与档口证据冲突时阻断	通过
重复导入补充字段且终态审计不重置	通过
匹配阶段保持只读顺运宝	通过

测试

• 执行的命令：go test ./service ./repository ./syb -run InnerCode -count=1、go test ./... -count=1、go build ./...、go vet ./...、git diff --check（Go 1.23.0）。另对 raw_data/Shopee线下档口入库码映射_20260817_V3.3-R5.xlsx 做本地只读解析，确认第 31、32 行原始 SKU。
• 结果：全部通过；实际 Excel 目标两行均成功解析。
• 没验证到的部分：实现提交后尚未连接生产 MySQL 执行 v29；未登录生产顺运宝重新规划目标订单，也未执行任何远端回写。

相关提交

• 4383bb8 fix: 使用原始SKU辅助档口匹配 (#259)
• b685d2c fix: 追加原始SKU字段兼容迁移 (#259)