# 腾讯文档倒计时和批量推送记录功能说明

## 功能概述

本次更新实现了腾讯文档自动推送的倒计时监控和批量推送记录管理功能，主要包括：

1. **批量推送记录**：记录每次批量推送的详细信息，包括成功数、失败数、耗时等
2. **操作日志关联**：每条操作日志都关联到对应的批次ID，方便追踪
3. **倒计时监控**：实时显示自动推送倒计时，支持手动触发和取消
4. **推送历史查看**：可查看历史推送记录，展开查看每条记录的详细操作日志

## 数据库变更

### 1. 新建批量推送记录表

```sql
-- 执行SQL文件
source sql/tencent_doc_batch_push_record.sql;
```

主要字段：
- `batch_id`：批次ID（UUID）
- `file_id`、`sheet_id`：文档和工作表ID
- `push_type`：推送类型（AUTO-自动推送，MANUAL-手动推送）
- `trigger_source`：触发来源（DELAYED_TIMER-延迟定时器，USER-用户手动）
- `start_time`、`end_time`：推送开始和结束时间
- `duration_ms`：推送耗时（毫秒）
- `start_row`、`end_row`：推送的行范围
- `success_count`、`skip_count`、`error_count`：成功、跳过、错误数量
- `status`：状态（RUNNING-执行中，SUCCESS-成功，PARTIAL-部分成功，FAILED-失败）

### 2. 修改操作日志表

为 `tencent_doc_operation_log` 表添加 `batch_id` 字段，用于关联批量推送记录。

```sql
ALTER TABLE `tencent_doc_operation_log` 
ADD COLUMN `batch_id` varchar(64) DEFAULT NULL COMMENT '批次ID（关联批量推送记录）' AFTER `id`,
ADD KEY `idx_batch_id` (`batch_id`);
```

## 后端更新

### 1. 新增实体类和Mapper

- **TencentDocBatchPushRecord.java**：批量推送记录实体
- **TencentDocBatchPushRecordMapper.java**：批量推送记录Mapper接口
- **TencentDocBatchPushRecordMapper.xml**：MyBatis映射文件

### 2. 新增Service层

- **ITencentDocBatchPushService.java**：批量推送服务接口
- **TencentDocBatchPushServiceImpl.java**：批量推送服务实现

主要方法：
- `createBatchPushRecord`：创建批量推送记录
- `updateBatchPushRecord`：更新批量推送记录
- `getBatchPushRecord`：查询单条记录（含操作日志）
- `getBatchPushRecordListWithLogs`：查询记录列表（含操作日志）
- `getLastSuccessRecord`：查询最后一次成功的推送记录
- `getPushStatusAndCountdown`：获取推送状态和倒计时信息

### 3. 修改延迟推送服务

- **TencentDocDelayedPushServiceImpl.java**
  - 在执行批量推送前创建批量推送记录
  - 调用API时传递批次ID
  - 推送失败时更新记录状态

### 4. 新增Controller API

**TencentDocController.java** 新增接口：

| 接口 | 方法 | 说明 |
|------|------|------|
| `/jarvis/tendoc/batchPushRecords` | GET | 获取批量推送记录列表 |
| `/jarvis/tendoc/batchPushRecord/{batchId}` | GET | 获取批量推送记录详情 |
| `/jarvis/tendoc/pushStatus` | GET | 获取推送状态和倒计时信息 |
| `/jarvis/tendoc/triggerPushNow` | POST | 手动触发立即推送 |
| `/jarvis/tendoc/cancelPendingPush` | POST | 取消待推送任务 |

## 前端更新

### 1. API接口封装

**tendoc.js** 新增方法：
```javascript
// 获取批量推送记录列表
getBatchPushRecords(params)

// 获取批量推送记录详情
getBatchPushRecordDetail(batchId)

// 获取推送状态和倒计时信息
getPushStatus()

// 手动触发立即推送
triggerPushNow()

// 取消待推送任务
cancelPendingPush()
```

### 2. 新增推送监控组件

**TencentDocPushMonitor.vue**

功能特性：
- ✅ 实时倒计时显示（分:秒格式）
- ✅ 推送状态监控（等待推送中/无待推送任务）
- ✅ 手动触发立即推送
- ✅ 取消待推送任务
- ✅ 查看推送历史记录
- ✅ 时间轴展示推送记录
- ✅ 展开查看每条记录的操作日志
- ✅ 自动刷新（每30秒）
- ✅ 倒计时自动更新（每秒）

### 3. 集成到订单列表

**orderList.vue** 更新：
- 新增"推送监控"按钮
- 导入并注册 `TencentDocPushMonitor` 组件
- 添加 `showPushMonitor` 状态控制

## 使用指南

### 1. 打开推送监控

在订单列表页面，点击"推送监控"按钮即可打开监控对话框。

### 2. 查看倒计时

对话框顶部显示当前倒计时状态：
- **有待推送任务**：显示剩余时间（分:秒）
- **无待推送任务**：显示"00:00"

### 3. 手动操作

- **立即推送**：点击后立即执行批量推送，无需等待倒计时结束
- **取消推送**：取消当前待推送任务，倒计时清零
- **刷新状态**：手动刷新当前状态

### 4. 查看推送历史

对话框下方以时间轴形式展示推送记录：
- 绿色：推送成功
- 黄色：部分成功
- 红色：推送失败
- 蓝色：正在执行

点击记录可展开查看详细信息：
- 结果消息
- 错误信息（如果有）
- 操作日志列表（每条订单的详细操作记录）

### 5. 查看操作日志

展开推送记录后，可以看到该批次的所有操作日志，包括：
- 订单号
- 操作类型
- 目标行
- 物流链接
- 操作状态
- 错误信息（如果有）

## 数据流程

### 1. 录单触发

```
用户录单（H-TF订单）
  ↓
触发延迟推送服务
  ↓
设置10分钟倒计时
  ↓
10分钟内有新录单 → 重置倒计时
  ↓
10分钟到期 → 执行批量推送
```

### 2. 批量推送流程

```
创建批量推送记录（状态：RUNNING）
  ↓
调用批量同步API（传递batchId）
  ↓
每条订单操作都关联batchId
  ↓
推送完成后更新批量推送记录
  ├─ 状态：SUCCESS/PARTIAL/FAILED
  ├─ 成功/跳过/错误数量
  ├─ 结果消息
  └─ 错误信息（如果有）
```

### 3. 前端监控流程

```
打开推送监控对话框
  ↓
加载推送状态（倒计时）
  ↓
加载推送记录列表
  ↓
每秒更新倒计时显示
  ↓
每30秒自动刷新状态
  ↓
展开记录查看操作日志
```

## 技术要点

### 1. 倒计时同步

- 后端Redis存储 `scheduledTime`（推送执行时间戳）
- 前端每秒计算 `remainingSeconds = (scheduledTime - now) / 1000`
- 服务端和客户端同步倒计时，避免误差

### 2. 批次ID生成

使用UUID生成唯一批次ID：
```java
String batchId = UUID.randomUUID().toString().replace("-", "");
```

### 3. 日志关联

操作日志表添加 `batch_id` 字段，通过此字段关联：
- 一次批量推送 → 一条批量推送记录
- 一次批量推送 → 多条操作日志（每条订单一条）

### 4. 状态管理

批量推送记录的状态转换：
```
RUNNING → SUCCESS  （全部成功）
RUNNING → PARTIAL  （部分成功）
RUNNING → FAILED   （全部失败）
```

### 5. 自动刷新

组件实现两个定时器：
- **countdownTimer**：每秒更新倒计时显示
- **refreshTimer**：每30秒刷新状态和记录列表

## 注意事项

1. **数据库迁移**：部署前必须执行SQL脚本创建新表和字段
2. **Redis配置**：确保Redis正常运行，用于存储倒计时信息
3. **时间同步**：确保服务器时间准确，避免倒计时误差
4. **性能考虑**：批量推送记录会持续增长，建议定期清理历史记录
5. **并发控制**：延迟推送服务使用分布式锁，防止并发推送

## 常见问题

### Q1：倒计时不准确？

**A**：检查服务器时间是否准确，确保服务器时区设置正确。

### Q2：推送记录看不到操作日志？

**A**：确保 `batch_id` 字段已正确添加到操作日志表，并且在插入日志时传递了 `batchId`。

### Q3：手动触发推送没反应？

**A**：
1. 检查后端日志是否有错误
2. 确认腾讯文档配置是否完整
3. 检查网络连接和API权限

### Q4：倒计时显示00:00但标记为"等待推送中"？

**A**：可能是倒计时刚结束，正在执行推送。刷新状态即可更新。

## 后续优化建议

1. **推送记录分页**：当记录很多时，实现分页加载
2. **日志导出**：支持导出推送记录和操作日志为Excel
3. **推送统计**：添加推送成功率、平均耗时等统计图表
4. **告警通知**：推送失败时发送邮件或钉钉通知
5. **历史清理**：实现定时任务自动清理过期记录
6. **性能监控**：记录每次推送的性能指标，优化慢查询

## 版本信息

- **版本**：v1.0.0
- **更新日期**：2025-11-07
- **开发者**：AI Assistant
- **适用系统**：若依管理系统（RuoYi-Vue）

---

如有问题，请查看日志文件或联系技术支持。