alla-tms/docs/policy-management-enhancement-report.md

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