hzdyjs/学校学生操行历史数据迁移/README.md

学生操行分历史数据迁移工具

📋 概述

本工具用于将学校历史操行分数据从Excel文件导入到校园管理系统数据库中。支持完整的迁移流程，包括数据导入、解析、关联、导入和验证。

🎯 迁移流程

数据处理流程

Excel文件 → 临时表导入 → 数据解析 → 学生关联 → 正式导入 → 验证清理

脚本执行顺序

1. 01_import_excel_to_temp.py - Excel数据导入临时表
2. 02_parse_score_data.py - 数据解析处理
3. 03_link_student_data.py - 数据关联处理
4. 04_import_to_production.py - 正式导入处理
5. 05_validate_and_cleanup.py - 验证与清理

🚀 快速开始

1. 环境准备

# 安装依赖
pip install -r requirements.txt

# 确保Excel文件存在
ls -la 操行.xls

2. 创建临时表

# 连接到数据库，执行建表脚本
mysql -h 47.99.164.66 -u root -p hzdyjs_xg < create_temp_tables.sql

3. 执行完整迁移

# 一键执行所有步骤
python import_conduct_score_history.py

4. 分步骤执行（推荐用于调试）

# 步骤1：Excel导入
python 01_import_excel_to_temp.py

# 步骤2：数据解析
python 02_parse_score_data.py

# 步骤3：数据关联
python 03_link_student_data.py

# 步骤4：正式导入
python 04_import_to_production.py

# 步骤5：验证清理
python 05_validate_and_cleanup.py

📊 数据格式说明

Excel文件要求

• 文件名：操行.xls
• 必需列：学号、学年、学期、平时分数
• 其他列：姓名、性别、民族、最终分、等级、院系、专业、班级、年级

数据格式转换

学年格式

• Excel: 2015-2016
• 数据库: 2015

学期格式

• Excel: 第一学期 → 数据库: 1
• Excel: 第二学期 → 数据库: 2

平时分数格式

• Excel: 一月:90,九月:85,十月:85,十一月:90,十二月:85
• 数据库: 多条月度记录，每条记录一个月份的分数

🛠️ 高级用法

从指定步骤开始执行

# 从步骤3开始执行（适用于断点续传）
python import_conduct_score_history.py --start-from 3

仅执行验证

# 只执行验证步骤，不执行迁移
python import_conduct_score_history.py --validate-only

清理临时数据

# 验证完成后清理临时表
python 05_validate_and_cleanup.py --cleanup

📋 配置说明

数据库配置 (db_config.py)

• 数据库连接信息
• 表名映射
• 常量配置
• 月度和学期映射

日志文件

• logs/01_import_excel.log - Excel导入日志
• logs/02_parse_data.log - 数据解析日志
• logs/03_link_data.log - 数据关联日志
• logs/04_import_production.log - 正式导入日志
• logs/05_validate_cleanup.log - 验证清理日志
• logs/migration_main.log - 主控制脚本日志

🔍 验证与监控

自动验证

脚本5会自动进行以下验证：

• 数据完整性检查
• 关联关系验证
• 重复数据检查
• 分数范围验证

错误处理

• 解析失败的记录会标记为error状态
• 关联失败的记录会记录错误信息
• 导入失败的记录会回滚并记录

输出文件

• migration_report_YYYYMMDD_HHMMSS.txt - 详细迁移报告
• migration_parse_errors.csv - 解析错误详情
• migration_link_errors.csv - 关联错误详情

⚠️ 注意事项

数据安全

• 导入前会检查重复数据，避免重复导入
• 事务处理确保数据一致性
• 支持断点续传，不会因为中断丢失进度

性能考虑

• 大批量处理，自动分批提交
• 索引优化，提升查询性能
• 内存管理，避免大文件导致内存溢出

错误恢复

• 每个步骤都可以独立重试
• 错误记录详细，便于问题定位
• 支持部分成功场景的继续处理

🐛 故障排除

常见问题

1. Excel文件不存在

   • 检查文件路径和文件名
   • 确保文件在当前目录

2. 数据库连接失败

   • 检查网络连接
   • 验证数据库配置
   • 确认用户权限

3. 数据解析失败

   • 检查Excel数据格式
   • 查看错误日志详情
   • 手动修复数据后重试

4. 学生关联失败

   • 检查学号是否存在于学生表
   • 确认学生状态为有效
   • 查看关联错误CSV文件

调试模式

# 查看详细日志
tail -f logs/migration_main.log

# 检查临时表数据
mysql -e "SELECT COUNT(*) FROM temp_conduct_score_import;"

# 查看错误记录
mysql -e "SELECT * FROM temp_conduct_score_parsed WHERE processing_status = 'error' LIMIT 5;"

📞 技术支持

如遇到问题，请：

1. 查看相关日志文件
2. 检查错误输出文件
3. 确认数据格式正确性
4. 联系技术支持团队

📝 更新日志

• v1.0.0 (2025-01-XX): 初始版本，支持完整迁移流程
• 支持断点续传和错误恢复
• 自动验证和报告生成