Admin：商品目录导入支持无 SKU ID 和分级更新策略 #141

New Issue

2026-08-11T10:33:32+08:00

ila commented

2026-08-11 10:33:32 +08:00

基本信息

类型：需求（Admin 接口 + MySQL 迁移）
父级大工单：#14
所属 MVP / 版本：#15 / 商品目录数据接入后续
阶段：目录导入兼容与覆盖策略
依赖：#132、#133、#134
状态：待验收

要解决什么

部分数据来源 Excel 没有真实蝦皮 SKU ID，但当前商品目录接口要求 sku_id 必填，数据库也把它当作 shopee_skus 主键，导致这些规格无法安全导入。不同来源重复导入时还需要明确“只新增、补空字段、同来源更新”的边界，不能用简单的“是否覆盖颜色尺码”布尔值批量洗掉人工修正或更可靠来源数据。

做什么 / 不做什么

做：保留真实蝦皮 SKU ID 字段但改为可空外部标识；增加系统内部规格主键和 spec_key；商品目录接口允许无 SKU ID；增加 insert_only、fill_missing、overwrite_same_source 三种更新策略，默认 fill_missing；记录字段来源/人工边界和导入统计。
不做：不删除已有真实 SKU ID；不伪造 SKU ID；不提供第三方脚本“强制覆盖全部”；不覆盖 is_manual=1 或人工修正字段；不允许旧 observed_at 覆盖新数据；不修改 PDD 关联和 Client 四接口。

怎么做

MySQL 只追加迁移：shopee_skus 增加内部主键所需结构、可空真实 shopee_sku_id、spec_key、来源/观测时间和人工修改保护字段；迁移既有记录时保留原 SKU ID，并生成稳定规格键。具体主键切换、外键和历史 sku_mappings 兼容必须先用真实 schema 自检，不能原地改写已发布迁移。
无 SKU ID 的规格按 goods_id + spec_key 查找；有真实 SKU ID 时优先按真实 ID 定位，并校验商品和规格身份一致。相同商品/规格出现多个不同真实 SKU ID 时返回冲突，不能自动合并。
update_policy 为批次级显式枚举：
- insert_only：仅新增，已有记录不修改；
- fill_missing：默认，只补当前为空且非人工保护的颜色、尺码、建议等字段；
- overwrite_same_source：仅同来源、更新的 observed_at 才能覆盖该来源拥有的字段。
spec_raw 永久保留；不同原文导致身份变化时返回结构化冲突或保留别名/历史，不直接洗掉旧原文。
导入记录增加策略及新增、补空、同来源更新、人工跳过、旧数据跳过、冲突计数；不保存完整请求体。
更新 docs/admin/10-商品目录接入接口.md JSON 契约、迁移/回滚说明及脱敏示例。
预计修改 catalog model/service/repository/API、MySQL 迁移、自检、导入记录页面与文档。

验收标准

没有真实 SKU ID 的规格可以通过 goods_id + spec_key 幂等新增和更新。
已有真实 SKU ID 完整保留；后续补到真实 ID 时复用原内部记录，不重复新建。
同商品同规格对应多个不同真实 SKU ID 时返回稳定 409，并整批回滚。
默认 fill_missing 只补空字段，不覆盖非空值、人工字段、PDD 关联或 spec_raw。
insert_only 不修改已有记录；overwrite_same_source 只接受同来源且更新的观测时间。
第三方脚本无法请求强制覆盖人工或跨来源数据。
导入响应和记录准确区分新增、补空、同来源更新、跳过和冲突。
MySQL 迁移首次执行、中断重放、上一版本升级、历史引用兼容和形状错误均有测试。
Go 1.23 build/test/vet 通过，Client 四接口保持不变。

怎么验证

固定 Go 1.23 全量 build/test/vet；httptest 覆盖三种策略、缺失 SKU ID、补真实 ID、人工保护、旧时间和冲突；MySQL 8.4 _test 验证迁移重放、唯一约束、历史映射引用和并发批次；用脱敏目录 JSON 做端到端导入。

风险和回退

规格主键和历史引用调整属于高风险数据库迁移，发布前必须备份并在 _test 完整演练。旧代码无法理解无 SKU ID 记录，因此代码与迁移必须同版本发布；回退应用前应确认新数据兼容，不能直接删除新增列或伪造旧 SKU ID。

## 基本信息 - 类型：需求（Admin 接口 + MySQL 迁移） - 父级大工单：#14 - 所属 MVP / 版本：#15 / 商品目录数据接入后续 - 阶段：目录导入兼容与覆盖策略 - 依赖：#132、#133、#134 - 状态：待验收 ## 要解决什么部分数据来源 Excel 没有真实蝦皮 SKU ID，但当前商品目录接口要求 `sku_id` 必填，数据库也把它当作 `shopee_skus` 主键，导致这些规格无法安全导入。不同来源重复导入时还需要明确“只新增、补空字段、同来源更新”的边界，不能用简单的“是否覆盖颜色尺码”布尔值批量洗掉人工修正或更可靠来源数据。 ## 做什么 / 不做什么 - 做：保留真实蝦皮 SKU ID 字段但改为可空外部标识；增加系统内部规格主键和 `spec_key`；商品目录接口允许无 SKU ID；增加 `insert_only`、`fill_missing`、`overwrite_same_source` 三种更新策略，默认 `fill_missing`；记录字段来源/人工边界和导入统计。 - 不做：不删除已有真实 SKU ID；不伪造 SKU ID；不提供第三方脚本“强制覆盖全部”；不覆盖 `is_manual=1` 或人工修正字段；不允许旧 `observed_at` 覆盖新数据；不修改 PDD 关联和 Client 四接口。 ## 怎么做 - MySQL 只追加迁移：`shopee_skus` 增加内部主键所需结构、可空真实 `shopee_sku_id`、`spec_key`、来源/观测时间和人工修改保护字段；迁移既有记录时保留原 SKU ID，并生成稳定规格键。具体主键切换、外键和历史 `sku_mappings` 兼容必须先用真实 schema 自检，不能原地改写已发布迁移。 - 无 SKU ID 的规格按 `goods_id + spec_key` 查找；有真实 SKU ID 时优先按真实 ID 定位，并校验商品和规格身份一致。相同商品/规格出现多个不同真实 SKU ID 时返回冲突，不能自动合并。 - `update_policy` 为批次级显式枚举： - `insert_only`：仅新增，已有记录不修改； - `fill_missing`：默认，只补当前为空且非人工保护的颜色、尺码、建议等字段； - `overwrite_same_source`：仅同来源、更新的 `observed_at` 才能覆盖该来源拥有的字段。 - `spec_raw` 永久保留；不同原文导致身份变化时返回结构化冲突或保留别名/历史，不直接洗掉旧原文。 - 导入记录增加策略及新增、补空、同来源更新、人工跳过、旧数据跳过、冲突计数；不保存完整请求体。 - 更新 `docs/admin/10-商品目录接入接口.md` JSON 契约、迁移/回滚说明及脱敏示例。 - 预计修改 catalog model/service/repository/API、MySQL 迁移、自检、导入记录页面与文档。 ## 验收标准 - [x] 没有真实 SKU ID 的规格可以通过 `goods_id + spec_key` 幂等新增和更新。 - [x] 已有真实 SKU ID 完整保留；后续补到真实 ID 时复用原内部记录，不重复新建。 - [x] 同商品同规格对应多个不同真实 SKU ID 时返回稳定 409，并整批回滚。 - [x] 默认 `fill_missing` 只补空字段，不覆盖非空值、人工字段、PDD 关联或 `spec_raw`。 - [x] `insert_only` 不修改已有记录；`overwrite_same_source` 只接受同来源且更新的观测时间。 - [x] 第三方脚本无法请求强制覆盖人工或跨来源数据。 - [x] 导入响应和记录准确区分新增、补空、同来源更新、跳过和冲突。 - [x] MySQL 迁移首次执行、中断重放、上一版本升级、历史引用兼容和形状错误均有测试。 - [x] Go 1.23 build/test/vet 通过，Client 四接口保持不变。 ## 怎么验证固定 Go 1.23 全量 build/test/vet；httptest 覆盖三种策略、缺失 SKU ID、补真实 ID、人工保护、旧时间和冲突；MySQL 8.4 `_test` 验证迁移重放、唯一约束、历史映射引用和并发批次；用脱敏目录 JSON 做端到端导入。 ## 风险和回退规格主键和历史引用调整属于高风险数据库迁移，发布前必须备份并在 `_test` 完整演练。旧代码无法理解无 SKU ID 记录，因此代码与迁移必须同版本发布；回退应用前应确认新数据兼容，不能直接删除新增列或伪造旧 SKU ID。

ila referenced this issue

2026-08-11 10:33:50 +08:00

[Epic] Admin 采集采购管理端 #14

ila referenced this issue

2026-08-11 10:33:52 +08:00

[MVP] Admin 四模块可用闭环 #15

ila referenced this issue

2026-08-11 10:40:03 +08:00

Admin：商品目录支持蝦皮图片和店铺信息并在列表展示 #142

ila commented

2026-08-11 11:04:03 +08:00

实施完成，等待验收

实现提交：4259be0
归档提交：2193430
归档：docs/task/141-商品目录无SKU与更新策略.md
验证：固定 Go 1.23 全量 build/test/vet 通过。
未验证：当前未启用独立 MySQL 8.4 _test 环境，受保护的真实迁移集成测试本次跳过；上线前须演练 v7→v8 并备份。

## 实施完成，等待验收 - 实现提交：`4259be0` - 归档提交：`2193430` - 归档：`docs/task/141-商品目录无SKU与更新策略.md` - 验证：固定 Go 1.23 全量 build/test/vet 通过。 - 未验证：当前未启用独立 MySQL 8.4 `_test` 环境，受保护的真实迁移集成测试本次跳过；上线前须演练 v7→v8 并备份。

ila referenced this issue

2026-08-11 11:23:19 +08:00

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

ila commented

2026-08-12 10:31:49 +08:00