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

Frontend-Learner (Web) — Technical Documentation

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

อัปเดตล่าสุด: ปลายเดือนกุมภาพันธ์ 2026

---

Table of Contents

• 1. Technical Foundation
  • 1.1 Tech Stack
  • 1.2 Security & Authentication
• 2. Project Architecture
  • 2.1 Directory Structure
  • 2.2 Shared Infrastructure
• 3. Logic & Data Layer (Composables)
• 4. Branding & UI Policy
  • 4.1 Theme Strategy
  • 4.2 UI Elements
• 5. Core Feature Highlights
• 6. Maintenance & Performance Guidelines

---

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 บนมือถืออย่างสมบูรณ์

---