@optima-chat/commerce-cli 1.0.0 → 1.2.0

package/.claude/skills/commerce-i18n/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: commerce-i18n
+description: Internationalization and translation management. Add multilingual translations for products, variants, collections, merchant info, homepage sections. Use when user needs to translate content, manage multiple languages, or configure i18n settings.
+---
+
+# Commerce CLI - Internationalization
+
+## Overview
+
+国际化模块，用于管理商品、变体、集合、商户和首页的多语言翻译。
+
+## Instructions
+
+### 自然语言映射
+
+当用户说：
+- "给商品添加中文翻译" → `commerce i18n product create --product-id XX --lang zh-CN`
+- "翻译商品变体" → `commerce i18n variant create --variant-id XX --lang YY`
+- "翻译集合信息" → `commerce i18n collection create --collection-id XX --lang YY`
+- "设置商户多语言信息" → `commerce i18n merchant create --lang XX`
+- "翻译首页区块" → `commerce i18n homepage set --section-id XX --lang YY`
+
+### 核心功能
+
+**商品翻译**:
+- `commerce i18n product create` - 创建商品翻译
+- `commerce i18n product list` - 查看商品翻译列表
+- `commerce i18n product get` - 查看单个翻译
+- `commerce i18n product update` - 更新翻译
+- `commerce i18n product delete` - 删除翻译
+
+**变体翻译**:
+- `commerce i18n variant create` - 创建变体翻译
+- `commerce i18n variant list` - 查看变体翻译
+- `commerce i18n variant update` - 更新变体翻译
+- `commerce i18n variant delete` - 删除变体翻译
+
+**集合翻译**:
+- `commerce i18n collection create` - 创建集合翻译
+- `commerce i18n collection list` - 查看集合翻译
+- `commerce i18n collection update` - 更新集合翻译
+- `commerce i18n collection delete` - 删除集合翻译
+
+**商户翻译**:
+- `commerce i18n merchant create` - 创建商户翻译
+- `commerce i18n merchant list` - 查看商户翻译
+- `commerce i18n merchant update` - 更新商户翻译
+- `commerce i18n merchant delete` - 删除商户翻译
+
+**首页翻译**:
+- `commerce i18n homepage set` - 设置首页区块翻译
+- `commerce i18n homepage list` - 查看首页翻译
+- `commerce i18n homepage delete` - 删除首页翻译
+
+## Examples
+
+### 商品翻译
+```bash
+# 用户说："给商品prod_123添加中文翻译"
+commerce i18n product create \
+  --product-id prod_123 \
+  --lang zh-CN \
+  --name "手工陶瓷杯" \
+  --description "精美的手工制作陶瓷杯，适合日常使用"
+```
+
+### 变体翻译
+```bash
+# 用户说："给变体var_456添加日语翻译，包括规格翻译"
+commerce i18n variant create \
+  --variant-id var_456 \
+  --lang ja-JP \
+  --name "セラミックマグ（赤・小）" \
+  --variant-attributes-translations '{
+    "颜色": {
+      "key_translation": "色",
+      "value_translation": {"红色": "赤"}
+    },
+    "尺寸": {
+      "key_translation": "サイズ",
+      "value_translation": {"S": "小"}
+    }
+  }'
+```
+
+### 集合翻译
+```bash
+# 用户说："给summer-sale集合添加西班牙语翻译"
+commerce i18n collection create \
+  --collection-id coll_789 \
+  --lang es-ES \
+  --name "Promoción de Verano" \
+  --description "Grandes ofertas para el verano"
+```
+
+### 商户翻译
+```bash
+# 用户说："添加商户的英文翻译"
+commerce i18n merchant create \
+  --lang en-US \
+  --name "Fashion Store" \
+  --description "Your premium fashion destination"
+```
+
+### 首页区块翻译
+```bash
+# 用户说："给首页精选区块添加中英文标题"
+# 中文
+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
+# 用户说："把所有商品翻译成日语"
+# 1. 获取商品列表
+commerce product list --limit 100
+
+# 2. 逐个添加翻译
+commerce i18n product create --product-id prod_1 --lang ja-JP --name "..."
+commerce i18n product create --product-id prod_2 --lang ja-JP --name "..."
+```
+
+## Notes
+
+- 支持的语言：en-US, es-ES, ja-JP, vi-VN, zh-CN
+- 变体翻译的 `variant-attributes-translations` 格式复杂，需要同时翻译规格键和值
+- 商户翻译是单例，不需要指定 ID
+- 首页区块翻译用于前端展示的多语言标题和描述
+- 主商品的 variant_attributes_translations 会自动从变体聚合
+- 使用 `--help` 查看命令详细参数

package/.claude/skills/commerce-inventory/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: commerce-inventory
+description: Inventory management and stock monitoring. Track stock levels, update inventory, check low stock alerts, view inventory history, reserve stock. Use when user needs to check stock, replenish inventory, monitor low stock warnings, or manage stock reservations.
+---
+
+# Commerce CLI - Inventory Management
+
+## Overview
+
+库存管理模块，用于监控库存水平、补货、预留和历史跟踪。
+
+## Instructions
+
+### 自然语言映射
+
+当用户说：
+- "查看库存低于10的商品" → `commerce inventory low-stock --threshold 10`
+- "商品XX补货50个" → `commerce inventory update --id XX --quantity 50 --reason "补货"`
+- "预留库存" → `commerce inventory reserve --product-id XX --quantity YY`
+- "查看库存历史" → `commerce inventory history --product-id XX`
+- "查看所有商品库存" → `commerce inventory list`
+
+### 核心功能
+
+**库存查询**:
+- `commerce inventory list` - 查看所有商品库存
+- `commerce inventory get` - 查看单个商品库存
+- `commerce inventory low-stock` - 查看低库存商品
+- `commerce inventory history` - 查看库存变更历史
+
+**库存更新**:
+- `commerce inventory update` - 更新库存数量
+- `commerce inventory reserve` - 预留库存
+- `commerce inventory release` - 释放预留库存
+
+## Examples
+
+### 查看低库存预警
+```bash
+# 用户说："查看库存低于5的商品"
+commerce inventory low-stock --threshold 5
+```
+
+### 补货操作
+```bash
+# 用户说："商品prod_123补货100个"
+commerce inventory update \
+  --id prod_123 \
+  --quantity 100 \
+  --reason "定期补货"
+```
+
+### 预留库存
+```bash
+# 用户说："为订单预留5个商品"
+commerce inventory reserve \
+  --product-id prod_123 \
+  --quantity 5 \
+  --order-id order_456
+```
+
+### 查看库存历史
+```bash
+# 用户说："查看商品prod_123的库存变更记录"
+commerce inventory history \
+  --product-id prod_123 \
+  --limit 20
+```
+
+### 批量查看库存
+```bash
+# 用户说："查看所有商品的库存情况"
+commerce inventory list --limit 100
+```
+
+## Notes
+
+- 库存变更会自动记录历史
+- 预留库存不会减少可用库存数量
+- 更新库存时建议添加 `--reason` 说明原因
+- 低库存阈值可以自定义
+- 支持批量库存更新（通过脚本循环调用）
+- 使用 `--help` 查看命令详细参数

package/.claude/skills/commerce-order/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: commerce-order
+description: Order fulfillment and shipping management. Process orders, ship packages, handle cancellations, manage refunds, track shipments. Use when user needs to fulfill orders, ship products, cancel orders, process refunds, or check shipping status.
+---
+
+# Commerce CLI - Order Fulfillment
+
+## Overview
+
+订单履行模块，用于处理订单、发货、售后和物流跟踪。
+
+## Instructions
+
+### 自然语言映射
+
+当用户说：
+- "查看待发货订单" → `commerce order list --status paid`
+- "订单XX发货" → `commerce order ship --id XX --tracking YY --carrier ZZ`
+- "取消订单XX" → `commerce order cancel --id XX --yes`
+- "标记订单已送达" → `commerce order mark-delivered --id XX`
+- "查询运费" → `commerce shipping calculate --country XX --weight YY`
+- "处理退款" → `commerce refund create --order-id XX --amount YY`
+
+### 核心功能
+
+**订单管理**:
+- `commerce order list` - 查看订单列表
+- `commerce order get` - 查看订单详情
+- `commerce order ship` - 标记订单发货
+- `commerce order cancel` - 取消订单
+- `commerce order complete` - 完成订单
+- `commerce order mark-delivered` - 标记已送达
+
+**退款管理**:
+- `commerce refund create` - 创建退款
+- `commerce refund list` - 查看退款列表
+- `commerce refund get` - 查看退款详情
+- `commerce refund approve` - 批准退款
+- `commerce refund reject` - 拒绝退款
+
+**物流管理**:
+- `commerce shipping calculate` - 计算运费
+- `commerce shipping track` - 物流追踪
+- `commerce shipping update-status` - 更新物流状态
+
+## Examples
+
+### 查看待处理订单
+```bash
+# 用户说："查看今天待发货的订单"
+commerce order list --status paid --limit 50
+```
+
+### 订单发货
+```bash
+# 用户说："订单order_123发货，快递单号DHL123456，承运商DHL"
+commerce order ship \
+  --id order_123 \
+  --tracking DHL123456 \
+  --carrier DHL
+```
+
+### 取消订单
+```bash
+# 用户说："取消订单order_456，原因是客户要求"
+commerce order cancel \
+  --id order_456 \
+  --reason "客户要求取消" \
+  --yes
+```
+
+### 标记订单完成
+```bash
+# 用户说："标记订单order_789已送达"
+commerce order mark-delivered --id order_789
+```
+
+### 计算运费
+```bash
+# 用户说："计算寄到美国纽约10001的运费，重量0.5kg"
+commerce shipping calculate \
+  --country US \
+  --postal-code 10001 \
+  --weight 0.5
+```
+
+### 处理退款
+```bash
+# 用户说："订单order_123要退款150美元"
+commerce refund create \
+  --order-id order_123 \
+  --amount 150 \
+  --reason "商品有瑕疵"
+
+# 批准退款
+commerce refund approve --id refund_456
+```
+
+### 物流追踪
+```bash
+# 用户说："查询快递单号DHL123456的物流信息"
+commerce shipping track --tracking-number DHL123456
+```
+
+## Notes
+
+- 订单状态流转：pending → paid → shipped → delivered → completed
+- 取消和删除操作需要 `--yes` 确认
+- 发货后订单状态自动变为 shipped
+- 退款需要先创建，然后批准才会实际退款
+- 支持的物流商：DHL, FedEx, UPS, USPS, SF Express, 顺丰
+- 使用 `--help` 查看命令详细参数

package/.claude/skills/commerce-product/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: commerce-product
+description: Product catalog management for e-commerce stores. Create and update products, manage variants/SKUs, upload product images, organize tags. Use when user needs to add new products, update pricing, manage product inventory, upload photos, or organize product catalog.
+---
+
+# Commerce CLI - Product Management
+
+## Overview
+
+商品管理模块，用于电商商品目录的创建、编辑和组织。
+
+## Instructions
+
+### 自然语言映射
+
+当用户说：
+- "创建XX商品，价格YY" → `commerce product create --title XX --price YY`
+- "上传商品图片" → `commerce upload image --path ./photo.jpg`
+- "添加商品变体" → `commerce variant create --product-id XX --sku YY`
+- "更新商品价格" → `commerce product update --id XX --price YY`
+- "给商品打标签" → `commerce product update --id XX --tags "featured,new"`
+- "查看所有商品" → `commerce product list`
+
+### 核心功能
+
+**商品 CRUD**:
+- `commerce product create` - 创建商品
+- `commerce product list` - 查看商品列表
+- `commerce product get` - 查看商品详情
+- `commerce product update` - 更新商品信息
+- `commerce product delete` - 删除商品
+
+**变体/SKU 管理**:
+- `commerce variant create` - 创建商品变体
+- `commerce variant list` - 查看变体列表
+- `commerce variant update` - 更新变体信息
+- `commerce variant delete` - 删除变体
+
+**图片管理**:
+- `commerce upload image` - 上传图片
+- `commerce product add-images` - 关联图片到商品
+- `commerce product remove-images` - 移除商品图片
+
+## Examples
+
+### 创建商品
+```bash
+# 用户说："创建T恤商品，99美元，库存20"
+commerce product create \
+  --title "T恤" \
+  --price 99 \
+  --stock 20 \
+  --description "100% 纯棉T恤"
+```
+
+### 上传商品图片
+```bash
+# 用户说："上传商品主图"
+commerce upload image --path ./tshirt-main.jpg
+# 返回: { media_id: "media_123" }
+
+# 关联到商品
+commerce product add-images \
+  --id prod_123 \
+  --media-id media_123
+```
+
+### 创建商品变体
+```bash
+# 用户说："给商品添加红色S码的变体"
+commerce variant create \
+  --product-id prod_123 \
+  --sku "TSHIRT-RED-S" \
+  --price 99 \
+  --stock 50 \
+  --attributes '{"颜色":"红色","尺寸":"S"}'
+```
+
+### 管理商品标签
+```bash
+# 用户说："把商品标记为精选和新品"
+commerce product update \
+  --id prod_123 \
+  --tags "featured,new"
+
+# 查看带特定标签的商品
+commerce product list --tags "featured"
+```
+
+### 批量更新价格
+```bash
+# 用户说："把所有T恤价格改成89"
+# 1. 先查找T恤商品
+commerce product list --query "T恤"
+
+# 2. 逐个更新
+commerce product update --id prod_123 --price 89
+commerce product update --id prod_456 --price 89
+```
+
+## Notes
+
+- 所有命令默认 JSON 输出，便于 AI 解析
+- 图片需要先上传获取 `media_id`，再关联到商品
+- 变体的 `attributes` 使用 JSON 格式
+- 标签使用逗号分隔的字符串
+- 支持的图片格式：JPG, PNG, WebP
+- 使用 `--help` 查看命令详细参数

package/.claude/skills/commerce-storefront/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: commerce-storefront
+description: Storefront and homepage configuration. Manage homepage sections, product collections, merchant profile, navigation menus, banners. Use when user needs to configure homepage, create product collections, update store information, or organize storefront layout.
+---
+
+# Commerce CLI - Storefront Configuration
+
+## Overview
+
+店铺前台配置模块，用于首页设置、商品集合管理和商户信息维护。
+
+## Instructions
+
+### 自然语言映射
+
+当用户说：
+- "创建首页轮播图" → `commerce homepage module create --type banner ...`
+- "更新首页设置" → `commerce homepage settings update --show-search true`
+- "创建商品集合" → `commerce collection create --name XX --slug YY`
+- "把商品添加到集合" → `commerce collection add-products --id XX --product-ids YY`
+- "更新店铺信息" → `commerce merchant update --name XX`
+
+### 核心功能
+
+**首页模块管理**:
+- `commerce homepage module create` - 创建首页模块
+- `commerce homepage module list` - 查看所有模块
+- `commerce homepage module update` - 更新模块
+- `commerce homepage module delete` - 删除模块
+- `commerce homepage module reorder` - 重新排序
+
+**首页设置**:
+- `commerce homepage settings get` - 查看首页设置
+- `commerce homepage settings update` - 更新首页设置
+
+**商品集合**:
+- `commerce collection create` - 创建集合
+- `commerce collection list` - 查看集合列表
+- `commerce collection update` - 更新集合
+- `commerce collection delete` - 删除集合
+- `commerce collection add-products` - 添加商品到集合
+- `commerce collection remove-products` - 从集合移除商品
+
+**商户信息**:
+- `commerce merchant info` - 查看商户信息
+- `commerce merchant update` - 更新商户信息
+- `commerce merchant init` - 初始化商户设置
+
+## Examples
+
+### 创建首页轮播图
+```bash
+# 用户说："创建首页轮播图模块"
+commerce homepage module create \
+  --slug hero-banner \
+  --type banner \
+  --position 1 \
+  --enabled true \
+  --config '{"images":[{"url":"https://example.com/banner1.jpg"}]}'
+```
+
+### 更新首页设置
+```bash
+# 用户说："启用首页搜索功能，显示8个精选商品"
+commerce homepage settings update \
+  --show-search true \
+  --featured-limit 8
+```
+
+### 创建商品集合
+```bash
+# 用户说："创建夏季促销集合"
+commerce collection create \
+  --name "Summer Sale" \
+  --slug summer-sale \
+  --description "Hot deals for summer"
+```
+
+### 添加商品到集合
+```bash
+# 用户说："把商品prod_123和prod_456添加到summer-sale集合"
+commerce collection add-products \
+  --slug summer-sale \
+  --product-ids prod_123,prod_456
+```
+
+### 更新商户信息
+```bash
+# 用户说："更新店铺名称和描述"
+commerce merchant update \
+  --name "My Fashion Store" \
+  --description "Premium fashion for everyone"
+```
+
+### 重新排序首页模块
+```bash
+# 用户说："调整首页模块顺序"
+commerce homepage module reorder \
+  --module-id module_123 \
+  --position 2
+```
+
+## Notes
+
+- 首页模块支持类型：banner（轮播图）、featured（精选商品）、categories（分类）
+- 集合 slug 必须唯一，用于 URL
+- 模块的 position 决定显示顺序（从小到大）
+- config 字段使用 JSON 格式
+- 集合可以手动管理商品，也可以设置自动规则
+- 使用 `--help` 查看命令详细参数