# 学生管理系统 — 架构设计文档 ## 1. 系统概述 学生管理系统（SMS）是一个面向教育培训机构的后台管理系统，提供学生信息管理、成绩管理、就业管理、班级管理及教师管理五大核心功能，以及统计分析大盘接口。 - **项目定位**：教培行业轻量级 SaaS 后台 - **技术栈**：FastAPI + SQLAlchemy + PyMySQL + SQLite（开发）/ MySQL（生产） - **目标用户**：教务管理员、班主任、顾问老师 --- ## 2. 总体架构 ### 2.1 架构分层 ``` ┌─────────────────────────────────────────────────┐ │ Client / Frontend │ │ （Vue3 / 静态页面 / Postman） │ └────────────────────────┬────────────────────────┘ │ HTTP/REST ┌────────────────────────▼────────────────────────┐ │ API Gateway / Load Balancer │ │ （Nginx / Caddy，可选） │ └────────────────────────┬────────────────────────┘ │ ┌────────────────────────▼────────────────────────┐ │ FastAPI 应用层 │ │ ┌─────────────┐ ┌──────────────┐ ┌─────────┐ │ │ │ Routers │ │ Middlewares │ │ Services│ │ │ │ (REST API) │ │ (CORS/Auth) │ │ (待扩展) │ │ │ └──────┬──────┘ └──────────────┘ └────┬────┘ │ │ │ │ │ │ ┌──────▼──────┐ ┌────────▼────┐ │ │ │ Schemas │ │ Validators │ │ │ │(Pydantic) │ │ (业务校验) │ │ │ └──────┬──────┘ └─────────────┘ │ │ │ │ │ ┌──────▼──────┐ │ │ │ Services │ ◄──── 业务逻辑（待拆分） │ │ └──────┬──────┘ │ └─────────┼────────────────────────────────────────┘ │ SQLAlchemy ORM ┌─────────▼────────────────────────────────────────┐ │ 数据访问层 │ │ ┌──────────────┐ ┌──────────────────────────┐ │ │ │ Repository │ │ BaseQuery / Mixins │ │ │ │ (可选未来) │ │ (软删除、分页统一处理) │ │ │ └──────────────┘ └──────────────────────────┘ │ └─────────┬────────────────────────────────────────┘ │ ┌─────────▼────────────────────────────────────────┐ │ 数据库层 │ │ ┌──────────────┐ ┌──────────────────────────┐ │ │ │ MySQL │ │ SQLite（开发环境） │ │ │ │ (生产) │ │ │ │ │ └──────────────┘ └──────────────────────────┘ │ └──────────────────────────────────────────────────┘ ``` ### 2.2 架构演进路线 | 阶段 | 架构形态 | 说明 | |------|----------|------| | V1.0（当前）| 单体架构 | FastAPI 单体，SQLAlchemy ORM，sqlite/MySQL 双适配 | | V2.0（规划）| 模块拆分 | 学生、成绩、就业等模块独立 Service 层，便于测试和复用 | | V3.0（规划）| 微服务化 | 按业务域拆分独立服务，引入消息队列、服务注册发现 | --- ## 3. 模块设计 ### 3.1 模块划分 ``` student_manage_system/ ├── main.py # 应用入口，lifespan 管理 ├── database.py # DB 连接与 Session 工厂 ├── models.py # SQLAlchemy ORM 模型 ├── schemas.py # Pydantic 请求/响应 Schema ├── seed.py # 数据初始化脚本 ├── routers/ # API 路由层 │ ├── __init__.py │ ├── teachers.py # 教师管理模块 │ ├── classes.py # 班级管理模块 │ ├── students.py # 学生管理模块 │ ├── scores.py # 成绩管理模块 │ ├── employment.py # 就业管理模块 │ └── stats.py # 统计分析模块 ├── static/ # 静态前端 │ └── index.html ├── docs/ # 项目文档 ├── pyproject.toml # 项目依赖配置 └── uv.lock # 依赖锁定文件 ``` ### 3.2 模块职责矩阵 | 模块 | 路径 | 核心职责 | HTTP 前缀 | |------|------|----------|-----------| | 教师管理 | routers/teachers.py | 教师 CRUD | /api/teachers | | 班级管理 | routers/classes.py | 班级 CRUD，关联教师分配 | /api/classes | | 学生管理 | routers/students.py | 学生 CRUD，关联班级/顾问 | /api/students | | 成绩管理 | routers/scores.py | 成绩录入、修改、软删除 | /api/scores | | 就业管理 | routers/employment.py | 就业信息 CRUD | /api/employments | | 统计分析 | routers/stats.py | 班级/成绩/就业维度统计 | /api/stats | --- ## 4. 技术选型说明 ### 4.1 后端框架：FastAPI - 原生异步支持，适合 IO 密集型场景 - 自动 OpenAPI 文档生成（`/docs`、`/redoc`） - Pydantic 内置数据校验，减少样板代码 - 依赖注入（`Depends`）支持 Session 管理和鉴权扩展 ### 4.2 ORM：SQLAlchemy 2.0 - 声明式模型，支持 `Mapped` / `Column` 新风格 - 与 PyMySQL 驱动无缝集成 - 软删除模式通过基类 `BaseModel` 统一实现 ### 4.3 数据库驱动 | 环境 | 驱动 | 连接方式 | |------|------|----------| | 开发 | pymysql（SQLite 直连）| 文件数据库，无需部署 | | 生产 | pymysql | MySQL 8.0+ / PostgreSQL 14+ | ### 4.4 包管理：uv - 比 pip 快 10-100x 的 Python 包管理器 - 统一的锁文件管理（`uv.lock`） - `uv sync` 确保多环境一致 --- ## 5. 接口设计规范 ### 5.1 RESTful 风格 - 资源使用名词复数：`/api/students` - 统一路径前缀：`/api/` - 软删除代替硬删除，返回语义一致的响应码 ### 5.2 统一响应格式 | 操作 | HTTP 方法 | 成功状态码 | 失败典型状态码 | |------|-----------|------------|----------------| | 列表查询 | GET | 200 | 400（参数错误） | | 详情查询 | GET /{id} | 200 | 404（不存在） | | 创建 | POST | 201 | 400（重复/校验失败） | | 更新 | PUT /{id} | 200 | 404 / 400 | | 删除 | DELETE /{id} | 200 | 404 | ### 5.3 分页规范 所有列表接口统一支持： - `skip`（偏移量，默认 0） - `limit`（页大小，默认 100） --- ## 6. 中间件设计 ### 6.1 当前中间件 ```python # CORS 中间件（开发环境全放行，生产需收紧） CORSMiddleware( allow_origins=["*"], allow_credentials=True, allow_methods=["*"], allow_headers=["*"], ) ``` ### 6.2 待补充中间件（V2.0 规划） - **认证鉴权中间件**：基于 OAuth2 + JWT 的请求拦截 - **请求日志中间件**：统一记录请求耗时、状态码、IP - **限流中间件**：防止单接口高频调用 --- ## 7. 部署架构 ### 7.1 开发环境 ``` 本地开发机 ├── uv run uvicorn main:app --reload ├── SQLite（本地文件 sms.db） └── 浏览器访问 http://localhost:8000 ``` ### 7.2 生产环境（推荐） ``` ┌─────────────┐ │ Nginx │ ← 反向代理 + HTTPS 终止 │ (port 443) │ └──────┬──────┘ │ ┌──────────────┼──────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ FastAPI │ │ FastAPI │ │ FastAPI │ ← 水平扩展（多实例） │ :8000 │ │ :8001 │ │ :8002 │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ └─────────────┼─────────────┘ ▼ ┌────────────────┐ │ MySQL 集群 │ ← 主从复制 / 云数据库 │ (port 3306) │ └────────────────┘ ``` ### 7.3 容器化部署（Docker） ```dockerfile FROM python:3.13-slim WORKDIR /app COPY pyproject.toml uv.lock ./ RUN uv sync --frozen --no-dev COPY . . EXPOSE 8000 CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"] ``` --- ## 8. 安全设计 | 层次 | 措施 | 当前状态 | |------|------|----------| | 传输层 | HTTPS（生产） | 规划中 | | 应用层 | Pydantic 数据校验 | ✅ 已实现 | | 应用层 | 软删除防止数据误删 | ✅ 已实现 | | 认证层 | JWT Token | 规划中 | | 授权层 | RBAC 角色权限 | 规划中 | | 注入防护 | SQLAlchemy 参数化查询 | ✅ 已实现 | --- ## 9. 可扩展性设计 ### 9.1 当前已预留扩展点 - `lifespan` 钩子：启动时自动建表和种子数据，后续可扩展为迁移工具（Alembic） - 路由模块化：各业务模块独立文件，便于拆分微服务 - `BaseModel` 基类：所有模型共享审计字段，后续可加分布式 ID ### 9.2 未来演进方向 1. **多租户支持**：在 `BaseModel` 中加入 `tenant_id` 字段 2. **缓存层**：Redis 缓存统计结果，减轻数据库压力 3. **异步任务**：Celery / APScheduler 处理离线统计和报告生成 4. **事件驱动**：学生/成绩变更时发布事件，供下游系统消费