187 lines
16 KiB
Markdown
187 lines
16 KiB
Markdown
# 🛠️ Web Development Documentation: e-Learning Platform (Frontend)
|
|
|
|
เอกสารฉบับนี้สรุปรายละเอียดทางเทคนิค โครงสร้างโค้ด และการทำงานของระบบ **Frontend-Learner** (อัปเดตล่าสุด: กุมภาพันธ์ 2026)
|
|
|
|
---
|
|
|
|
## 🏗️ 1. Technical Foundation (รากฐานทางเทคนิค)
|
|
|
|
รวมข้อมูลเครื่องมือ, ระบบความปลอดภัย และประสิทธิภาพการทำงานไว้ด้วยกัน
|
|
|
|
### 1.1 Tech Stack
|
|
|
|
- **Core:** [Nuxt 3](https://nuxt.com) (v`^3.11.2`), TypeScript `^5.4.5`
|
|
- **UI Framework:** Quasar Framework `^2.15.2` (via `nuxt-quasar-ui ^3.0.0`)
|
|
- **Styling:** Tailwind CSS `^6.12.0` (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 หลัก (ใช้ร่วมกับ AppSidebar)
|
|
- `FormInput.vue`: Input field มาตรฐาน
|
|
- **Layout (`components/layout/`):**
|
|
- `AppSidebar.vue`: Sidebar หลักสำหรับ Dashboard (Collapsible)
|
|
- `LandingHeader.vue`: Header เฉพาะสำหรับหน้า Landing Page
|
|
- **Course (`components/course/`):**
|
|
- `CourseCard.vue`: การ์ดแสดงผลคอร์ส รองรับ Progress และ **Glassmorphism** ในโหมดมืด
|
|
- **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 และ YouTube Support
|
|
- **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
|
|
- `fetchCourseAnnouncements`: ดึงข้อมูลประกาศของคอร์ส
|
|
- `saveVideoProgress`: บันทึกเวลาเรียน (Sync Server)
|
|
- **i18n Support:** `getLocalizedText` ตัวช่วยในการเลือกแสดงผลภาษา (TH/EN) ตาม Locale ปัจจุบันที่ผู้ใช้เลือก อัตโนมัติทั่วทั้งแอป
|
|
|
|
### 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)
|
|
- **Aesthetics:** ปรับปรุงความชัดเจนของ Badge, Icon และสถานะต่างๆ ในหน้าสอบ (Quiz) สำหรับโหมดมืดโดยเฉพาะ ให้มี Contrast สูงและดู Premium
|
|
- **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. **Smooth Navigation & Quiz Experience:**
|
|
- **SPA Navigation:** เปลี่ยนการสไลด์บทเรียนจาก Hard Reload เป็น SPA Navigation (`router.push`) ทำให้เรียนได้ต่อเนื่อง ไม่ต้องรอโหลดหน้าใหม่
|
|
- **Smart Lesson Loading:** ปรับปรุง Error ที่หน้าเว็บชอบเด้งกลับไปบทเรียนที่ 1 เสมอ โดยเปลี่ยนให้ความสำคัญกับ `lesson_id` จาก URL ก่อน
|
|
- **UI Simplification:** ลบทิ้ง "Legend/คำอธิบายสถานะ" ในหน้าสอบเพื่อความสะอาดตา (Minimal UI)
|
|
- **Sidebar visibility:** ช่วยให้ผู้ใช้เปิด-ปิด Sidebar บน Desktop ได้อย่างอิสระผ่านปุ่ม Hamburger
|
|
|
|
6. **Internationalization (i18n) Improvements:**
|
|
- **Localized Text Logic:** แก้ไขฟังก์ชัน `getLocalizedText` ให้แสดงภาษาตามที่ผู้ใช้สลับจริง (แก้ปัญหาหน้าเว็บเป็นอังกฤษแต่ชื่อวิชาเป็นไทย)
|
|
- **Hardcoded Removal:** ทยอยลบข้อความภาษาไทยที่พิมพ์ค้างไว้ในโค้ด (เช่น ใน Sidebar หมวดหมู่) และแทนที่ด้วย i18n keys
|
|
- **Boot Sequence Fix:** แก้ไขปัญหาเว็บค้าง (Error 500) ที่เกิดจากการเรียกใช้ภาษาเร็วเกินไปก่อนที่ระบบจะพร้อม (`initialization error`)
|
|
|
|
7. **Classroom & UX Optimization (Mid-February 2026):**
|
|
- **SPA Navigation for Learning:** เปลี่ยนระบบเลือกบทเรียนจากการ Reload หน้าเป็น SPA Navigation ทำให้เปลี่ยนวิดีโอ/บทเรียนได้ทันทีโดยไม่ต้อง Refresh หน้าจอ
|
|
- **Announcement Persistence:** เพิ่มระบบเช็กสถานะการอ่านประกาศ (Unread Badge) โดยบันทึกสถานะล่าสุดลง LocalStorage แยกตามผู้ใช้และคอร์ส
|
|
- **YouTube Resume:** รองรับการเรียนต่อจากจุดเดิมสำหรับวิดีโอ YouTube (Time Seeking via URL parameter)
|
|
|
|
8. **Quiz System Enhancements:**
|
|
- **Answer Review Mode:** เพิ่มโหมดเฉลยข้อสอบหลังทำเสร็จ พร้อมการไฮไลท์สีที่ชัดเจน (เขียว = ถูก, แดง = ตอบผิด)
|
|
- **Shuffle Logic:** เพิ่มการสลับคำถามและตัวเลือก (Shuffle) เพื่อความโปร่งใสในการสอบ
|
|
- **Enhanced Feedback:** ปรับปรุง UI ผลลัพธ์การสอบให้มีความ Premium และเข้าใจง่ายขึ้น
|
|
|
|
9. **Security & Registration Polish:**
|
|
- **Phone Validation:** เพิ่มระบบตรวจสอบเบอร์โทรศัพท์ในหน้าสมัครสมาชิก (ต้องเป็นตัวเลขและยาวไม่เกิน 10 หลัก)
|
|
- **Enrollment Alert Logic:** ปรับปรุง Logic การสมัครเรียนให้ตรวจสอบสถานะ Enrollment เดิมก่อน เพื่อป้องกัน API Error และการเรียก request ซ้ำซ้อน
|
|
|
|
10. **Profile & Certificates:**
|
|
- **Verification Badge:** เพิ่มการแสดงผลสถานะการยืนยันอีเมลในหน้าโปรไฟล์ พร้อมปุ่มส่งอีเมลยืนยันหากยังไม่ได้ทำ
|
|
- **Certificate Flow:** ปรับปรุงระบบดาวน์โหลดใบประกาศนียบัตรให้รองรับทั้งการดึงไฟล์เดิมและสั่ง Generate ใหม่หากยังไม่มี
|