diff --git a/docs/task/152-蝦皮规格确定性正式化.md b/docs/task/152-蝦皮规格确定性正式化.md new file mode 100644 index 0000000..05c137e --- /dev/null +++ b/docs/task/152-蝦皮规格确定性正式化.md @@ -0,0 +1,76 @@ +# 152 将确定的蝦皮非正式规格转换为正式规格 + +- 类型:数据修复 +- 父级大工单:#14 +- 所属 MVP / 版本:#15 / 商品目录数据接入后续 +- 状态:已完成,待用户验收 +- 日期:2026-08-11 +- Gitea 工单: + +## 背景与目标 + +#146 已将三个 Excel 的 2075 个蝦皮商品、33049 条规格导入生产库。源文件没有 +颜色和尺码的维度名称,因此当时只保留 `spec_raw`,全部规格显示为“待补”。 + +本任务只把能够确定维度的规格转换为正式规格,无法确定的商品继续待补,不为追求 +全量转换而猜测数据。 + +## 最终方案 + +在原导入工具中增加独立的 `--formalize-specs` 模式,普通原始导入行为保持不变。 +转换按商品整体判断两列:整列取值都具有明确尺码证据,且另一列没有尺码冲突时, +才确定尺码列;单维规格只有全部取值能够明确识别为尺码或颜色时才转换。同商品列数 +不一致、证据冲突或不足时,整个商品保持待补。 + +正式化请求只包含确定的 SKU,强制使用 `fill_missing`,不重复提交商品、PDD 商品或 +关联,不修改 `spec_raw`、`spec_key` 和真实 SKU ID。请求使用独立的 +`xlsx-spec-v1` 幂等批次版本。 + +原计划使用独立 MySQL `_test` 库演练。生产账号没有创建测试库权限,测试库未创建; +经工单记录后改用已有目录接口回归、真实 Excel dry-run、生产只读基线、完整备份、 +逐批事务和执行后不变量核对作为替代门禁。本任务不涉及数据库结构迁移。 + +## 改了哪些 + +- `tools/import_catalog_xlsx.py`:增加商品级确定性判断、正式化模式、预检统计和独立批次。 +- `tools/test_import_catalog_xlsx.py`:覆盖正向、反向、单维、歧义、冲突和幂等行为。 +- `docs/admin/10-商品目录接入接口.md`:增加正式化预检、执行和核对说明。 +- 生产 MySQL `shopee_skus`:通过目录接口补齐 31178 条确定规格的颜色/尺码。 +- 仓库外生产备份: + `D:\chengma\cmautobuy_private_backups\autobuy-before-152-20260811T143430.sql.gz`。 + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| 真实 Excel 预检稳定得到 2075 个商品、33049 条 SKU | 通过 | +| 只转换确定规格,歧义数据继续待补 | 通过;正式 31178,待补 1871 | +| 同一商品统一映射,列数不一致和证据冲突不转换 | 通过 | +| `spec_raw/spec_key` 和 SKU 总数保持不变 | 通过;身份 XOR/SUM 与执行前一致 | +| 不伪造真实 SKU ID,不提交商品、PDD 商品和关联 | 通过 | +| 只补空字段,人工字段不覆盖 | 通过;created 0、manual skipped 0 | +| 11 个生产批次幂等提交成功 | 通过;11 succeeded、0 failed、0 processing | +| 生产备份存在且可读取 | 通过;gzip 完整读取和 SHA-256 校验通过 | +| 凭据和商业规格明细未进入 Git、工单或归档 | 通过 | + +## 测试 + +- 执行的命令:`python -m py_compile tools/import_catalog_xlsx.py`。 +- 结果:通过。 +- 执行的命令:`python -m unittest tools.test_import_catalog_xlsx`。 +- 结果:11 项测试通过。 +- 执行的命令:`python tools/import_catalog_xlsx.py --formalize-specs --dry-run`。 +- 结果:可正式化 1920 个商品、31178 条 SKU;155 个商品、1871 条 SKU 保持待补; + 共生成 11 个批次,未发送请求。 +- 执行的命令:在 `admin/` 使用固定 Go 1.23 执行 `go build ./...`、 + `go test ./... -count=1`、`go vet ./...`。 +- 结果:全部通过。 +- 执行的操作:生产只读基线、mysqldump 备份、11 批 HTTPS 提交和 MySQL 前后核对。 +- 结果:SKU 总数 33049;正式 31178、待补 1871、人工 0;规格身份 XOR + `1848061991`、SUM `70664155756801` 与执行前一致;商品总数仍为 5451。 +- **没验证到的部分**:生产账号无创建 `_test` 库权限,未执行独立 MySQL 8.4 + `_test` 演练;未逐行人工检查全部 31178 条正式规格;未执行备份恢复演练。 + +## 相关提交 + +- `30bdab3` 确定性转换蝦皮待补规格