新增

2026-04-07 18:13:03 +08:00
parent a780356908
commit fdf714f833
397 changed files with 15086 additions and 1043 deletions
@@ -0,0 +1,308 @@
+# 物流查询功能更新说明
+
+## 更新内容
+
+### 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
+- 更新顺丰官网查询链接（新版）
+- 更新京东物流查询链接
+- 新增完整的集成指南文档
+- 新增配置示例文件
+- 新增测试脚本
+- 优化错误提示信息