elearning/Frontend-Learner/คู่มืออธิบาย/web-dev-details.md

🛠️ Web Development Documentation: e-Learning Platform (Frontend)

เอกสารฉบับนี้สรุปรายละเอียดทางเทคนิค โครงสร้างโค้ด และการทำงานของระบบ Frontend-Learner เพื่อความสะดวกในการพัฒนาต่อและส่งมอบงาน

---

🚀 1. Tech Stack & Tools

เครื่องมือและเทคโนโลยีหลักที่ใช้ในการพัฒนาระบบ:

• Core Framework: Nuxt 3 (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: ออกแบบให้ยืดหยุ่นสูง

---

📂 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	หน้าสมัครสมาชิก (อัปเดต 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	ดึงหมวดหมู่ทั้งหมด

---

🔐 3. Security & Core Systems

• 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)

---

🆕 4. 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)

---

🔍 5. 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)

---