---
name: shopify
description: Shopify store integration for Optima Commerce. Connect Shopify stores, sync products/orders/inventory/customers, manage collections, discounts, draft orders, refunds, webhooks, markets, and analytics. Use when user mentions Shopify, wants to connect a Shopify store, or manage Shopify-related operations.
---

# Shopify CLI - Shopify 店铺集成管理

Shopify 集成模块，用于连接和管理用户的 Shopify 店铺。

**重要**：这里管理的是用户在 Shopify 平台上的店铺，不是 Optima 自有店铺。用户可以将 Shopify 店铺连接到 Optima，实现跨平台管理。

## 典型场景

当用户说：
- "连接我的 Shopify 店铺" → 使用下方「连接 Shopify 店铺流程（AI Shell）」
- "查看我连接了哪些 Shopify 店铺" → `shopify auth stores`
- "看看 Shopify 上有哪些商品" → `shopify product list --store <storeId>`
- "把 Shopify 商品同步过来" → `shopify product sync --store <storeId>`
- "查看 Shopify 订单" → `shopify order list --store <storeId>`
- "Shopify 订单发货" → `shopify order fulfill --store <storeId> --order <orderId> --tracking <号码>`
- "查看 Shopify 库存" → `shopify inventory list --store <storeId>`
- "同步 Shopify 库存" → `shopify inventory sync --store <storeId>`
- "创建 Shopify 折扣码" → `shopify discount create --store <storeId> --code SAVE10 --percentage 10`
- "查看 Shopify 销售数据" → `shopify analytics report --store <storeId>`

### 场景决策表

| 用户需求 | 推荐命令 | 关键注意点 |
|---------|---------|-----------|
| 连接 Shopify 店铺 | 见下方 AI Shell 连接流程 | 两步式：获取 URL → 轮询状态 |
| 查看已连接店铺 | `shopify auth stores` | 显示所有已连接店铺 |
| 断开 Shopify 店铺 | `shopify auth stores --disconnect <storeId>` | 不可逆操作，需确认 |
| 浏览 Shopify 商品 | `shopify product list --store <id>` | 可用 --status 过滤 |
| 同步商品到 Optima | `shopify product sync --store <id>` | 从 Shopify 同步到 Optima |
| 查看 Shopify 订单 | `shopify order list --store <id>` | 可用 --status 过滤 |
| Shopify 订单发货 | `shopify order fulfill --store <id> --order <oid>` | 需要 tracking 号 |
| 库存对比 | `shopify inventory compare --store <id>` | 对比 Shopify 和 Optima 库存差异 |
| 客户同步 | `shopify customer sync --store <id>` | 同步客户数据到 Optima |
| 创建折扣码 | `shopify discount create --store <id>` | 支持百分比和固定金额 |
| 销售报表 | `shopify analytics report --store <id>` | ShopifyQL 数据分析 |

## 使用前提

1. 用户必须先登录 Optima（`optima auth login`）
2. 然后连接 Shopify 店铺（`shopify auth login --shop <domain>`）
3. 连接后通过 `--store <storeId>` 指定操作哪个店铺

### 获取 storeId

所有操作都需要 `--store <storeId>` 参数，先用 `shopify auth stores` 获取：

```bash
shopify auth stores
```

如果用户只连接了一个店铺，可以从输出中直接取 storeId。

## 连接 Shopify 店铺流程（AI Shell）

**重要**：在 AI Shell 环境中，**必须使用两步式流程**（`--url-only` + `auth check`），不要使用默认的 `auth login`（会阻塞等待浏览器授权）。

### 步骤 1：获取授权 URL

```bash
shopify auth login --shop mystore.myshopify.com --url-only
```

返回 JSON 包含 `installUrl` 和 `state`。

### 步骤 2：展示链接给用户

将 `installUrl` 作为**可点击的 Markdown 链接**展示给用户，例如：

> 请点击以下链接授权您的 Shopify 店铺：
> [授权 mystore.myshopify.com](https://mystore.myshopify.com/admin/oauth/authorize?...)
> 我会自动检测授权状态，请在浏览器中完成授权。

### 步骤 3：自动轮询授权状态

展示链接后，**立即开始轮询**，不需要等待用户回复：

```bash
# 等待 15 秒后检查
sleep 15 && shopify auth check --state <state值>
```

根据返回结果：
- `completed: true` → 授权成功，展示店铺信息
- `completed: false, expired: false` → 尚未完成，继续等 15 秒再查
- `completed: false, expired: true` → 已过期，提示用户重新连接

**轮询规则**：
- 每次间隔 **15 秒**
- 最多轮询 **20 次**（5 分钟）
- 每 3-4 次轮询时告知用户："⏳ 仍在等待授权..."
- 超时后告知用户："授权超时，请重试"

### 完整示例对话

```
用户：连接我的 Shopify 店铺 cool-gadgets.myshopify.com

AI：[执行 Bash: shopify auth login --shop cool-gadgets.myshopify.com --url-only]
    → 获取到 installUrl 和 state

    请点击以下链接授权您的 Shopify 店铺：
    [授权 cool-gadgets.myshopify.com](https://cool-gadgets.myshopify.com/admin/oauth/authorize?...)
    我会自动检测授权状态。

    [执行 Bash: sleep 15 && shopify auth check --state abc123]
    → completed: false

    [执行 Bash: sleep 15 && shopify auth check --state abc123]
    → completed: false

    ⏳ 仍在等待授权...

    [执行 Bash: sleep 15 && shopify auth check --state abc123]
    → completed: true, store: { shopName: "Cool Gadgets", ... }

    ✅ 已成功连接 Shopify 店铺！
    - 店铺：Cool Gadgets
    - 域名：cool-gadgets.myshopify.com
    - 邮箱：owner@example.com
```

## 命令参考

### 认证和店铺管理
- `shopify auth login --shop <domain>` - 连接 Shopify 店铺（有浏览器环境）
- `shopify auth login --shop <domain> --url-only` - 获取授权 URL（AI Shell/无头环境）
- `shopify auth check --state <state>` - 检查 OAuth 授权状态（单次检查）
- `shopify auth status` - 查看认证状态
- `shopify auth stores` - 列出已连接店铺
- `shopify auth stores --info <storeId>` - 查看店铺实时信息
- `shopify auth stores --disconnect <storeId>` - 断开店铺连接

### 商品管理
- `shopify product list --store <id>` - 商品列表
- `shopify product get --store <id> --product <pid>` - 商品详情
- `shopify product search --store <id> --query <关键词>` - 搜索商品
- `shopify product sync --store <id>` - 同步商品到 Optima
- `shopify product publish --store <id> --product <pid>` - 发布商品到销售渠道
- `shopify product mapping --store <id>` - 查看 Shopify↔Optima 商品映射

### 订单管理
- `shopify order list --store <id>` - 订单列表
- `shopify order get --store <id> --order <oid>` - 订单详情
- `shopify order fulfill --store <id> --order <oid> --tracking <号码>` - 订单发货
- `shopify order sync --store <id>` - 同步订单到 Optima

### 库存管理
- `shopify inventory list --store <id>` - 库存列表
- `shopify inventory get --store <id> --product <pid>` - 查看商品库存
- `shopify inventory adjust --store <id> --item <itemId> --delta <数量>` - 调整库存
- `shopify inventory sync --store <id>` - 同步库存
- `shopify inventory compare --store <id>` - 对比 Shopify/Optima 库存差异
- `shopify inventory locations --store <id>` - 查看库存位置

### 位置管理
- `shopify location list --store <id>` - 仓库/位置列表
- `shopify location get --store <id> --location <lid>` - 位置详情

### 集合管理
- `shopify collection list --store <id>` - 集合列表
- `shopify collection get --store <id> --collection <cid>` - 集合详情
- `shopify collection create --store <id> --title <名称>` - 创建集合
- `shopify collection add --store <id> --collection <cid> --products <pid1,pid2>` - 添加商品到集合

### 客户管理
- `shopify customer list --store <id>` - 客户列表
- `shopify customer get --store <id> --customer <cid>` - 客户详情
- `shopify customer sync --store <id>` - 同步客户到 Optima

### 折扣管理
- `shopify discount list --store <id>` - 折扣列表
- `shopify discount get --store <id> --discount <did>` - 折扣详情
- `shopify discount create --store <id>` - 创建折扣码
- `shopify discount delete --store <id> --discount <did>` - 删除折扣

### 草稿订单
- `shopify draft-order list --store <id>` - 草稿订单列表
- `shopify draft-order get --store <id> --draft-order <did>` - 草稿订单详情
- `shopify draft-order create --store <id>` - 创建草稿订单
- `shopify draft-order complete --store <id> --draft-order <did>` - 完成草稿订单
- `shopify draft-order delete --store <id> --draft-order <did>` - 删除草稿订单

### 退款管理
- `shopify refund list --store <id> --order <oid>` - 退款列表
- `shopify refund create --store <id> --order <oid>` - 创建退款

### 市场管理
- `shopify market list --store <id>` - 市场列表
- `shopify market get --store <id> --market <mid>` - 市场详情

### 数据分析
- `shopify analytics report --store <id>` - 销售报表
- `shopify analytics query --store <id> --query <ShopifyQL>` - 自定义 ShopifyQL 查询

### Webhook 管理
- `shopify webhook list --store <id>` - 已订阅的 webhook
- `shopify webhook subscribe --store <id> --topic <topic>` - 订阅 webhook
- `shopify webhook unsubscribe --store <id> --subscription <sid>` - 取消订阅

## 详细示例

### 连接店铺并查看商品
```bash
# 连接 Shopify 店铺
shopify auth login --shop my-cool-store.myshopify.com

# 查看已连接店铺，获取 storeId
shopify auth stores

# 查看商品列表
shopify product list --store abc123

# 搜索特定商品
shopify product search --store abc123 --query "T-shirt"
```

### 同步商品和库存
```bash
# 将 Shopify 商品同步到 Optima Commerce
shopify product sync --store abc123

# 查看商品映射关系
shopify product mapping --store abc123

# 对比两个平台的库存差异
shopify inventory compare --store abc123

# 同步库存
shopify inventory sync --store abc123
```

### 订单发货
```bash
# 查看待发货订单
shopify order list --store abc123 --status unfulfilled

# 查看订单详情
shopify order get --store abc123 --order order_456

# 发货（提供 tracking 号码）
shopify order fulfill --store abc123 --order order_456 \
  --tracking SF1234567890
```

### 创建折扣码
```bash
# 创建 10% 折扣码
shopify discount create --store abc123 \
  --code SAVE10 \
  --percentage 10 \
  --title "新年促销 10% off"

# 创建固定金额折扣
shopify discount create --store abc123 \
  --code FLAT20 \
  --amount 20 \
  --title "满减优惠 $20 off"
```

### 销售数据分析
```bash
# 生成销售报表
shopify analytics report --store abc123

# 自定义 ShopifyQL 查询
shopify analytics query --store abc123 \
  --query "FROM orders SHOW sum(total_price) GROUP BY day SINCE -30d"
```

## 重要提示

- 所有命令都需要 `--store <storeId>` 参数，先用 `shopify auth stores` 获取
- 商品/订单/库存同步是从 **Shopify → Optima** 方向
- 折扣码在 **Shopify 平台**上创建和管理
- 连接店铺需要浏览器交互（OAuth 授权），在 AI Shell 中使用 `--url-only` + `auth check` 两步式流程
- 断开店铺是软删除，不会影响 Shopify 上的数据
- 使用 `--help` 查看命令详细参数
