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

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

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

---

## 🚀 1. Tech Stack & Tools

เครื่องมือและเทคโนโลยีหลักที่ใช้ในการพัฒนาระบบ:

- **Core Framework:** [Nuxt 3](https://nuxt.com) (Vue 3 Composition API)
- **Language:** TypeScript `^5.0`
- **Styling Engine:**
  - **Tailwind CSS:** สำหรับ Utility classes ส่วนใหญ่
  - **Vanilla CSS / CSS Variables:** สำหรับ Design Tokens และ Theming (Dark/Light mode)
- **State Management:**
  - `ref`, `reactive` (Local Component State)
  - `Composables` (Global State Logic)
- **Internationalization:** `@nuxtjs/i18n` (รองรับภาษา TH / EN)
- **UI Architecture:**
  - **Atomic Design-ish:** แยก Components เป็นส่วนย่อยที่นำกลับมาใช้ใหม่ได้
  - **Slots & Props:** ออกแบบให้ยืดหยุ่นสูง

---

## 📂 2. Project Structure (โครงสร้างไฟล์)

โครงสร้างโฟลเดอร์ถูกจัดระเบียบตามหน้าที่การทำงาน (Feature-based grouping):

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

กำหนดเส้นทาง URL ของเว็บไซต์:

| Module        | ไฟล์ (File)                   | Path URL           | หน้าที่ (Description)                                  |
| :------------ | :---------------------------- | :----------------- | :----------------------------------------------------- |
| **Landing**   | `index.vue`                   | `/`                | หน้าแรกบุคคลทั่วไป (Hero Section, Features)            |
| **Auth**      | `auth/login.vue`              | `/auth/login`      | หน้าเข้าสู่ระบบ                                        |
|               | `auth/register.vue`           | `/auth/register`   | **หน้าสมัครสมาชิก** (อัปเดต Endpoint ถูกต้อง)          |
|               | `auth/forgot-password.vue`    | `/auth/forgot..`   | หน้าลืมรหัสผ่าน                                        |
|               | `auth/reset-password.vue`     | `/auth/reset..`    | หน้าตั้งรหัสใหม่                                       |
| **Dashboard** | `dashboard/index.vue`         | `/dashboard`       | หน้าหลักผู้เรียน (Overall Progress, Recommend)         |
|               | `dashboard/my-courses.vue`    | `/dashboard/my..`  | **คอร์สของฉัน** (ดึงข้อมูลจริงจาก API)                 |
|               | `dashboard/profile.vue`       | `/dashboard/pro..` | หน้าแก้ไขข้อมูลส่วนตัว                                 |
|               | `dashboard/announcements.vue` | `/dashboard/ann..` | หน้าประกาศข่าวสาร                                      |
| **Catalog**   | `browse/index.vue`            | `/browse`          | หน้ารวมคอร์สแบบ Public                                 |
|               | `browse/discovery.vue`        | `/browse/disc..`   | **หน้าค้นหาคอร์ส** (Filter, Search, API Integration)   |
| **Course**    | `course/[id].vue`             | `/course/:id`      | **รายละเอียดคอร์ส** (Enroll, Syllabus, Dynamic)        |
| **Classroom** | `classroom/learning.vue`      | `/classroom/lea..` | **ห้องเรียนออนไลน์** (Video Player, Progress Tracking) |
|               | `classroom/quiz.vue`          | `/classroom/quiz`  | ระบบสอบวัดผล (Placeholder for API integration)         |

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

ชิ้นส่วน UI ที่ใช้ซ้ำได้บ่อย:

- **Layout & Navigation:**
  - `AppHeader.vue`, `AppSidebar.vue`: ส่วนหัวและเมนูหลัก
  - `LanguageSwitcher.vue`: ปุ่มเปลี่ยนภาษา
  - `UserMenu.vue`, `MobileNav.vue`: เมนูผู้ใช้และ Mobile Menu
- **Display & Content:**
  - `CourseCard.vue`: **Smart Card** updated link to `/course/:id`
  - `UserAvatar.vue`: รูปโปรไฟล์พร้อม Fallback
- **Common:**
  - `FormInput.vue`: Input Field พร้อม Validation styles
  - `LoadingSpinner.vue`, `LoadingSkeleton.vue`: Loading states

### 2.3 `composables/` (Core Logic & API)

ศูนย์รวม Logic ของระบบ (Business Logic Layer):

| Composable             | หน้าที่หลัก (Responsibilities)                                                      |
| :--------------------- | :---------------------------------------------------------------------------------- |
| `useAuth.ts`           | **Auth Management:** Login (Student Only), Register (`/register-learner`), Reset PW |
| `useCourse.ts`         | **Course Management:** Fetch Courses, Course Detail, Encode, Progress               |
| `useCategory.ts`       | **Category Management:** ดึงหมวดหมู่สำหรับ Filter                                   |
| `useFormValidation.ts` | Helper สำหรับตรวจสอบความถูกต้องของฟอร์ม (RegEx validations)                         |

### 2.4 API Integration Points (Verified Endpoints)

รายการ API ที่มีการเชื่อมต่อและตรวจสอบแล้วว่าใช้งานได้จริง:

#### **User (`useAuth.ts`)**

| Endpoint                    | Method | Function Name       | Description                          |
| :-------------------------- | :----- | :------------------ | :----------------------------------- |
| `/api/user/me`              | GET    | `fetchUserProfile`  | ดึงข้อมูลโปรไฟล์ผู้ใช้ปัจจุบัน       |
| `/api/user/me`              | PUT    | `updateUserProfile` | อัปเดตข้อมูลส่วนตัว (ชื่อ, เบอร์โทร) |
| `/api/user/change-password` | POST   | `changePassword`    | เปลี่ยนรหัสผ่าน                      |

#### **CoursesStudent (`useCourse.ts`)**

| Endpoint                                                           | Method | Function Name             | Description                                 |
| :----------------------------------------------------------------- | :----- | :------------------------ | :------------------------------------------ |
| `/api/students/courses/{courseId}/enroll`                          | POST   | `enrollCourse`            | ลงทะเบียนเรียนคอร์ส                         |
| `/api/students/courses`                                            | GET    | `fetchEnrolledCourses`    | ดึงรายชื่อคอร์สที่ลงทะเบียนแล้ว (My Course) |
| `/api/students/courses/{courseId}/learn`                           | GET    | `fetchCourseLearningInfo` | ดึงโครงสร้างบทเรียนสำหรับการเรียน           |
| `/api/students/courses/{courseId}/lessons/{lessonId}`              | GET    | `fetchLessonContent`      | ดึงเนื้อหาบทเรียน (วิดีโอ)                  |
| `/api/students/courses/{courseId}/lessons/{lessonId}/access-check` | GET    | `checkLessonAccess`       | ตรวจสอบสิทธิ์การเข้าเรียน                   |
| `/api/students/lessons/{lessonId}/progress`                        | POST   | `saveVideoProgress`       | บันทึกเวลาที่ดูวิดีโอ (Progress)            |
| `/api/students/lessons/{lessonId}/progress`                        | GET    | `fetchVideoProgress`      | ดึงเวลาที่ดูวิดีโอล่าสุด                    |
| `/api/students/courses/{courseId}/lessons/{lessonId}/complete`     | POST   | `markLessonComplete`      | มาร์คว่าเรียนจบบทเรียนแล้ว                  |

#### **Courses (`useCourse.ts`)**

| Endpoint            | Method | Function Name     | Description                             |
| :------------------ | :----- | :---------------- | :-------------------------------------- |
| `/api/courses`      | GET    | `fetchCourses`    | ดึงรายชื่อคอร์สทั้งหมด (Public Catalog) |
| `/api/courses/{id}` | GET    | `fetchCourseById` | ดึงรายละเอียดคอร์ส (Public)             |

#### **Categories (`useCategory.ts`)**

| Endpoint          | Method | Function Name     | Description        |
| :---------------- | :----- | :---------------- | :----------------- |
| `/api/categories` | GET    | `fetchCategories` | ดึงหมวดหมู่ทั้งหมด |

---

## 🔐 3. Security & Core Systems

- **Middleware (`middleware/auth.ts`):** ดักจับ Route ป้องกันไม่ให้ผู้ที่ยังไม่ล็อกอินเข้าถึง Dashboard/Classroom
- **API Integration:**
  - Base URL from `runtimeConfig.public.apiBase`
  - Authentication headers (Bearer Token) handled in composables
- **Localization (`i18n/`):**
  - แยกไฟล์ภาษาชัดเจน: `locales/th.json`, `locales/en.json`
  - Helper Function: `getLocalizedText` สำหรับเลือกภาษาจาก API Response (`{ th, en }`)
- **Theming:** รองรับ Dark Mode สมบูรณ์แบบ (Tailwind `dark:` classes + CSS Variables)

---

## 🎨 4. Theme & Styling Guide (แนวทางการออกแบบ)

เพื่อให้การพัฒนาในอนาคตเป็นระเบียบและส่งต่อได้ง่าย ระบบมีการจัดการ CSS ดังนี้:

### 4.1 การจัดการ Dark Mode

ระบบใช้การสลับคลาส `.dark` ที่ `<html>` tag โดยอ้างอิงตัวแปรจาก `assets/css/main.css`:

- **Main Background (`--bg-body`):**
  - Light: `#f8fafc` (Slate 50)
  - Dark: `#0f172a` (Slate 900)
- **Surface/Card Background (`--bg-surface`):**
  - Light: `#ffffff`
  - Dark: `#1e293b` (Slate 800)
- **Text Primary (`--text-main`):**
  - Light: `#0f172a` (Slate 900)
  - Dark: `#f8fafc` (Slate 50)
- **Border Color (`--border-color`):**
  - Light: `#e2e8f0` (Slate 200)
  - Dark: `#334155` (Slate 700)

### 4.2 มาตรฐานการเขียน CSS

1. **ใช้ Tailwind `dark:` เสมอ:** เมื่อต้องการกำหนดสไตล์เฉพาะโหมดมืด (เช่น `dark:bg-slate-800`).
2. **ใช้ CSS Variables:** สำหรับค่าสเตติกที่ใช้ทั้งเว็บ (เช่น `color: var(--primary)`).
3. **ฟอนต์:** ระบบใช้ **"Prompt"** สำหรับหัวข้อและตัวเน้น และ **"Sarabun"** สำหรับเนื้อหาภาษาไทยเพื่อให้พรีเมียมและอ่านง่าย.

---

## ⚡ 5. Performance & Caching (ระบบจัดการความเร็ว)

เพื่อป้องกันปัญหา **429 Too Many Requests** และเพิ่มความเร็ว ระบบมีการทำ **Client-side Caching** ในระดับ Composables:

- **State Management:** ใช้ `useState()` ของ Nuxt เพื่อเก็บข้อมูลในหน่วยความจำ (Shared Memory).
- **Cached Endpoints:**
  - `fetchUserProfile`: โหลดเพียงครั้งเดียวเมื่อแอปเริ่มต้น (หรือเมื่อสั่ง Force Refresh).
  - `fetchCategories`: โหลดครั้งเดียวและแชร์ใช้ข้ามหน้า.
  - `fetchCourses`: เก็บรายชื่อคอร์สทั้งหมดเพื่อลดภาระ Server ในการเปลี่ยนหน้าไปมา.
- **Request Deduping:** มีระบบเช็คสถานะ Loading เพื่อป้องกันการยิง API ตัวเดียวกันซ้ำซ้อนพร้อมกันหลายที่.

---

## 🆕 6. Recent Updates (บันทึกการอัปเดตล่าสุด)

### ✅ Phase 1: Authentication & UI Refactor

- ย้ายระบบ Auth เข้า Module `pages/auth/`
- **Correction:** อัปเดต Endpoint สมัครสมาชิกเป็น `/api/auth/register-learner` ให้ตรงกับ Backend
- ปรับปรุง UI หน้า Register (Dark Theme Consistency)
- ลบ Comments และ Code ที่ไม่ได้ใช้งานออก (Code Cleanup)

### ✅ Phase 2: Course Discovery & Detail

- **Course Detail Page (`pages/course/[id].vue`):**
  - ปรับ Layout ให้เหมือนหน้า Discovery
  - แสดง Course Syllabus (Chapters & Lessons) แบบ Dynamic
  - เพิ่มปุ่ม "Enroll Now" ที่ทำงานจริง เชื่อมต่อ `useCourse().enrollCourse`
  - แก้ไข TypeScript Error ในการคำนวณลำดับบทเรียน
- **Discovery Page (`pages/browse/discovery.vue`):**
  - อัปเดตการ์ดคอร์สให้ลิงก์ไปยังหน้ารายละเอียดคอร์ส (`/course/:id`) แทน Modal หรือหน้า Static
  - ลบ Mock Data ออก เพื่อรองรับข้อมูลจริงจาก API

### ✅ Phase 3: Full Learning Experience & Documentation (Current)

- **Documentation & Localization:**
  - **Added Thai Code Comments:** เพิ่มคำอธิบายภาษาไทยในไฟล์สำคัญ (`nuxt.config.ts`, `useAuth`, `useCourse`, `useCategory`, `auth middleware`, `pages/index`, `app.vue`, `layouts/default`) เพื่อช่วยให้ทีมพัฒนาเข้าใจโค้ดได้ง่ายขึ้น
  - **API Verification:** ยืนยันความถูกต้องของการเชื่อมต่อ API ครบทุก Endpoints หลัก (User, Courses, Enroll, Learning, Categories)
- **UI Enhancements:**
  - ปรับปรุงหน้า `dashboard/index.vue` ให้ลิงก์ถูกต้อง
  - ปรับแก้ UI เล็กน้อยในหน้า Landing (`index.vue`) และ Browse (`browse/index.vue`)

---

## 🔍 7. Status & Missing Integrations (ส่วนที่ต้องพัฒนาต่อ)

จากการตรวจสอบล่าสุด รายการดังต่อไปนี้ยังเป็นส่วนที่รอการพัฒนา (Pending):

1.  **Quiz System 🔴 (สำคัญมาก):** หน้า `classroom/quiz.vue` ปัจจุบันเคลียร์ Mock Data แล้ว รอ API:
    - `GET /api/quizzes/:id` (ดึงโจทย์)
    - `POST /api/quizzes/:id/submit` (ส่งคำตอบ)
2.  **Dashboard Statistics:** `dashboard/index.vue` หน้า Overview ยังอาจต้องเชื่อมต่อ API stats เพิ่มเติม (เช่น Last Access Course)
3.  **Certificates:** ยังไม่มีหน้าดาวน์โหลดใบประกาศ
4.  **Reviews & Ratings:** การแสดงดาวและคอมเมนต์ยังเป็น Static Data หรือ Placeholder
5.  **Profile Image Upload:** ระบบแก้ไขโปรไฟล์ยังไม่รองรับการอัปโหลดรูปภาพจริง (ปัจจุบันแก้ได้แค่ Text Data)

---