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`
- **Styling:** Tailwind CSS (Utility) + Vanilla CSS Variables (Theming)
- **State:** `ref`/`reactive` (Local) + `useState` (Global/Shared State)
- **Localization:** `@nuxtjs/i18n` (TH/EN Support)

### 1.2 Core Systems & Security

- **Authentication:** ระบบ Auth ผูกกับ API โดยมี Middleware (`middleware/auth.ts`) คอยป้องกันการเข้าถึง Route เฉพาะ
- **API Handling:** ใช้ `runtimeConfig.public.apiBase` จัดการ Base URL และ Auto-attach Bearer Token ใน Composables
- **Performance:**
  - **Caching:** ใช้ `useState` จำข้อมูล (User Profile, Courses, Categories) เพื่อลด request ซ้ำซ้อน
  - **Request Deduping:** ป้องกันการเรียก API เดิมซ้ำๆ ในเวลาเดียวกัน

---

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

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

| Module      | ไฟล์                       | Path                    | หน้าที่                      |
| :---------- | :------------------------- | :---------------------- | :--------------------------- |
| **Public**  | `index.vue`                | `/`                     | หน้าแรก Landing Page         |
|             | `browse/index.vue`         | `/browse`               | หน้ารวมคอร์สทั้งหมด          |
|             | `browse/discovery.vue`     | `/browse/discovery`     | **ระบบค้นหาและ Filter**      |
|             | `course/[id].vue`          | `/course/:id`           | **หน้ารายละเอียดคอร์ส**      |
| **Auth**    | `auth/login.vue`           | `/auth/login`           | เข้าสู่ระบบ                  |
|             | `auth/register.vue`        | `/auth/register`        | สมัครสมาชิกผู้เรียน          |
| **Student** | `dashboard/index.vue`      | `/dashboard`            | แดชบอร์ดภาพรวม               |
|             | `dashboard/my-courses.vue` | `/dashboard/my-courses` | คอร์สของฉัน                  |
|             | `classroom/learning.vue`   | `/classroom/learning`   | **ห้องเรียน (Video Player)** |
|             | `classroom/quiz.vue`       | `/classroom/quiz`       | การสอบวัดผล                  |

### 2.2 Reusable Components (`components/`)

- **Layout:** `AppHeader.vue`, `AppSidebar.vue`, `MobileNav.vue` (Navigation หลัก)
- **Common:** `FormInput.vue` (ฟอร์ม), `LoadingSpinner.vue` (สถานะโหลด), `LanguageSwitcher.vue` (เปลี่ยนภาษา)
- **Modules:** `CourseCard.vue` (แสดงผลคอร์สแบบ Grid), `UserAvatar.vue` (รูปโปรไฟล์)

---

## 🧠 3. Logic & Data Layer (Composables + API)

รวบรวม Logic และ API Endpoint ที่เกี่ยวข้องไว้ในที่เดียวเพื่อความเข้าใจง่าย

### 3.1 `useAuth.ts` (Authentication & User)

จัดการสถานะผู้ใช้, ล็อกอิน, และข้อมูลส่วนตัว

- **Endpoints:**
  - `GET /api/user/me`: ดึงข้อมูลโปรไฟล์ (Cached)
  - `PUT /api/user/me`: อัปเดตข้อมูลส่วนตัว
  - `POST /api/user/change-password`: เปลี่ยนรหัสผ่าน
  - `POST /api/user/upload-avatar`: อัปโหลดรูปโปรไฟล์

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

หัวใจหลักของการเรียนการสอน ตั้งแต่หน้ารายการคอร์สจนถึงห้องเรียน

- **Course Catalog Endpoints:**
  - `GET /api/courses`: ดึงคอร์สทั้งหมด (Cached)
  - `GET /api/courses/{id}`: ดึงรายละเอียดคอร์ส
  - `POST /api/students/courses/{id}/enroll`: ลงทะเบียนเรียน
- **Classroom Endpoints:**
  - `GET /api/students/courses`: ดึง "คอร์สของฉัน"
  - `GET /api/students/courses/{id}/learn`: ดึงโครงสร้างบทเรียน (Syllabus)
  - `GET /api/students/courses/{id}/lessons/{lessonId}`: ดึงวิดีโอเนื้อหา
  - `GET /api/students/courses/{id}/lessons/{lessonId}/access-check`: ตรวจสอบสิทธิ์การเข้าถึงบทเรียน
  - `POST /api/students/lessons/{lessonId}/progress`: บันทึกเวลาเรียน (Video Progress)
  - `GET /api/students/lessons/{lessonId}/progress`: ดึงเวลาเรียนล่าสุด
  - `POST /api/students/courses/{id}/lessons/{lessonId}/complete`: บันทึกว่าเรียนจบแล้ว
  - `POST /api/students/courses/{id}/lessons/{lessonId}/quiz/submit`: ส่งคำตอบแบบทดสอบ (Quiz)

### 3.3 `useCategory.ts` & Utilities

- `fetchCategories`: ดึงหมวดหมู่ (`GET /api/categories`) สำหรับตัวกรองหน้า Discovery
- `useFormValidation.ts`: รวม RegEx สำหรับตรวจสอบ Email, Password เบื้องต้น

---

## 🎨 4. Design System & Theming

### 4.1 Dark Mode Strategy

ระบบใช้ **Class-based Dark Mode** ของ Tailwind ผสมกับ CSS Variables:

- **Backgrounds:** `bg-slate-50` (Light) vs `bg-slate-900` (Dark)
- **Text Visibility Rule (New):**
  - ใช้ **Utility Classes** ระบุสีตรงๆ แทนตัวแปร CSS ในจุดสำคัญเพื่อป้องกันสีเพี้ยน
  - Ex: `<h1 class="text-slate-900 dark:text-white">`
- **Fonts:** Prompt (Headings), Sarabun (Body)

---

## 6. Dependency Map & Relationships (แผนผังความสัมพันธ์ไฟล์)

ส่วนนี้ใช้อ้างอิงเวลาแก้ไขโค้ด เพื่อดูว่าไฟล์ไหนเชื่อมโยงหรือถูกเรียกใช้โดยไฟล์ใดบ้าง (Impact Analysis)

### 6.1 Page Dependencies (หน้าเว็บหลักใช้อะไรบ้าง)

| Page (หน้าเว็บ)                    | Components used (ส่วนประกอบที่ใช้)          | Composables used (Logic & API ที่ใช้)                 |
| :--------------------------------- | :------------------------------------------ | :---------------------------------------------------- |
| **`pages/index.vue`** (Landing)    | `LandingHeader`, `CourseCard`               | `useAuth`, `useCourse` (fetchCourses)                 |
| **`pages/browse/discovery.vue`**   | `CourseCard`, `FormInput`, `LoadingSpinner` | `useCategory` (Filter), `useCourse` (Search/List)     |
| **`pages/course/[id].vue`**        | `LoadingSpinner`, `UserAvatar` (Instructor) | `useCourse` (Detail, Enroll), `useAuth` (User Status) |
| **`pages/classroom/learning.vue`** | `AppSidebar` (Curriculum), `GlobalLoader`   | `useCourse` (Video, Progress), `useThemeMode`         |
| **`pages/dashboard/index.vue`**    | `CourseCard` (Recommended), `UserAvatar`    | `useAuth` (Profile), `useCourse` (My Courses)         |
| **`pages/auth/*.vue`** (Login/Reg) | `FormInput`, `LanguageSwitcher`             | `useAuth` (Login/Register), `useFormValidation`       |

### 6.2 Key Components Dependencies (Component นี้ถูกใช้ที่ไหน)

- **`CourseCard.vue`** ถูกใช้ใน:
  - `pages/index.vue` (Recommended)
  - `pages/browse/index.vue` (Catalog List)
  - `pages/browse/discovery.vue` (Search Result)
  - `pages/dashboard/index.vue` (Dashboard Recommend)
  - `pages/dashboard/my-courses.vue` (My Course List)

- **`FormInput.vue`** ถูกใช้ใน:
  - `pages/auth/*` (Login, Register, Forgot Password)
  - `pages/dashboard/profile.vue` (Edit Profile)

### 6.3 Composable Usage (Logic นี้ใครเรียกใช้บ้าง)

- **`useAuth.ts`** -> ถูกเรียกใช้เกือบทุกหน้าที่มีการเช็ค User, Logout, หรือแสดงชื่อ
- **`useCourse.ts`** -> ถูกเรียกใช้ในหน้า Browse, Course Detail, Classroom, Dashboard
- **`useThemeMode.ts`** -> ถูกเรียกใช้ใน `layouts/default.vue` เพื่อคุม Theme ทั้งเว็บ

---

## <20>📊 7. Project Status (สถานะการพัฒนา)

### ✅ Completed Updates (สิ่งที่ทำเสร็จแล้ว)

1.  **Code Cleanup:** ลบไฟล์ขยะ (Mock Data pages) ออกจากระบบ
2.  **Theme Refinement:** แก้ไขปัญหาการแสดงผล Text Color ใน Light/Dark Mode หน้า `learning.vue` และ `discovery.vue` เสร็จสมบูรณ์
3.  **API Integration:** เชื่อมต่อระบบหลักครบถ้วน (Auth, Course, Enroll, Learning Progress)
4.  **Localization:** รองรับภาษาไทยสมบูรณ์พร้อมคำอธิบายโค้ด
5.  **Profile Avatar:** ระบบอัปโหลดรูปโปรไฟล์จริง (`/api/user/upload-avatar`) พร้อมแสดงผลทันทีแบบ Real-time และการจัดการสถานะ (Upload/Change)
6.  **Quiz System Integrations:**
    - เชื่อมต่อ API ส่งคำตอบ (`/api/.../quiz/submit`) และแสดงผลคะแนน
    - ระบบคำนวณคะแนนและสถานะ Pass/Fail จาก Server จริง
    - แก้ไขปัญหา Cache ฯ หน้าเรียน (`learning.vue`) ให้แสดงสถานะ "เรียนจบ" (✅) ทันทีที่สอบผ่าน โดยใช้ Timestamp Query (`?_t=...`) และ Watcher Logic

### 🚀 Pending / Future Work (สิ่งที่ต้องทำต่อ)

1.  **Advanced Features:** ระบบ Reviews/Rating คอร์สเรียน
2.  **Certificates:** ระบบดาวน์โหลดใบประกาศนียบัตร (ข้อมูล Backend พร้อมแล้ว รอเชื่อมต่อ UI)
3.  **Payment Gateway:** (ถ้ามีในอนาคต)

---