# PROD 发布 - SQL 脚本变更检查

**检查日期**: 2026-02-05  
**目标**: 部署前确认 PROD 库需执行的增量脚本及执行顺序

---

## 一、本次发布涉及的 SQL 脚本（scripts/sql/）

| 序号 | 脚本文件 | 说明 | 涉及表 | 风险 | 是否幂等 |
|------|----------|------|--------|------|----------|
| 1 | V1.0.3__open_api_dict.sql | 开放API接口字典数据 | pg_api_dict | 低 | 是（ON DUPLICATE KEY UPDATE） |
| 2 | V1.0.4__grade_add_stage.sql | 年级表增加学段字段 | pg_grade | 中 | 否（重复执行会报错：列已存在） |
| 3 | V1.0.5__clean_region_data.sql | 清理非湖北省区域数据 | pg_region | 高 | 否（物理删除，不可逆） |

---

## 二、各脚本变更内容摘要

### V1.0.3__open_api_dict.sql

- **操作类型**: INSERT（存在则 UPDATE）
- **变更内容**:
  - 学生：OPEN_STUDENT_LIST、OPEN_STUDENT_LIST_FULL（2 条）
  - 学校：OPEN_SCHOOL_LIST、OPEN_SCHOOL_LIST_ALL、OPEN_SCHOOL_INFO（3 条）
  - 年级：OPEN_GRADE_LIST、OPEN_GRADE_LIST_ALL、OPEN_GRADE_INFO（3 条）
  - 班级：OPEN_CLASS_LIST、OPEN_CLASS_LIST_ALL、OPEN_CLASS_INFO（3 条）
- **共 11 条** pg_api_dict 记录
- **执行前**: 确认 PROD 存在表 `pg_api_dict`，且主键/唯一约束与脚本一致（api_id 或 api_code）
- **重复执行**: 安全，仅更新名称/路径/描述

### V1.0.4__grade_add_stage.sql

- **操作类型**: ALTER TABLE + UPDATE
- **变更内容**:
  1. `ALTER TABLE pg_grade ADD COLUMN stage CHAR(1) NULL COMMENT '学段（1小学 2初中 3高中 4中专 5大学）' AFTER grade_name;`
  2. 按年级名称回填：小学(1)/初中(2)/高中(3)，未匹配默认小学(1)
  3. `ALTER TABLE pg_grade MODIFY COLUMN stage ... NOT NULL DEFAULT '1';`
- **执行前**: 必须确认 PROD 的 `pg_grade` **没有** `stage` 列，否则跳过或先判断列是否存在
- **重复执行**: 会报错（列已存在），需做存在性检查或仅执行一次

### V1.0.5__clean_region_data.sql

- **操作类型**: 物理 DELETE
- **变更内容**:
  - 删除所有「非湖北省及其下级」的区域（ancestors 不以 `0,42` 开头，且 region_id≠42）
  - 再删除其他省份根节点（parent_id=0 且 region_id≠42）
- **执行前**: 必须备份 `pg_region`；确认湖北省 region_id=42；建议业务低峰期、单独审批后执行
- **重复执行**: 可执行（已删的不会再删），但不可逆

---

## 三、PROD 执行前必做检查

1. **确认表是否存在**
   - `pg_api_dict`、`pg_grade`、`pg_region` 在 PROD 是否存在且结构一致。

2. **确认是否已执行过**
   - **V1.0.4**：在 PROD 执行  
     `SELECT COUNT(*) FROM information_schema.COLUMNS WHERE TABLE_SCHEMA=DATABASE() AND TABLE_NAME='pg_grade' AND COLUMN_NAME='stage';`  
     - 若结果为 1，说明已有 `stage`，**不要**再执行 V1.0.4。
   - **V1.0.3**：可重复执行，无需跳过。

3. **V1.0.5 是否在本次执行**
   - 若 PROD 需保留多省数据，**不要**执行 V1.0.5。
   - 若只保留湖北省，执行前必须备份：  
     `mysqldump -h <PROD库> -u<> -p pguser-db pg_region > pg_region_backup_YYYYMMDD.sql`

4. **会员区域字段（本次 H5 会员区域功能依赖）**
   - 若 PROD 的 `pg_member` 表是早期建表、**没有** `region_id` 列，需先执行增量加列（见下节），再发布应用与 H5。

---

## 四、可选：pg_member.region_id 增量脚本

若 PROD 的 `pg_member` 尚无 `region_id` 列，需在应用发布前执行（仅执行一次）：

```sql
-- 检查是否已有列（结果为 0 表示需要执行下面的 ADD）
-- SELECT COUNT(*) FROM information_schema.COLUMNS 
-- WHERE TABLE_SCHEMA=DATABASE() AND TABLE_NAME='pg_member' AND COLUMN_NAME='region_id';

ALTER TABLE pg_member 
ADD COLUMN region_id bigint DEFAULT NULL COMMENT '区域ID' AFTER open_id;
```

建议将上述内容保存为 `scripts/sql/V1.0.2__member_region_id.sql`（或 V1.0.6，按你们版本号规范），并在发布计划中注明执行顺序：在 V1.0.3 之前或之后均可（与 pg_grade、pg_region 无依赖）。

---

## 五、推荐执行顺序（PROD）

| 顺序 | 脚本 | 条件 |
|------|------|------|
| 1 | V1.0.2__member_region_id.sql（若有） | 仅当 pg_member 无 region_id 时执行 |
| 2 | V1.0.3__open_api_dict.sql | 必执行 |
| 3 | V1.0.4__grade_add_stage.sql | 仅当 pg_grade 无 stage 列时执行 |
| 4 | V1.0.5__clean_region_data.sql | 仅当确定只保留湖北省且已备份 pg_region 时执行 |

---

*检查说明：按上述顺序与条件执行，可避免重复加列报错与误删区域数据。*