student_manage_system/docs/01-architecture-design.md

学生管理系统 — 架构设计文档

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 当前中间件

# 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）

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. 事件驱动：学生/成绩变更时发布事件，供下游系统消费