Sherif-Osama/School-Management-System
GitHub: Sherif-Osama/School-Management-System
基于 ASP.NET Core 分层架构构建的学校管理 REST API，通过业务逻辑层强制执行排课冲突检测、学年验证、成绩完整性等真实领域规则。
Stars: 1 | Forks: 0
# 学校管理系统 — REST API
这是一个分层的 ASP.NET Core Web API，用于管理学校的日常运营：学生、教师、家长、班级、科目、日程、考试、成绩和考勤 —— 基于原生 ADO.NET 和 SQL Server 存储过程构建，采用了清晰的 **DAL → BLL → API** 架构。
## 目录
- [概述](#overview)
- [架构](#architecture)
- [功能](#features)
- [技术栈](#tech-stack)
- [项目结构](#project-structure)
- [快速开始](#getting-started)
- [API 文档](#api-documentation)
- [关键设计决策](#key-design-decisions)
- [已知局限性](#known-limitations)
- [路线图](#roadmap)
- [许可证](#license)
## 概述
该系统对整个学校领域进行了建模：人员可以是学生、教师或家长；学生被编入班级；班级拥有由教师在教室中教授的预定科目；考试根据班级-科目创建，并据此对学生进行评分；考勤则按学生按天进行追踪。
该系统并没有仅仅作为数据库的一个简单的 CRUD 包装器，而是由 **业务逻辑层 (BLL)** 强制执行真实的领域规则 —— 例如，一个班级不能被安排在当时已被占用的教室里，学生不能被分配高于考试总分的成绩，并且考试日期必须在其班级的学年内。
## 架构
该解决方案遵循严格的 **3+1 分层架构**，每一层仅依赖于其正下方的层：
```
flowchart TD
A[School.API
Controllers, Middleware, Swagger] --> B[School.BLL
Business Rules & Validation] B --> C[School.DAL
ADO.NET + Stored Procedures] C --> D[(SQL Server)] A -.-> E[School.DTO
Shared Data Contracts] B -.-> E C -.-> E ``` | 层级 | 职责 | |---|---| | **School.API** | HTTP 入口点。轻量级控制器，将请求映射到 BLL 调用、全局异常处理中间件、Swagger/OpenAPI 文档。 | | **School.BLL** | 所有业务规则：输入验证、存在性检查、唯一性检查、跨实体一致性规则、密码哈希。仅依赖于 DAL *接口*。 | | **School.DAL** | 通过 `Microsoft.Data.SqlClient` 进行数据访问，专门调用 SQL Server 存储过程（无原生内联 SQL，无 ORM）。仅依赖于 DTO。 | | **School.DTO** | 所有层共享的纯数据契约 —— 无逻辑，无依赖。 | 每个 DAL 和 BLL 类都通过接口公开，并通过 `IServiceCollection` 扩展方法（`AddDAL()`, `AddBLL()`）进行注册，因此整个依赖关系图都是通过构造函数注入串联起来的，并且每一层都可以被独立模拟/替换。 ### 横切关注点 单一的 `ExceptionHandlingMiddleware` 将领域异常转换为一致的 HTTP 响应，因此控制器中永远不会包含 try/catch 块： | 异常 | HTTP 状态码 | |---|---| | `ArgumentException` / `ArgumentOutOfRangeException` | 400 Bad Request | | `KeyNotFoundException` | 404 Not Found | | `InvalidOperationException` | 409 Conflict | | `UnauthorizedAccessException` | 401 Unauthorized | | `SqlException` (外键冲突，错误代码 547) | 409 Conflict | | 其他任何异常 | 500 Internal Server Error | ## 功能 该 API 暴露了 18 个资源控制器，涵盖整个学校领域： - **人员与身份** — `People`, `Users` (BCrypt 哈希密码，密码修改流程) - **学术结构** — `Grades`, `Classes`, `Subjects`, `ClassSubjects` (教师-科目-班级分配), `Classrooms` - **注册** — `Students`, `StudentStatuses`, `Parents`, `StudentParents` - **人员配备** — `Teachers`, `TeacherSubjects` - **排课** — `Schedules`，具有针对教室、教师和班级双重预订的自动冲突检测 - **评估** — `ExamTypes`, `Exams`, `StudentGrades` - **考勤** — `Attendances`, `AttendanceStatuses` ### 在 BLL 中强制执行的重要业务规则 - **排课冲突**：教室、教师或班级不能在重叠的日期/时间段被重复预订 (`ScheduleService`)。 - **学年边界**：考试日期和考勤日期必须落在班级的学年（9月1日 → 8月31日）内，且仅适用于活跃班级 (`ExamService`, `AttendanceService`, `AcademicYearHelper`)。 - **班级容量**：学生不能被录入已达到最大容量的班级 (`StudentService`)。 - **评分完整性**：成绩不能超过考试的总分，当学生被标记为缺勤时成绩必须为 `0`，且每个学生每次考试只允许有一个成绩 (`StudentGradeService`)。 - **参照一致性**：在任何写入操作*之前*，都会验证每个外键关系（人员 ↔ 学生，人员 ↔ 用户，学生 ↔ 班级等）是否存在，并且一对一关系（例如，每人一个用户账户）会被严格执行。 - **密码安全**：密码在存储前使用 BCrypt 进行哈希处理；明文密码绝不会接触到数据库。 ## 技术栈 - **.NET 8** / ASP.NET Core Web API - **Microsoft.Data.SqlClient** — 直接的 ADO.NET 访问，无 ORM - **SQL Server** — 所有数据访问均使用存储过程（无内联/动态 SQL） - **BCrypt.Net** — 密码哈希 - **Swashbuckle (Swagger/OpenAPI)** — 交互式 API 文档 - **依赖注入** — 内置的 ASP.NET Core 容器，分层级作用的 `AddDAL()` / `AddBLL()` 扩展 ## 项目结构 ``` SchoolManagement/ ├── SchoolManagement/ # School.API — Controllers, Middleware, Program.cs │ ├── Controllers/ │ ├── Middlewares/ │ └── Program.cs ├── School.BLL/ # Business logic, validation, interfaces │ ├── Interfaces/ │ ├── Common/ # PasswordHasher │ ├── Helpers/ # AcademicYearHelper │ └── *Service.cs ├── School.DAL/ # Data access via stored procedures │ ├── Interfaces/ │ ├── Common/ # BaseData (connection + command factory) │ └── *Data.cs ├── School.DTO/ # Shared request/response contracts │ └── */ # grouped by domain (StudentsDTOs, ExamDTOs, ...) └── Database/ # SQL Server database backup ``` ## 快速开始 ### 前置条件 - [.NET 8 SDK](https://dotnet.microsoft.com/download) - SQL Server (LocalDB、Express 或完整版) - 用于恢复 `.bck` 数据库备份的工具 (SSMS 或 `sqlcmd`) ### 设置 1. **克隆仓库** git clone https://github.com/Sherif-Osama/School-Management-System.git cd SchoolManagement 2. **还原数据库** 将 `Database/SchoolDB.bck` 还原到您本地的 SQL Server 实例中（这包含了 DAL 使用的所有表和存储过程）。 3. **配置连接字符串** 在 `SchoolManagement/appsettings.json`（或 `appsettings.Development.json`）中，设置： { "ConnectionStrings": { "DefaultConnection": "Server=YOUR_SERVER;Database=SchoolDB;Trusted_Connection=True;TrustServerCertificate=True;" } } 4. **运行 API** cd SchoolManagement dotnet restore dotnet run 5. **打开 Swagger UI** 导航到 `https://localhost:/swagger` 以交互方式探索和测试所有 endpoint。
## API 文档
完整的交互式文档通过 Swagger/OpenAPI 自动生成，并在 Development 环境中的 `/swagger` 路径下提供服务。每个 endpoint 都通过 `[ProducesResponseType]` 记录其预期的成功和错误状态码。
## 关键设计决策
- **使用存储过程而非 ORM**：每个查询和命令都通过命名的 SQL Server 存储过程执行，而不是内联 SQL 或 EF Core，从而保持数据访问的明确性、可审计性，并可直接在数据库中进行调优。
- **以 DTO 作为共享契约**：相同的 DTO 类型流经 DAL → BLL → API，避免了重复的映射层，同时为本项目的范围保持了刻意简化的领域模型。
- **验证逻辑位于 BLL 中，而不是数据库或控制器中**：每一条业务规则（存在性、唯一性、范围、跨实体一致性）都集中在服务类中，独立于 API 层的实现方式。
- **无处不在的接口**：DAL 和 BLL 类都通过接口公开，使得每一层都可以被独立模拟和单元测试（参见[路线图](#roadmap)）。
## 已知局限性
该项目正在开发中。在此特意记录，而不是将其隐藏：
- **目前还没有身份验证/授权。** `Users` 带有哈希密码，但没有登录 endpoint，没有签发 token，也没有在任何控制器上强制执行 `[Authorize]` —— 目前每个 endpoint 都是开放的。这是下方路线图的首要任务。
- **唯一性/可用性检查可能存在竞态条件。** 诸如排课冲突检测、考试重复和班级容量等规则，在 BLL 中是以“先检查，后写入”的顺序实现的（例如 `EnsureClassroomAvailableAsync` → `AddScheduleAsync`）。在并发请求下，两个调用都可能在其中任何一个执行写入之前通过了检查，从而导致重复预订。这需要通过数据库级别的约束（唯一索引 / `CHECK`）、具有适当隔离级别的事务，或应用级别的锁来解决。
- **没有自动化测试。** 分层、基于接口的设计在设计时考虑了可测试性，但尚未编写单元/集成测试。
- **没有日志记录。** 中间件或服务中没有结构化日志记录（例如 `ILogger`/Serilog），这使得生产环境中的调试更加困难。
- **存储过程仅作为二进制备份** (`Database/SchoolDB.bck`) 进行版本控制，而不是作为单独的 `.sql` 脚本，这使得它们难以审查或对比差异。
## 路线图
- [ ] **身份验证与授权** — 添加一个签发 JWT 的登录 endpoint，基于角色的 `[Authorize]` 策略（管理员 / 教师 / 家长），以及 refresh token。
- [ ] **修复竞态条件** — 在数据库级别强制执行排课、容量和唯一性规则（唯一约束 / 具有适当隔离级别的事务），以便它们在并发负载下依然有效，而不仅仅是在应用程序代码中。
- [ ] **自动化测试** — 针对 BLL 的单元测试（业务规则是最高价值的目标）以及针对 API 的集成测试。
- [ ] **结构化日志记录** — 在中间件和服务中集成 `ILogger` / Serilog。
- [ ] **版本控制的 SQL** — 将存储过程提取为 `.sql` 迁移脚本并提交到仓库中。
- [ ] **通过 DataAnnotations 进行输入验证** — 在 DTO 上进行验证，以补充 BLL 级别的检查，并在 API 边界处实现自动的模型状态验证。
- [ ] **CI pipeline** — 在每次 push/PR 时进行构建和测试自动化。
## 许可证
本项目出于教育和作品集目的开放。
Controllers, Middleware, Swagger] --> B[School.BLL
Business Rules & Validation] B --> C[School.DAL
ADO.NET + Stored Procedures] C --> D[(SQL Server)] A -.-> E[School.DTO
Shared Data Contracts] B -.-> E C -.-> E ``` | 层级 | 职责 | |---|---| | **School.API** | HTTP 入口点。轻量级控制器，将请求映射到 BLL 调用、全局异常处理中间件、Swagger/OpenAPI 文档。 | | **School.BLL** | 所有业务规则：输入验证、存在性检查、唯一性检查、跨实体一致性规则、密码哈希。仅依赖于 DAL *接口*。 | | **School.DAL** | 通过 `Microsoft.Data.SqlClient` 进行数据访问，专门调用 SQL Server 存储过程（无原生内联 SQL，无 ORM）。仅依赖于 DTO。 | | **School.DTO** | 所有层共享的纯数据契约 —— 无逻辑，无依赖。 | 每个 DAL 和 BLL 类都通过接口公开，并通过 `IServiceCollection` 扩展方法（`AddDAL()`, `AddBLL()`）进行注册，因此整个依赖关系图都是通过构造函数注入串联起来的，并且每一层都可以被独立模拟/替换。 ### 横切关注点 单一的 `ExceptionHandlingMiddleware` 将领域异常转换为一致的 HTTP 响应，因此控制器中永远不会包含 try/catch 块： | 异常 | HTTP 状态码 | |---|---| | `ArgumentException` / `ArgumentOutOfRangeException` | 400 Bad Request | | `KeyNotFoundException` | 404 Not Found | | `InvalidOperationException` | 409 Conflict | | `UnauthorizedAccessException` | 401 Unauthorized | | `SqlException` (外键冲突，错误代码 547) | 409 Conflict | | 其他任何异常 | 500 Internal Server Error | ## 功能 该 API 暴露了 18 个资源控制器，涵盖整个学校领域： - **人员与身份** — `People`, `Users` (BCrypt 哈希密码，密码修改流程) - **学术结构** — `Grades`, `Classes`, `Subjects`, `ClassSubjects` (教师-科目-班级分配), `Classrooms` - **注册** — `Students`, `StudentStatuses`, `Parents`, `StudentParents` - **人员配备** — `Teachers`, `TeacherSubjects` - **排课** — `Schedules`，具有针对教室、教师和班级双重预订的自动冲突检测 - **评估** — `ExamTypes`, `Exams`, `StudentGrades` - **考勤** — `Attendances`, `AttendanceStatuses` ### 在 BLL 中强制执行的重要业务规则 - **排课冲突**：教室、教师或班级不能在重叠的日期/时间段被重复预订 (`ScheduleService`)。 - **学年边界**：考试日期和考勤日期必须落在班级的学年（9月1日 → 8月31日）内，且仅适用于活跃班级 (`ExamService`, `AttendanceService`, `AcademicYearHelper`)。 - **班级容量**：学生不能被录入已达到最大容量的班级 (`StudentService`)。 - **评分完整性**：成绩不能超过考试的总分，当学生被标记为缺勤时成绩必须为 `0`，且每个学生每次考试只允许有一个成绩 (`StudentGradeService`)。 - **参照一致性**：在任何写入操作*之前*，都会验证每个外键关系（人员 ↔ 学生，人员 ↔ 用户，学生 ↔ 班级等）是否存在，并且一对一关系（例如，每人一个用户账户）会被严格执行。 - **密码安全**：密码在存储前使用 BCrypt 进行哈希处理；明文密码绝不会接触到数据库。 ## 技术栈 - **.NET 8** / ASP.NET Core Web API - **Microsoft.Data.SqlClient** — 直接的 ADO.NET 访问，无 ORM - **SQL Server** — 所有数据访问均使用存储过程（无内联/动态 SQL） - **BCrypt.Net** — 密码哈希 - **Swashbuckle (Swagger/OpenAPI)** — 交互式 API 文档 - **依赖注入** — 内置的 ASP.NET Core 容器，分层级作用的 `AddDAL()` / `AddBLL()` 扩展 ## 项目结构 ``` SchoolManagement/ ├── SchoolManagement/ # School.API — Controllers, Middleware, Program.cs │ ├── Controllers/ │ ├── Middlewares/ │ └── Program.cs ├── School.BLL/ # Business logic, validation, interfaces │ ├── Interfaces/ │ ├── Common/ # PasswordHasher │ ├── Helpers/ # AcademicYearHelper │ └── *Service.cs ├── School.DAL/ # Data access via stored procedures │ ├── Interfaces/ │ ├── Common/ # BaseData (connection + command factory) │ └── *Data.cs ├── School.DTO/ # Shared request/response contracts │ └── */ # grouped by domain (StudentsDTOs, ExamDTOs, ...) └── Database/ # SQL Server database backup ``` ## 快速开始 ### 前置条件 - [.NET 8 SDK](https://dotnet.microsoft.com/download) - SQL Server (LocalDB、Express 或完整版) - 用于恢复 `.bck` 数据库备份的工具 (SSMS 或 `sqlcmd`) ### 设置 1. **克隆仓库** git clone https://github.com/Sherif-Osama/School-Management-System.git cd SchoolManagement 2. **还原数据库** 将 `Database/SchoolDB.bck` 还原到您本地的 SQL Server 实例中（这包含了 DAL 使用的所有表和存储过程）。 3. **配置连接字符串** 在 `SchoolManagement/appsettings.json`（或 `appsettings.Development.json`）中，设置： { "ConnectionStrings": { "DefaultConnection": "Server=YOUR_SERVER;Database=SchoolDB;Trusted_Connection=True;TrustServerCertificate=True;" } } 4. **运行 API** cd SchoolManagement dotnet restore dotnet run 5. **打开 Swagger UI** 导航到 `https://localhost:
标签：ADO.NET, ASP.NET Core, SQL Server, Web API开发, 分层架构, 教务管理系统