elearning/Frontend-Learner/คู่มืออธิบาย/web-dev-details.md

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

เอกสารฉบับนี้สรุปรายละเอียดทางเทคนิค โครงสร้างโค้ด และการทำงานของระบบ Frontend-Learner (อัปเดตล่าสุด: กุมภาพันธ์ 2026)

---

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

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

1.1 Tech Stack

• Core: Nuxt 3 (v^3.11.2), TypeScript ^5.4.5
• UI Framework: Quasar Framework ^2.15.2 (via nuxt-quasar-ui ^3.0.0)
• Styling: Tailwind CSS ^6.12.0 (Utility) + Vanilla CSS Variables (Theming/Dark Mode)
• State Management: ref/reactive (Local) + useState (Global/Shared State)
• Localization: @nuxtjs/i18n (Supports JSON locales in i18n/locales/)
• Media Control: useMediaPrefs (Command Pattern for global volume/mute state)

1.2 Core Systems & Security

• Authentication:
  • ใช้ JWT (Access Token 1 วัน, Refresh Token 7 วัน)
  • เก็บ Token ใน useCookie (Secure, SameSite)
  • Middleware (middleware/auth.ts) ป้องกัน Route ตามสถานะ
  • Remember Me: ระบบจดจำอีเมลลงใน localStorage (จำแยกจาก session, ไม่ถูกลบเมื่อ Logout)
• API Handling:
  • ใช้ runtimeConfig.public.apiBase เชื่องโยง Backend
  • Auto-attach Bearer Token ใน useAuth และ useCourse
• Performance:
  • Hybrid Progress Saving: บันทึกเวลาเรียนลง LocalStorage (ถี่) และ Server (Throttle 15s) เพื่อความแม่นยำสูงสุด
  • Caching: ใช้ useState จำข้อมูล Profile และ Categories ลด request
  • Code Quality: ลบ Log, Dead logic และ Redundant comments ทั่วทั้งโปรเจกต์ (Clean Code Phase)

---

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

2.1 Application Routes (pages/)

Module	ไฟล์	Path	หน้าที่
Public	index.vue	/	หน้าแรก Landing Page (Forced Light Mode)
	browse/discovery.vue	/browse/discovery	ระบบค้นหาและ Filter คอร์ส (Catalog)
	course/[id].vue	/course/:id	หน้ารายละเอียดคอร์ส (Course Detail)
Auth	auth/login.vue	/auth/login	เข้าสู่ระบบ (Remember Me, Light Mode)
	auth/register.vue	/auth/register	สมัครสมาชิกผู้เรียน (Light Mode)
	auth/forgot-password.vue	/auth/forgot-password	กู้คืนรหัสผ่าน (Light Mode)
Student	dashboard/index.vue	/dashboard	แดชบอร์ดภาพรวมผู้เรียน
	dashboard/my-courses.vue	/dashboard/my-courses	คอร์สของฉัน และดาวน์โหลดใบประกาศฯ
	dashboard/profile.vue	/dashboard/profile	จัดการโปรไฟล์, รูปภาพ, เปลี่ยนรหัสผ่าน
	classroom/learning.vue	/classroom/learning	ห้องเรียน (Video Player) & Announcements
	classroom/quiz.vue	/classroom/quiz	การสอบวัดผล (API-Driven Logic)

2.2 Key Components (components/)

• Common (components/common/):
  • GlobalLoader.vue: Loading indicator ทั่วทั้งแอป
  • LanguageSwitcher.vue: ปุ่มเปลี่ยนภาษา (TH/EN)
  • AppHeader.vue, MobileNav.vue: Navigation หลัก (ใช้ร่วมกับ AppSidebar)
  • FormInput.vue: Input field มาตรฐาน
• Layout (components/layout/):
  • AppSidebar.vue: Sidebar หลักสำหรับ Dashboard (Collapsible)
  • LandingHeader.vue: Header เฉพาะสำหรับหน้า Landing Page
• Course (components/course/):
  • CourseCard.vue: การ์ดแสดงผลคอร์ส รองรับ Progress และ Glassmorphism ในโหมดมืด
• Discovery (components/discovery/):
  • CategorySidebar.vue: Sidebar ตัวกรองหมวดหมู่แบบย่อ/ขยายได้
  • CourseDetailView.vue: หน้ารายละเอียดคอร์สขนาดใหญ่ (Video Preview + Syllabus)
• Classroom (components/classroom/):
  • CurriculumSidebar.vue: Sidebar บทเรียนและสถานะการเรียน
  • AnnouncementModal.vue: Modal แสดงประกาศของคอร์ส
  • VideoPlayer.vue: Video Player พร้อม Custom Controls และ YouTube Support
• User / Profile (components/user/, components/profile/):
  • UserAvatar.vue: แสดงรูปโปรไฟล์ (รองรับ Fallback)
  • ProfileEditForm.vue: ฟอร์มแก้ไขข้อมูลส่วนตัว
  • PasswordChangeForm.vue: ฟอร์มเปลี่ยนรหัสผ่าน

2.3 Shared Infrastructure (types/, constants/)

• Types (types/): หัวใจของ Type Safety ทั่วทั้งแอป
  • auth.ts, course.ts: จัดเก็บ Interface หลักที่ใช้ร่วมกันระหว่าง Composable และ Components
  • index.ts: Central export สำหรับรวบรวมทุก Type ให้เรียกใช้ได้ง่ายผ่าน @/types
• Constants (constants/): แหล่งเก็บข้อมูล Static
  • landing.ts: จัดเก็บข้อมูลการตลาดและเนื้อหาคงที่ของหน้าแรก (Landing Page) เพื่อลดขนาดไฟล์ .vue

---

🧠 3. Logic & Data Layer (Composables)

รวบรวม Logic หลักแยกส่วนตามหน้าที่ (Separation of Concerns)

3.1 useAuth.ts (Authentication & User)

จัดการสถานะผู้ใช้, ล็อกอิน, และความปลอดภัย

• Key Functions: login, register, fetchUserProfile, uploadAvatar, sendVerifyEmail
• Features: Refresh Token อัตโนมัติ, ตรวจสอบ Role, Logout Logic ที่ไม่ลบข้อมูลจดจำผู้ใช้

3.2 useCourse.ts (Course & Classroom)

หัวใจหลักของการเรียนการสอน

• Catalog: fetchCourses, fetchCourseById, enrollCourse
• Classroom:
  • fetchCourseLearningInfo: โครงสร้างบทเรียน (Chapters/Lessons)
  • fetchLessonContent: เนื้อหาวิดีโอ/Quiz/Attachments
  • fetchCourseAnnouncements: ดึงข้อมูลประกาศของคอร์ส
  • saveVideoProgress: บันทึกเวลาเรียน (Sync Server)
• i18n Support: getLocalizedText ตัวช่วยในการเลือกแสดงผลภาษา (TH/EN) ตาม Locale ปัจจุบันที่ผู้ใช้เลือก อัตโนมัติทั่วทั้งแอป

3.3 useQuizRunner.ts (Quiz System)

จัดการ Logic การทำข้อสอบ (Production-Ready)

• Logic: ควบคุมการเปลี่ยนข้อ, การส่งคำตอบ, และการรับผลลัพธ์จาก API
• Cleanup: ลบ Mock delays และ Simulation logic ออกทั้งหมดเพื่อให้ทำงานร่วมกับ API จริงได้ทันที
• Type Safety: ทุก Composable เรียกใช้ Interface จาก @/types เพื่อความสอดคล้องของข้อมูล

---

🎨 4. Design System & Theming

4.1 Theme Strategy

• Framework: Tailwind CSS + Quasar UI
• Light/Dark Mode Policy:
  • Public Pages: บังคับ Light Mode (Landing, Course Detail, Auth) เพื่อภาพลักษณ์แบรนด์ที่สะอาดตา
  • Dashboard/Learning: รองรับ Dark Mode เต็มรูปแบบ (Oceanic Theme)
  • Aesthetics: ปรับปรุงความชัดเจนของ Badge, Icon และสถานะต่างๆ ในหน้าสอบ (Quiz) สำหรับโหมดมืดโดยเฉพาะ ให้มี Contrast สูงและดู Premium
• Visual Fixes: แก้ไขปัญหา "Dark Frame" ในหน้า Auth โดยการบังคับสไตล์ระดับ HTML/Body

---

📊 5. Dependency Map (ความสัมพันธ์ไฟล์)

หน้าเว็บ (Page)	Components หลัก	Composables หลัก
Login / Register	FormInput	useAuth (Remember Me), useFormValidation
Discovery (Browse)	CourseCard	useCourse (Search/Filter), useCategory
My Courses	CourseCard (with Progress)	useCourse (Certificates)
Classroom (Learning)	Video Player, Sidebar	useCourse (Progress, Announcements), useMediaPrefs
Quiz	QuizHeader, QuizContent	useQuizRunner (Real API Integration)
Profile	UserAvatar, FormInput	useAuth (Upload Avatar, Verify Email)
Global Context	GlobalLoader	useThemeMode (Theme Standard), useAuth (Root Init)

5.1 Shared Resource Architecture

• Data Flow: API -> Composable (with Types) -> Page/Component (with Constants)
• State Persistence: useCookie (Auth) + localStorage (Theme, Forget Me, Unread Badges)

---

✅ 6. Project Status (สถานะล่าสุด)

✨ Recent Updates (กุมภาพันธ์ 2026)

1. System-Wide Code Cleanup (Phase Final):

   • Refactoring: ปัดกวาดโค้ดในหน้า learning, quiz, discovery, dashboard และ profile
   • Logging: ลบ console.log มหาศาล และ logic ซ้ำซ้อนที่ตกค้างจากการพัฒนา
   • Structure: จัดกลุ่มสไตล์และฟังก์ชันให้เป็นระเบียบ อ่านง่ายขึ้นตามมาตรฐาน Clean Code

2. Authentication & Security Polish:

   • Remember Me: พัฒนาระบบจดจำอีเมลในหน้า Login ให้เสถียร (ใช้ localStorage)
   • Smart Logout: ปรับปรุง useAuth.logout ให้ลบข้อมูล Session แต่เก็บข้อมูลที่ผู้ใช้สั่งจำไว้ (อีเมล)

3. UI & Aesthetics (Premium Fixes):

   • Theme Enforcement: บังคับหน้าสาธารณะ (Landing/Auth) ให้เป็น Light Mode 100% พร้อมแก้ปัญหากรอบมืด (Dark Frame) ตกค้าง
   • Dark Mode Optimization: ปรับปรุงสีและ Contrast ในหน้า Dashboard และ Profile ให้สวยงามและอ่านง่ายขึ้นในโหมมืด

4. Quiz System Productionization:

   • useQuizRunner: แปลงร่างจาก Mock system เป็น API-Ready system (ลบ simulation logic ทั้งหมด)
   • Quiz UI: ปรับปรุงการนำทางและสถานะการทำข้อสอบให้ลื่นไหล

5. Smooth Navigation & Quiz Experience:

   • SPA Navigation: เปลี่ยนการสไลด์บทเรียนจาก Hard Reload เป็น SPA Navigation (router.push) ทำให้เรียนได้ต่อเนื่อง ไม่ต้องรอโหลดหน้าใหม่
   • Smart Lesson Loading: ปรับปรุง Error ที่หน้าเว็บชอบเด้งกลับไปบทเรียนที่ 1 เสมอ โดยเปลี่ยนให้ความสำคัญกับ lesson_id จาก URL ก่อน
   • UI Simplification: ลบทิ้ง "Legend/คำอธิบายสถานะ" ในหน้าสอบเพื่อความสะอาดตา (Minimal UI)
   • Sidebar visibility: ช่วยให้ผู้ใช้เปิด-ปิด Sidebar บน Desktop ได้อย่างอิสระผ่านปุ่ม Hamburger

6. Internationalization (i18n) Improvements:

   • Localized Text Logic: แก้ไขฟังก์ชัน getLocalizedText ให้แสดงภาษาตามที่ผู้ใช้สลับจริง (แก้ปัญหาหน้าเว็บเป็นอังกฤษแต่ชื่อวิชาเป็นไทย)
   • Hardcoded Removal: ทยอยลบข้อความภาษาไทยที่พิมพ์ค้างไว้ในโค้ด (เช่น ใน Sidebar หมวดหมู่) และแทนที่ด้วย i18n keys
   • Boot Sequence Fix: แก้ไขปัญหาเว็บค้าง (Error 500) ที่เกิดจากการเรียกใช้ภาษาเร็วเกินไปก่อนที่ระบบจะพร้อม (initialization error)

7. Classroom & UX Optimization (Mid-February 2026):

   • SPA Navigation for Learning: เปลี่ยนระบบเลือกบทเรียนจากการ Reload หน้าเป็น SPA Navigation ทำให้เปลี่ยนวิดีโอ/บทเรียนได้ทันทีโดยไม่ต้อง Refresh หน้าจอ
   • Announcement Persistence: เพิ่มระบบเช็กสถานะการอ่านประกาศ (Unread Badge) โดยบันทึกสถานะล่าสุดลง LocalStorage แยกตามผู้ใช้และคอร์ส
   • YouTube Resume: รองรับการเรียนต่อจากจุดเดิมสำหรับวิดีโอ YouTube (Time Seeking via URL parameter)

8. Quiz System Enhancements:

   • Answer Review Mode: เพิ่มโหมดเฉลยข้อสอบหลังทำเสร็จ พร้อมการไฮไลท์สีที่ชัดเจน (เขียว = ถูก, แดง = ตอบผิด)
   • Shuffle Logic: เพิ่มการสลับคำถามและตัวเลือก (Shuffle) เพื่อความโปร่งใสในการสอบ
   • Enhanced Feedback: ปรับปรุง UI ผลลัพธ์การสอบให้มีความ Premium และเข้าใจง่ายขึ้น

9. Security & Registration Polish:

   • Phone Validation: เพิ่มระบบตรวจสอบเบอร์โทรศัพท์ในหน้าสมัครสมาชิก (ต้องเป็นตัวเลขและยาวไม่เกิน 10 หลัก)
   • Enrollment Alert Logic: ปรับปรุง Logic การสมัครเรียนให้ตรวจสอบสถานะ Enrollment เดิมก่อน เพื่อป้องกัน API Error และการเรียก request ซ้ำซ้อน

10. Profile & Certificates:

    • Verification Badge: เพิ่มการแสดงผลสถานะการยืนยันอีเมลในหน้าโปรไฟล์ พร้อมปุ่มส่งอีเมลยืนยันหากยังไม่ได้ทำ
    • Certificate Flow: ปรับปรุงระบบดาวน์โหลดใบประกาศนียบัตรให้รองรับทั้งการดึงไฟล์เดิมและสั่ง Generate ใหม่หากยังไม่มี

11. Refactoring & UI System Overhaul (Late February 2026):

    • Centralized Types System: ย้าย Interface และ Type definitions ทั้งหมดออกจากไฟล์ Composable (เช่น useAuth, useCourse) ไปไว้ในโฟลเดอร์ @/types/ เพื่อลดขนาดไฟล์ Logic และเพิ่มความสามารถในการนำมาใช้ซ้ำ (Reusability)
    • Constants Extraction: แยกข้อมูล Static (เช่น รายชื่อหมวดหมู่, ข้อความหน้า Landing) ไปไว้ใน @/constants/landing.ts เพื่อให้โค้ดส่วน UI สะอาดและจัดการข้อมูลได้จากจุดเดียว
    • Mobile Master Drawer: รวบรวมเมนู Navigation, Profile, Tools (เปลี่ยนภาษา/Dark Mode) และ Logout เข้ามาไว้ใน Drawer เดียวกันบนมือถือ เพื่อความสะดวกในการใช้งานแบบ Single-Hand
    • Landing Page Redesign: ปรับโฉมส่วน "หมวดหมู่ที่น่าสนใจ" (Image 2 Style) เป็นแบบการ์ดแนวนอน (Horizontal) ที่เรียบง่าย ตัดลูกศรและคำอธิบายที่ไม่จำเป็นออกเพื่อให้ดู Minimal และ Premium มากขึ้น
    • Theming Standardization: ปรับปรุง app.vue ให้ใช้ Composable useThemeMode ในการควบคุมธีมทั้งหมดแทนการเขียน Logic แยกต่างหาก ทำให้การสลับโหมดเสถียรและแม่นยำขึ้น
    • Authentication UI Polish: เพิ่มกล่อง "Test Credentials" ในหน้า Login เพื่ออำนวยความสะดวกในการทดสอบระบบ และปรับเปลี่ยนหน้ายืนยันอีเมลให้เป็นแบบ Standalone UI (auth layout)