# 极兔速递支持已添加

## 更新说明

系统已添加极兔速递（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/