alla-tms/plans/implementation-plan.md

Training System Implementation Plan

เอกสารนี้สรุป implementation plan แบบ phase-by-phase สำหรับพัฒนาระบบ Training System บน stack ของโปรเจ็กต์นี้

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

เอกสารนี้อ้างอิงจาก req.md และออกแบบให้สอดคล้องกับ feature-based architecture ของรีโปนี้

Phase 0: Foundation Alignment

เป้าหมาย:

• ทำให้ requirement, domain language, และโครงสร้างข้อมูลสอดคล้องกับ stack และ architecture ของโปรเจ็กต์

งานหลัก:

• ยืนยันคำศัพท์โดเมนหลัก:
  • organization
  • membership
  • user
  • employee
  • course
  • training_record
  • certificate
  • training_matrix
• แยกความหมายของ user กับ employee ให้ชัด
• ยืนยัน status values กลางของระบบ เช่น:
  • pending
  • approved
  • rejected
  • needs_revision
• ยืนยัน training types:
  • online
  • onsite
  • internal
  • external
• กำหนด naming convention สำหรับ:
  • database tables
  • route handlers
  • query keys
  • feature folders

ผลลัพธ์:

• domain language ชัดเจน
• requirement พร้อมสำหรับลงมือทำ

Phase 1: Auth, Organization, and RBAC Core

เป้าหมาย:

• วาง auth และ multi-tenant foundation ให้ทุกฟีเจอร์ใหม่ใช้งานร่วมกันได้

งานหลัก:

• ใช้ Auth.js เป็น auth boundary หลัก
• ใช้ตาราง:
  • users
  • organizations
  • memberships
• ทำ server-side helpers:
  • requireSession()
  • requireOrganizationAccess()
  • requireRole() เมื่อจำเป็น
• ปรับ route protection สำหรับ dashboard และ protected API
• ทำ session shape ให้ client ใช้:
  • activeOrganizationId
  • activeOrganizationName
  • role
  • permissions
• ปรับ navigation filtering ให้ดึงจาก app-owned session

ผลลัพธ์:

• ระบบ login/logout ใช้งานได้
• organization switching ใช้งานได้
• role-based access เริ่มทำงานได้

Acceptance Criteria:

• ผู้ใช้ที่ไม่ login เข้า dashboard ไม่ได้
• ผู้ใช้ที่ไม่มี active organization เข้า org-scoped page ไม่ได้
• visibility ของ nav เปลี่ยนตาม session และ role

Phase 2: Shared Domain Schema

เป้าหมาย:

• วาง schema กลางของระบบ Training System ใน PostgreSQL ด้วย Drizzle

งานหลัก:

• เพิ่ม schema สำหรับ:
  • departments
  • positions
  • employees
  • courses
  • training_records
  • certificates
  • training_matrices
• ทุก business table ต้องมี organizationId
• กำหนด foreign keys ให้ครบ
• เพิ่ม timestamps และ audit-friendly fields ตามความเหมาะสม
• สร้างและ apply migration

ผลลัพธ์:

• database model ครบพอสำหรับสร้างฟีเจอร์หลัก

Acceptance Criteria:

• schema build ผ่าน
• migration ใช้งานได้
• relation หลัก query ได้จริง

Phase 3: Employee Management

เป้าหมาย:

• มี master data พนักงานที่ใช้เป็นฐานของการบันทึกอบรม

งานหลัก:

• สร้าง feature employees
• เพิ่มไฟล์:
  • src/features/employees/api/types.ts
  • src/features/employees/api/service.ts
  • src/features/employees/api/queries.ts
  • src/features/employees/api/mutations.ts
  • src/features/employees/components/*
  • src/features/employees/schemas/*
• เพิ่ม route handlers:
  • GET /api/employees
  • POST /api/employees
  • GET /api/employees/:id
  • PATCH /api/employees/:id
• สร้าง dashboard page สำหรับ list และ create/edit
• ใช้ React Query + nuqs table pattern

ข้อมูลหลัก:

• employee code
• full name
• department
• position
• company
• active status

ผลลัพธ์:

• admin จัดการข้อมูล employee ได้

Acceptance Criteria:

• list/filter/search/pagination ทำงาน
• create/update/disable employee ทำงาน
• จำกัดข้อมูลตาม organization

Phase 4: Course Management

เป้าหมาย:

• มี course catalog กลางของ organization

งานหลัก:

• สร้าง feature courses
• เพิ่ม CRUD route handlers และ Drizzle queries
• สร้าง list page และ create/edit form
• ใช้ table pattern เดียวกับ products และ users

ข้อมูลหลัก:

• course name
• category
• organizer
• standard hours
• certificate validity
• required flag

ผลลัพธ์:

• admin จัดการหลักสูตรได้

Acceptance Criteria:

• create/update/delete course ทำงาน
• list/filter/search/sort ทำงาน
• course ถูกจำกัดตาม organization

Phase 5: Training Record CRUD

เป้าหมาย:

• ทำ flow หลักของระบบให้ผู้ใช้บันทึกประวัติการอบรมได้จริง

งานหลัก:

• สร้าง feature training-records
• เพิ่ม route handlers:
  • GET /api/training-records
  • POST /api/training-records
  • GET /api/training-records/:id
  • PATCH /api/training-records/:id
  • DELETE /api/training-records/:id
• สร้างหน้า:
  • list page
  • detail page
  • create/edit form
• ใช้ TanStack Form + Zod
• ใช้ React Query mutations + invalidation

ข้อมูลหลัก:

• employee
• course
• training date
• training type
• hours
• organizer
• note
• approval status

ผลลัพธ์:

• ผู้ใช้เพิ่มและจัดการประวัติการอบรมได้

Acceptance Criteria:

• user เพิ่ม record ได้
• user เห็นเฉพาะ record ที่เกี่ยวข้องตาม policy
• admin เห็น records ภายใน organization

Phase 6: Certificate Upload and Metadata

เป้าหมาย:

• รองรับไฟล์ใบรับรองและ metadata อย่างเป็นระบบ

งานหลัก:

• เพิ่ม certificate model และ route handlers ที่เกี่ยวข้อง
• เก็บ metadata ใน PostgreSQL:
  • fileName
  • fileType
  • fileSize
  • storageKey
  • uploadedAt
• ผูก certificate กับ training_record
• เพิ่ม upload flow และ preview/open flow
• กำหนดข้อจำกัดไฟล์:
  • pdf
  • jpg
  • jpeg
  • png

ผลลัพธ์:

• training record มีหลักฐานแนบได้จริง

Acceptance Criteria:

• upload สำเร็จ
• metadata ถูกบันทึก
• เปิดดูย้อนหลังได้
• validation ประเภทและขนาดไฟล์ทำงาน

Phase 7: Approval Workflow

เป้าหมาย:

• ให้ admin ตรวจสอบและอนุมัติรายการอบรมได้

งานหลัก:

• เพิ่ม admin queue สำหรับรายการ pending
• เพิ่ม actions:
  • approve
  • reject
  • request changes
• เก็บ reviewer note
• กำหนด policy การแก้ไข record หลัง approve
• เพิ่ม filtering ตาม status

ผลลัพธ์:

• ระบบมี workflow ตรวจสอบจริง

Acceptance Criteria:

• admin เปลี่ยนสถานะได้
• user เห็นสถานะล่าสุดได้
• unauthorized user เปลี่ยนสถานะไม่ได้

Phase 8: Training Matrix

เป้าหมาย:

• ทำ logic ความครบถ้วนตาม requirement ของแต่ละตำแหน่งหรือแผนก

งานหลัก:

• สร้าง feature training-matrix
• รองรับ mapping:
  • department -> required courses
  • position -> required courses
• เตรียมรองรับ employee-specific overrides ในอนาคต
• เพิ่มหน้า admin สำหรับจัดการ matrix
• เพิ่ม query/helper สำหรับคำนวณ compliance

คำตัดสินเชิงกติกาที่ต้อง implement:

• ใช้เฉพาะ approved training records
• course ที่หมดอายุสามารถถือว่าไม่ครบได้ ถ้าระบบกำหนด validity
• matrix ต้องคำนวณในระดับ organization เสมอ

ผลลัพธ์:

• ระบบสามารถตอบได้ว่าใครครบหรือยังไม่ครบ

Acceptance Criteria:

• admin กำหนด matrix ได้
• employee compliance คำนวณได้
• dashboard/report เรียกใช้ข้อมูลนี้ได้

Phase 9: Dashboards and Analytics

เป้าหมาย:

• ทำ dashboard ให้สะท้อนข้อมูลธุรกิจจริง

งานหลัก:

• User dashboard:
  • total courses
  • total training hours
  • total certificates
  • missing required courses
  • training chart by month/year
• Admin dashboard:
  • employee count
  • total hours
  • pending approvals
  • compliance percentage
  • charts by department/category/time
• ใช้ Recharts
• ใช้ server prefetch + HydrationBoundary + useSuspenseQuery

ผลลัพธ์:

• dashboard ใช้ข้อมูลจาก DB จริง

Acceptance Criteria:

• metrics ถูกต้อง
• charts render ได้
• organization scoping ถูกต้อง

Phase 10: Reports and Export

เป้าหมาย:

• เพิ่ม reporting สำหรับใช้งานจริงของ admin

งานหลัก:

• สร้าง feature reports
• ทำรายงาน:
  • individual training history
  • department training summary
  • accumulated hours
  • missing required courses
  • expiring certificates
  • organization training matrix summary
• เริ่มจาก on-screen report pages
• เพิ่ม export ใน phase ย่อยถัดไป เช่น CSV หรือ PDF

ผลลัพธ์:

• admin ตรวจสอบข้อมูลย้อนหลังและสรุปผลได้

Acceptance Criteria:

• รายงานโหลดได้
• filter/report criteria ใช้งานได้
• export อย่างน้อย 1 รูปแบบเมื่อรวมใน scope

Phase 11: UX, Theme, and Hardening

เป้าหมาย:

• polish ระบบให้พร้อมใช้งานและขยายต่อ

งานหลัก:

• ปรับ visual theme ตาม requirement ผ่าน theme system ของโปรเจ็กต์
• ใช้สีหลัก:
  • #336b4a
  • #808285
  • #e26631
  • #413b60
• จัด empty/loading/error/access states ให้ครบ
• ปรับ mobile behavior ของ table และ form
• เพิ่ม validation messages ให้สม่ำเสมอ
• เก็บ lint/type/build issues ให้สะอาด
• เพิ่ม test coverage ใน critical flows

ผลลัพธ์:

• ระบบพร้อม demo และพร้อมพัฒนาต่อ

Acceptance Criteria:

• build ผ่าน
• ไม่มี lint issue ใหม่จากส่วนที่เพิ่ม
• flow หลักใช้งานได้ทั้ง desktop และ mobile

Milestones ที่แนะนำ

Milestone A

• Phase 1
• Phase 2
• Phase 3
• Phase 4

ผลลัพธ์:

• organization foundation พร้อม
• employee และ course CRUD พร้อม

Milestone B

• Phase 5
• Phase 6

ผลลัพธ์:

• training records และ certificate flow ใช้งานได้

Milestone C

• Phase 7
• Phase 8

ผลลัพธ์:

• approval workflow และ training matrix ใช้งานได้

Milestone D

• Phase 9
• Phase 10
• Phase 11

ผลลัพธ์:

• dashboard, reports, และ UX polish พร้อมใช้งาน

ลำดับลงมือที่แนะนำ

1. ทำ shared schema และ domain foundation ให้ครบก่อน
2. ทำ master data คือ employees และ courses
3. ทำ training-records และ certificates
4. ทำ approval workflow
5. ทำ training matrix
6. ทำ dashboard และ reports
7. ทำ polish และ hardening

Mapping กับโครงสร้างรีโป

feature ที่ควรมีใน src/features/:

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

page routes ที่ควรมีใน src/app/dashboard/:

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

API routes ที่ควรมีใน src/app/api/:

• employees
• courses
• training-records
• certificates
• training-matrix
• reports เมื่อจำเป็น

หมายเหตุสำหรับการ implement

• ใช้ PageContainer สำหรับ page header ทุกหน้า
• ใช้ apiClient สำหรับเรียก local route handlers จาก service.ts
• ใช้ queryOptions และ mutationOptions ตาม pattern เดิม
• ใช้ Icons จาก @/components/icons
• อย่าใช้ mock data สำหรับฟีเจอร์ใหม่
• อย่าใช้ vendor UI ภายนอกแทน component patterns ของโปรเจ็กต์