@optima-chat/commerce-cli 1.1.0 → 1.3.0

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

@@ -0,0 +1,256 @@
+---
+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 "..."
+```
+
+## 卓越标准
+
+### 翻译质量维度
+- **翻译完整性**: 核心字段100%翻译（商品名、描述、规格）
+- **语言准确性**: 使用母语审校，避免机翻错误
+- **本地化适配**: 考虑文化差异，调整表达方式（如日期格式、货币符号）
+- **SEO优化**: 标题包含目标语言关键词，长度符合搜索引擎要求
+- **更新及时性**: 原文变更后24小时内同步更新翻译
+
+### 翻译管理原则
+- **语言代码规范**: 使用BCP 47格式（en-US, zh-CN），不用短代码（en, zh）
+- **优先级排序**: 先翻译商品和集合，再翻译变体细节
+- **一致性检查**: 同一术语在不同场景保持一致（如"Size"统一译为"サイズ"）
+- **变体规格翻译**: 先翻译规格键（如"颜色"→"Color"），再翻译规格值（如"红色"→"Red"）
+- **占位符策略**: 未翻译的内容回退到默认语言，不显示空白
+
+## 工作流推荐
+
+### 新语言启用流程
+1. **翻译商户信息** - `commerce i18n merchant create --lang XX` 设置店铺名称、描述
+2. **翻译核心集合** - 翻译首页展示的3-5个主要集合
+3. **翻译热门商品** - 优先翻译销量前20的商品
+4. **翻译首页区块** - 翻译轮播图标题、精选区块标题
+5. **翻译变体规格** - 为有变体的商品添加规格翻译
+6. **批量翻译其他商品** - 逐步补充完整商品库翻译
+7. **验证完整性** - 检查关键页面是否所有内容已翻译
+
+### 批量翻译最佳实践
+
+**❌ 低效做法**：
+```bash
+# 不规划优先级，随机翻译
+for product_id in $(commerce product list --json | jq -r '.[].id'); do
+  commerce i18n product create --product-id $product_id --lang ja-JP --name "..."
+done
+```
+
+**✅ 高效做法**：
+```bash
+# 1. 先翻译商户信息
+commerce i18n merchant create --lang ja-JP --name "ファッションストア" --description "..."
+
+# 2. 获取热门商品列表（按销量排序）
+commerce product list --sort-by sales --limit 20
+
+# 3. 优先翻译热门商品
+commerce i18n product create --product-id prod_hot_1 --lang ja-JP --name "..." --description "..."
+commerce i18n product create --product-id prod_hot_2 --lang ja-JP --name "..." --description "..."
+
+# 4. 翻译核心集合
+commerce i18n collection create --collection-id coll_featured --lang ja-JP --name "おすすめ商品"
+
+# 5. 最后批量翻译其他商品
+for product_id in $(commerce product list --json | jq -r '.[].id'); do
+  commerce i18n product create --product-id $product_id --lang ja-JP --name "..."
+done
+```
+
+### 变体规格翻译技巧
+
+**关键点**：主商品的 `variant_attributes_translations` 会自动从变体聚合，只需翻译变体即可。
+
+```bash
+# 1. 创建主商品（不需要翻译variant_attributes_translations）
+commerce i18n product create --product-id prod_123 --lang en-US --name "T-Shirt"
+
+# 2. 翻译所有变体（包括规格）
+commerce i18n variant create --variant-id var_1 --lang en-US \
+  --name "Red T-Shirt (Small)" \
+  --variant-attributes-translations '{
+    "颜色": {"key_translation": "Color", "value_translation": {"红色": "Red"}},
+    "尺寸": {"key_translation": "Size", "value_translation": {"S": "Small"}}
+  }'
+
+# 3. 主商品会自动聚合变体的规格翻译
+commerce i18n product get --product-id prod_123 --lang en-US
+# 返回聚合后的 variant_attributes_translations
+```
+
+### 常见场景决策
+
+| 用户需求 | 推荐命令 | 关键注意点 |
+|---------|---------|-----------|
+| 新增语言 | `i18n merchant create` → 集合 → 商品 | 按优先级翻译，先商户、集合、热门商品 |
+| 翻译商品 | `i18n product create` | 名称和描述必填，SEO关键词要本地化 |
+| 翻译变体 | `i18n variant create` | 使用variant-id（不是product-id），包含规格翻译 |
+| 翻译集合 | `i18n collection create` | 名称要简洁，描述突出价值 |
+| 翻译首页区块 | `i18n homepage set` | 用于前端展示，标题≤30字，描述≤100字 |
+| 更新翻译 | `i18n * update` | 原文变更后及时同步更新 |
+
+### 语言选择策略
+
+**目标市场推荐**：
+- **北美市场** - en-US（必须）
+- **欧洲市场** - es-ES（西班牙语覆盖拉美）
+- **亚洲市场** - ja-JP（日本）, vi-VN（越南）, zh-CN（中国大陆）
+- **全球电商** - en-US + es-ES + zh-CN（覆盖70%全球用户）
+
+**翻译投入建议**：
+- 小店铺：先支持1-2种主要语言
+- 中型店铺：支持3-5种语言，覆盖核心市场
+- 大型店铺：支持5种以上语言，专人维护翻译质量
+
+### 翻译质量检查清单
+
+**上线前必查**：
+- [ ] 商户信息已翻译（名称、描述）
+- [ ] 首页所有区块标题已翻译
+- [ ] 核心集合已翻译（至少5个）
+- [ ] 热门商品已翻译（至少20个）
+- [ ] 变体规格翻译格式正确
+- [ ] 无机翻痕迹（如直译、语序错误）
+- [ ] 术语一致性（如Size统一译法）
+- [ ] 移动端显示正常（无溢出、截断）
+
+## 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,164 @@
+---
+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
+```
+
+## 卓越标准
+
+### 库存管理质量指标
+- **库存准确率**: 账实相符率 ≥ 98%，定期盘点验证
+- **低库存预警响应**: 检测到低库存后24小时内补货
+- **缺货率**: < 2%，避免影响客户体验和转化率
+- **超卖率**: 0%，通过预留机制和实时同步防止超卖
+- **库存周转率**: 根据品类优化，畅销品 > 6次/年，滞销品及时清理
+
+### 库存管理原则
+- **实时同步**: 订单创建时立即预留库存，发货后扣减，取消后释放
+- **安全库存**: 设置合理的低库存阈值（畅销品 > 30天销量，滞销品 > 7天销量）
+- **先进先出**: 先入库的商品优先出库，减少积压和过期
+- **定期盘点**: 每月盘点核对账实差异，及时调整
+- **历史追踪**: 所有库存变更必须记录原因，便于审计
+
+## 工作流推荐
+
+### 日常库存监控流程
+1. **查看低库存** - 每日 `commerce inventory low-stock --threshold 10`
+2. **分析销售趋势** - 结合订单数据判断补货优先级
+3. **制定补货计划** - 畅销品加大补货量，滞销品谨慎补货
+4. **执行补货** - `commerce inventory update --id XX --quantity YY --reason "补货"`
+5. **验证更新** - `commerce inventory get --id XX` 确认库存正确
+6. **定期盘点** - 每月实地盘点，调整账面库存
+
+### 批量补货最佳实践
+
+**❌ 危险做法**：
+```bash
+# 不分析就盲目补货，可能造成库存积压
+for product_id in $(commerce inventory low-stock --json | jq -r '.[].id'); do
+  commerce inventory update --id $product_id --quantity 100 --reason "批量补货"
+done
+```
+
+**✅ 科学做法**：
+```bash
+# 先分析低库存商品，按销售速度分级补货
+commerce inventory low-stock --threshold 10
+
+# 根据销售数据决定补货量
+commerce inventory update --id prod_hot --quantity 500 --reason "畅销品大量补货"
+commerce inventory update --id prod_normal --quantity 100 --reason "常规补货"
+commerce inventory update --id prod_slow --quantity 20 --reason "滞销品少量补货"
+```
+
+### 库存预留机制
+- **订单创建时预留** - 避免超卖，保证订单可履行
+- **支付超时释放** - 未支付订单15分钟后自动释放预留
+- **取消订单释放** - 订单取消后立即释放预留
+- **发货后扣减** - 商品发货后从可用库存扣减
+
+### 常见场景决策
+
+| 用户需求 | 推荐命令 | 关键注意点 |
+|---------|---------|-----------|
+| 查看低库存 | `inventory low-stock --threshold 10` | 阈值根据品类和销售速度设定 |
+| 补货操作 | `inventory update --quantity XX --reason` | 必须填写原因，便于追踪 |
+| 预留库存 | `inventory reserve --order-id XX` | 订单创建时立即预留，避免超卖 |
+| 释放预留 | `inventory release --order-id XX` | 订单取消或支付超时时释放 |
+| 查看历史 | `inventory history --product-id XX` | 分析库存变化趋势，优化补货策略 |
+| 盘点调整 | `inventory update --reason "盘点调整"` | 账实不符时手动调整，记录差异原因 |
+
+### 库存异常处理
+
+**超卖场景**：
+- 预防措施：订单创建时立即预留库存
+- 发生后：优先处理早期订单，联系后续客户协商延期或退款
+- 长期优化：检查库存同步机制，修复bug
+
+**库存差异场景**：
+- 定期盘点发现差异 → 核实实际库存，调整账面库存
+- 记录差异原因（损耗、盗窃、系统错误等）
+- 差异率 > 5%需要深入调查
+
+**滞销商品场景**：
+- 库存周转率低 → 降价促销、捆绑销售
+- 3个月未动销 → 考虑清仓处理
+- 6个月未动销 → 下架并清理库存
+
+## Notes
+
+- 库存变更会自动记录历史
+- 预留库存不会减少可用库存数量
+- 更新库存时建议添加 `--reason` 说明原因
+- 低库存阈值可以自定义
+- 支持批量库存更新（通过脚本循环调用）
+- 使用 `--help` 查看命令详细参数

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

@@ -0,0 +1,192 @@
+---
+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
+```
+
+## 卓越标准
+
+### 订单处理质量指标
+- **发货及时性**: 付款后24小时内发货（标品），48小时内发货（定制品）
+- **物流信息准确性**: 100%订单有tracking number，无虚假单号
+- **客户满意度**: 退款率 < 5%，客服投诉响应 < 2小时
+- **订单完成率**: 取消率 < 3%，拒收率 < 2%
+
+### 订单状态管理原则
+- **3-5-7原则**: 3分钟确认订单，5小时内完成打包，7天内跟踪售后
+- **自动化优先**: 批量处理相同状态订单，优先处理付款时间早的订单
+- **数据完整性**: 发货前验证库存、收货地址、物流商可达性
+- **客户沟通**: 关键状态变更后及时通知（发货、延迟、退款、取消）
+- **审计留痕**: 所有操作记录原因和操作人，便于问题追溯
+
+## 工作流推荐
+
+### 标准订单履行流程
+1. **查看待发货** - `commerce order list --status paid` 按时间升序
+2. **验证订单** - 检查库存、地址、特殊要求
+3. **批量打包** - 准备商品、包装材料、打印面单
+4. **标记发货** - 循环 `commerce order ship --id XX --tracking YY --carrier ZZ`
+5. **物流跟踪** - 定期 `commerce shipping track` 监控异常
+6. **确认送达** - 签收后 `commerce order mark-delivered --id XX`
+
+### 批量发货最佳实践
+
+**❌ 危险做法**：
+```bash
+# 不验证就批量发货，可能发错货或虚假发货
+for order_id in $(commerce order list --status paid --json | jq -r '.[].id'); do
+  commerce order ship --id $order_id --tracking FAKE123 --carrier DHL
+done
+```
+
+**✅ 安全做法**：
+```bash
+# 先人工验证，准备好真实tracking号，再批量发货
+commerce order list --status paid  # 先查看订单列表
+
+# 准备好所有tracking号后，逐个发货
+commerce order ship --id order_123 --tracking DHL123456 --carrier DHL
+commerce order ship --id order_456 --tracking DHL123457 --carrier DHL
+commerce order ship --id order_789 --tracking DHL123458 --carrier DHL
+```
+
+### 退款处理最佳实践
+1. **创建退款** - `commerce refund create` 填写详细原因
+2. **审核评估** - 检查商品状态、退货凭证、历史记录
+3. **批准/拒绝** - `commerce refund approve/reject` 并通知客户
+4. **跟踪反馈** - 记录退款原因，优化产品和服务
+
+### 常见场景决策
+
+| 用户需求 | 推荐命令 | 关键注意点 |
+|---------|---------|-----------|
+| 查看待发货订单 | `order list --status paid` | 按付款时间升序，优先处理早期订单 |
+| 批量发货 | 循环 `order ship` | 必须有真实tracking号，避免虚假发货 |
+| 取消订单 | `order cancel --yes` | 检查是否已发货，避免错误取消 |
+| 处理退款 | `refund create` → `refund approve` | 先创建后审批，保留审计记录 |
+| 运费查询 | `shipping calculate` | 提供准确重量和邮编，避免运费纠纷 |
+| 物流异常 | `shipping track` → `shipping update-status` | 主动更新状态，及时通知客户 |
+
+### 异常处理指南
+
+**订单取消场景**：
+- 客户主动取消 → 检查是否已发货，未发货立即取消
+- 地址错误无法送达 → 联系客户更新地址或取消退款
+- 库存不足 → 立即通知客户，协商补货或退款
+
+**退款场景**：
+- 商品质量问题 → 无需退货，直接全额退款
+- 客户不满意 → 要求退货，收到货后退款
+- 物流丢失 → 联系物流商理赔，先行退款给客户
+
+**物流延迟场景**：
+- 国内延迟 > 3天 → 主动联系客户说明情况
+- 国际延迟 > 7天 → 提供物流追踪链接，协商解决方案
+- 物流丢失 → 联系物流商查询，必要时补发或退款
+
+## Notes
+
+- 订单状态流转：pending → paid → shipped → delivered → completed
+- 取消和删除操作需要 `--yes` 确认
+- 发货后订单状态自动变为 shipped
+- 退款需要先创建，然后批准才会实际退款
+- 支持的物流商：DHL, FedEx, UPS, USPS, SF Express, 顺丰
+- 使用 `--help` 查看命令详细参数