# 专业合并功能实施计划

> 状态：P0 已落地（待联调验收）  
> 更新时间：2026-08-18  
> 入口页面：`/student/classmsg/majormsg`（专业信息）  
> 背景：生产环境存在重复专业定义（如「中药」与「中药(技师)」），需将源专业下班级/学生及业务当前归属合并到目标专业。

### 已落地代码位置

| 项 | 路径 |
|----|------|
| 预览/合并 API | `POST /xg/major/merge/preview`、`POST /xg/major/merge` |
| Controller | `ruoyi-xg/.../XgMajorMergeController.java` |
| Service | `ruoyi-xg/.../XgMajorMergeServiceImpl.java` |
| 前端 | `web/src/views/xg/xsjcxx/classmsg/majormsg/index.vue` |
| DDL | `docs/设计文档/database/专业信息管理/专业合并快照表结构.sql` |
| 权限 | `docs/设计文档/database/专业信息管理/专业合并菜单权限.sql` |

---

## 1. 目标与原则

### 1.1 业务目标

在专业信息界面多选专业 → 点击【专业合并】→ 弹窗从已选中指定**一个目标专业** → 其余源专业的**当前归属数据**全部改挂到目标专业 → 源专业**停用**。

### 1.2 已确认规则

| 规则 | 结论 |
|------|------|
| 班级处理 | 班级整体挂到目标专业；**班级 ID 不变**；同名班**不合并** |
| 学生处理 | 只改专业归属，**不改班级** |
| 源专业处理后 | 本版仅 **停用**（`status=1`），是否逻辑删除后续再定 |
| 学院约束 | 仅允许**同一学院**下的专业互相合并 |
| 历史快照 | 转班等「原专业/新专业」历史记录 **不回写** |

### 1.3 核心原则（防漏改）

**凡表示「当前专业归属」的字段，`major_id` 与 `major_name`（以及存在的 `major_code`）必须成对同步更新。**

禁止只改 ID、不改名称：列表/导出/筛选会出现「ID 已是中药、名称仍显示中药(技师)」的异常。

更新条件统一为：

```text
WHERE major_id IN (源专业ID列表)
SET major_id = 目标专业ID,
    major_name = 目标专业名称
-- 若表有 major_code / major_dept_id，一并改为目标专业对应值
```

---

## 2. 改造范围总表

### 2.1 组织与主数据（必改，事务内优先）

| 序号 | 表 | 动作 | ID / 名称字段 |
|------|-----|------|----------------|
| 1 | `sys_dept`（班级节点 `bj-*`） | `parent_id` 改为目标专业；重算 `ancestors` | 无冗余名称 |
| 2 | `sys_dept`（源专业 `zy-*`） | `status = '1'`（停用） | `dept_name` 保留作追溯 |
| 3 | `xg_class_msg` | 当前归属改挂 | **`major_id` + `major_name` 同改** |
| 4 | `xg_student_msg` | 当前归属改挂 | **`major_id` + `major_name` 同改** |
| 5 | `xg_student_manager_source` | `data_id` 若等于源专业 ID，改为目标专业 ID | 无名称字段 |

说明：`sys_user.dept_id` 本系统学生通常挂**班级**；合并时班级 ID 不变则用户表一般无需改。合并前应用 SQL 探测是否存在 `dept_id IN (源专业ID)`，有则改为目标专业 ID。

### 2.2 业务冗余表（必改：当前归属 = 源专业时）

原则：**有 ID 改 ID，有名称改名称，有编码改编码；能按 ID 定位的优先按 ID。**

| 模块 | 表 | 同改字段 | 备注 |
|------|-----|----------|------|
| 请假 | `xg_student_leave` | `major_id` + `major_name` | |
| 销假 | `xg_student_cancel_leave` | `major_id` + `major_name` | |
| 宿舍申请 | `xg_dorm_application` | `major_id` + `major_name` | |
| 床位分配 | `xg_dorm_bed_student` | `major_id` | 无名称字段 |
| 卫生评分 | `xg_dorm_hygiene_student_score` | `major_id` + `major_name` | |
| 查寝明细 | `xg_dorm_roll_call_detail` | `major_id` + `major_name` | |
| 违纪 | `xg_dorm_violation` | `major_id` + `major_name` | |
| 假期留宿 | `xg_holiday_stay` | `major_id` + `major_name` | |
| 信息收集批次班级 | `xg_stu_col_batch_class` | `major_id` + `major_name` | |
| 学生信息批次 | `xg_student_msg_batch` | `major_id` + `major_name` | |
| 心理测评 | `xljk_evaluation` | `major_id` + `major_name` | |
| 考核申请 | `xskh_assessment_application` | `major_id` + `major_name` | |
| 考核审批 | `xskh_assessment_application_approval` | `major_id` + `major_name` | |
| 处分 | `xskh_discipline_record` | `major_id` + `major_name` | |
| 奖励 | `xskh_reward_record` | `major_id` + `major_name` | |
| 贫困认定 | `jcbt_poverty_application` | `major_id` + `major_name`（+`major_code` 若有） | |
| 奖学金申请 | `jcbt_scholarship_application` | `major_id` | 无名称字段 |
| 勤工助学 | `jcbt_work_study_application` | **仅有 `major_name`** | 见 §2.4 特殊处理 |
| 毕业生 | `zsjy_graduate_info` | `major_id` + `major_name` | |
| 实习 | `zsjy_internship_info` | `major_id` | 无名称字段 |
| 招生专业配置 | `zsjy_enrollment_major` | `major_dept_id` + `major_name` + `major_code` | **特殊**：存在 `uk_major_dept` 唯一键；目标已有配置则**逻辑删除源行**，否则改挂 |

### 2.3 配置 / 权限类（有则改）

| 表 | 动作 |
|----|------|
| `jcbt_scholarship_quota` | `target_dept_id` 若等于源专业 ID → 改为目标专业 ID（注意唯一约束冲突时需合并名额行） |
| `sys_role_dept` | `dept_id` 若等于源专业 ID → 改为目标专业 ID（注意主键冲突去重） |

### 2.4 特殊处理表

| 表 | 策略 |
|----|------|
| `jcbt_work_study_application` | 仅有 `major_name`：按**源专业名称精确匹配**更新为目标专业名称；合并前日志记录影响行数 |
| `xg_student_class_change` | **不更新**（`original_*` / `new_*` 为历史真相） |
| `*_his`、备份表、`sys_oper_log` | **不更新** |
| `cx_zysj` / `cx_bjsj` / `cx_xssj` | **本版不更新**；文档标注超星同步回写风险，P2 做映射 |
| `zsjy_major_info` / `his_*` | 非学工主链路组织树；本版不改，避免误伤招生目录 |

### 2.5 班级维度表（一般不必改专业）

以下按 `class_id` 关联，班级 ID 不变则**无需因合并改行**（除非另有 `major_id`）：

- `xg_conduct_score`
- `xg_class_pos_msg`
- `xg_class_teacher_counselor_rel`

合并后统计「按专业」时走班级 → `xg_class_msg.major_id`，因此班级主数据改对即可。

---

## 3. 防漏改机制（解决「范围不够」）

### 3.1 后端统一更新器（推荐）

不要散落多处手写 UPDATE。在服务内维护**白名单清单**：

```text
MajorMergeTableSpec {
  tableName
  idColumn          // major_id / major_dept_id / data_id / target_dept_id / dept_id
  nameColumn?       // major_name，可空
  codeColumn?       // major_code，可空
  extraWhere?       // 如 deleted=0
  strategy          // BY_ID | BY_NAME_ONLY | DEPT_TREE | SKIP_HISTORY
}
```

合并服务循环执行：

1. 预检 COUNT（按源 ID / 源名称）→ 写入合并结果 VO / 操作日志  
2. 事务内按清单 UPDATE  
3. 组织树改挂 + 源专业停用  
4. 合并后复查：各表白名单 `COUNT(源专业ID) == 0`，否则整单回滚并报错

### 3.2 合并前预检 SQL（上线前必跑）

对每个候选源专业 ID，输出各表命中行数；发现「新表有 `major_id` 但不在白名单」时，**禁止上线**，先补清单。

可维护仓库脚本：`test/专业合并影响行数预检.sql`（开发阶段补充）。

### 3.3 名称同步硬规则

```text
IF 表同时存在 major_id 与 major_name:
    禁止只更新其中一个
IF 仅存在 major_name:
    使用源专业名称精确匹配更新（并记录日志）
IF 仅存在 major_id:
    只更新 ID
```

目标专业名称取自合并时刻 `sys_dept.dept_name`（目标节点），保证与组织树一致。

---

## 3.4 合并前行级快照备份（P0 必做，便于错误恢复）

### 为什么要做 / 为什么不做整表备份

| 方式 | 结论 |
|------|------|
| 整表 `CREATE TABLE AS SELECT` | **不采用**：学生/业务表体量大，每次合并磁盘与耗时不可控 |
| 仅事务回滚 | **不够**：合并**成功提交后**若发现选错目标专业，事务已结束无法回退 |
| **只备份将被修改的行** | **采用**：体积小、可按 `merge_batch_id` 追溯与回滚 |

### 表设计

**1）合并批次主表 `xg_major_merge_batch`**

| 字段 | 说明 |
|------|------|
| `id` | 雪花 ID，即 `merge_batch_id` |
| `target_major_id` / `target_major_name` | 目标专业 |
| `source_major_ids` / `source_major_names` | JSON，源专业列表 |
| `college_id` | 所属学院 |
| `status` | `SUCCESS` / `FAILED` / `ROLLED_BACK` |
| `summary_json` | 各表更新行数摘要 |
| `operator_id` / `create_time` 等 | 标准审计字段 |

**2）行快照表 `xg_major_merge_row_snapshot`**

| 字段 | 说明 |
|------|------|
| `id` | 雪花 ID |
| `merge_batch_id` | 关联批次 |
| `table_name` | 原表名，如 `xg_student_msg` |
| `row_pk` | 原表主键值（字符串，兼容联合主键时用约定拼接） |
| `row_json` | 更新前整行 JSON（或至少还原所需列：专业相关字段 + 主键 + 组织树字段） |
| `create_time` | 快照时间 |

说明：`sys_dept` 班级改挂、源专业停用前，同样写入快照（记录改前的 `parent_id`/`ancestors`/`status`）。

### 执行顺序（必须先快照再改数）

```text
1. 校验参数与同学院
2. 生成 merge_batch_id，写入 batch 主表（status 可先 SUCCESS 前用 RUNNING）
3. 按白名单：把「即将被 UPDATE 的行」INSERT 进 row_snapshot
4. 再执行各表 UPDATE / 组织树改挂 / 停用源专业
5. 复查无源专业 ID 残留
6. 更新 batch.summary_json、status=SUCCESS
失败则事务回滚（含已写入的本批快照）；若需「成功后回滚」见下
```

事务策略建议：

- **同事务**：快照 + 改数同一事务 → 失败自动干净回滚。  
- **成功后误操作恢复**：另提供运维接口/SQL：按 `merge_batch_id` 读取 `row_json` 回写原表（P0 至少落库快照并文档化手工回滚步骤；P1 再做一键 `rollback` API）。

### 回滚注意事项

- 回滚只能恢复「本批改过的行」；合并后若业务又改过这些行，回滚会覆盖后续人工修改 → 回滚前需人工确认。  
- `sys_role_dept` / 名额表若发生「删源行 + 合并到目标行」，快照需记录删除前整行，回滚逻辑单独处理。  
- 快照表本身不做业务查询用途，可按保留策略定期归档（如保留 180 天）。

---

## 4. 接口设计

### 4.1 影响预览（建议 P0 带上，降低误操作）

```http
POST /system/dept/major/merge/preview
权限: majormsg:major:merge

Body:
{
  "targetMajorId": 20251223133304109,
  "sourceMajorIds": [20251223133304116]
}

Response data:
{
  "targetMajorId": ...,
  "targetMajorName": "中药",
  "sources": [
    {
      "majorId": ...,
      "majorName": "中药(技师)",
      "classCount": 1,
      "studentCount": 50,
      "tableHits": [
        { "table": "xg_student_leave", "rows": 0 },
        ...
      ]
    }
  ],
  "warnings": ["同学院校验通过", "..."]
}
```

### 4.2 执行合并

```http
POST /system/dept/major/merge
权限: majormsg:major:merge

Body: 同 preview

Response data:
{
  "success": true,
  "mergeBatchId": 2089...,
  "movedClassCount": 1,
  "updatedStudentCount": 50,
  "disabledMajorCount": 1,
  "snapshotRowCount": 120,
  "tableUpdateSummary": [ { "table": "xg_class_msg", "updated": 1 }, ... ]
}
```

校验失败示例：

- 源列表为空 / 未含目标 / 目标不在已选集合  
- 所选不足 2 个专业  
- 跨学院  
- 目标已停用或不存在  
- 复查仍有源专业 ID 残留  

### 4.3 权限与菜单

- 新增按钮权限：`majormsg:major:merge`  
- 菜单/角色授权与现有 `majormsg:major:*` 一并配置 SQL  

---

## 5. 前端设计（`majormsg/index.vue`）

1. 工具栏增加【专业合并】（`v-hasPermi="['majormsg:major:merge']"`）  
2. `selection.length < 2` 时禁用  
3. 弹窗：  
   - 展示已选专业列表（名称 + 类别编码）  
   - 单选「目标专业」（仅能选已选中的项）  
   - 可选：调用 preview 展示班级数/学生数/业务命中  
   - 二次确认文案：明确「源专业将停用；班级不合并；名称与 ID 同步改挂」  
4. 成功后刷新列表  

---

## 6. 后端实现要点

| 项 | 说明 |
|----|------|
| 模块位置 | 建议放在系统部门能力旁：`SysDept` 相关 Service，或学工模块包装后调部门服务；**事务边界在同一服务方法** |
| 事务 | `@Transactional(rollbackFor = Exception.class)` |
| 祖先路径 | 班级 `ancestors = 目标专业.ancestors + ',' + 目标专业.deptId` |
| 操作日志 | `@Log` 记录目标/源/摘要 |
| 幂等 | 源专业已停用且无子班级时可提示「无需合并」 |

伪代码顺序：

```text
1. 校验参数与同学院
2. 创建 merge_batch，按白名单把「将改行」写入 xg_major_merge_row_snapshot
3. 更新各业务表白名单（ID+名称同改）
4. 更新 xg_student_msg / xg_class_msg
5. 更新 sys_dept 班级 parent/ancestors
6. 处理 manager_source / role_dept / scholarship_quota
7. 停用源专业
8. 复查 COUNT(源ID)==0，否则抛错回滚
9. 回写 batch 摘要与 SUCCESS；接口返回 mergeBatchId
```

---

## 7. 分期交付

| 阶段 | 内容 | 验收 |
|------|------|------|
| **P0** | 前端按钮+弹窗；preview+merge API；**行级快照表+批次表**；`sys_dept`+`xg_class_msg`+`xg_student_msg`+manager_source；白名单业务表 ID+名称同改；源专业停用；权限+日志；文档化按 batch 手工回滚步骤 | 用「中药(技师)→中药」演练：班级挂对、学生名称变「中药」、源专业停用、复查无残留；快照行数与更新行数一致 |
| **P1** | 预检脚本入库；名额/角色冲突处理增强；**一键按 mergeBatchId 回滚 API**；合并结果导出 | 成功合并后可一键恢复到合并前 |
| **P2** | 超星同步映射；可选逻辑删除源专业；快照归档策略 | 同步不回写重复专业 |

---

## 8. 测试用例（最小集）

1. 同学院 2 个专业合并成功；目标名称写入所有命中业务行  
2. 只改 ID 漏改名称的回归：抽查 `xg_student_msg`、`xg_student_leave` 等 `major_id` 与 `major_name` 一致  
3. 跨学院拒绝  
4. 选 1 个专业无法合并  
5. 同名班级并存（不合并班级）  
6. `xg_student_class_change` 历史行不变  
7. 事务中途失败整单回滚（含本批快照）  
8. 无权限看不到按钮 / 接口 403  
9. 合并成功后快照可查；按文档步骤可手工恢复抽样表  

---

## 9. 文档与配置同步（开发时）

- API：`docs/开发文档/API/` 下增补「专业合并」章节（或写入专业信息管理 API）  
- 权限初始化 SQL  
- 快照/批次表 DDL 放入 `docs/设计文档/database/`  
- 本实施计划随代码落地更新「状态：已完成」  

---

## 10. 开放问题（实现前可默认）

| 问题 | 默认建议 |
|------|----------|
| 勤工助学仅名称字段误伤同名？ | 精确匹配源 `dept_name`；合并前 preview 展示行数人工确认 |
| 奖学金名额行冲突 | 目标已有名额则累加 `total_quota` 后删源行，或报错人工处理（P0 可报错） |
| 超星 | P0 合并后口头告知运营：勿从超星再灌该源专业码 |
| 快照保留多久 | 默认 180 天，可配置 |

---

## 11. 评审确认清单

请确认后进入开发：

- [ ] ID 与名称（及 code）同改原则同意  
- [ ] §2 表白名单范围同意（可增删）  
- [ ] 历史表 / 超星本版不改同意  
- [ ] P0 含 preview 同意  
- [ ] 权限码 `majormsg:major:merge` 同意  
- [x] **合并前行级快照备份**同意（非整表；P0 落库 + 手工回滚说明；P1 一键回滚）  

确认后按本计划实现前后端与预检 SQL。