明序教务管理系统

面向普通高校的教务管理系统。后端使用 ASP.NET Core 10、EF Core 10，前端使用 Vue 3、TypeScript 和 Element Plus。

当前已实现系统登录与角色权限、基础数据、用户管理、教师档案、学生档案、课程库、培养方案、教学任务、排课课表、学生选课、成绩管理、考试考场、学籍异动、毕业审核、学位授予、毕业离校和首页统计。人员及课程列表支持组合筛选、服务端分页和完整增删改查；培养方案支持课程模块、专业年级版本、复制新版本、发布与旧版本归档，已发布版本可继续维护名称、学分说明和课程结构，适用专业、入学年级及版本号保持锁定；教学任务支持学期课程开设、多教师、合班、容量校验、发布与结课，公共课由校级教务负责、专业必修/专业选修/实践课下放课程所属学院管理，并支持教师按学期申报授课科目、学院审核授课资格、公共课按若干行政班合并教学班，以及在审核通过的教师池中随机均衡分配后批量生成草稿；排课支持学期作息维护、单双周与周次节次、课程可用时间、校区/教学楼/指定教室约束、不占用教室课程、教室容量、教师/行政班/教室冲突校验、自动生成、手工微调和版本化发布；选课支持批次时间窗、投放范围、容量与学分上限、重复课程与课表冲突校验、退课截止时间和实时教学班名单；成绩管理支持分项比例、批量录入、特殊考试状态、自动总评与绩点、教师提交、学院审核、校级发布和学生成绩单；考试管理支持考试计划、场次、考场容量、监考教师、考生名单以及考场/监考/学生时间冲突校验；学籍异动支持休学、复学、退学申请，辅导员、学院、学校三级顺序审核，学生撤回，以及最终审批后自动同步学籍状态；毕业审核按入学年级匹配已发布培养方案，以正式成绩计算总学分、必修通过和未解决不及格课程，支持学院范围查看、人工复核、校级锁定发布和学生结果查询；学位授予以已发布毕业资格为来源，按正式成绩加权平均绩点生成规则结论，支持学院人工复核、校级发布锁定和学生结果查询；毕业离校支持自定义事项与责任部门，按校级、学院、辅导员角色分工办理，强制数据范围校验，学生进度查询，以及必办事项全部完成后的批次锁定。

课程库支持下载标准模板后批量导入 .xlsx，按课程编码新增或更新，并在整批校验失败时不写入任何课程；授课资格既支持教师申报后审核，也支持学院在本院教师范围内直接分配；学生可在“我的培养方案”中查看本人适用的已发布方案，并按已完成、在读、重修中、未通过、待完成和未修读状态核对课程与学分进度。

权限采用后端强制校验的角色与数据范围模型。多角色账号按 All > College > Class > Self 取最高数据范围：校级角色可访问全校数据，院系管理员限定本学院，辅导员通过稳定的账号 ID 绑定所带行政班，教师和学生限定本人及当前教学关系；前端菜单和路由限制仅作为交互辅助，不替代 API 授权。

人员档案与登录账号分开维护。新增或 Excel 导入学生、教师档案时不会自动创建账号，也不会在修改档案时同步账号。学生首次使用时可以在登录页进入“自助激活”，填写姓名、学号、学院、专业、年级和行政班；全部匹配在籍档案后自行设置密码，系统才创建 Identity 登录账号并关联学生角色。AspNetUsers 作为 ASP.NET Core Identity 的内部安全存储，负责密码哈希、登录锁定、角色和令牌。

本地开发：热更新模式

本地开发固定使用 SQLite。首次启动会自动创建空的 src/Jiaowu.Api/data/jiaowu-dev.sqlite，只初始化系统角色和课程分类，不再写入 演示组织、人员、课程、业务记录或内置测试账号。

$env:SeedAdmin__UserName = 'admin'
$env:SeedAdmin__Password = '请替换为本机开发密码'
$env:SeedAdmin__DisplayName = '系统管理员'
dotnet run --project src/Jiaowu.Api

另开一个终端：

Set-Location web
npm install
npm run dev

访问 http://localhost:5173。首次创建管理员后可以清除三个 SeedAdmin__* 环境变量；后续账号和基础数据均通过管理界面维护。

本地开发：单服务模式

不需要前端热更新时，可以先把 Vue 编译进 API 的 wwwroot：

npm --prefix web run build
dotnet run --project src/Jiaowu.Api

访问 http://localhost:5255。/api 和静态页面由同一个 ASP.NET Core 服务提供，/base-data 等前端路由刷新时也会回退到 index.html。

MySQL 8.4 生产部署

非 Development 环境只允许使用 MySQL。构建发布包与数据库配置相互独立： dotnet publish 不需要数据库连接串、JWT 密钥或生产环境变量，也不会把这些配置写入发布包。 它会自动执行 npm ci 和 npm run build，并将 Vue 静态文件放入发布目录的 wwwroot：

dotnet publish src/Jiaowu.Api -c Release -o .artifacts/publish

如需在特殊流水线中跳过自动前端构建，可传入 -p:BuildFrontendOnPublish=false。

将发布包复制到目标服务器后，再通过 Windows 服务、容器编排平台或密钥管理系统， 为 应用运行进程 注入配置。下面仅演示在当前 PowerShell 会话中配置；变量只对该 会话及其启动的子进程生效：

$env:ASPNETCORE_ENVIRONMENT = 'Production'
$env:Database__Provider = 'MySql'
$env:Jwt__Key = '至少32字节的随机生产密钥'
$env:AllowedHosts = 'jiaowu.example.edu.cn'

这些值由 Jiaowu.Api 在每次启动时读取。不要把真实连接串或密钥写入仓库中的 appsettings*.json，证书路径也必须是目标服务器上的实际路径。

数据库应明确使用 utf8mb4；MySQL 8.4 的默认排序规则为 utf8mb4_0900_ai_ci。新建数据库时可执行：

CREATE DATABASE `jiaowu`
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_0900_ai_ci;

首次部署或版本升级时，先在目标服务器设置具备 DDL 权限的迁移账号连接串，并单独 执行迁移：

$env:ConnectionStrings__MySql = 'Server=db.example.edu.cn;Port=3306;Database=jiaowu;User=MIGRATION_USER;Password=MIGRATION_PASSWORD;SslMode=VerifyFull;SslCa=C:\certs\mysql-ca.pem;'
& '.artifacts\publish\Jiaowu.Api.exe' --migrate-only

迁移成功后，将连接串替换为仅具备应用所需 DML 权限的运行账号，再启动服务：

$env:ConnectionStrings__MySql = 'Server=db.example.edu.cn;Port=3306;Database=jiaowu;User=APP_USER;Password=APP_PASSWORD;SslMode=VerifyFull;SslCa=C:\certs\mysql-ca.pem;'
& '.artifacts\publish\Jiaowu.Api.exe'

Database:ApplyMigrationsOnStartup 默认关闭。普通启动会检查待执行迁移并在架构落后时 直接失败，避免多实例同时执行 DDL。只有明确接受启动期 DDL 风险的单实例部署才应将 Database__ApplyMigrationsOnStartup 设为 true。

生产环境不会创建默认管理员。首次部署可以临时配置 SeedAdmin__UserName、SeedAdmin__Password 和 SeedAdmin__DisplayName， 账号创建后立即移除这些配置。

生产数据库使用 MySQL 专用 EF Core 迁移。部署前先恢复仓库工具并检查迁移：

dotnet tool restore
dotnet ef migrations list --no-connect --project src/Jiaowu.Api --startup-project src/Jiaowu.Api

不要使用当前提供程序生成的 dotnet ef migrations script --idempotent 作为 MySQL 部署脚本；其条件块不是 MySQL 8.4 可直接执行的语法。应使用上述 --migrate-only 入口，或在明确知道目标迁移状态时生成非幂等脚本并先做备份。 MySQL 的 DDL 会隐式提交，迁移不能依赖外层事务整体回滚。

SQLite 只用于本地开发：新库通过 EnsureCreated 建立，已有开发库通过轻量、版本化的 本地升级脚本补齐结构，不需要手动删除数据文件。SQLite 文件不能用于生产。

服务探针：

• /health/live：只检查进程存活。
• /health、/health/ready：实际检查数据库连接，失败时返回 HTTP 503。

验证

dotnet test Jiaowu.slnx
npm --prefix web run build