SmartGrad

SmartGrad เป็นแอปพลิเคชันบนเว็บที่ช่วยให้นักศึกษาสามารถตรวจสอบความก้าวหน้าในการเรียน คำนวณเปอร์เซ็นต์ความสำเร็จตามโครงสร้างหลักสูตร และวางแผนการลงทะเบียนเรียนในเทอมถัดไปได้อัตโนมัติ โดยใช้ข้อมูลจากการอัปโหลดไฟล์ Transcript รูปแบบ PDF จากสำนักทะเบียน นอกจากนี้ยังมีระบบสำหรับอาจารย์ที่ปรึกษาเพื่อใช้ติดตามผลการเรียนของนักศึกษาในความดูแลได้

โครงสร้างไฟล์ (Project Structure)

• main.py — แกนหลักของ FastAPI ตั้งค่าแอปพลิเคชันรวมถึงการกำหนด Route สำหรับฝั่งนักศึกษา (/, /search, /plan)
• parser.py — ประมวลผลและดึงข้อมูลจากไฟล์ Transcript PDF ด้วย pdfplumber (อ่านรหัสนักศึกษา, ชื่อ, รายวิชาที่เรียน, เกรด)
• dashboard.py — คำนวณความก้าวหน้าในการเรียน และสร้างตารางแนะนำแผนการเรียน (Study Plan)
• database.py — การตั้งค่าการเชื่อมต่อ SQLite (ใช้ฐานข้อมูล smartgrad.db)
• init.sql / seed.py — คำสั่ง SQL สำหรับสร้างโครงสร้างหลักสูตร (Curriculum) และฟังก์ชันสำหรับ Seed ข้อมูลลงฐานข้อมูลเริ่มต้น
• models.py — โมเดลข้อมูล Pydantic/SQLAlchemy เพื่อใช้ในการรับส่งข้อมูล
• config.py — ศูนย์รวมการตั้งค่าและค่าคงที่ทั้งหมด (Single Source of Truth) เช่น รหัสวิชาเกณฑ์การผ่าน
• services.py — ฟังก์ชันตัวช่วย (Shared Business Logic) ที่ถูกเรียกใช้ร่วมกันระหว่างหลายโมดูล
• routers/ — จัดการ API Routes ย่อย:
  • students.py — API เกี่ยวกับการจัดการข้อมูลนักศึกษา, บันทึกการจำลองถอนวิชา
  • curriculum.py — API สำหรับดึงข้อมูลโครงสร้างหลักสูตรและการค้นหารายวิชา
  • advisors.py — API และ Logic สำหรับระบบอาจารย์ที่ปรึกษา
• templates/ — หน้าต่างแสดงผล (Frontend) ใช้ HTML/JS/CSS ร่วมกับ Jinja2
  • index.html — หน้าหลักของนักศึกษา (อัปโหลด, ตรวจสอบ, Dashboard สรุปผล, วางแผนการเรียน และ Export PDF)
  • search.html — หน้าสำหรับค้นหารายวิชาทั้งหมดในหลักสูตร
  • advisor.html — หน้าสำหรับอาจารย์ที่ปรึกษา

Prerequisites

• Python 3.12+
• Docker (ถ้าต้องการใช้งานผ่าน Docker)
• uv (แนะนำสำหรับการจัดการแพ็กเกจที่รวดเร็ว)

การรันโปรเจกต์ (Local Run)

วิธีที่ 1: รันผ่าน Docker Compose (แนะนำ)

ไม่ต้องติดตั้ง Python บนเครื่อง สามารถรันคำสั่งนี้ได้เลย:

docker compose up -d

ระบบจะเข้าใช้งานได้ที่ http://localhost:8000 (ระบบนี้รันผ่าน Dockerfile ที่ปรับจูนให้ติดตั้งแพ็กเกจด้วย uv แบบอัตโนมัติ ทำให้ Build ได้เร็วมาก)

วิธีที่ 2: รันแบบ Local ผ่านคำสั่ง uv หรือ pip

โปรเจกต์นี้จัดการแพ็กเกจด้วย pyproject.toml แบบมาตรฐานยุคใหม่ (ไม่ต้องพึ่งไฟล์ requirements.txt)

ใช้ uv (แนะนำ):

uv venv
# สำหรับ Windows: .venv\Scripts\activate
# สำหรับ Mac/Linux: source .venv/bin/activate
uv pip install -e .
uvicorn main:app --reload

หรือใช้ pip ปกติ:

python -m venv .venv
# สำหรับ Windows: .venv\Scripts\activate
# สำหรับ Mac/Linux: source .venv/bin/activate
pip install .
uvicorn main:app --reload

เข้าใช้งานได้ที่: http://localhost:8000

Student Features

1. อัปโหลดและตรวจสอบ: ดึงข้อมูลจาก Transcript (.pdf) ได้ทันที
2. Dashboard สรุปผล: แสดงหน่วยกิตที่ได้แยกตามหมวดหมู่ (วิชาแกน, เลือกสาขา, GE, เลือกเสรี) พร้อมแถบ % ความก้าวหน้า
3. วางแผนการเรียน (Study Plan): ระบบแนะนำการลงวิชาในแต่ละเทอม (Drag & Drop เพื่อย้ายเทอมได้)
4. Export PDF: สั่งบันทึกแผนการเรียนที่จัดเสร็จแล้วออกมาเป็นไฟล์ PDF ได้
5. จำลองการถอน (Withdraw): จำลองสถานการณ์ถอนรายวิชา (W) ในเทอมปัจจุบัน เพื่อดูผลกระทบ

Advisor System

เปิด http://localhost:8000/advisor แล้วเข้าสู่ระบบด้วยบัญชีเริ่มต้นจากระบบ Seed ข้อมูล:

• รหัสอาจารย์: ADVISOR001
• รหัสผ่าน: smartgrad-demo
• ปีการศึกษาที่ดูแล: 2567 (นักศึกษาที่รหัสขึ้นต้นด้วย 67)