新增

2026-04-07 18:13:03 +08:00
parent a780356908
commit fdf714f833
397 changed files with 15086 additions and 1043 deletions
@@ -0,0 +1,251 @@
+# 极兔速递支持已添加
+
+## 更新说明
+
+系统已添加极兔速递（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/