档案管理系统进度功能不准确 从排查到修复全流程实操指南

前置准备：排查前需确认的基础信息

开始排查前请提前准备好以下3项内容，避免中途卡壳：

• 系统架构台账：确认进度功能是前端本地计算还是后端接口返回，数据库类型、是否用Redis做缓存
• 权限账号：系统超级管理员账号、服务器SSH权限、数据库读写权限、前端代码仓库权限
• 复现样本：收集至少3个进度不准确的档案ID，以及对应的官方标准进度值，排除偶发bug干扰

第一步：前端逻辑排查（10分钟可完成）

1.1 前端计算逻辑校验

打开Chrome浏览器，按下F12打开开发者工具，切换到「Network」面板，筛选「Fetch/XHR」请求，找到获取档案详情的接口，复制接口返回的progress字段值，和页面显示的进度值对比：如果两者不一致，说明是前端计算逻辑错误，走1.2修复步骤；如果一致，说明问题出在后端，直接跳转到第二步排查。

1.2 前端进度计算错误修复

找到前端进度计算的代码块，通常在src/views/archive/detail.vue或者对应的js文件里，常见错误是分子分母取值错误、百分比计算保留小数逻辑出错，直接用以下标准代码替换原有逻辑：

```js // 正确进度计算逻辑：已完成节点数/总节点数100，保留1位小数 const calcProgress = (finishedNode, totalNode) => { if(totalNode === 0) return 0 return Number((finishedNode / totalNode 100).toFixed(1)) } ```

替换完成后本地打包测试，确认所有样本档案的页面显示进度和接口返回值一致后，再部署到线上环境。

第二步：后端逻辑排查（20分钟可完成）

2.1 缓存数据校验

如果系统用Redis做了档案进度缓存，首先执行以下命令排查缓存值是否正确：

```shell 连接Redis（替换为你自己的Redis密码和端口，默认端口6379） redis-cli -a 你的Redis密码 -p 6379 查询对应档案的进度缓存（key规则通常是archive:progress:档案ID，替换为实际ID） get archive:progress:1001 ```

如果缓存值和正确进度不一致，直接删除错误缓存：

```shell del archive:progress:1001 ```

删除后刷新页面看进度是否恢复正常，如果恢复，说明是缓存更新策略问题，走2.3修复；如果缓存值正确或者系统未使用缓存，走2.2排查。

2.2 数据库数据校验

根据档案ID查询数据库里的节点完成状态，以MySQL为例，执行以下查询语句：

```sql -- 替换1001为对应档案ID，查询总节点数和已完成节点数 SELECT COUNT() AS total_node, SUM(IF(status = 1,1,0)) AS finished_node FROM archive_node WHERE archive_id = 1001; ```

把查询到的finished_node/total_node100的结果，和接口返回的progress值对比，如果不一致，说明是后端接口计算逻辑错误，走2.3修复；如果一致，说明是节点状态更新逻辑错误，跳转到第三步排查。

2.3 后端逻辑修复

缓存更新策略修复：在档案节点状态更新的接口代码里，新增删除对应进度缓存的逻辑，Java示例代码：

```java // 节点状态更新成功后立即执行，删除旧缓存 redisTemplate.delete("archive:progress:" + archiveId); ```

接口计算逻辑修复：把后端接口里的进度计算逻辑替换为和前端一致的规则，避免前后端计算精度差异，Java示例：

```java import java.math.BigDecimal; import java.math.RoundingMode; public BigDecimal calcProgress(int finishedNode, int totalNode) { if(totalNode == 0) { return BigDecimal.ZERO; } return BigDecimal.valueOf(finishedNode) .divide(BigDecimal.valueOf(totalNode), 1, RoundingMode.HALF_UP) .multiply(BigDecimal.valueOf(100)); } ```

第三步：节点状态更新逻辑排查（15分钟可完成）

3.1 事务回滚排查

查询对应档案的操作日志，确认用户提交节点完成操作后，是否触发了节点状态更新的事务回滚，MySQL查询最近1小时的事务回滚记录命令：

```sql SELECT FROM information_schema.innodb_trx WHERE trx_state = 'ROLLBACK' AND trx_started > DATE_SUB(NOW(), INTERVAL 1 HOUR); ```

如果有对应的回滚记录，检查代码里的事务边界是否正确，是否把非核心操作放到了事务里导致异常回滚，把非核心操作移出事务即可解决。

3.2 消息队列消费排查

如果节点状态更新是通过MQ异步处理的，查看MQ消费情况，以RocketMQ为例，执行以下命令查看消费失败的消息：

```shell 进入RocketMQ安装目录的bin目录，替换为你自己的安装路径 cd /usr/local/rocketmq/bin 查询消费组的消费失败消息（替换为你自己的消费组名称、namesrv地址） ./mqadmin consumerProgress -g archive_node_update_group -n 127.0.0.1:9876 ```

如果有消息堆积或者消费失败，在MQ控制台手动重试消费失败的消息，节点状态就会自动更新，进度也会同步恢复正常。

修复后验证&长效优化方案

修复完成后，首先用收集到的3个以上样本档案验证进度是否正确，再新增一个测试档案，走完全部节点流程，确认进度从0到100%全程更新准确后，再通知业务方验证。

为避免后续再出现同类问题，可新增2项长效机制：

• 新增进度校验定时任务：每天凌晨1点全量扫描所有进行中的档案，重新计算进度并更新缓存和数据库，crontab配置如下： ```shell 每天凌晨1点执行进度校验脚本，替换为你自己的jar包路径和日志路径 0 1 /usr/bin/java -jar /opt/archive/progress-check.jar >> /var/log/archive-progress-check.log 2>&1 ```
• 新增进度异常告警：在接口逻辑里增加校验规则，当接口返回的进度值和数据库实时计算的进度值差值超过1%时，触发企业微信/短信告警，第一时间发现问题。