cmautobuy/docs/task/231-档口入库码单表导入.md

# 231 Admin：档口入库码单表迁移与 Excel 幂等导入

- 类型：需求
- 父级大工单：#14
- 所属 MVP / 版本：#224
- 状态：已完成
- 日期：2026-08-15
- Gitea 工单：<http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/231>

## 背景与目标

把线下档口 Excel 从一次性载体转换为 Admin 可追踪的业务记录，为后续确定性匹配和安全
回写提供数据基础，同时保持用户确认的“一张业务表”边界。

## 最终方案

- MySQL schema v23 只增加 `syb_inner_code_records`，保存导入原字段、匹配快照、回写状态
  和操作账号，不增加批次表、尝试表，也不保存 Excel 原文件或哈希。
- Excel 固定读取“标签入库码映射”，在前 10 行定位表头，兼容组合或拆分的档口字段和两种
  规格表头。单次限制 10MB、5000 行，并校验字段长度和同日入库码唯一性。
- 业务键为日期、订单号、档口及货号、标准化规格。重复业务组压成一行并记录重复数量，
  供后续匹配整组跳过；重复导入不覆盖已经回写或需要核对的审计状态。
- 当前生产基线固定 MySQL 8.4，因此没有扩展历史 SQLite 运行时 schema。

## 改了哪些

- `admin/repository/mysql_db.go`：追加 v23 可重放迁移和结构自检。
- `admin/model/inner_code.go`：增加单表状态、记录和导入模型。
- `admin/repository/inner_code.go`：增加事务内按业务键锁定的幂等写入。
- `admin/service/inner_code_import.go`：增加上传校验、Excel 解析、规格标准化和事务编排。
- `admin/service/inner_code_import_test.go`：覆盖规格清洗、表头、重复和冲突。
- `docs/admin/03-data-model.md`：记录 v23 单表约束和状态。

## 验收结果

| 验收标准 | 结果 |
|---|---|
| v23 迁移可重放并在自检成功后记录版本 | 通过（代码与全量测试）；真实 MySQL 见未验证项 |
| 合法 Excel 幂等写入且重复业务键不新增第二行 | 通过 |
| 已完成/需核对记录重复导入不丢失远端审计状态 | 通过（SQL 条件更新） |
| 文件类型、大小、行数、必填字段和长度错误可读 | 通过 |
| 覆盖规格标准化、重复键和同日入库码冲突 | 通过 |

## 测试

- 执行的命令：`go test ./service ./repository -run InnerCode -count=1`；
  `go test ./... -count=1`；`go vet ./...`
- 结果：全部通过。
- **没验证到的部分**：本机没有另行提供以 `_test` 结尾的 MySQL 8.4 隔离测试库，未执行
  v22 真实库升级和重复迁移；没有使用含商业数据的原始 Excel，只使用代码生成的脱敏工作簿。

## 相关提交

- `5a9c0f0` feat: 增加档口入库码单表导入 (#231)
- `c0eb957` fix: 明确拦截档口入库码唯一冲突 (#231)