# 物流查询功能更新说明

## 更新内容

### 1. 更新官网查询链接

#### 顺丰速运
- **旧链接**：`https://ucmp.sf-express.com/cx/#/waybill/waybill-search?waybillNumber={单号}`
- **新链接**：`https://www.sf-express.com/cn/sc/dynamic_function/waybill/#search/bill-number/{单号}`
- **说明**：更新为顺丰官网最新版查询页面

#### 京东物流
- **旧链接**：`https://www.jdl.com/express/tracking/?waybillCodes={单号}`
- **新链接**：`https://www.jdl.com/#/trackQuery?waybillCode={单号}`
- **说明**：更新为京东物流最新版查询页面

### 2. 更新文件列表

- `server/app/common/service/ExpressTrackService.php` - 后端服务类
- `admin/src/views/consumer/prescription/order_list.vue` - 前端订单列表页面

### 3. 新增文档

- `LOGISTICS_INTEGRATION_GUIDE.md` - 完整的物流集成指南
- `server/.env.logistics.example` - 环境变量配置示例
- `server/test_logistics.php` - 物流查询测试脚本

---

## 快速开始

### 方案一：使用快递100 API（推荐）

#### 1. 注册快递100账号
访问：https://www.kuaidi100.com/
- 注册企业账号
- 申请API接口权限
- 获取 Customer 和 Key

#### 2. 配置环境变量
在 `server/.env` 文件中添加：

```env
LOGISTICS_KUAIDI100_CUSTOMER=你的customer
LOGISTICS_KUAIDI100_KEY=你的key
```

#### 3. 重启服务器
```bash
# 重启PHP服务
systemctl restart php-fpm

# 或重启整个应用
```

#### 4. 测试配置
```bash
cd server
php test_logistics.php
```

### 方案二：使用官网链接（免费）

无需配置，系统会自动提供官网查询链接：
- 顺丰速运：需要输入收件人手机号后4位
- 京东物流：直接查询

---

## 使用说明

### 前端操作

1. 进入"业务订单列表"
2. 点击订单查看详情
3. 在"物流轨迹"区域：
   - 选择快递公司（自动识别/顺丰/京东）
   - 点击"查询物流"按钮
   - 查看实时物流轨迹
4. 备用方案：
   - 点击"顺丰官网查件"或"京东物流查件"
   - 跳转到官网手动查询

### 自动识别规则

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

---

## 顺丰查询问题解决

### 问题：查不到顺丰快递

#### 原因分析
1. **手机号验证失败**
   - 顺丰查询需要收件人手机号后4位
   - 系统会自动从订单中获取手机号
   - 如果手机号不正确，查询会失败

2. **运单号错误**
   - 确保运单号完整且正确
   - 顺丰运单号通常以 `SF` 开头

3. **快递未揽收**
   - 刚下单的快递可能还未揽收
   - 等待快递员揽收后再查询

4. **快递100配置问题**
   - Customer 或 Key 配置错误
   - 账户余额不足

#### 解决方案

**方案1：检查订单手机号**
```
1. 打开订单详情
2. 确认"收件人手机号"字段填写正确
3. 重新查询物流
```

**方案2：使用官网查询**
```
1. 点击"顺丰官网查件"链接
2. 在官网页面手动输入手机号后4位
3. 查看物流信息
```

**方案3：检查快递100配置**
```bash
# 1. 查看配置
cat server/.env | grep LOGISTICS_KUAIDI100

# 2. 测试配置
cd server
php test_logistics.php

# 3. 检查日志
tail -f runtime/log/error.log
```

---

## 京东查询问题解决

### 问题：查不到京东快递

#### 原因分析
1. 运单号错误
2. 快递未揽收
3. 快递100配置问题

#### 解决方案

**方案1：核对运单号**
- 确保运单号完整且正确
- 京东运单号通常以 `JD` 开头

**方案2：使用官网查询**
- 点击"京东物流查件"链接
- 京东查询无需手机号验证

**方案3：等待揽收**
- 刚下单的快递可能还未揽收
- 等待1-2小时后再查询

---

## API 接口说明

### 查询物流轨迹

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

**请求参数：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | number | 是 | 业务订单ID |
| express_company | string | 否 | 快递公司 (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"
}
```

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

---

## 测试步骤

### 1. 测试配置
```bash
cd server
php test_logistics.php
```

### 2. 测试官网链接
1. 打开浏览器
2. 访问生成的官网链接
3. 确认能正常打开查询页面

### 3. 测试实时查询（需要配置快递100）
1. 在订单中填写真实的快递单号
2. 点击"查询物流"按钮
3. 查看是否返回物流轨迹

### 4. 测试手机号验证（顺丰）
1. 创建订单时填写正确的收件人手机号
2. 查询顺丰快递
3. 确认能正常返回结果

---

## 常见问题

### Q1: 为什么快递100查询失败？
**A:** 可能原因：
1. 未配置 Customer 和 Key
2. 账户余额不足
3. 运单号错误或快递未揽收
4. 网络连接问题

### Q2: 顺丰查询为什么需要手机号？
**A:** 顺丰为了保护用户隐私，查询时需要验证收件人手机号后4位。系统会自动从订单中获取手机号传给快递100。

### Q3: 可以添加其他快递公司吗？
**A:** 可以。参考 `LOGISTICS_INTEGRATION_GUIDE.md` 中的"扩展其他快递公司"章节。

### Q4: 快递100收费吗？
**A:** 是的，快递100按查询次数收费。具体价格请咨询快递100官方。

### Q5: 不配置快递100可以用吗？
**A:** 可以。系统会提供官网查询链接，用户可以跳转到官网手动查询。

---

## 技术支持

### 相关文档
- `LOGISTICS_INTEGRATION_GUIDE.md` - 完整集成指南
- `server/.env.logistics.example` - 配置示例
- 快递100官方文档：https://api.kuaidi100.com/

### 日志查看
```bash
# 查看错误日志
tail -f server/runtime/log/error.log

# 查看应用日志
tail -f server/runtime/log/app.log
```

### 联系方式
如有问题，请查看项目文档或联系技术支持。

---

## 更新历史

### 2024-01-15
- 更新顺丰官网查询链接（新版）
- 更新京东物流查询链接
- 新增完整的集成指南文档
- 新增配置示例文件
- 新增测试脚本
- 优化错误提示信息