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

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

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

---

## 🏗️ 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 ตามสถานะ
- **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

---

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

### 2.1 Application Routes (`pages/`)

| Module      | ไฟล์                       | Path                    | หน้าที่                                      |
| :---------- | :------------------------- | :---------------------- | :------------------------------------------- |
| **Public**  | `index.vue`                | `/`                     | หน้าแรก Landing Page                         |
|             | `browse/discovery.vue`     | `/browse/discovery`     | **ระบบค้นหาและ Filter คอร์ส** (Catalog)      |
|             | `course/[id].vue`          | `/course/:id`           | **หน้ารายละเอียดคอร์ส** (Course Detail)      |
| **Auth**    | `auth/login.vue`           | `/auth/login`           | เข้าสู่ระบบ (รองรับ Remember Me)             |
|             | `auth/register.vue`        | `/auth/register`        | สมัครสมาชิกผู้เรียน                          |
|             | `auth/reset-password.vue`  | `/auth/reset-password`  | ตั้งรหัสผ่านใหม่ (Reset Flow)                |
| **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`       | การสอบวัดผล (Quiz System)                    |

### 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`: การ์ดแสดงผลคอร์ส (ใช้ซ้ำหลายหน้า)
- **User (`components/user/`):**
  - `UserAvatar.vue`: แสดงรูปโปรไฟล์ (รองรับ Fallback)

---

## 🧠 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

### 3.2 `useCourse.ts` (Course & Classroom)

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

- **Catalog:** `fetchCourses`, `fetchCourseById`, `enrollCourse`
- **Classroom:**
  - `fetchCourseLearningInfo`: โครงสร้างบทเรียน (Chapters/Lessons)
  - `fetchLessonContent`: เนื้อหาวิดีโอ/Quiz/Attachments
  - `saveVideoProgress`: บันทึกเวลาเรียน (Sync Server)
  - `fetchCourseAnnouncements`: ดึงประกาศในคอร์สเรียน
  - `getCertificate` / `generateCertificate`: ออกใบประกาศนียบัตร

### 3.3 `useMediaPrefs.ts` (Media Control)

จัดการการตั้งค่า Media Player

- **State:** `volume` (0-1), `muted` (boolean)
- **Functions:** `setVolume`, `setMuted`, `applyTo` (apply state to video element)

---

## 🎨 4. Design System & Theming

### 4.1 Theme Strategy

- **Framework:** Tailwind CSS + Quasar UI
- **Dark Mode:** รองรับ Class-based Dark Mode (`.dark`)
- **Fonts:**
  - **Heading:** Prompt, Sarabun (TH), Inter (EN)
  - **Body:** Sarabun (TH), Inter (EN)
  - **Handwriting:** (Optional) Dancing Script

---

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

| หน้าเว็บ (Page)          | Components หลัก              | Composables หลัก                                       |
| :----------------------- | :--------------------------- | :----------------------------------------------------- |
| **Login / Register**     | `FormInput`                  | `useAuth`, `useFormValidation`                         |
| **Discovery (Browse)**   | `CourseCard`                 | `useCourse` (Search/Filter), `useCategory`             |
| **My Courses**           | `CourseCard` (with Progress) | `useCourse` (Certificates)                             |
| **Classroom (Learning)** | Video Player, Sidebar        | `useCourse` (Progress, Announcements), `useMediaPrefs` |
| **Profile**              | `UserAvatar`, `FormInput`    | `useAuth` (Upload Avatar, Verify Email)                |

---

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

### ✨ Recent Updates (อัปเดตล่าสุด)

1.  **Code Optimization (Clean Code):**
    - **ลบ Mock Data ทั้งหมด:** หน้า `quiz`, `classroom`, `discovery` ใช้ข้อมูลจริงจาก API 100%
    - **ลบ Dead Code:** กำจัดตัวแปรที่ไม่ได้ใช้ (`currentUser` ซ้ำซ้อน, `unused intervals`) และ `console.log`

2.  **Robust Learning System (Classroom):**
    - **Hybrid Progress Saving:** ระบบบันทึกเวลาเรียนแบบลูกผสม (Local + Server) ป้องกันเวลาหายเมื่อเน็ตหลุดหรือปิดแท็บ
    - **Announcements:** เพิ่มแท็บประกาศใน Sidebar ห้องเรียน เชื่อมต่อ API `course-announcements` พร้อมแจ้งเตือน "New"
    - **Video Player:** ปรับปรุง UI Player, Volume Persistence (`useMediaPrefs`)

3.  **i18n & Configuration:**
    - **Path Correction:** แก้ไข `nuxt.config.ts` ให้เรียกไฟล์ภาษาจาก `i18n/locales/` ได้ถูกต้อง
    - **Consistency:** เพิ่มคีย์ภาษาที่ขาดหาย (เช่น `common.close`) ใน `en.json`

4.  **Enrollment & User Experience:**
    - **Smart Enrolled Filter:** หน้า "คอร์สของฉัน" Tab "กำลังเรียน" แสดงทั้งคอร์สที่เพิ่งลงทะเบียน (`ENROLLED`) และกำลังเรียน (`IN_PROGRESS`)
    - **Certificate System:** ระบบดาวน์โหลด/สร้างใบประกาศฯ อัตโนมัติเมื่อเรียนจบ

5.  **Profile & Security:**
    - **Email Verification:** ปุ่มยืนยันอีเมลและสถานะในหน้าโปรไฟล์
    - **Avatar Upload:** อัปโหลดรูปภาพพร้อม Preview และ Validation (Size/Type)