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

## 📋 概述

本工具用于将学校历史操行分数据从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): 初始版本，支持完整迁移流程
- 支持断点续传和错误恢复
- 自动验证和报告生成