commit
This commit is contained in:
455
plans/implementation-plan.md
Normal file
455
plans/implementation-plan.md
Normal file
@@ -0,0 +1,455 @@
|
||||
# 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 ของโปรเจ็กต์
|
||||
Reference in New Issue
Block a user