🛠️ Web Development Documentation: Frontend-Learner

เอกสารฉบับนี้สรุปรายละเอียดทางเทคนิค โครงสร้างโค้ด และกลไกการทำงานของระบบ Frontend-Learner (ระบบฝั่งผู้เรียน) อย่างครบถ้วน เพื่อใช้เป็นคู่มือสำหรับการพัฒนาและบำรุงรักษา (อัปเดตล่าสุด: ปลายเดือนกุมภาพันธ์ 2026)

🚀 1. Technical Foundation

รากฐานทางเทคนิคที่ขับเคลื่อนระบบ เพื่อให้ได้ประสิทธิภาพและความเสถียรสูงสุด

1.1 Tech Stack

Framework: Nuxt 3 (Vue 3, Vite, SSR/SPA Hybrid)
UI System: Quasar Framework + Tailwind CSS (Utility-first)
Typography: Google Fonts ("Prompt" เป็น Font หลักเพื่อความทันสมัยและอ่านง่าย)
Multilingual: @nuxtjs/i18n (รองรับ JSON-based locales ภาษาไทยและอังกฤษ)
Programming: TypeScript (Strict Type Checking)

1.2 Security & Authentication

Token Management: ใช้ JWT (Access & Refresh Tokens) จัดเก็บผ่าน useCookie ระบบรักษาความปลอดภัยระดับ HTTP-only และ SameSite
Middleware: auth.ts ตรวจสอบสิทธิ์การเข้าถึงหน้า Dashboard และ Classroom แบบ Real-time
Persistence: ระบบ Remember Me (จดจำอีเมล) ใช้ localStorage แยกส่วนจาก Session เพื่อความปลอดภัยและสะดวกสำหรับผู้ใช้

📂 2. Project Architecture

โครงสร้างโฟลเดอร์ที่จัดระเบียบตามหลัก Clean Architecture เพื่อความคล่องตัวในการขยายระบบ

2.1 Directory Structure

pages/: ระบบ Routing ทั้งหมด (Landing, Auth, Dashboard, Classroom)
components/: UI Components แยกตามความรับผิดชอบ (Common, Layout, Course, Classroom, Profile)
composables/: Business Logic ทั้งหมด (Auth, Course, Theme, Quiz, Navigation)
types/: ศูนย์รวม Interface และ Type definitions ของทั้งระบบ
constants/: แหล่งเก็บข้อมูล Static (เช่น Category cards, Why choose us) เพื่อลดความซับซ้อนในไฟล์ Vue
assets/css/: main.css ที่เป็น Single Source of Truth สำหรับสไตล์และ CSS Variables
layouts/: Master templates (Default, Auth, Dashboard)
middleware/: ตัวกรองความปลอดภัยก่อนเข้าถึงแต่ละหน้า

2.2 Shared Infrastructure

Types Architecture: การสกัด Types จาก Composable ออกมาไว้ที่ @/types ช่วยลดความซ้ำซ้อนและป้องกัน Error จากการเปลี่ยนโครงสร้างข้อมูล API
Constants System: การใช้ @/constants ช่วยให้การแก้ไขคำโฆษณาหรือข้อมูลหน้าแรกทำได้จากจุดเดียว โดยไม่ต้องแก้โค้ด HTML

🧠 3. Logic & Data Layer (Composables)

การแยก Logic ออกจาก UI เพื่อความสะอาดและ Testable

useAuth: จัดการสถานะ Login, การดึงโปรไฟล์ล่วงหน้า (Pre-fetching), และระบบ Token Refresh
useCourse: หัวใจของระบบ จัดการตั้งแต่ Catalog, การสมัครเรียน (Enroll), ไปจนถึงการส่งผลการเรียน (Progress)
useThemeMode: ระบบจัดการธีมกลางที่เชื่อมต่อกับ localStorage และ CSS Variables อย่างเป็นระบบ
useQuizRunner: จัดการสถานะการสอบ เปลี่ยนข้อสอบ และส่งคะแนนไปยัง Backend โดยตรง
useNavItems: Single Source of Truth สำหรับเมนูทั้งหมด (Sidebar, Mobile Drawer, User Menu)

🎨 4. Branding & UI Policy

มาตรฐานการออกแบบที่เน้นความ Premium และ Consistent

4.1 Theme Strategy

Public Pages (Landing, Auth, Detail): บังคับ Forced Light Mode เพื่อภาพลักษณ์แบรนด์ที่สะอาดและน่าเชื่อถือ
Internal Pages (Dashboard, Learning): รองรับ Dark Mode (Oceanic Theme) ลดการเมื่อยล้าของสายตาขณะเรียนเป็นเวลานาน
Transitions: ใช้ GlobalLoader และ Smooth transitions ทั่วทั้งแอปเพื่อประสบการณ์ที่ลื่นไหล

4.2 UI Elements

Image 2 Style Categories: การ์ดหมวดหมู่แบบแนวนอนที่เป็นระเบียบ (Minimalist)
Glassmorphism: พื้นผิวโปร่งแสงใน Dashboard และ Classroom ช่วยให้แอปดูมีมิติ
Standardized Icons: ใช้ Material Icons ผ่าน Quasar ระบบเดียวทั้งหมด

📚 5. Core Feature Highlights

ฟีเจอร์เด่นที่ถูกพัฒนาขึ้นเพื่อผู้เรียนโดยเฉพาะ

SPA Learning Journey: การสลับบทเรียนในห้องเรียนเป็นแบบ Single Page App (ไม่มีการ Re-load หน้า) ทำให้การเรียนต่อเนื่อง
Hybrid Progress Tracking: บันทึกเวลาเรียนลง LocalStorage แบบ Real-time และ Sync ขึ้น Server เป็นระยะเพื่อป้องกันข้อมูลหาย
Announcement System: ระบบแจ้งเตือนในคอร์สพร้อมตัวระบุ "ยังไม่ได้อ่าน" (Unread Badge) ที่จำสถานะตามผู้ใช้งาน
Interactive Quizzes: ระบบสอบที่สลับคำถามอัตโนมัติ พร้อมโหมดเฉลย (Answer Review) ที่ชัดเจน
Certificate Automation: ระบบตรวจสอบสิทธิ์ความสำเร็จและออกใบประกาศนียบัตรได้ทันที

🛠️ 6. Maintenance & Performance Guidelines

แนวทางสำหรับการพัฒนาต่อยอด

Clean Code: หลีกเลี่ยงการใช้ console.log ในโค้ด Final และลบ Dead Logic ทิ้งทันที
Standard Fonts: ใช้ชุด Font Prompt ผ่านตัวแปร --font-main เสมอ
API Integrity: ตรวจสอบข้อมูลผ่าน Interface ใน @/types ก่อนการใช้งานทุกครั้ง
Mobile First: ทุก Component ต้องรองรับระบบ Master Drawer บนมือถืออย่างสมบูรณ์

เอกสารนี้ถูกจัดทำขึ้นเพื่อให้ทีมพัฒนาเข้าใจทิศทางเดียวกัน และรักษามารตฐานสูงสุดของโปรเจกต์ e-Learning Platform

8.4 KiB Raw Blame History