252 lines
5.8 KiB
Markdown
252 lines
5.8 KiB
Markdown
# 极兔速递支持已添加
|
|
|
|
## 更新说明
|
|
|
|
系统已添加极兔速递（J&T Express）的物流查询支持。
|
|
|
|
### 单号示例
|
|
- `JT5472795424064` - 极兔速递单号格式：JT + 13位数字
|
|
|
|
---
|
|
|
|
## 更新内容
|
|
|
|
### 1. 后端更新
|
|
|
|
**文件：** `server/app/common/service/ExpressTrackService.php`
|
|
|
|
- 添加极兔速递常量 `KUAIDI_COM_JT = 'jtexpress'`
|
|
- 添加极兔单号识别规则：`/^JT\d{13}$/i`
|
|
- 添加极兔官网查询链接：`https://www.jtexpress.com.cn/index/query/gzquery.html?bills={单号}`
|
|
- 更新 `resolveCarrier()` 方法支持极兔识别
|
|
- 更新 `officialUrls()` 方法返回极兔链接
|
|
|
|
**文件：** `server/app/adminapi/logic/tcm/PrescriptionOrderLogic.php`
|
|
|
|
- 更新 `normalizeExpressCompany()` 方法支持 `jt` 和 `jtexpress`
|
|
|
|
### 2. 前端更新
|
|
|
|
**文件：** `admin/src/views/consumer/prescription/order_list.vue`
|
|
|
|
- 添加极兔速递选项到快递公司下拉框
|
|
- 添加"极兔速递查件"官网链接按钮
|
|
- 更新 `expressCompanyLabel()` 函数支持极兔显示
|
|
- 更新 `detailOfficialUrls` 计算属性包含极兔链接
|
|
- 更新提示文本说明支持极兔速递
|
|
|
|
---
|
|
|
|
## 使用方法
|
|
|
|
### 方式一：自动识别（推荐）
|
|
|
|
系统会自动识别以 `JT` 开头且后跟13位数字的单号为极兔速递。
|
|
|
|
**示例：**
|
|
- 单号：`JT5472795424064`
|
|
- 快递公司：选择"自动识别"
|
|
- 系统自动识别为：极兔速递
|
|
|
|
### 方式二：手动选择
|
|
|
|
在订单编辑或查询时，手动选择"极兔速递"。
|
|
|
|
**步骤：**
|
|
1. 打开业务订单详情
|
|
2. 在"快递公司"下拉框中选择"极兔速递"
|
|
3. 填写快递单号
|
|
4. 点击"查询物流"
|
|
|
|
---
|
|
|
|
## 快递100 API 支持
|
|
|
|
极兔速递在快递100中的编码为 `jtexpress`，系统已配置。
|
|
|
|
### 查询参数示例
|
|
|
|
```json
|
|
{
|
|
"com": "jtexpress",
|
|
"num": "JT5472795424064",
|
|
"resultv2": "1"
|
|
}
|
|
```
|
|
|
|
### 注意事项
|
|
|
|
1. **快递100配置**
|
|
- 确保已配置 `LOGISTICS_KUAIDI100_CUSTOMER` 和 `LOGISTICS_KUAIDI100_KEY`
|
|
- 确保 `LOGISTICS_KUAIDI100_DISABLE = false`
|
|
|
|
2. **单号格式**
|
|
- 极兔单号通常为：JT + 13位数字
|
|
- 示例：`JT5472795424064`
|
|
|
|
3. **查询时机**
|
|
- 快递已揽收后才能查询到物流信息
|
|
- 刚下单的快递可能需要等待1-2小时
|
|
|
|
---
|
|
|
|
## 官网查询
|
|
|
|
如果快递100查询失败，可以使用官网链接：
|
|
|
|
**极兔速递官网：** https://www.jtexpress.com.cn/
|
|
|
|
**查询链接格式：**
|
|
```
|
|
https://www.jtexpress.com.cn/index/query/gzquery.html?bills={单号}
|
|
```
|
|
|
|
**示例：**
|
|
```
|
|
https://www.jtexpress.com.cn/index/query/gzquery.html?bills=JT5472795424064
|
|
```
|
|
|
|
---
|
|
|
|
## 测试
|
|
|
|
### 测试脚本
|
|
|
|
运行测试脚本验证极兔速递支持：
|
|
|
|
```bash
|
|
cd server
|
|
php test_jt_express.php
|
|
```
|
|
|
|
### 测试步骤
|
|
|
|
1. **创建测试订单**
|
|
- 快递公司：选择"极兔速递"或"自动识别"
|
|
- 快递单号：`JT5472795424064`（替换为真实单号）
|
|
|
|
2. **查询物流**
|
|
- 打开订单详情
|
|
- 点击"查询物流"按钮
|
|
- 查看是否返回物流轨迹
|
|
|
|
3. **官网查询**
|
|
- 点击"极兔速递查件"链接
|
|
- 确认能正常打开极兔官网查询页面
|
|
|
|
---
|
|
|
|
## 支持的快递公司列表
|
|
|
|
| 快递公司 | 代码 | 快递100编码 | 单号格式 | 自动识别 |
|
|
|---------|------|------------|---------|---------|
|
|
| 顺丰速运 | sf | shunfeng | SF + 数字 | ✅ |
|
|
| 京东快递 | jd | jd | JD/JDV/JDK/JDEX + 数字 | ✅ |
|
|
| 极兔速递 | jt | jtexpress | JT + 13位数字 | ✅ |
|
|
|
|
---
|
|
|
|
## 扩展其他快递公司
|
|
|
|
如需添加更多快递公司（如中通、圆通、申通等），请参考以下步骤：
|
|
|
|
### 1. 查询快递100编码
|
|
|
|
访问快递100官方文档查询快递公司编码：
|
|
https://api.kuaidi100.com/document/5f0ffb5ebc8da837cbd8aefc/5f0ffc3cbc8da837cbd8afc0
|
|
|
|
### 2. 修改后端代码
|
|
|
|
在 `ExpressTrackService.php` 中：
|
|
|
|
```php
|
|
// 添加常量
|
|
private const KUAIDI_COM_ZTO = 'zhongtong'; // 中通快递
|
|
|
|
// 添加识别规则
|
|
if ($ec === 'zto' || $ec === 'zhongtong') {
|
|
return ['carrier' => 'zto', 'kuaidi_com' => self::KUAIDI_COM_ZTO, 'label' => '中通快递'];
|
|
}
|
|
|
|
// 添加单号自动识别（可选）
|
|
if (preg_match('/^[0-9]{12}$/', $num)) {
|
|
return ['carrier' => 'zto', 'kuaidi_com' => self::KUAIDI_COM_ZTO, 'label' => '中通快递（单号识别）'];
|
|
}
|
|
|
|
// 添加官网链接
|
|
'zto' => 'https://www.zto.com/GuestService/Bill?txtBill=' . $enc,
|
|
```
|
|
|
|
### 3. 修改前端代码
|
|
|
|
在 `order_list.vue` 中：
|
|
|
|
```vue
|
|
<!-- 添加选项 -->
|
|
<el-option label="中通快递" value="zto" />
|
|
|
|
<!-- 添加官网链接 -->
|
|
<el-link :href="detailOfficialUrls.zto" target="_blank" type="primary">中通快递查件</el-link>
|
|
|
|
<!-- 更新计算属性 -->
|
|
zto: `https://www.zto.com/GuestService/Bill?txtBill=${enc}`
|
|
|
|
<!-- 更新标签函数 -->
|
|
if (s === 'zto' || s === 'zhongtong') return '中通快递'
|
|
```
|
|
|
|
### 4. 更新后端逻辑
|
|
|
|
在 `PrescriptionOrderLogic.php` 中：
|
|
|
|
```php
|
|
if (!in_array($ec, ['sf', 'jd', 'jt', 'zto', 'auto'], true)) {
|
|
return 'auto';
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 常见问题
|
|
|
|
### Q1: 极兔单号查询失败？
|
|
|
|
**可能原因：**
|
|
1. 快递尚未揽收
|
|
2. 单号格式错误
|
|
3. 快递100配置问题
|
|
|
|
**解决方案：**
|
|
1. 确认单号格式：JT + 13位数字
|
|
2. 等待快递揽收后再查询
|
|
3. 使用"极兔速递查件"官网链接
|
|
|
|
### Q2: 自动识别不准确？
|
|
|
|
**解决方案：**
|
|
手动选择快递公司，不使用"自动识别"。
|
|
|
|
### Q3: 如何添加更多快递公司？
|
|
|
|
参考上面的"扩展其他快递公司"章节。
|
|
|
|
---
|
|
|
|
## 更新历史
|
|
|
|
### 2024-01-15
|
|
- ✅ 添加极兔速递支持
|
|
- ✅ 支持单号自动识别（JT + 13位数字）
|
|
- ✅ 添加极兔官网查询链接
|
|
- ✅ 更新前端选项和显示
|
|
- ✅ 创建测试脚本
|
|
|
|
---
|
|
|
|
## 相关文档
|
|
|
|
- `LOGISTICS_INTEGRATION_GUIDE.md` - 完整物流集成指南
|
|
- `LOGISTICS_UPDATE_README.md` - 物流功能更新说明
|
|
- `server/.env.logistics.example` - 配置示例
|
|
- 快递100官方文档：https://api.kuaidi100.com/
|