275 lines
8.1 KiB
Markdown
275 lines
8.1 KiB
Markdown
# 智能状态同步机制 - 详细说明
|
||
|
||
## 📖 背景
|
||
|
||
在实际使用中，腾讯文档的物流链接可能通过多种方式填写：
|
||
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. 兼容性
|
||
- ✅ 兼容手动填写
|
||
- ✅ 兼容外部导入
|
||
- ✅ 兼容协同编辑
|
||
- ✅ 兼容各种数据来源
|
||
|
||
## 📝 代码实现（简化版）
|
||
|
||
```java
|
||
// 批量同步时，检查文档物流列
|
||
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
|
||
```
|
||
|
||
### 操作日志表记录
|
||
|
||
```sql
|
||
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'
|
||
);
|
||
```
|
||
|
||
## 🛠️ 排查与维护
|
||
|
||
### 查询智能同步记录
|
||
|
||
```sql
|
||
-- 查询所有智能同步操作
|
||
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）
|
||
|
||
```sql
|
||
-- 如果有记录，说明智能同步未触发或失败
|
||
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);
|
||
```
|
||
|
||
### 手动修正状态不一致
|
||
|
||
```sql
|
||
-- 如果发现状态不一致，可以手动修正
|
||
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. **备份重要数据**
|
||
- 定期备份腾讯文档
|
||
- 定期备份订单数据库
|
||
|
||
## 🎉 总结
|
||
|
||
智能状态同步机制确保了：
|
||
- ✅ **订单状态** 与 **文档实际状态** 始终保持一致
|
||
- ✅ 兼容多种数据来源（系统推送、手动填写、外部导入）
|
||
- ✅ 减少重复查询，提高系统效率
|
||
- ✅ 所有同步操作可追溯，便于审计
|
||
|
||
**这是一个真正智能的、自适应的状态管理机制！** 🚀
|
||
|