Student_Management_System/README.md

# 江山代有人才秃 - 干就完了

# master ： 最终合并版本

# 每个人创建自己的分支
1. 每个表里都要有创建时间、更新时间、逻辑删除字段

---

# 版本一
一、需求整理（去冗余、补逻辑）

核心实体关系（ER 简版）


班级(1) ────< (n)学生(n) ────< (n)成绩
老师(1) ────< (n)班级              │
顾问(1) ────< (n)学生              │
学生(1) ────< (n)就业信息 ─────────┘


各模块功能清单（整理后）

模块 功能点 说明

学生管理 CRUD + 逻辑删除 学号唯一；顾问编号关联老师表

成绩管理 按序次录入/改/删 一个学生一次考核一条记录

就业管理 CRUD + 查询(公司/薪资范围) 冗余姓名字段，查询时同步更新

班级管理 CRUD 班主任、授课老师关联老师表

老师管理 CRUD 含带班信息

统计分析 6个统计接口 见需求2.6

关键设计决策

1. 冗余字段处理：就业表里 学生姓名、学生班级 冗余 → 写入时从学生表拷贝，更新学生信息时同步更新就业表（或查询时JOIN，看你选哪种，建议写入时拷贝减少JOIN）
2. 逻辑删除：学生表加 deleted_at 字段，查询默认过滤
3. 成绩"每次考试"：按 考核序次 分组，序次=1,2,3...代表第几次考核
4. 就业时长计算：offer下发时间 - 就业开放时间，单位天

二、技术文档

技术栈（基于你现有依赖）

层次 技术

Web框架 FastAPI 0.128.0

服务器 Uvicorn

ORM SQLAlchemy 2.0.49

数据库 MySQL（PyMySQL / aiomysql 异步驱动）

数据校验 Pydantic 2.13.3

认证 python-jose + passlib（JWT，可选）

迁移 Alembic 1.18.5

AI辅助 ollama / openai（需求里有，可用于啥？）

项目目录结构


student_management/
├── main.py                 # 入口
├── config.py               # 配置（数据库URL、密钥等）
├── database.py             # 数据库连接、Session管理
├── models/                 # SQLAlchemy 模型（表结构）
│   ├── __init__.py
│   ├── student.py
│   ├── class_info.py
│   ├── teacher.py
│   ├── score.py
│   └── employment.py
├── schemas/                # Pydantic 请求/响应模型
│   ├── __init__.py
│   ├── student.py
│   ├── class_info.py
│   ├── teacher.py
│   ├── score.py
│   └── employment.py
├── crud/                   # 数据库操作层（增删改查）
│   ├── __init__.py
│   ├── student.py
│   ├── class_info.py
│   ├── teacher.py
│   ├── score.py
│   └── employment.py
├── api/                    # 路由层（接口定义）
│   ├── __init__.py
│   ├── student.py
│   ├── class_info.py
│   ├── teacher.py
│   ├── score.py
│   ├── employment.py
│   └── stats.py            # 统计分析接口
├── services/               # 业务逻辑层（复杂计算放这）
│   ├── __init__.py
│   └── stats_service.py
├── utils/                  # 工具函数
│   ├── __init__.py
│   └── dependencies.py     # 依赖注入（如get_db）
├── alembic/                # 数据库迁移
│   └── versions/
├── requirements.txt
├── .env                    # 环境变量（不提交git）
├── .env.example            # 环境变量模板
└── README.md


分层架构


┌─────────────────────────────────────────┐
│            API 路由层 (api/)             │  ← 接收请求、参数校验、返回JSON
├─────────────────────────────────────────┤
│         业务逻辑层 (services/)           │  ← 复杂统计、事务编排
├─────────────────────────────────────────┤
│         CRUD操作层 (crud/)              │  ← 纯数据库读写
├─────────────────────────────────────────┤
│      ORM模型层 (models/) + Schemas      │  ← 表结构 + 数据校验
├─────────────────────────────────────────┤
│         数据库 (MySQL)                  │
└─────────────────────────────────────────┘


数据库表结构（核心字段）

-- 老师表
teacher: id, name, phone, email, created_at

-- 班级表
class: id, class_code, start_date, head_teacher_id(FK), instructor_id(FK)

-- 学生表
student: id, student_no, class_id(FK), name, hometown, school, major, 
         enroll_date, graduate_date, education, advisor_id(FK), age, 
         gender, deleted_at

-- 成绩表
score: id, student_id(FK), exam_sequence, score, created_at

-- 就业表
employment: id, student_id(FK), student_name(冗余), class_name(冗余),
             employment_open_date, offer_date, company_name, salary,
             created_at, updated_at


API 接口清单

模块 方法 路径 说明

学生 POST /api/students/ 创建

学生 GET /api/students/ 列表（支持筛选）

学生 GET /api/students/{id} 详情

学生 PUT /api/students/{id} 更新

学生 DELETE /api/students/{id} 逻辑删除

成绩 POST /api/scores/ 录入

成绩 PUT /api/scores/{id} 修改

成绩 DELETE /api/scores/{id} 删除

就业 POST /api/employments/ 记录

就业 GET /api/employments/ 查询（公司/薪资范围）

就业 PUT /api/employments/{id} 修改

就业 DELETE /api/employments/{id} 删除

班级 CRUD /api/classes/ 同上

老师 CRUD /api/teachers/ 同上

统计 GET /api/stats/students/over-30 超30岁学员

统计 GET /api/stats/classes/population 班级人数/性别分布

统计 GET /api/stats/scores/excellent 每次都80+

统计 GET /api/stats/scores/failed-2plus 两次以上不及格

统计 GET /api/stats/scores/class-average 班级平均分排序

统计 GET /api/stats/employment/top-salary 薪资Top5

统计 GET /api/stats/employment/duration 就业时长统计

三、6人分工方案

推荐分工（按模块+层次交叉）

成员 职责 具体任务

A（组长/架构） 项目初始化 + 学生模块 + 整体协调 搭项目骨架、config/database/base、学生CRUD、统筹进度、合并代码

B 班级模块 + 老师模块 班级&老师 models/schemas/crud/api 全套，老师带班关联

C 成绩模块 + 统计分析（成绩部分） 成绩录入/修改/删除 + 3个成绩统计接口（优秀/不及格/平均分）

D 就业模块 + 统计分析（就业部分） 就业CRUD + 冗余字段同步 + 3个就业统计接口（Top5/时长/班级平均）

E 学生模块补充 + 统计分析（基本信息） 学生筛选/逻辑删除/更新同步 + 超30岁/班级人数统计 + 前端对接（如果有人做前端）

F 数据库迁移 + 测试 + 文档 Alembic迁移脚本、接口测试（Postman/curl）、README、API文档核对

开发顺序（时间线建议）


第1天：A搭骨架 → 全员 clone → 各自建分支
第2-3天：A/B/D 并行做 models + schemas + crud
第4-5天：C/D/E 并行做 api 路由 + 业务逻辑
第6天：F 写迁移 + 联调测试
第7天：全员修bug + 补充统计接口边界情况


Git 协作规范

# 每人基于 main 建自己的分支
git checkout -b feature/student-module    # A
git checkout -b feature/class-teacher     # B
git checkout -b feature/score            # C
git checkout -b feature/employment       # D
git checkout -b feature/stats-basic      # E
git checkout -b feature/migration-test   # F

# 每天下班前 push，组长 review 后 merge


关键约定（团队必须遵守）

1. 分支命名：feature/模块名、fix/问题描述
2. commit规范：feat: 添加学生逻辑删除、fix: 成绩录入校验
3. 接口统一返回格式：
{
  "code": 200,
  "message": "success",
  "data": {...}
}

4. 所有查询接口必须加分页参数：?page=1&size=10
5. 数据库操作全部走 crud 层，api 层不直接写 SQL
6. 统计接口复杂查询放 services 层，crud 只做简单读写

# 方案二：
这份需求文档涉及 学生管理、成绩、就业、班级、老师、统计分析 6 大模块，加上数据库设计和后续合并测试，正好适合 6 人小组 按“模块 + 公共基础”的方式分工。下面给你一套可直接落地的分工方案，兼顾开发效率、代码解耦和答辩覆盖度。

一、推荐分工方案（6 人）

✅ 原则

• 每人负责 1 个独立模块

• 1 人负责 公共基础 + 数据库 + 项目骨架

• 每人独立分支，最后统一合并

• 答辩时每人都能讲“自己写的代码 + 涉及的设计”

👥 人员分工表

成员 负责模块 核心职责

A（组长/架构） 公共基础 + 数据库设计 项目初始化、数据库建模、BaseModel、异常、依赖、路由聚合、合并分支

B 学生基本信息管理 学生 CRUD、逻辑删除、查询筛选

C 成绩管理模块 成绩录入、修改、删除、学生成绩查询

D 就业管理模块 就业信息增删改查、冗余字段设计

E 班级 & 老师管理模块 班级、老师信息管理、带班关系

F 统计分析模块 所有统计接口（成绩/就业/基本信息统计）

二、每人详细职责说明

👤 A：公共基础 + 数据库设计（非常关键）

职责：
• MySQL 数据库设计（ER 图、表结构）

• FastAPI 项目骨架搭建

• 公共依赖（数据库 session、分页、权限预留）

• Pydantic 基础模型

• 统一异常处理

• 路由汇总（include_router）

• Git 分支管理与最终合并

产出：
• models/

• schemas/

• database.py

• dependencies.py

• exceptions.py

• main.py

📌 建议分支：

dev/base


👤 B：学生基本信息管理

职责：
• 学生表设计建议

• 学生增删改查

• 逻辑删除

• 条件查询（编号/姓名/班级）

API 示例：
• GET /students

• POST /students

• GET /students/{id}

• PUT /students/{id}

📌 分支：

dev/student


👤 C：成绩管理模块

职责：
• 成绩表设计

• 成绩录入、修改、删除

• 单学生成绩查询

API 示例：
• POST /score/

• GET /score/{stu_id}

• PUT /score/update

• POST /score/delete

📌 分支：

dev/score


👤 D：就业管理模块

职责：
• 就业表设计（含冗余字段）

• 就业信息新增 / 更新

• 多条件查询（公司、薪资范围）

API 示例：
• GET /employment/students/{id}

• POST /employment/students/{id}

📌 分支：

dev/employment


👤 E：班级 & 老师管理模块

职责：
• 班级表、老师表

• 班级 CRUD

• 老师 CRUD

• 带班关系设计

API 示例：
• GET /classes

• POST /classes

• GET /teachers

📌 分支：

dev/class-teacher


👤 F：统计分析模块

职责：
• 所有统计 SQL / ORM 查询

• 成绩统计

• 就业统计

• 基本信息统计

API 示例：
• GET /statistics/xxx

📌 分支：

dev/statistics


三、Git 分支与合并策略（强烈建议）

分支结构

 ├── dev/base           （A）
 ├── dev/student        （B）
 ├── dev/score          （C）
 ├── dev/employment     （D）
 ├── dev/class-teacher  （E）
 └── dev/statistics     （F）


合并流程

1. A 先完成 dev/base
2. 其他人从 dev/base 拉自己的分支
3. 每人开发完成后 → PR 到 dev/base
4. A 负责 code review + 合并
5. 最后合并到 main

四、数据库设计建议（给 A 的提示）

核心表

• student

• score

• employment

• class

• teacher

• class_teacher（多对多）

冗余字段处理

• 就业表中：

  • student_name

  • class_name

• 插入/更新时同步，查询时直接读

五、答辩 & 抽查应对策略

每人必须能讲清楚

• 自己负责模块的：

  • 表结构

  • API 设计

  • 关键代码逻辑

• 为什么这样设计（尤其是统计 SQL）

组长额外准备

• 项目整体架构

• 数据库 ER 图

• 分支管理

• 合并冲突解决