chamomind/elearning
6
0
Fork 0
Code Issues 4 Pull requests Projects Releases Packages 3 Wiki Activity Actions
elearning/Frontend-Learner/คู่มืออธิบาย/web-dev-details.md

12 KiB
Raw Blame History

🛠️ Web Development Documentation: e-Learning Platform (Frontend)

เอกสารฉบับนี้สรุปรายละเอียดทางเทคนิค โครงสร้างโค้ด และการทำงานของระบบ Frontend-Learner

🏗️ 1. Technical Foundation (รากฐานทางเทคนิค)

รวมข้อมูลเครื่องมือ, ระบบความปลอดภัย และประสิทธิภาพการทำงานไว้ด้วยกัน

1.1 Tech Stack

  • Core: Nuxt 3 (Vue 3 Composition API), TypeScript ^5.0
  • Styling: Tailwind CSS (Utility) + Vanilla CSS Variables (Theming)
  • State: ref/reactive (Local) + useState (Global/Shared State)
  • Localization: @nuxtjs/i18n (TH/EN Support)

1.2 Core Systems & Security

  • Authentication: ระบบ Auth ผูกกับ API โดยมี Middleware (middleware/auth.ts) คอยป้องกันการเข้าถึง Route เฉพาะ
  • API Handling: ใช้ runtimeConfig.public.apiBase จัดการ Base URL และ Auto-attach Bearer Token ใน Composables
  • Performance:
    • Caching: ใช้ useState จำข้อมูล (User Profile, Courses, Categories) เพื่อลด request ซ้ำซ้อน
    • Request Deduping: ป้องกันการเรียก API เดิมซ้ำๆ ในเวลาเดียวกัน

📂 2. Frontend Structure (โครงสร้างหน้าเว็บและ UI)

2.1 Application Routes (pages/)

Module ไฟล์ Path หน้าที่
Public index.vue / หน้าแรก Landing Page
browse/index.vue /browse หน้ารวมคอร์สทั้งหมด
browse/discovery.vue /browse/discovery ระบบค้นหาและ Filter
course/[id].vue /course/:id หน้ารายละเอียดคอร์ส
Auth auth/login.vue /auth/login เข้าสู่ระบบ
auth/register.vue /auth/register สมัครสมาชิกผู้เรียน
Student dashboard/index.vue /dashboard แดชบอร์ดภาพรวม
dashboard/my-courses.vue /dashboard/my-courses คอร์สของฉัน
classroom/learning.vue /classroom/learning ห้องเรียน (Video Player)
classroom/quiz.vue /classroom/quiz การสอบวัดผล

2.2 Reusable Components (components/)

  • Layout: AppHeader.vue, AppSidebar.vue, MobileNav.vue (Navigation หลัก)
  • Common: FormInput.vue (ฟอร์ม), LoadingSpinner.vue (สถานะโหลด), LanguageSwitcher.vue (เปลี่ยนภาษา)
  • Modules: CourseCard.vue (แสดงผลคอร์สแบบ Grid), UserAvatar.vue (รูปโปรไฟล์)

🧠 3. Logic & Data Layer (Composables + API)

รวบรวม Logic และ API Endpoint ที่เกี่ยวข้องไว้ในที่เดียวเพื่อความเข้าใจง่าย

3.1 useAuth.ts (Authentication & User)

จัดการสถานะผู้ใช้, ล็อกอิน, และข้อมูลส่วนตัว

  • Endpoints:
    • GET /api/user/me: ดึงข้อมูลโปรไฟล์ (Cached)
    • PUT /api/user/me: อัปเดตข้อมูลส่วนตัว
    • POST /api/user/change-password: เปลี่ยนรหัสผ่าน
    • POST /api/user/upload-avatar: อัปโหลดรูปโปรไฟล์

3.2 useCourse.ts (Course & Learning)

หัวใจหลักของการเรียนการสอน ตั้งแต่หน้ารายการคอร์สจนถึงห้องเรียน

  • Course Catalog Endpoints:
    • GET /api/courses: ดึงคอร์สทั้งหมด (Cached)
    • GET /api/courses/{id}: ดึงรายละเอียดคอร์ส
    • POST /api/students/courses/{id}/enroll: ลงทะเบียนเรียน
  • Classroom Endpoints:
    • GET /api/students/courses: ดึง "คอร์สของฉัน"
    • GET /api/students/courses/{id}/learn: ดึงโครงสร้างบทเรียน (Syllabus)
    • GET /api/students/courses/{id}/lessons/{lessonId}: ดึงวิดีโอเนื้อหา
    • GET /api/students/courses/{id}/lessons/{lessonId}/access-check: ตรวจสอบสิทธิ์การเข้าถึงบทเรียน
    • POST /api/students/lessons/{lessonId}/progress: บันทึกเวลาเรียน (Video Progress)
    • GET /api/students/lessons/{lessonId}/progress: ดึงเวลาเรียนล่าสุด
    • POST /api/students/courses/{id}/lessons/{lessonId}/complete: บันทึกว่าเรียนจบแล้ว
    • POST /api/students/courses/{id}/lessons/{lessonId}/quiz/submit: ส่งคำตอบแบบทดสอบ (Quiz)

3.3 useCategory.ts & Utilities

  • fetchCategories: ดึงหมวดหมู่ (GET /api/categories) สำหรับตัวกรองหน้า Discovery
  • useFormValidation.ts: รวม RegEx สำหรับตรวจสอบ Email, Password เบื้องต้น

🎨 4. Design System & Theming

4.1 Dark Mode Strategy

ระบบใช้ Class-based Dark Mode ของ Tailwind ผสมกับ CSS Variables:

  • Backgrounds: bg-slate-50 (Light) vs bg-slate-900 (Dark)
  • Text Visibility Rule (New):
    • ใช้ Utility Classes ระบุสีตรงๆ แทนตัวแปร CSS ในจุดสำคัญเพื่อป้องกันสีเพี้ยน
    • Ex: <h1 class="text-slate-900 dark:text-white">
  • Fonts: Prompt (Headings), Sarabun (Body)

6. Dependency Map & Relationships (แผนผังความสัมพันธ์ไฟล์)

ส่วนนี้ใช้อ้างอิงเวลาแก้ไขโค้ด เพื่อดูว่าไฟล์ไหนเชื่อมโยงหรือถูกเรียกใช้โดยไฟล์ใดบ้าง (Impact Analysis)

6.1 Page Dependencies (หน้าเว็บหลักใช้อะไรบ้าง)

Page (หน้าเว็บ) Components used (ส่วนประกอบที่ใช้) Composables used (Logic & API ที่ใช้)
pages/index.vue (Landing) LandingHeader, CourseCard useAuth, useCourse (fetchCourses)
pages/browse/discovery.vue CourseCard, FormInput, LoadingSpinner useCategory (Filter), useCourse (Search/List)
pages/course/[id].vue LoadingSpinner, UserAvatar (Instructor) useCourse (Detail, Enroll), useAuth (User Status)
pages/classroom/learning.vue AppSidebar (Curriculum), GlobalLoader useCourse (Video, Progress), useThemeMode
pages/dashboard/index.vue CourseCard (Recommended), UserAvatar useAuth (Profile), useCourse (My Courses)
pages/auth/*.vue (Login/Reg) FormInput, LanguageSwitcher useAuth (Login/Register), useFormValidation

6.2 Key Components Dependencies (Component นี้ถูกใช้ที่ไหน)

  • CourseCard.vue ถูกใช้ใน:

    • pages/index.vue (Recommended)
    • pages/browse/index.vue (Catalog List)
    • pages/browse/discovery.vue (Search Result)
    • pages/dashboard/index.vue (Dashboard Recommend)
    • pages/dashboard/my-courses.vue (My Course List)

  • FormInput.vue ถูกใช้ใน:

    • pages/auth/* (Login, Register, Forgot Password)
    • pages/dashboard/profile.vue (Edit Profile)

6.3 Composable Usage (Logic นี้ใครเรียกใช้บ้าง)

  • useAuth.ts -> ถูกเรียกใช้เกือบทุกหน้าที่มีการเช็ค User, Logout, หรือแสดงชื่อ
  • useCourse.ts -> ถูกเรียกใช้ในหน้า Browse, Course Detail, Classroom, Dashboard
  • useThemeMode.ts -> ถูกเรียกใช้ใน layouts/default.vue เพื่อคุม Theme ทั้งเว็บ

<EFBFBD>📊 7. Project Status (สถานะการพัฒนา)

✅ Completed Updates (สิ่งที่ทำเสร็จแล้ว)

  1. Code Cleanup: ลบไฟล์ขยะ (Mock Data pages) ออกจากระบบ
  2. Theme Refinement: แก้ไขปัญหาการแสดงผล Text Color ใน Light/Dark Mode หน้า learning.vue และ discovery.vue เสร็จสมบูรณ์
  3. API Integration: เชื่อมต่อระบบหลักครบถ้วน (Auth, Course, Enroll, Learning Progress)
  4. Localization: รองรับภาษาไทยสมบูรณ์พร้อมคำอธิบายโค้ด
  5. Profile Avatar: ระบบอัปโหลดรูปโปรไฟล์จริง (/api/user/upload-avatar) พร้อมแสดงผลทันทีแบบ Real-time และการจัดการสถานะ (Upload/Change)
  6. Quiz System Integrations:
    • เชื่อมต่อ API ส่งคำตอบ (/api/.../quiz/submit) และแสดงผลคะแนน
    • ระบบคำนวณคะแนนและสถานะ Pass/Fail จาก Server จริง
    • แก้ไขปัญหา Cache ฯ หน้าเรียน (learning.vue) ให้แสดงสถานะ "เรียนจบ" (✅) ทันทีที่สอบผ่าน โดยใช้ Timestamp Query (?_t=...) และ Watcher Logic
  7. UX/UI Improvements (My Courses & Enroll):
    • My Courses: แสดง Progress Bar ถูกต้อง (ดึง progress_percentage) และปรับ Filter "กำลังเรียน" ให้แสดงคอร์สใหม่ (ENROLLED) ด้วย
    • Enrollment Flow: แก้ไขปุ่ม "เริ่มเรียนทันที" ใน Modal ให้ลิงก์ไปยังคอร์สที่ถูกต้อง (ส่ง course_id param)
    • Auth: เพิ่มฟังก์ชัน "จดจำฉัน" (Remember Me) ในหน้า Login เพื่อจำ Email ผู้ใช้

🚀 Pending / Future Work (สิ่งที่ต้องทำต่อ)

  1. Certificates: ระบบดาวน์โหลดใบประกาศนียบัตร (ข้อมูล Backend พร้อมแล้ว รอเชื่อมต่อ UI)
  2. Payment Gateway: (ถ้ามีในอนาคต)