@optima-chat/optima-agent 0.1.0

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

@@ -0,0 +1,291 @@
+---
+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
+
+库存管理模块，用于监控库存水平、补货、预留和历史跟踪。
+
+## 典型场景
+
+### 场景决策表
+
+| 用户需求 | 推荐命令 | 关键注意点 |
+|---------|---------|-----------|
+| 查看低库存 | `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. 查看低库存预警
+
+**场景**：每日检查需要补货的商品
+
+```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 \
+  --product-id prod_123 \
+  --quantity 5 \
+  --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 \
+  --product-id prod_123 \
+  --limit 20
+```
+
+## 卓越标准
+
+### 库存管理质量指标
+- **库存准确率**: 账实相符率 ≥ 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. **定期盘点** - 每月实地盘点，调整账面库存
+
+## 常见问题
+
+### ❌ 问题1：批量补货不分析，造成库存积压
+
+**错误做法**：
+```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 "滞销品少量补货"
+```
+
+### ❌ 问题2：库存差异超过5%未深入调查
+
+**场景**：定期盘点发现差异
+
+**处理流程**：
+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：超卖后处理不当
+
+**预防措施**：
+- 订单创建时立即预留库存
+- 使用实时库存同步机制
+
+**发生后正确处理**：
+1. ✅ 优先处理早期订单（先到先得）
+2. ✅ 主动联系后续客户，提供补偿方案
+3. ✅ 紧急补货，缩短等待时间
+4. ❌ 不要直接取消订单不解释
+5. ❌ 不要让客户长时间等待无反馈
+
+## 命令参考
+
+### 自然语言映射
+
+当用户说：
+- "查看库存低于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
+```
+
+## 重要提示
+
+- 库存变更会自动记录历史
+- 预留库存不会减少可用库存数量
+- 更新库存时建议添加 `--reason` 说明原因
+- 低库存阈值可以自定义
+- 支持批量库存更新（通过脚本循环调用）
+- 使用 `--help` 查看命令详细参数

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

@@ -0,0 +1,201 @@
+---
+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
+
+订单履行模块，用于处理订单、发货、售后和物流跟踪。
+
+## 典型场景
+
+当用户说：
+- "查看待发货订单" → `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`
+
+### 场景决策表
+
+| 用户需求 | 推荐命令 | 关键注意点 |
+|---------|---------|-----------|
+| 查看待发货订单 | `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` - 标记订单发货
+- `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` - 更新物流状态
+
+## 详细示例
+
+### 查看待处理订单
+```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
+```
+
+## 重要提示
+
+- 订单状态流转：pending → paid → shipped → delivered → completed
+- 取消和删除操作需要 `--yes` 确认
+- 发货后订单状态自动变为 shipped
+- 退款需要先创建，然后批准才会实际退款
+- 支持的物流商：DHL, FedEx, UPS, USPS, SF Express, 顺丰
+- 使用 `--help` 查看命令详细参数