## 亚马逊格式数据 → 店匠（Shoplazza）商品导入模板：转换说明

本仓库支持把 `data/mai_jia_jing_ling/products_data/*.xlsx`（**亚马逊格式导出**）转换为店匠后台可导入的 `docs/商品导入模板.xlsx` 格式。

对应脚本：
- **主入口**：`scripts/amazon_xlsx_to_shoplazza_xlsx.py`
- **历史兼容**：`scripts/competitor_xlsx_to_shoplazza_xlsx.py`（仅名称过时，逻辑一致）
- **模板写入复用工具**：`scripts/shoplazza_excel_template.py`

---

## 一、输入数据（亚马逊格式 xlsx）的关键字段

以 `Competitor-US-Last-30-days-363464.xlsx` 为例（文件名不影响：内容是亚马逊维度字段）：

- **ASIN**：变体 id（我们视为 `sku_id`，会写入模板的 `商品SKU`）
- **父ASIN**：父商品 id（我们视为 `spu_id`/`product_id`，会写入模板的 `商品spu`，并用于分组 M/P）
- **商品标题**：商品标题（写入 `商品标题*`、SEO标题等）
- **SKU**：亚马逊变体描述字符串（关键：解析出多款式维度）
  - 示例：`Size: One Size | Color: Black`
- **商品主图**：图片 URL（用于 `商品图片*` / `商品主图`）
- **价格($)** / **prime价格($)**：价格（用于 `商品售价*` / `商品原价`）
- **详细参数**：详情参数串（用于拼接 `商品描述`）
- **上架时间**：用于 `创建时间`
- **类目路径/大类目/小类目/品牌/商品详情页链接/品牌链接**：用于专辑、标签、SEO、供应商URL、备注等
- **商品重量（单位换算）/商品重量/商品尺寸**：用于 `商品重量/重量单位/尺寸信息`

> 注意：该数据源通常**没有库存**，脚本默认给每个变体一个固定库存（当前默认 100），以满足导入后的可用性。

---

## 二、输出数据（店匠导入模板）的核心规则（M / P / S）

店匠模板在 `docs/商品导入模板说明.md` 中定义了三种商品属性（`商品属性*`）：

- **S（单一款式）**：一个商品只有一个变体（只有 1 个 ASIN）
  - 输出 **1 行**
- **M（主商品）+ P（子款式）**：一个父商品（父ASIN）包含多个变体（多个 ASIN）
  - 输出 **1 行 M + N 行 P**
  - 且 **同一商品的 P 行必须紧跟在 M 行后面**（模板导入强约束）

本仓库的转换策略：
- 对每个 `父ASIN` 分组：
  - **分组 size = 1** → 生成 `S`
  - **分组 size > 1** → 生成 `M` + 多个 `P`

---

## 三、多款式（变体）是如何构造的（最关键部分）

### 1）为什么 “SKU” 列是关键

亚马逊格式里，变体的“颜色/尺码”等信息往往并不拆成多个列，而是集中在 `SKU` 字符串里，例如：

- `Size: One Size | Color: Black`
- `Color: Red | Style: 2-Pack`

店匠模板的多款式需要：
- **M 行**：`款式1/款式2/款式3` 写“维度名”（例如 Size / Color / Material）
- **P 行**：`款式1/款式2/款式3` 写“维度值”（例如 One Size / Black / Cotton）

### 2）脚本如何从 SKU 解析出维度（key/value）

脚本会把 `SKU` 以 `|` 分割，再用 `:` 拆成 key/value：

- 输入：`Size: One Size | Color: Black`
- 解析结果：`{ "Size": "One Size", "Color": "Black" }`

### 3）如何从多个变体里选出 “最多3个维度”

店匠模板只提供 `款式1~3` 三个维度，因此脚本会在一个 `父ASIN` 组内统计 key 的出现频次，并按优先级挑选最多 3 个维度：

- 优先级大致为：`Size`、`Color`、`Style`、`Pattern`、`Material` ……
- 如果一个组里解析不到任何 key/value，则退化为单维度：`Variant`
  - M 行 `款式1 = Variant`
  - P 行 `款式1 = ASIN`

### 4）M 行与 P 行分别填什么（避免导入报错）

根据模板说明，脚本遵循以下分工：

- **M 行（主商品）**：
  - 填：标题/描述/SEO/专辑/标签/主图/款式维度名
  - 不填：价格、库存、重量等 SKU 级字段（保持为空更安全）
- **P 行（子款式）**：
  - 填：款式维度值、价格、商品SKU（ASIN）、库存、重量、尺寸、（可选）子款式图
  - 不填：描述/SEO/专辑/供应商等 SPU 级字段（保持为空）

---

## 四、字段映射总览（高频字段）

- **商品spu** ← `父ASIN`（无父ASIN则用 ASIN）
- **商品SKU** ← `ASIN`
- **商品标题\*** ← `商品标题`
- **商品图片\*** / **商品主图** ← `商品主图`
- **商品售价\*** ← `prime价格($)` 优先，否则 `价格($)`
- **创建时间** ← `上架时间`（仅日期时补齐为 `YYYY-MM-DD 00:00:00`）
- **商品描述** ← `商品标题` + `详细参数`（以 HTML 拼接）
- **专辑名称** ← `大类目`（无则取 `类目路径` 第一段）
- **标签** ← `品牌,大类目,小类目`
- **商品重量/重量单位** ← 优先解析 `商品重量（单位换算）`（如 `68.04 g`）
- **尺寸信息** ← 解析 `商品尺寸` 前三段数字（英寸）拼成 `L,W,H`

---

## 五、如何运行（生成导入文件）

### 1）先小批量验证（推荐）

```bash
python scripts/amazon_xlsx_to_shoplazza_xlsx.py \
  --input-dir data/mai_jia_jing_ling/products_data \
  --template docs/商品导入模板.xlsx \
  --output data/mai_jia_jing_ling/amazon_shoplazza_import_SAMPLE.xlsx \
  --max-files 1 --max-rows-per-file 2000 --max-products 50
```

### 性能提示（很重要）

- 旧实现如果用 `ws.cell()` 逐格读取/写入，处理 1 个 xlsx 就可能非常慢（分钟级甚至更久）。
- 当前脚本已经使用 **`iter_rows(values_only=True)`** 做快速读取，并默认启用 **fast writer**（写出时不逐格写模板）。
- 如需使用慢速的“按模板逐格写入”（不推荐），可加：`--no-fast-write`

### 2）生成全量

```bash
python scripts/amazon_xlsx_to_shoplazza_xlsx.py \
  --input-dir data/mai_jia_jing_ling/products_data \
  --template docs/商品导入模板.xlsx \
  --output data/mai_jia_jing_ling/amazon_shoplazza_import_ALL.xlsx
```

---

## 六、可扩展点（后续常见需求）

- **库存/上架/收税策略参数化**：目前是脚本默认值（Y/N/100），可按目标店铺规则改为命令行参数。
- **更强的多款式解析**：如果未来亚马逊格式 `SKU` 不规范，可补充从 `详细参数` 里挖出 `Color/Size`。
- **图片策略**：目前 P 行用各自 `商品主图`；也可改为 M 行合并多图（逗号拼接）。