# 物流追踪系统 - 快速开始

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