@optima-chat/commerce-cli 1.2.0 → 1.3.0

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

@@ -131,6 +131,121 @@ 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

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

@@ -73,6 +73,87 @@ commerce inventory history \
 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
 
 - 库存变更会自动记录历史

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

@@ -102,6 +102,86 @@ commerce refund approve --id refund_456
 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

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

@@ -98,6 +98,62 @@ commerce product update --id prod_123 --price 89
 commerce product update --id prod_456 --price 89
 ```
 
+## 卓越标准
+
+### 商品质量维度
+- **图片质量**: 至少3张不同角度，主图尺寸 ≥ 1200x1200px
+- **描述完整性**: 必填字段100%填写，描述文字 ≥ 50字
+- **SEO优化**: 标题包含核心关键词，使用3-5个相关标签
+- **变体规范**: 使用统一的attributes key（如"颜色"、"尺寸"），避免同义词混用
+- **库存准确**: 创建时设置真实库存，避免超卖和缺货
+
+### 上架流程原则
+- **图片先行**: 先批量上传所有图片获取media_id，再创建商品（避免重复上传）
+- **主商品后变体**: 先创建主商品获取product_id，再创建所有变体
+- **数据完整性**: 每个变体必须有独立SKU、库存、价格
+- **标签策略**: 精选(featured)、新品(new)、促销(sale)等核心标签要及时更新
+
+## 工作流推荐
+
+### 标准商品上架流程
+1. **准备素材** - 整理图片、文案、SKU、规格表
+2. **批量上传图片** - 使用 `commerce upload image` → 记录所有media_id
+3. **创建主商品** - `commerce product create` → 记录product_id
+4. **创建变体** - 循环 `commerce variant create` 添加所有SKU
+5. **关联图片** - `commerce product add-images` 关联主图和详情图
+6. **验证完整性** - `commerce product get --id XXX` 检查所有字段
+
+### 批量操作最佳实践
+
+**❌ 低效做法**：
+```bash
+# 每个商品都重复上传相同的品牌logo
+for product in products; do
+  commerce upload image --path ./brand-logo.jpg
+  commerce product create --title "$product" --media-id $NEW_ID
+done
+```
+
+**✅ 高效做法**：
+```bash
+# 先上传共享资源，复用media_id
+commerce upload image --path ./brand-logo.jpg  # 获得 media_123
+
+for product in products; do
+  commerce product create --title "$product" --media-id media_123
+done
+```
+
+### 常见场景决策
+
+| 用户需求 | 推荐命令 | 关键注意点 |
+|---------|---------|-----------|
+| 创建单个商品 | `product create` | 先上传图片，准备好所有必填字段 |
+| 创建多规格商品 | `product create` + `variant create` | 主商品设置基础价格，变体设置差异价 |
+| 批量上架 | 脚本循环 `product create` | 复用共享图片的media_id，避免重复上传 |
+| 更新价格 | `product update --price` | 如有变体，需逐个更新变体价格 |
+| 添加促销标签 | `product update --tags` | 用逗号分隔，保留原有标签 |
+
 ## Notes
 
 - 所有命令默认 JSON 输出，便于 AI 解析

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

@@ -100,6 +100,94 @@ commerce homepage module reorder \
   --position 2
 ```
 
+## 卓越标准
+
+### 店铺配置质量指标
+- **页面加载速度**: 首页加载 < 3秒，移动端 < 5秒
+- **视觉设计**: 轮播图尺寸统一（1920x600px），图片清晰无水印
+- **导航体验**: 分类层级 ≤ 3层，集合数量 5-15个最佳
+- **内容更新频率**: 轮播图每周更新，精选商品每3天更新
+- **转化率**: 首页访客转化率 > 3%，集合页转化率 > 5%
+
+### 店铺配置原则
+- **移动优先**: 所有配置考虑移动端体验，图片支持响应式
+- **性能优化**: 轮播图 ≤ 5张，精选商品 ≤ 12个，减少加载负担
+- **SEO友好**: 集合slug使用英文，标题包含关键词
+- **一致性**: 风格统一（色彩、字体、间距），提升品牌辨识度
+- **数据驱动**: 根据点击率和转化率优化首页布局和集合内容
+
+## 工作流推荐
+
+### 首页配置标准流程
+1. **规划布局** - 确定首页模块顺序（轮播图 → 分类 → 精选商品 → 集合）
+2. **创建模块** - 依次 `commerce homepage module create` 创建各模块
+3. **配置顺序** - 使用 position 1, 2, 3... 排序
+4. **设置参数** - `commerce homepage settings update` 配置搜索、精选数量
+5. **验证效果** - `commerce homepage module list` 检查配置
+6. **定期优化** - 根据数据调整模块顺序和内容
+
+### 商品集合策略
+
+**推荐集合类型**：
+- **时令集合** - 春夏秋冬、节日促销（如"Christmas Sale"）
+- **品类集合** - 按商品类型分组（如"T-Shirts", "Dresses"）
+- **主题集合** - 按场景分组（如"Office Wear", "Casual Style"）
+- **促销集合** - 新品、热卖、折扣（如"New Arrivals", "Best Sellers"）
+
+### 集合管理最佳实践
+
+**❌ 混乱做法**：
+```bash
+# 集合命名随意，无规划
+commerce collection create --name "aaa" --slug "test123"
+commerce collection create --name "商品111" --slug "product-collection"
+commerce collection create --name "Sale!!!" --slug "promotion"
+```
+
+**✅ 规范做法**：
+```bash
+# 命名清晰，slug 符合 SEO 规范
+commerce collection create --name "Summer Sale 2024" --slug "summer-sale-2024"
+commerce collection create --name "Men's T-Shirts" --slug "mens-tshirts"
+commerce collection create --name "New Arrivals" --slug "new-arrivals"
+```
+
+### 常见场景决策
+
+| 用户需求 | 推荐命令 | 关键注意点 |
+|---------|---------|-----------|
+| 创建轮播图 | `homepage module create --type banner` | 图片尺寸1920x600px，≤5张，配置跳转链接 |
+| 显示精选商品 | `homepage module create --type featured` | 选择高转化商品，数量8-12个 |
+| 创建促销集合 | `collection create --slug sale` | slug 简短有意义，添加10-30个商品 |
+| 调整模块顺序 | `homepage module reorder --position X` | 重要模块靠前（轮播图position=1） |
+| 更新店铺信息 | `merchant update --name/description` | 名称简洁，描述突出差异化优势 |
+
+### 首页模块推荐配置
+
+**标准首页布局**（position顺序）：
+1. **轮播图** (position=1) - 展示促销、新品、品牌故事
+2. **分类导航** (position=2) - 快速引导到商品分类
+3. **精选商品** (position=3) - 展示高转化或高利润商品
+4. **热门集合** (position=4) - 展示2-3个核心集合
+5. **品牌故事** (position=5) - 建立信任和品牌认知
+
+**性能优化建议**：
+- 轮播图：懒加载，压缩图片，支持WebP格式
+- 精选商品：限制8-12个，缓存1小时
+- 集合：按点击率排序，隐藏低转化集合
+
+### 首页配置检查清单
+
+**上线前必查**：
+- [ ] 轮播图尺寸统一，图片清晰
+- [ ] 所有链接可点击，无404
+- [ ] 移动端显示正常
+- [ ] 加载速度 < 3秒
+- [ ] SEO信息完整（标题、描述、关键词）
+- [ ] 精选商品有库存
+- [ ] 集合至少包含5个商品
+- [ ] 店铺信息准确（名称、Logo、联系方式）
+
 ## Notes
 
 - 首页模块支持类型：banner（轮播图）、featured（精选商品）、categories（分类）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/commerce-cli",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "用自然语言管理电商店铺 - 专为 Claude Code 设计的对话式 CLI 工具，支持多环境和功能测试",
   "main": "dist/index.js",
   "type": "module",