---
name: logistics
description: "物流服务管理。使用场景：运单查询、运单取消、标签获取、物流追踪、运费报价、地址验证。当用户问物流服务、运单详情、追踪号查询、快递识别、运费查询时使用。"
---

# 物流服务 (Logistics)

> **注意**：此模块管理 optima-logistics 物流服务的底层能力。日常订单发货请使用 **order** skill（`commerce order ship`）。

## 典型场景

| 用户说 | 命令 |
|--------|------|
| "查运单详情" / "运单 lo_xxx 的状态" | `logistics shipment get <id>` |
| "取消运单" | `logistics shipment cancel <id>` |
| "打印面单" / "下载标签" | `logistics shipment label <id>` |
| "追踪物流" / "包裹到哪了"（用运单号） | `logistics tracking get <tracking-number>` |
| "注册追踪号" | `logistics tracking register <tracking-number>` |
| "识别快递公司" | `logistics tracking detect-courier <tracking-number>` |
| "查运费" / "报价" | `logistics rates query` |
| "验证地址" | `logistics address validate` |

## 不在此模块

| 用户说 | 正确模块 |
|--------|----------|
| "订单发货" | **order** skill → `commerce order ship` |
| "运费设置" / "运费模式" | **shipping** skill → `commerce shipping` |
| "固定运费区域" | **shipping** skill → `commerce shipping-zone` |

---

## 运单管理

### 查看运单详情
```bash
logistics shipment get <logistics-order-id>

# 示例
logistics shipment get lo_abc123def456
```

### 取消运单
```bash
logistics shipment cancel <logistics-order-id>
```

### 获取运单标签
```bash
logistics shipment label <logistics-order-id>
```

返回标签下载链接（PDF），用于打印贴在包裹上。

---

## 物流追踪

### 查询追踪信息
```bash
logistics tracking get <tracking-number> [--courier <slug>]

# 示例
logistics tracking get SF1234567890
logistics tracking get 1Z999AA10123456784 --courier ups
```

返回：当前状态、轨迹列表（checkpoints）、预计送达时间。

### 注册追踪号（推送通知）
```bash
logistics tracking register <tracking-number> [--courier <slug>] [--logistics-order-id <id>]
```

注册后可通过 webhook 接收物流状态更新推送。

### 识别快递公司
```bash
logistics tracking detect-courier <tracking-number>

# 示例
logistics tracking detect-courier SF1234567890
# → sf-express
```

---

## 运费报价

### 查询运费
```bash
logistics rates query \
  --origin '<JSON Address>' \
  --destination '<JSON Address>' \
  --items '<JSON ParcelItem[]>' \
  [--currency USD]
```

Address JSON 格式：
```json
{
  "name": "John",
  "street1": "123 Main St",
  "city": "New York",
  "state": "NY",
  "postalCode": "10001",
  "country": "US",
  "phone": "+1234567890"
}
```

ParcelItem JSON 格式：
```json
[{
  "title": "T-Shirt",
  "quantity": 2,
  "price": 29.99,
  "currency": "USD",
  "weight": 300,
  "originCountry": "CN"
}]
```

---

## 地址验证

```bash
logistics address validate --address '<JSON Address>'
```

---

## 命令参考

### 运单管理
- `logistics shipment get <id>` - 查看运单详情
- `logistics shipment cancel <id>` - 取消运单
- `logistics shipment label <id>` - 获取运单标签

### 物流追踪
- `logistics tracking get <number>` - 查询追踪信息
- `logistics tracking register <number>` - 注册追踪号
- `logistics tracking detect-courier <number>` - 识别快递公司

### 运费
- `logistics rates query` - 查询运费报价

### 地址
- `logistics address validate` - 验证地址

所有命令支持 `--pretty` 参数输出人类可读格式。

### JD 走货限制知识

**货物类型限制**（不同专线支持不同 cargo type）：
- 普货线：仅接 general
- 带电线：接 battery + general
- 服装线：接 clothing + general
- 化妆品线：接 cosmetic
- 系统会自动根据产品 cargo_type 过滤不可用专线

**品牌限制**：部分国际品牌在 JD 禁运列表中，系统自动检查

**PGA 管控**：部分商品（食品、药品等）受 PGA 管控，系统做关键词初筛

**偏远邮编**：US 部分邮编为偏远无服务区域，JD 不提供服务

### AI 发货决策树

```
卖家说"发货" → 查 getRates
  ├── 有可用方案 → AskUserQuestion 展示方案让卖家选择
  ├── JD 无方案但有 EasyShip → 告知原因，建议使用其他物流或手动发货
  └── 全部无方案 → 告知原因 + 建议手动发货
```

## 不确定用什么命令？

运行 `logistics --help` 查看所有子命令。
