# 教育培训管理系统 — 项目总览

> 本文档汇总学生管理系统的架构、业务、数据库及运维部署设计，作为项目开发和维护的参考基准。

## 文档目录

| 序号 | 文档 | 说明 |
|------|------|------|
| 01 | [架构设计文档](./01-architecture-design.md) | 系统分层、模块划分、技术选型、部署架构 |
| 02 | [业务设计文档](./02-business-design.md) | 用户角色、业务流程、实体关系、统计规则 |
| 03 | [数据库设计文档](./03-database-design.md) | ER 图、DDL、索引策略、字典表、归档方案 |
| 04 | [运维部署文档](./04-operations-deployment.md) | 环境配置、Docker、Nginx、监控、备份、故障排查 |
| 05 | [优化文档](./05-optimization-plan.md) | 当前问题清单、优化方案、V2.0 规划、目录结构调整 |

## 核心实体关系速查

```
teachers ──1:N──► classes ──1:N──► students ──1:N──► scores
   │                                    │
   │ 1:N (advisor)                      │ 1:1
   └────────────────────────────────────┴──► employment
```

## 技术栈

- **语言**：Python 3.13
- **框架**：FastAPI 0.141+
- **ORM**：SQLAlchemy 2.0+
- **数据库**：MySQL 8.0（生产）/ SQLite（开发）
- **包管理**：uv
- **前端**：原生 HTML + JS（V2.0 规划迁移至 Vue3）

## API 接口清单

| 模块 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 教师 | GET | /api/teachers/ | 教师列表 |
| 教师 | GET | /api/teachers/{id} | 教师详情 |
| 教师 | POST | /api/teachers/ | 创建教师 |
| 教师 | PUT | /api/teachers/{id} | 更新教师 |
| 教师 | DELETE | /api/teachers/{id} | 软删除教师 |
| 班级 | GET | /api/classes/ | 班级列表 |
| 班级 | GET | /api/classes/{id} | 班级详情 |
| 班级 | POST | /api/classes/ | 创建班级 |
| 班级 | PUT | /api/classes/{id} | 更新班级 |
| 班级 | DELETE | /api/classes/{id} | 软删除班级 |
| 学生 | GET | /api/students/ | 学生列表 |
| 学生 | GET | /api/students/{id} | 学生详情 |
| 学生 | POST | /api/students/ | 创建学生 |
| 学生 | PUT | /api/students/{id} | 更新学生 |
| 学生 | DELETE | /api/students/{id} | 软删除学生 |
| 成绩 | GET | /api/scores/ | 成绩列表 |
| 成绩 | GET | /api/scores/{id} | 成绩详情 |
| 成绩 | POST | /api/scores/ | 录入成绩 |
| 成绩 | PUT | /api/scores/{id} | 更新成绩 |
| 成绩 | DELETE | /api/scores/{id} | 软删除成绩 |
| 就业 | GET | /api/employments/ | 就业列表 |
| 就业 | GET | /api/employments/{id} | 就业详情 |
| 就业 | POST | /api/employments/ | 创建就业记录 |
| 就业 | PUT | /api/employments/{id} | 更新就业记录 |
| 就业 | DELETE | /api/employments/{id} | 软删除就业记录 |
| 统计 | GET | /api/stats/classes | 班级人数统计 |
| 统计 | GET | /api/stats/scores | 成绩统计 |
| 统计 | GET | /api/stats/employment | 就业统计 |

## V1.0 → V2.0 演进计划

| 优先级 | 功能项 | 影响模块 |
|--------|--------|----------|
| P0 | 用户认证（JWT/OAuth2） | main.py, routers/* |
| P0 | 字典表迁移（sex/education/coach_area） | models.py, seed.py |
| P1 | 部门管理模块 | 新增 routers/departments.py |
| P1 | 数据源配置（多环境 DB URL） | database.py |
| P2 | 前端重构（Vue3 + Element Plus） | static/ → frontend/ |
| P2 | 请求日志中间件 | main.py middleware |
| P3 | AI 知识库接入 | routers/ai.py（新模块） |
| P3 | 统计分析增强（趋势图、导出） | routers/stats.py |