---
name: product
description: Product catalog management for e-commerce stores. Create and update products, manage variants/SKUs, upload product images, organize tags. Use when user needs to add new products, update pricing, upload photos, or organize product catalog. NOTE - For inventory/stock management, use the inventory skill instead.
---

# Commerce CLI - Product Management

商品管理模块，用于电商商品目录的创建、编辑和组织。

## 典型场景

### 场景1：单个商品上架
**流程**: 准备素材 → 上传图片 → 创建商品 → 验证
```bash
# 1. 上传商品图片
commerce upload image --path ./tshirt-main.jpg  # 获得 media_123

# 2. 创建商品
commerce product create \
  --name "纯棉T恤" \
  --price 99 \
  --stock 20 \
  --description "100% 纯棉，舒适透气" \
  --media-id media_123
```

### 场景2：多规格商品上架
**流程**: 创建主商品 → 创建所有变体 → 关联图片（共享+变体专属）
```bash
# 1. 创建主商品
commerce product create --name "T恤" --price 99
# 获得 product_id: prod_123

# 2. 创建所有变体
commerce variant create --product-id prod_123 --sku "TSHIRT-RED-S" \
  --attributes '{"颜色":"红色","尺寸":"S"}' --price 99 --stock 50
# 获得 variant_id: var_red_s
commerce variant create --product-id prod_123 --sku "TSHIRT-BLUE-S" \
  --attributes '{"颜色":"蓝色","尺寸":"S"}' --price 99 --stock 50
# 获得 variant_id: var_blue_s

# 3. 关联共享图片（所有变体都能看到）
commerce product add-images --id prod_123 --media-id media_front,media_back

# 4. 关联变体专属图片（选择该变体时显示）
commerce variant add-images --product-id prod_123 --variant-id var_red_s --url "https://cdn.../red.jpg"
commerce variant add-images --product-id prod_123 --variant-id var_blue_s --url "https://cdn.../blue.jpg"
# 也可以用已有 media_id：--media-id media_red
```

### 场景3：批量商品导入
**流程**: 先上传共享资源 → 循环创建商品
```bash
# 1. 上传品牌logo（所有商品共享）
commerce upload image --path ./brand-logo.jpg  # 获得 media_shared

# 2. 批量创建商品（复用media_id）
for product in "T恤" "衬衫" "卫衣"; do
  commerce product create --name "$product" --price 99 --media-id media_shared
done
```

### 场景4：促销活动准备
**任务**: 批量更新价格和标签
```bash
# 1. 查找目标商品
commerce product list --query "T恤" --limit 50

# 2. 批量更新价格和促销标签（设置原价显示折扣）
commerce product update --id prod_123 --price 79 --original-price 99 --tags "featured,sale"
commerce product update --id prod_456 --price 79 --original-price 99 --tags "featured,sale"
```

### 场景5：商品图片更新
**任务**: 更换主图或添加详情图
```bash
# 1. 上传新图片
commerce upload image --path ./new-photo.jpg  # 获得 media_new

# 2. 添加到商品
commerce product add-images --id prod_123 --media-id media_new
```

### 场景6：创建促销商品
**任务**: 创建带折扣显示的商品（显示划线价）
```bash
# 创建促销商品：售价79，原价99（显示划线价）
commerce product create \
  --name "夏日特惠T恤" \
  --price 79 \
  --original-price 99 \
  --stock 100 \
  --tags "sale"
```

### 场景决策表

| 用户需求 | 推荐命令 | 关键注意点 |
|---------|---------|-----------|
| 单个商品 | `product create` | 先上传图片，准备好所有必填字段 |
| 多规格商品 | `product create` + `variant create` | 主商品设置基础价格，变体设置差异价 |
| 批量上架 | 脚本循环 `product create` | 复用共享图片的media_id，避免重复上传 |
| 更新价格 | `product update --price` | 如有变体，需逐个更新变体价格 |
| 促销商品 | `product create --original-price` | `--original-price` 必须大于 `--price` |
| 促销标签 | `product update --tags` | 用逗号分隔，保留原有标签 |
| 图片更新 | `upload` + `add-images` | 先上传再关联，不要直接删除旧图 |
| 删除商品 | `product delete` | **软删除**，商品状态变为 archived |
| 下架商品 | `product update --status inactive` | 暂时隐藏，可随时恢复 |

## 商品状态说明（重要）

| 状态 | 含义 | 用户可能说 |
|------|------|-----------|
| `active` | 正常上架，买家可见 | "上架"、"发布" |
| `inactive` | 暂时下架，买家不可见 | "下架"、"隐藏" |
| `draft` | 草稿，未发布 | "草稿"、"暂存" |
| `archived` | **已删除（软删除）**，数据保留 | "删除"、"移除" |

**`product delete` = 软删除**：删除商品会将状态设为 `archived`，数据保留但不再显示。

**已归档商品不需要再删除**：如果商品状态已经是 `archived`，告诉用户"商品已删除"。

## 卓越标准

### 商品质量维度
- **图片质量**: 至少3张不同角度，主图尺寸 ≥ 1200x1200px
- **描述完整性**: 必填字段100%填写，描述文字 ≥ 50字
- **SEO优化**: 标题包含核心关键词，使用3-5个相关标签
- **变体规范**: 使用统一的attributes key（如"颜色"、"尺寸"），避免同义词混用
- **库存准确**: 创建时设置真实库存，避免超卖和缺货

### 上架流程原则
- **图片先行**: 先批量上传所有图片获取media_id，再创建商品（避免重复上传）
- **主商品后变体**: 先创建主商品获取product_id，再创建所有变体
- **数据完整性**: 每个变体必须有独立SKU、库存、价格
- **标签策略**: 精选(featured)、新品(new)、促销(sale)等核心标签要及时更新

### 质量检查清单
- [ ] 商品标题简洁有力，包含关键词
- [ ] 描述文字 ≥ 50字，突出卖点
- [ ] 至少3张图片，主图清晰
- [ ] 价格和库存准确无误
- [ ] 变体SKU不重复
- [ ] 标签使用合理（3-5个）

## 常见问题

### ❌ 问题1：重复上传图片
**错误做法**：
```bash
# 每个商品都上传相同的logo
for product in products; do
  commerce upload image --path ./logo.jpg
  commerce product create --name "$product" --media-id $NEW_ID
done
```

**正确做法**：
```bash
# 先上传一次，复用media_id
commerce upload image --path ./logo.jpg  # 获得 media_123
for product in products; do
  commerce product create --name "$product" --media-id media_123
done
```

### ❌ 问题2：忘记创建变体
**症状**: 多规格商品只有主商品，无法选择颜色/尺寸
**解决**: 创建主商品后，立即创建所有变体

```bash
# 错误：只创建主商品
commerce product create --name "T恤" --price 99

# 正确：创建主商品 + 所有变体
commerce product create --name "T恤" --price 99  # 获得 prod_123
commerce variant create --product-id prod_123 --sku "TSHIRT-RED-S" ...
commerce variant create --product-id prod_123 --sku "TSHIRT-RED-M" ...
```

### ❌ 问题3：变体attributes不一致
**症状**: 规格筛选混乱，如"颜色"、"color"、"Color"混用
**解决**: 统一使用中文或英文，全局保持一致

```bash
# 错误：同义词混用
--attributes '{"颜色":"红色"}'
--attributes '{"color":"蓝色"}'

# 正确：统一使用
--attributes '{"颜色":"红色"}'
--attributes '{"颜色":"蓝色"}'
```

### ❌ 问题4：批量更新时覆盖标签
**症状**: 更新标签时把原有标签清空
**解决**: 先查看原有标签，追加新标签

```bash
# 错误：直接覆盖
commerce product update --id prod_123 --tags "sale"  # featured标签丢失

# 正确：先查看再追加
commerce product get --id prod_123  # 查看原有标签: featured,new
commerce product update --id prod_123 --tags "featured,new,sale"
```

### ❌ 问题5：库存设置不准确
**症状**: 超卖或缺货
**解决**: 创建时设置真实库存，定期同步ERP数据

```bash
# 先确认真实库存，再创建
commerce product create --name "T恤" --price 99 --stock 50  # 确保真实有50件
```

## 命令参考

### 自然语言映射

当用户说：
- "创建XX商品，价格YY" → `commerce product create --name XX --price YY`
- "创建XX商品，售价YY，原价ZZ" → `commerce product create --name XX --price YY --original-price ZZ`
- "创建促销商品，价格79，划线价99" → `commerce product create --name XX --price 79 --original-price 99`
- "上传商品图片" → `commerce upload image --path ./photo.jpg`
- "添加商品变体" → `commerce variant create --product-id XX --sku YY`
- "给变体加图片" / "变体图片" / "变体显示图片" → `commerce variant add-images --product-id XX --variant-id YY --url/--media-id`
- "把已有图片指定给变体" → `commerce variant add-images --product-id XX --variant-id YY --media-id ZZ`
- "更新商品价格" → `commerce product update --id XX --price YY`
- "设置商品原价/划线价" → `commerce product update --id XX --original-price YY`
- "给商品打标签" → `commerce product update --id XX --tags "featured,new"`
- "设置商品重量和尺寸" → `commerce product update --id XX --weight 0.5 --length 10 --width 8 --height 5`
- "库存设置为 N" → `commerce inventory set --id XX --quantity N`（加载 inventory skill）
- "查看所有商品" → `commerce product list`

### 核心功能

**商品 CRUD**:
- `commerce product create` - 创建商品
- `commerce product list` - 查看商品列表
- `commerce product get` - 查看商品详情
- `commerce product update` - 更新商品信息
- `commerce product delete` - 删除商品

**变体/SKU 管理**:
- `commerce variant create` - 创建商品变体
- `commerce variant list` - 查看变体列表
- `commerce variant update` - 更新变体信息
- `commerce variant delete` - 删除变体
- `commerce variant add-images` - 给变体关联图片（支持 URL/本地文件/media_id）

**图片管理**:
- `commerce upload image` - 上传图片
- `commerce product add-images` - 关联图片到商品（所有变体共享）
- `commerce product remove-images` - 移除商品图片
- `commerce variant add-images` - 关联图片到特定变体（变体专属）

## 详细示例

### 示例1：创建单个商品
```bash
# 用户说："创建T恤商品，99美元，库存20"
# 描述支持 Markdown 格式
commerce product create \
  --name "T恤" \
  --price 99 \
  --stock 20 \
  --description "## 产品特点

- **材质**：100% 纯棉
- **特性**：透气舒适，不易起球
- **适合人群**：日常休闲、运动

> 机洗建议：30°C 以下冷水洗涤"
```

### 示例2：上传商品图片
```bash
# 用户说："上传商品主图"
commerce upload image --path ./tshirt-main.jpg
# 返回: { media_id: "media_123" }

# 关联到商品
commerce product add-images \
  --id prod_123 \
  --media-id media_123
```

### 示例3：创建商品变体
```bash
# 用户说："给商品添加红色S码的变体"
commerce variant create \
  --product-id prod_123 \
  --sku "TSHIRT-RED-S" \
  --price 99 \
  --stock 50 \
  --attributes '{"颜色":"红色","尺寸":"S"}'
```

### 示例4：管理商品标签
```bash
# 用户说："把商品标记为精选和新品"
commerce product update \
  --id prod_123 \
  --tags "featured,new"

# 查看带特定标签的商品
commerce product list --tags "featured"
```

### 示例5：批量更新价格
```bash
# 用户说："把所有T恤价格改成89"
# 1. 先查找T恤商品
commerce product list --query "T恤"

# 2. 逐个更新
commerce product update --id prod_123 --price 89
commerce product update --id prod_456 --price 89
```

### 示例6：完整的多规格商品上架
```bash
# 完整流程演示
# 1. 上传图片
commerce upload image --path ./tshirt-red.jpg    # media_red
commerce upload image --path ./tshirt-blue.jpg   # media_blue

# 2. 创建主商品
commerce product create --name "纯棉T恤" --price 99
# 获得 product_id: prod_123

# 3. 创建变体
commerce variant create --product-id prod_123 --sku "TSHIRT-RED-S" \
  --attributes '{"颜色":"红色","尺寸":"S"}' --price 99 --stock 50

commerce variant create --product-id prod_123 --sku "TSHIRT-RED-M" \
  --attributes '{"颜色":"红色","尺寸":"M"}' --price 99 --stock 30

commerce variant create --product-id prod_123 --sku "TSHIRT-BLUE-S" \
  --attributes '{"颜色":"蓝色","尺寸":"S"}' --price 99 --stock 40

# 4. 关联图片
commerce product add-images --id prod_123 --media-id media_red,media_blue

# 5. 验证
commerce product get --id prod_123
```

### 物流属性引导（物理产品）

创建 `requires_shipping: true` 的物理产品时：

1. **重量**：引导卖家填写准确重量（影响所有物流报价准确性）
2. **cargo_type**：根据产品标题/描述自动推断（默认 general），向卖家确认
   - 推断方式："根据产品信息，我推断这是普通商品，对吗？"（不要直接问"含电池吗？"）
   - 可选值：general（普货）、battery（带电）、liquid（液体）、cosmetic（化妆品）、clothing（服装）、powder（粉末）、wood（木制品）
   - 这是通用物流属性，不需要提及任何具体物流商
3. **brand**：引导填写品牌（可选，用于物流限制检查）
4. 用户可跳过，但告知"会影响物流方案选择和报价准确性"
5. 数字产品跳过整个物流属性流程

## 重要提示

- **国际化策略** - 平台默认语言是英文（en-US）。当用户同时提供中英文内容时，用英文创建商品，中文通过 `i18n` skill 添加翻译。当用户要求"国际化"时，确保英文在主表，其他语言通过 i18n 添加。详见 i18n skill。
- **库存管理统一使用 inventory skill** - 设置目标值用 `inventory set --id XX --quantity N`，增减库存用 `inventory adjust --id XX --quantity N`。**有变体的产品不能直接设置主产品库存**（会被拒绝），必须逐个设置变体的库存。
- **商品描述支持 Markdown 格式**，可以使用标题、列表、加粗、链接等排版
- 所有命令默认 JSON 输出，便于 AI 解析
- 图片需要先上传获取 `media_id`，再关联到商品
- 变体的 `attributes` 使用 JSON 格式
- 标签使用逗号分隔的字符串
- 支持的图片格式：JPG, PNG, WebP（最大 10MB）
- 使用 `--help` 查看命令详细参数
- 删除商品会同时删除所有变体和图片关联
- 价格单位默认为美元（USD），可通过后台配置修改
- **重量单位：kg**（如 0.5 表示 500g）
- **尺寸单位：cm**（length/width/height）
- 集合 slug 必须唯一，用于 URL，使用英文和连字符
- 集合封面支持三种方式：`--media-id`（推荐）、`--url`、`--path`
