# 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)