npm package: @optima-chat/commerce-cli
Description: 用自然语言管理电商店铺 - 专为 Claude Code 设计的对话式 CLI 工具，支持多环境和功能测试
Author: Optima Commerce Team
Latest version: 1.18.1

<div align="center">

# ⚡️ Commerce CLI

### 用自然语言管理你的电商店铺

**专为 Claude Code 设计的对话式 CLI 工具**

[![NPM Version](https://img.shields.io/npm/v/@optima-chat/commerce-cli?style=flat&logo=npm&color=CB3837)](https://www.npmjs.com/package/@optima-chat/commerce-cli)
[![Downloads](https://img.shields.io/npm/dt/@optima-chat/commerce-cli?style=flat&logo=npm&color=CB3837)](https://www.npmjs.com/package/@optima-chat/commerce-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue?style=flat&logo=typescript)](https://www.typescriptlang.org/)
[![Node Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat&logo=node.js)](https://nodejs.org/)

[网站](https://cli.optima.shop) • [文档](https://github.com/Optima-Chat/commerce-cli#readme) • [NPM](https://www.npmjs.com/package/@optima-chat/commerce-cli) • [问题反馈](https://github.com/Optima-Chat/commerce-cli/issues)

</div>

---

## 🎯 简介

Commerce CLI 是 [Optima Commerce](https://www.optima.shop) 生态的命令行工具，**专为 Claude Code 设计**。

无需记住命令 - 直接用中文对话，Claude 会自动调用相应的 CLI 命令来管理你的电商店铺。

```bash
# 传统方式（需要记住命令）
commerce product create --title "陶瓷杯" --price 89 --stock 20

# Commerce CLI + Claude Code（自然语言）
"创建陶瓷杯商品，89 美元，库存 20" ✨
```

## 🎬 演示

### Claude Code 自然语言交互
> 这是 Commerce CLI 最强大的功能 - 用自然语言管理电商店铺

<!--
TODO: 录制演示 GIF 后取消注释
![Claude Code 演示](.github/assets/demo-claude-code.gif)
-->

**计划展示场景**：
- 💬 用中文对话创建商品
- 📦 自然语言查询订单
- 🚚 对话式订单发货
- 📊 智能库存管理

> 📹 演示内容录制中。参见 [DEMO_GUIDE.md](./docs/DEMO_GUIDE.md) 查看录制计划

### 安装和基本使用
<!--
TODO: 录制安装演示 GIF
![安装演示](.github/assets/demo-install.gif)
-->

### 商品管理
<!--
TODO: 录制商品管理演示 GIF
![商品管理演示](.github/assets/demo-product.gif)
-->

## ✨ 核心特性

- 🤖 **对话式操作** - 在 Claude Code 中用自然语言管理店铺，无需记住命令
- ⚡️ **即开即用** - 一行命令安装，自动配置 Claude Code 集成
- 📦 **功能完整** - 16 个模块，95+ 个命令，覆盖商品、订单、库存、物流、首页配置等全流程
- 🌍 **国际化支持** - 内置多语言翻译管理，支持商品、商户、集合、首页的国际化
- 🎨 **双输出模式** - 默认 JSON 格式（AI 友好），支持 `--pretty` 彩色表格输出
- 🤖 **AI 优先设计** - 所有命令默认 JSON 输出，可被 AI Agent 直接解析和处理
- 🔐 **安全可靠** - OAuth 2.0 Device Flow 认证，Token 自动刷新
- 🌐 **多环境隔离** - 支持 Production/Stage/Development 三环境，各自独立配置
- 🧪 **测试工具** - 内置健康检查、冒烟测试、E2E 测试脚本，可用作功能测试工具
- 🛠 **开发者友好** - TypeScript 类型安全，完善的错误处理，单元测试覆盖

## 🚀 快速开始

**要求**：Node.js >= 18

### 1. 安装

```bash
npm install -g @optima-chat/commerce-cli@latest
```

安装完成后，在项目中运行 `commerce init` 启用所需场景。支持 5 个场景化 Skills：

**可用场景**：
- 🛍️ **Product Management** - 商品管理（商品、变体、图片）
- 📦 **Order Fulfillment** - 订单履行（发货、退款）
- 📊 **Inventory Management** - 库存管理（监控、补货）
- 🏪 **Storefront Configuration** - 店铺配置（首页、集合）
- 🌍 **Internationalization** - 国际化（多语言翻译）

```bash
# 交互式选择场景
commerce init

# 或直接指定场景
commerce init --skills product,order
```

### 2. 登录你的账号

在 Claude Code 中，你可以用自然语言说：

```
"登录 Optima"
"Optima 登录"
"帮我登录到 Optima"
```

Claude 会自动打开浏览器引导你完成 OAuth 授权。

### 3. 开始用自然语言管理店铺 ✨

在 Claude Code 中，你可以这样说：

```
- "创建珍珠耳环商品，299 美元，库存 10"
- "查看今天的订单"
- "订单 order_123 发货，快递单号 DHL123456"
- "库存低于 5 的商品"
- "商品 prod_123 改价 399"
- "给商品添加中文翻译"
```

Claude 会自动调用对应的 `commerce` 命令来完成操作。

**就是这么简单！** 🎉

## 📦 功能模块

Commerce CLI 提供 **16 个功能模块**，**95+ 个命令**，覆盖电商全流程：

| 模块 | 命令数 | 说明 |
|------|--------|------|
| 🔐 **auth** | 4 | OAuth 2.0 认证（login, logout, whoami, switch）+ 多环境支持 |
| 📦 **product** | 7 | 商品 CRUD，图片管理，URL |
| 🎨 **variant** | 6 | SKU/规格管理 |
| 📋 **order** | 6 | 订单查询、发货、取消、标记送达 |
| 💰 **refund** | 2 | 退款创建和查询 |
| 📊 **inventory** | 4 | 库存预警、调整、历史、预留 |
| 🏪 **merchant** | 4 | 商户资料管理，URL |
| 🏠 **homepage** | 13 | 首页配置（CRUD、设置、重排序、翻译） |
| 📚 **collection** | 13 | 集合管理（CRUD、产品关联、翻译） |
| 🚚 **shipping** | 3 | 运费计算、物流历史、状态更新 |
| 🌍 **shipping-zone** | 5 | 运费区域和费率配置 |
| 📤 **upload** | 3 | 图片、视频、文件上传 |
| 💬 **conversation** | 7 | 客服对话管理 |
| 💳 **transfer** | 2 | 财务转账和汇总 |
| 🌐 **i18n** | 24 | 多语言翻译管理（商品/变体/集合/商户/首页） |
| 🧪 **test** | 2 | 健康检查、冒烟测试（功能测试工具） |

## 🎨 输出格式

Commerce CLI 支持两种输出格式，适用于不同场景：

### JSON 模式（默认，AI 友好）

适合 AI Agent 和程序化处理，返回结构化 JSON 数据：

```bash
commerce product list --limit 2
# 输出标准 JSON 格式
{
  "success": true,
  "data": {
    "products": [...],
    "total": 2,
    "page": 1,
    "has_next": false
  }
}
```

**JSON 输出特性**：
- ✅ 所有 93 个命令默认输出 JSON 格式
- ✅ 统一的响应格式：`{ success, data, message?, error? }`
- ✅ 完整的数据结构，无信息丢失
- ✅ 适合 AI Agent 解析和自动化脚本
- ✅ 向后兼容：可使用 `--pretty` 切换到表格模式

### Pretty 模式（人类可读）

适合人类阅读，提供彩色终端输出和表格化数据：

```bash
commerce product list --limit 2 --pretty
# 输出彩色表格，包含商品名称、价格、库存等
```

**使用场景**：

**JSON 模式**（默认）：
- AI Agent 调用（如 Claude Code）
- 自动化脚本和 CI/CD 流程
- 需要解析数据的程序
- 数据导出和集成

**Pretty 模式**：
- 在终端手动执行命令
- 快速查看数据和调试
- 人类可读性优先

**示例对比**：

```bash
# JSON 模式（AI 友好，默认）
$ commerce merchant info
{
  "success": true,
  "data": {
    "merchant": {
      "id": "...",
      "name": "徐昊的全球小店",
      "slug": "xuhao-global-store",
      "default_currency": "USD",
      ...
    }
  }
}

# Pretty 模式（人类友好）
$ commerce merchant info --pretty
✔ 商户信息获取成功

店铺名称: 徐昊的全球小店
店铺 Slug: xuhao-global-store
默认货币: USD
...
```

> **提示**：在 Claude Code 中，Claude 会根据需要自动选择合适的输出格式。

## 🤖 非交互模式 / CI/CD

**v0.16.0 新增**：Commerce CLI 现在支持智能环境检测，自动适配终端用户和 AI/CI/CD 环境！

### 🎯 自动环境检测

Commerce CLI 自动检测运行环境，无需手动配置：

| 环境 | 行为 | 示例 |
|------|------|------|
| **终端** | 缺少参数时显示友好交互提示 | `$ commerce product create`<br>📦 创建新商品<br>? 商品名称: _ |
| **AI / CI/CD** | 自动禁用交互，立即报错 | `$ commerce product create`<br>⚠️ 缺少必需参数: --title |

### 🔧 环境变量控制

**强制启用交互模式**（终端检测失败时）：
```bash
export OPTIMA_INTERACTIVE=1
```

**强制禁用交互模式**：
```bash
export NON_INTERACTIVE=1
# 或
export OPTIMA_NON_INTERACTIVE=true
```

**CI 环境自动检测**：
- GitHub Actions (`CI=true`)
- GitLab CI (`GITLAB_CI=true`)
- Jenkins (`JENKINS_URL` 存在)
- Travis CI (`TRAVIS=true`)
- 等其他 CI 平台

### 💻 CI/CD 使用示例

#### GitHub Actions

```yaml
name: Deploy Products
on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Commerce CLI
        run: npm install -g @optima-chat/commerce-cli

      - name: Create Products
        env:
          OPTIMA_TOKEN: ${{ secrets.OPTIMA_TOKEN }}
        run: |
          # CI 环境自动禁用交互提示
          commerce product create \
            --title "自动化商品" \
            --price 99 \
            --stock 100

          # 删除操作需要 --yes 确认
          commerce product delete --id prod-123 --yes
```

#### GitLab CI

```yaml
stages:
  - deploy

deploy_products:
  stage: deploy
  image: node:18
  before_script:
    - npm install -g @optima-chat/commerce-cli
  script:
    # CI 环境自动检测，无需额外配置
    - commerce product list --json > products.json
    - commerce product create --title "新商品" --price 49
  variables:
    OPTIMA_TOKEN: $OPTIMA_TOKEN
```

#### Docker

```dockerfile
FROM node:18-alpine

RUN npm install -g @optima-chat/commerce-cli

# 非交互环境，需提供所有参数
CMD ["commerce", "product", "list", "--json"]
```

```bash
# 运行容器
docker run -e OPTIMA_TOKEN=$OPTIMA_TOKEN commerce-cli
```

### ✅ 确认操作（`--yes` 标志）

删除、取消等危险操作在终端和 CI 环境都需要明确确认：

```bash
# 终端：显示确认提示
$ commerce product delete --id prod-123
⚠️  即将删除商品: prod-123
? 确定要删除此商品吗？ (y/N)

# CI/CD：使用 --yes 跳过确认
$ commerce product delete --id prod-123 --yes
✓ 商品删除成功！
```

需要 `--yes` 的命令：
- `product delete`, `variant delete`
- `order cancel`, `order complete`
- `shipping-zone delete`
- `cleanup`

### 📋 受影响的命令（17 个）

以下命令支持自动环境检测：

| 类别 | 命令 | 非交互要求 |
|------|------|-----------|
| **核心** | `shipping calculate`, `product create`, `order ship` | 提供所有必需参数 |
| **常用** | `variant create`, `inventory update/reserve`, `shipping-zone create/add-rate` | 提供所有必需参数 |
| **确认** | `product/variant delete`, `order cancel/complete`, `cleanup` | 添加 `--yes` 标志 |
| **i18n** | `i18n product/merchant create` | 提供 `--lang` 和 `--name` |

### 📚 更多信息

完整技术文档请参阅 [`docs/NON_INTERACTIVE_MODE_DESIGN.md`](./docs/NON_INTERACTIVE_MODE_DESIGN.md)

---

## 📖 命令参考

> **提示**：推荐通过 Claude Code 用自然语言调用，以下为完整命令参考。

### 🔐 认证管理

```bash
commerce auth login                        # OAuth 登录到生产环境（默认）
commerce auth login --env stage            # OAuth 登录到 Stage 环境
commerce auth login --env development      # OAuth 登录到开发环境
commerce auth whoami                       # 查看当前用户和环境信息
commerce auth switch --env stage           # 切换到 Stage 环境（无需重新登录）
commerce auth logout                       # 登出当前环境
commerce auth logout --env stage           # 登出指定环境
commerce auth logout --all                 # 登出所有环境
```

**多环境支持**（v0.19.0+）：

Commerce CLI 支持三个独立环境，共享统一的 token 文件：

| 环境 | Auth API | Commerce API | 店铺前端域名 | token.json env |
|------|----------|--------------|------------|----------------|
| Production（默认） | auth.optima.shop | api.optima.shop | optima.shop | `prod` |
| **Stage** | **auth.stage.optima.onl** | **api.stage.optima.onl** | **store.stage.optima.onl** | `stage` |
| Development | auth.optima.chat | api.optima.chat | optima.sh | `ci` |

**Token 文件位置**：`~/.optima/token.json`（所有环境共享）

```bash
# 登录到不同环境
commerce auth login                        # Production（默认）
commerce auth login --env stage            # Stage 预发布环境
commerce auth login --env development      # Development 开发环境

# 切换环境（无需重新登录）
commerce auth switch --env stage           # 切换到 Stage
commerce auth switch --env production      # 切换回 Production

# 查看当前环境
commerce auth whoami                       # 显示环境、用户、API URLs

# 环境配置会持久化，后续命令自动使用当前环境
commerce merchant url                      # 根据当前环境返回正确的店铺域名
```

**环境变量认证**（适用于容器/CI/CD）：

```bash
# 设置环境变量后直接使用，无需 commerce auth login
export OPTIMA_TOKEN=<your_access_token>
commerce product list

# Docker 容器
docker run -e OPTIMA_TOKEN=<your_token> commerce-cli product list

# CI/CD 流水线
export OPTIMA_TOKEN=${{ secrets.OPTIMA_TOKEN }}
commerce product create --title "商品"
```

**认证优先级**：`OPTIMA_TOKEN` 环境变量 > 配置文件（`~/.config/commerce-cli`）

**自定义 Backend 地址**（适用于开发/测试环境）：

```bash
# 自定义 Commerce API 地址
export OPTIMA_API_URL=http://localhost:8000
commerce product list

# 自定义 Auth API 地址
export OPTIMA_AUTH_URL=http://localhost:3000
commerce auth login

# Docker 开发环境
docker run \
  -e OPTIMA_TOKEN=<your_token> \
  -e OPTIMA_API_URL=http://host.docker.internal:8000 \
  commerce-cli product list
```

**默认 Backend**：
- Commerce API: `https://api.optima.shop`
- Auth API: `https://auth.optima.shop`

### 📦 商品管理

```bash
commerce product create [--tags <tags>]                # 创建商品（支持标签）
commerce product list [--limit 20] [--tags <tags>]     # 商品列表（支持标签筛选）
commerce product get --id <id>                          # 商品详情
commerce product update --id <id> [--tags <tags>]      # 更新商品（支持标签）
commerce product delete --id <id> [-y]                  # 删除商品
commerce product add-images --id <id> --path <...>     # 添加本地图片
commerce product add-images --id <id> --url <...>      # 添加图片URL
```

**示例**：

```bash
# 创建商品（带标签）
commerce product create \
  --title "手工陶瓷杯" \
  --price 89 \
  --currency USD \
  --stock 20 \
  --description "精美手工制作" \
  --tags "featured,new,handmade"

# 更新商品
commerce product update --id prod_123 \
  --price 99 \
  --stock 50 \
  --tags "featured,sale"

# 按标签筛选商品
commerce product list --tags "featured,new"

# 添加本地图片
commerce product add-images --id prod_123 --path ./img1.jpg ./img2.jpg

# 添加图片 URL（避免重复上传）
commerce product add-images --id prod_123 --url https://example.com/image.jpg

# 混合使用
commerce product add-images --id prod_123 --path ./local.jpg --url https://example.com/remote.jpg
```

### 🎨 商品变体（SKU/规格）

```bash
commerce variant list --product-id <product-id>                              # 变体列表
commerce variant create --product-id <product-id>                            # 创建变体
commerce variant get --product-id <product-id> --id <id>                     # 变体详情
commerce variant update --product-id <product-id> --id <id>                  # 更新变体
commerce variant delete --product-id <product-id> --id <id> [-y]             # 删除变体
commerce variant add-images --product-id <product-id> --id <id> --path <...> # 添加变体图片
```

**示例**：

```bash
# 创建变体
commerce variant create --product-id prod_123 \
  --sku "CUP-S-WHITE" \
  --price 89 \
  --stock 10 \
  --attributes '{"size":"S","color":"White"}'
```

### 📋 订单管理

```bash
commerce order list [--status pending]        # 订单列表
commerce order get --id <id>                   # 订单详情
commerce order ship --id <id>                  # 订单发货
commerce order complete --id <id>              # 完成订单
commerce order cancel --id <id>                # 取消订单
commerce order mark-delivered --id <id>        # 标记已送达
```

**示例**：

```bash
# 发货
commerce order ship --id order_123 \
  --tracking DHL123456 \
  --carrier DHL

# 取消订单
commerce order cancel --id order_456 \
  --reason "客户要求取消" \
  --yes
```

### 💰 退款管理

```bash
commerce refund create --order-id <order-id>    # 创建退款
commerce refund get --id <id>                   # 退款详情
```

**示例**：

```bash
# 创建退款
commerce refund create --order-id order_123 \
  --amount 50 \
  --reason requested_by_customer
```

### 📊 库存管理

```bash
commerce inventory low-stock [--threshold 5]    # 低库存商品
commerce inventory update --id <id>             # 更新库存
commerce inventory history --id <id>            # 库存历史
commerce inventory reserve --id <id>            # 预留库存
```

**示例**：

```bash
# 查看低库存
commerce inventory low-stock --threshold 10

# 更新库存
commerce inventory update --id prod_123 \
  --quantity 50 \
  --reason "补货"
```

### 🏪 商户管理

```bash
commerce merchant info          # 获取商户信息
commerce merchant update        # 更新商户资料
commerce merchant setup         # 初始化商户资料（首次使用）
commerce merchant url [--open]  # 获取店铺链接（可在浏览器打开）
```

**初始化商户资料示例**：

```bash
# 交互式模式（适合本地使用）
commerce merchant setup

# 非交互式模式（适合容器/CI/CD，所有必填字段通过参数提供）
commerce merchant setup \
  --name "我的店铺" \
  --origin-country-alpha2 HK \
  --origin-city Saikung \
  --origin-state "New Territories" \
  --origin-line-1 "G/F NO.93, TAI PO TSAI VILLAGE" \
  --contact-name "XU, HAO" \
  --contact-phone "53736279" \
  --contact-email "merchant@example.com"

# 带可选字段
commerce merchant setup \
  --name "我的店铺" \
  --description "高品质商品" \
  --slug "my-store" \
  --default-currency USD \
  --origin-country-alpha2 CN \
  --origin-city "深圳" \
  --origin-state "广东省" \
  --origin-line-1 "南山区科技园" \
  --origin-line-2 "创业大厦10楼" \
  --origin-postal-code "518000" \
  --contact-name "张三" \
  --contact-phone "13800138000" \
  --contact-email "merchant@example.com" \
  --company-name "深圳某某科技有限公司"
```

**必填字段**：
- `--name`: 商户名称
- `--origin-country-alpha2`: 发货国家代码（2位，如 CN, US, HK）
- `--origin-city`: 发货城市
- `--origin-state`: 发货省/州
- `--origin-line-1`: 发货地址第一行
- `--contact-name`: 联系人姓名
- `--contact-phone`: 联系电话
- `--contact-email`: 联系邮箱

### 🏠 首页配置

```bash
# 首页模块管理
commerce homepage module list                      # 查看所有首页模块
commerce homepage module get --slug <slug>         # 获取模块详情
commerce homepage module create                    # 创建首页模块
commerce homepage module update --slug <slug>      # 更新模块
commerce homepage module delete --slug <slug> [-y] # 删除模块
commerce homepage module reorder                   # 重新排序模块

# 首页设置
commerce homepage settings get                     # 获取首页设置
commerce homepage settings update                  # 更新首页设置

# 首页统计
commerce homepage analytics                        # 查看首页分析数据

# 首页区块翻译
commerce i18n homepage list --section-id <id>                              # 查看区块的所有翻译
commerce i18n homepage set --section-id <id> --lang <lang> --title <text>  # 创建/更新区块翻译
commerce i18n homepage delete --section-id <id> --lang <lang> [-y]         # 删除区块翻译
```

**示例**：

```bash
# 创建轮播图模块
commerce homepage module create \
  --slug hero-banner \
  --type banner \
  --position 1 \
  --enabled true \
  --config '{"images":[{"url":"https://example.com/banner.jpg","alt":"Summer Sale"}]}'

# 更新首页设置
commerce homepage settings update \
  --show-search true \
  --show-categories true \
  --featured-limit 8

# 为首页区块添加中英文翻译
commerce i18n homepage set \
  --section-id section-123 \
  --lang zh-CN \
  --title "精选商品" \
  --description "查看我们最受欢迎的产品"

commerce i18n homepage set \
  --section-id section-123 \
  --lang en-US \
  --title "Featured Products" \
  --description "Discover our most popular items"
```

### 📚 集合管理

```bash
# 集合 CRUD
commerce collection list                           # 查看所有集合
commerce collection get --slug <slug>              # 获取集合详情
commerce collection create                         # 创建集合
commerce collection update --slug <slug>           # 更新集合
commerce collection delete --slug <slug> [-y]      # 删除集合

# 集合产品关联
commerce collection add-products --slug <slug>     # 添加产品到集合
commerce collection remove-products --slug <slug>  # 从集合移除产品

# 集合翻译
commerce i18n collection list --collection-id <id> # 查看集合翻译列表
commerce i18n collection get --collection-id <id> --lang <lang>  # 获取特定语言翻译
commerce i18n collection create --collection-id <id>              # 创建集合翻译
commerce i18n collection update --collection-id <id> --lang <lang> # 更新集合翻译
commerce i18n collection delete --collection-id <id> --lang <lang> [-y] # 删除集合翻译
```

**示例**：

```bash
# 创建夏季促销集合
commerce collection create \
  --name "Summer Sale" \
  --slug summer-sale \
  --description "Hot deals for summer" \
  --image-url "https://example.com/summer.jpg"

# 添加产品到集合
commerce collection add-products --slug summer-sale \
  --product-ids prod_123,prod_456,prod_789

# 添加西班牙语翻译
commerce i18n collection create \
  --collection-id coll_123 \
  --lang es-ES \
  --name "Promoción de Verano" \
  --description "Ofertas calientes para el verano"
```

### 🚚 物流管理

```bash
commerce shipping calculate                     # 计算运费
commerce shipping history --order-id <order-id> # 物流历史
commerce shipping update-status --id <id>       # 更新物流状态
```

**示例**：

```bash
# 计算运费
commerce shipping calculate \
  --country US \
  --postal-code 10001 \
  --weight 0.5
```

### 🌍 运费区域管理

```bash
commerce shipping-zone list                            # 运费区域列表
commerce shipping-zone create                          # 创建运费区域
commerce shipping-zone delete --id <id> [-y]           # 删除运费区域
commerce shipping-zone list-rates --zone-id <zone-id>  # 查看区域费率
commerce shipping-zone add-rate --zone-id <zone-id>    # 添加运费费率
```

**示例**：

```bash
# 创建区域
commerce shipping-zone create \
  --name "北美区域" \
  --countries US,CA,MX

# 添加费率
commerce shipping-zone add-rate --zone-id zone_123 \
  --price 15 \
  --currency USD \
  --min-weight 0 \
  --free-threshold 100
```

### 📤 文件上传

```bash
commerce upload image --path <path>    # 上传图片
commerce upload video --path <path>    # 上传视频
commerce upload file --path <path>     # 上传文件
```

### 💬 对话管理

```bash
commerce conversation list                       # 对话列表
commerce conversation get --id <id>              # 对话详情
commerce conversation create                     # 创建对话
commerce conversation close --id <id>            # 关闭对话
commerce conversation messages --id <id>         # 查看消息
commerce conversation send --id <id>             # 发送消息
commerce conversation mark-read --id <id>        # 标记已读
```

### 💳 财务管理

```bash
commerce transfer list       # 转账列表
commerce transfer summary    # 财务汇总
```

### 🌐 国际化翻译

Commerce CLI 内置完整的多语言翻译管理系统：

```bash
# 语言管理
commerce i18n languages [--all]    # 查看支持的语言

# 商品翻译
commerce i18n product list --product-id <product-id>
commerce i18n product get --product-id <product-id> --lang <lang>
commerce i18n product create --product-id <product-id>
commerce i18n product update --product-id <product-id> --lang <lang>
commerce i18n product delete --product-id <product-id> --lang <lang> [-y]

# 商户翻译
commerce i18n merchant list
commerce i18n merchant get --lang <lang>
commerce i18n merchant create
commerce i18n merchant update --lang <lang>
commerce i18n merchant delete --lang <lang> [-y]

# 变体翻译
commerce i18n variant list --variant-id <variant-id>
commerce i18n variant get --variant-id <variant-id> --lang <lang>
commerce i18n variant create --variant-id <variant-id>
commerce i18n variant update --variant-id <variant-id> --lang <lang>
commerce i18n variant delete --variant-id <variant-id> --lang <lang> [-y]

# 集合翻译
commerce i18n collection list --collection-id <collection-id>
commerce i18n collection get --collection-id <collection-id> --lang <lang>
commerce i18n collection create --collection-id <collection-id>
commerce i18n collection update --collection-id <collection-id> --lang <lang>
commerce i18n collection delete --collection-id <collection-id> --lang <lang> [-y]

# 首页区块翻译
commerce i18n homepage list --section-id <id>
commerce i18n homepage set --section-id <id> --lang <lang> --title <text>
commerce i18n homepage delete --section-id <id> --lang <lang> [-y]
```

**示例**：

```bash
# 查看支持的语言
commerce i18n languages

# 为商品添加中文翻译
commerce i18n product create --product-id prod_123 \
  --lang zh-CN \
  --name "手工陶瓷杯" \
  --description "精美的手工制作陶瓷杯" \
  --meta-title "手工陶瓷杯 - 传统工艺"

# 为变体添加翻译（注意：使用 --variant-id 而非 --product-id）
commerce i18n variant create --variant-id var_456 \
  --lang ja-JP \
  --name "セラミックマグ" \
  --variant-attributes-translations '{"size":{"key_translation":"サイズ","value_translation":{"S":"小"}},"color":{"key_translation":"色","value_translation":{"白":"白"}}}'

# 为集合添加翻译
commerce i18n collection create --collection-id coll_789 \
  --lang es-ES \
  --name "Promoción de Verano" \
  --description "Colección especial de verano"
```

### 🧪 测试工具

Commerce CLI 内置测试工具，可用作功能测试和 API 健康检查：

```bash
# 健康检查（检查 API 连通性和响应时间）
commerce test health

# 冒烟测试（测试核心 API 端点）
commerce test smoke

# 端到端测试脚本（适用于 CI/CD）
export OPTIMA_TOKEN=your_token
export TEST_ENV=stage
./scripts/e2e-test.sh
```

**健康检查示例**：
```bash
$ commerce test health

🏥 健康检查 - stage 环境

检查 Auth API...
  ✓ Auth API 健康 (120ms)
检查 Commerce API...
  ✓ Commerce API 健康 (150ms)

认证状态:
  ✓ 已登录

总体状态:
  ✓ 所有服务正常
```

**冒烟测试示例**：
```bash
$ commerce test smoke

🧪 冒烟测试 - stage 环境

1. 测试商户信息 API...
   ✓ 成功 (120ms) - 商户: My Store
2. 测试商品列表 API...
   ✓ 成功 (150ms) - 5 个商品
3. 测试订单列表 API...
   ✓ 成功 (180ms) - 3 个订单

测试结果:
  ✓ 通过: 3

成功率: 100.0%
```

**E2E 测试脚本**：
```bash
# scripts/e2e-test.sh 执行完整业务流程测试
# 1. 健康检查
# 2. 冒烟测试
# 3. 创建测试商品
# 4. 验证商品
# 5. 清理测试数据

# 在 CI/CD 中使用
- name: Run E2E tests
  env:
    OPTIMA_TOKEN: ${{ secrets.OPTIMA_TOKEN_STAGE }}
    TEST_ENV: stage
  run: ./scripts/e2e-test.sh
```

**特点**：
- ✅ 默认 JSON 输出，易于解析
- ✅ 测试失败时退出码为 1（CI/CD 友好）
- ✅ 支持多环境测试
- ✅ 详细的错误信息和响应时间

## 💬 自然语言示例

在 Claude Code 中，你可以用非常简洁的自然语言描述需求：

**认证和环境**：
- "登录 Optima"
- "登录到 Stage 环境"
- "切换到生产环境"
- "查看我的账号信息"
- "打开我的店铺"
- "切换到开发环境"

**商品管理**：
- "创建陶瓷杯商品，89 美元，库存 20"
- "查看所有商品"
- "商品 prod_123 改价 99"
- "删除商品 prod_456"
- "给商品 prod_789 添加这张图片"
- "把产品 handle 改成英文"
- "创建白色 S 码变体，SKU 为 CUP-S-WHITE"

**订单处理**：
- "今天的订单"
- "待发货订单"
- "订单 order_123 详情"
- "订单 order_456 发货，快递单号 DHL123456"
- "取消订单 order_789"
- "标记订单 order_123 已送达"

**库存管理**：
- "库存低于 5 的商品"
- "商品 prod_123 库存改为 50"
- "查看商品 prod_456 的库存历史"
- "预留商品 prod_789 的 10 个库存"

**物流管理**：
- "计算从香港到纽约的运费，0.5 公斤"
- "查看订单 order_123 的物流历史"
- "创建北美运费区域，包含 US、CA、MX"

**国际化管理**：
- "查看支持的语言"
- "给商品 prod_123 添加中文翻译"
- "更新商品 prod_456 的日语翻译"
- "查看商户的所有翻译"
- "给变体 var_123 添加日语翻译"
- "给集合 coll_456 添加西班牙语翻译"

**首页配置**：
- "查看首页所有模块"
- "创建轮播图模块"
- "更新首页设置，启用搜索栏"
- "重新排序首页模块"
- "给首页添加中文翻译"

**集合管理**：
- "创建夏季促销集合"
- "查看所有集合"
- "给集合 coll_123 添加商品 prod_456"
- "从集合中移除商品"
- "给集合添加西班牙语翻译"

**客服管理**：
- "查看所有对话"
- "创建新的客户对话"
- "给对话 conv_123 发送消息"

**测试工具**：
- "检查 API 健康状态"
- "运行冒烟测试"
- "测试 Stage 环境的服务"

> **提示**：说话越自然越好，Claude 会理解你的意图并调用正确的命令。

## 🛠 工具命令

```bash
commerce init            # 在当前项目启用 Commerce CLI（创建 Claude Skill）
commerce cleanup         # 清理配置文件
commerce version         # 显示版本信息
```

## 🏗 项目状态

**当前版本：v1.0.0** 🎉

✅ **已完成功能**：
- ✅ 完整的 OAuth 2.0 认证系统（Device Flow + 自动刷新）
- ✅ 16 个核心功能模块（新增 test 测试模块）
- ✅ 95+ 个完整命令
- ✅ 默认 JSON 输出（AI 优先设计）
- ✅ 双输出模式（JSON + Pretty）
- ✅ 国际化翻译管理系统（支持 5 种语言）
- ✅ 首页配置管理（模块化组件 + 多语言）
- ✅ 集合管理（CRUD + 产品关联 + 翻译）
- ✅ **三环境隔离支持**（Production/Stage/Development）
- ✅ **测试工具集成**（健康检查 + 冒烟测试 + E2E 脚本）
- ✅ Claude Code 深度集成
- ✅ 完善的错误处理和用户提示
- ✅ 单元测试覆盖（19 tests, 81% coverage）
- ✅ 交互式命令提示
- ✅ 智能环境检测（终端 vs AI/CI）

**功能覆盖率**：100%（所有核心商户运营功能 + 测试工具）

## 🔧 开发

```bash
# 克隆仓库
git clone https://github.com/Optima-Chat/commerce-cli.git
cd commerce-cli

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 构建
npm run build

# 测试
npm test                 # 运行所有测试
npm run test:watch       # 监听模式
npm run test:coverage    # 生成覆盖率报告

# 发布到 NPM
npm version minor        # 升级版本号
git push --follow-tags   # 推送触发自动发布
```

## 📚 技术栈

- **语言**：TypeScript 5.3
- **CLI 框架**：Commander.js
- **HTTP 客户端**：Axios
- **交互提示**：Inquirer.js
- **UI 组件**：Chalk（颜色）+ cli-table3（表格）+ Ora（加载动画）
- **配置存储**：Conf（加密）
- **认证**：OAuth 2.0 Device Flow
- **测试**：Jest + ts-jest（19 tests, 81% coverage）

## 📝 许可证

[MIT License](./LICENSE)

## 🔗 相关链接

- [Optima Commerce 官网](https://www.optima.shop)
- [Agentic Chat](https://ai.optima.chat) - 卖家对话界面
- [Optima Store](https://go.optima.shop) - 买家购物前端
- [Claude Code](https://claude.com/claude-code)
- [NPM Package](https://www.npmjs.com/package/@optima-chat/commerce-cli)
- [GitHub Issues](https://github.com/Optima-Chat/commerce-cli/issues)

## 💬 支持

遇到问题？

- 提交 [Issue](https://github.com/Optima-Chat/commerce-cli/issues)
- 查看完整命令列表：`commerce --help`
- 联系团队：support@optima.chat

---

**由 [Optima Commerce Team](https://www.optima.shop) 用 ❤️ 打造**