No changes were provided to summarize.
This commit is contained in:
supalerk-ar66
parent
2e0675f1c9
commit
4461c1d119
1 changed files with 94 additions and 115 deletions
|
|
@ -1,6 +1,6 @@
|
|||
# 🛠️ Web Development Documentation: e-Learning Platform (Frontend)
|
||||
|
||||
เอกสารฉบับนี้สรุปรายละเอียดทางเทคนิค โครงสร้างโค้ด และการทำงานของระบบ **Frontend-Learner**
|
||||
เอกสารฉบับนี้สรุปรายละเอียดทางเทคนิค โครงสร้างโค้ด และการทำงานของระบบ **Frontend-Learner** (อัปเดตล่าสุด)
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -11,17 +11,24 @@
|
|||
### 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)
|
||||
- **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:** ระบบ Auth ผูกกับ API โดยมี Middleware (`middleware/auth.ts`) คอยป้องกันการเข้าถึง Route เฉพาะ
|
||||
- **API Handling:** ใช้ `runtimeConfig.public.apiBase` จัดการ Base URL และ Auto-attach Bearer Token ใน Composables
|
||||
- **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:**
|
||||
- **Caching:** ใช้ `useState` จำข้อมูล (User Profile, Courses, Categories) เพื่อลด request ซ้ำซ้อน
|
||||
- **Request Deduping:** ป้องกันการเรียก API เดิมซ้ำๆ ในเวลาเดียวกัน
|
||||
- **Hybrid Progress Saving:** บันทึกเวลาเรียนลง LocalStorage (ถี่) และ Server (Throttle 15s) เพื่อความแม่นยำสูงสุด
|
||||
- **Caching:** ใช้ `useState` จำข้อมูล Profile และ Categories ลด request
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -29,140 +36,112 @@
|
|||
|
||||
### 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` | การสอบวัดผล |
|
||||
| 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 Reusable Components (`components/`)
|
||||
### 2.2 Key Components (`components/`)
|
||||
|
||||
- **Layout:** `AppHeader.vue`, `AppSidebar.vue`, `MobileNav.vue` (Navigation หลัก)
|
||||
- **Common:** `FormInput.vue` (ฟอร์ม), `LoadingSpinner.vue` (สถานะโหลด), `LanguageSwitcher.vue` (เปลี่ยนภาษา)
|
||||
- **Modules:** `CourseCard.vue` (แสดงผลคอร์สแบบ Grid), `UserAvatar.vue` (รูปโปรไฟล์)
|
||||
- **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 + API)
|
||||
## 🧠 3. Logic & Data Layer (Composables)
|
||||
|
||||
รวบรวม Logic และ API Endpoint ที่เกี่ยวข้องไว้ในที่เดียวเพื่อความเข้าใจง่าย
|
||||
รวบรวม Logic หลักแยกส่วนตามหน้าที่ (Separation of Concerns)
|
||||
|
||||
### 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`: อัปโหลดรูปโปรไฟล์
|
||||
- `POST /api/user/send-verify-email`: ส่งอีเมลยืนยันตัวตน
|
||||
- **Key Functions:** `login`, `register`, `fetchUserProfile`, `uploadAvatar`, `sendVerifyEmail`
|
||||
- **Features:** Refresh Token อัตโนมัติ, ตรวจสอบ Role
|
||||
|
||||
### 3.2 `useCourse.ts` (Course & Learning)
|
||||
### 3.2 `useCourse.ts` (Course & Classroom)
|
||||
|
||||
หัวใจหลักของการเรียนการสอน ตั้งแต่หน้ารายการคอร์สจนถึงห้องเรียน
|
||||
หัวใจหลักของการเรียนการสอน
|
||||
|
||||
- **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)
|
||||
- `GET /api/certificates/{courseId}`: ดึงใบประกาศนียบัตร
|
||||
- `POST /api/certificates/{courseId}/generate`: สร้างใบประกาศนียบัตรใหม่
|
||||
- **Catalog:** `fetchCourses`, `fetchCourseById`, `enrollCourse`
|
||||
- **Classroom:**
|
||||
- `fetchCourseLearningInfo`: โครงสร้างบทเรียน (Chapters/Lessons)
|
||||
- `fetchLessonContent`: เนื้อหาวิดีโอ/Quiz/Attachments
|
||||
- `saveVideoProgress`: บันทึกเวลาเรียน (Sync Server)
|
||||
- `fetchCourseAnnouncements`: ดึงประกาศในคอร์สเรียน
|
||||
- `getCertificate` / `generateCertificate`: ออกใบประกาศนียบัตร
|
||||
|
||||
### 3.3 `useCategory.ts` & Utilities
|
||||
### 3.3 `useMediaPrefs.ts` (Media Control)
|
||||
|
||||
- `fetchCategories`: ดึงหมวดหมู่ (`GET /api/categories`) สำหรับตัวกรองหน้า Discovery
|
||||
- `useFormValidation.ts`: รวม RegEx สำหรับตรวจสอบ Email, Password เบื้องต้น
|
||||
จัดการการตั้งค่า Media Player
|
||||
|
||||
- **State:** `volume` (0-1), `muted` (boolean)
|
||||
- **Functions:** `setVolume`, `setMuted`, `applyTo` (apply state to video element)
|
||||
|
||||
---
|
||||
|
||||
## 🎨 4. Design System & Theming
|
||||
|
||||
### 4.1 Dark Mode Strategy
|
||||
### 4.1 Theme 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)
|
||||
- **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
|
||||
|
||||
---
|
||||
|
||||
## 6. Dependency Map & Relationships (แผนผังความสัมพันธ์ไฟล์)
|
||||
## 📊 5. Dependency Map (ความสัมพันธ์ไฟล์)
|
||||
|
||||
ส่วนนี้ใช้อ้างอิงเวลาแก้ไขโค้ด เพื่อดูว่าไฟล์ไหนเชื่อมโยงหรือถูกเรียกใช้โดยไฟล์ใดบ้าง (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 ทั้งเว็บ
|
||||
| หน้าเว็บ (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) |
|
||||
|
||||
---
|
||||
|
||||
## <EFBFBD>📊 7. Project Status (สถานะการพัฒนา)
|
||||
## ✅ 6. Project Status (สถานะล่าสุด)
|
||||
|
||||
### ✅ Completed Updates (สิ่งที่ทำเสร็จแล้ว)
|
||||
### ✨ Recent 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
|
||||
7. **UX/UI Improvements (My Courses & Enroll):**
|
||||
- **My Courses:** แสดง Progress Bar ถูกต้อง (ดึง `progress_percentage`) และปรับ Filter "กำลังเรียน" ให้แสดงคอร์สใหม่ (`ENROLLED`) ด้วย
|
||||
- **Enrollment Flow:** แก้ไขปุ่ม "เริ่มเรียนทันที" ใน Modal ให้ลิงก์ไปยังคอร์สที่ถูกต้อง (ส่ง `course_id` param)
|
||||
- **Auth:** เพิ่มฟังก์ชัน **"จดจำฉัน" (Remember Me)** ในหน้า Login เพื่อจำ Email ผู้ใช้
|
||||
8. **Certificates System:**
|
||||
- เชื่อมต่อ API ดึงใบประกาศนียบัตร (`GET /api/certificates/{courseId}`) และสร้างใหม่ (`POST .../generate`)
|
||||
- ระบบ **Smart Download:** เช็คก่อนว่ามีไฟล์ไหม ถ้าไม่มีถึงสร้างใหม่ แล้วเปิด PDF ทันที
|
||||
- รองรับการแสดงผลภาษาไทยและวันที่ถูกต้องแบบ Real-time API
|
||||
9. **Email Verification:**
|
||||
- เพิ่มระบบส่งอีเมลยืนยันตัวตน (`POST /api/user/send-verify-email`)
|
||||
- ปุ่มกดส่งยืนยันในหน้าโปรไฟล์ (`profile.vue`) พร้อมจัดการสถานะ (Already Verified)
|
||||
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)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue