---
name: homepage
description: 店铺首页配置。管理首页区块（Banner、集合列表、集合商品、特色推荐）和页面级设置（背景图、叠加层）。当用户需要配置店铺首页布局、添加轮播图、展示集合、设置背景图片、设置 Banner 不裁切/完整显示时使用。
---

## 重要：先查后做

1. 不确定参数时，先运行 `<command> --help` 查看完整参数说明
2. 修改 settings 字段时，必须使用下方「Settings 合法字段」中列出的字段名，不要猜测
3. 操作已有区块前，先 `commerce homepage list` 获取区块 ID

## 用户意图 → 命令

### 查看

| 用户说 | 命令 |
|-------|------|
| 查看首页配置 | `commerce homepage get-config` |
| 查看首页区块列表 | `commerce homepage list` |
| 查看区块详情 | `commerce homepage get --id <id>` |
| 查看可用模板 | `commerce homepage list-templates` |

### Banner（轮播图）

| 用户说 | 命令 |
|-------|------|
| 添加/创建轮播图 | `commerce homepage create-banner --title <title> --lang <lang> --images '<json>'` |
| Banner 不裁切 / 完整显示 / 按原始比例 | 新建时加 `--image-fit contain`；已有 banner 用 `patch-settings --id <id> --settings '{"image_fit":"contain"}'` |
| 更换所有图片 | `commerce homepage update-images --id <id> --images '<json>'`（全量替换，见下方说明） |
| 给第 N 张图加/换手机版 | `commerce homepage patch-banner-image --id <id> --index N --mobile-url "https://..."` |
| 改第 N 张图的描述/动作 | `commerce homepage patch-banner-image --id <id> --index N --alt "..." --action-type collection --action-value slug` |
| 移除第 N 张图的手机版 | `commerce homepage patch-banner-image --id <id> --index N --remove-mobile-url` |
| 关闭自动播放 | `commerce homepage patch-settings --id <id> --settings '{"autoplay":false}'` |
| 修改轮播间隔 | `commerce homepage patch-settings --id <id> --settings '{"interval":3000}'` |

### 集合

| 用户说 | 命令 |
|-------|------|
| 添加集合入口区块 | `commerce homepage create-collections --title <title> --lang <lang> --slugs "a,b,c"` |
| 更新集合列表 | `commerce homepage update-collections --id <id> --slugs "a,b,c"` |
| 添加集合商品区块 | `commerce homepage create-collection-products --title <title> --lang <lang> --slug <slug>` |

### 特色推荐

| 用户说 | 命令 |
|-------|------|
| 添加特色推荐 | `commerce homepage create-featured --title <title> --lang <lang> --target-type collection --target-handle <handle> --cta "查看" --image-url "https://..."` |
| 更新推荐目标 | `commerce homepage update-target --id <id> --type <type> --handle <handle>` |

### 背景图

| 用户说 | 命令 |
|-------|------|
| 设置首页背景图 | 先 `commerce upload --file bg.png` 拿到 media_id，再 `commerce homepage update-page-settings --background-media-id <id> --background-mode repeat-y` |
| 设置固定背景（照片） | 先上传，再 `commerce homepage update-page-settings --background-media-id <id> --background-mode fixed` |
| 调整背景叠加透明度 | `commerce homepage update-page-settings --overlay-opacity 0.7` |
| 调整背景叠加颜色 | `commerce homepage update-page-settings --overlay-color "#f5f5f5"` |
| 移除背景图 | `commerce homepage update-page-settings --remove-background` |

### 品牌色

| 用户说 | 命令 |
|-------|------|
| "修改品牌色" / "设置主题色" | **merchant skill**：`commerce merchant update --primary-color "#xxx"` |

### 通用操作

| 用户说 | 命令 |
|-------|------|
| 调整区块顺序 | `commerce homepage reorder --moves '[{"section_id":"<id>","new_position":0}]'` |
| 修改区块标题/描述 | `commerce i18n homepage set --section-id <id> --lang <lang> --title "新标题"` |
| 删除区块 | `commerce homepage delete --id <id> --yes` |
| 切换模板 | `commerce homepage switch-template --template-key <minimal\|standard> --yes` |

## Settings 合法字段

使用 `patch-settings` 修改设置时，只能使用以下字段名。**使用未列出的字段会被后端拒绝（extra="forbid"）。**

### banner

| 字段 | 类型 | 说明 |
|------|------|------|
| images | array | 图片数组（通过 `update-images` 或 `patch-banner-image` 修改，不要用 patch-settings） |
| autoplay | boolean | 是否自动播放，默认 true |
| interval | number | 轮播间隔（毫秒），1000-30000，默认 5000 |
| image_fit | string | `cover`（默认，裁切填充）/ `contain`（完整显示，高度自适应，无裁切） |

### collections

| 字段 | 类型 | 说明 |
|------|------|------|
| collection_slugs | array | 集合 slug 数组（通过 `update-collections` 修改更方便） |
| layout | string | `grid` / `carousel` |
| show_product_count | boolean | 是否显示商品数量 |

### collection_products

| 字段 | 类型 | 说明 |
|------|------|------|
| collection_slug | string | 集合 slug |
| mode | string | `auto` / `manual` |
| product_handles | array | manual 模式下的商品 handle 列表 |
| limit | number | auto 模式最多展示数量，默认 8 |
| sort_by | string | `created_at` / `price` / `title` |
| sort_order | string | `asc` / `desc` |

### featured

| 字段 | 类型 | 说明 |
|------|------|------|
| target_type | string | `collection` / `product` |
| target_handle | string | 目标 slug/handle |
| media_id | string | 封面图片 ID |
| url | string | 封面图片 URL（新上传用 url，后端自动转 media_id） |
| cta_text | string | CTA 按钮文字 |
| background_color | string | 背景颜色，如 `#f5f5f5` |

### page_settings（页面级设置）

通过 `update-page-settings` 命令修改，不是 `patch-settings`。

| 字段 | 类型 | 说明 |
|------|------|------|
| background_media_id | string / null | 背景图片 Media ID（通过 `commerce upload` 获取，推荐） |
| background_image | string / null | 背景图片 URL（不推荐直接使用，应通过 media_id 设置） |
| background_mode | string | `repeat-y`（横向填满纵向平铺，默认）/ `fixed`（固定视口） |
| background_overlay_color | string | 叠加颜色（hex 格式，默认 `#ffffff`） |
| background_overlay_opacity | number | 叠加透明度 0-1（默认 0.85，越大越不透明） |

## 复杂操作说明

### update-images 全量替换

`update-images` 会覆盖整个 images 数组。操作步骤：

1. `commerce homepage get --id <id>` 获取现有图片（含 media_id）
2. 构建完整数组：已有图原样透传 media_id，新图用 url
3. 执行替换

```bash
commerce homepage update-images --id section_xxx --images '[
  {"media_id":"med_abc","mobile_media_id":"med_def","alt":"图1","action_type":"collection","action_value":"sale"},
  {"url":"https://new-image.jpg","alt":"新图","action_type":"none"}
]'
```

**注意：漏传的字段（如 `mobile_media_id`）会导致手机图丢失。务必完整复制现有图片的所有字段。**

### Banner 图片字段说明

| 字段 | 必填 | 说明 |
|------|------|------|
| url | △ | 桌面端图片 URL（url 或 media_id 至少一个） |
| media_id | △ | 已有图片 ID（从 `homepage get` 获取） |
| mobile_url | | 手机端图片 URL（3:4 竖向，可选） |
| mobile_media_id | | 手机端已有图片 ID |
| alt | ✓ | 图片描述 |
| action_type | ✓ | `none` / `collection` / `product` / `url` / `section` |
| action_value | | 动作目标（slug / URL / section handle） |

### patch-banner-image vs update-images

| 场景 | 用哪个 |
|------|--------|
| 改单张图的属性（alt、mobile_url 等） | `patch-banner-image --index N` |
| 添加/删除图片、重新排序 | `update-images`（全量替换） |

## 注意事项

- **语言代码**：设置标题/描述时必须指定 `--lang`（zh-CN、en-US、ja-JP、es-ES、vi-VN），根据用户文字识别语言
- **区块顺序**：position 从 0 开始
- **media_id 生命周期**：URL → 传给 API → 后端自动转为 media_id → 后续 `homepage get` 返回 media_id
- **手机端图片**：mobile_url 为 3:4 竖向，有时手机端显示竖版大图，无则保持横向
- **image_fit**：默认 `cover`（裁切），设 `contain` 可按原始比例完整显示，适合纯切图首页
- **模板切换**：会创建新区块并停用旧区块，谨慎操作
- **删除确认**：删除操作需要 `--yes`
