7.6 KiB
7.6 KiB
物流追踪系统 - 快速开始
5分钟快速部署
1. 安装数据库表
Linux/Mac:
chmod +x install_express_tracking.sh
./install_express_tracking.sh
Windows:
install_express_tracking.bat
或手动执行SQL:
mysql -u root -p your_database < server/database/migrations/create_express_tracking_tables.sql
2. 注册命令
编辑 server/config/console.php，在 commands 数组中添加：
'commands' => [
// ... 其他命令
'express:auto-update' => \app\command\ExpressAutoUpdate::class,
],
3. 测试命令
cd server
php think express:auto-update
应该看到：
开始自动更新物流信息...
更新完成！
总数: 0
成功: 0
失败: 0
耗时: 0.05秒
4. 配置定时任务
Linux/Mac (crontab):
crontab -e
# 添加以下行（每10分钟执行）
*/10 * * * * cd /path/to/your/server && php think express:auto-update >> /dev/null 2>&1
Windows (计划任务):
schtasks /create /tn "ExpressAutoUpdate" /tr "php D:\path\to\server\think express:auto-update" /sc minute /mo 10
使用示例
示例1：订单发货时创建追踪
use app\common\service\ExpressTrackingService;
// 在订单发货时调用
$tracking = ExpressTrackingService::createOrUpdate([
'order_id' => $order->id,
'order_type' => 'prescription',
'tracking_number' => 'JD0230761381812',
'express_company' => 'jd',
'recipient_phone' => $order->recipient_phone,
'recipient_name' => $order->recipient_name,
'recipient_address' => $order->shipping_address,
]);
// 系统会：
// 1. 创建追踪记录
// 2. 立即查询物流信息
// 3. 存储到数据库
// 4. 开始自动更新
示例2：查询物流详情
// 获取完整物流信息
$detail = ExpressTrackingService::getDetail($trackingId);
// 返回数据包含：
// - 基本信息（单号、快递公司、收件人等）
// - 当前状态（在途、派件、签收等）
// - 所有轨迹记录（时间、内容、位置）
// - 状态变更历史
示例3：手动更新
// 手动触发更新
$result = ExpressTrackingService::queryAndUpdate($trackingId, false);
// 返回最新的物流信息
集成到现有系统
修改订单创建逻辑
在 server/app/adminapi/logic/tcm/PrescriptionOrderLogic.php 的 create() 方法中添加：
public static function create(array $params, int $adminId, array $adminInfo)
{
// ... 原有代码
$order->save();
// 【新增】创建物流追踪
if (!empty($params['tracking_number'])) {
\app\common\service\ExpressTrackingService::createOrUpdate([
'order_id' => $order->id,
'order_type' => 'prescription',
'tracking_number' => $params['tracking_number'],
'express_company' => $params['express_company'] ?? 'auto',
'recipient_phone' => $order->recipient_phone,
'recipient_name' => $order->recipient_name,
'recipient_address' => $order->shipping_address,
]);
}
return $out;
}
修改订单编辑逻辑
在 edit() 方法中添加：
public static function edit(array $params, int $adminId, array $adminInfo)
{
// ... 原有代码
$order->save();
// 【新增】更新物流追踪
if (array_key_exists('tracking_number', $params) && !empty($params['tracking_number'])) {
\app\common\service\ExpressTrackingService::createOrUpdate([
'order_id' => $order->id,
'order_type' => 'prescription',
'tracking_number' => $params['tracking_number'],
'express_company' => $order->express_company,
'recipient_phone' => $order->recipient_phone,
'recipient_name' => $order->recipient_name,
'recipient_address' => $order->shipping_address,
]);
}
return $out;
}
修改物流查询接口
在 logisticsTrace() 方法开头添加：
public static function logisticsTrace(int $id, string $expressCompanyOverride, int $adminId, array $adminInfo): ?array
{
// ... 权限检查等原有代码
// 【新增】优先从数据库获取
$tracking = \app\common\model\ExpressTracking::where('order_id', $id)
->where('order_type', 'prescription')
->whereNull('delete_time')
->find();
if ($tracking) {
// 如果距离上次查询超过5分钟，重新查询
if (time() - $tracking->last_query_time > 300) {
\app\common\service\ExpressTrackingService::queryAndUpdate($tracking->id, false);
$tracking->refresh();
}
// 返回数据库中的数据
$traces = $tracking->traces->map(function($trace) {
return [
'time' => $trace->trace_time,
'context' => $trace->trace_context,
'status' => $trace->status,
'location' => $trace->location,
];
})->toArray();
$payload = [
'carrier' => $tracking->express_company,
'carrier_label' => $tracking->express_company_name,
'traces' => $traces,
'state' => $tracking->current_state,
'state_text' => $tracking->current_state_text,
'source' => $tracking->data_source,
'official_urls' => ExpressTrackService::officialUrls($tracking->tracking_number),
'tracking_number' => $tracking->tracking_number,
'is_signed' => $tracking->is_signed,
'estimated_arrival_time' => $tracking->estimated_arrival_time,
];
return $payload;
}
// 如果数据库中没有，走原有逻辑
// ... 原有查询代码
}
验证安装
1. 检查数据库表
SHOW TABLES LIKE 'zyt_express%';
-- 应该看到4个表：
-- zyt_express_tracking
-- zyt_express_trace
-- zyt_express_state_log
-- zyt_express_query_log
2. 测试创建追踪
$tracking = ExpressTrackingService::createOrUpdate([
'order_id' => 1,
'order_type' => 'test',
'tracking_number' => 'JD0230761381812',
'express_company' => 'jd',
'recipient_phone' => '13800138000',
'recipient_name' => '测试',
'recipient_address' => '测试地址',
]);
var_dump($tracking->id); // 应该返回ID
3. 检查定时任务
# 查看crontab
crontab -l | grep express
# 手动执行一次
cd server && php think express:auto-update
# 查看日志
tail -f runtime/log/info.log
常见问题
Q: 定时任务不执行？
A: 检查crontab配置和PHP路径
# 查看crontab
crontab -l
# 检查PHP路径
which php
# 查看cron日志
tail -f /var/log/cron
Q: 快递100返回"找不到对应公司"？
A: 账号未充值，请先充值快递100账户
- 登录：https://www.kuaidi100.com/
- 充值后重试
Q: 如何停止某个快递的自动更新？
A:
$tracking = ExpressTracking::find($id);
$tracking->auto_update = 0;
$tracking->save();
Q: 如何修改更新频率？
A:
// 修改单个追踪记录的更新间隔
$tracking->update_interval = 3600; // 1小时
$tracking->save();
// 或修改crontab执行频率
crontab -e
# 改为每30分钟: */30 * * * *
下一步
- ✅ 确认快递100已充值
- ✅ 集成到订单系统
- ✅ 配置定时任务
- ✅ 测试物流查询
- 📖 阅读完整文档：
EXPRESS_TRACKING_SYSTEM.md
技术支持
- 完整文档：
EXPRESS_TRACKING_SYSTEM.md - 快递100文档：https://api.kuaidi100.com/
- 问题排查：
KUAIDI100_TROUBLESHOOTING.md