ruoyi-java/doc/如何查看同步进度和操作日志.md

如何查看同步进度和操作日志

您的三个问题解答

1️⃣ startRow被更新了吗？

答：是的，每次同步都会更新！

更新逻辑在代码中：

// 更新 Redis 中的进度
redisCache.setCacheObject(redisKey, currentMaxRow, 30, TimeUnit.DAYS);

但是：前端配置页面不会自动刷新！

您需要：

1. 关闭配置对话框
2. 重新打开配置
3. 就能看到最新的进度了

---

2️⃣ 更新状态是真实的吗？

答：是真实的！

数据存储位置：

• Redis Key: tendoc:progress:fileId:sheetId
• 过期时间: 30天
• 存储内容: 当前处理到的最大行号

您可以通过以下方式验证：

# 在Redis中查看
redis-cli
> get "tendoc:progress:DTUFydU9FTkRLbEN6:BB08J2"

---

3️⃣ 同步日志在哪里查看？

答：操作日志记录在数据库中！

📊 方法1：直接查询数据库

-- 查看最近50条操作日志
SELECT 
    id,
    operation_type,
    order_no,
    target_row,
    operation_status,
    error_message,
    operator,
    create_time
FROM tencent_doc_operation_log
WHERE file_id = 'DTUFydU9FTkRLbEN6'
ORDER BY create_time DESC
LIMIT 50;

-- 查看成功的操作
SELECT COUNT(*) as 成功数量
FROM tencent_doc_operation_log
WHERE file_id = 'DTUFydU9FTkRLbEN6'
AND operation_status = 'SUCCESS'
AND DATE(create_time) = CURDATE();

-- 查看失败的操作
SELECT 
    order_no,
    target_row,
    error_message,
    create_time
FROM tencent_doc_operation_log
WHERE file_id = 'DTUFydU9FTkRLbEN6'
AND operation_status = 'FAILED'
ORDER BY create_time DESC;

-- 查看跳过的操作
SELECT COUNT(*) as 跳过数量
FROM tencent_doc_operation_log
WHERE file_id = 'DTUFydU9FTkRLbEN6'
AND operation_status = 'SKIPPED'
AND DATE(create_time) = CURDATE();

📊 方法2：通过API查看（已添加）

接口1：查询操作日志列表

GET /jarvis-api/jarvis/tendoc/operationLogs?fileId=DTUFydU9FTkRLbEN6

接口2：查询最近N条日志

GET /jarvis-api/jarvis/tendoc/recentLogs?fileId=DTUFydU9FTkRLbEN6&limit=50

返回数据示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "fileId": "DTUFydU9FTkRLbEN6",
      "sheetId": "BB08J2",
      "operationType": "BATCH_SYNC",
      "orderNo": "JY202511061595",
      "targetRow": 2575,
      "logisticsLink": "https://3.cn/-2urt1U5",
      "operationStatus": "SUCCESS",
      "errorMessage": null,
      "operator": "admin",
      "createTime": "2025-11-06 22:03:30"
    }
  ]
}

---

🔍 详细的同步进度说明

进度更新规则

代码中的进度更新逻辑：

1. 有数据填充成功：

   currentMaxRow = endRow (本次处理的结束行)
   nextStartRow = currentMaxRow - 100 (回溯100行防止遗漏)
   

2. 本次无数据填充，但跳跃不大：

   currentMaxRow = endRow
   nextStartRow = currentMaxRow - 100
   

3. 本次无数据填充，且跳跃过大：

   不更新Redis进度
   nextStartRow = effectiveStartRow (配置的起始行)
   

为什么前端不自动刷新？

因为配置对话框是静态的，它在打开时读取一次配置，之后不会主动刷新。

解决方案：

• 关闭配置对话框
• 重新打开
• 或者点击"刷新"按钮（如果有）

---

📈 如何判断同步是否正常？

1. 查看后端日志

grep "批量填充物流链接完成" ruoyi-admin.log | tail -10

应该看到类似：

批量填充物流链接完成 - 成功: 15, 跳过: 178, 错误: 7
本次填充成功 15 条，更新进度到第 2699 行，下次从第 2599 行开始

2. 查看数据库日志统计

-- 今天的统计
SELECT 
    operation_status,
    COUNT(*) as 数量
FROM tencent_doc_operation_log
WHERE file_id = 'DTUFydU9FTkRLbEN6'
AND DATE(create_time) = CURDATE()
GROUP BY operation_status;

应该看到：

operation_status | 数量
----------------|------
SUCCESS         | 150
SKIPPED         | 500
FAILED          | 10

3. 检查Redis中的进度

redis-cli
> get "tendoc:progress:DTUFydU9FTkRLbEN6:BB08J2"
"2699"

这个数字应该随着同步而增长。

---

🎯 快速诊断问题

问题A：进度没有更新

可能原因：

1. Redis连接失败
2. 同步过程中出现异常
3. 没有成功填充任何数据

排查方法：

# 1. 检查Redis
redis-cli ping

# 2. 查看后端日志
tail -f ruoyi-admin.log | grep "tendoc:progress"

# 3. 查看数据库日志
SELECT * FROM tencent_doc_operation_log 
ORDER BY create_time DESC LIMIT 10;

问题B：日志中全是SKIPPED

可能原因：

1. 所有订单都已经推送过了（tencent_doc_pushed = 1）
2. 或者腾讯文档中的物流链接列都已经有值了

解决方法：

-- 检查订单的推送状态
SELECT 
    tencent_doc_pushed,
    COUNT(*) as 数量
FROM jd_order
WHERE distribution_mark = 'H-TF'
GROUP BY tencent_doc_pushed;

-- 重置推送状态（慎用！）
UPDATE jd_order
SET tencent_doc_pushed = 0,
    tencent_doc_push_time = NULL
WHERE distribution_mark = 'H-TF'
AND tencent_doc_pushed = 1;

问题C：有ERROR日志

排查步骤：

-- 查看错误详情
SELECT 
    order_no,
    target_row,
    error_message,
    create_time
FROM tencent_doc_operation_log
WHERE operation_status = 'FAILED'
ORDER BY create_time DESC
LIMIT 20;

常见错误：

• 未找到订单 - 数据库中不存在该订单
• 订单物流链接为空 - 订单还没有物流信息
• API调用失败 - 腾讯文档API异常

---

🔧 添加前端日志查看功能（可选）

如果您想在前端直接查看日志，我可以帮您添加一个"查看操作日志"对话框。

需要：

1. 在配置页面添加"查看日志"按钮
2. 创建日志查看对话框组件
3. 调用上面的API接口展示数据

是否需要？请告知！

---

📊 日志表结构

CREATE TABLE `tencent_doc_operation_log` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `file_id` varchar(100) COMMENT '文件ID',
  `sheet_id` varchar(100) COMMENT '工作表ID',
  `operation_type` varchar(50) COMMENT '操作类型',
  `order_no` varchar(100) COMMENT '订单号',
  `target_row` int COMMENT '目标行号',
  `logistics_link` varchar(500) COMMENT '物流链接',
  `operation_status` varchar(50) COMMENT '操作状态',
  `error_message` text COMMENT '错误信息',
  `operator` varchar(100) COMMENT '操作人',
  `create_time` datetime COMMENT '创建时间',
  `remark` varchar(500) COMMENT '备注',
  PRIMARY KEY (`id`),
  KEY `idx_file_id` (`file_id`),
  KEY `idx_order_no` (`order_no`),
  KEY `idx_create_time` (`create_time`)
) COMMENT='腾讯文档操作日志表';

---

总结：

1. ✅ startRow 有更新，存储在Redis中
2. ✅ 更新状态是真实的
3. ✅ 日志在 tencent_doc_operation_log 表中，可通过SQL或API查询
4. ❓ 前端配置页面需要手动刷新（关闭重开）才能看到最新进度

如需添加前端日志查看功能，请告知！