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

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

- 类型：缺陷
- 父级大工单：#14
- 所属 MVP / 版本：#224 / 档口入库码回写 MVP
- 状态：已完成
- 日期：2026-08-18
- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/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)