# 学生学籍异动同步教务系统 — 改造方案

## 1. 背景与目标

学生信息模块支持学籍异动（退学、休学、复学、毕业）与换班级等操作，数据已落在本库多张表中。教务系统要求按固定字段接收异动数据。本方案通过**数据库视图（可再叠加物化/同步任务）**汇聚数据，供教务拉数或中间 ETL 使用。

**目标**：在不大改现有业务表的前提下，输出字段稳定、语义清晰、可逐步补全的对外视图。

---

## 2. 教务字段与本地映射总表


| 序号    | 教务字段                             | 本方案取值策略                                                                                                                              | 主要数据来源                                                                  |
| ----- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| 1     | 提交时间                             | 有则格式化为日期 `YYYY-MM-DD`（与教务示例一致）；口径建议统一为「登记/创建侧」：`学籍异动` 用 `apply_date` 或 `create_time`；`换班级` 用 `change_time` 或 `create_time`（实施时二选一写死） | `xg_student_status_change` / `xg_student_class_change`                  |
| 2     | 异动生效学期                           | **保留列，值为空**（`NULL` 或 `''`，与对方接口约定一致即可）                                                                                               | 常量列，不推算                                                                 |
| 3     | 异动生效时间                           | **必填语义由本库生效字段承担**：学籍异动用 `effective_date`；换班级用 `effective_time`（类型统一为 `DATETIME` 便于对接）                                                | 同上两表                                                                    |
| 4     | 异动类型                             | 输出教务附件1 **中文名称**（退学/休学/复学/转班级）；见 §4 映射表；**毕业（BI_YE）不同步**                                                               | 视图内 `CASE` + WHERE 过滤                                                    |
| 5     | 申请人学号                            | 直接输出                                                                                                                                 | `student_no`                                                            |
| 6     | 姓名                               | 输出异动当时姓名：换班级表有 `student_name`；学籍异动可 `JOIN xg_student_msg` 取当前 `name`（若需「当时」姓名需后续增强，见 §6）                                             | 业务表 + `xg_student_msg`                                                  |
| 7     | 异动前所在年级                          | 有则输出                                                                                                                                 | 换班级：`original_`* 无年级时 JOIN 原班级 `xg_class_msg.grade`；学籍异动：见 §6           |
| 8     | 异动前所在校区                          | **暂不填写，恒为空**                                                                                                                         | `NULL`                                                                  |
| 9     | 异动前所在院系                          | 有则输出                                                                                                                                 | 换班级 `original_college_name`；学籍异动见 §6                                    |
| 10    | 异动前所在专业                          | 有则输出                                                                                                                                 | 换班级 `original_major_name`；学籍异动见 §6                                      |
| 11    | 异动前所在班级                          | 有则输出                                                                                                                                 | 换班级 `original_class_name`；学籍异动见 §6                                      |
| 12    | 异动前学制                            | 有则输出                                                                                                                                 | JOIN `xg_class_msg`（原 `class_id`）取 `school_system`                      |
| 13～18 | 异动后所在校区 / 年级 / 班级 / 院系 / 专业 / 学制 | 校区：**空**；其余：换班级用 `new_`* + 新班 `xg_class_msg`；纯学籍异动时教务若仍要求「后」与「前」一致，可用 **COALESCE(后, 前)** 或统一填「前」快照（需与教务确认）                           | `xg_student_class_change` + `xg_class_msg` / 约定                         |
| 19    | 异动后班主任工号                         | 有则输出                                                                                                                                 | `class_teacher_id` → `sys_user.user_no`（需业务确认教师工号存于 `user_no`）          |
| 20    | 异动后班主任姓名                         | 有则输出                                                                                                                                 | `xg_class_msg.class_teacher_name` 或 `xg_student_msg.class_teacher_name` |
| 21    | 新名字                              | 选填；无独立「改名流水」时建议 **NULL**；若仅用 `former_name`/`name` 推断改名，易产生误判，不推荐作为正式口径                                                               | 暂空或后续扩展表                                                                |
| 22    | 审核状态                             | 默认「已通过」或空                                                                                                                            | 常量或扩展字段                                                                 |


---

## 3. 数据源与表关系（现状）


| 表名                         | 用途                                                                           |
| -------------------------- | ---------------------------------------------------------------------------- |
| `xg_student_status_change` | 退学、休学、复学、毕业；含 `effective_date`、`apply_date`、`change_type`、`process_status` 等 |
| `xg_student_class_change`  | 换班级前后学院/专业/班级；含 `effective_time`、`status`、`student_name` 等                   |
| `xg_student_msg`           | 学生当前快照（学号、姓名、班级冗余字段等）                                                        |
| `xg_class_msg`             | 班级学制、年级、班主任等                                                                 |
| `sys_user`                 | 班主任用户编号 `user_no`（作工号来源，需确认）                                                 |


说明：批量处理脚本会向 `xg_student_msg_his` 备份快照；**仅学籍异动**的「异动前」若依赖历史表，需严格定义「取哪一条 his」的规则（见 §6），否则易产生歧义。

---

## 4. 异动类型（与教务对齐）

本库 → 教务附件1 中文名称映射（视图 `异动类型` 列直接输出教务名称）：

| 本库来源 | 内部标识 | 教务异动类型名称 |
| -------- | -------- | ---------------- |
| 学籍异动 | `TUI_XUE` | 退学 |
| 学籍异动 | `XIU_XUE` | 休学 |
| 学籍异动 | `FU_XUE` | 复学 |
| 换班级 | — | 转班级 |

**不同步**：`BI_YE`（毕业）记录不进入视图、不传给教务。

详细说明见：`跟教务系统同步学生异动信息/异动类型映射说明.md`。

「复学并换班级」会同时存在学籍记录与换班级记录：当前策略为 **两条都出**。

---

## 5. 视图设计方案

### 5.1 原则

- 对外**一张宽表视图**（或一张视图 `UNION ALL` 两段子查询），列名与教务一致或建中间映射层。
- **校区列保留**，值为 `NULL`。
- **异动生效学期列保留**，值为 `NULL`。
- **异动生效时间**为真实业务时间，来自库表（见 §2）。

### 5.2 建议结构

1. **子视图 A**：`xg_student_status_change`
  - 关联 `xg_student_msg`（学号、姓名、当前组织维度作「前/后」占位时的来源，按 §6）。  
  - `异动生效学期` → `NULL`；`异动前/后校区` → `NULL`；`异动生效时间` → `CAST(effective_date AS DATETIME)`（若原列为 `DATE`，统一 cast）。
2. **子视图 B**：`xg_student_class_change`
  - `LEFT JOIN xg_class_msg` 原班 `oc`：`oc.id = original_class_id`  
  - `LEFT JOIN xg_class_msg` 新班 `nc`：`nc.id = new_class_id`  
  - 前/后年级、学制、班主任工号（经 `sys_user`）等从 `oc`/`nc` 补全。  
  - `异动生效学期` → `NULL`；校区 → `NULL`；`异动生效时间` → `effective_time`。
3. **总视图**：`UNION ALL` A、B，列顺序与类型完全一致。

### 5.3 过滤条件（建议）

- 仅同步已办结数据：学籍 `process_status = 1`；换班级 `status = '1'`。  
- 排除逻辑删除：`deleted = 0`（各表按项目规范）。

### 5.4 交付物

- **视图 DDL 脚本**：[`vw_jw_student_change_export.sql`](./vw_jw_student_change_export.sql)（视图名 `vw_jw_student_change_export`，含验证用 `数据来源` / `来源记录id` 两列，对接教务时可删列重建视图）。  
- 可选：`COMMENT ON` 或建表注释说明每列口径。

---

## 6. 风险与后续增强（摘要）


| 项             | 说明                                                                            |
| ------------- | ----------------------------------------------------------------------------- |
| 纯学籍异动的「异动前」组织 | 视图优先读 `xg_student_msg_his`（处理脚本落库快照），无快照时回退 `xg_student_msg`；同一学生多次异动时 his 仅保留首次快照，需长期可考虑落库冗余字段。 |
| 校区            | 当前方案恒空；将来可在 `xg_class_msg` 或学院维度补 `campus_id/name` 后改视图即可。                    |
| 异动生效学期        | 当前恒空；将来有校历维表后，可只改视图计算逻辑，不必改业务表。                                               |
| 改名            | 无流水则「新名字」保持空；需要时增加改名记录表或审计。                                                   |
| 班主任工号         | 确认 `sys_user.user_no` 与教务工号一致；否则增加教师工号字段或映射表。                                 |


---

## 7. 实施步骤建议

1. 与教务确认：**空学期、空校区**是否接口可接受；**异动后**字段在退学等场景下是否允许与「异动前」相同或填空。
2. 定稿 **教务异动类型码** 与本地 `change_type`/换班级 的映射。
3. 编写并评审 **视图 DDL**（含 `UNION ALL`、JOIN、`NULL` 列、时间统一、已处理过滤）。
4. 在测试库用真实数据抽样校验：换班级、仅休学、复学并换班级、毕业等各一条。
5. 对接方式落地：教务定时拉视图 / 中间库同步 / 应用定时任务读视图写入对方库。

---

## 8. 文档维护

- API 行为未变时，**可不修改** `docs/开发文档/API/学生学籍异动与换班级API.md`。  
- 视图 DDL 落地后，在本文件「修订记录」中追加日期与变更说明。


| 日期         | 修订内容                                                         |
| ---------- | ------------------------------------------------------------ |
| 2026-05-07 | 初稿：汇聚视图方案；校区、生效学期为空；生效时间取自 `effective_date`/`effective_time` |
| 2026-05-07 | 补充：`vw_jw_student_change_export.sql` 可执行 DDL |
| 2026-06-22 | API 改为按「异动生效时间」自然年筛选；视图输出教务中文异动类型；学籍异动「前」优先读 `xg_student_msg_his` |
| 2026-06-22 | 毕业（`BI_YE`）记录不同步给教务，视图 WHERE 排除 |