docs: 归档任务 #259

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

@@ -0,0 +1,52 @@
+# 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)`。
+- 导入器兼容“原始SKU”“原始sku”“原始 SKU”和带来源说明的表头。数据库保留单元格原文，比较时只去除两端空白。
+- 重复导入补充原始 SKU；已回写、回写中或需核对记录仍保留原状态和远端审计。
+- 先执行订单、采购字段和规格门禁，再把原始 SKU 与候选 `sku/variationSku` 完全相等比较。唯一命中时允许覆盖分隔符不同造成的档口零命中。
+- 原始 SKU 重复命中、档口证据重复，或两项证据唯一指向不同候选时停止自动选择。原始 SKU 缺失或零命中继续使用原档口规则。
+- 没有增加去 `#`、包含匹配、短货号或 AI 猜测。
+
+## 改了哪些
+
+- `admin/repository/mysql_db.go`：增加 MySQL v28 迁移和字段结构自检。
+- `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 可重放迁移及结构自检 | 通过 |
+| 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 执行 v28；未登录生产顺运宝重新规划目标订单，也未执行任何远端回写。
+
+## 相关提交
+
+- `4383bb8` fix: 使用原始SKU辅助档口匹配 (#259)