# 物流查询集成指南

## 当前实现

系统已集成快递100 API，支持顺丰速运和京东快递的物流轨迹查询。

### 查询方式优先级

1. **快递100 API**（推荐）- 实时查询物流轨迹
2. **官网链接跳转**（备用）- 未配置API时使用

---

## 快递100 API 配置（推荐）

### 1. 注册快递100账号

访问：https://www.kuaidi100.com/
- 注册企业账号
- 申请API接口权限
- 获取 `customer` 和 `key`

### 2. 配置环境变量

在 `server/.env` 文件中添加：

```env
# 快递100配置
LOGISTICS_KUAIDI100_ENABLE=true
LOGISTICS_KUAIDI100_CUSTOMER=你的customer
LOGISTICS_KUAIDI100_KEY=你的key
LOGISTICS_KUAIDI100_QUERY_URL=https://poll.kuaidi100.com/poll/query.do
```

### 3. 配置文件

在 `server/config/logistics.php` 中：

```php
<?php

return [
    'kuaidi100' => [
        'enable' => env('LOGISTICS_KUAIDI100_ENABLE', false),
        'customer' => env('LOGISTICS_KUAIDI100_CUSTOMER', ''),
        'key' => env('LOGISTICS_KUAIDI100_KEY', ''),
        'query_url' => env('LOGISTICS_KUAIDI100_QUERY_URL', 'https://poll.kuaidi100.com/poll/query.do'),
    ],
];
```

### 4. 支持的快递公司

- **顺丰速运** (sf / shunfeng)
- **京东快递** (jd)
- 更多快递公司可通过快递100文档查询编码

---

## 官网查询链接（备用方案）

当未配置快递100 API时，系统会提供官网查询链接：

### 顺丰速运
- 链接格式：`https://www.sf-express.com/cn/sc/dynamic_function/waybill/#search/bill-number/{运单号}`
- 特点：需要输入收件人手机号后4位验证

### 京东物流
- 链接格式：`https://www.jdl.com/#/trackQuery?waybillCode={运单号}`
- 特点：直接查询，无需验证

---

## 使用说明

### 前端查询界面

位置：`业务订单详情` → `物流轨迹`

功能：
1. 选择快递公司（自动识别/顺丰/京东）
2. 点击"查询物流"按钮
3. 查看实时物流轨迹
4. 备用：点击"顺丰官网查件"或"京东物流查件"

### 自动识别规则

系统会根据运单号自动识别快递公司：
- 顺丰：以 `SF` 开头
- 京东：以 `JD`、`JDV`、`JDK`、`JDEX` 开头

### 物流状态说明

- **0** - 在途
- **1** - 揽收
- **2** - 疑难
- **3** - 已签收
- **4** - 退签
- **5** - 派件中
- **6** - 退回
- **7** - 转投
- **10** - 待清关
- **11** - 清关中
- **12** - 已清关
- **13** - 清关异常
- **14** - 收件人拒签

---

## 顺丰查询注意事项

### 为什么查不到顺丰快递？

1. **手机号验证**
   - 顺丰查询需要收件人手机号后4位
   - 系统已自动传入订单中的收件人手机号
   - 如果查询失败，请检查订单中的手机号是否正确

2. **运单号格式**
   - 确保运单号正确无误
   - 顺丰运单号通常以 `SF` 开头

3. **快递100配置**
   - 确认已正确配置 `LOGISTICS_KUAIDI100_*` 环境变量
   - 确认快递100账户余额充足

4. **官网查询**
   - 如果API查询失败，可使用官网链接
   - 官网查询需要手动输入手机号后4位

---

## 扩展其他快递公司

### 1. 修改 ExpressTrackService.php

在 `resolveCarrier` 方法中添加新的快递公司识别：

```php
if ($ec === 'ems') {
    return ['carrier' => 'ems', 'kuaidi_com' => 'ems', 'label' => 'EMS'];
}
```

### 2. 添加官网链接

在 `officialUrls` 方法中添加：

```php
return [
    'sf' => '...',
    'jd' => '...',
    'ems' => 'https://www.ems.com.cn/queryList?mailNum=' . $enc,
];
```

### 3. 更新前端选项

在 `order_list.vue` 中添加选项：

```vue
<el-option label="EMS" value="ems" />
```

---

## 故障排查

### 问题1：提示"未配置快递100查询密钥"

**解决方案：**
1. 检查 `.env` 文件中的配置
2. 确认 `LOGISTICS_KUAIDI100_ENABLE=true`
3. 重启服务器

### 问题2：查询返回"查询失败"

**可能原因：**
1. 运单号错误
2. 快递尚未揽收
3. 快递100账户余额不足
4. 手机号后4位不匹配（顺丰）

**解决方案：**
1. 核对运单号
2. 等待快递揽收后再查询
3. 充值快递100账户
4. 使用官网链接手动查询

### 问题3：顺丰查询失败但京东正常

**原因：**
顺丰查询需要手机号后4位验证

**解决方案：**
1. 确保订单中填写了正确的收件人手机号
2. 使用官网链接，手动输入手机号后4位

---

## API 接口说明

### 查询物流轨迹

**接口：** `GET /tcm.prescriptionOrder/logisticsTrace`

**参数：**
- `id` (必填): 业务订单ID
- `express_company` (可选): 快递公司 (auto/sf/jd)

**返回示例：**

```json
{
    "carrier": "sf",
    "carrier_label": "顺丰速运",
    "kuaidi_com": "shunfeng",
    "traces": [
        {
            "time": "2024-01-15 10:30:00",
            "context": "快件已签收"
        },
        {
            "time": "2024-01-15 08:00:00",
            "context": "派件中"
        }
    ],
    "state": "3",
    "state_text": "已签收",
    "source": "kuaidi100",
    "hint": "",
    "official_url": "https://www.sf-express.com/...",
    "official_urls": {
        "sf": "https://www.sf-express.com/...",
        "jd": "https://www.jdl.com/..."
    },
    "tracking_number": "SF1234567890",
    "express_company_used": "sf"
}
```

---

## 费用说明

### 快递100 API

- 按查询次数计费
- 具体价格请咨询快递100官方
- 建议：配置后台缓存减少重复查询

### 官网查询

- 完全免费
- 需要用户手动跳转
- 顺丰需要手机号验证

---

## 更新日志

### 2024-01-15
- 更新顺丰官网查询链接（新版）
- 更新京东物流查询链接
- 优化手机号后4位自动传入逻辑
- 完善错误提示信息