diff --git a/Frontend-Learner/คู่มืออธิบาย/web-dev-details.md b/Frontend-Learner/คู่มืออธิบาย/web-dev-details.md index c92b00e6..cc52444c 100644 --- a/Frontend-Learner/คู่มืออธิบาย/web-dev-details.md +++ b/Frontend-Learner/คู่มืออธิบาย/web-dev-details.md @@ -1,71 +1,107 @@ -# 🛠️ Web Development Documentation: Frontend-Learner -เอกสารฉบับนี้สรุปรายละเอียดทางเทคนิค โครงสร้างโค้ด และกลไกการทำงานของระบบ **Frontend-Learner** (ระบบฝั่งผู้เรียน) อย่างครบถ้วน เพื่อใช้เป็นคู่มือสำหรับการพัฒนาและบำรุงรักษา (อัปเดตล่าสุด: ปลายเดือนกุมภาพันธ์ 2026) +# Frontend-Learner (Web) — Technical Documentation + +เอกสารฉบับนี้สรุปรายละเอียดทางเทคนิค โครงสร้างโค้ด และกลไกการทำงานของระบบ **Frontend-Learner (ฝั่งผู้เรียน)** +ใช้เป็นคู่มือสำหรับการพัฒนา บำรุงรักษา และขยายระบบต่อไป + +> อัปเดตล่าสุด: ปลายเดือนกุมภาพันธ์ 2026 --- -## 🚀 1. Technical Foundation +## Table of Contents + +- [1. Technical Foundation](#1-technical-foundation) + - [1.1 Tech Stack](#11-tech-stack) + - [1.2 Security & Authentication](#12-security--authentication) +- [2. Project Architecture](#2-project-architecture) + - [2.1 Directory Structure](#21-directory-structure) + - [2.2 Shared Infrastructure](#22-shared-infrastructure) +- [3. Logic & Data Layer (Composables)](#3-logic--data-layer-composables) +- [4. Branding & UI Policy](#4-branding--ui-policy) + - [4.1 Theme Strategy](#41-theme-strategy) + - [4.2 UI Elements](#42-ui-elements) +- [5. Core Feature Highlights](#5-core-feature-highlights) +- [6. Maintenance & Performance Guidelines](#6-maintenance--performance-guidelines) + +--- + +## 1. Technical Foundation รากฐานทางเทคนิคที่ขับเคลื่อนระบบ เพื่อให้ได้ประสิทธิภาพและความเสถียรสูงสุด ### 1.1 Tech Stack -- **Framework:** [Nuxt 3](https://nuxt.com) (Vue 3, Vite, SSR/SPA Hybrid) +- **Framework:** Nuxt 3 (Vue 3, Vite, SSR/SPA Hybrid) - **UI System:** Quasar Framework + Tailwind CSS (Utility-first) -- **Typography:** Google Fonts ("Prompt" เป็น Font หลักเพื่อความทันสมัยและอ่านง่าย) +- **Typography:** Google Fonts (**Prompt** เป็น Font หลักเพื่อความทันสมัยและอ่านง่าย) - **Multilingual:** `@nuxtjs/i18n` (รองรับ JSON-based locales ภาษาไทยและอังกฤษ) - **Programming:** TypeScript (Strict Type Checking) ### 1.2 Security & Authentication -- **Token Management:** ใช้ JWT (Access & Refresh Tokens) จัดเก็บผ่าน `useCookie` ระบบรักษาความปลอดภัยระดับ HTTP-only และ SameSite +- **Token Management:** ใช้ JWT (Access & Refresh Tokens) จัดเก็บผ่าน `useCookie` + โดยตั้งค่าความปลอดภัยระดับ **HTTP-only** และ **SameSite** - **Middleware:** `auth.ts` ตรวจสอบสิทธิ์การเข้าถึงหน้า Dashboard และ Classroom แบบ Real-time -- **Persistence:** ระบบ **Remember Me** (จดจำอีเมล) ใช้ `localStorage` แยกส่วนจาก Session เพื่อความปลอดภัยและสะดวกสำหรับผู้ใช้ +- **Persistence:** ระบบ Remember Me (จดจำอีเมล) ใช้ `localStorage` แยกส่วนจาก Session + เพื่อความปลอดภัยและสะดวกสำหรับผู้ใช้ --- -## 📂 2. Project Architecture +## 2. Project Architecture -โครงสร้างโฟลเดอร์ที่จัดระเบียบตามหลัก **Clean Architecture** เพื่อความคล่องตัวในการขยายระบบ +โครงสร้างโฟลเดอร์ที่จัดระเบียบตามหลัก Clean Architecture เพื่อความคล่องตัวในการขยายระบบ ### 2.1 Directory Structure -- `pages/`: ระบบ Routing ทั้งหมด (Landing, Auth, Dashboard, Classroom) -- `components/`: UI Components แยกตามความรับผิดชอบ (Common, Layout, Course, Classroom, Profile) -- `composables/`: Business Logic ทั้งหมด (Auth, Course, Theme, Quiz, Navigation) -- `types/`: ศูนย์รวม Interface และ Type definitions ของทั้งระบบ -- `constants/`: แหล่งเก็บข้อมูล Static (เช่น Category cards, Why choose us) เพื่อลดความซับซ้อนในไฟล์ Vue -- `assets/css/`: `main.css` ที่เป็น Single Source of Truth สำหรับสไตล์และ CSS Variables -- `layouts/`: Master templates (Default, Auth, Dashboard) -- `middleware/`: ตัวกรองความปลอดภัยก่อนเข้าถึงแต่ละหน้า +- `pages/` : ระบบ Routing ทั้งหมด (Landing, Auth, Dashboard, Classroom) +- `components/` : UI Components แยกตามความรับผิดชอบ (Common, Layout, Course, Classroom, Profile) +- `composables/` : Business Logic ทั้งหมด (Auth, Course, Theme, Quiz, Navigation) +- `types/` : ศูนย์รวม Interface และ Type definitions ของทั้งระบบ +- `constants/` : แหล่งเก็บข้อมูล Static (เช่น Category cards, Why choose us) เพื่อลดความซ้อนในไฟล์ Vue +- `assets/css/` : `main.css` ที่เป็น Single Source of Truth สำหรับสไตล์และ CSS Variables +- `layouts/` : Master templates (Default, Auth, Dashboard) +- `middleware/` : ตัวกรองความปลอดภัยก่อนเข้าถึงแต่ละหน้า ### 2.2 Shared Infrastructure -- **Types Architecture:** การสกัด Types จาก Composable ออกมาไว้ที่ `@/types` ช่วยลดความซ้ำซ้อนและป้องกัน Error จากการเปลี่ยนโครงสร้างข้อมูล API -- **Constants System:** การใช้ `@/constants` ช่วยให้การแก้ไขคำโฆษณาหรือข้อมูลหน้าแรกทำได้จากจุดเดียว โดยไม่ต้องแก้โค้ด HTML +- **Types Architecture:** การสกัด Types จาก Composable ออกมาไว้ที่ `@/types` + ช่วยลดความซ้ำซ้อนและป้องกัน Error จากการเปลี่ยนโครงสร้างข้อมูล API +- **Constants System:** การใช้ `@/constants` ช่วยให้การแก้ไขคำโฆษณาหรือข้อมูลหน้าแรกทำได้จากจุดเดียว + โดยไม่ต้องแก้โค้ด HTML --- -## 🧠 3. Logic & Data Layer (Composables) +## 3. Logic & Data Layer (Composables) การแยก Logic ออกจาก UI เพื่อความสะอาดและ Testable -- **`useAuth`:** จัดการสถานะ Login, การดึงโปรไฟล์ล่วงหน้า (Pre-fetching), และระบบ Token Refresh -- **`useCourse`:** หัวใจของระบบ จัดการตั้งแต่ Catalog, การสมัครเรียน (Enroll), ไปจนถึงการส่งผลการเรียน (Progress) -- **`useThemeMode`:** ระบบจัดการธีมกลางที่เชื่อมต่อกับ `localStorage` และ CSS Variables อย่างเป็นระบบ -- **`useQuizRunner`:** จัดการสถานะการสอบ เปลี่ยนข้อสอบ และส่งคะแนนไปยัง Backend โดยตรง -- **`useNavItems`:** Single Source of Truth สำหรับเมนูทั้งหมด (Sidebar, Mobile Drawer, User Menu) +- `useAuth` + จัดการสถานะ Login, การดึงโปรไฟล์ล่วงหน้า (Pre-fetching), และระบบ Token Refresh + +- `useCourse` + หัวใจของระบบ จัดการตั้งแต่ Catalog, การสมัครเรียน (Enroll), ไปจนถึงการส่งผลการเรียน (Progress) + +- `useThemeMode` + ระบบจัดการธีมกลางที่เชื่อมต่อกับ `localStorage` และ CSS Variables อย่างเป็นระบบ + +- `useQuizRunner` + จัดการสถานะการสอบ เปลี่ยนข้อสอบ และส่งคะแนนไปยัง Backend โดยตรง + +- `useNavItems` + Single Source of Truth สำหรับเมนูทั้งหมด (Sidebar, Mobile Drawer, User Menu) --- -## 🎨 4. Branding & UI Policy +## 4. Branding & UI Policy -มาตรฐานการออกแบบที่เน้นความ **Premium** และ **Consistent** +มาตรฐานการออกแบบที่เน้นความ Premium และ Consistent ### 4.1 Theme Strategy -- **Public Pages (Landing, Auth, Detail):** บังคับ **Forced Light Mode** เพื่อภาพลักษณ์แบรนด์ที่สะอาดและน่าเชื่อถือ -- **Internal Pages (Dashboard, Learning):** รองรับ **Dark Mode (Oceanic Theme)** ลดการเมื่อยล้าของสายตาขณะเรียนเป็นเวลานาน -- **Transitions:** ใช้ `GlobalLoader` และ Smooth transitions ทั่วทั้งแอปเพื่อประสบการณ์ที่ลื่นไหล +- **Public Pages (Landing, Auth, Detail):** บังคับ **Forced Light Mode** + เพื่อภาพลักษณ์แบรนด์ที่สะอาดและน่าเชื่อถือ +- **Internal Pages (Dashboard, Learning):** รองรับ **Dark Mode (Oceanic Theme)** + ลดการเมื่อยล้าของสายตาขณะเรียนเป็นเวลานาน +- **Transitions:** ใช้ GlobalLoader และ Smooth transitions ทั่วทั้งแอปเพื่อประสบการณ์ที่ลื่นไหล ### 4.2 UI Elements @@ -75,27 +111,28 @@ --- -## 📚 5. Core Feature Highlights +## 5. Core Feature Highlights ฟีเจอร์เด่นที่ถูกพัฒนาขึ้นเพื่อผู้เรียนโดยเฉพาะ -- **SPA Learning Journey:** การสลับบทเรียนในห้องเรียนเป็นแบบ Single Page App (ไม่มีการ Re-load หน้า) ทำให้การเรียนต่อเนื่อง -- **Hybrid Progress Tracking:** บันทึกเวลาเรียนลง LocalStorage แบบ Real-time และ Sync ขึ้น Server เป็นระยะเพื่อป้องกันข้อมูลหาย -- **Announcement System:** ระบบแจ้งเตือนในคอร์สพร้อมตัวระบุ "ยังไม่ได้อ่าน" (Unread Badge) ที่จำสถานะตามผู้ใช้งาน +- **SPA Learning Journey:** การสลับบทเรียนในห้องเรียนเป็นแบบ Single Page App (ไม่มีการ Re-load หน้า) + ทำให้การเรียนต่อเนื่อง +- **Hybrid Progress Tracking:** บันทึกเวลาเรียนลง `localStorage` แบบ Real-time และ Sync ขึ้น Server เป็นระยะ + เพื่อป้องกันข้อมูลหาย +- **Announcement System:** ระบบแจ้งเตือนในคอร์สพร้อมตัวระบุ "ยังไม่ได้อ่าน" (Unread Badge) + ที่จำสถานะตามผู้ใช้งาน - **Interactive Quizzes:** ระบบสอบที่สลับคำถามอัตโนมัติ พร้อมโหมดเฉลย (Answer Review) ที่ชัดเจน - **Certificate Automation:** ระบบตรวจสอบสิทธิ์ความสำเร็จและออกใบประกาศนียบัตรได้ทันที --- -## 🛠️ 6. Maintenance & Performance Guidelines +## 6. Maintenance & Performance Guidelines แนวทางสำหรับการพัฒนาต่อยอด -1. **Clean Code:** หลีกเลี่ยงการใช้ `console.log` ในโค้ด Final และลบ Dead Logic ทิ้งทันที -2. **Standard Fonts:** ใช้ชุด Font `Prompt` ผ่านตัวแปร `--font-main` เสมอ -3. **API Integrity:** ตรวจสอบข้อมูลผ่าน Interface ใน `@/types` ก่อนการใช้งานทุกครั้ง -4. **Mobile First:** ทุก Component ต้องรองรับระบบ **Master Drawer** บนมือถืออย่างสมบูรณ์ +- **Clean Code:** หลีกเลี่ยงการใช้ `console.log` ในโค้ด Final และลบ Dead Logic ทิ้งทันที +- **Standard Fonts:** ใช้ชุด Font Prompt ผ่านตัวแปร `--font-main` เสมอ +- **API Integrity:** ตรวจสอบข้อมูลผ่าน Interface ใน `@/types` ก่อนการใช้งานทุกครั้ง +- **Mobile First:** ทุก Component ต้องรองรับระบบ Master Drawer บนมือถืออย่างสมบูรณ์ --- - -_เอกสารนี้ถูกจัดทำขึ้นเพื่อให้ทีมพัฒนาเข้าใจทิศทางเดียวกัน และรักษามารตฐานสูงสุดของโปรเจกต์ e-Learning Platform_