guoyu/工具包使用说明.txt

========================================
数据管理工具包
========================================
创建时间：2025-12-11
目的：解决学生管理和课程分配人数不一致问题

----------------------------------------
📁 工具清单
----------------------------------------

1. 【必备】导入前数据备份.bat
   - 用途：导入新用户前备份数据
   - 使用时机：每次导入前必须运行
   - 备份内容：sys_user、student_class、class 三张表
   - 备份位置：log\backup\backup_YYYYMMDD_HHMMSS\

2. 【诊断】检查班级数据一致性.bat
   - 用途：检查数据是否存在问题
   - 使用时机：导入前/后、发现问题时
   - 检查内容：
     ✓ 各班级学生数量（有效 vs 总数）
     ✓ 存在问题的班级详情
     ✓ 学生重复分配情况
     ✓ 孤儿记录（已删除学生的分配记录）

3. 【修复】修复所有班级status问题.bat
   - 用途：一键修复所有status=0的问题
   - 使用时机：检查发现问题后
   - 修复内容：将所有正常学员的班级分配改为有效（status=1）
   - 安全性：只修改正常学员，不影响已删除学员

4. 【统计】统计课程分配情况.bat
   - 用途：查看整体数据分布
   - 使用时机：任何时候
   - 统计内容：
     ✓ 各班级的学生分布（按监区）
     ✓ 各监区的班级分布
     ✓ 班级规模统计
     ✓ 未分配班级的学生

5. 【高级】创建辅助视图.sql
   - 用途：在数据库中创建便捷查询视图
   - 使用方法：mysql -u root -proot study < 创建辅助视图.sql
   - 视图列表：
     ✓ v_student_current_class - 学生当前班级
     ✓ v_class_statistics - 班级统计
     ✓ v_prison_area_statistics - 监区统计
     ✓ v_course_assignment_detail - 课程分配详情

6. 【参考】用户导入操作指南.md
   - 用途：完整的操作手册
   - 内容：导入前准备、执行导入、验证、问题排查

7. 【旧版】检查最新语音记录.bat
   - 用途：查询最新的语音评测记录
   - 使用时机：测试语音评测功能后

----------------------------------------
🚀 快速开始
----------------------------------------

【场景1】准备导入新用户
步骤：
1. 运行：导入前数据备份.bat
2. 运行：检查班级数据一致性.bat
3. 如果有问题，运行：修复所有班级status问题.bat
4. 在后台管理系统执行导入
5. 导入后再次运行：检查班级数据一致性.bat

【场景2】发现人数不一致
步骤：
1. 运行：检查班级数据一致性.bat（确认问题）
2. 运行：修复所有班级status问题.bat（一键修复）
3. 刷新后台管理页面验证

【场景3】查看整体数据情况
步骤：
1. 运行：统计课程分配情况.bat
2. 查看各班级、监区的学生分布

----------------------------------------
⚠️ 注意事项
----------------------------------------

1. 【重要】导入前务必备份数据！
2. 修复脚本是安全的，只修改status字段
3. 所有脚本都不会删除数据
4. 如果不确定，先运行"检查"脚本查看情况
5. 遇到问题可参考"用户导入操作指南.md"

----------------------------------------
🔍 问题排查
----------------------------------------

问题1：学生管理显示12人，课程分配显示14人
原因：存在status=0的无效分配记录
解决：运行"修复所有班级status问题.bat"

问题2：导入提示"班级不存在"
原因：Excel中的班级名称系统中不存在
解决：先在后台管理创建班级，或修正Excel

问题3：学生同时在多个班级
原因：历史遗留或多次导入未处理旧班级
解决：查看"用户导入操作指南.md"的Q3部分

问题4：导入后看不到学生
原因：status不是0或del_flag是2
解决：查看"用户导入操作指南.md"的Q4部分

----------------------------------------
📞 技术说明
----------------------------------------

核心问题：
- student_class表的status字段
  status=1：有效分配（学生在该班级）
  status=0：无效分配（学生已移除）
- 学生管理查询只统计status=1的记录
- 如果课程分配统计了所有记录，就会不一致

解决方案：
- 代码层面：所有新操作都正确设置status=1 ✅
- 数据层面：用脚本修复历史遗留的status=0记录 ✅
- 监控层面：提供检查工具随时发现问题 ✅

----------------------------------------
✅ 已解决的问题
----------------------------------------

1. ✅ 语音评测音频路径保存问题
   - 前端传递服务器路径而非本地路径
   - 后端返回MP3路径而非WAV路径

2. ✅ 学生管理和课程分配人数不一致
   - 代码逻辑已完善
   - 提供一键修复工具
   - 提供完整操作指南

3. ✅ 用户导入可能出现的问题
   - 提供备份工具
   - 提供检查工具
   - 提供统计工具
   - 完善操作文档

----------------------------------------
🎉 总结
----------------------------------------

所有工具已就绪，可以放心使用！

建议工作流程：
1. 导入前：备份 → 检查 → （修复）
2. 执行导入
3. 导入后：检查 → （修复）→ 验证

有任何问题请参考"用户导入操作指南.md"

========================================