211 lines
4.9 KiB
Markdown
211 lines
4.9 KiB
Markdown
# 学生操行分历史数据迁移工具
|
||
|
||
## 📋 概述
|
||
|
||
本工具用于将学校历史操行分数据从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. 环境准备
|
||
|
||
```bash
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 确保Excel文件存在
|
||
ls -la 操行.xls
|
||
```
|
||
|
||
### 2. 创建临时表
|
||
|
||
```bash
|
||
# 连接到数据库，执行建表脚本
|
||
mysql -h 47.99.164.66 -u root -p hzdyjs_xg < create_temp_tables.sql
|
||
```
|
||
|
||
### 3. 执行完整迁移
|
||
|
||
```bash
|
||
# 一键执行所有步骤
|
||
python import_conduct_score_history.py
|
||
```
|
||
|
||
### 4. 分步骤执行（推荐用于调试）
|
||
|
||
```bash
|
||
# 步骤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`
|
||
- 数据库: 多条月度记录，每条记录一个月份的分数
|
||
|
||
## 🛠️ 高级用法
|
||
|
||
### 从指定步骤开始执行
|
||
|
||
```bash
|
||
# 从步骤3开始执行（适用于断点续传）
|
||
python import_conduct_score_history.py --start-from 3
|
||
```
|
||
|
||
### 仅执行验证
|
||
|
||
```bash
|
||
# 只执行验证步骤，不执行迁移
|
||
python import_conduct_score_history.py --validate-only
|
||
```
|
||
|
||
### 清理临时数据
|
||
|
||
```bash
|
||
# 验证完成后清理临时表
|
||
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文件
|
||
|
||
### 调试模式
|
||
|
||
```bash
|
||
# 查看详细日志
|
||
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): 初始版本，支持完整迁移流程
|
||
- 支持断点续传和错误恢复
|
||
- 自动验证和报告生成
|