claude_sms_test

2026-09-18 16:53:21 +08:00
commit b9311bdb1e
46 changed files with 4225 additions and 0 deletions
@@ -0,0 +1,90 @@
+# 码力全开：学生管理系统（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 不及格`。