# 码力全开：学生管理系统（FastAPI 分层示例）

基于 FastAPI + SQLAlchemy + MySQL 的学生管理系统后端，采用前后端分离的 RESTful API 设计。

## 模块一览

| 模块 | 路由前缀 | 说明 |
| --- | --- | --- |
| 学生信息管理 | `/api/student` | 学生基本信息的增删改查 |
| 学生成绩管理 | `/api/score` | 成绩增删改查，等级自动判定 |
| 班级管理 | `/api/classes` | 班级增删改查 |
| 学生就业管理 | `/api/employ` | 就业记录增删改查（与学生一对一） |
| 教师信息管理 | `/api/teacher` | 教师增删改查 |
| 顾问信息管理 | `/api/advisor` | 顾问增删改查 |
| 统计分析 | `/api/stats` | 总览、分布、成绩/就业综合统计 |

## 项目结构（分层）

```
claude_sms_test/
├── main.py            # 应用入口：注册路由、中间件、DAO 异常处理器
├── database.py        # 数据库引擎 / 会话工厂 / 依赖注入
├── init_db.py         # 建表脚本
├── model/             # 模型层：ORM 表映射
├── schemas/           # 模式层：Pydantic 请求/响应校验
├── dao/               # 数据访问层：查库、业务校验、事务
├── api/               # 路由层：接口出入参
└── static/            # 前端页面：原生 HTML/CSS/JS 单页应用（挂载在 /ui）
```

### 各层职责

| 层 | 干什么 | 不干什么 |
| --- | --- | --- |
| `api/` | 接收 HTTP 参数、调用 DAO、组装响应 | 不写 SQL、不 `import HTTPException` |
| `dao/` | 所有 SQLAlchemy 查询、唯一性/外键校验、软删除、事务提交 | 不感知 HTTP |
| `schemas/` | 请求体校验与响应序列化 | 不碰数据库 |
| `model/` | ORM 表结构映射 | 不含业务逻辑 |

**异常流转**：DAO 层只抛 `NotFoundError`(404) / `ConflictError`(409)，
在 `main.py` 注册的全局处理器统一转成 `{"detail": "..."}` 响应。
因此接口层不需要写任何 `try/except`。

```python
# dao      → 抛业务异常
raise NotFoundError("所属班级不存在")

# main.py  → 统一映射为状态码
@app.exception_handler(DaoError)
async def dao_error_handler(request: Request, exc: DaoError):
    return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail})

# api      → 干净的一行调用
return stu_dao.create_student(db, payload.model_dump())
```

## 快速开始

1. 安装依赖：
   ```bash
   pip install -r requirements.txt
   ```
2. 在 MySQL 中创建数据库（默认库名 `claude_sms_test`），并确认 `database.py` 中的连接信息正确。
3. 建表：
   ```bash
   python init_db.py
   ```
4. 启动服务：
   ```bash
   python main.py
   ```
5. 打开接口文档：http://localhost:8002/docs
6. 打开可视化管理界面（含查询小助手）：http://localhost:8002/ui

## 前端界面

`static/` 下是配套的管理界面，原生 HTML/CSS/JS，**无构建、无第三方依赖**，由 `main.py` 挂载在 `/ui`。

- 九个视图：数据总览 / 统计分析 / 学生 / 班级 / 教师 / 顾问 / 成绩 / 就业 / 查询小助手
- 表格支持分页与多条件筛选；新增、编辑、软删除均直连后端接口，删除为软删除并二次确认
- 统计图表为纯 DOM 绘制，不依赖任何 CDN，离线可用
- 右侧「查询小助手」直接用中文提问：
  - 编号直达详情：`S0001` / `C001` / `T001` / `A001`
  - 条件筛选：性别、学历、生源地、专业、班级、顾问、成绩等级、就业状态、就业公司
  - 统计问答：就业率、平均分、最高/最低分、及格率、薪资、生源地 Top、各类分布

## 说明

- 所有删除操作均为**软删除**（`is_deleted` 标记），数据不会真正从数据库中移除。
- 成绩等级未显式指定时，按分数自动判定：`>=90 优秀`、`80-89 良好`、`60-79 普通`、`<60 不及格`。