feat: Disable chat input and button while a response is being generated.

This commit is contained in:
supalerk-ar66 2026-01-27 14:34:39 +07:00
parent 52a013f431
commit 67b7de7cd2

View file

@ -1,215 +1,116 @@
# 🛠️ Web Development Documentation: e-Learning Platform (Frontend)
เอกสารฉบับนี้สรุปรายละเอียดทางเทคนิค โครงสร้างโค้ด และการทำงานของระบบ **Frontend-Learner** เพื่อความสะดวกในการพัฒนาต่อและส่งมอบงาน
เอกสารฉบับนี้สรุปรายละเอียดทางเทคนิค โครงสร้างโค้ด และการทำงานของระบบ **Frontend-Learner**
---
## 🚀 1. Tech Stack & Tools
## 🏗️ 1. Technical Foundation (รากฐานทางเทคนิค)
เครื่องมือและเทคโนโลยีหลักที่ใช้ในการพัฒนาระบบ:
รวมข้อมูลเครื่องมือ, ระบบความปลอดภัย และประสิทธิภาพการทำงานไว้ด้วยกัน
- **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:** ออกแบบให้ยืดหยุ่นสูง
### 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. Project Structure (โครงสร้างไฟล์)
## 📂 2. Frontend Structure (โครงสร้างหน้าเว็บและ UI)
โครงสร้างโฟลเดอร์ถูกจัดระเบียบตามหน้าที่การทำงาน (Feature-based grouping):
### 2.1 Application Routes (`pages/`)
### 2.1 `pages/` (Application Routes)
| 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` | การสอบวัดผล |
กำหนดเส้นทาง URL ของเว็บไซต์:
### 2.2 Reusable Components (`components/`)
| 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` | ดึงหมวดหมู่ทั้งหมด |
- **Layout:** `AppHeader.vue`, `AppSidebar.vue`, `MobileNav.vue` (Navigation หลัก)
- **Common:** `FormInput.vue` (ฟอร์ม), `LoadingSpinner.vue` (สถานะโหลด), `LanguageSwitcher.vue` (เปลี่ยนภาษา)
- **Modules:** `CourseCard.vue` (แสดงผลคอร์สแบบ Grid), `UserAvatar.vue` (รูปโปรไฟล์)
---
## 🔐 3. Security & Core Systems
## 🧠 3. Logic & Data Layer (Composables + API)
- **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)
รวบรวม Logic และ API Endpoint ที่เกี่ยวข้องไว้ในที่เดียวเพื่อความเข้าใจง่าย
### 3.1 `useAuth.ts` (Authentication & User)
จัดการสถานะผู้ใช้, ล็อกอิน, และข้อมูลส่วนตัว
- **Endpoints:**
- `GET /api/user/me`: ดึงข้อมูลโปรไฟล์ (Cached)
- `PUT /api/user/me`: อัปเดตข้อมูลส่วนตัว
- `POST /api/user/change-password`: เปลี่ยนรหัสผ่าน
### 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}`: ดึงวิดีโอเนื้อหา
- `POST /api/students/lessons/{lessonId}/progress`: บันทึกเวลาเรียน (Video Progress)
### 3.3 `useCategory.ts` & Utilities
- `fetchCategories`: ดึงหมวดหมู่ (`GET /api/categories`) สำหรับตัวกรองหน้า Discovery
- `useFormValidation.ts`: รวม RegEx สำหรับตรวจสอบ Email, Password เบื้องต้น
---
## 🎨 4. Theme & Styling Guide (แนวทางการออกแบบ)
## 🎨 4. Design System & Theming
เพื่อให้การพัฒนาในอนาคตเป็นระเบียบและส่งต่อได้ง่าย ระบบมีการจัดการ CSS ดังนี้:
### 4.1 Dark Mode Strategy
### 4.1 การจัดการ Dark Mode
ระบบใช้ **Class-based Dark Mode** ของ Tailwind ผสมกับ CSS Variables:
ระบบใช้การสลับคลาส `.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"** สำหรับเนื้อหาภาษาไทยเพื่อให้พรีเมียมและอ่านง่าย.
- **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)
---
## ⚡ 5. Performance & Caching (ระบบจัดการความเร็ว)
## 📊 5. Project Status (สถานะการพัฒนา)
เพื่อป้องกันปัญหา **429 Too Many Requests** และเพิ่มความเร็ว ระบบมีการทำ **Client-side Caching** ในระดับ Composables:
### ✅ Completed Updates (สิ่งที่ทำเสร็จแล้ว)
- **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)
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:** รองรับภาษาไทยสมบูรณ์พร้อมคำอธิบายโค้ด
### <20> Pending / Future Work (สิ่งที่ต้องทำต่อ)
1. **Quiz System:** หน้า Quiz ยังรอการเชื่อมต่อ API (`/api/quizzes`)
2. **Certificates:** ระบบดาวน์โหลดใบประกาศนียบัตร
3. **Advanced Features:** Upload รูปโปรไฟล์จริง, ระบบ Reviews/Rating คอร์สเรียน
---