物流跟踪API | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

物流跟踪API

简介

本文件面向电商物流模块开发者，提供“物流跟踪”相关API的完整参考。内容覆盖：

发货信息录入接口：物流公司选择、运单号填写、发货确认
物流状态查询接口：基于运单号的轨迹与当前位置查询（对接第三方快递）
签收确认接口：用户确认收货与自动签收机制说明
异常处理流程：丢件、破损、延误等异常的处理逻辑
费用计算接口：按重量、距离、地区等因素计算运费
服务商集成接口：多快递公司对接方式
数据同步与缓存策略：物流数据同步与缓存建议
前端可视化集成指南：追踪轨迹展示的前端接入要点

项目结构

本项目采用模块化分层设计，物流跟踪能力主要分布在以下位置：

后台订单模块：负责物流信息录入、状态推进、库存解锁等
插件体系：通过“配送方式插件”扩展物流服务商与运费计算
订单状态机：确保订单从已付款到已完成的状态流转正确
支付服务：与物流联动（如货到付款、无物流时直接完成）
前端模板与脚本：订单详情页展示物流信息、运费动态切换

graph TB
A["后台订单控制器<br/>OrderController"] --> B["后台订单服务<br/>OrderService"]
B --> C["订单模型<br/>Order"]
B --> D["订单状态机<br/>OrderStatusTransition"]
A --> E["后台路由<br/>order.php"]
B --> F["支付服务<br/>PaymentService"]
B --> G["配送插件服务<br/>ExpressService"]
H["前端页面/脚本<br/>global.js"] --> I["订单详情视图<br/>order.htm"]

核心组件

后台订单控制器：暴露物流录入接口（POST /order/tracking），接收校验后的表单数据并调用服务层
后台订单服务：实现物流信息保存、首次发货时的订单状态推进与库存解锁
订单模型：定义可写入字段（shipping_id、tracking_no、shipped_at 等）
订单状态机：控制订单状态转换，结合是否启用物流插件决定最终状态
支付服务：在货到付款或无物流场景下联动订单状态推进
快递插件服务：提供配送方式列表与基础运费配置
前端脚本：支持运费动态切换与订单金额更新

架构总览

物流跟踪的核心流程围绕“后台订单物流录入”展开：管理员在订单详情页选择物流公司并填写运单号，提交后系统保存物流信息；若为首次发货，则推进订单状态并解锁库存。同时，系统根据是否启用物流插件决定付款后是否直接进入“已完成”。

sequenceDiagram
participant Admin as "管理员"
participant Route as "后台路由 order.php"
participant Ctrl as "OrderController"
participant Svc as "OrderService"
participant Model as "Order 模型"
participant State as "OrderStatusTransition"
participant Pay as "PaymentService"
Admin->>Route : POST /order/tracking
Route->>Ctrl : tracking(form)
Ctrl->>Svc : tracking(data)
Svc->>Model : 更新 shipping_id/tracking_no/shipped_at
alt 首次发货
Svc->>State : changeStatus(COMPLETED)
State-->>Svc : 状态变更成功
Svc->>Pay : 必要时联动支付/状态
else 非首次发货
Svc-->>Admin : 仅更新物流信息
end
Ctrl-->>Admin : 重定向至订单详情

详细组件分析

发货信息录入接口（POST /order/tracking）

功能：保存物流公司与运单号；首次填写时推进订单状态并解锁库存
请求参数
- order_id：必填，正整数
- shipping_id：可选，物流公司标识（最大长度限制）
- tracking_no：可选，运单号（最大长度限制）
响应：成功后重定向至订单详情页
业务规则
- 若订单已有运单号：仅更新物流信息与发货时间
- 若首次填写：将订单状态推进至“已完成”，并设置允许售后、解锁库存

flowchart TD
Start(["进入 tracking()"]) --> Validate["校验 order_id"]
Validate --> |无效| Err1["抛出非法参数异常"]
Validate --> |有效| LoadOrder["加载订单"]
LoadOrder --> |不存在| Err2["抛出非法参数异常"]
LoadOrder --> CheckTrack{"是否已有运单号?"}
CheckTrack --> |是| UpdateOnly["更新 shipping_id/tracking_no/shipped_at"]
CheckTrack --> |否| PushStatus["推进订单状态为 COMPLETED"]
PushStatus --> UnlockStock["解锁库存并允许售后"]
UpdateOnly --> Redirect["返回详情页URL"]
UnlockStock --> Redirect
Err1 --> End(["结束"])
Err2 --> End
Redirect --> End

物流状态查询接口（GET /order/tracking/{tracking_no}）

功能：根据运单号查询包裹运输轨迹与当前位置
说明：当前仓库未提供内置的物流轨迹查询实现；需通过“配送方式插件”扩展对接第三方快递API
建议实现
- 在 ExpressService 中增加 methods() 之外的查询方法，例如 queryTracking(trackingNo)
- 控制器新增 getTracking(trackingNo) 方法，调用插件查询并返回标准化结果
- 前端通过 AJAX 轮询或 WebSocket 获取最新轨迹

注意：本节为扩展建议，当前代码库未包含具体实现。

签收确认接口（POST /order/sign/{order_sn}）

功能：用户确认收货或系统自动签收
说明：当前仓库未提供专门的签收接口；可通过订单状态机与支付服务联动实现
建议实现
- 当订单处于“已发货”且超过预计送达时间，系统自动推进至“已完成”
- 用户手动确认后，调用状态机推进并完成售后标记
- 结合 PaymentService 的 markSucceeded 进行幂等收尾

注意：本节为扩展建议，当前代码库未包含具体实现。

异常处理流程（丢件、破损、延误）

丢件：触发售后流程，记录异常类型与时间，通知客服介入
破损：拍照上传证据，创建退款或换货申请
延误：延长售后时限，发送提醒通知
建议实现
- 在订单服务中增加异常事件监听，统一记录异常日志
- 与支付服务联动，必要时发起退款或补偿
- 通过插件体系扩展不同快递公司的异常回调

注意：本节为扩展建议，当前代码库未包含具体实现。

物流费用计算接口（POST /order/calculate-shipping）

功能：按重量、距离、地区等因素计算运费
说明：当前通过“配送方式插件”提供基础运费配置；可扩展更复杂的计费规则
建议实现
- 在 ExpressService 中增加 calculate(weight, distance, region) 方法
- 控制器调用插件计算并返回运费明细
- 前端使用 global.js 中的 changeShipping 逻辑进行动态更新

物流服务商集成接口

功能：支持与多家快递公司对接
说明：通过插件体系扩展配送方式；当前提供“快递配送”基础插件
建议实现
- 新增插件类继承 BaseService，实现 methods() 与查询/下单/回调方法
- 在订单服务中调用插件 API 完成下单与轨迹查询
- 统一管理插件配置与密钥

物流数据同步机制与缓存策略

数据同步：建议通过定时任务拉取第三方快递轨迹，增量更新本地数据库
缓存策略：对常用查询结果（如快递公司列表、运费规则）进行短期缓存
一致性保障：使用事务保证订单状态与物流信息的一致性
错误重试：对第三方API失败进行指数退避重试

注意：本节为扩展建议，当前代码库未包含具体实现。

前端可视化展示集成指南

订单详情页：展示物流公司、运单号、发货时间
轨迹展示：通过 AJAX 调用查询接口，渲染时间轴地图
运费切换：使用 global.js 中的 changeShipping 函数动态更新运费与订单金额
状态提示：根据订单状态显示“未发货”、“已发货”、“已完成”等状态

依赖关系分析

控制器依赖路由与服务层
服务层依赖模型、状态机与支付服务
插件体系提供扩展点
前端脚本与后端接口协同工作

graph LR
R["order.php"] --> C["OrderController"]
C --> S["OrderService"]
S --> M["Order"]
S --> T["OrderStatusTransition"]
S --> P["PaymentService"]
S --> X["ExpressService"]
F["global.js"] --> V["order.htm"]

性能考虑

减少数据库查询：批量更新物流信息时使用事务
缓存热点数据：快递公司列表、运费规则短期缓存
异步处理：轨迹查询与通知发送使用队列
限流保护：对高频查询接口进行限流

故障排查指南

参数校验失败：检查 order_id、shipping_id、tracking_no 是否符合规则
订单不存在：确认订单ID有效性
状态机拒绝：检查订单当前状态是否允许目标状态转换
支付联动失败：查看支付服务日志，确认订单状态是否可收款
插件调用失败：检查插件配置与网络连通性

结论

本API文档基于现有代码库梳理了物流跟踪的核心能力，包括发货信息录入、状态推进、库存解锁等。对于轨迹查询、签收确认、异常处理、费用计算与服务商集成等扩展能力，提供了明确的实现建议。开发者可在此基础上快速构建完整的物流模块。

附录

关键接口路径
- 发货信息录入：POST /order/tracking
- 物流状态查询（扩展）：GET /order/tracking/{tracking_no}
- 签收确认（扩展）：POST /order/sign/{order_sn}
- 费用计算（扩展）：POST /order/calculate-shipping
相关文件路径
- 后台路由：_'/module/order/admin/route/order.php
- 控制器：_'/module/order/admin/controller/order/OrderController.php
- 服务层：_'/module/order/admin/service/order/OrderService.php
- 模型：_'/module/order/admin/model/order/Order.php
- 状态机：_'/module/order/core/service/order/OrderStatusTransition.php
- 支付服务：core/service/payment/PaymentService.php
- 插件服务：plugin/express/ExpressService.php
- 前端脚本：_'/theme/landou/images/global.js

添加日期：2026-10-05