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

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

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

---

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

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

### 1.1 Tech Stack

- **Core:** [Nuxt 3](https://nuxt.com) (Vue 3 Composition API), TypeScript `^5.0`
- **UI Framework:** Quasar Framework (via `nuxt-quasar-ui`)
- **Styling:** Tailwind CSS (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 หลัก
  - `FormInput.vue`: Input field มาตรฐาน
- **Course (`components/course/`):**
  - `CourseCard.vue`: การ์ดแสดงผลคอร์ส (ใช้ซ้ำหลายหน้า)
- **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
- **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
  - `saveVideoProgress`: บันทึกเวลาเรียน (Sync Server)

### 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)
- **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.  **Performance & Stability:**
    - แก้ไขปัญหาการเชื่อมต่อ Media (`ERR_CONNECTION_FAILED`) ผ่านการปรับปรุง config
    - ปรับปรุงการโหลดข้อมูลเบื้องหลังด้วย `useAsyncData` ให้มีความเสถียรมากขึ้น