From bdebf2224e8959f5148e6f1313f6139d2426a422 Mon Sep 17 00:00:00 2001 From: supalerk-ar66 Date: Tue, 20 Jan 2026 16:36:20 +0700 Subject: [PATCH] A --- Frontend-Learner/คู่มืออธิบาย/web-dev-details.md | 193 +++++++++---------- 1 file changed, 90 insertions(+), 103 deletions(-) diff --git a/Frontend-Learner/คู่มืออธิบาย/web-dev-details.md b/Frontend-Learner/คู่มืออธิบาย/web-dev-details.md index 11ba6c3a..76e5a762 100644 --- a/Frontend-Learner/คู่มืออธิบาย/web-dev-details.md +++ b/Frontend-Learner/คู่มืออธิบาย/web-dev-details.md @@ -1,128 +1,115 @@ -# 🛠️ Web Development Details: e-Learning Platform (Learner Frontend) +# 🛠️ Web Development Documentation: e-Learning Platform (Frontend) -เอกสารฉบับนี้สรุปรายละเอียดทางเทคนิค โครงสร้างโค้ด และการทำงานของระบบเพื่อความสะดวกในการพัฒนาต่อและส่งมอบงาน - -## 🚀 Tech Stack - -- **Framework:** Nuxt 3 (Vue 3 Composition API) -- **Language:** TypeScript -- **Internationalization:** @nuxtjs/i18n (Multi-language support: TH/EN) -- **Styling:** - - Tailwind CSS (Utility-first) - - Vanilla CSS Variables (Design Tokens & Theming) - - Custom CSS Animations (ใน `assets/css/main.css`) -- **State Management:** Vue `ref`, `reactive`, `computed` (Local State) & Composables (Global State) -- **UI Component:** - - Custom Premium Components (สร้างเองเพื่อให้ได้ Design ที่เฉพาะตัว) - - Quasar UI (ใช้บางส่วนสำหรับ Notifications และ Layout พื้นฐาน) -- **Icons:** SVG Icons (Inline เพื่อ Performance สูงสุด) +เอกสารฉบับนี้สรุปรายละเอียดทางเทคนิค โครงสร้างโค้ด และการทำงานของระบบ **Frontend-Learner** เพื่อความสะดวกในการพัฒนาต่อและส่งมอบงาน --- -## 📂 โครงสร้างโฟลเดอร์และหน้าที่ของไฟล์ (Project Structure) +## 🚀 1. Tech Stack & Tools -### `pages/` (Routes) +เครื่องมือและเทคโนโลยีหลักที่ใช้ในการพัฒนาระบบ: -กำหนดเส้นทาง (Routes) ของเว็บไซต์: +- **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:** ออกแบบให้ยืดหยุ่นสูง -| ไฟล์ | Path URL | หน้าที่และความสำคัญ | -| :------------------------ | :----------------- | :------------------------------------------------------------------------------------------- | -| `index.vue` | `/` | **Main Landing Page:** หน้าแรกบุคคลทั่วไป มีเอฟเฟกต์พื้นหลัง Hero Section และข้อมูลแพลตฟอร์ม | -| **`auth/`** | | **Authentication Module:** รวมหน้าที่เกี่ยวกับการยืนยันตัวตนทั้งหมด | -| ├── `login.vue` | `/auth/login` | หน้าเข้าสู่ระบบ | -| ├── `register.vue` | `/auth/register` | หน้าสมัครสมาชิกใหม่ | -| ├── `forgot-password.vue` | `/auth/forgot..` | หน้าขอรหัสผ่านใหม่ | -| └── `reset-password.vue` | `/auth/reset..` | หน้าตั้งรหัสผ่านใหม่ | -| **`dashboard/`** | | **User Dashboard Module:** ส่วนพื้นที่ส่วนตัวของผู้ใช้ | -| ├── `index.vue` | `/dashboard` | **Main Dashboard:** หน้าหลักแสดงความคืบหน้าการเรียนล่าสุด และคอร์สแนะนำ | -| ├── `my-courses.vue` | `/dashboard/my..` | **User Knowledge Base:** รวมคอร์สที่ผู้ใช้งานลงทะเบียนเรียนแล้ว | -| ├── `profile.vue` | `/dashboard/pro..` | **User Settings:** หน้าจัดการข้อมูลส่วนตัว | -| ├── `announcements.vue` | `/dashboard/ann..` | **Platform News:** หน้ารวมประกาศข่าวสาร | -| **`browse/`** | | **Browsing Module:** ส่วนค้นหาคอร์สเรียน | -| ├── `index.vue` | `/browse` | **Public Catalog:** หน้ารวมคอร์สสำหรับผู้เยี่ยมชมทั่วไป (Clean Card UI) | -| ├── `discovery.vue` | `/browse/disc..` | **Course Catalog:** หน้าค้นหาคอร์ส พร้อมระบบ Filter Accordion และ Expandable Categories | -| ├── `opencovery.vue` | `/browse/open..` | **Public Detail:** หน้ารายละเอียดคอร์สแบบสาธารณะ | -| **`classroom/`** | | **Learning Module:** ส่วนการเรียนการสอน | -| ├── `learning.vue` | `/classroom/lea..` | **Classroom Experience:** ห้องเรียนออนไลน์เต็มรูปแบบ (Video Player, Sidebar) | -| ├── `quiz.vue` | `/classroom/quiz` | **Assessment Module:** ระบบสอบวัดผล 4 ขั้นตอน | +--- -### `components/` (Reusable UI) +## 📂 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` | หน้าสมัครสมาชิก | +| | `auth/forgot-password.vue` | `/auth/forgot..` | หน้าลืมรหัสผ่าน | +| | `auth/reset-password.vue` | `/auth/reset..` | หน้าตั้งรหัสใหม่ | +| **Dashboard** | `dashboard/index.vue` | `/dashboard` | หน้าหลักผู้เรียน (Overall Progress) | +| | `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) | +| | `browse/opencovery.vue` | `/browse/open..` | หน้ารายละเอียดคอร์ส (Public View) | +| **Classroom** | `classroom/learning.vue` | `/classroom/lea..` | **ห้องเรียนออนไลน์** (Video Player, Progress Tracking) | +| | `classroom/quiz.vue` | `/classroom/quiz` | ระบบสอบวัดผล | + +### 2.2 `components/` (Reusable UI) + +ชิ้นส่วน UI ที่ใช้ซ้ำได้บ่อย: - **Layout & Navigation:** - - `AppHeader.vue` / `AppSidebar.vue`: ส่วนหัวและเมนูข้างสำหรับผู้ใช้ที่ล็อกอินแล้ว - - `LandingHeader.vue` / `LandingFooter.vue`: ส่วนหัวและท้ายสำหรับหน้า Landing Page - - `MobileNav.vue`: เมนูนำทางด้านล่างสำหรับหน้าจอมือถือ - - `UserMenu.vue`: เมนู Dropdown จัดการบัญชีผู้ใช้ - - `LanguageSwitcher.vue`: ปุ่มสลับภาษา (TH/EN) พร้อมดีไซน์ที่รองรับ Dark Mode -- **Cards & Display:** - - `CourseCard.vue`: การ์ดแสดงข้อมูลคอร์ส (Updated: Clean Design, No Badge) - - `UserAvatar.vue`: แสดงรูปโปรไฟล์ผู้ใช้ พร้อม Fallback -- **Forms & Feedback:** - - `FormInput.vue`, `LoadingSpinner.vue`, `LoadingSkeleton.vue` + - `AppHeader.vue`, `AppSidebar.vue` (ส่วนหัวและเมนูหลัก) + - `LanguageSwitcher.vue` (ปุ่มเปลี่ยนภาษา) + - `UserMenu.vue`, `MobileNav.vue` +- **Display & Content:** + - `CourseCard.vue`: **Smart Card** รองรับสถานะ (ทั่วไป / ลงทะเบียนแล้ว / เรียนจบ) + - `UserAvatar.vue`: รูปโปรไฟล์พร้อม Fallback +- **Feedback & Loading:** + - `LoadingSpinner.vue`, `LoadingSkeleton.vue` -### `i18n/` (Localization) +### 2.3 `composables/` (Core Logic & API) -โฟลเดอร์เก็บไฟล์แปลภาษา: +ศูนย์รวม Logic ของระบบ (Business Logic Layer): -- `locales/`: - - `th.json`: ไฟล์รวมคำแปลภาษาไทย - - `en.json`: ไฟล์รวมคำแปลภาษาอังกฤษ +| Composable | หน้าที่หลัก (Responsibilities) | +| :--------------------- | :-------------------------------------------------------------------------- | +| `useAuth.ts` | จัดการ Login, Register, Logout และเก็บ State ผู้ใช้ | +| `useCourse.ts` | **Course Management:** ค้นหา, ลงทะเบียน, ดึงเนื้อหาบทเรียน, บันทึก Progress | +| `useCategory.ts` | **Category Management:** ดึงหมวดหมู่สำหรับ Filter | +| `useFormValidation.ts` | Helper สำหรับตรวจสอบความถูกต้องของฟอร์ม | --- -## 🔐 ระบบรักษาความปลอดภัยและ Logic พิเศษ (Core Logic) +## 🔐 3. Security & Core Systems -| ส่วนงาน | ไฟล์ | คำอธิบาย | -| :--------------- | :----------------------------------- | :-------------------------------------------------------------- | -| **Route Guard** | `middleware/auth.ts` | Middleware ดักจับการเข้าถึง เช็กสถานะการล็อกอิน | -| **Auth State** | `composables/useAuth.ts` | Centralized Logic สำหรับ Login/Logout เก็บ state ผู้ใช้ปัจจุบัน | -| **Course Logic** | `composables/useCourse.ts` | Centralized Logic สำหรับดึงข้อมูลคอร์สทั้งหมดและรายละเอียดคอร์ส | -| **No-Cache** | `server/middleware/cache-control.ts` | ป้องกันการ Cache หน้าสำคัญด้วย Headers | +- **Middleware (`middleware/auth.ts`):** ดักจับ Route ป้องกันไม่ให้ผู้ที่ยังไม่ล็อกอินเข้าถึงหน้า Dashboard/Classroom +- **Localization (`i18n/`):** + - แยกไฟล์ภาษาชัดเจน: `locales/th.json`, `locales/en.json` + - ใช้ `$t('key')` ใน Template ทั้งหมด +- **Theming:** รองรับ Dark Mode สมบูรณ์แบบด้วย Tailwind `dark:` classes และ CSS Variables --- -## 🎨 Design System & Theming +## 🆕 4. Recent Updates (บันทึกการอัปเดตล่าสุด) -- **Global Styles:** `assets/css/main.css` - - **Strict Dark Palette:** ใช้ระบบ CSS Variables ใหม่ (`--bg-body`, `--bg-surface`, `--text-main`, etc.) เพื่อคุมธีม Dark Mode ให้แม่นยำ (`Slate-900` base) - - **Dynamic Colors:** เปลี่ยนการใช้ Hardcoded HEX เป็น Tailwind Utilities (`text-slate-900 dark:text-white`) เพื่อรองรับทั้ง Light/Dark Mode สมบูรณ์แบบ -- **Font Configuration:** ใช้ **Inter** (English) และ **Prompt/Sarabun** (Thai) +### ✅ Phase 1: Authentication & UI Refactor + +- ย้ายระบบ Auth ทั้งหมดเข้า Module `pages/auth/` +- ปรับปรุง UI หน้า Dashboard และ Landing Page +- ติดตั้งระบบ **i18n** รองรับ 2 ภาษาเต็มรูปแบบ + +### ✅ Phase 2: Course Discovery (Browse) + +- เชื่อมต่อ API `/api/courses` สำหรับหน้าค้นหา +- เพิ่มระบบ Filter หมวดหมู่ (ย่อ/ขยายได้) และ Search Real-time +- ปรับปรุงการ์ดแสดงผลคอร์สให้รองรับข้อมูลจริงจาก Backend + +### ✅ Phase 3: Full Learning Experience (Current) + +- **Classroom Integration (`learning.vue`):** + - เปลี่ยนจาก Mock Data เป็น **Real API Data** + - **Video Player:** เล่นวิดีโอจาก URL จริง + - **Feature:** + - 🔒 **Locking:** ล็อกบทเรียนที่ยังเรียนไม่ได้ + - 💾 **Progress:** บันทึกเวลาเรียนอัตโนมัติทุก 10 วินาที + - ✅ **Auto-Complete:** จบบทเรียนอัตโนมัติเมื่อดูวิดีโอจบ +- **API Expansion:** เพิ่ม Endpoints ครบวงจรใน `useCourse.ts` (`fetchLesson`, `saveProgress`, `enroll`) --- -## 🆕 อัปเดตล่าสุด (Recent Major Updates) - -### 1. **Authentication Refactor** - -- ย้ายไฟล์ที่เกี่ยวข้องกับ Auth (`login`, `register`, etc.) ไปไว้ในโฟลเดอร์ `pages/auth/` เพื่อความเป็นระเบียบและง่ายต่อการจัดการ - -### 2. **UI/UX Refinements (Discovery & Courses)** - -- **Discovery Page:** - - **Accordion Filters:** ปรับปรุง Filter หมวดหมู่ให้สามารถ ย่อ/ขยาย ได้ (`v-show`) - - **Show More Logic:** เพิ่มปุ่ม "แสดงเพิ่มเติม/แสดงน้อยลง" สำหรับรายการหมวดหมู่ที่ยาว - - **Cleaner UI:** ลบไอคอน Chevron ที่ซ้ำซ้อนในแต่ละรายการออก -- **Courses Page (Public):** - - **Simplified Cards:** ลบ Badge ระดับความยาก (Level) ออกเพื่อให้การ์ดดูสะอาดตาขึ้น - - **Data Cleanup:** ลบข้อมูล Level ที่ไม่จำเป็นออกจาก Mock Data - -### 3. **Dashboard (Home) Update** - -- **New Layout:** ปรับปรุงหน้า Dashboard ให้แสดง "คอร์สที่เรียนล่าสุด" และ "คอร์สแนะนำ" อย่างชัดเจน -- **Progress Tracking:** แสดง Progress Bar ที่สวยงามสำหรับการเรียนปัจจุบัน - -### 4. **API Integration (Course System)** - -- **Real Data Integration:** เชื่อมต่อหน้า `browse/discovery` เข้ากับ Backend API (`/api/courses`) สำเร็จ -- **Dynamic Detail View:** เพิ่มระบบดึงข้อมูลรายคอร์ส (`/api/courses/{id}`) เมื่อคลิก "ดูรายละเอียด" -- **New Composable:** สร้าง `useCourse.ts` เพื่อจัดการ Logic การดึงข้อมูลคอร์สแยกออกมาให้เป็นระเบียบ -- **Updated Course Card:** รองรับการแสดงผลรูปภาพปกคอร์ส (`thumbnail_url`) และราคาจริงจาก API - -### 5. **Internationalization (i18n) Implementation** - -- **Full Language Support:** ติดตั้งและตั้งค่า `@nuxtjs/i18n` รองรับ 2 ภาษา (ไทย/อังกฤษ) -- **Locale Management:** แยกไฟล์คำแปลเป็น `locales/th.json` และ `locales/en.json` เพื่อง่ายต่อการแก้ไข -- **Dynamic Translation:** เปลี่ยนข้อความ Static ทั้งหมดในหน้า `Dashboard`, `Discovery`, `My Courses`, `Profile` และ `Sidebar` ให้ใช้ `$t(...)` -- **Language Switcher:** เพิ่มปุ่มสลับภาษาที่ Header/Sidebar พร้อมจำค่าภาษาที่เลือกไว้ +> _เอกสารนี้อัปเดตล่าสุด: 2026-01-20_