---
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` | 创建退款请求 |
| 运费查询 | `shipping calculate` | 提供准确重量和邮编，避免运费纠纷 |
| 物流状态更新 | `order update-shipping-status` | 手动更新物流状态，及时通知客户 |
| 查看物流历史 | `order shipping-history` | 查看订单物流状态变更记录 |

### 标准订单履行流程
1. **查看待发货** - `commerce order list --status paid` 按时间升序
2. **验证订单** - 检查库存、地址、特殊要求
3. **批量打包** - 准备商品、包装材料、打印面单
4. **标记发货** - 循环 `commerce order ship --id XX --tracking YY --carrier ZZ`
5. **更新物流** - `commerce order update-shipping-status` 更新物流状态
6. **确认送达** - 签收后 `commerce order mark-delivered --id XX`

### 退款处理流程
1. **创建退款** - `commerce refund create --order-id XX --amount YY --reason "原因"`
2. **查看详情** - `commerce refund get --id XX` 查看退款状态
3. **跟踪反馈** - 记录退款原因，优化产品和服务

## 卓越标准

### 订单处理质量指标
- **发货及时性**: 付款后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 update-shipping-status` - 更新物流状态（手动物流）
- `commerce order mark-delivered` - 标记已送达
- `commerce order complete` - 完成订单
- `commerce order cancel` - 取消订单
- `commerce order shipping-history` - 查看物流状态历史

### 退款管理
- `commerce refund create` - 创建退款
- `commerce refund get` - 查看退款详情

### 运费管理
- `commerce shipping calculate` - 计算运费
- `commerce shipping get-mode` - 查看运费模式配置
- `commerce shipping update-mode` - 更新运费模式配置
- `commerce shipping countries` - 查看支持的运送国家

## 详细示例

### 查看待处理订单
```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 get --id refund_456
```

### 查看物流历史
```bash
# 用户说："查看订单order_123的物流状态历史"
commerce order shipping-history --id order_123
```

### 更新物流状态
```bash
# 用户说："更新订单order_123的物流状态为已发货"
commerce order update-shipping-status \
  --id order_123 \
  --status shipped \
  --note "已从仓库发出"
```

## 重要提示

- 订单状态流转：pending → paid → shipped → delivered → completed
- 取消操作需要 `--yes` 确认
- 发货后订单状态自动变为 shipped
- 退款使用 `refund create` 创建，使用 `refund get` 查看状态
- 物流状态更新使用 `order update-shipping-status`（手动物流模式）
- 使用 `--help` 查看命令详细参数