@optima-chat/commerce-cli

v1.7.3

Published

12 hours ago

用自然语言管理电商店铺 - 专为 Claude Code 设计的对话式 CLI 工具，支持多环境和功能测试

0High
0Medium
0Low

optima-chat

optima commerce cli e-commerce claude-code ai natural-language

⚡️ Commerce CLI

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

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

网站 • 文档 • NPM • 问题反馈

🎯 简介

Commerce CLI 是 Optima Commerce 生态的命令行工具，专为 Claude Code 设计。

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

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

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

🎬 演示

Claude Code 自然语言交互

这是 Commerce CLI 最强大的功能 - 用自然语言管理电商店铺

计划展示场景：

💬 用中文对话创建商品
📦 自然语言查询订单
🚚 对话式订单发货
📊 智能库存管理

📹 演示内容录制中。参见 DEMO_GUIDE.md 查看录制计划

安装和基本使用

商品管理

✨ 核心特性

🤖 对话式操作 - 在 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. 安装

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

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

可用场景：

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

# 交互式选择场景
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 数据：

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 模式（人类可读）

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

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

使用场景：

JSON 模式（默认）：

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

Pretty 模式：

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

示例对比：

# 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📦 创建新商品? 商品名称: _ | | AI / CI/CD | 自动禁用交互，立即报错 | $ commerce product create⚠️ 缺少必需参数: --title |

🔧 环境变量控制

强制启用交互模式（终端检测失败时）：

export OPTIMA_INTERACTIVE=1

强制禁用交互模式：

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

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

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

FROM node:18-alpine

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

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

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

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

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

# 终端：显示确认提示
$ 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

📖 命令参考

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

🔐 认证管理

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 支持三个独立环境，各自拥有独立的配置文件：

| 环境 | Auth API | Commerce API | 前端域名 | 配置文件 | |------|----------|--------------|---------|----------| | Production（默认） | auth.optima.shop | api.optima.shop | optima.shop | config-prod.json | | Stage | auth-stage.optima.shop | api-stage.optima.shop | stage.optima.shop | config-stage.json | | Development | auth.optima.chat | api.optima.chat | optima.sh | config-dev.json |

配置文件位置：~/.config/commerce-cli/

# 登录到不同环境
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）：

# 设置环境变量后直接使用，无需 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 地址（适用于开发/测试环境）：

# 自定义 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

📦 商品管理

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

示例：

# 创建商品（带标签）
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/规格）

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 <...> # 添加变体图片

示例：

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

📋 订单管理

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>        # 标记已送达

示例：

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

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

💰 退款管理

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

示例：

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

📊 库存管理

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

示例：

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

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

🏪 商户管理

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

初始化商户资料示例：

# 交互式模式（适合本地使用）
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 "[email protected]"

# 带可选字段
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 "[email protected]" \
  --company-name "深圳某某科技有限公司"

必填字段：

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

🏠 首页配置

# 首页模块管理
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]         # 删除区块翻译

示例：

# 创建轮播图模块
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"

📚 集合管理

# 集合 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] # 删除集合翻译

示例：

# 创建夏季促销集合
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"

🚚 物流管理

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

示例：

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

🌍 运费区域管理

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>    # 添加运费费率

示例：

# 创建区域
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

📤 文件上传

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

💬 对话管理

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>        # 标记已读

💳 财务管理

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

🌐 国际化翻译

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

# 语言管理
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]

示例：

# 查看支持的语言
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 健康检查：

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

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

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

健康检查示例：

$ commerce test health

🏥 健康检查 - stage 环境

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

认证状态:
  ✓ 已登录

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

冒烟测试示例：

$ commerce test smoke

🧪 冒烟测试 - stage 环境

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

测试结果:
  ✓ 通过: 3

成功率: 100.0%

E2E 测试脚本：

# 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 会理解你的意图并调用正确的命令。

🛠 工具命令

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%（所有核心商户运营功能 + 测试工具）

🔧 开发

# 克隆仓库
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

🔗 相关链接

💬 支持

遇到问题？

提交 Issue
查看完整命令列表：commerce --help
联系团队：[email protected]

由 Optima Commerce Team 用 ❤️ 打造