# 亚马逊格式到店匠格式转换 - 核心工作内容分析

## 一、概述

本项目实现了从**亚马逊格式Excel数据**到**店匠（Shoplazza）商品导入模板**的格式转换，主要处理商品的多款式（变体）结构和属性字段映射。

**核心脚本**：`scripts/amazon_xlsx_to_shoplazza_xlsx.py`

---

## 二、父子款式处理（M/P/S 结构转换）

### 2.1 输入格式（亚马逊）

- **ASIN**：变体ID（SKU级别）
- **父ASIN**：父商品ID（SPU级别）
- 一个父ASIN可以包含多个ASIN（多个变体）

### 2.2 输出格式（店匠）

店匠模板定义了三种商品属性类型：

1. **S（单一款式）**：只有一个变体的商品
   - 输出：**1行**
   - 包含所有商品信息（标题、价格、库存等）

2. **M（主商品）+ P（子款式）**：包含多个变体的商品
   - 输出：**1行M + N行P**
   - **关键约束**：同一商品的P行必须紧跟在M行后面（模板导入强约束）

### 2.3 转换策略

```python
# 核心逻辑（简化版）
for 父ASIN in 所有父ASIN:
    variants = 获取该父ASIN下的所有ASIN
    
    if len(variants) == 1:
        生成 S 行（单一款式）
    else:
        生成 M 行（主商品）+ 多个 P 行（子款式）
```

### 2.4 关键处理点

#### 1. 父ASIN排序
- 确保父ASIN对应的变体在列表最前面
- 如果找不到父ASIN对应的变体，根据配置决定是否丢弃整个SPU

#### 2. 标题一致性检查
- 同一SPU下的所有变体标题必须一致
- 如果发现不一致：
  - 选项1：丢弃标题不一致的SKU（默认）
  - 选项2：修正为统一的主商品标题

#### 3. M行与P行的字段分工

**M行（主商品）填写**：
- ✅ 商品标题、描述、SEO信息
- ✅ 专辑、标签、供应商信息
- ✅ 商品主图
- ✅ 款式维度名（款式1/2/3的key）
- ❌ 不填：价格、库存、重量等SKU级字段（保持为空更安全）

**P行（子款式）填写**：
- ✅ 商品标题（与M行一致）
- ✅ 款式维度值（款式1/2/3的value）
- ✅ 价格、商品SKU（ASIN）、库存
- ✅ 重量、尺寸
- ✅ 子款式图（可选）
- ❌ 不填：描述、SEO、专辑等SPU级字段（保持为空）

---

## 三、属性字段处理（款式维度解析）

### 3.1 问题背景

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

```
示例1: "Size: One Size | Color: Black"
示例2: "Color: Red | Style: 2-Pack"
```

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

### 3.2 SKU解析逻辑

```python
def parse_sku_options(sku_text):
    """
    解析 SKU 列，提取 key:value 对
    输入: "Size: One Size | Color: Black"
    输出: {"Size": "One Size", "Color": "Black"}
    """
    # 1. 按 | 分割
    parts = sku_text.split("|")
    
    # 2. 按 : 拆成 key/value
    for part in parts:
        if ":" in part:
            key, value = part.split(":", 1)
            result[key.strip()] = value.strip()
    
    return result
```

### 3.3 维度选择策略（最多3个维度）

店匠模板只提供 `款式1~3` 三个维度，因此需要从多个变体中**智能选择最多3个维度**：

#### 优先级规则

1. **按预设优先级排序**：
   ```python
   PREFERRED_OPTION_KEYS = [
       "Size", "Color", "Style", "Pattern", "Material", 
       "Flavor", "Scent", "Pack", "Pack of", ...
   ]
   ```

2. **按出现频次排序**：统计每个key在所有变体中的出现次数

3. **综合排序**：
   ```python
   def key_sort(k):
       return (
           预设优先级（越小越优先）,
           -出现频次（越大越优先）,
           字母顺序（作为最后排序依据）
       )
   ```

#### 退化处理

如果解析不到任何 key/value，则退化为单维度：
- M行：`款式1 = "Variant"`
- P行：`款式1 = ASIN`（使用ASIN作为维度值）

### 3.4 维度映射示例

**输入数据**（3个变体）：
```
变体1: SKU = "Size: S | Color: Red"
变体2: SKU = "Size: M | Color: Red"  
变体3: SKU = "Size: S | Color: Blue"
```

**解析结果**：
- 维度统计：Size出现3次，Color出现3次
- 选择维度：Size（优先级1）、Color（优先级2）
- 最多3个，所以选择前2个

**输出格式**：
```
M行：
  款式1 = "Size"
  款式2 = "Color"
  款式3 = ""

P行1：
  款式1 = "S"
  款式2 = "Red"
  款式3 = ""

P行2：
  款式1 = "M"
  款式2 = "Red"
  款式3 = ""

P行3：
  款式1 = "S"
  款式2 = "Blue"
  款式3 = ""
```

---

## 四、字段映射总览

### 4.1 核心字段映射

| 店匠字段 | 亚马逊字段 | 处理逻辑 |
|---------|-----------|---------|
| **商品spu** | `父ASIN` | 无父ASIN则用ASIN |
| **商品SKU** | `ASIN` | 直接映射 |
| **商品标题*** | `商品标题` | 截断至255字符 |
| **商品图片*** | `商品主图` | URL直接映射 |
| **商品售价*** | `prime价格($)` 或 `价格($)` | 优先prime价格 |
| **创建时间** | `上架时间` | 日期格式转换（补齐时分秒） |
| **商品描述** | `商品标题` + `详细参数` | HTML拼接 |
| **专辑名称** | `大类目` | 无则取`类目路径`第一段 |
| **标签** | `品牌,大类目,小类目` | 逗号拼接 |
| **商品重量/重量单位** | `商品重量（单位换算）` | 解析数值和单位（g/kg/lb/oz） |
| **尺寸信息** | `商品尺寸` | 解析前三段数字，拼成 `L,W,H`（英寸） |

### 4.2 特殊字段处理

#### 1. 价格处理
```python
price = prime价格($) or 价格($) or 9.99  # 默认值9.99
```

#### 2. 库存处理
- 亚马逊数据源通常**没有库存**
- 脚本默认给每个变体固定库存：**100**

#### 3. 日期格式转换
```python
输入: "2018-05-09" 或 datetime对象
输出: "2018-05-09 00:00:00"  # 补齐时分秒
```

#### 4. 重量解析
```python
输入: "68.04 g" 或 "0.15 pounds"
输出: (68.04, "g") 或 (0.15, "lb")
```

#### 5. 尺寸解析
```python
输入: "7.9 x 7.9 x 2 inches"
输出: "7.9,7.9,2"  # L,W,H格式
```

#### 6. SEO URL Handle生成
```python
输入: "Legendary Whitetails Men's Buck Camp Flannel Shirt"
输出: "products/legendary-whitetails-mens-buck-camp-flannel-shirt"
# 规则：转小写、去特殊字符、空格转横线
```

---

## 五、重要工作内容总结

### 5.1 数据结构转换

1. **父子关系识别**：从扁平化的ASIN列表识别出SPU-SKU层级关系
2. **分组策略**：按父ASIN分组，决定生成S还是M+P结构
3. **行序保证**：确保同一SPU的M+P行连续，不被打断

### 5.2 属性字段解析

1. **SKU字符串解析**：从非结构化字符串中提取key:value对
2. **维度智能选择**：从多个可能的维度中选择最重要的3个
3. **优先级算法**：综合考虑预设优先级、出现频次、字母顺序

### 5.3 字段映射与转换

1. **格式转换**：日期、价格、重量、尺寸等格式标准化
2. **默认值填充**：库存、价格等缺失字段的默认值策略
3. **数据清洗**：标题截断、HTML转义、URL生成等

### 5.4 数据质量控制

1. **标题一致性检查**：确保同一SPU下所有变体标题一致
2. **父ASIN验证**：检查父ASIN是否存在于变体列表中
3. **错误处理**：提供配置选项决定是修正还是丢弃异常数据

### 5.5 性能优化

1. **批量处理**：支持多文件批量转换
2. **文件拆分**：按最大行数自动拆分输出文件（保证同一SPU不拆分）
3. **快速读写**：使用`iter_rows(values_only=True)`和write_only模式提升性能

---

## 六、关键技术难点

### 6.1 维度选择算法

**挑战**：从多个变体的SKU字符串中，智能选择最重要的3个维度

**解决方案**：
- 统计所有变体中每个key的出现频次
- 结合预设优先级列表（Size > Color > Style > ...）
- 综合排序选择前3个

### 6.2 数据一致性保证

**挑战**：确保同一SPU下的所有变体数据一致

**解决方案**：
- 标题一致性检查和修正
- 父ASIN排序保证
- M行和P行的字段分工明确

### 6.3 文件拆分策略

**挑战**：按最大行数拆分文件，但不能拆分同一SPU

**解决方案**：
- 先按SPU分组生成所有行
- 拆分时以SPU为单位，不拆分单个SPU的行

---

## 七、扩展点

### 7.1 可配置项

- 库存默认值（当前100）
- 价格默认值（当前9.99）
- 上架/收税/物流策略（当前硬编码Y/N）

### 7.2 可增强功能

- **更强的多款式解析**：如果SKU字段不规范，可从`详细参数`中提取Color/Size
- **图片策略优化**：P行可改为使用M行合并的多图（逗号拼接）
- **元字段支持**：支持店匠的元字段导入

---

## 八、使用示例

### 8.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-products 50
```

### 8.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
```

### 8.3 自动拆分文件

```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_SPLIT.xlsx \
  --max-rows-per-output 40000
```

---

## 九、总结

亚马逊格式到店匠格式的转换，核心工作包括：

1. **父子款式结构转换**：从ASIN/父ASIN关系转换为M/P/S结构
2. **属性字段解析**：从SKU字符串中提取并智能选择款式维度
3. **字段映射与转换**：40+个字段的格式转换和默认值处理
4. **数据质量控制**：一致性检查、错误处理、数据清洗
5. **性能优化**：批量处理、文件拆分、快速读写

这是一个典型的**数据格式转换ETL任务**，涉及数据结构重组、字符串解析、智能算法选择等多个技术领域。