zyt/LOGISTICS_UPDATE_README.md

物流查询功能更新说明

更新内容

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 文件中添加：

LOGISTICS_KUAIDI100_CUSTOMER=你的customer
LOGISTICS_KUAIDI100_KEY=你的key

3. 重启服务器

# 重启PHP服务
systemctl restart php-fpm

# 或重启整个应用

4. 测试配置

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配置

# 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)

返回示例：

{
    "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. 测试配置

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/

日志查看

# 查看错误日志
tail -f server/runtime/log/error.log

# 查看应用日志
tail -f server/runtime/log/app.log

联系方式

如有问题，请查看项目文档或联系技术支持。

---

更新历史

2024-01-15

• 更新顺丰官网查询链接（新版）
• 更新京东物流查询链接
• 新增完整的集成指南文档
• 新增配置示例文件
• 新增测试脚本
• 优化错误提示信息