docs: 归档任务 #152

docs/task/152-蝦皮规格确定性正式化.md

@@ -0,0 +1,76 @@
+# 152 将确定的蝦皮非正式规格转换为正式规格
+
+- 类型：数据修复
+- 父级大工单：#14
+- 所属 MVP / 版本：#15 / 商品目录数据接入后续
+- 状态：已完成，待用户验收
+- 日期：2026-08-11
+- Gitea 工单：<http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/152>
+
+## 背景与目标
+
+#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` 确定性转换蝦皮待补规格