docs: 归档任务 #141

docs/task/141-商品目录无SKU与更新策略.md

@@ -0,0 +1,55 @@
+# 141 Admin：商品目录导入支持无 SKU ID 和分级更新策略
+
+- 类型：需求
+- 父级大工单：#14
+- 所属 MVP / 版本：#15 / 商品目录数据接入后续
+- 状态：已完成
+- 日期：2026-08-11
+- Gitea 工单：<http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/141>
+
+## 背景与目标
+
+部分来源没有真实蝦皮 SKU ID，旧接口和数据库无法导入；多个来源重复提交时也缺少安全的更新边界。本任务允许按商品和规格身份导入，并提供只新增、补空、同来源更新三种策略。
+
+## 最终方案
+
+- MySQL schema v8 保留历史 `sku_id` 作为内部主键，新增可空且唯一的 `shopee_sku_id` 作为真实外部 ID，并增加唯一 `(goods_id, spec_key)`。
+- 无真实 ID 时生成明确只供系统使用的内部主键；后续取得真实 ID 时回填原记录。
+- `update_policy` 支持 `insert_only`、默认 `fill_missing`、`overwrite_same_source`。
+- 用 `field_sources`、`field_observed_at` 分别记录颜色、尺码、建议和 SKU 编码的来源及时间；同来源策略只更新本来源拥有且时间不旧的字段。
+- `is_manual=1` 始终跳过，`spec_raw` 永不改写；同规格出现不同真实 ID 返回 409 并整批回滚。
+- 导入响应、查询接口和管理页面分别统计新增、补空、同来源更新、人工跳过和旧数据跳过。
+- SQLite 单向迁移在复制后补齐 v8 身份和字段来源，不改写冻结的历史 SQLite schema。
+
+## 改了哪些
+
+- `admin/repository/mysql_db.go`：追加 schema v8、回填、唯一约束、形状自检和可重放迁移。
+- `admin/repository/catalog_import.go`、`admin/service/catalog_import.go`：实现规格身份定位、三种策略、字段来源和结构化冲突。
+- `admin/repository/sqlite_to_mysql.go`：兼容历史 SQLite 数据迁入 v8。
+- `admin/handler/integration/catalog_api.go`、`admin/templates/catalog/`：输出并展示策略和分级统计。
+- `admin/repository/shopee.go`、`admin/model/`：区分内部记录主键与真实外部 SKU ID。
+- 对应 repository/service/handler/MySQL 集成测试及 Admin 接口、数据模型文档。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 无真实 SKU ID 可按商品和规格幂等导入 | 通过 |
+| 后补真实 ID 复用原内部记录 | 通过 |
+| 同规格不同真实 ID 返回 409，整批回滚 | 通过 |
+| 默认只补空，不覆盖非空、人工、关联或原文 | 通过 |
+| 只新增和同来源更新策略边界正确 | 通过 |
+| 不提供强制覆盖策略 | 通过 |
+| 响应和记录区分各类结果 | 通过 |
+| v8 首建、重放、升级、冲突形状测试 | 通过（测试代码）；真实 MySQL 环境未启用 |
+| Go 1.23 build/test/vet，Client 四接口不变 | 通过 |
+
+## 测试
+
+- 执行的命令：`$env:GOTOOLCHAIN='go1.23.0'; go build ./...; go test ./... -count=1; go vet ./...`
+- 结果：Admin 全部包通过；SQLite 目录服务测试覆盖三种策略、无 ID、补 ID、人工保护、旧时间、跨来源字段和事务回滚。
+- **没验证到的部分**：未配置 `CMAUTOBUY_MYSQL_TEST=1` 和独立 MySQL 8.4 `_test` 库，因此真实 MySQL 的首次迁移、中断重放和 v7→v8 集成测试本次跳过；上线前必须按工单要求演练并备份。
+
+## 相关提交
+
+- `4259be0` 支持无 SKU 目录导入策略