架构设计文档

README.md

@@ -1 +1,286 @@
-# 学生管理系统
+# 教培系统架构设计与开发
+
+本项目旨在开发一个基于FastAPI的学生管理系统，提供**学生基本信息管理、考核成绩管理和就业管理**三大核心功能模块。
+
+系统将采用RESTful API设计，支持前后端分离架构。
+
+
+
+## 需求分期
+
+团队对需求管理按照模块化解耦拆分开发，按照三个阶段开发
+
+1. 基础需求：按照开发任务，完成5 + 1 统计模块的开发
+
+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'
+);
+```
+
+
+
+
+
+
+
+## 技术架构设计
+
+
+
+### 构建环境适配
+
+```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
+  - 
+
+
+
+
+
+
+
+### 脚手架设计
+