新增

2026-04-07 18:13:03 +08:00
parent a780356908
commit fdf714f833
397 changed files with 15086 additions and 1043 deletions
@@ -0,0 +1,335 @@
+# 物流追踪系统 - 快速开始
+
+## 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`