student_manage_system/README.md

# 教培系统架构设计与开发

本项目旨在开发一个基于FastAPI的学生管理系统，提供**学生基本信息管理、考核成绩管理和就业管理**三大核心功能模块。

系统将采用RESTful API设计，支持前后端分离架构。



## 需求分期

团队对需求管理按照模块化解耦拆分开发，按照三个阶段开发

1. 基础需求：按照开发任务，完成5 + 1 统计模块的开发
> todo: 每个人补充一下自己对本模块的理解
    

2. 特色需求： 

   - 数据源配置

   - 鉴权管理

   - 添加部门管理，顾问管理模块

   - 添加用户认证模块

   - 开发前端应用

   - 开发更多的分析查询接口

   - 增加AI智能体和知识库开发

3. 脚手架集成





### 第一阶段 - 基础需求

按照开发任务，完成5 + 1 统计模块的开发

- 学生
- 班级
- 老师
- 成绩
- 就业
- 统计分析





### 第二阶段 - 特色需求

- 数据源配置

- 鉴权管理

- 添加部门管理，顾问管理模块

- 添加用户认证模块

- 开发前端应用

- 开发更多的分析查询接口

- 增加AI智能体和知识库开发









### 第三阶段 - 脚手架集成

核心组件

- 服务状态监控 - utc时区[还有哪些可替代？]
  - db ，中间件等组件是否活跃
  - 自身服务是否活跃
- 认证模块： oauth2_scheme
  - 
- 



## 业务拆分

> 业务范围划分
>
> - 实体
>   - 学生基本信息管理
>   - 考核成绩管理
>   - 就业管理
>   - 班级
>   - 老师
> - 统计分析







## 数据架构设计

数据关系

- 学生：班级 = N: 1, 班级：老师 = 1 : 1 / [N:1], 学生: 成绩 = 1:N , 学生：就业 = 1:1，
- 统计分析：



表结构优化

- 索引设置
- 



```sql
create database student_management_system;
use  student_management_system;

-- students
create table if not exists students(
	id int auto_increment primary key,
    snum int not null comment '学生编号',
    sname varchar(30) not null,
    age int not null,
    sex int not null,

    home_place varchar(50) null comment '家乡',
    college varchar(50) null comment '毕业院校',
    specialty varchar(50) null comment '专业',
    enrollment_time datetime null comment '入学时间',
    graduate_time datetime null comment '毕业时间',
    education varchar(50) null comment '学历',
    
    class_id int not null,

    advisor_id int null comment '顾问id',
    advisor_num int null comment '顾问编号',
    
    -- 通用字段
    create_time datetime not null,
    update_time datetime not null,
    is_detleted int not null comment '0 未删除,1'
);

-- teachers
create table if not exists teachers(
	id int auto_increment primary key,
    tnum int not null comment '老师编号',
    tname int not null,
    age int not null,
    sex int not null,    
        
    home_place varchar(50) null comment '家乡',
    college varchar(50) null comment '毕业院校',
    specialty varchar(50) null comment '专业',
    enrollment_time datetime null comment '入学时间',
    graduate_time datetime null comment '毕业时间',
    education varchar(50) null comment '学历',

    -- 额外信息：工作经验/教学评级 ，教学方向：应用，项目，算法；          
    work_experience text null comment '工作经验',
    coach_area text null comment '教学方向：应用，项目，算法',
        
    -- 通用字段
    create_time datetime not null,
    update_time datetime not null,
    is_detleted int not null comment '0 未删除,1'    
);


-- classes
create table if not exists classes(
	id int auto_increment primary key,
    class_num int not null comment '班级编号',
    class_start_time datetime null comment '开课时间',
    head_teacher_id int null comment '班主任',
    head_teacher_num int null comment '班主任编号',
    
    coach_teacher_id int null comment '授课老师',
    coach_teacher_num int null comment '授课老师编号',
    
    tutor_teacher_id int null comment '助教老师',
    tutor_teacher_num int null comment '助教老师编号',
            
    -- 通用字段
    create_time datetime not null,
    update_time datetime not null,
    is_detleted int not null comment '0 未删除,1'
);


-- scores
create table if not exists scores(
	id int auto_increment primary key,
	sid int not null,
    snum int not null,
    score_num int not null comment '考核序次', 
    score decimal(10,2) not null,
            
    -- 通用字段
    create_time datetime not null,
    update_time datetime not null,
    is_detleted int not null comment '0 未删除,1'
);


-- employment
create table if not exists employment(
	id int auto_increment primary key,
	sid int not null,
    snum int not null,
	sname varchar(30) not null,
	class_id int not null,
    class_num int not null comment '班级编号',
    
    employment_open_time datetime null comment '就业开放时间',
    offer_recived_time datetime null comment 'offer下发时间',
    employment_company varchar(50) null comment '就业公司',
    employment_salary decimal(10,2) null comment '就业薪资',
            
    -- 通用字段
    create_time datetime not null,
    update_time datetime not null,
    is_detleted int not null comment '0 未删除,1'
);
```







## 技术架构设计

### git 协作
- 按照业务模块，每个人新建自己的分支，分支名称：user_module
- main 分支：发版分支，test分支：做集成测试用


### 构建环境适配

```bash
# uv 统一 
pip install uv
uv init
uv add fastapi[standard] pymsql sqlalchemy # 添加依赖

# 运行测试
uv run uvicorn main:app  --reload  # uv run fastapi dev

# 其他平台： sync 同步即可
uv sync
```





### 基础架构适配

- 后端框架：
  - web route / api docs / 数据校验 : FastAPI
  - ORM 框架： pymysql, sqlarchemy 
  - 日志系统：loguru， 
  - 
- 数据库：多数据源适配
  - dev : sqlite3
  - prod: MySQL, PG
- 前端框架：
  - vue3
  - 







### 脚手架设计