Student Management System (QLSV)

Tổng quan

Đây là một ứng dụng quản lý sinh viên hoàn chỉnh với đầy đủ các tính năng:

• Quản lý người dùng - 4 vai trò: ADMIN, CVHT, TEACHER, STUDENT
• Quản lý lớp học - Lớp chính quy (CVHT) và Lớp học phần (Teacher)
• Quản lý môn học - Danh mục môn học, tín chỉ, công thức điểm
• Quản lý điểm - Nhập điểm, tính GPA tự động, tổng kết học kỳ
• Forum thảo luận - Riêng biệt cho từng lớp
• Chat real-time - WebSocket, tìm kiếm theo SĐT
• AI Assistant - Chatbot hỗ trợ học tập với Gemini AI
• Thống kê & báo cáo - Dashboard, phân bố điểm, cảnh báo học vụ

Hệ thống quản lý sinh viên với phân quyền đầy đủ cho ADMIN, CVHT (Cố vấn học tập), TEACHER và STUDENT.

Tính năng chính

Phân quyền theo vai trò

ADMIN

• Quản lý tất cả người dùng trong hệ thống
• Tạo và quản lý danh mục môn học
• Xem toàn bộ dữ liệu hệ thống
• Quản lý lớp chính quy và lớp học phần

CVHT (Cố vấn học tập)

• Quản lý lớp chính quy của mình
• Import danh sách sinh viên từ Excel/CSV
• Xem thống kê học lực của lớp
• Tính toán GPA tự động từ điểm các môn
• Cập nhật thông tin nợ học phí, cảnh báo học vụ
• Quản lý forum lớp chính quy

TEACHER (Giảng viên)

• Tạo và quản lý lớp học phần
• Import danh sách sinh viên đăng ký môn học
• Nhập điểm cho sinh viên (giữa kỳ, cuối kỳ, bài tập)
• Quản lý forum lớp học phần
• Xem danh sách sinh viên trong lớp

STUDENT (Sinh viên)

• Xem điểm các môn học
• Xem tổng kết học kỳ và GPA
• Xem lớp chính quy và lớp học phần
• Tham gia forum thảo luận
• Chat với bạn cùng lớp, giảng viên, CVHT

Quản lý lớp học

Hệ thống có 2 loại lớp học rõ ràng:

1. Lớp chính quy (Administrative Class)

• Quản lý bởi: CVHT (Cố vấn học tập)
• Mục đích: Nhóm sinh viên theo khóa học, tồn tại suốt 4 năm
• Ví dụ: CNTT-K17, QTM-K18
• Chức năng:
  • Theo dõi học lực toàn khóa
  • Quản lý thông tin sinh viên
  • Tính GPA và tổng kết học kỳ
  • Cảnh báo học vụ

2. Lớp học phần (Course Class)

• Quản lý bởi: Teacher (Giảng viên)
• Mục đích: Dạy môn học cụ thể trong 1 học kỳ
• Ví dụ: IT3080.01, IT3090.02
• Chức năng:
  • Quản lý sinh viên đăng ký môn học
  • Nhập điểm (giữa kỳ, cuối kỳ, bài tập)
  • Tính điểm tổng kết theo công thức

Quản lý điểm

Điểm môn học (Course Grades)

• Teacher nhập điểm từng môn
• Hỗ trợ nhiều thành phần: giữa kỳ, cuối kỳ, bài tập
• Công thức tính điểm linh hoạt theo từng môn
• Tự động tính điểm tổng kết

Tổng kết học kỳ (Semester Summary)

• Tự động tính GPA từ điểm các môn
• Tính số tín chỉ tích lũy
• Xếp loại học lực: Xuất sắc, Giỏi, Khá, Trung bình, Yếu
• Cảnh báo học vụ tự động

Tính năng khác

• Forum thảo luận cho từng lớp
• Chat real-time với WebSocket
• Import dữ liệu từ Excel/CSV
• Dashboard thống kê trực quan
• Báo cáo phân bố điểm

Cài đặt và chạy

Yêu cầu hệ thống

• Python 3.8 trở lên
• MongoDB 4.0 trở lên
• Hệ điều hành: Windows, Linux, macOS

Bước 1: Cài đặt dependencies

pip install -r requirements.txt

Bước 2: Cấu hình

Tạo file .env từ .env.example:

DATABASE_HOST=localhost
DATABASE_PORT=27017
DATABASE_NAME=qlsv_v2
SECRET_KEY=your-secret-key-here
ALGORITHM=HS256
ACCESS_EXPIRE=30
REFRESH_EXPIRE=7
API_V1_STR=/api/v1
GOOGLE_API_KEY=""

Bước 3: Khởi động MongoDB

# Linux/macOS
sudo systemctl start mongod

# Windows
net start MongoDB

Bước 4: Import dữ liệu mẫu

python import_sample_data.py

Dữ liệu mẫu bao gồm:

• 1 ADMIN, 1 CVHT, 2 TEACHER, 3 STUDENT
• 5 môn học
• 1 lớp chính quy với 3 sinh viên
• 2 lớp học phần với điểm số
• Dữ liệu forum và chat

Bước 5: Chạy ứng dụng

Terminal 1 - Backend:

python -m uvicorn app.main:app --reload --port 8080

Terminal 2 - Frontend:

python frontend/main.py

Bước 6: Đăng nhập

Mở ứng dụng frontend và đăng nhập với các tài khoản sau:

Password cho tất cả tài khoản: password123

Vai trò	MSSV	Tên	Mô tả
ADMIN	ADMIN001	Admin User	Quản trị viên hệ thống
CVHT	CVHT001	Nguyen Van An	CVHT lớp CNTT-K17
TEACHER	GV001	Tran Thi Binh	Giảng viên Python
TEACHER	GV002	Le Van Cuong	Giảng viên Database
STUDENT	20201234	Pham Thi Dung	Sinh viên xuất sắc (GPA 3.8)
STUDENT	20201235	Hoang Van Em	Sinh viên giỏi (GPA 3.2)
STUDENT	20201236	Nguyen Thi Phuong	Sinh viên khá (GPA 2.8)

Cấu trúc dự án

Backend (FastAPI)

app/
├── main.py                      # Entry point, khởi tạo FastAPI
├── dependencies.py              # Authentication và phân quyền
├── core/
│   ├── security.py             # JWT, password hashing
│   └── socket.py               # WebSocket manager
├── db/
│   └── connection.py           # Kết nối MongoDB
├── model/                      # Pydantic models
│   ├── muser.py               # User model
│   ├── mcourse.py             # Course & Course Class models
│   ├── madministrative_class.py  # Administrative Class model
│   ├── mgrade.py              # Grade models
│   ├── mpost.py               # Forum post model
│   └── mchat.py               # Chat models
├── routers/                    # API endpoints
│   ├── auth.py                # Login, register
│   ├── users.py               # User management
│   ├── courses.py             # Courses & Course Classes
│   ├── administrative_classes.py  # Administrative Classes
│   ├── course_grades.py       # Grade entry
│   ├── semester_summary.py    # GPA calculation
│   ├── posts.py               # Forum
│   ├── chat.py                # Chat & WebSocket
│   ├── stats.py               # Statistics
│   └── ai_assistant.py        # AI Chatbot
└── utils/
    └── grade_calculator.py     # GPA calculation logic

Frontend (CustomTkinter)

frontend/
├── main.py                     # Entry point
└── src/
    ├── api/
    │   └── client.py          # API client với authentication
    ├── components/
    │   └── sidebar.py         # Navigation sidebar
    └── views/                 # UI views
        ├── login_view.py
        ├── main_view.py
        ├── dashboard_view.py
        ├── users_view.py
        ├── courses_view.py
        ├── admin_classes_view.py
        ├── course_classes_view.py
        ├── course_grades_view.py
        ├── semester_summary_view.py
        ├── student_classes_view.py
        ├── student_grades_view.py
        ├── stats_view.py
        ├── forum_view.py
        └── chat_view.py

Quy trình sử dụng

Quy trình hoàn chỉnh từ đầu đến cuối

1. ADMIN tạo môn học

   • Vào menu "Courses"
   • Thêm môn học mới với mã môn, tên, số tín chỉ
   • Cấu hình công thức tính điểm (giữa kỳ, cuối kỳ, bài tập)

2. CVHT tạo lớp chính quy

   • Vào menu "Administrative Classes"
   • Tạo lớp mới (ví dụ: CNTT-K17)
   • Import danh sách sinh viên từ Excel/CSV

3. TEACHER tạo lớp học phần

   • Vào menu "My Courses"
   • Chọn môn học và tạo lớp học phần
   • Import danh sách sinh viên đăng ký

4. TEACHER nhập điểm

   • Vào menu "Grade Entry"
   • Chọn lớp học phần
   • Nhập điểm cho từng sinh viên

5. CVHT tính GPA

   • Vào menu "Semester Summary"
   • Hệ thống tự động tính GPA từ điểm các môn
   • Cập nhật thông tin nợ học phí, cảnh báo

6. STUDENT xem điểm

   • Vào menu "My Academic Records"
   • Xem điểm từng môn và GPA

Database Schema

Collections chính

users

• Lưu thông tin người dùng
• Fields: mssv, full_name, email, password, role, phone, administrative_class_id

courses

• Danh mục môn học
• Fields: code, name, credits, grade_formula

administrative_classes (Lớp chính quy)

• Quản lý bởi CVHT, tồn tại suốt khóa học
• Fields: name, academic_year, advisor_id, student_ids
• Ví dụ: CNTT-K17, QTM-K18

course_classes (Lớp học phần)

• Quản lý bởi Teacher, tồn tại trong 1 học kỳ
• Fields: course_id, teacher_id, semester, class_code, student_ids
• Ví dụ: IT3080.01, IT3090.02

course_grades

• Điểm từng môn học
• Fields: student_id, course_class_id, midterm_score, final_score, assignment_score, total_score

semester_summaries

• Tổng kết học kỳ (tự động tính từ điểm các môn)
• Fields: student_id, semester, gpa, credits_earned, credits_passed, tuition_debt, academic_warning

posts

• Bài viết forum (cho cả lớp chính quy và lớp học phần)
• Fields: post_type, class_id, author_id, content, likes, comments

conversations & messages

• Chat real-time
• Fields: participants, messages, timestamps

API Documentation

Sau khi chạy backend, truy cập Swagger UI để xem tài liệu API đầy đủ:

http://localhost:8080/docs

API Endpoints chính

Authentication:

• POST /api/v1/auth/login - Đăng nhập
• POST /api/v1/auth/register - Đăng ký
• POST /api/v1/auth/refresh - Refresh token

Users:

• GET /api/v1/users/ - Danh sách users (Admin)
• GET /api/v1/users/me - Thông tin user hiện tại

Courses (Môn học):

• GET /api/v1/courses/ - Danh sách môn học
• POST /api/v1/courses/ - Tạo môn học (Admin)

Administrative Classes (Lớp chính quy - CVHT):

• GET /api/v1/administrative-classes/ - Danh sách lớp chính quy
• POST /api/v1/administrative-classes/ - Tạo lớp chính quy (CVHT)
• POST /api/v1/administrative-classes/{id}/import-students - Import sinh viên

Course Classes (Lớp học phần - Teacher):

• GET /api/v1/course-classes/ - Danh sách lớp học phần
• POST /api/v1/course-classes/ - Tạo lớp học phần (Teacher)
• POST /api/v1/course-classes/{id}/import-students - Import sinh viên

Grades:

• POST /api/v1/course-grades/import - Import điểm (Teacher)
• GET /api/v1/course-grades/my-grades - Xem điểm của mình (Student)

Semester Summary:

• POST /api/v1/semester-summary/calculate/{student_id} - Tính GPA (CVHT)
• GET /api/v1/semester-summary/my-summary - Xem tổng kết (Student)

Real-time:

• WebSocket /ws/{user_id} - Chat real-time

Bảo mật

• Password được hash bằng bcrypt
• Authentication sử dụng JWT tokens
• Role-based access control (RBAC)
• HTTPOnly cookies cho refresh token
• Input validation với Pydantic
• Protected WebSocket connections

Tính năng nổi bật

Tính GPA tự động

• Không cần nhập thủ công
• Tự động tính từ điểm các môn học
• Cập nhật real-time khi có điểm mới

Import dữ liệu linh hoạt

• Hỗ trợ Excel (.xlsx, .xls) và CSV
• Tự động mapping theo email hoặc MSSV
• Báo cáo chi tiết kết quả import

Forum thảo luận

• Riêng biệt cho từng lớp
• Hiển thị tên và vai trò người đăng
• Hỗ trợ comments

Chat real-time

• WebSocket cho tốc độ cao
• Chat với bạn cùng lớp
• Chat với giảng viên và CVHT
• Tìm kiếm người dùng theo số điện thoại

Thống kê trực quan

• Biểu đồ phân bố điểm
• Thống kê theo lớp
• Dashboard tổng quan

Phát triển tiếp

Các tính năng có thể bổ sung:

• Thông báo qua email
• Upload file đính kèm trong forum
• Ảnh đại diện người dùng
• Biểu đồ lịch sử điểm
• Quản lý điểm danh
• Quản lý thời khóa biểu
• Ứng dụng mobile
• Export báo cáo PDF/Excel
• Pagination cho danh sách lớn
• Rate limiting API
• Logging và monitoring

AI Assistant Feature

Tính năng mới: Chatbot AI với Gemini

Cài đặt:

pip install google-genai

Cấu hình .env:

GEMINI_API_KEY=your-api-key-here

Lấy API key: https://aistudio.google.com/apikey

Tính năng:

• Context-aware responses theo role user
• Hỗ trợ tiếng Việt
• Floating button trong Dashboard
• Chỉ hiển thị cho STUDENT, TEACHER, CVHT (không có ADMIN)

Sử dụng:

1. Vào Dashboard
2. Click nút "🤖 AI Assistant"
3. Hỏi về học tập, điểm số, GPA, phương pháp dạy, v.v.

License

MIT License - Tự do sử dụng cho mục đích học tập