@optima-chat/commerce-cli 1.3.0 → 1.4.1

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

@@ -5,52 +5,51 @@ description: Inventory management and stock monitoring. Track stock levels, upda
 
 # 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` - 查看库存变更历史
+| 用户需求 | 推荐命令 | 关键注意点 |
+|---------|---------|-----------|
+| 查看低库存 | `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 "盘点调整"` | 账实不符时手动调整，记录差异原因 |
 
-**库存更新**:
-- `commerce inventory update` - 更新库存数量
-- `commerce inventory reserve` - 预留库存
-- `commerce inventory release` - 释放预留库存
+### 1. 查看低库存预警
 
-## Examples
+**场景**：每日检查需要补货的商品
 
-### 查看低库存预警
 ```bash
 # 用户说："查看库存低于5的商品"
 commerce inventory low-stock --threshold 5
 ```
 
-### 补货操作
+### 2. 补货操作
+
+**场景**：根据销售速度和品类特性进行科学补货
+
 ```bash
 # 用户说："商品prod_123补货100个"
 commerce inventory update \
   --id prod_123 \
   --quantity 100 \
   --reason "定期补货"
+
+# 根据销售数据决定补货量
+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 "滞销品少量补货"
 ```
 
-### 预留库存
+### 3. 预留库存
+
+**场景**：订单创建时立即预留库存，防止超卖
+
 ```bash
 # 用户说："为订单预留5个商品"
 commerce inventory reserve \
@@ -59,7 +58,49 @@ commerce inventory reserve \
   --order-id order_456
 ```
 
-### 查看库存历史
+**库存预留机制**：
+- **订单创建时预留** - 避免超卖，保证订单可履行
+- **支付超时释放** - 未支付订单15分钟后自动释放预留
+- **取消订单释放** - 订单取消后立即释放预留
+- **发货后扣减** - 商品发货后从可用库存扣减
+
+### 4. 盘点调整
+
+**场景**：定期盘点发现账实差异，需要调整库存
+
+```bash
+# 实际库存95，账面库存100，差异5个
+commerce inventory update \
+  --id prod_123 \
+  --quantity 95 \
+  --reason "盘点调整：实际库存95，账面100，差异-5（仓库损耗）"
+
+# 验证更新
+commerce inventory get --id prod_123
+```
+
+### 5. 处理超卖
+
+**场景**：发现库存不足以满足所有订单
+
+**预防措施**：
+- 订单创建时立即预留库存
+- 使用实时库存同步机制
+
+**发生后处理**：
+1. 优先处理早期订单，确保先到先得
+2. 联系后续客户协商延期或退款
+3. 紧急补货，缩短等待时间
+
+**长期优化**：
+- 检查库存同步机制，修复bug
+- 加强预留机制的可靠性
+- 设置安全库存缓冲
+
+### 6. 查看库存历史
+
+**场景**：分析库存变化趋势，优化补货策略
+
 ```bash
 # 用户说："查看商品prod_123的库存变更记录"
 commerce inventory history \
@@ -67,12 +108,6 @@ commerce inventory history \
   --limit 20
 ```
 
-### 批量查看库存
-```bash
-# 用户说："查看所有商品的库存情况"
-commerce inventory list --limit 100
-```
-
 ## 卓越标准
 
 ### 库存管理质量指标
@@ -89,8 +124,6 @@ commerce inventory list --limit 100
 - **定期盘点**: 每月盘点核对账实差异，及时调整
 - **历史追踪**: 所有库存变更必须记录原因，便于审计
 
-## 工作流推荐
-
 ### 日常库存监控流程
 1. **查看低库存** - 每日 `commerce inventory low-stock --threshold 10`
 2. **分析销售趋势** - 结合订单数据判断补货优先级
@@ -99,9 +132,11 @@ commerce inventory list --limit 100
 5. **验证更新** - `commerce inventory get --id XX` 确认库存正确
 6. **定期盘点** - 每月实地盘点，调整账面库存
 
-### 批量补货最佳实践
+## 常见问题
+
+### ❌ 问题1：批量补货不分析，造成库存积压
 
-**❌ 危险做法**：
+**错误做法**：
 ```bash
 # 不分析就盲目补货，可能造成库存积压
 for product_id in $(commerce inventory low-stock --json | jq -r '.[].id'); do
@@ -109,7 +144,7 @@ for product_id in $(commerce inventory low-stock --json | jq -r '.[].id'); do
 done
 ```
 
-**✅ 科学做法**：
+**✅ 正确做法**：
 ```bash
 # 先分析低库存商品，按销售速度分级补货
 commerce inventory low-stock --threshold 10
@@ -120,41 +155,133 @@ commerce inventory update --id prod_normal --quantity 100 --reason "常规补货
 commerce inventory update --id prod_slow --quantity 20 --reason "滞销品少量补货"
 ```
 
-### 库存预留机制
-- **订单创建时预留** - 避免超卖，保证订单可履行
-- **支付超时释放** - 未支付订单15分钟后自动释放预留
-- **取消订单释放** - 订单取消后立即释放预留
-- **发货后扣减** - 商品发货后从可用库存扣减
+### ❌ 问题2：库存差异超过5%未深入调查
 
-### 常见场景决策
+**场景**：定期盘点发现差异
 
-| 用户需求 | 推荐命令 | 关键注意点 |
-|---------|---------|-----------|
-| 查看低库存 | `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 "盘点调整"` | 账实不符时手动调整，记录差异原因 |
+**处理流程**：
+1. 核实实际库存，调整账面库存
+2. 记录差异原因（损耗、盗窃、系统错误等）
+3. 差异率 > 5%需要深入调查根本原因
 
-### 库存异常处理
+```bash
+# 调整库存并详细记录原因
+commerce inventory update \
+  --id prod_123 \
+  --quantity 95 \
+  --reason "盘点调整：实际95，账面100，差异-5（仓库损耗，需检查存储条件）"
+```
+
+### ❌ 问题3：滞销商品长期占用库存
+
+**滞销商品处理策略**：
+
+| 滞销时长 | 处理方式 | 命令示例 |
+|---------|---------|---------|
+| 库存周转率低 | 降价促销、捆绑销售 | 调整价格，增加曝光 |
+| 3个月未动销 | 考虑清仓处理 | 大幅降价或买一送一 |
+| 6个月未动销 | 下架并清理库存 | 捐赠、报废或转移 |
+
+```bash
+# 查看库存历史判断是否滞销
+commerce inventory history --product-id prod_slow --limit 50
+```
+
+### ❌ 问题4：不记录库存变更原因
+
+**错误做法**：
+```bash
+# 缺少原因，无法追溯
+commerce inventory update --id prod_123 --quantity 100
+```
+
+**✅ 正确做法**：
+```bash
+# 必须记录原因
+commerce inventory update \
+  --id prod_123 \
+  --quantity 100 \
+  --reason "定期补货：上周销量50，预计2周销量"
+```
+
+### ❌ 问题5：超卖后处理不当
+
+**预防措施**：
+- 订单创建时立即预留库存
+- 使用实时库存同步机制
 
-**超卖场景**：
-- 预防措施：订单创建时立即预留库存
-- 发生后：优先处理早期订单，联系后续客户协商延期或退款
-- 长期优化：检查库存同步机制，修复bug
+**发生后正确处理**：
+1. ✅ 优先处理早期订单（先到先得）
+2. ✅ 主动联系后续客户，提供补偿方案
+3. ✅ 紧急补货，缩短等待时间
+4. ❌ 不要直接取消订单不解释
+5. ❌ 不要让客户长时间等待无反馈
 
-**库存差异场景**：
-- 定期盘点发现差异 → 核实实际库存，调整账面库存
-- 记录差异原因（损耗、盗窃、系统错误等）
-- 差异率 > 5%需要深入调查
+## 命令参考
 
-**滞销商品场景**：
-- 库存周转率低 → 降价促销、捆绑销售
-- 3个月未动销 → 考虑清仓处理
-- 6个月未动销 → 下架并清理库存
+### 自然语言映射
+
+当用户说：
+- "查看库存低于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` - 释放预留库存
+
+## 详细示例
+
+### 查看低库存预警
+```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
+## 重要提示
 
 - 库存变更会自动记录历史
 - 预留库存不会减少可用库存数量

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

@@ -5,13 +5,9 @@ description: Order fulfillment and shipping management. Process orders, ship pac
 
 # Commerce CLI - Order Fulfillment
 
-## Overview
-
 订单履行模块，用于处理订单、发货、售后和物流跟踪。
 
-## Instructions
-
-### 自然语言映射
+## 典型场景
 
 当用户说：
 - "查看待发货订单" → `commerce order list --status paid`
@@ -21,9 +17,102 @@ description: Order fulfillment and shipping management. Process orders, ship pac
 - "查询运费" → `commerce shipping calculate --country XX --weight YY`
 - "处理退款" → `commerce refund create --order-id XX --amount YY`
 
-### 核心功能
+### 场景决策表
+
+| 用户需求 | 推荐命令 | 关键注意点 |
+|---------|---------|-----------|
+| 查看待发货订单 | `order list --status paid` | 按付款时间升序，优先处理早期订单 |
+| 批量发货 | 循环 `order ship` | 必须有真实tracking号，避免虚假发货 |
+| 取消订单 | `order cancel --yes` | 检查是否已发货，避免错误取消 |
+| 处理退款 | `refund create` → `refund approve` | 先创建后审批，保留审计记录 |
+| 运费查询 | `shipping calculate` | 提供准确重量和邮编，避免运费纠纷 |
+| 物流异常 | `shipping track` → `shipping update-status` | 主动更新状态，及时通知客户 |
+
+### 标准订单履行流程
+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`
+
+### 退款处理流程
+1. **创建退款** - `commerce refund create` 填写详细原因
+2. **审核评估** - 检查商品状态、退货凭证、历史记录
+3. **批准/拒绝** - `commerce refund approve/reject` 并通知客户
+4. **跟踪反馈** - 记录退款原因，优化产品和服务
+
+## 卓越标准
+
+### 订单处理质量指标
+- **发货及时性**: 付款后24小时内发货（标品），48小时内发货（定制品）
+- **物流信息准确性**: 100%订单有tracking number，无虚假单号
+- **客户满意度**: 退款率 < 5%，客服投诉响应 < 2小时
+- **订单完成率**: 取消率 < 3%，拒收率 < 2%
+
+### 订单状态管理原则
+- **3-5-7原则**: 3分钟确认订单，5小时内完成打包，7天内跟踪售后
+- **自动化优先**: 批量处理相同状态订单，优先处理付款时间早的订单
+- **数据完整性**: 发货前验证库存、收货地址、物流商可达性
+- **客户沟通**: 关键状态变更后及时通知（发货、延迟、退款、取消）
+- **审计留痕**: 所有操作记录原因和操作人，便于问题追溯
+
+## 常见问题
+
+### 批量发货错误
+
+❌ **危险做法 - 不验证就批量发货**：
+```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
+# 先查看订单列表
+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
+```
+
+### 订单取消场景
+
+❌ **错误操作 - 已发货还取消**：
+- 不检查订单状态直接取消，导致客户收到货但订单已取消
+
+✅ **正确处理**：
+- **客户主动取消** → 检查是否已发货，未发货立即取消
+- **地址错误无法送达** → 联系客户更新地址或取消退款
+- **库存不足** → 立即通知客户，协商补货或退款
+
+### 退款处理错误
+
+❌ **错误流程 - 直接批准未审核的退款**：
+- 不检查商品状态、退货凭证就批准，容易被恶意退款
+
+✅ **正确流程**：
+- **商品质量问题** → 无需退货，直接全额退款
+- **客户不满意** → 要求退货，收到货后退款
+- **物流丢失** → 联系物流商理赔，先行退款给客户
+
+### 物流延迟处理
 
-**订单管理**:
+❌ **错误做法 - 不主动通知客户**：
+- 物流延迟不告知客户，导致客户投诉和差评
+
+✅ **正确处理**：
+- **国内延迟 > 3天** → 主动联系客户说明情况
+- **国际延迟 > 7天** → 提供物流追踪链接，协商解决方案
+- **物流丢失** → 联系物流商查询，必要时补发或退款
+
+## 命令参考
+
+### 订单管理
 - `commerce order list` - 查看订单列表
 - `commerce order get` - 查看订单详情
 - `commerce order ship` - 标记订单发货
@@ -31,19 +120,19 @@ description: Order fulfillment and shipping management. Process orders, ship pac
 - `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
@@ -102,87 +191,7 @@ 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
 - 取消和删除操作需要 `--yes` 确认