@optima-chat/commerce-cli 1.0.0

package/README.md

@@ -0,0 +1,1132 @@
+<div align="center">
+
+# ⚡️ Optima 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/optima-cli#readme) • [NPM](https://www.npmjs.com/package/@optima-chat/commerce-cli) • [问题反馈](https://github.com/Optima-Chat/optima-cli/issues)
+
+</div>
+
+---
+
+## 🎯 简介
+
+Optima CLI 是 [Optima Commerce](https://www.optima.shop) 生态的命令行工具，**专为 Claude Code 设计**。
+
+无需记住命令 - 直接用中文对话，Claude 会自动调用相应的 CLI 命令来管理你的电商店铺。
+
+```bash
+# 传统方式（需要记住命令）
+commerce product create --title "陶瓷杯" --price 89 --stock 20
+
+# Optima CLI + Claude Code（自然语言）
+"创建陶瓷杯商品，89 美元，库存 20" ✨
+```
+
+## 🎬 演示
+
+### Claude Code 自然语言交互
+> 这是 Optima 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
+```
+
+安装完成后会自动配置 Claude Code 集成。如需在项目中启用，对 Claude 说：
+
+```
+"在这个项目启用 Optima CLI"
+```
+
+### 2. 登录你的账号
+
+在 Claude Code 中，你可以用自然语言说：
+
+```
+"登录 Optima"
+"Optima 登录"
+"帮我登录到 Optima"
+```
+
+Claude 会自动打开浏览器引导你完成 OAuth 授权。
+
+### 3. 开始用自然语言管理店铺 ✨
+
+在 Claude Code 中，你可以这样说：
+
+```
+- "创建珍珠耳环商品，299 美元，库存 10"
+- "查看今天的订单"
+- "订单 order_123 发货，快递单号 DHL123456"
+- "库存低于 5 的商品"
+- "商品 prod_123 改价 399"
+- "给商品添加中文翻译"
+```
+
+Claude 会自动调用对应的 `optima` 命令来完成操作。
+
+**就是这么简单！** 🎉
+
+## 📦 功能模块
+
+Optima 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 | 健康检查、冒烟测试（功能测试工具） |
+
+## 🎨 输出格式
+
+Optima 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 新增**：Optima CLI 现在支持智能环境检测，自动适配终端用户和 AI/CI/CD 环境！
+
+### 🎯 自动环境检测
+
+Optima 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 Optima 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 ["optima", "product", "list", "--json"]
+```
+
+```bash
+# 运行容器
+docker run -e OPTIMA_TOKEN=$OPTIMA_TOKEN optima-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+）：
+
+Optima 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/optima-cli/`
+
+```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> optima-cli product list
+
+# CI/CD 流水线
+export OPTIMA_TOKEN=${{ secrets.OPTIMA_TOKEN }}
+commerce product create --title "商品"
+```
+
+**认证优先级**：`OPTIMA_TOKEN` 环境变量 > 配置文件（`~/.config/optima-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 \
+  optima-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    # 财务汇总
+```
+
+### 🌐 国际化翻译
+
+Optima 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"
+```
+
+### 🧪 测试工具
+
+Optima 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            # 在当前项目启用 Optima CLI
+commerce cleanup         # 清理配置文件
+commerce version         # 显示版本信息
+```
+
+## 🏗 项目状态
+
+**当前版本：v0.19.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%（所有核心商户运营功能 + 测试工具）
+
+**最近更新**：
+
+**v0.19.0**（2025-11-13）：
+- 🌐 **三环境架构**：新增 Stage 环境，支持 Production/Stage/Development 完全隔离
+- 🔐 **多文件配置**：每个环境独立配置文件（config-prod.json, config-stage.json, config-dev.json）
+- 🔄 **环境切换命令**：新增 `auth switch` 命令，无需重新登录即可切换环境
+- 🧪 **测试模块**：新增 `test health` 和 `test smoke` 命令
+- 📜 **E2E 测试脚本**：`scripts/e2e-test.sh` 用于 CI/CD 集成
+- 🛠️ **认证命令增强**：`whoami` 显示环境信息，`logout` 支持 `--env` 和 `--all`
+- 📚 **完整文档更新**：CLAUDE.md 和 README.md 包含所有新功能
+
+**v0.18.1**（2025-11-11）：
+- 🐛 修复：开发环境店铺域名使用正确的 `optima.sh`
+- 🛠️ 优化：统一店铺域名管理，自动根据环境选择
+
+**v0.18.0**（2025-11-11）：
+- 🌍 新增：环境支持（`--env development` 参数）
+- 🔐 支持生产和开发环境切换
+- 🎯 自动选择对应的 OAuth Client ID 和 API 端点
+- 🔄 环境配置持久化
+
+## 🔧 开发
+
+```bash
+# 克隆仓库
+git clone https://github.com/Optima-Chat/optima-cli.git
+cd optima-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/optima-cli/issues)
+
+## 💬 支持
+
+遇到问题？
+
+- 提交 [Issue](https://github.com/Optima-Chat/optima-cli/issues)
+- 查看 [完整命令列表](.claude/CLAUDE.md)
+- 联系团队：support@optima.chat
+
+---
+
+**由 [Optima Commerce Team](https://www.optima.shop) 用 ❤️ 打造**