cmautobuy/docs/task/144-修复商品目录迁移.md

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

• 类型：缺陷
• 父级大工单：#14
• 所属 MVP / 版本：#15 / 商品目录数据接入后续
• 状态：已完成
• 日期：2026-08-11
• Gitea 工单：#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 商品约束