pangu-user-platform/docs/发布计划_2026-02-05.md

# 增量发布计划

**发布日期**: 2026-02-05  
**目标服务器**: 192.168.71.56  
**发布类型**: 增量发布  
**编制人**: pangu

---

## 一、发布概览

| 项目 | 本地最新版本 | 服务器当前版本 | 待发布提交数 |
|------|-------------|---------------|-------------|
| pangu-user-platform (后端+管理后台) | a9bbb30 | 2026-02-03 22:29 部署 | 6 个 |
| user_authentication_center_front (H5前端) | 76f27ce | 2026-02-03 22:04 部署 | 3 个 |

---

## 二、pangu-user-platform 发布内容

### 2.1 待发布提交清单

| 序号 | Commit ID | 提交说明 | 类型 |
|------|----------|---------|------|
| 1 | a9bbb30 | 业务功能按钮权限统一（v-hasPermi，与角色配置一致） | fix |
| 2 | add00c9 | 新增学校自动添加年级 + 修复区域层级查询 + 清理区域数据 | feat |
| 3 | 72cb666 | 年级管理增加学段字段（小学/初中/高中/中专/大学） | feat |
| 4 | 80dd406 | 新增OpenApi基础数据接口 + 学生完整数据接口 + UI文案优化 | feat |
| 5 | 1a0b75e | 同步需求与技术方案文档 | docs |
| 6 | 6027a8c | 修改后端欢迎语为盘古后台管理系统 | refactor |

### 2.2 功能变更摘要

1. **业务功能按钮权限统一（本次新增）**
   - 学生、会员、学校、应用管理、接口字典、年级、班级、学科、区域等列表页的「新增」「编辑」「删除」「导入」「导出」等按钮增加 `v-hasPermi` 控制
   - 与角色管理中配置的菜单权限一致，无权限用户不显示对应按钮

2. **学校管理优化**
   - 新增学校时自动添加对应学段的年级
   - 修复选择省/市时无法显示学校的Bug（支持区域层级查询）
   - 区域树默认只展开湖北省，平行显示市级

3. **年级管理增强**
   - 新增学段字段（小学/初中/高中/中专/大学）
   - 支持按学段筛选年级

4. **OpenAPI接口扩展**
   - 新增学校/年级/班级基础数据查询接口
   - 新增学生完整数据接口（不脱敏，需特殊授权）

5. **UI文案优化**
   - "教育身份" 改为 "任教信息"
   - 后端欢迎语改为 "盘古后台管理系统"

### 2.3 数据库增量脚本

| 序号 | 脚本文件 | 说明 | 影响范围 | 风险等级 |
|------|---------|------|---------|---------|
| 1 | V1.0.3__open_api_dict.sql | OpenAPI接口字典数据 | pg_api_dict表 | 🟢 低 |
| 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**
- 新增11条API字典记录
- 使用 `ON DUPLICATE KEY UPDATE` 幂等设计
- 可重复执行，无副作用

**V1.0.4__grade_add_stage.sql**
- 为 `pg_grade` 表新增 `stage` 字段
- 自动根据年级名称初始化学段数据
- ⚠️ 注意：执行前需确认 `pg_grade` 表无 `stage` 字段

**V1.0.5__clean_region_data.sql**
- ⚠️ **高风险脚本 - 物理删除操作**
- 删除所有非湖北省的区域数据（约3309条）
- 仅保留湖北省及其下级区域（约120条）
- ⚠️ **执行前必须备份 `pg_region` 表**

### 2.4 服务器部署路径

| 组件 | 路径 |
|------|------|
| 后端 JAR | /opt/pangu-user-platform/backend/pangu-admin.jar |
| 管理后台前端 | /opt/pangu-user-platform/frontend/admin-manage/ |
| 启动脚本 | /opt/pangu-user-platform/scripts/service.sh |
| 配置文件 | /opt/pangu-user-platform/backend/application-test.yml |
| 日志目录 | /opt/pangu-user-platform/backend/logs/ |

---

## 三、user_authentication_center_front 发布内容

### 3.1 待发布提交清单

| 序号 | Commit ID | 提交说明 | 类型 |
|------|----------|---------|------|
| 1 | 76f27ce | 会员支持所在区域：注册和个人中心可填可改，教育身份和绑定学生表单默认带出区域 | feat |
| 2 | 70fc1ad | 优化登录注册页面交互和弹窗内容 | feat |
| 3 | 842d64f | 允许通过IP地址访问H5前端 | fix |

### 3.2 功能变更摘要

1. **会员所在区域（本次新增）**
   - 注册时增加所在区域选择（级联）
   - 个人中心可查看、修改所在区域
   - 添加教育身份、绑定学生时区域默认带出会员区域，可修改

2. **登录注册优化**
   - 优化登录注册页面交互体验
   - 改进弹窗内容展示

3. **访问限制修复**
   - 允许通过IP地址直接访问H5前端

### 3.3 服务器部署路径

| 组件 | 路径 |
|------|------|
| H5前端 | /opt/pangu-user-platform/frontend/user-front/ |

---

## 四、发布步骤

### 4.1 发布前准备

```bash
# 1. 备份数据库
ssh root@192.168.71.56
mysqldump -h 8.148.25.55 -uroot -p pguser-db pg_region > /opt/backup/pg_region_$(date +%Y%m%d_%H%M%S).sql
mysqldump -h 8.148.25.55 -uroot -p pguser-db pg_grade > /opt/backup/pg_grade_$(date +%Y%m%d_%H%M%S).sql
mysqldump -h 8.148.25.55 -uroot -p pguser-db pg_api_dict > /opt/backup/pg_api_dict_$(date +%Y%m%d_%H%M%S).sql

# 2. 备份当前部署版本
cp -r /opt/pangu-user-platform/backend/pangu-admin.jar /opt/backup/pangu-admin.jar.bak
cp -r /opt/pangu-user-platform/frontend/admin-manage /opt/backup/admin-manage.bak
cp -r /opt/pangu-user-platform/frontend/user-front /opt/backup/user-front.bak
```

### 4.2 本地构建

```bash
# 1. 构建后端
cd /Users/felix/pgWorkSpace/pangu-user-platform/backend
./build.sh -q -f

# 2. 构建管理后台前端
cd /Users/felix/pgWorkSpace/pangu-user-platform/frontend
npm run build

# 3. 构建H5前端
cd /Users/felix/pgWorkSpace/user_authentication_center_front/user-front
npm run build
```

### 4.3 上传部署包

```bash
# 1. 上传后端JAR
scp /Users/felix/pgWorkSpace/pangu-user-platform/backend/pangu-admin/target/pangu-admin.jar root@192.168.71.56:/opt/pangu-user-platform/backend/

# 2. 上传管理后台前端
scp -r /Users/felix/pgWorkSpace/pangu-user-platform/frontend/dist/* root@192.168.71.56:/opt/pangu-user-platform/frontend/admin-manage/

# 3. 上传H5前端
scp -r /Users/felix/pgWorkSpace/user_authentication_center_front/user-front/dist/* root@192.168.71.56:/opt/pangu-user-platform/frontend/user-front/

# 4. 上传SQL脚本
scp /Users/felix/pgWorkSpace/pangu-user-platform/scripts/sql/V1.0.*.sql root@192.168.71.56:/opt/pangu-user-platform/scripts/
```

### 4.4 执行数据库脚本

```bash
ssh root@192.168.71.56

# 按顺序执行SQL脚本
mysql -h 8.148.25.55 -uroot -paly2024A pguser-db < /opt/pangu-user-platform/scripts/V1.0.3__open_api_dict.sql
mysql -h 8.148.25.55 -uroot -paly2024A pguser-db < /opt/pangu-user-platform/scripts/V1.0.4__grade_add_stage.sql

# ⚠️ V1.0.5 需要单独确认后执行（高风险）
# mysql -h 8.148.25.55 -uroot -paly2024A pguser-db < /opt/pangu-user-platform/scripts/V1.0.5__clean_region_data.sql
```

### 4.5 重启服务

```bash
ssh root@192.168.71.56

# 重启后端服务
cd /opt/pangu-user-platform/scripts
./service.sh restart

# 检查服务状态
./service.sh status

# 查看启动日志
./service.sh logs
```

### 4.6 验证测试

| 验证项 | 验证方法 | 预期结果 |
|--------|---------|---------|
| 后端服务 | `curl http://localhost:9083/actuator/health` | {"status":"UP"} |
| 管理后台登录 | 浏览器访问管理后台 | 正常登录 |
| 权限按钮显隐 | 用无增删改权限账号登录，进入学生/会员等列表 | 仅显示查询，不显示新增/编辑/删除等按钮 |
| 学校管理-区域树 | 查看区域树展开状态 | 默认展开湖北省 |
| 学校管理-层级查询 | 选择武汉市查看学校 | 显示武汉市下所有学校 |
| 年级管理-学段 | 查看年级列表 | 显示学段列 |
| OpenAPI接口 | 调用新增的接口 | 正常返回数据 |
| H5前端登录 | 浏览器访问H5 | 正常登录 |
| H5会员区域 | 注册选区域、个人中心改区域，教育身份/绑定学生表单 | 区域可选且默认带出会员区域 |

---

## 五、回滚方案

### 5.1 后端回滚

```bash
ssh root@192.168.71.56
cd /opt/pangu-user-platform/scripts

# 停止服务
./service.sh stop

# 恢复JAR包
cp /opt/backup/pangu-admin.jar.bak /opt/pangu-user-platform/backend/pangu-admin.jar

# 启动服务
./service.sh start
```

### 5.2 前端回滚

```bash
# 恢复管理后台前端
rm -rf /opt/pangu-user-platform/frontend/admin-manage/*
cp -r /opt/backup/admin-manage.bak/* /opt/pangu-user-platform/frontend/admin-manage/

# 恢复H5前端
rm -rf /opt/pangu-user-platform/frontend/user-front/*
cp -r /opt/backup/user-front.bak/* /opt/pangu-user-platform/frontend/user-front/
```

### 5.3 数据库回滚

```bash
# 恢复pg_grade表（如果执行了V1.0.4）
mysql -h 8.148.25.55 -uroot -paly2024A pguser-db -e "ALTER TABLE pg_grade DROP COLUMN stage;"

# 恢复pg_region表（如果执行了V1.0.5）
mysql -h 8.148.25.55 -uroot -paly2024A pguser-db < /opt/backup/pg_region_YYYYMMDD_HHMMSS.sql
```

---

## 六、风险评估

| 风险项 | 风险等级 | 应对措施 |
|--------|---------|---------|
| 数据库结构变更 | 🟡 中 | 执行前备份相关表 |
| 区域数据物理删除 | 🔴 高 | 必须备份，可单独安排执行 |
| 后端服务中断 | 🟢 低 | 使用热部署，中断时间<30秒 |
| 前端静态资源更新 | 🟢 低 | nginx无需重启，刷新即生效 |

---

## 七、审批确认

| 角色 | 姓名 | 确认签字 | 日期 |
|------|------|---------|------|
| 开发负责人 | | | |
| 测试负责人 | | | |
| 运维负责人 | | | |
| 项目经理 | | | |

---

## 八、特别说明

### 8.1 关于 V1.0.5__clean_region_data.sql

此脚本将**物理删除**所有非湖北省的区域数据（约3309条），仅保留湖北省及其下级区域（约120条）。

**建议处理方式**：
1. 此脚本可在本次发布中暂不执行
2. 单独安排时间，在业务低峰期执行
3. 执行前必须完成 `pg_region` 表的完整备份
4. 执行后需验证学校管理功能正常

### 8.2 注意事项

1. 发布前确保本地代码已全部提交并推送
2. 建议选择业务低峰期（如晚间或周末）发布
3. 发布后持续关注服务日志，确保无异常

---

*文档生成时间: 2026-02-05*  
*更新说明: 已纳入业务功能按钮权限统一（a9bbb30）与 H5 会员所在区域（76f27ce）两项提交。*