252 lines
11 KiB
Markdown
252 lines
11 KiB
Markdown
# 学生管理系统 — 架构设计文档
|
||
|
||
## 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/<resource>`
|
||
- 软删除代替硬删除，返回语义一致的响应码
|
||
|
||
### 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. **事件驱动**：学生/成绩变更时发布事件，供下游系统消费
|