辛泽批量上架专家skill
适用场景
用户有一个目录，里面每个子文件夹是一个商品（含商品图与可选的中文 info.txt），
要把它们批量上架到 Ozon 店铺。
不适用：单个商品的手工上架（用 Ozon 后台更快）、非 Ozon 平台、无图的纯数据导入。
§0 起手三步（不可跳过，缺一个就停）
第 1 步 · 索要批次目录
明确问用户："商品文件夹在哪个目录？"——不要猜，不要扫工作区。
第 2 步 · 确认 Ozon 密钥就绪
密钥从以下两处之一读取，你不许把密钥写进任何文件：
# 方式一：环境变量
export OZON_CLIENT_ID=xxx
export OZON_API_KEY=xxx
# 方式二：config 文件（放在工作区外或 .gitignore 里）
# {"client_id": "...", "api_key": "..."}
密钥没配好时，说明去哪拿：
Ozon 后台 → 设置 → API 集成 → Seller API → 创建密钥，角色必须选 Admin。
第 3 步 · 确认仓库 ID
python scripts/ozon_call.py --action warehouses
没有仓库 ID，库存设不进去 → 商品建了也不开卖。这是第一步就要拿到的东西，不要留到最后。
> 停下来问，而不是猜。 这三样缺任何一个，后面全是白工。
§1 商品文件夹约定
批次目录下，一个子文件夹 = 一个商品：
批次目录/
├── 军绿保温杯-480ml/
│ ├── 01-主图.jpg ← 文件名排序，01 即首图（primary_image）
│ ├── 02-材质细节.jpg
│ └── info.txt ← 可选，原始中文信息
└── 驼色粗针羊毛毛衣/
└── ...
- 以
_或.开头的目录会被跳过（给人工放杂物的口子） - 图片短边 < 600px 会被记告警（Ozon 可能拒收）
- 详细规范见
references/folder-convention.md
§2 标准作业流程（八步）
第 1 步 · 扫描
python scripts/scan_batch.py --mode scan --batch-dir "<批次目录>" --out scan.json
产出 scan.json。纯本地扫描，不联网。
第 2 步 · AI 补全（你的核心价值）
读 scan.json，为每个商品补齐，写成 enrich.json（格式见 samples/enrich.example.json）：
| 字段 | 来源 | 纪律 |
|---|---|---|
name 俄语标题 |
读 info.txt → 译成俄语电商习惯的标题 |
不堆砌关键词 |
cat_id / type_id |
调 --action tree 实时查 |
禁止凭记忆 |
brand |
无品牌填 Нет бренда |
别留空 |
price_ref |
查同类目均价 | 必须标来源 + 日期 + "仅参考" |
第 3 步 · 生成人工审核表
python scripts/scan_batch.py --mode build --scan-in scan.json \
--enrich enrich.json --out "上架表-<批次>-<日期>.xlsx"
生成后必须停下，交给用户填。 说清三句话：
- 共几行，黄底列是哪几列
- 填完把「填写状态」改成「已确认」
- 不想上架的行改成「跳过」
不许代填黄底列。这是三道闸门，不是流程装饰。
第 4 步 · 图片托管
python scripts/host_images.py --batch-dir "<批次目录>" --backend cos \
--bucket <bucket> --region <region> --out hosted.json
用户没有图床时，如实告知「商品卡会是无图状态」，不要用本地路径硬填。
第 5 步 · 校验与组包（三道闸门在这里执行）
python scripts/validate_build.py --xlsx "上架表.xlsx" --out payload.json \
--report "校验报告.md" --hosted hosted.json --warehouse-id <ID>
产出 payload.json（商品卡）+ stocks.json（库存）+ 校验报告.md。
把阻断行念给用户听：哪行、卡在第几道闸门、要补什么。
第 6 步 · 提交上架
# 先 dry-run 确认请求体
python scripts/ozon_call.py --action import --payload payload.json --dry-run
# 正式提交
python scripts/ozon_call.py --action import --payload payload.json --out task_ids.json
拿 task_id。超 100 个自动分批。
第 7 步 · 查结果并回写
等 1–2 分钟再查：
python scripts/ozon_call.py --action writeback --xlsx "上架表.xlsx" --task-id "<id>"
第 8 步 · 建卡成功后设库存（顺序不能反）
python scripts/ozon_call.py --action stocks --payload stocks.json
先建卡，再上量：库存不在 /v3/product/import 里 ——
没这一步，商品在 Ozon 上是「有卡无货」，买家看不到、也买不了。
§3 Excel 中介层
三个工作表：① 使用说明 / ② 上架清单 / ③ 上传结果。
23 列，六色分区。列定义以 scripts/_schema.py 为单一事实来源。
| 底色 | 区域 | 谁填 |
|---|---|---|
灰 #D9D9D9 |
系统锁定 | 系统（人不要改） |
浅蓝 #DAE9F8 |
AI 预填·请核对 | AI（人可改） |
黄 #FFE699 |
★必须人工填写★ | 人（AI 禁止代填） |
浅绿 #E2EFDA |
仅参考·不可作为依据 | AI |
浅黄 #FFF2CC |
人工确认 | 人（下拉） |
近白 #F2F2F2 |
系统回写 | 系统 |
详见 references/sheet-schema.md。
§4 三道闸门（硬约束）
| 闸门 | 判据 | 不过的后果 |
|---|---|---|
| 1 · 人工确认 | 填写状态 = 「已确认」 |
该行不上架 |
| 2 · 必填非空 | 售价/库存/重量/长/宽/高 六项齐全 | 该行不上架 |
| 3 · 数值合法 | 数字 + 合理区间 + 划线价高于售价 | 超区间阻断 / 划线价异常告警 |
外加一条隐性闸门（图片）：主图直链必须是 http(s)。
file:// 与本地路径会被 Ozon 静默忽略，商品变无图——所以校验脚本把它列为阻断，不是告警。
详见 references/three-gates.md。
§5 脚本清单
所有脚本在 scripts/ 下，用当前工作目录的相对路径调用：
| 脚本 | 作用 | 关键参数 |
|---|---|---|
_schema.py |
列定义（被 import，不直接运行） | — |
scan_batch.py |
扫描 / 生成 Excel | --mode scan\|build、--batch-dir、--scan-in、--enrich、--out |
host_images.py |
图片托管 | --batch-dir、--backend cos\|oss\|s3\|local、--bucket、--region、--out |
validate_build.py |
三道闸门 + 组包 | --xlsx、--out、--report、--hosted、--warehouse-id、--allow-no-image |
ozon_call.py |
全部 Ozon API | --action tree\|attrs\|dict\|warehouses\|import\|status\|stocks\|writeback、--dry-run |
make_samples.py |
造样例批次自测 | 无参数，直接运行 |
调用纪律：
- 一律先
--dry-run（ozon_call.py支持），确认请求体再真发 - 校验脚本每次都会回写
校验备注列到 Excel，这是给用户看的 --warehouse-id不传就不生成库存包，脚本会提示make_samples.py造样例时读同级的styles/目录（复用已生成的样图）；
该目录不存在时它报错退出，不会产出半成品。样例批次落到samples/，
可直接当成批次目录跑完整链路（自测用，不需要真实商品与密钥）
§6 失败处置
| 现象 | 处置 |
|---|---|
401 / 403 |
密钥错或角色不足 → 确认是 Admin 角色 |
429 |
脚本自动指数退避重试；反复则放慢批次 |
failed + code 含 ATTRIBUTE |
回查 attribute_id 的字典值 |
failed + code 含 PRICE |
检查价格是字符串、是否低于下限 |
| 商品建了但前台看不到 | 没设库存 → 走 --action stocks |
| 商品卡无图 | 直链不可公网访问，或用了 file:// |
| 类目报错 | 用了非叶子节点或 ID 过期 → 重查类目树 |
完整版见 references/failure-playbook.md。
§7 交付规范
每次交付必须说清：
- 批次概况：目录、商品数、图片数、扫描告警
- AI 补全了什么：俄语标题、类目、参考价（逐项标来源）
- 待人工填的清单：哪几列、共几项
- 校验结果：通过 / 阻断 / 跳过 各几行；阻断的逐行原因
- 上架结果：task_id、状态分布、失败逐条
- 下一步：要不要设库存 / 补图 / 重传
- 不确定性声明：哪步没验证、哪个依赖缺失
产物落点（统一约定）：所有中间产物与交付物落在 <批次目录>/_output/ 下 ——
_ 开头的目录在扫描时会被自动跳过，所以放在批次里也不会污染商品清单。
--out / --report / --stocks-out / --xlsx 都接受显式路径，不要用隐式相对路径，
否则多个批次会在同一个工作目录里互相覆盖（台账与 payload 分裂，出问题无法定位）。
禁止出现：密钥、未标来源的数据、"应该能过审"、替用户填的价格库存尺寸。
§8 禁止事项
- 禁止代填黄底六项（售价/库存/重量/长/宽/高）——哪怕用户说"你随便填个"
- 禁止凭记忆写类目 ID 与字典值 —— 必须调 API 查
- 禁止把密钥写进任何文件
- 禁止跳过人工填表直接上架
- 禁止用本地路径当图片直链
- 禁止把库存塞进
/v3/product/import—— 那个接口没有库存字段 - 禁止没查结果就说"已上架"
- 禁止越过
_schema.py自建列定义 —— 会与校验脚本脱钩
参考文件
references/folder-convention.md— 商品文件夹约定references/sheet-schema.md— Excel 23 列与颜色语义references/three-gates.md— 三道闸门完整定义references/ozon-endpoints.md— Ozon 端点与 payload 结构references/category-attributes.md— 类目与字典值规则references/image-hosting.md— 图片托管要求references/failure-playbook.md— 失败处置手册
