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

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

📋 功能说明

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

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

⚙️ 配置文件

在 application.yml 中添加配置：

# 腾讯文档延迟推送配置
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

响应示例：

{
  "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连接是否正常

解决方法：

# 查看Redis中的倒计时
redis-cli
> get "tendoc:delayed_push:next_time"

问题2：推送不执行

检查步骤：

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

解决方法：

# 查看锁状态
redis-cli
> get "tendoc:delayed_push:lock"

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

问题3：倒计时一直重置

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

解决方法：

• 减少延迟时间（如改为5分钟）
• 或手动触发推送

---

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