---
name: commerce-storefront
description: Storefront and product page configuration. Manage homepage sections, product collections, merchant profile, product detail page sections with 3-layer inheritance (System → Merchant → Product). Use when user needs to configure homepage, create collections, customize product page sections, or organize storefront layout.
---

# Commerce CLI - Storefront Configuration

店铺前台配置模块，用于首页设置、商品集合管理和商户信息维护。

## 典型场景

### 场景决策表

| 用户需求 | 推荐命令 | 关键注意点 |
|---------|---------|-----------|
| 创建轮播图 | `commerce homepage create --type banner` | 图片尺寸1920x600px，≤5张，配置跳转链接 |
| 显示精选商品 | `commerce homepage create --type featured` | 选择高转化商品，数量8-12个 |
| 创建促销集合 | `commerce collection create --slug sale` | slug 简短有意义，添加10-30个商品 |
| 设置集合封面 | `commerce collection set-cover --id XX` | 支持 --url、--path、--media-id 三种方式 |
| 调整区块顺序 | `commerce homepage reorder --moves '[...]'` | 重要区块靠前（position=0） |
| 更新店铺信息 | `commerce merchant update` | 名称简洁，描述突出差异化优势 |

### 场景 1：首页配置

**标准首页布局**（position顺序）：
1. **轮播图** (position=1) - 展示促销、新品、品牌故事
2. **分类导航** (position=2) - 快速引导到商品分类
3. **精选商品** (position=3) - 展示高转化或高利润商品
4. **热门集合** (position=4) - 展示2-3个核心集合
5. **品牌故事** (position=5) - 建立信任和品牌认知

**标准流程**：
1. **规划布局** - 确定首页区块顺序（轮播图 → 分类 → 精选商品 → 集合）
2. **创建区块** - 依次 `commerce homepage create` 创建各区块
3. **配置顺序** - 使用 `commerce homepage reorder` 调整顺序
4. **更新设置** - `commerce homepage patch-settings` 配置区块参数
5. **验证效果** - `commerce homepage list` 检查配置
6. **定期优化** - 根据数据调整区块顺序和内容

### 场景 2：创建轮播图

**配置要点**：
- 图片尺寸：1920x600px（桌面端）
- 数量限制：≤ 5张（避免影响加载速度）
- 格式支持：WebP（优先）、JPG、PNG
- 跳转链接：配置促销页面或集合页面
- 懒加载：启用图片懒加载优化性能
- 显示模式：`--image-fit cover`（默认，裁切填充）或 `--image-fit contain`（完整显示，高度自适应）
- contain 模式适合纯切图首页（用 banner 堆叠实现完整页面，图片不裁切）

```bash
# 图片 URL 直接使用，后端自动下载处理
commerce homepage create-banner --title "主 Banner" \
  --images '[{"url":"https://example.com/banner.jpg","link":"/collections/summer-sale"}]'

# 创建不裁切的 banner（图片按原始比例完整显示）
commerce homepage create-banner --title "全屏 Banner" \
  --images '[{"url":"https://example.com/full-page.jpg"}]' --image-fit contain
```

### 场景 3：创建商品集合

**推荐集合类型**：
- **时令集合** - 春夏秋冬、节日促销（如"Christmas Sale"）
- **品类集合** - 按商品类型分组（如"T-Shirts", "Dresses"）
- **主题集合** - 按场景分组（如"Office Wear", "Casual Style"）
- **促销集合** - 新品、热卖、折扣（如"New Arrivals", "Best Sellers"）

**创建流程**：
```bash
# 1. 创建集合（图片 URL 直接使用）
commerce collection create \
  --name "Summer Sale 2024" \
  --slug "summer-sale-2024" \
  --description "Hot deals for summer" \
  --image-url "https://example.com/cover.jpg"

# 2. 添加商品到集合
commerce collection add-products \
  --slug summer-sale-2024 \
  --product-ids prod_123,prod_456,prod_789
```

### 场景 4：调整模块顺序

**重新排序原则**：
- 重要模块靠前（轮播图 position=1）
- 高转化模块优先级高
- 移动端体验优先
- 定期根据数据优化

```bash
# 调整精选商品区块到第2位（0-indexed）
commerce homepage reorder --moves '[{"section_id":"section-123","new_position":1}]'
```

### 场景 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 create --type banner --title "Banner" --settings '{"images":[...10张图片...]}'
```

**✅ 正确做法**：
```bash
# 限制≤5张，压缩图片，启用懒加载
commerce homepage create --type banner --title "Banner" --settings '{"images":[...3-5张图片...]}'
```

### ❌ 问题 3：精选商品数量过多

**错误做法**：
```bash
# 显示30个精选商品，影响用户决策
commerce homepage patch-settings --id section-123 --settings '{"limit":30}'
```

**✅ 正确做法**：
```bash
# 限制8-12个，选择高转化商品
commerce homepage patch-settings --id section-123 --settings '{"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
# 创建后不调整顺序，导致布局混乱
commerce homepage create --type featured --title "精选"
commerce homepage create --type banner --title "Banner"  # Banner 应该在最前面
```

**✅ 正确做法**：
```bash
# 先创建，再用 reorder 调整顺序
commerce homepage create --type banner --title "主 Banner"
commerce homepage create --type collections --title "分类导航"
commerce homepage create --type featured --title "精选商品"
# 确保 Banner 在最前面
commerce homepage reorder --moves '[{"section_id":"banner-id","new_position":0}]'
```

### ❌ 问题 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"
```

## 命令参考

### 自然语言映射

当用户说：
- "创建首页轮播图" → `commerce homepage create --type banner --title "Banner"`
- "查看首页配置" → `commerce homepage get-config`
- "查看首页区块列表" → `commerce homepage list`
- "创建商品集合" → `commerce collection create --name XX --slug YY`
- "查看集合详情" → `commerce collection get --id XX`
- "把商品添加到集合" → `commerce collection add-products --id XX --product-ids YY`
- "查看集合内商品" → `commerce collection list-products --id XX`
- "更新店铺信息" → `commerce merchant update --name XX`
- "查看店铺链接" → `commerce merchant url`
- "Banner 图片地址是 https://..." → `commerce homepage update-images --id XX --images '[{"url":"https://...","alt":"..."}]'`
- "Featured 图片地址是 https://..." → `commerce homepage patch-settings --id XX --settings '{"url":"https://..."}'`
- "设置集合封面" / "修改集合封面图" → `commerce collection set-cover --id XX --url/--path/--media-id`
- "集合封面图 URL 是 https://..." → `commerce collection set-cover --id XX --url "https://..."`
- "上传本地图片作为集合封面" → `commerce collection set-cover --id XX --path ./cover.jpg`
- "Banner 图片不裁切" / "图片完整显示" → `commerce homepage create-banner ... --image-fit contain`
- "纯切图首页" → 所有 banner 区块使用 `--image-fit contain`

### 核心功能

**首页配置**:
- `commerce homepage get-config` - 查看当前首页配置
- `commerce homepage list` - 查看所有首页区块
- `commerce homepage create` - 创建首页区块
- `commerce homepage get` - 查看单个区块详情
- `commerce homepage update` - 更新区块
- `commerce homepage delete` - 删除区块
- `commerce homepage reorder` - 重新排序区块
- `commerce homepage update-images` - 更新 Banner 图片
- `commerce homepage update-collections` - 更新集合区块
- `commerce homepage update-target` - 更新 Featured 区块目标
- `commerce homepage patch-settings` - 更新区块设置

**首页模板**:
- `commerce homepage list-templates` - 查看可用模板
- `commerce homepage switch-template` - 切换首页模板

**商品集合**:
- `commerce collection create` - 创建集合
- `commerce collection list` - 查看集合列表
- `commerce collection get` - 查看集合详情
- `commerce collection update` - 更新集合
- `commerce collection delete` - 删除集合
- `commerce collection set-cover` - 设置集合封面图
- `commerce collection add-products` - 添加商品到集合
- `commerce collection remove-products` - 从集合移除商品
- `commerce collection list-products` - 查看集合内商品

**商户信息**:
- `commerce merchant info` - 查看商户信息
- `commerce merchant update` - 更新商户信息
- `commerce merchant setup` - 初始化商户设置
- `commerce merchant url` - 获取店铺公开链接

## 详细示例

### 创建首页轮播图
```bash
# 用户说："创建首页轮播图"
commerce homepage create \
  --type banner \
  --title "主 Banner" \
  --settings '{"images":[{"url":"https://example.com/banner1.jpg"}]}'
```

### 更新区块设置
```bash
# 用户说："更新精选商品数量为8个"
commerce homepage patch-settings \
  --id section-123 \
  --settings '{"limit":8}'
```

### 创建商品集合
```bash
# 用户说："创建夏季促销集合"
commerce collection create \
  --name "Summer Sale" \
  --slug summer-sale \
  --description "Hot deals for summer"
```

### 添加商品到集合
```bash
# 用户说："把商品prod_123和prod_456添加到summer-sale集合"
commerce collection add-products \
  --slug summer-sale \
  --product-ids prod_123,prod_456
```

### 设置集合封面图
```bash
# 方式 1：使用 Media ID（推荐，可复用已上传图片）
commerce upload image --path ./cover.jpg  # 获取 media_id
commerce collection set-cover --id coll-123 --media-id media_456

# 方式 2：使用图片 URL
commerce collection set-cover --id coll-123 --url "https://example.com/cover.jpg"

# 方式 3：上传本地文件
commerce collection set-cover --id coll-123 --path ./cover.jpg
```

### 更新商户信息
```bash
# 用户说："更新店铺名称和描述"
commerce merchant update \
  --name "My Fashion Store" \
  --description "Premium fashion for everyone"
```

### 重新排序首页区块
```bash
# 用户说："调整首页区块顺序"
commerce homepage reorder --moves '[{"section_id":"section-123","new_position":1}]'
```

### 完整首页配置示例
```bash
# 1. 创建轮播图区块
commerce homepage create \
  --type banner \
  --title "主 Banner" \
  --settings '{"images":[{"url":"https://example.com/banner1.jpg","link":"/collections/summer-sale"},{"url":"https://example.com/banner2.jpg","link":"/collections/new-arrivals"}]}'

# 2. 创建集合区块
commerce homepage create \
  --type collections \
  --title "精选集合"

# 3. 创建精选商品区块
commerce homepage create \
  --type featured \
  --title "精选商品" \
  --settings '{"limit":10}'

# 4. 调整区块顺序（确保 Banner 在最前面）
commerce homepage list  # 先查看区块 ID
commerce homepage reorder --moves '[{"section_id":"banner-section-id","new_position":0}]'

# 5. 验证配置
commerce homepage list
```

## 场景 7：商品详情页区块管理（PDP）

**注意**：`pdp` 命令管理的是商品详情页上显示的**额外内容区块**（如护理说明、尺码指南、配送信息等），**不是**商品属性（名称、价格、图片、描述）。商品属性请使用 `product` 命令。

### 三层继承模型

```
System（7个系统默认区块）→ Merchant（商户定制）→ Product（单品覆盖）
```

- 无 `--product` → merchant 级（影响所有商品）
- 有 `--product <id或handle>` → product 级（仅影响该商品）

### 查看区块配置

```bash
# 查看所有区块（默认合并视图，无需 --resolved）
commerce pdp show

# 查看特定商品的区块配置
commerce pdp show --product blue-hoodie

# 只看某个区块
commerce pdp show --handle care
```

### 编辑已有区块（自动覆盖系统默认）

```bash
# 修改护理说明（merchant 级，所有商品生效）
commerce pdp edit --handle care --content "机洗，30度冷水。"

# 为特定商品单独设置
commerce pdp edit --handle care --content "真丝产品需要干洗。" --product silk-dress
```

### 添加自定义区块

```bash
# 添加品牌故事（merchant 级，所有商品显示）
commerce pdp add --handle brand-story --title "品牌故事" --content "## 关于我们\n\n创立于2020年..."

# 为特定商品添加
commerce pdp add --handle ingredients --content "100% 有机棉" --product blue-hoodie
```

### 隐藏区块

```bash
# 隐藏环保包装区块
commerce pdp hide --handle eco-friendly

# 隐藏特定商品的退货政策
commerce pdp hide --handle return --product blue-hoodie
```

### 排序（handle:position 格式，无 JSON）

```bash
commerce pdp reorder highlights:1 details:2 care:3 return:4

# 在 tab group 内排序
commerce pdp reorder --tab-group product-info highlights:1 details:2 care:3
```

### 添加多语言翻译

```bash
commerce pdp translate --handle care --lang zh-CN --title "护理说明" --content "机洗，30度冷水。"

commerce pdp translate --handle care --lang ja-JP --title "お手入れ方法" --content "洗濯機で洗えます。"
```

### PDP 常见问题

#### ❌ 问题：使用 `commerce product` 操作页面区块

**错误**：`commerce product update --handle care --content "..."` — product 管理商品属性，不是页面区块。

**✅ 正确**：`commerce pdp edit --handle care --content "..."`

#### ❌ 问题：在 product 级重复创建全局区块

**错误**：逐个商品添加品牌故事 `commerce pdp add --handle brand-story --product X`

**✅ 正确**：在 merchant 级创建一次 `commerce pdp add --handle brand-story --content "..."`（自动应用到所有商品）

### PDP 自然语言映射

- "查看商品详情页区块" → `commerce pdp show`
- "查看商品X的区块配置" → `commerce pdp show --product <handle>`
- "修改护理说明" → `commerce pdp edit --handle care --content "..."`
- "隐藏退货政策区块" → `commerce pdp hide --handle return`
- "添加自定义区块" → `commerce pdp add --handle XX --content "..."`
- "添加区块的中文翻译" → `commerce pdp translate --handle <handle> --lang zh-CN --title "..." --content "..."`
- "调整区块顺序" → `commerce pdp reorder highlights:1 details:2 care:3`

## 重要提示

### 首页配置
- 首页区块类型：banner（轮播图）、collections（集合列表）、collection_products（集合商品）、featured（精选商品）
- 集合 slug 必须唯一，用于 URL
- 使用 `homepage reorder` 调整区块顺序
- settings 字段使用 JSON 格式
- 集合可以手动管理商品，也可以设置自动规则
- **图片 URL 直接用**：Banner、Featured、集合封面等图片参数支持直接传 URL，后端自动下载处理

### 商品详情页内容区块（PDP）
- `pdp` 命令管理详情页额外内容（护理说明、尺码指南等），不是商品属性
- 系统默认区块：highlights, details, guarantee, care, shipping-policies, return, eco-friendly
- `pdp show` 默认显示完整合并视图（无需 --resolved）
- `source` 字段标识来源：system | merchant | product
- 想改所有商品用 `pdp edit/add`，只改一个商品加 `--product <handle>`

### 通用
- 使用 `--help` 查看命令详细参数
- 所有配置创建后需要验证是否正确
- 定期根据数据分析优化布局和内容