215 lines
16 KiB
Markdown
215 lines
16 KiB
Markdown
# 🛠️ 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)
|
|
|
|
---
|