# 生产环境部署指南 - 学校班级ID迁移

## 背景说明

由于雪花算法生成的 ID（19位数字）超出了 JavaScript 安全整数范围（`9007199254740991`），导致前端在处理 `pg_school_class.id` 时会丢失精度。

本次更新将 `pg_school_class` 表的 ID 生成策略从雪花算法改为数据库自增。

## 涉及的代码变更

| 文件 | 变更内容 |
|------|----------|
| `PgSchoolClass.java` | `@TableId(type = IdType.ASSIGN_ID)` → `@TableId(type = IdType.AUTO)` |
| `SchoolClassIdMigration.java` | 新增，应用启动时自动迁移（仅开发环境使用） |

## 部署步骤

### 1. 准备工作

- [ ] 通知相关人员，安排维护窗口
- [ ] 备份生产数据库（完整备份）
- [ ] 准备好回滚方案

### 2. 执行数据库迁移

**重要：在部署新代码之前执行！**

```bash
# 连接到生产数据库
mysql -h <host> -u <user> -p <database>

# 执行迁移脚本
source production_migrate_school_class_id.sql
```

脚本执行过程中会显示：
- 需要迁移的记录数
- ID 映射详情（旧ID → 新ID）
- 数据完整性验证结果

### 3. 验证迁移结果

确认脚本输出中所有检查项都显示 `✓ 通过`：
- 数据完整性检查
- 学生关联检查  
- ID范围检查

### 4. 部署新代码

```bash
# 停止应用服务
systemctl stop pangu-business

# 部署新版本 JAR
cp pangu-business-new.jar /opt/pangu/pangu-business.jar

# 启动应用服务
systemctl start pangu-business
```

**注意**：新代码中包含 `SchoolClassIdMigration.java`，但由于数据库已经迁移完成，该组件会检测到无需迁移并跳过。

### 5. 功能验证

- [ ] 登录系统，访问学生管理页面
- [ ] 查看学生列表，确认班级名称正常显示
- [ ] 编辑学生，选择班级后保存
- [ ] 再次编辑该学生，确认班级信息正确回显
- [ ] 新增班级，确认功能正常

### 6. 清理临时表

确认功能正常后，执行清理：

```sql
DROP TABLE IF EXISTS tmp_school_class_id_mapping;
DROP TABLE IF EXISTS pg_school_class_backup_prod;
DROP TABLE IF EXISTS pg_student_class_backup_prod;
```

## 回滚方案

如果迁移出现问题，执行回滚脚本：

```bash
mysql -h <host> -u <user> -p <database>
source production_rollback_school_class_id.sql
```

回滚后需要部署旧版本代码。

## 常见问题

### Q: 迁移脚本执行失败怎么办？

A: 脚本在执行过程中创建了备份表，可以通过回滚脚本恢复。如果回滚脚本也失败，使用完整数据库备份恢复。

### Q: 新代码部署后，自动迁移组件会重复执行吗？

A: 不会。`SchoolClassIdMigration.java` 会检测是否存在超出安全范围的 ID，如果没有则跳过迁移。

### Q: 迁移后新增的班级 ID 是什么样的？

A: 新增班级的 ID 将是小的自增数字（如 113, 114, 115...），不再是 19 位的雪花 ID。

## 文件清单

| 文件 | 用途 |
|------|------|
| `production_migrate_school_class_id.sql` | 生产环境迁移脚本 |
| `production_rollback_school_class_id.sql` | 回滚脚本 |
| `DEPLOYMENT_GUIDE.md` | 本文档 |