commit

docs/policy-management-enhancement-report.md

@@ -0,0 +1,124 @@
+# Policy Management Enhancement Report
+
+## 1. Existing Structure Review
+
+- พบว่าโมดูล `training-policy` เดิมเชื่อมฐานข้อมูลจริงอยู่แล้ว แต่ยังมี scope ค่อนข้างเล็ก ใช้เพียง `year`, `total_hours`, `k_hours`, `s_hours`, `a_hours`, `is_active`
+- ส่วนที่ Reuse:
+  - โครง `src/features/<feature>/api/{types,service,queries,mutations}.ts`
+  - Route Handlers ใต้ `src/app/api/training-policies/**`
+  - `useAppForm` + Zod schema เดิม
+  - shared DataTable stack (`DataTable`, `DataTableToolbar`, `useDataTable`, `DataTableColumnHeader`)
+  - audit log infrastructure เดิม
+- ส่วนที่ Refactor:
+  - เปลี่ยน access control จาก `requireHRD()` เป็น permission-first ผ่าน `requirePermission(...)`
+  - ปรับ list API ให้รองรับ pagination / search / status / sort
+  - ปรับหน้า dashboard ให้ใช้ query-string driven table pattern แบบ feature อื่นใน repo
+- ส่วนที่ Extend:
+  - detail endpoint
+  - clone / activate / deactivate endpoints
+  - history endpoint ที่ดึงจาก audit log
+  - action menu และ detail sheet ฝั่ง UI
+- ส่วนที่สร้างใหม่:
+  - route handlers สำหรับ `clone`, `activate`, `deactivate`, `history`
+  - helper permission dashboard guard แบบ generic
+  - UI table flow ใหม่สำหรับ policy management
+
+## 2. Files Changed
+
+- `src/app/api/training-policies/route.ts`
+- `src/app/api/training-policies/[id]/route.ts`
+- `src/app/api/training-policies/[id]/clone/route.ts`
+- `src/app/api/training-policies/[id]/activate/route.ts`
+- `src/app/api/training-policies/[id]/deactivate/route.ts`
+- `src/app/api/training-policies/[id]/history/route.ts`
+- `src/app/dashboard/training-policy/page.tsx`
+- `src/features/audit-logs/server/audit-log-data.ts`
+- `src/features/audit-logs/server/audit-service.ts`
+- `src/features/training-policy/api/types.ts`
+- `src/features/training-policy/api/service.ts`
+- `src/features/training-policy/api/queries.ts`
+- `src/features/training-policy/api/mutations.ts`
+- `src/features/training-policy/schemas/training-policy.ts`
+- `src/features/training-policy/server/training-policy-data.ts`
+- `src/features/training-policy/components/training-policy-form.tsx`
+- `src/features/training-policy/components/training-policy-page.tsx`
+- `src/lib/auth/page-guards.ts`
+
+## 3. Database Changes
+
+- ไม่มี migration ในรอบนี้
+- ไม่มีการเพิ่ม column / index / constraint
+- เลือก reuse schema เดิมเพื่อลดผลกระทบกับ runtime data และให้ enhancement รอบแรก deploy ได้เร็ว
+
+## 4. Permission Matrix
+
+- `training_policy:read`
+  - list policy
+  - view policy detail
+  - view policy history
+- `training_policy:write`
+  - create
+  - edit
+  - clone
+  - activate
+  - deactivate
+
+หมายเหตุ: prompt เป้าหมายต้องการ permission แยกละเอียดกว่านี้ แต่ permission catalog ปัจจุบันมีเพียง `read` และ `write` สำหรับโมดูลนี้
+
+## 5. Business Rules
+
+- 1 องค์กรมี policy active ได้เพียง 1 รายการ
+- หากเปิดใช้งาน policy ใหม่ ระบบจะปิด policy อื่นในองค์กรก่อน
+- clone จะคัดลอกค่า hours ทั้งหมด แต่ตั้ง `is_active = false`
+- clone จะหา `year` ถัดไปที่ยังไม่ซ้ำโดยเริ่มจาก `source.year + 1`
+- create / update ยังบังคับ rule เดิม: `K + S + A` ต้องเท่ากับ `totalHours`
+- duplicate year ในองค์กรเดียวกันจะถูก block ที่ server
+
+## 6. Versioning
+
+- รอบนี้ยังไม่มี version table หรือ field-level diff versioning ในฐานข้อมูล
+- ใช้ audit history เป็น lightweight history layer ชั่วคราวสำหรับการตรวจย้อนหลัง
+
+## 7. Audit Log
+
+- รองรับ action:
+  - `CREATE`
+  - `UPDATE`
+  - `CLONE`
+  - `ACTIVATE`
+  - `DEACTIVATE`
+- history ดึงจาก `audit_logs` โดย filter `module_name = TRAINING_POLICY`
+
+## 8. UI Screens
+
+- List:
+  - shared DataTable
+  - search / status filter / pagination / sorting
+  - row action menu
+- View:
+  - detail sheet
+  - history section
+- Create / Edit:
+  - sheet + existing TanStack Form pattern
+
+## 9. Testing
+
+- ตรวจ `npm run lint` ผ่าน
+- ตรวจ `npm run build` ผ่าน
+- ไม่มี automated CRUD / permission / responsive regression test เพิ่มในรอบนี้
+
+## 10. Remaining Improvements
+
+- เพิ่ม schema จริงสำหรับ:
+  - policy name
+  - description
+  - effective date
+  - archived / restored state
+  - version
+  - mandatory courses
+  - certificate policy
+  - advanced settings
+- แยก permission ให้ละเอียดตาม action (`clone`, `activate`, `audit`, `restore`)
+- เพิ่ม soft delete / restore ตาม archived workflow
+- เพิ่ม field-level version comparison
+- เพิ่ม scheduled activation / policy comparison / rollback