新增

2026-04-07 18:13:03 +08:00
parent a780356908
commit fdf714f833
397 changed files with 15086 additions and 1043 deletions
@@ -0,0 +1,244 @@
+# 物流追踪系统同步完成报告
+
+## 问题分析
+
+### 用户疑问
+"定时任务找不到快递单号，明明订单里有快递单号"
+
+### 根本原因
+定时任务查询的是 `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. 创建一个新的未签收订单进行完整测试