1. 立项原因
中小型高中的教师、学生、班级和账号信息通常分散在 Excel、纸质表格和多个系统中，存在重复录入、统计口径不一致、转班/离校状态不同步等问题；同时校长、教务主任、教师、学生四类角色对数据的可见范围不同，仅靠前端隐藏菜单无法防止越权访问。项目立项旨在提供一套统一的后端管理平台，把教师/学生档案、班级归属、班主任关系和登录账号纳入同一套数据模型，并通过 JWT 鉴权与按角色、年级的行级数据范围控制，解决信息孤岛、权限越界和数据一致性问题。
2. 行业场景与业务背景
面向 3 个年级、每级 5 个班、每班容量 30 人的高中教务管理场景。校长负责全局教师/学生/账号管理及教务主任任命；教务主任和教师仅能管理本年级数据；学生只能查看和修改本人档案。业务覆盖教师入职与学生入学建档、分班与转班、离校与复学、班级容量校验、班主任任命/解除、班级花名册与在读/离校/性别统计，以及账号开通、同步、停用和密码重置。系统可作为民办高中、中职院校或培训机构的教务管理后端，也适合作为多角色、强权限约束的 SaaS 教务产品基础服务。
1. 项目有哪些具体的功能模块
系统按业务域划分为七个模块：认证与权限、教师管理、学生管理、年级管理、班级与班主任管理、账号管理、基础支撑。
认证与权限：登录、当前用户查询、修改密码、JWT 无状态鉴权、401/403 统一响应。
教师管理：教师档案增删改查、分页与条件查询、逻辑删除、本人档案自助维护。
学生管理：学生档案增删改查、分页查询、逻辑删除、按班级分班、转班、离校与复学、本人档案自助维护。
年级管理：只读返回高一、高二、高三三个年级。
班级与班主任管理：班级列表与详情、花名册与统计、班主任任命与解除、班级范围校验。
账号管理：校长初始化、教师/学生自动开号、批量回填、重置密码、停用账号、角色调整、账号与档案同步。
基础支撑：统一响应与错误码、全局异常处理、分页、逻辑删除、Flyway 迁移、Swagger 接口文档。
2. 项目的主要功能描述
系统面向校长、教务主任、教师、学生四类角色提供差异化能力。校长可管理全部教师、学生、班级和账号，并任命教务主任与班主任；教务主任可管理本年级教师、查看本年级班级并任命/解除班主任；教师可管理本年级学生、查看本年级班级和花名册，并维护本人档案；学生仅能查看和修改本人档案。
教师/学生的新增、修改、删除、分班、转班、离校、复学等写操作，与账号开通、同步、停用处于同一事务，工号或学号冲突、账号冲突、班级满员会返回明确错误码并整体回滚。班级模块提供班主任唯一性校验、教师异动保护（班主任调年级、停用、删除前须先解除或转交）、花名册的在读/离校/性别统计，以及 30 人容量的并发安全校验。权限采用方法级角色校验与行级数据范围双重控制，确保不同角色只能访问授权范围内的数据。
1. 我负责的具体任务
我负责后端从设计到落地：搭建 Common 与 SchoolManager 多模块架构，设计统一响应、分页、错误码和全局异常；设计教师、学生、账号、年级、班级数据模型及 Flyway V1–V5 迁移；实现 JWT 登录、401/403 处理、教师/学生档案增删改查、分页、逻辑删除、自助维护和自动开号；实现班级查询、班主任任命/解除、花名册与容量校验；编写 212 个测试并维护 Swagger 与 README。
2. 技术栈、架构与实现亮点/难点
技术栈：Java 21、Spring Boot 3.5.16、Spring Security、jjwt、MyBatis-Plus 3.5.17、MySQL 8、Flyway、springdoc、Maven 多模块、JUnit 5 + Mockito + MockMvc。
架构：模块化单体，Common 提供统一 Web 契约，SchoolManager 为唯一启动应用；业务按 controller→service→mapper 分层，DTO/VO 隔离入参出参，BaseEntity 统一逻辑删除与审计字段，Flyway 管理表结构演进。
亮点：双层权限。@PreAuthorize 控制角色，DataScopeService 按角色和年级做行级过滤；JWT 每次请求重查账号，角色与状态变更即时生效；高优先级异常处理器保证方法级拒绝返回 403 而非 500。
难点：并发一致性。班主任任命按“班级行→教师行”加锁，教师异动先锁教师行，唯一索引兜底一人一班；学生分班/转班/复学按“学生行→班级行”加锁，容量计数在加锁后执行，避免 REPEATABLE READ 旧快照超员；真实 MySQL 30/31 并发边界验证通过。
评论