# 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](./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 ของโปรเจ็กต์