# 物流追踪系统同步完成报告

## 问题分析

### 用户疑问
"定时任务找不到快递单号，明明订单里有快递单号"

### 根本原因
定时任务查询的是 `zyt_express_tracking` 表（物流追踪表），而不是 `zyt_tcm_prescription_order` 表（订单表）。

这两个表是分离的：
- **订单表**：存储业务订单信息，包括快递单号
- **物流追踪表**：专门存储物流追踪信息和轨迹历史

需要将订单表中的快递单号同步到物流追踪表，定时任务才能找到并更新。

## 解决方案

### 1. 创建同步命令
创建了 `SyncTrackingNumbers` 命令，用于将订单表中的快递单号同步到物流追踪表。

**文件**：`server/app/command/SyncTrackingNumbers.php`

**使用方法**：
```bash
php think express:sync
```

### 2. 注册命令
在 `server/config/console.php` 中注册了两个命令：
```php
'commands' => [
    'express:auto-update' => 'app\\command\\ExpressAutoUpdate',  // 自动更新
    'express:sync' => 'app\\command\\SyncTrackingNumbers',       // 同步快递单号
],
```

### 3. 执行同步
```bash
$ php think express:sync
开始同步现有订单快递单号...
找到 1 个有快递单号的订单
跳过: JD0230761381812 (已存在)

========================================
同步完成！
========================================
总数: 1
成功: 0
跳过: 1
失败: 0
耗时: 0.28秒
```

## 当前状态

### 物流追踪记录状态
```
快递单号: JD0230761381812
快递公司: auto
当前状态: 3 - 已签收
是否签收: 是
自动更新: 禁用
下次更新时间: 1970-01-01 08:00:00 (0)
当前时间: 2026-04-07 17:12:50
是否应该更新: 否
不更新原因: 自动更新未启用 已签收 状态为终态
```

### 为什么定时任务总数为0？

**答案**：这是正常的！

这个快递单号已经是"已签收"状态（state=3），系统自动：
1. 停止了自动更新（`auto_update = 0`）
2. 标记为已签收（`is_signed = 1`）
3. 状态为终态（state = 3）

**定时任务的过滤条件**：
```php
$list = ExpressTracking::where('auto_update', 1)           // ✗ 当前为0
    ->where('next_update_time', '<=', $now)                // ✗ 当前为0
    ->where('is_signed', 0)                                // ✗ 当前为1
    ->whereNotIn('current_state', [3, 4, 5])               // ✗ 当前为3
    ->whereNull('delete_time')
    ->limit($limit)
    ->select();
```

所有条件都不满足，所以不会被查询到。这是设计的预期行为，避免浪费查询次数。

## 工作流程

### 新订单的物流追踪流程

1. **订单创建/编辑时**
   ```php
   ExpressTrackingService::createOrUpdate([
       'order_id' => $orderId,
       'order_type' => 'prescription',
       'tracking_number' => $trackingNumber,
       'express_company' => $expressCompany,
       'recipient_phone' => $phone,
       'recipient_name' => $name,
       'recipient_address' => $address,
   ]);
   ```
   - 创建物流追踪记录
   - 立即查询一次物流信息
   - 设置 `auto_update = 1`（启用自动更新）
   - 设置 `next_update_time = now`（立即更新）

2. **定时任务自动更新**
   ```bash
   php think express:auto-update
   ```
   - 每10分钟执行一次
   - 只查询未签收的订单
   - 更新物流信息和轨迹
   - 检测状态变更

3. **签收后自动停止**
   - 检测到签收状态（state=3）
   - 设置 `is_signed = 1`
   - 设置 `auto_update = 0`（停止自动更新）
   - 记录签收时间

### 现有订单的同步

对于已有的订单（如当前的 JD0230761381812），需要手动同步：

```bash
# 同步现有订单快递单号
php think express:sync

# 同步后会立即查询一次物流信息
# 如果已签收，会自动停止更新
```

## 测试验证

### 1. 检查物流追踪记录
```bash
php check_tracking_status.php
```

### 2. 测试同步命令
```bash
php think express:sync
```

### 3. 测试自动更新
```bash
php think express:auto-update
```

### 4. 查看日志
```bash
tail -f runtime/log/202X-XX-XX.log
```

## 下一步操作

### 1. 集成到订单系统

在订单创建/编辑的控制器或逻辑层中添加：

**文件**：`server/app/adminapi/logic/tcm/PrescriptionOrderLogic.php`

```php
use app\common\service\ExpressTrackingService;

// 在保存订单后
if (!empty($params['tracking_number'])) {
    ExpressTrackingService::createOrUpdate([
        'order_id' => $orderId,
        'order_type' => 'prescription',
        'tracking_number' => $params['tracking_number'],
        'express_company' => $params['express_company'] ?? 'auto',
        'recipient_phone' => $params['recipient_phone'],
        'recipient_name' => $params['recipient_name'],
        'recipient_address' => $params['shipping_address'],
    ]);
}
```

### 2. 配置定时任务

#### Windows（任务计划程序）
```batch
schtasks /create /tn "ExpressAutoUpdate" /tr "php D:\web\zyt\server\think express:auto-update" /sc minute /mo 10
```

#### Linux（crontab）
```bash
crontab -e
# 添加以下行
0,10,20,30,40,50 * * * * cd /path/to/server && php think express:auto-update >> /dev/null 2>&1
```

### 3. 测试新订单

1. 创建一个新订单，填写快递单号
2. 检查 `zyt_express_tracking` 表是否自动创建记录
3. 等待10分钟，查看是否自动更新
4. 查看 `zyt_express_trace` 表是否有轨迹记录

## 相关文件

### 核心文件
- `server/app/common/service/ExpressTrackingService.php` - 物流追踪服务
- `server/app/command/ExpressAutoUpdate.php` - 自动更新命令
- `server/app/command/SyncTrackingNumbers.php` - 同步命令
- `server/config/console.php` - 命令注册

### 数据库
- `server/database/migrations/create_express_tracking_tables.sql` - 创建表
- `server/database/migrations/sync_existing_tracking_numbers.sql` - 同步SQL

### 工具脚本
- `server/install_tracking_tables.php` - 安装表
- `server/check_tracking_status.php` - 检查状态

### 文档
- `EXPRESS_TRACKING_SYSTEM.md` - 系统架构
- `EXPRESS_TRACKING_QUICKSTART.md` - 快速开始
- `EXPRESS_TRACKING_FIXES.md` - 修复记录
- `EXPRESS_TRACKING_COMMAND_FIX.md` - 命令修复
- `EXPRESS_TRACKING_SYNC_COMPLETE.md` - 本文档

## 总结

✅ 问题已解决：订单表和物流追踪表已同步
✅ 定时任务正常工作：正确过滤已签收订单
✅ 自动停止机制：签收后自动停止更新，节省查询次数
✅ 同步命令可用：`php think express:sync`
✅ 自动更新命令可用：`php think express:auto-update`

**当前状态**：系统已就绪，等待新订单测试。现有订单（JD0230761381812）已签收，不会再更新。

**建议**：
1. 在订单创建/编辑时集成 `ExpressTrackingService::createOrUpdate()`
2. 配置定时任务（每10分钟执行一次）
3. 创建一个新的未签收订单进行完整测试