feat: 增加商品目录 Excel 分批提交脚本 (#146)

docs/admin/10-商品目录接入接口.md

@@ -100,3 +100,49 @@ HTTP/HTTPS URL，最长 2048 字节；店铺名最长 500 个字符。Admin 只
 
 旧版 Admin 不理解无真实 SKU ID 的新记录。应用回退前应暂停目录接口并确认没有此类
 记录；不要删除 v8 列或把内部主键复制成伪造的外部 SKU ID。
+
+## 6. 三个已处理工作簿的分批导入脚本
+
+仓库根目录的 `tools/import_catalog_xlsx.py` 用于导入以下三个本地商业样本，文件本身
+不提交 Git：
+
+- `raw_data/shopee_chanpin_1_已处理.xlsx`
+- `raw_data/shopee_chanpin_2_已处理.xlsx`
+- `raw_data/shopee_chanpin_3_已处理.xlsx`
+
+脚本需要 Python 3.10+ 和 `openpyxl`。从仓库根目录安装固定依赖并先预检：
+
+```powershell
+python -m pip install -r tools/requirements-catalog-import.txt
+python tools/import_catalog_xlsx.py --dry-run
+```
+
+预检会读取全部行、校验固定字段和关联、生成批次并检查 500 商品、5000 SKU、5 MB
+三个接口限制，但不会读取 Token，也不会发送请求。当前三个样本的基准结果是 2075 个
+蝦皮商品、33049 条 SKU、11 个批次；样本变化后以脚本实际输出为准。
+
+真实提交前先备份生产数据库，然后在当前 PowerShell 窗口设置环境变量并运行：
+
+```powershell
+$env:CMAUTOBUY_CATALOG_BASE_URL = "https://buy.833729.com"
+$env:CMAUTOBUY_CATALOG_TOKEN = Read-Host "请输入商品目录专用 Token"
+python tools/import_catalog_xlsx.py
+Remove-Item Env:CMAUTOBUY_CATALOG_TOKEN
+```
+
+脚本默认使用 `fill_missing`，不会用空字段清除现有数据，也不会覆盖人工字段。文件没有
+真实蝦皮 SKU ID和可靠的颜色/尺码维度名称，因此脚本只按两个变种列的原顺序生成
+`spec_raw`，不猜测 `sku_id`、颜色或尺码；PDD 只提交确定存在的商品 ID、规范化 URL、
+店铺名及关联，不伪造 PDD 标题、价格或规格。
+
+每个批次 ID 由转换器版本、文件内容哈希、批量大小、更新策略和批次序号确定，
+`observed_at` 取批内 Excel 最大更新时间。因此同一文件和参数重新运行会提交完全相同的请求：已成功批次返回
+`replayed=true`，可用于断点续传。临时网络错误、429 和可重试 5xx 会指数退避；校验、
+鉴权或业务冲突会立即停止，不会跳过失败批次继续写后续数据。
+
+需要只导入指定文件时，把路径作为位置参数传入；要改变更新策略必须显式指定：
+
+```powershell
+python tools/import_catalog_xlsx.py raw_data/shopee_chanpin_3_已处理.xlsx
+python tools/import_catalog_xlsx.py --update-policy overwrite_same_source --dry-run
+```