77 lines
4.1 KiB
Markdown
77 lines
4.1 KiB
Markdown
# 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` 确定性转换蝦皮待补规格
|