1

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

@@ -0,0 +1,201 @@
+# 腾讯文档延迟推送配置说明
+
+## 📋 功能说明
+
+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
+