@optima-chat/commerce-cli 1.3.0 → 1.4.0

package/.claude/skills/commerce-product/SKILL.md

@@ -5,11 +5,180 @@ description: Product catalog management for e-commerce stores. Create and update
 
 # Commerce CLI - Product Management
 
-## Overview
-
 商品管理模块，用于电商商品目录的创建、编辑和组织。
 
-## Instructions
+## 典型场景
+
+### 场景1：单个商品上架
+**流程**: 准备素材 → 上传图片 → 创建商品 → 验证
+```bash
+# 1. 上传商品图片
+commerce upload image --path ./tshirt-main.jpg  # 获得 media_123
+
+# 2. 创建商品
+commerce product create \
+  --title "纯棉T恤" \
+  --price 99 \
+  --stock 20 \
+  --description "100% 纯棉，舒适透气" \
+  --media-id media_123
+```
+
+### 场景2：多规格商品上架
+**流程**: 创建主商品 → 创建所有变体 → 关联图片
+```bash
+# 1. 创建主商品
+commerce product create --title "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
+commerce variant create --product-id prod_123 --sku "TSHIRT-RED-M" \
+  --attributes '{"颜色":"红色","尺寸":"M"}' --price 99 --stock 50
+commerce variant create --product-id prod_123 --sku "TSHIRT-BLUE-S" \
+  --attributes '{"颜色":"蓝色","尺寸":"S"}' --price 99 --stock 50
+```
+
+### 场景3：批量商品导入
+**流程**: 先上传共享资源 → 循环创建商品
+```bash
+# 1. 上传品牌logo（所有商品共享）
+commerce upload image --path ./brand-logo.jpg  # 获得 media_shared
+
+# 2. 批量创建商品（复用media_id）
+for product in "T恤" "衬衫" "卫衣"; do
+  commerce product create --title "$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 --tags "featured,sale"
+commerce product update --id prod_456 --price 79 --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
+```
+
+### 场景决策表
+
+| 用户需求 | 推荐命令 | 关键注意点 |
+|---------|---------|-----------|
+| 单个商品 | `product create` | 先上传图片，准备好所有必填字段 |
+| 多规格商品 | `product create` + `variant create` | 主商品设置基础价格，变体设置差异价 |
+| 批量上架 | 脚本循环 `product create` | 复用共享图片的media_id，避免重复上传 |
+| 更新价格 | `product update --price` | 如有变体，需逐个更新变体价格 |
+| 促销标签 | `product update --tags` | 用逗号分隔，保留原有标签 |
+| 图片更新 | `upload` + `add-images` | 先上传再关联，不要直接删除旧图 |
+
+## 卓越标准
+
+### 商品质量维度
+- **图片质量**: 至少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 --title "$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 --title "$product" --media-id media_123
+done
+```
+
+### ❌ 问题2：忘记创建变体
+**症状**: 多规格商品只有主商品，无法选择颜色/尺寸
+**解决**: 创建主商品后，立即创建所有变体
+
+```bash
+# 错误：只创建主商品
+commerce product create --title "T恤" --price 99
+
+# 正确：创建主商品 + 所有变体
+commerce product create --title "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 --title "T恤" --price 99 --stock 50  # 确保真实有50件
+```
+
+## 命令参考
 
 ### 自然语言映射
 
@@ -41,9 +210,9 @@ description: Product catalog management for e-commerce stores. Create and update
 - `commerce product add-images` - 关联图片到商品
 - `commerce product remove-images` - 移除商品图片
 
-## Examples
+## 详细示例
 
-### 创建商品
+### 示例1：创建单个商品
 ```bash
 # 用户说："创建T恤商品，99美元，库存20"
 commerce product create \
@@ -53,7 +222,7 @@ commerce product create \
   --description "100% 纯棉T恤"
 ```
 
-### 上传商品图片
+### 示例2：上传商品图片
 ```bash
 # 用户说："上传商品主图"
 commerce upload image --path ./tshirt-main.jpg
@@ -65,7 +234,7 @@ commerce product add-images \
   --media-id media_123
 ```
 
-### 创建商品变体
+### 示例3：创建商品变体
 ```bash
 # 用户说："给商品添加红色S码的变体"
 commerce variant create \
@@ -76,7 +245,7 @@ commerce variant create \
   --attributes '{"颜色":"红色","尺寸":"S"}'
 ```
 
-### 管理商品标签
+### 示例4：管理商品标签
 ```bash
 # 用户说："把商品标记为精选和新品"
 commerce product update \
@@ -87,7 +256,7 @@ commerce product update \
 commerce product list --tags "featured"
 ```
 
-### 批量更新价格
+### 示例5：批量更新价格
 ```bash
 # 用户说："把所有T恤价格改成89"
 # 1. 先查找T恤商品
@@ -98,63 +267,35 @@ commerce product update --id prod_123 --price 89
 commerce product update --id prod_456 --price 89
 ```
 
-## 卓越标准
-
-### 商品质量维度
-- **图片质量**: 至少3张不同角度，主图尺寸 ≥ 1200x1200px
-- **描述完整性**: 必填字段100%填写，描述文字 ≥ 50字
-- **SEO优化**: 标题包含核心关键词，使用3-5个相关标签
-- **变体规范**: 使用统一的attributes key（如"颜色"、"尺寸"），避免同义词混用
-- **库存准确**: 创建时设置真实库存，避免超卖和缺货
+### 示例6：完整的多规格商品上架
+```bash
+# 完整流程演示
+# 1. 上传图片
+commerce upload image --path ./tshirt-red.jpg    # media_red
+commerce upload image --path ./tshirt-blue.jpg   # media_blue
 
-### 上架流程原则
-- **图片先行**: 先批量上传所有图片获取media_id，再创建商品（避免重复上传）
-- **主商品后变体**: 先创建主商品获取product_id，再创建所有变体
-- **数据完整性**: 每个变体必须有独立SKU、库存、价格
-- **标签策略**: 精选(featured)、新品(new)、促销(sale)等核心标签要及时更新
+# 2. 创建主商品
+commerce product create --title "纯棉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
 
-### 标准商品上架流程
-1. **准备素材** - 整理图片、文案、SKU、规格表
-2. **批量上传图片** - 使用 `commerce upload image` → 记录所有media_id
-3. **创建主商品** - `commerce product create` → 记录product_id
-4. **创建变体** - 循环 `commerce variant create` 添加所有SKU
-5. **关联图片** - `commerce product add-images` 关联主图和详情图
-6. **验证完整性** - `commerce product get --id XXX` 检查所有字段
+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
 
-**❌ 低效做法**：
-```bash
-# 每个商品都重复上传相同的品牌logo
-for product in products; do
-  commerce upload image --path ./brand-logo.jpg
-  commerce product create --title "$product" --media-id $NEW_ID
-done
-```
-
-**✅ 高效做法**：
-```bash
-# 先上传共享资源，复用media_id
-commerce upload image --path ./brand-logo.jpg  # 获得 media_123
+# 4. 关联图片
+commerce product add-images --id prod_123 --media-id media_red,media_blue
 
-for product in products; do
-  commerce product create --title "$product" --media-id media_123
-done
+# 5. 验证
+commerce product get --id prod_123
 ```
 
-### 常见场景决策
-
-| 用户需求 | 推荐命令 | 关键注意点 |
-|---------|---------|-----------|
-| 创建单个商品 | `product create` | 先上传图片，准备好所有必填字段 |
-| 创建多规格商品 | `product create` + `variant create` | 主商品设置基础价格，变体设置差异价 |
-| 批量上架 | 脚本循环 `product create` | 复用共享图片的media_id，避免重复上传 |
-| 更新价格 | `product update --price` | 如有变体，需逐个更新变体价格 |
-| 添加促销标签 | `product update --tags` | 用逗号分隔，保留原有标签 |
-
-## Notes
+## 重要提示
 
 - 所有命令默认 JSON 输出，便于 AI 解析
 - 图片需要先上传获取 `media_id`，再关联到商品
@@ -162,3 +303,5 @@ done
 - 标签使用逗号分隔的字符串
 - 支持的图片格式：JPG, PNG, WebP
 - 使用 `--help` 查看命令详细参数
+- 删除商品会同时删除所有变体和图片关联
+- 价格单位默认为美元（USD），可通过后台配置修改