309 lines
6.9 KiB
Markdown
309 lines
6.9 KiB
Markdown
# 物流查询功能更新说明
|
||
|
||
## 更新内容
|
||
|
||
### 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
|
||
- 更新顺丰官网查询链接（新版）
|
||
- 更新京东物流查询链接
|
||
- 新增完整的集成指南文档
|
||
- 新增配置示例文件
|
||
- 新增测试脚本
|
||
- 优化错误提示信息
|