学生学籍号刷新脚本设计说明

📋 文档说明

版本: v1.0.0 制定时间: 2025-12-26 适用范围: 学生学籍号自动刷新业务 重要性: ⚠️ 核心数据处理脚本 - 自动刷新学生学籍号信息

🎯 设计目标

1. 业务需求

自动刷新学籍号: 自动为学生生成学籍号（'G' + 身份证号）
数据完整性: 确保所有学生的ext_field2字段都有正确的学籍号
批量处理: 支持大量数据的批量处理
监控守护: 持续监控并处理新的学生数据

2. 技术要求

数据安全性: 遵循项目数据库设计规范
性能优化: 合理的批量处理策略，支持高效更新
扩展性: 支持一次性处理和持续监控两种模式
容错性: 完善的错误处理和重试机制

🗄️ 脚本架构

文件结构

学籍号刷新/
├── data.conf              # 开发环境配置
├── data.conf.prod         # 生产环境配置
├── process_student_id_card_refresh.sh  # 主处理脚本
└── 学生学籍号刷新脚本设计说明.md     # 设计文档

脚本模式

1. 一次性处理模式

./process_student_id_card_refresh.sh once

一次性刷新所有符合条件的学籍号
适合初始化或手动触发处理

2. 持续监控模式（默认）

./process_student_id_card_refresh.sh

每10分钟检查一次需要刷新的记录
持续运行的守护进程模式

🔄 处理逻辑

刷新规则

学籍号生成规则: ext_field2 = 'G' + id_card

处理条件

WHERE (ext_field2 IS NULL OR ext_field2 = '')
  AND id_card IS NOT NULL
  AND id_card != ''
  AND deleted = 0

更新语句

UPDATE xg_student_msg SET
    ext_field2 = CONCAT('G', id_card),
    update_by = 1,
    update_time = NOW()
WHERE (ext_field2 IS NULL OR ext_field2 = '')
  AND id_card IS NOT NULL
  AND id_card != ''
  AND deleted = 0;

⚙️ 配置说明

data.conf 配置参数

# Database configuration
DB_HOST="47.99.164.66"          # 数据库主机
DB_PORT="3306"                  # 数据库端口
DB_NAME="hzdyjs_xg"            # 数据库名
DB_USER="root"                 # 数据库用户
DB_PASS="hn02le.34lkdLKD"      # 数据库密码

# Script configuration
LOG_DIR="${SCRIPT_DIR}/student_id_card_refresh"  # 日志目录
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"  # 脚本目录
LOCK_FILE="${SCRIPT_DIR}/script.lock"  # 锁定文件

# Processing configuration
BATCH_SIZE=500                 # 批次处理大小
MAX_RETRY=3                    # 最大重试次数
RETRY_DELAY=5                  # 重试间隔（秒）
CYCLE_INTERVAL=600             # 循环间隔（秒，默认10分钟）

🔧 使用方法

1. 准备工作

# 进入脚本目录
cd 学籍号刷新

# 给脚本添加执行权限
chmod +x process_student_id_card_refresh.sh

2. 一次性处理模式

# 执行一次性刷新
./process_student_id_card_refresh.sh once

3. 持续监控模式

# 使用快速启动脚本（推荐）
./run_refresh.sh bg

# 或直接后台运行
nohup ./process_student_id_card_refresh.sh > /dev/null 2>&1 &

4. 停止脚本

# 查找进程
ps aux | grep process_student_id_card_refresh

# 终止进程
kill -9 <PID>

📊 日志和监控

日志文件

日志文件保存在 student_id_card_refresh/ 目录下：

文件命名: process_student_id_card_refresh_YYYYMMDD_HHMMSS.log
包含详细的处理过程和错误信息

日志内容

[2025-12-26 14:30:15] [INFO] 启动学生学籍号刷新处理脚本
[2025-12-26 14:30:15] [INFO] 处理类型: ID_CARD_REFRESH(学籍号刷新)
[2025-12-26 14:30:15] [INFO] 数据库连接成功
[2025-12-26 14:30:15] [INFO] 发现 1250 条需要刷新的学籍号记录，开始处理...
[2025-12-26 14:30:20] [INFO] 批次处理完成 - 找到记录: 500, 失败: 0

监控要点

处理进度: 定期检查日志中的处理进度
错误统计: 关注失败的记录数和错误原因
性能监控: 监控数据库负载和脚本运行状态

🔒 安全考虑

数据安全

多租户隔离: 通过deleted字段和业务逻辑隔离
事务安全: 每次更新都有明确的条件限制
备份机制: 更新前建议备份相关数据
权限控制: 脚本需要数据库写入权限

运行安全

单实例运行: 通过锁定文件防止多实例同时运行
错误处理: 完善的错误捕获和日志记录
资源控制: 合理的批次大小和处理间隔

🚀 性能优化

批量处理策略

批次大小: 500条/批，避免单次处理过多数据
处理间隔: 10分钟，与学生换班级脚本保持一致
并发控制: 单进程运行，避免数据库压力

数据库优化

-- 建议添加的索引（如果性能需要）
ALTER TABLE xg_student_msg ADD INDEX idx_ext_field2_deleted (ext_field2, deleted);
ALTER TABLE xg_student_msg ADD INDEX idx_id_card_deleted (id_card, deleted);

📞 维护说明

定期维护任务

日志清理: 定期清理历史日志文件
配置检查: 检查配置文件是否正确
数据库监控: 监控脚本对数据库的影响
性能调优: 根据实际情况调整批次大小和间隔

故障处理

常见问题

数据库连接失败
- 检查网络连接和数据库状态
- 验证配置文件中的数据库参数
权限不足
- 检查数据库用户的权限
- 确认用户有UPDATE权限
磁盘空间不足
- 清理日志文件
- 检查磁盘空间使用情况

应急处理

# 强制停止脚本
pkill -f process_student_id_card_refresh

# 清理锁定文件
rm -f process_student_id_card_refresh.lock

# 手动执行SQL验证
mysql -h host -u user -p database -e "UPDATE语句"

📈 统计分析

处理统计

-- 查看学籍号刷新情况
SELECT
    COUNT(*) as total_students,
    SUM(CASE WHEN ext_field2 LIKE 'G%' THEN 1 ELSE 0 END) as with_id_card,
    SUM(CASE WHEN ext_field2 IS NULL OR ext_field2 = '' THEN 1 ELSE 0 END) as need_refresh
FROM xg_student_msg
WHERE deleted = 0;

效果验证

-- 验证学籍号格式是否正确
SELECT
    student_no,
    student_name,
    id_card,
    ext_field2,
    CONCAT('G', id_card) as expected_id_card
FROM xg_student_msg
WHERE ext_field2 LIKE 'G%'
  AND CONCAT('G', id_card) != ext_field2
  AND deleted = 0;

⚠️ 重要提醒

数据备份: 执行脚本前务必备份数据库
测试验证: 先在测试环境验证脚本功能
监控运行: 持续监控脚本运行状态和日志
权限控制: 确保脚本运行账号有适当权限
文档同步: 脚本变更必须同步更新本文档

🔗 相关文档

数据库设计: docs/设计文档/database/mysql-database-standard.md
项目规范: .cursor/cursorrules-backend.md
API文档: docs/开发文档/API/用户认证登录API.md

🔧 版本历史

v1.0.2 (2025-12-26) - 易用性增强版

✅ 后台执行: 新增run_refresh.sh bg模式，支持后台守护进程
✅ 用户友好: 提供PID显示、状态检查和停止命令提示
✅ 使用简化: 一键启动后台监控，无需手动nohup

v1.0.1 (2025-12-26) - 性能优化版

✅ 逻辑简化: 移除不必要的预查询统计，直接执行UPDATE语句
✅ 效率提升: 使用SELECT ROW_COUNT()获取受影响行数，一次查询完成所有操作
✅ 代码精简: 减少数据库查询次数，降低系统开销
✅ 监控优化: 监控模式也使用简化的处理逻辑

v1.0.0 (2025-12-26) - 初始版本

✅ 基础学籍号刷新功能
✅ 批量处理和监控模式
✅ 完善的日志和错误处理

最后更新: 2025-12-26 当前版本: v1.0.2 维护人员: AI Assistant 联系方式: 项目技术团队

学生学籍号刷新脚本设计说明.md 8.0 KB 文件歷史 原始文件