alla-tms/docs/role-permission-management-implementation-report.md

Role & Permission Management Implementation Report

วันที่อัปเดต: 2026-07-07

1. Summary

พัฒนา Coding Phase 1 ของระบบ Role & Permission Management ตามแผนใน docs/role-permission-management-plan.md โดยยังคง compatibility mode เดิมของระบบไว้ และยังไม่ย้าย feature อื่นไปใช้ permission-first model

สิ่งที่ทำแล้ว:

• สร้าง feature module src/features/permission-management/
• เพิ่มหน้า dashboard:
  • /dashboard/permissions/templates
  • /dashboard/permissions/matrix
  • /dashboard/permissions/users
  • /dashboard/permissions/audit-logs
• เพิ่ม route handlers สำหรับ permission templates, permission catalog, user permission assignments, overrides, และ permission audit logs
• เพิ่ม super-admin-only page guard สำหรับหน้า permission management
• เพิ่มเมนู Permission Management ใน sidebar โดยมองเห็นเฉพาะ super_admin
• เพิ่ม report และ TODO ที่จำเป็นโดยไม่แก้ schema/migration ตามข้อกำหนดของ phase นี้

2. Files Created

• src/features/permission-management/api/types.ts
• src/features/permission-management/api/service.ts
• src/features/permission-management/api/queries.ts
• src/features/permission-management/api/mutations.ts
• src/features/permission-management/schemas/permission-template.ts
• src/features/permission-management/schemas/user-permission-assignment.ts
• src/features/permission-management/server/permission-management-catalog.ts
• src/features/permission-management/server/permission-audit-service.ts
• src/features/permission-management/server/permission-template-data.ts
• src/features/permission-management/server/user-permission-data.ts
• src/features/permission-management/server/permission-audit-data.ts
• src/features/permission-management/components/permission-status-badge.tsx
• src/features/permission-management/components/permission-template-form-sheet.tsx
• src/features/permission-management/components/permission-template-row-actions.tsx
• src/features/permission-management/components/permission-template-columns.tsx
• src/features/permission-management/components/permission-template-table.tsx
• src/features/permission-management/components/permission-template-listing.tsx
• src/features/permission-management/components/permission-matrix.tsx
• src/features/permission-management/components/effective-permission-preview.tsx
• src/features/permission-management/components/user-permission-sheet.tsx
• src/features/permission-management/components/user-permission-row-actions.tsx
• src/features/permission-management/components/user-permission-columns.tsx
• src/features/permission-management/components/user-permission-table.tsx
• src/features/permission-management/components/user-permission-listing.tsx
• src/features/permission-management/components/permission-audit-log-columns.tsx
• src/features/permission-management/components/permission-audit-log-table.tsx
• src/features/permission-management/components/permission-audit-log-listing.tsx
• src/app/dashboard/permissions/templates/page.tsx
• src/app/dashboard/permissions/matrix/page.tsx
• src/app/dashboard/permissions/users/page.tsx
• src/app/dashboard/permissions/audit-logs/page.tsx
• src/app/api/permissions/catalog/route.ts
• src/app/api/permission-templates/route.ts
• src/app/api/permission-templates/[id]/route.ts
• src/app/api/permission-templates/[id]/clone/route.ts
• src/app/api/permission-templates/[id]/activate/route.ts
• src/app/api/permission-templates/[id]/deactivate/route.ts
• src/app/api/user-permissions/route.ts
• src/app/api/user-permissions/[userId]/route.ts
• src/app/api/user-permissions/[userId]/assignment/route.ts
• src/app/api/user-permissions/[userId]/overrides/route.ts
• src/app/api/user-permissions/[userId]/overrides/[overrideId]/route.ts
• src/app/api/user-permissions/[userId]/effective/route.ts
• src/app/api/permission-audit-logs/route.ts
• docs/role-permission-management-implementation-report.md

3. Files Modified

• src/lib/auth/session.ts
• src/lib/auth/page-guards.ts
• src/config/nav-config.ts

4. API Implemented

Permission Templates

• GET /api/permission-templates
• POST /api/permission-templates
• GET /api/permission-templates/[id]
• PATCH /api/permission-templates/[id]
• DELETE /api/permission-templates/[id]
• POST /api/permission-templates/[id]/clone
• POST /api/permission-templates/[id]/activate
• POST /api/permission-templates/[id]/deactivate

Permission Catalog

• GET /api/permissions/catalog

User Permissions

• GET /api/user-permissions
• GET /api/user-permissions/[userId]
• PUT /api/user-permissions/[userId]/assignment
• GET /api/user-permissions/[userId]/effective
• POST /api/user-permissions/[userId]/overrides
• PATCH /api/user-permissions/[userId]/overrides/[overrideId]
• DELETE /api/user-permissions/[userId]/overrides/[overrideId]

Permission Audit Logs

• GET /api/permission-audit-logs

5. UI Pages

• Permission Templates

  • table + search + pagination + sorting
  • create/edit sheet
  • clone / activate / deactivate / soft delete actions

• Permission Matrix

  • grouped permission catalog
  • read-only checklist-style layout

• User Permissions

  • user table + search
  • manage sheet สำหรับ assign template และ allow/deny permissions
  • effective permission preview

• Permission Audit Logs

  • table + filters ผ่าน query params เดิมของระบบ
  • data source ใหม่จาก permission_audit_logs

6. Remaining TODO

• เพิ่ม DB-level constraint สำหรับ 1 active template per user per organization
• เพิ่ม index สำหรับ permission_audit_logs ถ้าข้อมูลโต
• ปรับ UI assignment ให้รองรับ granular override management แบบแยก create/edit/delete ในหน้าเดียว
• แสดง target user ใน permission audit log ให้ครบกว่านี้
• เพิ่ม form-level search/filter สำหรับ permission checklist เมื่อจำนวน permission โตขึ้น
• เชื่อม default template seed จริงในฐานข้อมูล

7. Known Limitations

• phase นี้ยังไม่แก้ schema หรือ migration ตาม requirement
• การบังคับ 1 active template ตอนนี้ทำใน application logic และมี TODO ชัดเจนไว้ใน server layer
• หน้า User Permissions ใช้ flow แบบ save assignment ทั้งชุดในครั้งเดียวเป็นหลัก แม้ route override แยกจะถูกสร้างไว้แล้ว
• หน้า Permission Matrix เป็น read-only reference screen ยังไม่ใช่ editor เต็มรูปแบบ
• หน้า Permission Audit Logs ยังแสดงรายละเอียดแบบย่อ และยังไม่ได้ reuse UI รายการเดิมแบบ 100% ในเชิง component-level

8. Compatibility Status

ยังคง compatibility mode เดิมไว้ทั้งหมด:

• ไม่ลบ businessRole
• ไม่ลบ isHRD()
• ไม่ลบ isIT()
• ไม่ย้าย feature runtime อื่นไปใช้ permission-first ในรอบนี้
• ไม่แก้ navigation เดิม ยกเว้นเพิ่มเมนู Permission Management
• authorization ของหน้าและ API ใหม่ทั้งหมดใช้ super_admin เท่านั้น โดยไม่กระทบ flow เดิมของ HRD / IT / Employee

Verification

ตรวจสอบแล้ว:

• npx oxlint src/features/permission-management src/app/api/permission-templates src/app/api/user-permissions src/app/api/permissions src/app/api/permission-audit-logs src/app/dashboard/permissions src/config/nav-config.ts src/lib/auth/page-guards.ts src/lib/auth/session.ts ผ่าน
• npx tsc --noEmit ผ่าน