ruoyi-java/doc/延迟推送配置说明.md

# 腾讯文档延迟推送配置说明

## 📋 功能说明

H-TF订单录单后，**不立即推送**到腾讯文档，而是采用**智能延迟推送机制**：

1. 录单完成 → 触发10分钟倒计时
2. 10分钟内有新录单 → 重置倒计时
3. 10分钟内无新录单 → 自动执行推送
4. 推送执行中有新录单 → 推送完成后重新倒计时

## ⚙️ 配置文件

在 `application.yml` 中添加配置：

```yaml
# 腾讯文档延迟推送配置
tencent:
  doc:
    delayed:
      push:
        # 延迟时间（分钟），默认10分钟
        minutes: 10
```

## 🎯 工作原理

### 1. Redis存储

- **倒计时结束时间**: `tendoc:delayed_push:next_time`
- **推送执行锁**: `tendoc:delayed_push:lock`
- **新订单标记**: `tendoc:delayed_push:new_order_flag`

### 2. 定时任务

- 每30秒检查一次是否到期
- 到期后自动执行推送

### 3. 防并发机制

- 使用Redis分布式锁
- 确保同一时间只有一个推送任务在执行

### 4. 智能重试

- 推送执行期间有新录单 → 推送完成后自动重新开始倒计时

## 📊 API接口（待实现）

### 查询倒计时状态
```
GET /jarvis-api/jarvis/tendoc/delayedPushStatus
```

**响应示例：**
```json
{
  "code": 200,
  "data": {
    "hasPending": true,
    "remainingSeconds": 300,
    "nextPushTime": "2025-11-06 23:10:00",
    "isPushing": false
  }
}
```

### 立即执行推送
```
POST /jarvis-api/jarvis/tendoc/executeDelayedPushNow
```

### 取消待推送任务
```
POST /jarvis-api/jarvis/tendoc/cancelDelayedPush
```

## 🔍 日志输出

### 触发延迟推送
```
✓ H-TF订单已触发延迟推送 - 单号: 2025110601, 第三方单号: JY202511061595
触发延迟推送，10分钟后执行（23:10:00）
```

### 倒计时检查
```
距离下次推送还有 300 秒
```

### 执行推送
```
倒计时结束，开始执行推送
✓ 获取推送锁成功
开始执行批量同步...
批量同步调用完成，响应码: 200
✓ 推送执行完成
✓ 释放推送锁
```

### 推送期间有新录单
```
推送执行中，标记有新订单，推送完成后将重新开始倒计时
...
推送期间有新订单，重新开始倒计时
触发延迟推送，10分钟后执行（23:20:00）
```

## 🎯 使用场景

### 场景1：连续录单

```
23:00:00 - 录单1 → 触发倒计时，23:10:00执行
23:02:00 - 录单2 → 重置倒计时，23:12:00执行
23:05:00 - 录单3 → 重置倒计时，23:15:00执行
23:15:00 - （10分钟无新录单）→ 自动推送
```

### 场景2：推送执行中有新录单

```
23:00:00 - 录单1 → 触发倒计时，23:10:00执行
23:10:00 - 开始推送（预计需要2分钟）
23:11:00 - 录单2 → 标记有新订单
23:12:00 - 推送完成 → 检测到标记 → 重新触发倒计时，23:22:00执行
```

### 场景3：手动触发推送

```
23:00:00 - 录单1 → 触发倒计时，23:10:00执行
23:05:00 - 手动点击"批量同步物流" → 立即执行推送
23:05:05 - 推送完成 → 清除倒计时
23:06:00 - 录单2 → 重新触发倒计时，23:16:00执行
```

## ⚠️ 注意事项

1. **延迟时间建议**: 
   - 录单频率高：设置5-10分钟
   - 录单频率低：设置10-15分钟

2. **服务器重启**: 
   - 倒计时存储在Redis中
   - 服务器重启后，倒计时会继续（Redis数据保留）

3. **推送失败**: 
   - 推送失败不会自动重试
   - 需要手动点击"批量同步物流"

4. **并发安全**: 
   - 使用Redis分布式锁
   - 多台服务器部署时也能正确工作

## 🔧 故障排查

### 问题1：倒计时不触发

**检查步骤：**
1. 确认Service已正常启动
2. 查看日志中是否有"延迟推送服务已启动"
3. 检查Redis连接是否正常

**解决方法：**
```bash
# 查看Redis中的倒计时
redis-cli
> get "tendoc:delayed_push:next_time"
```

### 问题2：推送不执行

**检查步骤：**
1. 查看日志中是否有"倒计时结束，开始执行推送"
2. 检查是否有错误日志
3. 查看Redis锁状态

**解决方法：**
```bash
# 查看锁状态
redis-cli
> get "tendoc:delayed_push:lock"

# 如果有锁但长时间未释放，手动删除
> del "tendoc:delayed_push:lock"
```

### 问题3：倒计时一直重置

**原因：** 录单频率太高，倒计时不断被重置

**解决方法：** 
- 减少延迟时间（如改为5分钟）
- 或手动触发推送

---

**最后更新**: 2025-11-06  
**版本**: v1.0