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](https://nuxt.com) (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`: ฟอร์มเปลี่ยนรหัสผ่าน

---

## 🧠 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 จริงได้ทันที

---

## 🎨 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)                |

---

## ✅ 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 ใหม่หากยังไม่มี