15 KiB
江山代有人才秃 - 干就完了
master ： 最终合并版本
每个人创建自己的分支
- 每个表里都要有创建时间、更新时间、逻辑删除字段
版本一
一、需求整理（去冗余、补逻辑）
核心实体关系（ER 简版）
班级(1) ────< (n)学生(n) ────< (n)成绩 老师(1) ────< (n)班级 │ 顾问(1) ────< (n)学生 │ 学生(1) ────< (n)就业信息 ─────────┘
各模块功能清单（整理后）
模块 功能点 说明
学生管理 CRUD + 逻辑删除 学号唯一；顾问编号关联老师表
成绩管理 按序次录入/改/删 一个学生一次考核一条记录
就业管理 CRUD + 查询(公司/薪资范围) 冗余姓名字段，查询时同步更新
班级管理 CRUD 班主任、授课老师关联老师表
老师管理 CRUD 含带班信息
统计分析 6个统计接口 见需求2.6
关键设计决策
- 冗余字段处理：就业表里 学生姓名、学生班级 冗余 → 写入时从学生表拷贝，更新学生信息时同步更新就业表（或查询时JOIN，看你选哪种，建议写入时拷贝减少JOIN）
- 逻辑删除：学生表加 deleted_at 字段，查询默认过滤
- 成绩"每次考试"：按 考核序次 分组，序次=1,2,3...代表第几次考核
- 就业时长计算：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
关键约定（团队必须遵守）
-
分支命名：feature/模块名、fix/问题描述
-
commit规范：feat: 添加学生逻辑删除、fix: 成绩录入校验
-
接口统一返回格式： { "code": 200, "message": "success", "data": {...} }
-
所有查询接口必须加分页参数：?page=1&size=10
-
数据库操作全部走 crud 层，api 层不直接写 SQL
-
统计接口复杂查询放 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）
合并流程
- A 先完成 dev/base
- 其他人从 dev/base 拉自己的分支
- 每人开发完成后 → PR 到 dev/base
- A 负责 code review + 合并
- 最后合并到 main
四、数据库设计建议（给 A 的提示）
核心表
• student
• score
• employment
• class
• teacher
• class_teacher（多对多）
冗余字段处理
• 就业表中：
• student_name
• class_name
• 插入/更新时同步，查询时直接读
五、答辩 & 抽查应对策略
每人必须能讲清楚
• 自己负责模块的：
• 表结构
• API 设计
• 关键代码逻辑
• 为什么这样设计（尤其是统计 SQL）
组长额外准备
• 项目整体架构
• 数据库 ER 图
• 分支管理
• 合并冲突解决
ER图解析
都搞定了。ER 图出了概念 / 物理两张，配套把 FastAPI 项目骨架也搭好了，直接下载就能分给 6 个人开工。
一、ER 图设计要点
图1 概念图保留了需求文档里的 stu_name、class_name 冗余字段，用粉色标出，方便答辩时说明"需求这么写"；图2 物理图按第三范式把它们去掉了，改用外键关联——这是你们答辩最容易被追问的点，建议这样答：
冗余字段会造成数据不一致（学生改名后就业表还是旧名字），所以物理建模时去掉，查询时用 JOIN 实时取；只有在校验高频、性能吃紧的场景才按需冗余。
6 张表 + 1 张关系表：
表 对应成员 关键设计
student B is_deleted 逻辑删除、class_id 外键
class E head_teacher_id 指向班主任
teacher E 通用老师表
score C (student_id, exam_no) 联合唯一，防止同一考次重复录入
employment D student_id 唯一，一人一条就业记录
class_teacher E 班级↔老师多对多，带 subject 区分授课/带班
二、项目骨架结构
wolin_student_system/ ├── requirements.txt ├── README.md ← 含分工表 + 启动命令 └── app/ ├── main.py ← A 负责：入口、路由挂载 ├── config.py ← 数据库 URL（读 .env） ├── database.py ← engine + Session ├── dependencies.py ← get_db ├── exceptions.py ← 统一异常 ├── models/ ← 6 个成员各占一个文件 ├── schemas/ ← Pydantic 请求/响应模型 ├── routers/ ← 各成员主战场（已写好接口骨架+TODO） └── services/ ← 复杂查询放这里
骨架里的贴心细节： • 每个 router 文件里已经把需求文档要求的接口按路径签名写好（参数、装饰器、docstring 齐全），成员只要往里填实现，不用从零对着文档想接口名，避免 6 个人命名风格打架。
• models 用 SQLAlchemy 2.0 的 Mapped 新写法，relationship 已配好双向关联（比如 student.scores、class.students）。
• schemas/common.py 提供了 PageResponse 分页包装和 ApiResponse 统一返回结构，全组复用，前端解析方便。
三、给组长的合并建议
- 你先把 dev/base 推上去，其他人 rebase 而不是 merge 你的更新，历史更干净。
- 约定好冲突高发区：app/main.py（路由挂载）和 app/models/__init__.py（模型导出）这两个文件让各成员只改自己那一行，别整文件覆盖。
- routers/__init__.py 和 models/__init__.py 建议由你统一维护，别人提 PR 时只改自己的 router 文件。
需要我接着做哪个？比如：把统计模块的 SQL 全部写出来、补一份 .env.example + Alembic 迁移配置、或者按这个骨架把某个模块（比如成绩管理）的实现代码直接填满。