diff --git a/docs/task/280-第三方商品工作簿导出规范csv.md b/docs/task/280-第三方商品工作簿导出规范csv.md new file mode 100644 index 0000000..0bb0bbd --- /dev/null +++ b/docs/task/280-第三方商品工作簿导出规范csv.md @@ -0,0 +1,58 @@ +# 280 Admin:导出第三方商品工作簿为规范 CSV + +- 类型:需求 +- 父级大工单:#14 +- 所属 MVP / 版本:#15(商品目录接入后续批量数据准备) +- 状态:已完成,待验收 +- 日期:2026-08-20 +- Gitea 工单:http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/280 + +## 背景与目标 + +`D:\chengma\全部店铺拼多多商品` 中的第三方 ERP 工作簿含蝦皮商品、SKU、店铺、图片和 PDD 来源链接。工作表的 OOXML dimension 被错误写成 `A1`,常规依赖 dimension 的读取方式会漏掉实际数据。 + +本任务先把每个 XLSX 转成一份可供后续商品目录入库程序使用的 CSV,便于人工核对。此次没有调用商品目录接口,也没有写入任何 Admin 数据库。 + +## 最终方案 + +新增只读转换器,直接用 `zipfile + lxml.etree.iterparse` 流式读取 `xl/worksheets/sheet*.xml`,不使用错误的 dimension 元数据。每个来源 SKU 行导出为一行 UTF-8 BOM CSV;输出保留来源相对目录,因此一个 XLSX 对应一个同名 CSV。 + +CSV 包含蝦皮商品、蝦皮 SKU、店铺、图片、原始规格、仅依明确属性标题解析出的颜色/尺码、PDD 商品 ID/规范 URL、关联字段和来源审计字段。PDD URL 不能解析出数字 `goods_id` 时,仍保留蝦皮行,清空 PDD/关联字段并记录校验码。来源中的蝦皮价格和促销价没有写进任何 PDD 价格字段。 + +实际输出目录为 `D:\chengma\全部店铺拼多多商品规范CSV`,不在 Git 仓库内。 + +## 改了哪些 + +- `tools/export_thirdparty_catalog_xlsx.py`:实现第三方 XLSX 到规范 CSV 的流式转换命令。 +- `tools/requirements-thirdparty-catalog-export.txt`:固定转换脚本依赖 `lxml==6.1.1`。 +- `tools/test_export_thirdparty_catalog_xlsx.py`:覆盖错误 dimension、繁简体规格列、PDD URL 规范化、无效 PDD URL 和输出目录保护。 + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| 每个 XLSX 只生成一个同名 CSV,保留子目录 | 通过:20 个 XLSX 对应 20 个 CSV,无缺失和多余文件。 | +| 能读取 dimension 为 `A1` 的异常工作簿 | 通过:单元测试构造异常 dimension 工作簿;实际 20 文件也全部完成。 | +| CSV 包含蝦皮、SKU、PDD、关联和审计字段 | 通过:表头已逐文件一致性核对。 | +| PDD URL 可提取 `goods_id` 并规范化 | 通过:1,044,681 行生成规范 PDD URL。 | +| 无效 PDD URL 保留蝦皮数据并标注 | 通过:4,730 行为 `PDD_GOODS_ID_MISSING`,30 行为 `PDD_URL_HOST_INVALID`。 | +| 不把来源蝦皮价格写为 PDD 价格,不猜测规格 | 通过:CSV 不含 PDD 价格字段;规格只依据属性标题解析。 | +| 自动化测试覆盖关键转换规则 | 通过。 | + +## 测试 + +- 执行的命令: + + ```powershell + cd D:\chengma\cmautobuy + python -m unittest tools.test_export_thirdparty_catalog_xlsx -v + python -m py_compile tools\export_thirdparty_catalog_xlsx.py + python tools\export_thirdparty_catalog_xlsx.py "D:\chengma\全部店铺拼多多商品" --output-dir "D:\chengma\全部店铺拼多多商品规范CSV" + ``` + +- 结果:3 个自动化测试通过;实际转换 20 个工作簿共 1,049,441 行。二次读取 CSV 核对为 20 个输出、无缺失/多余文件、无临时文件。 +- **没验证到的部分**:没有调用商品目录接口,也没有导入数据库;后续接口导入任务需要单独核对 CSV 去重、批次大小和线上写入结果。 + +## 相关提交 + +- `71fabb1` feat: 导出第三方商品规范 CSV (#280)