hzdyjs/docs/设计文档/database/学生学籍异动同步教务系统改造方案.md

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

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，含验证用 数据来源 / 来源记录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 排除
2026-07-03	视图去重：同一学号 + 登记日 + 异动类型仅保留 MIN(id) 一条（按学号分组，非 student_id）