---
name: shipping
description: "运费配置和物流管理。使用场景：查看/设置运费模式、固定运费区域、计算运费、Easyship集成。当用户问运费设置、运费模式、运费区域、Easyship相关问题时使用。"
---

# 运费管理

> **注意**：`commerce easyship *` 命令已逐步迁移到 `logistics *`（见 **logistics** skill）。运费模式和固定运费区域仍使用此模块。

## 典型场景

| 用户说 | 命令 |
|--------|------|
| "查看运费设置" / "运费模式" | `commerce shipping get-mode` |
| "修改运费模式" | `commerce shipping update-mode` |
| "计算运费" / "寄到XX多少钱" | `commerce shipping calculate` |
| "查看运费区域" / "固定运费" | `commerce shipping-zone list` |
| "添加运费区域" | `commerce shipping-zone create` |
| "设置默认运费" / "兜底运费" / "其他地区运费" | `commerce shipping-zone create --is-default` |
| "全球免运费" / "免邮" / "包邮" | `commerce shipping update-mode --mode free` |
| "Easyship快递" / "可用快递" | `commerce easyship couriers` |
| "查看发货地址" | `commerce easyship get-origin` |
| "更新发货地址" | `commerce merchant update --origin-*`（见 merchant skill） |

## 不在此模块

| 用户说 | 正确命令 |
|--------|----------|
| "订单发货" | `commerce order ship`（见 order skill） |
| "查询订单物流" | `commerce order tracking`（见 order skill） |

---

## 运费模式

店铺的运费计算方式，影响买家结账时看到的运费选项。

### 查看当前模式
```bash
commerce shipping get-mode
```

### 修改模式
```bash
commerce shipping update-mode --mode <模式>

# 设置免运费模式（可配置配送天数）
commerce shipping update-mode --mode free --free-days-min 5 --free-days-max 10
```

| 模式 | 说明 |
|------|------|
| `free` | **全球免运费**（新商户默认），可配置配送天数 |
| `fixed` | 仅使用固定运费区域 |
| `dynamic` | 动态实时报价（通过 logistics 服务获取承运商报价） |

**免运费模式参数**：
- `--free-days-min` - 最小配送天数（默认 7）
- `--free-days-max` - 最大配送天数（默认 14）

---

## 运费计算

根据目的地和重量计算运费（发货前使用）。

```bash
commerce shipping calculate \
  --country <国家代码> \
  --postal-code <邮编> \
  --weight <重量kg>
```

示例：
```bash
# 计算寄到美国的运费
commerce shipping calculate --country US --postal-code 10001 --weight 0.5

# 计算寄到日本的运费
commerce shipping calculate --country JP --postal-code 100-0001 --weight 1.2
```

### 查看支持的国家
```bash
commerce shipping countries
```

---

## 固定运费区域

为不同地区设置固定运费，适合不使用 Easyship 的场景。

### 查看所有区域
```bash
commerce shipping-zone list
```

### 创建区域
```bash
commerce shipping-zone create \
  --name "北美" \
  --countries "US,CA" \
  --price 15.00

# 创建默认区域（兜底，当客户地址不匹配其他区域时使用）
commerce shipping-zone create \
  --name "其他地区" \
  --price 25.00 \
  --is-default
```

**`--is-default` 使用时机**：用户提到"默认运费"、"兜底运费"、"其他地区"、"全球运费"时使用。

### 添加费率
```bash
commerce shipping-zone add-rate \
  --zone-id <区域ID> \
  --min-weight 0 \
  --max-weight 1 \
  --rate 10.00
```

### 更新/删除
```bash
commerce shipping-zone update --id <区域ID> --name "新名称"
commerce shipping-zone delete --id <区域ID> --yes
```

---

## Easyship 集成

Easyship 提供实时国际运费报价。

### 查看可用快递
```bash
commerce easyship couriers
```

### 发货地址

```bash
# 查看发货地址
commerce easyship get-origin

# 更新发货地址 → 使用 merchant 命令
commerce merchant update --origin-country-alpha2 CN --origin-city 深圳 ...

# 验证发货地址
commerce easyship validate-origin
```

**注意**：更新发货地址用 `commerce merchant update --origin-*`，详见 merchant skill。

### 地址验证
```bash
# 验证买家地址
commerce easyship validate-address \
  --country-alpha2 US \
  --city "New York" \
  --postal-code 10001 \
  --line-1 "123 Main St"
```

### 物流追踪

物流追踪功能已统一到 `commerce order tracking` 命令（见 order skill）。

---

## 命令参考

### 运费配置
- `commerce shipping get-mode` - 查看运费模式
- `commerce shipping update-mode` - 修改运费模式
- `commerce shipping calculate` - 计算运费
- `commerce shipping countries` - 支持的国家列表

### 固定运费区域
- `commerce shipping-zone list` - 查看所有区域
- `commerce shipping-zone get` - 查看区域详情
- `commerce shipping-zone create` - 创建区域
- `commerce shipping-zone update` - 更新区域
- `commerce shipping-zone delete` - 删除区域
- `commerce shipping-zone add-rate` - 添加费率
- `commerce shipping-zone update-rate` - 更新费率
- `commerce shipping-zone delete-rate` - 删除费率

### Easyship
- `commerce easyship couriers` - 可用快递公司
- `commerce easyship get-origin` - 查看发货地址
- `commerce easyship validate-origin` - 验证发货地址
- `commerce easyship validate-address` - 验证买家地址

**更新发货地址**用 `commerce merchant update --origin-*`（见 merchant skill）

## 不确定用什么命令？

运行 `commerce shipping --help` 或 `commerce easyship --help` 查看所有子命令。
