# 144 Admin：修复已记录 v8/v9 但 SKU 来源字段缺失的迁移

- 类型：缺陷
- 父级大工单：#14
- 所属 MVP / 版本：#15 / 商品目录数据接入后续
- 状态：已完成
- 日期：2026-08-11
- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/144

## 背景与目标

部分 MySQL 数据库曾在 schema v8 开发中间状态提前记录 v8，之后又记录 v9，
但 `shopee_skus.field_sources`、`field_observed_at` 并未真正建立。新代码按版本号
跳过 v8 后，最终自检报字段缺失，Admin 无法启动。本任务让这类数据库自动收敛，
同时保留现有业务数据和历史迁移记录。

## 最终方案

追加 MySQL schema v10，不修改已经发布的 v8/v9 版本记录。v10 重放现有的幂等 v8、
v9 修复逻辑：逐项检查并补齐 SKU 身份、规格键、字段来源列、导入统计列、商品图片/
店铺字段、约束和唯一索引，回填语句只处理空值。随后同时执行 v8、v9 结构自检，
全部通过后才记录 v10。首次实现只重放 v8，实际启动继续暴露 v9 人工标记约束缺失，
因此在不改变数据边界的前提下补充重放 v9。

新增两个真实 MySQL 集成场景：一是构造“已记录 v9、缺少两个来源字段和 v9 人工
标记约束”的异常状态，核对自动修复、业务字段保持和版本幂等；二是模拟 v10 DDL
已提交但版本尚未记录的中断状态，核对重启后继续收敛。

## 改了哪些

- `admin/repository/mysql_db.go`：schema 版本提升到 v10，重放 v8/v9 并增加完整形状自检。
- `admin/repository/mysql_db_integration_test.go`：增加异常 v9 修复和 v10 中断重跑用例。
- `docs/admin/03-data-model.md`：记录 v10 的用途、数据边界和版本记录规则。
- `docs/admin/10-商品目录接入接口.md`：补充 v10 发布、修复与回退说明。

## 验收结果

| 验收标准 | 结果 |
|---|---|
| 已记录 v8/v9 但缺少来源字段时执行 v10 自动补齐 | 通过（集成用例已覆盖） |
| 已记录 v9 但缺少图片/店铺人工标记约束时自动补齐 | 通过（集成用例已覆盖） |
| 保留真实 SKU ID、规格、颜色尺码、人工标志和商品关联 | 通过（集成用例逐字段核对） |
| 来源和观测时间只对空 JSON 安全回填 | 通过 |
| 完整 v8/v9 升级 v10 无业务副作用 | 通过（幂等重跑覆盖） |
| v10 中断后可收敛且版本只记录一次 | 通过（集成用例已覆盖） |
| 重复规格仍停止，不自动合并 | 通过（沿用并通过既有回归） |
| Go 1.23 build、test、vet 通过，Client 四接口不变 | 通过 |

## 测试

- 执行的命令：在 `admin/` 运行 `$env:GOTOOLCHAIN='go1.23.0'; go build ./...; go test ./... -count=1; go vet ./...`。
- 结果：全部通过；`git diff --check` 通过。
- **没验证到的部分**：当前环境未设置 `CMAUTOBUY_MYSQL_TEST=1` 且未提供专用 `_test` 数据库，新增的真实 MySQL 8 集成用例本次被安全跳过；未在生产数据库执行 v10，生产发布前仍需备份并在 `_test` 库演练。

## 相关提交

- `fef97cf` 修复不完整的商品目录迁移
- `9671202` 补齐不完整的 v9 商品约束