From edb835a9edb4cf17215fb935edcb6ff177fafaf1 Mon Sep 17 00:00:00 2001
From: chengma <chengma2027@gmail.com>
Date: Tue, 11 Aug 2026 11:27:14 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=E4=BB=BB=E5=8A=A1=20?=
 =?UTF-8?q?#144?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/task/144-修复商品目录迁移.md | 54 +++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 docs/task/144-修复商品目录迁移.md

diff --git a/docs/task/144-修复商品目录迁移.md b/docs/task/144-修复商品目录迁移.md
new file mode 100644
index 0000000..8c72195
--- /dev/null
+++ b/docs/task/144-修复商品目录迁移.md
@@ -0,0 +1,54 @@
+# 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
+修复逻辑：逐项检查并补齐 SKU 身份、规格键、字段来源列、导入统计列和唯一索引，
+回填语句只处理空值。随后同时执行 v8、v9 结构自检，全部通过后才记录 v10。
+
+新增两个真实 MySQL 集成场景：一是构造“已记录 v9、缺少两个来源字段”的异常状态，
+核对自动修复、业务字段保持和版本幂等；二是模拟 v10 DDL 已提交但版本尚未记录的
+中断状态，核对重启后继续收敛。实现与建单方案一致。
+
+## 改了哪些
+
+- `admin/repository/mysql_db.go`：schema 版本提升到 v10，增加兼容修复和完整形状自检。
+- `admin/repository/mysql_db_integration_test.go`：增加异常 v9 修复和 v10 中断重跑用例。
+- `docs/admin/03-data-model.md`：记录 v10 的用途、数据边界和版本记录规则。
+- `docs/admin/10-商品目录接入接口.md`：补充 v10 发布、修复与回退说明。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 已记录 v8/v9 但缺少来源字段时执行 v10 自动补齐 | 通过（集成用例已覆盖） |
+| 保留真实 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` 修复不完整的商品目录迁移