Merge pull request #4 from mingyush/dev04

 v1.2 新增数据一致性修复功能

Author: mingyush

CHANGELOG.md

@@ -0,0 +1,41 @@
+# 更新日志 (Changelog)
+
+## 🌟 版本 1.2.0
+**日期**: 2026年3月
+**亮点**: 数据一致性、性能监控及系统稳定性修复
+
+### ✨ 新增功能 (Features)
+1. **数据一致性修复工具**:
+   - 分离式的修复脚本 `scripts/fix_data_consistency.js` 与内嵌在“系统设置”中的一键修复面板。
+   - 自动扫描并合并不规则的重复学期记录（解决多线程或由于设备拷贝造成的同步写入导致的重复学期创建）。
+   - 自动追溯缺失的历史积分变更记录，生成“系统初始化余额归集”记录，将数据库底层分值对齐到 `point_records` 历史流水线上，确保班级大屏不再因跨学期断层显示 0 分。
+2. **进程与内存深度监控**:
+   - 优化 `errorHandler.js` 中的内存监控模块。从单一的 V8 堆内存（`heapUsed`）监控，升级为对 Node.js 的常驻内存集（`rss`）与服务器系统级真实可用内存（`os.freemem()`）的双重监控，彻底消除非真实超载导致的高频系统警告和告警邮件。
+
+### 🐛 Bug 修复 (Bug Fixes)
+1. **彻底解决教师面板“最近操作”无数据问题**:
+   - 修复了因为代码缺失导致的选中学生时没有执行 `loadRecentOperations()` 钩子的问题。在教师后台侧边栏点击学生时，右下方的“操作历史记录”能立刻以极低延迟精准展现。
+2. **修复积分加、减算法中的正负倒置错误**:
+   - 修正了在进行独立积分扣除时底层处理库产生“- - = +”式的负向重叠写入数据库的问题。
+3. **彻底修复跨系统的 `MODULE_NOT_FOUND` 大小写崩溃**:
+   - 修正在 macOS 环境下 `Require()` 大小不敏感但在 NAS（Linux 核心）部署时找不到 `systemService.js` / `SystemService.js` 导致的程序 `status=1/FAILURE` 无限重启崩溃现象，将全系统 import 完全标准化大小写。
+4. **修复由瞬时高并发产生的 SQLite 锁库异常 (Database is Locked)**:
+   - 修改了 `config.js` 等接口多次新建独立 `dataAccess` 子实例导致 SQLite 并行事务处理超载的问题。改为各功能继承并复用同一实例，大大提高了密集数据刷新时的引擎稳定性。
+
+---
+
+## 🔄 版本 1.1.0 (原标为 2026 V2 升级包)
+**日期**: 2026年3月早期
+**亮点**: 学期隔离和全新管理体系
+
+1. **学期积分隔离系统 (Semester Isolation)**: 
+   - 彻底解决了跨学期“积分清零”污染流水线的问题。
+   - 所有积分记录严格绑定 `semester_id`。系统切换学期时执行底层静默抹零，不产生额外扣分账单。
+   - 日榜、周榜排除了系统操作行为的影响，大屏展示永远只显示当下的真实奋斗轨迹。
+2. **内嵌超级管理员体系**:
+   - `admin` 账号成为系统底层保护机制的一部分（不可见，无法被普通教师账号删除、编辑）。
+   - 提供给班主任或系统环境部署者唯一的最高控制权，保护系统根源数据不被下发平展级教师误篡改。
+3. **数据库重建与测试隔离**:
+   - 加入了全新的基于原始JSON模版的数据库重置引擎。支持一键初始化跨学期的基础数据架构，无损保留基础用户结构。
+4. **前端UI体系优化**:
+   - 修正了顶部菜单遮挡屏幕区域、教师与学生状态栏因内容产生悬浮跳动的大量交互级 Bug。

README.md

@@ -6,14 +6,14 @@
 
 ## 🎯 功能特点
 
-- **🖥️ 大屏展示**: 实时显示学生积分排行榜，支持教室投影
-- **👨‍🏫 教师管理**: 简单直观的积分加减操作界面
-- **👨‍🎓 学生查询**: 个人积分查看和奖品预约功能
-- **💾 数据持久化**: 基于JSON文件的可靠数据存储
-- **⚡ 实时更新**: 使用Server-Sent Events实现实时数据推送
-- **🔐 权限控制**: 教师和学生分离的权限管理
-- **📊 数据统计**: 总积分、日积分、周积分多维度排行
-- **🎁 奖品系统**: 完整的商品预约和兑换流程
+- **🖥️ 大屏展示**: 实时显示学生积分排行榜，支持教室平时/上课双模式投影
+- **👨‍🏫 教师管理**: 简单直观的积分加减操作界面，支持多维度的数据追踪
+- **👨‍🎓 学生查询**: 个人积分查看和奖品在线预约功能
+- **💾 数据库引擎**: 基于高性能 SQLite 3 引擎的数据存储，保障并发读写安全
+- **⚡ 实时更新**: 使用 Server-Sent Events 实现大屏与前端数据的无刷新推送
+- **🔐 权限控制**: 教师、学生、系统管理员（Admin）、班主任（导演角色）四级权限分离
+- **📊 数据统计**: 总积分、日榜、周榜多维度排行，且按学期严格隔离
+- **🎁 奖品系统**: 完整的商品预留库存、预约和兑换审核流程
 
 ## 📸 系统界面展示
 
@@ -125,27 +125,20 @@
 ## 🛠️ 技术栈
 
 - **后端**: Node.js + Express.js
-- **前端**: HTML5 + CSS3 + 原生JavaScript
-- **数据存储**: JSON文件系统
+- **前端**: HTML5 + CSS3 + 原生JavaScript (零构建依赖)
+- **数据库引擎**: SQLite 3 (node-sqlite3)
 - **实时通信**: Server-Sent Events (SSE)
-- **认证**: JWT Token
-- **测试**: Jest + Supertest
-
-## 🔄 核心功能升级 (2026 V2)
-
-在最初期版本的基础上，系统进行了深度重构与功能升级（V2版）：
-
-1. **学期积分隔离隔离 (Semester Isolation)**: 
-   - 彻底解决了跨学期“积分清零”污染流水线的问题。
-   - 所有积分记录严格绑定 `semester_id`。系统切换学期时执行底层静默抹零，不产生额外扣分账单。
-   - 日榜、周榜排除了系统操作行为的影响，大屏展示永远只显示当下的真实奋斗轨迹。
-2. **内嵌超级管理员体系**:
-   - `admin` 账号成为系统底层保护机制的一部分（无法被普通教师账号删除、编辑）。
-   - 提供给班主任/系统管理者唯一的最高控制权，确保数据源的稳定性。
-3. **数据库重建与测试隔离**:
-   - 加入了全新的基于原始JSON模版的数据库重置引擎。支持一键初始化跨学期的基础数据架构。
-4. **前端UI体系优化**:
-   - 修正了顶部菜单遮挡、状态栏悬浮跳动等大量页面交互 Bug。
+- **认证安全**: JWT Token (带有强保护与过期策略)
+- **测试框架**: Jest + Supertest
+
+## 🔄 版本更新说明
+
+本系统持续在快速迭代并修复生产环境中遇到的各种细节问题。有关最新版本的功能扩展、修复清单与底层结构修改细节，请参阅：
+
+👉 **[查看完整更新日志 (CHANGELOG) ](CHANGELOG.md)**
+
+- **1.2.0**：主要新增数据一致性智能修复、真实服务器级系统资源告警隔离、修复基于大小写引发的群晖NAS模块加载崩溃、修复“最近操作”列表缺失。
+- **1.1.0**：增加“学期积分完全隔离系统”、超管降级防删体系、修正部分导致系统交互跳动的 UI 层 Bug。
 
 ## 升级与交叉部署指南 (含 NAS 部署)
 

api/config.js

@@ -3,6 +3,7 @@ const DataAccess = require('../utils/dataAccess');
 const sseService = require('../services/sseService');
 const { authenticateToken, requireTeacher } = require('./auth');
 const { asyncHandler, createError, operationLogger } = require('../middleware/errorHandler');
+const SystemService = require('../services/systemService');
 const router = express.Router();
 
 const dataAccess = new DataAccess();
@@ -256,4 +257,34 @@ router.post('/reset-points/toggle', authenticateToken, requireTeacher,
     })
 );
 
+/**
+ * 修复数据一致性
+ * POST /api/config/fix-data
+ * 需要教师权限 (admin/director)
+ */
+router.post('/fix-data', authenticateToken, requireTeacher,
+    operationLogger('修复数据一致性'),
+    asyncHandler(async (req, res) => {
+        try {
+            // 【修复】3. 复用模块全局的 dataAccess 实例进行数据连接，而不新开隐含 SQLite 连接
+            const systemService = new SystemService(dataAccess);
+
+            const results = await systemService.repairDataConsistency();
+
+            res.json({
+                success: true,
+                message: '数据一致性修复完成',
+                data: results
+            });
+        } catch (error) {
+            console.error('[FixData API] Error:', error);
+            res.status(500).json({
+                success: false,
+                message: '数据一致性修复失败: ' + error.message,
+                stack: error.stack
+            });
+        }
+    })
+);
+
 module.exports = router;

api/sse.js

@@ -166,5 +166,16 @@ router.post('/test', authenticateToken, requireTeacher, (req, res) => {
 module.exports = {
     router,
     broadcastSSEMessage,
-    getConnectionCount: () => sseConnections.size
+    getConnectionCount: () => sseConnections.size,
+    closeAllConnections: () => {
+        if (sseConnections.size > 0) {
+            console.log(`正在断开 ${sseConnections.size} 个存活的 SSE 连接...`);
+            sseConnections.forEach(conn => {
+                if (conn.response && !conn.response.writableEnded) {
+                    conn.response.end();
+                }
+            });
+            sseConnections.clear();
+        }
+    }
 };

middleware/errorHandler.js

@@ -1,5 +1,6 @@
 const fs = require('fs').promises;
 const path = require('path');
+const os = require('os');
 
 /**
  * 错误类型定义
@@ -586,18 +587,35 @@ class ErrorMonitor {
      */
     async checkSystemResources(alerts) {
         try {
-            const memoryUsage = process.memoryUsage();
-            const memoryUsagePercent = memoryUsage.heapUsed / memoryUsage.heapTotal;
+            const totalMem = os.totalmem();
+            const freeMem = os.freemem();
+            const usedMem = totalMem - freeMem;
+            const memoryUsagePercent = usedMem / totalMem;
+            const memoryUsage = process.memoryUsage(); // 保留用于记录进程数据
 
-            // 检查内存使用率
+            // 检查服务器物理内存使用率
             if (memoryUsagePercent > 0.9) { // 90%内存使用率
                 const alertKey = 'HIGH_MEMORY_USAGE';
                 if (this.shouldSendAlert(alertKey)) {
                     alerts.push({
                         type: alertKey,
-                        message: `内存使用率${(memoryUsagePercent * 100).toFixed(2)}%过高`,
+                        message: `服务器物理内存使用率${(memoryUsagePercent * 100).toFixed(2)}%过高`,
+                        severity: 'WARNING',
+                        data: { systemUsage: memoryUsagePercent, processMemory: memoryUsage }
+                    });
+                }
+            }
+
+            // 也检查一下 Node 进程本身是否占用过高 (超过 500MB rss)
+            const processMemUsageMB = memoryUsage.rss / (1024 * 1024);
+            if (processMemUsageMB > 500) {
+                const alertKey = 'HIGH_PROCESS_MEMORY';
+                if (this.shouldSendAlert(alertKey)) {
+                    alerts.push({
+                        type: alertKey,
+                        message: `Node进程内存占用过高: ${processMemUsageMB.toFixed(2)}MB`,
                         severity: 'WARNING',
-                        data: { memoryUsage, memoryUsagePercent }
+                        data: { processMemory: memoryUsage }
                     });
                 }
             }
@@ -734,13 +752,17 @@ class ErrorMonitor {
 
             const errorRate = statistics.totalErrors / Math.max(1, statistics.totalErrors + 100); // 假设正常请求数
             const memoryUsage = process.memoryUsage();
-            const memoryUsagePercent = memoryUsage.heapUsed / memoryUsage.heapTotal;
+            
+            // 将健康检查修改为基于系统的实际内存分配或者 RSS
+            const totalMem = os.totalmem();
+            const freeMem = os.freemem();
+            const memoryUsagePercent = (totalMem - freeMem) / totalMem;
 
             // 综合评估健康状态
             const healthChecks = {
                 errorRate: errorRate <= this.errorThresholds.errorRate,
                 errorCount: statistics.totalErrors <= this.errorThresholds.errorCount,
-                memoryUsage: memoryUsagePercent <= 0.9,
+                memoryUsage: memoryUsagePercent <= 0.9 && (memoryUsage.rss / (1024 * 1024)) < 500, // 系统不足90% 或 进程不足500MB 
                 uptime: process.uptime() < 7 * 24 * 60 * 60 // 7天
             };
 

models/dataModels.js

@@ -207,6 +207,7 @@ class Order {
     constructor(data = {}) {
         this.id = data.id || this.generateId();
         this.studentId = data.studentId || '';
+        this.semesterId = data.semesterId || null;
         this.productId = data.productId || '';
         this.status = data.status || 'pending'; // 'pending', 'confirmed', 'cancelled'
         this.reservedAt = data.reservedAt || new Date().toISOString();
@@ -256,6 +257,7 @@ class Order {
         return {
             id: this.id,
             studentId: this.studentId,
+            semesterId: this.semesterId,
             productId: this.productId,
             status: this.status,
             reservedAt: this.reservedAt,

public/css/teacher.css

@@ -394,6 +394,42 @@
 .operations-list {
   max-height: 200px;
   overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.operation-item {
+  background: #f1f3f5;
+  padding: 10px;
+  border-radius: 6px;
+  font-size: 0.9em;
+}
+
+.operation-header {
+  display: flex;
+  justify-content: space-between;
+  margin-bottom: 5px;
+}
+
+.operation-reason {
+  font-weight: bold;
+}
+
+.operation-points.add {
+  color: #28a745;
+}
+
+.operation-points.subtract,
+.operation-points.purchase {
+  color: #dc3545;
+}
+
+.operation-footer {
+  display: flex;
+  justify-content: space-between;
+  color: #6c757d;
+  font-size: 0.85em;
 }
 
 /* 预约管理样式 */
@@ -613,6 +649,16 @@
   color: white;
 }
 
+.backup-manager-btn {
+  background: #6f42c1;
+  color: white;
+}
+
+.repair-btn {
+  background: #fd7e14;
+  color: white;
+}
+
 .reset-btn.danger {
   background: #dc3545;
   color: white;
@@ -1419,10 +1465,11 @@
   width: 100%;
   border-collapse: collapse;
   background: white;
-  box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
 }
 
-.data-table th, .data-table td {
+.data-table th,
+.data-table td {
   padding: 12px 15px;
   text-align: left;
   border-bottom: 1px solid #ddd;

public/js/display.js

@@ -453,7 +453,8 @@ async function adjustPoints(studentId, points) {
 
     } catch (error) {
         console.error('积分操作失败:', error);
-        showMessage('积分操作失败，请重试', 'error');
+        // 使用服务器返回的具体错误信息，如果没有则使用默认提示
+        showMessage(error.message || '积分操作失败，请重试', 'error');
     } finally {
         // 重新启用按钮
         setTimeout(() => {