---
name: collection
description: 商品集合管理。创建、编辑集合，设置封面图，管理集合中的商品。当用户需要对商品进行分组、创建促销专区、管理商品分类、设置集合封面时使用。
---

## 概念

Collection（集合）是商品的逻辑分组，用于在店铺中组织和展示商品。类似 Shopify 的 Collections。

- 一个商品可以属于多个集合（多对多关系）
- 集合支持层级结构（parent_id）
- 集合通过 slug 在 URL 中标识，如 `/collections/summer-sale`

## 结构

```
Collection
├── 基本信息
│   ├── name: 集合名称
│   ├── slug: URL 标识（商户内唯一）
│   └── description: 描述
├── 显示设置
│   ├── display_order: 显示顺序
│   ├── is_active: 是否激活
│   └── cover_media_id: 封面图
├── 层级
│   └── parent_id: 父集合（可选）
├── SEO
│   ├── meta_title: SEO 标题
│   └── meta_description: SEO 描述
└── 商品（多对多）
    └── products: 集合中的商品列表
```

## 典型场景

当用户说：
- "查看所有集合" / "集合列表" → `commerce collection list`
- "创建集合 XX" → `commerce collection create --name "XX" --slug xx`
- "查看集合详情" → `commerce collection get --id xx`
- "删除集合 XX" → `commerce collection delete --id xx --yes`
- "把商品加到集合" → `commerce collection add-products --id xx --product-ids p1,p2`
- "从集合移除商品" → `commerce collection remove-products --id xx --product-ids p1`
- "查看集合里有哪些商品" → `commerce collection list-products --id xx`
- "设置集合封面" / "给集合加封面图" → `commerce collection set-cover --id xx --path ./cover.jpg`

## 命令参考

### 集合 CRUD
- `commerce collection list` - 列出所有集合
- `commerce collection create --name <name> --slug <slug>` - 创建集合
- `commerce collection get --id <id>` - 查看集合详情
- `commerce collection update --id <id>` - 更新集合（支持 --name, --slug, --description 等）
- `commerce collection delete --id <id> --yes` - 删除集合
- `commerce collection set-cover --id <id>` - 设置封面图（支持 --media-id, --url, --path）

### 商品管理
- `commerce collection add-products --id <id> --product-ids <ids>` - 添加商品
- `commerce collection remove-products --id <id> --product-ids <ids>` - 移除商品
- `commerce collection list-products --id <id>` - 列出集合中的商品

## 创建集合示例

```bash
# 创建促销集合（返回 id，用于后续操作）
commerce collection create \
  --name "Summer Sale 2024" \
  --slug summer-sale-2024 \
  --description "Hot deals for summer"
# 输出: { "id": "coll_xxx", ... }

# 添加商品到集合（使用返回的 id）
commerce collection add-products \
  --id coll_xxx \
  --product-ids prod_123,prod_456,prod_789

# 设置封面图
commerce collection set-cover \
  --id coll_xxx \
  --path ./summer-sale-cover.jpg
```

## 注意事项

- **slug 规范**：使用英文、数字、连字符，避免中文和特殊字符（影响 SEO 和 URL）
- **删除确认**：删除操作需要 `--yes` 参数确认
- **商品数量**：建议每个集合包含 5-30 个商品，过少显得空，过多难以浏览
- **层级深度**：支持父子集合，但建议层级不超过 2 层
