ruoyi-java/doc/智能状态同步机制说明.md

智能状态同步机制 - 详细说明

📖 背景

在实际使用中，腾讯文档的物流链接可能通过多种方式填写：

1. 系统推送：通过"推送物流"按钮自动填写
2. 手动填写：用户直接在文档中手动填写
3. 外部导入：从Excel等外部文件导入
4. 协同编辑：团队成员直接编辑文档

如果没有智能同步机制，会导致：

• ❌ 订单状态显示"未推送"，但文档中已有值
• ❌ 批量同步时重复查询这些订单
• ❌ 增加数据库查询负担
• ❌ 状态不一致，影响业务判断

✨ 智能同步机制

核心思路

以腾讯文档的实际状态为准，自动同步到订单系统

文档是最终展示层（实际填写状态）
    ↓
订单系统是管理层（推送状态记录）
    ↓
文档有值 + 订单未标记 = 状态不一致
    ↓
智能同步：自动更新订单状态

🔄 工作流程

场景1：系统推送（正常流程）

用户点击"推送物流"
    ↓
1. 检查订单状态：未推送 ✅
2. 检查文档物流列：无值 ✅
    ↓
写入物流链接到文档
    ↓
更新订单状态为"已推送"
    ↓
记录操作日志：SUCCESS

结果：订单状态 ✅ 已推送 | 文档状态 ✅ 有值

---

场景2：手动填写后首次批量同步（智能同步触发）

某人手动在文档中填写物流链接
    ↓
订单状态仍为"未推送"（因为是手动填写）
    ↓
批量同步开始
    ↓
1. 读取文档数据
2. 发现某行物流列已有值
3. 查询该单号对应的订单
    ↓
检测到状态不一致：
  - 订单状态：未推送 ❌
  - 文档状态：有值 ✅
    ↓
【智能同步触发】
    ↓
自动更新订单状态为"已推送"
    ↓
记录同步日志：SKIPPED（文档中已有值，已同步订单状态）

结果：订单状态 ✅ 已推送 | 文档状态 ✅ 有值

---

场景3：手动填写后再次批量同步（无需同步）

批量同步开始
    ↓
1. 读取文档数据
2. 发现某行物流列已有值
3. 查询该单号对应的订单
    ↓
检测到状态一致：
  - 订单状态：已推送 ✅（上次已同步）
  - 文档状态：有值 ✅
    ↓
直接跳过（无需同步）

结果：订单状态 ✅ 已推送 | 文档状态 ✅ 有值

---

场景4：用户尝试重复推送（拒绝）

用户点击"推送物流"
    ↓
1. 检查订单状态：已推送 ❌
    ↓
拒绝推送
    ↓
返回错误提示：
"该订单已推送到腾讯文档（推送时间：2025-11-06 12:30:00），请勿重复操作！"

结果：请求被拒绝，订单和文档状态保持不变

📊 状态同步矩阵

订单状态	文档物流列	用户操作	系统行为	最终状态
未推送	无值	单个推送	✅ 写入物流链接，更新订单状态	已推送 + 有值
未推送	无值	批量同步	✅ 写入物流链接，更新订单状态	已推送 + 有值
未推送	有值	单个推送	❌ 拒绝（文档已有值）	未推送 + 有值
未推送	有值	批量同步	✅ 智能同步订单状态	已推送 + 有值
已推送	有值	单个推送	❌ 拒绝（订单已推送）	已推送 + 有值
已推送	有值	批量同步	✅ 跳过（订单已推送）	已推送 + 有值
已推送	无值	单个推送	❌ 拒绝（订单已推送）	已推送 + 无值
已推送	无值	批量同步	✅ 跳过（订单已推送）	已推送 + 无值

重点场景：第4行 - 未推送 + 有值 + 批量同步 = 智能同步

🎯 核心优势

1. 自动化

• ✅ 无需人工干预
• ✅ 批量同步时自动检测
• ✅ 自动修正状态不一致

2. 高效性

• ✅ 同步后下次批量同步会跳过
• ✅ 减少数据库查询
• ✅ 减少不必要的状态检查

3. 可追溯

• ✅ 记录同步操作日志
• ✅ 标记同步原因："文档中已有物流链接（可能手动填写）"
• ✅ 便于审计和问题排查

4. 兼容性

• ✅ 兼容手动填写
• ✅ 兼容外部导入
• ✅ 兼容协同编辑
• ✅ 兼容各种数据来源

📝 代码实现（简化版）

// 批量同步时，检查文档物流列
String existingLogisticsLink = row.getString(logisticsLinkColumn);
if (existingLogisticsLink != null && !existingLogisticsLink.trim().isEmpty()) {
    // 文档中已有物流链接，检查订单状态
    JDOrder existingOrder = jdOrderService.selectJDOrderByThirdPartyOrderNo(orderNo);
    
    if (existingOrder != null && 
        (existingOrder.getTencentDocPushed() == null || 
         existingOrder.getTencentDocPushed() == 0)) {
        
        // 状态不一致，触发智能同步
        existingOrder.setTencentDocPushed(1);
        existingOrder.setTencentDocPushTime(new Date());
        jdOrderService.updateJDOrder(existingOrder);
        
        log.info("✓ 同步订单状态 - 单号: {}, 行号: {}, 原因: 文档中已有物流链接（可能手动填写）", 
            orderNo, excelRow);
        
        // 记录同步日志
        logOperation(fileId, sheetId, "BATCH_SYNC", orderNo, excelRow, 
            existingLogisticsLink, "SKIPPED", "文档中已有物流链接，已同步订单状态");
    }
    
    skippedCount++; // 跳过写入
    continue;
}

🔍 日志示例

智能同步触发

2025-11-06 14:30:15 INFO  - 批量同步开始 - 范围：第3-202行
2025-11-06 14:30:16 INFO  - 发现物流列已有值 - 单号: JY2025110329041, 行号: 123
2025-11-06 14:30:16 INFO  - 检测到状态不一致 - 订单状态: 未推送, 文档状态: 有值
2025-11-06 14:30:16 INFO  - ✓ 同步订单状态 - 单号: JY2025110329041, 行号: 123, 原因: 文档中已有物流链接（可能手动填写）
2025-11-06 14:30:16 INFO  - 记录同步日志 - 操作类型: BATCH_SYNC, 状态: SKIPPED

操作日志表记录

INSERT INTO tencent_doc_operation_log (
    file_id, sheet_id, operation_type, order_no, target_row, 
    logistics_link, operation_status, error_message, operator, create_time
) VALUES (
    'DUW50RUprWXh2TGJK', 'BB08J2', 'BATCH_SYNC', 'JY2025110329041', 123,
    'https://3.cn/2ume-Ak1', 'SKIPPED', '文档中已有物流链接，已同步订单状态', 
    'admin', '2025-11-06 14:30:16'
);

🛠️ 排查与维护

查询智能同步记录

-- 查询所有智能同步操作
SELECT order_no, target_row, logistics_link, create_time, operator
FROM tencent_doc_operation_log
WHERE operation_status = 'SKIPPED'
AND error_message LIKE '%文档中已有物流链接，已同步订单状态%'
ORDER BY create_time DESC;

查询状态不一致的订单（理论上应该为0）

-- 如果有记录，说明智能同步未触发或失败
SELECT o.third_party_order_no, o.tencent_doc_pushed, o.logistics_link
FROM jd_order o
WHERE o.logistics_link IS NOT NULL 
AND o.logistics_link != ''
AND (o.tencent_doc_pushed IS NULL OR o.tencent_doc_pushed = 0);

手动修正状态不一致

-- 如果发现状态不一致，可以手动修正
UPDATE jd_order 
SET tencent_doc_pushed = 1, 
    tencent_doc_push_time = NOW()
WHERE logistics_link IS NOT NULL 
AND logistics_link != ''
AND (tencent_doc_pushed IS NULL OR tencent_doc_pushed = 0);

✅ 最佳实践

1. 定期批量同步

   • 建议每天运行一次批量同步
   • 自动修正所有状态不一致

2. 监控同步日志

   • 定期检查 SKIPPED 状态的日志
   • 分析手动填写的频率和模式

3. 培训团队成员

   • 告知团队手动填写会被系统自动同步
   • 建议优先使用系统推送功能

4. 备份重要数据

   • 定期备份腾讯文档
   • 定期备份订单数据库

🎉 总结

智能状态同步机制确保了：

• ✅ 订单状态 与 文档实际状态 始终保持一致
• ✅ 兼容多种数据来源（系统推送、手动填写、外部导入）
• ✅ 减少重复查询，提高系统效率
• ✅ 所有同步操作可追溯，便于审计

这是一个真正智能的、自适应的状态管理机制！ 🚀