alla-tms/plans/req.md

Training System Requirements Aligned With Project Stack

1. เป้าหมายของระบบ

ระบบนี้เป็นเว็บแอปสำหรับจัดเก็บและติดตามประวัติการอบรมของพนักงาน รวมถึงไฟล์ใบรับรองการอบรม และการตรวจสอบความครบถ้วนตาม Training Matrix ของแต่ละหน่วยงานหรือแต่ละตำแหน่งงาน

เอกสารฉบับนี้ปรับให้สอดคล้องกับ stack และสถาปัตยกรรมของโปรเจ็กต์ปัจจุบัน โดยไม่ใช้ Google Apps Script, Google Sheets หรือ Google Drive เป็นแกนหลักของระบบ

2. Stack ที่ต้องใช้ตามโปรเจ็กต์นี้

• Frontend: Next.js 16 App Router + React 19 + TypeScript
• UI: Tailwind CSS v4 + shadcn/ui
• Auth: Auth.js
• Database: PostgreSQL + Drizzle ORM
• Data fetching: TanStack React Query
• URL state: nuqs
• Forms: TanStack Form + Zod ผ่าน useAppForm
• API boundary: Next.js Route Handlers ภายใต้ src/app/api/**
• Icons: ใช้ผ่าน @/components/icons เท่านั้น

3. แนวทางสถาปัตยกรรมที่ต้องยึด

• ใช้ feature-based structure ภายใต้ src/features/<feature>/
• ใช้ data layer pattern ของโปรเจ็กต์:
  • types.ts
  • service.ts
  • queries.ts
  • mutations.ts เมื่อมี create/update/delete
• ฝั่ง client ต้องเรียกข้อมูลผ่าน service.ts
• service.ts ต้องเรียก Route Handlers ด้วย apiClient
• Route Handlers ต้องเป็น boundary หลักสำหรับ auth, authorization, validation ขั้นต้น และ database access
• หน้า dashboard ต้องใช้ PageContainer สำหรับ page header
• table/listing ที่มี filter, search, sort, pagination ต้องใช้ React Query + nuqs ตาม pattern ของหน้า products และ users
• form ต้องใช้ useAppForm และ field wrappers ของโปรเจ็กต์

4. Domain Model ที่ต้องใช้ในระบบ

ระบบนี้ควรใช้คำศัพท์โดเมนให้ชัดและสอดคล้องกับโครงสร้าง auth ปัจจุบัน

• user: ผู้ใช้งานที่ล็อกอินเข้าระบบ
• organization: หน่วยงานเจ้าของข้อมูล หรือ tenant ของระบบ
• membership: ความสัมพันธ์ระหว่าง user กับ organization พร้อม role
• employee: ข้อมูลพนักงานที่ถูกติดตามประวัติการอบรม
• course: หลักสูตรอบรมกลาง
• training_record: รายการประวัติการอบรมของพนักงานแต่ละครั้ง
• certificate: ข้อมูลไฟล์ใบรับรองที่ผูกกับ training record
• training_matrix: ข้อกำหนดว่าตำแหน่งหรือแผนกใดต้องผ่านหลักสูตรอะไร
• department: หน่วยงานภายในองค์กร
• position: ตำแหน่งงาน

หมายเหตุ:

• ถ้าผู้ใช้ระบบกับพนักงานเป็นคนละแนวคิด ต้องแยก user ออกจาก employee
• ข้อมูลทั้งหมดควรถูกผูกกับ organizationId เพื่อรองรับ multi-tenant

5. ขอบเขตข้อมูลหลักใน PostgreSQL

ตารางหลักที่ควรมีในระบบนี้:

• users
  • ข้อมูลบัญชีผู้ใช้งานสำหรับ Auth.js
• organizations
  • ข้อมูลองค์กรหรือ workspace
• memberships
  • บทบาทของผู้ใช้งานในแต่ละ organization
• employees
  • รหัสพนักงาน, ชื่อ, แผนก, ตำแหน่ง, บริษัท, สถานะ
• departments
  • หน่วยงานภายใน organization
• positions
  • ตำแหน่งงานภายใน organization
• courses
  • ชื่อหลักสูตร, หมวดหมู่, ผู้จัดอบรม, จำนวนชั่วโมง, อายุใบรับรอง, บังคับหรือไม่
• training_records
  • employee, course, วันที่อบรม, รูปแบบการอบรม, ชั่วโมง, หมายเหตุ, สถานะอนุมัติ
• certificates
  • ชื่อไฟล์, path หรือ storage key, mime type, uploadedAt
• training_matrices
  • mapping ระหว่าง department หรือ position กับ course ที่จำเป็น

แนวทางสำคัญ:

• ทุกตารางเชิงธุรกิจควรมี organizationId
• ใช้ foreign keys ชัดเจนระหว่าง employee, course, training_record, certificate
• เก็บ file metadata ใน database และเก็บไฟล์จริงใน app-owned storage

6. แนวทางจัดเก็บไฟล์ใบรับรอง

ไม่ใช้ Google Drive เป็น storage หลักของระบบนี้

รอบแรกของระบบควรใช้แนวทางใดแนวทางหนึ่ง:

• ทางเลือกแนะนำสำหรับโปรเจ็กต์นี้:
  • เก็บ metadata ใน PostgreSQL
  • เก็บไฟล์จริงผ่าน local uploads หรือ object storage ที่ต่อเพิ่มภายหลัง

ข้อกำหนดเชิงระบบ:

• certificate ต้องผูกกับ training_record
• ต้องสามารถเปิดดูไฟล์ย้อนหลังได้
• ต้องรองรับไฟล์อย่างน้อย pdf, jpg, jpeg, png
• ต้องมี field สำหรับ fileName, fileType, fileSize, storageKey, uploadedAt

7. บทบาทผู้ใช้งาน

ระบบต้องรองรับ role อย่างน้อย:

• member
  • ดู dashboard ของตัวเอง
  • เพิ่มและแก้ไขประวัติการอบรมของตัวเอง
  • อัปโหลดใบรับรองของตัวเอง
  • ดูสถานะการอนุมัติ
• admin
  • จัดการ employee
  • จัดการ course
  • ตรวจสอบและอนุมัติ training record
  • จัดการ training matrix
  • ดูรายงานภาพรวมของ organization
• owner
  • สิทธิ์ระดับสูงสุดใน organization
  • จัดการสมาชิกและค่ากำหนดหลักของ organization

Authorization ต้องตรวจที่ server-side ผ่าน session + membership ไม่ใช่ตรวจเฉพาะ client

8. ฟีเจอร์หลักสำหรับผู้ใช้งานทั่วไป

8.1 User Dashboard

ผู้ใช้งานต้องเห็น dashboard ส่วนตัวที่ประกอบด้วย:

• จำนวนหลักสูตรที่เคยอบรมทั้งหมด
• จำนวนชั่วโมงอบรมสะสม
• จำนวนใบรับรองที่บันทึกแล้ว
• จำนวนหลักสูตรที่ยังขาดตาม training matrix
• กราฟสรุปการอบรมรายเดือนหรือรายปี

แนวทาง implementation:

• ใช้ Recharts สำหรับกราฟ
• ใช้ server prefetch + HydrationBoundary + useSuspenseQuery

8.2 บันทึกการอบรม

ผู้ใช้งานต้องสามารถเพิ่มรายการอบรมได้ โดยข้อมูลหลักประกอบด้วย:

• employee หรือข้อมูลผู้เข้าอบรม
• course
• training date
• training type: online | onsite | internal | external
• training hours
• organizer
• note
• certificate file
• approval status

แนวทาง implementation:

• ใช้ TanStack Form + Zod
• submit ผ่าน mutation ไปยัง Route Handler
• หลังบันทึกต้อง invalidate query ที่เกี่ยวข้อง

8.3 รายการอบรมของฉัน

ผู้ใช้งานต้องสามารถ:

• ค้นหาตามชื่อหลักสูตร
• กรองตามปี
• กรองตามหมวดหมู่
• กรองตามสถานะ
• เปิดดูรายละเอียด
• เปิดดูไฟล์ใบรับรอง
• แก้ไขรายการของตัวเอง
• ลบรายการที่ยังไม่ถูกอนุมัติ หรือเป็นไปตาม policy ที่กำหนด

แนวทาง implementation:

• ใช้ Data Table pattern เดียวกับ products หรือ users
• ใช้ React Query + nuqs

9. ฟีเจอร์หลักสำหรับ Admin

9.1 Admin Dashboard

Admin ต้องเห็น dashboard ภาพรวมของ organization:

• จำนวนพนักงาน
• จำนวนชั่วโมงอบรมรวม
• เปอร์เซ็นต์ความครบถ้วนตาม training matrix
• จำนวนรายการที่รออนุมัติ
• สถิติแยกตามแผนก หมวดหมู่ และช่วงเวลา

9.2 จัดการ Employee

Admin ต้องสามารถ:

• เพิ่ม employee
• แก้ไข employee
• ปิดการใช้งาน employee
• กำหนดแผนก
• กำหนดตำแหน่ง

9.3 จัดการ Course

Admin ต้องสามารถ:

• เพิ่ม course
• แก้ไข course
• ลบ course
• กำหนด category
• กำหนด standard training hours
• กำหนด certificate validity
• ระบุว่าเป็น required course หรือไม่

9.4 ตรวจสอบและอนุมัติ Training Record

Admin ต้องสามารถ:

• เปิดดูไฟล์ใบรับรอง
• ตรวจสอบรายละเอียดการอบรม
• approve
• reject
• request changes
• ใส่หมายเหตุประกอบการตรวจสอบ

สถานะที่ควรใช้:

• pending
• approved
• rejected
• needs_revision

9.5 จัดการ Training Matrix

Admin ต้องสามารถ:

• กำหนดหลักสูตรบังคับตาม department
• กำหนดหลักสูตรบังคับตาม position
• กำหนดหลักสูตรเฉพาะรายบุคคลในอนาคตได้
• กำหนด minimum required hours เมื่อจำเป็น
• ดูสถานะครบหรือไม่ครบของแต่ละ employee

10. รายงานที่ระบบควรมี

อย่างน้อยควรมีรายงานต่อไปนี้:

• ประวัติการอบรมรายบุคคล
• การอบรมแยกตามแผนก
• ชั่วโมงอบรมสะสม
• หลักสูตรที่ยังขาดตาม matrix
• ใบรับรองใกล้หมดอายุ
• สรุป training matrix ของ organization

รูปแบบการแสดงผล:

• แสดงบนหน้า dashboard/table
• รองรับ export ใน phase ถัดไป

11. แนวทาง UI/UX ที่ต้องสอดคล้องกับโปรเจ็กต์

• ใช้ shadcn/ui และ component patterns ที่มีอยู่แล้ว
• ใช้ PageContainer สำหรับ page title, description, action
• ใช้ @/components/icons แทนการ import icon ตรงจาก package ภายนอก
• ใช้ Card, Table, Dialog, Sheet, Tabs ตามแนวทางเดิมของโปรเจ็กต์
• รองรับ desktop และ mobile
• ไม่ใช้ SweetAlert2 หรือระบบ popup ภายนอกเป็นค่าเริ่มต้น
• ใช้ toast/alert/dialog ที่มีในโปรเจ็กต์แทน

12. Visual Direction

โทนสีจาก requirement เดิมสามารถตีความเป็น theme ของระบบได้ แต่ต้อง implement ผ่าน theme/token ของโปรเจ็กต์นี้ ไม่ใช่เขียนเป็นระบบ CSS แยกใหม่

สีที่ต้องการ:

• เขียวเข้ม: #336b4a
• เทา: #808285
• ส้ม: #e26631
• ม่วงเข้ม: #413b60

แนวทางใช้งาน:

• primary actions: เขียวเข้ม
• warning/highlight states: ส้ม
• supporting accents/charts: ม่วงเข้ม
• muted text/borders: เทา

ถ้าต้องทำ theme จริง ให้เพิ่มผ่านระบบ theme ของโปรเจ็กต์ ไม่ทำแยกนอก src/styles/themes และ theme.config.ts

13. แนวทางแบ่ง feature ในรีโปนี้

ฟีเจอร์ที่ควรสร้างใน src/features/:

• employees
• courses
• training-records
• certificates
• training-matrix
• reports

แต่ละ feature ควรมี:

• api/types.ts
• api/service.ts
• api/queries.ts
• api/mutations.ts เมื่อมี mutation
• components/
• schemas/
• constants/ เมื่อจำเป็น

และมี route ใต้ src/app/dashboard/<feature>/page.tsx

14. ลำดับการพัฒนาที่แนะนำ

เพื่อให้เข้ากับโครงสร้างของโปรเจ็กต์ ควรพัฒนาเป็นลำดับดังนี้:

1. Auth + organization + membership foundation
2. Employee management
3. Course management
4. Training record CRUD + certificate upload metadata
5. Training matrix
6. Dashboard summaries and reports

15. สิ่งที่ไม่ควรใช้ใน requirement ฉบับนี้

เพื่อให้ตรงกับโปรเจ็กต์นี้ ไม่ควรออกแบบระบบโดยอิงสิ่งต่อไปนี้เป็นแกนหลัก:

• Google Apps Script
• Google Sheets เป็น database หลัก
• Google Drive เป็น storage หลัก
• HTML/CSS/JavaScript แบบแยก standalone app
• SweetAlert2 เป็น UI feedback หลัก
• FontAwesome เป็น icon source หลัก

16. สรุป

ระบบ Training System ฉบับนี้ต้องถูกออกแบบให้เป็น multi-tenant web application บน stack ของโปรเจ็กต์ปัจจุบัน โดยใช้:

• Next.js App Router
• Auth.js
• PostgreSQL + Drizzle
• React Query + nuqs
• TanStack Form + Zod
• shadcn/ui + Tailwind CSS

และต้องจัดวางฟีเจอร์ตาม feature architecture ของรีโป เพื่อให้สามารถพัฒนาต่อจากฐานโค้ดนี้ได้จริง