@optima-chat/commerce-cli 1.3.0 → 1.4.0

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

@@ -5,11 +5,247 @@ description: Storefront and homepage configuration. Manage homepage sections, pr
 
 # Commerce CLI - Storefront Configuration
 
-## Overview
-
 店铺前台配置模块，用于首页设置、商品集合管理和商户信息维护。
 
-## Instructions
+## 典型场景
+
+### 场景决策表
+
+| 用户需求 | 推荐命令 | 关键注意点 |
+|---------|---------|-----------|
+| 创建轮播图 | `commerce homepage module create --type banner` | 图片尺寸1920x600px，≤5张，配置跳转链接 |
+| 显示精选商品 | `commerce homepage module create --type featured` | 选择高转化商品，数量8-12个 |
+| 创建促销集合 | `collection create --slug sale` | slug 简短有意义，添加10-30个商品 |
+| 调整模块顺序 | `homepage module reorder --position X` | 重要模块靠前（轮播图position=1） |
+| 更新店铺信息 | `merchant update --name/description` | 名称简洁，描述突出差异化优势 |
+
+### 场景 1：首页配置
+
+**标准首页布局**（position顺序）：
+1. **轮播图** (position=1) - 展示促销、新品、品牌故事
+2. **分类导航** (position=2) - 快速引导到商品分类
+3. **精选商品** (position=3) - 展示高转化或高利润商品
+4. **热门集合** (position=4) - 展示2-3个核心集合
+5. **品牌故事** (position=5) - 建立信任和品牌认知
+
+**标准流程**：
+1. **规划布局** - 确定首页模块顺序（轮播图 → 分类 → 精选商品 → 集合）
+2. **创建模块** - 依次 `commerce homepage module create` 创建各模块
+3. **配置顺序** - 使用 position 1, 2, 3... 排序
+4. **设置参数** - `commerce homepage settings update` 配置搜索、精选数量
+5. **验证效果** - `commerce homepage module list` 检查配置
+6. **定期优化** - 根据数据调整模块顺序和内容
+
+### 场景 2：创建轮播图
+
+**配置要点**：
+- 图片尺寸：1920x600px（桌面端）
+- 数量限制：≤ 5张（避免影响加载速度）
+- 格式支持：WebP（优先）、JPG、PNG
+- 跳转链接：配置促销页面或集合页面
+- 懒加载：启用图片懒加载优化性能
+
+```bash
+commerce homepage module create \
+  --slug hero-banner \
+  --type banner \
+  --position 1 \
+  --enabled true \
+  --config '{"images":[{"url":"https://example.com/banner1.jpg","link":"/collections/summer-sale"}]}'
+```
+
+### 场景 3：创建商品集合
+
+**推荐集合类型**：
+- **时令集合** - 春夏秋冬、节日促销（如"Christmas Sale"）
+- **品类集合** - 按商品类型分组（如"T-Shirts", "Dresses"）
+- **主题集合** - 按场景分组（如"Office Wear", "Casual Style"）
+- **促销集合** - 新品、热卖、折扣（如"New Arrivals", "Best Sellers"）
+
+**创建流程**：
+```bash
+# 1. 创建集合
+commerce collection create \
+  --name "Summer Sale 2024" \
+  --slug "summer-sale-2024" \
+  --description "Hot deals for summer"
+
+# 2. 添加商品到集合
+commerce collection add-products \
+  --slug summer-sale-2024 \
+  --product-ids prod_123,prod_456,prod_789
+```
+
+### 场景 4：调整模块顺序
+
+**重新排序原则**：
+- 重要模块靠前（轮播图 position=1）
+- 高转化模块优先级高
+- 移动端体验优先
+- 定期根据数据优化
+
+```bash
+# 调整精选商品模块到第2位
+commerce homepage module reorder \
+  --module-id module_123 \
+  --position 2
+```
+
+### 场景 5：优化转化率
+
+**数据驱动优化**：
+- 分析首页点击热图，调整模块顺序
+- A/B测试不同轮播图和精选商品
+- 根据转化率隐藏低效集合
+- 精选商品选择高利润或高评分商品
+
+**性能优化建议**：
+- 轮播图：懒加载，压缩图片，支持WebP格式
+- 精选商品：限制8-12个，缓存1小时
+- 集合：按点击率排序，隐藏低转化集合
+
+### 场景 6：店铺信息维护
+
+**更新要点**：
+- 店铺名称：简洁有辨识度
+- 描述：突出差异化优势和核心品类
+- Logo：清晰、支持透明背景
+- 联系方式：完整准确
+
+```bash
+commerce merchant update \
+  --name "My Fashion Store" \
+  --description "Premium fashion for everyone" \
+  --logo-url "https://example.com/logo.png"
+```
+
+## 卓越标准
+
+### 店铺配置质量指标
+- **页面加载速度**: 首页加载 < 3秒，移动端 < 5秒
+- **视觉设计**: 轮播图尺寸统一（1920x600px），图片清晰无水印
+- **导航体验**: 分类层级 ≤ 3层，集合数量 5-15个最佳
+- **内容更新频率**: 轮播图每周更新，精选商品每3天更新
+- **转化率**: 首页访客转化率 > 3%，集合页转化率 > 5%
+
+### 店铺配置原则
+- **移动优先**: 所有配置考虑移动端体验，图片支持响应式
+- **性能优化**: 轮播图 ≤ 5张，精选商品 ≤ 12个，减少加载负担
+- **SEO友好**: 集合slug使用英文，标题包含关键词
+- **一致性**: 风格统一（色彩、字体、间距），提升品牌辨识度
+- **数据驱动**: 根据点击率和转化率优化首页布局和集合内容
+
+### 首页配置检查清单
+
+**上线前必查**：
+- [ ] 轮播图尺寸统一，图片清晰
+- [ ] 所有链接可点击，无404
+- [ ] 移动端显示正常
+- [ ] 加载速度 < 3秒
+- [ ] SEO信息完整（标题、描述、关键词）
+- [ ] 精选商品有库存
+- [ ] 集合至少包含5个商品
+- [ ] 店铺信息准确（名称、Logo、联系方式）
+
+## 常见问题
+
+### ❌ 问题 1：集合命名随意，无规划
+
+**错误做法**：
+```bash
+# 命名不规范，slug 无意义
+commerce collection create --name "aaa" --slug "test123"
+commerce collection create --name "商品111" --slug "product-collection"
+commerce collection create --name "Sale!!!" --slug "promotion"
+```
+
+**✅ 正确做法**：
+```bash
+# 命名清晰，slug 符合 SEO 规范
+commerce collection create --name "Summer Sale 2024" --slug "summer-sale-2024"
+commerce collection create --name "Men's T-Shirts" --slug "mens-tshirts"
+commerce collection create --name "New Arrivals" --slug "new-arrivals"
+```
+
+### ❌ 问题 2：轮播图过多影响性能
+
+**错误做法**：
+```bash
+# 创建10张轮播图，导致首页加载缓慢
+commerce homepage module create --type banner --config '{"images":[...10张图片...]}'
+```
+
+**✅ 正确做法**：
+```bash
+# 限制≤5张，压缩图片，启用懒加载
+commerce homepage module create --type banner --config '{"images":[...3-5张图片...]}'
+```
+
+### ❌ 问题 3：精选商品数量过多
+
+**错误做法**：
+```bash
+# 显示30个精选商品，影响用户决策
+commerce homepage settings update --featured-limit 30
+```
+
+**✅ 正确做法**：
+```bash
+# 限制8-12个，选择高转化商品
+commerce homepage settings update --featured-limit 10
+```
+
+### ❌ 问题 4：集合缺少商品
+
+**错误做法**：
+```bash
+# 创建集合后忘记添加商品
+commerce collection create --name "New Arrivals" --slug "new-arrivals"
+# 集合页面显示空白
+```
+
+**✅ 正确做法**：
+```bash
+# 创建集合后立即添加商品（至少5个）
+commerce collection create --name "New Arrivals" --slug "new-arrivals"
+commerce collection add-products --slug new-arrivals --product-ids prod_1,prod_2,prod_3,prod_4,prod_5
+```
+
+### ❌ 问题 5：首页模块顺序混乱
+
+**错误做法**：
+```bash
+# position 随意设置，导致布局混乱
+commerce homepage module create --type banner --position 10
+commerce homepage module create --type featured --position 2
+commerce homepage module create --type categories --position 50
+```
+
+**✅ 正确做法**：
+```bash
+# 按重要性依次设置 position 1, 2, 3...
+commerce homepage module create --type banner --position 1
+commerce homepage module create --type categories --position 2
+commerce homepage module create --type featured --position 3
+```
+
+### ❌ 问题 6：slug 使用中文或特殊字符
+
+**错误做法**：
+```bash
+# slug 包含中文或特殊字符，影响 SEO 和 URL 可读性
+commerce collection create --name "夏季促销" --slug "夏季促销"
+commerce collection create --name "Sale!!!" --slug "sale!!!"
+```
+
+**✅ 正确做法**：
+```bash
+# slug 使用英文、数字、连字符
+commerce collection create --name "夏季促销" --slug "summer-sale"
+commerce collection create --name "Sale!!!" --slug "sale"
+```
+
+## 命令参考
 
 ### 自然语言映射
 
@@ -46,7 +282,7 @@ description: Storefront and homepage configuration. Manage homepage sections, pr
 - `commerce merchant update` - 更新商户信息
 - `commerce merchant init` - 初始化商户设置
 
-## Examples
+## 详细示例
 
 ### 创建首页轮播图
 ```bash
@@ -100,95 +336,39 @@ commerce homepage module reorder \
   --position 2
 ```
 
-## 卓越标准
-
-### 店铺配置质量指标
-- **页面加载速度**: 首页加载 < 3秒，移动端 < 5秒
-- **视觉设计**: 轮播图尺寸统一（1920x600px），图片清晰无水印
-- **导航体验**: 分类层级 ≤ 3层，集合数量 5-15个最佳
-- **内容更新频率**: 轮播图每周更新，精选商品每3天更新
-- **转化率**: 首页访客转化率 > 3%，集合页转化率 > 5%
-
-### 店铺配置原则
-- **移动优先**: 所有配置考虑移动端体验，图片支持响应式
-- **性能优化**: 轮播图 ≤ 5张，精选商品 ≤ 12个，减少加载负担
-- **SEO友好**: 集合slug使用英文，标题包含关键词
-- **一致性**: 风格统一（色彩、字体、间距），提升品牌辨识度
-- **数据驱动**: 根据点击率和转化率优化首页布局和集合内容
-
-## 工作流推荐
-
-### 首页配置标准流程
-1. **规划布局** - 确定首页模块顺序（轮播图 → 分类 → 精选商品 → 集合）
-2. **创建模块** - 依次 `commerce homepage module create` 创建各模块
-3. **配置顺序** - 使用 position 1, 2, 3... 排序
-4. **设置参数** - `commerce homepage settings update` 配置搜索、精选数量
-5. **验证效果** - `commerce homepage module list` 检查配置
-6. **定期优化** - 根据数据调整模块顺序和内容
-
-### 商品集合策略
-
-**推荐集合类型**：
-- **时令集合** - 春夏秋冬、节日促销（如"Christmas Sale"）
-- **品类集合** - 按商品类型分组（如"T-Shirts", "Dresses"）
-- **主题集合** - 按场景分组（如"Office Wear", "Casual Style"）
-- **促销集合** - 新品、热卖、折扣（如"New Arrivals", "Best Sellers"）
-
-### 集合管理最佳实践
-
-**❌ 混乱做法**：
-```bash
-# 集合命名随意，无规划
-commerce collection create --name "aaa" --slug "test123"
-commerce collection create --name "商品111" --slug "product-collection"
-commerce collection create --name "Sale!!!" --slug "promotion"
-```
-
-**✅ 规范做法**：
+### 完整首页配置示例
 ```bash
-# 命名清晰，slug 符合 SEO 规范
-commerce collection create --name "Summer Sale 2024" --slug "summer-sale-2024"
-commerce collection create --name "Men's T-Shirts" --slug "mens-tshirts"
-commerce collection create --name "New Arrivals" --slug "new-arrivals"
-```
-
-### 常见场景决策
-
-| 用户需求 | 推荐命令 | 关键注意点 |
-|---------|---------|-----------|
-| 创建轮播图 | `homepage module create --type banner` | 图片尺寸1920x600px，≤5张，配置跳转链接 |
-| 显示精选商品 | `homepage module create --type featured` | 选择高转化商品，数量8-12个 |
-| 创建促销集合 | `collection create --slug sale` | slug 简短有意义，添加10-30个商品 |
-| 调整模块顺序 | `homepage module reorder --position X` | 重要模块靠前（轮播图position=1） |
-| 更新店铺信息 | `merchant update --name/description` | 名称简洁，描述突出差异化优势 |
-
-### 首页模块推荐配置
+# 1. 创建轮播图模块
+commerce homepage module create \
+  --slug hero-banner \
+  --type banner \
+  --position 1 \
+  --config '{"images":[{"url":"https://example.com/banner1.jpg","link":"/collections/summer-sale"},{"url":"https://example.com/banner2.jpg","link":"/collections/new-arrivals"}]}'
 
-**标准首页布局**（position顺序）：
-1. **轮播图** (position=1) - 展示促销、新品、品牌故事
-2. **分类导航** (position=2) - 快速引导到商品分类
-3. **精选商品** (position=3) - 展示高转化或高利润商品
-4. **热门集合** (position=4) - 展示2-3个核心集合
-5. **品牌故事** (position=5) - 建立信任和品牌认知
+# 2. 创建分类导航模块
+commerce homepage module create \
+  --slug category-nav \
+  --type categories \
+  --position 2 \
+  --config '{"columns":4}'
 
-**性能优化建议**：
-- 轮播图：懒加载，压缩图片，支持WebP格式
-- 精选商品：限制8-12个，缓存1小时
-- 集合：按点击率排序，隐藏低转化集合
+# 3. 创建精选商品模块
+commerce homepage module create \
+  --slug featured-products \
+  --type featured \
+  --position 3 \
+  --config '{"limit":10}'
 
-### 首页配置检查清单
+# 4. 更新首页设置
+commerce homepage settings update \
+  --show-search true \
+  --featured-limit 10
 
-**上线前必查**：
-- [ ] 轮播图尺寸统一，图片清晰
-- [ ] 所有链接可点击，无404
-- [ ] 移动端显示正常
-- [ ] 加载速度 < 3秒
-- [ ] SEO信息完整（标题、描述、关键词）
-- [ ] 精选商品有库存
-- [ ] 集合至少包含5个商品
-- [ ] 店铺信息准确（名称、Logo、联系方式）
+# 5. 验证配置
+commerce homepage module list
+```
 
-## Notes
+## 重要提示
 
 - 首页模块支持类型：banner（轮播图）、featured（精选商品）、categories（分类）
 - 集合 slug 必须唯一，用于 URL
@@ -196,3 +376,5 @@ commerce collection create --name "New Arrivals" --slug "new-arrivals"
 - config 字段使用 JSON 格式
 - 集合可以手动管理商品，也可以设置自动规则
 - 使用 `--help` 查看命令详细参数
+- 所有模块和集合创建后需要验证配置是否正确
+- 定期根据数据分析优化首页布局和内容

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/commerce-cli",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "用自然语言管理电商店铺 - 专为 Claude Code 设计的对话式 CLI 工具，支持多环境和功能测试",
   "main": "dist/index.js",
   "type": "module",