336 lines
7.6 KiB
Markdown
336 lines
7.6 KiB
Markdown
# 物流追踪系统 - 快速开始
|
||
|
||
## 5分钟快速部署
|
||
|
||
### 1. 安装数据库表
|
||
|
||
**Linux/Mac:**
|
||
```bash
|
||
chmod +x install_express_tracking.sh
|
||
./install_express_tracking.sh
|
||
```
|
||
|
||
**Windows:**
|
||
```cmd
|
||
install_express_tracking.bat
|
||
```
|
||
|
||
**或手动执行SQL:**
|
||
```bash
|
||
mysql -u root -p your_database < server/database/migrations/create_express_tracking_tables.sql
|
||
```
|
||
|
||
### 2. 注册命令
|
||
|
||
编辑 `server/config/console.php`，在 `commands` 数组中添加：
|
||
|
||
```php
|
||
'commands' => [
|
||
// ... 其他命令
|
||
'express:auto-update' => \app\command\ExpressAutoUpdate::class,
|
||
],
|
||
```
|
||
|
||
### 3. 测试命令
|
||
|
||
```bash
|
||
cd server
|
||
php think express:auto-update
|
||
```
|
||
|
||
应该看到：
|
||
```
|
||
开始自动更新物流信息...
|
||
更新完成！
|
||
总数: 0
|
||
成功: 0
|
||
失败: 0
|
||
耗时: 0.05秒
|
||
```
|
||
|
||
### 4. 配置定时任务
|
||
|
||
**Linux/Mac (crontab):**
|
||
```bash
|
||
crontab -e
|
||
|
||
# 添加以下行（每10分钟执行）
|
||
*/10 * * * * cd /path/to/your/server && php think express:auto-update >> /dev/null 2>&1
|
||
```
|
||
|
||
**Windows (计划任务):**
|
||
```cmd
|
||
schtasks /create /tn "ExpressAutoUpdate" /tr "php D:\path\to\server\think express:auto-update" /sc minute /mo 10
|
||
```
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### 示例1：订单发货时创建追踪
|
||
|
||
```php
|
||
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：查询物流详情
|
||
|
||
```php
|
||
// 获取完整物流信息
|
||
$detail = ExpressTrackingService::getDetail($trackingId);
|
||
|
||
// 返回数据包含：
|
||
// - 基本信息（单号、快递公司、收件人等）
|
||
// - 当前状态（在途、派件、签收等）
|
||
// - 所有轨迹记录（时间、内容、位置）
|
||
// - 状态变更历史
|
||
```
|
||
|
||
### 示例3：手动更新
|
||
|
||
```php
|
||
// 手动触发更新
|
||
$result = ExpressTrackingService::queryAndUpdate($trackingId, false);
|
||
|
||
// 返回最新的物流信息
|
||
```
|
||
|
||
---
|
||
|
||
## 集成到现有系统
|
||
|
||
### 修改订单创建逻辑
|
||
|
||
在 `server/app/adminapi/logic/tcm/PrescriptionOrderLogic.php` 的 `create()` 方法中添加：
|
||
|
||
```php
|
||
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()` 方法中添加：
|
||
|
||
```php
|
||
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()` 方法开头添加：
|
||
|
||
```php
|
||
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. 检查数据库表
|
||
|
||
```sql
|
||
SHOW TABLES LIKE 'zyt_express%';
|
||
|
||
-- 应该看到4个表：
|
||
-- zyt_express_tracking
|
||
-- zyt_express_trace
|
||
-- zyt_express_state_log
|
||
-- zyt_express_query_log
|
||
```
|
||
|
||
### 2. 测试创建追踪
|
||
|
||
```php
|
||
$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. 检查定时任务
|
||
|
||
```bash
|
||
# 查看crontab
|
||
crontab -l | grep express
|
||
|
||
# 手动执行一次
|
||
cd server && php think express:auto-update
|
||
|
||
# 查看日志
|
||
tail -f runtime/log/info.log
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q: 定时任务不执行？
|
||
|
||
**A:** 检查crontab配置和PHP路径
|
||
```bash
|
||
# 查看crontab
|
||
crontab -l
|
||
|
||
# 检查PHP路径
|
||
which php
|
||
|
||
# 查看cron日志
|
||
tail -f /var/log/cron
|
||
```
|
||
|
||
### Q: 快递100返回"找不到对应公司"？
|
||
|
||
**A:** 账号未充值，请先充值快递100账户
|
||
- 登录：https://www.kuaidi100.com/
|
||
- 充值后重试
|
||
|
||
### Q: 如何停止某个快递的自动更新？
|
||
|
||
**A:**
|
||
```php
|
||
$tracking = ExpressTracking::find($id);
|
||
$tracking->auto_update = 0;
|
||
$tracking->save();
|
||
```
|
||
|
||
### Q: 如何修改更新频率？
|
||
|
||
**A:**
|
||
```php
|
||
// 修改单个追踪记录的更新间隔
|
||
$tracking->update_interval = 3600; // 1小时
|
||
$tracking->save();
|
||
|
||
// 或修改crontab执行频率
|
||
crontab -e
|
||
# 改为每30分钟: */30 * * * *
|
||
```
|
||
|
||
---
|
||
|
||
## 下一步
|
||
|
||
1. ✅ 确认快递100已充值
|
||
2. ✅ 集成到订单系统
|
||
3. ✅ 配置定时任务
|
||
4. ✅ 测试物流查询
|
||
5. 📖 阅读完整文档：`EXPRESS_TRACKING_SYSTEM.md`
|
||
|
||
---
|
||
|
||
## 技术支持
|
||
|
||
- 完整文档：`EXPRESS_TRACKING_SYSTEM.md`
|
||
- 快递100文档：https://api.kuaidi100.com/
|
||
- 问题排查：`KUAIDI100_TROUBLESHOOTING.md`
|