alla-tms/docs/permission-matrix-ui-improvement-report.md

Permission Matrix UI Improvement Report

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

1. Summary

ปรับปรุงหน้า Permission Matrix และ Permission Catalog ให้ผู้ใช้งานเข้าใจ permission แต่ละรายการได้ง่ายขึ้น โดยเพิ่ม metadata ระดับคำอธิบายภาษาไทยให้ทุก permission และปรับ UI ให้แสดงข้อมูลตามลำดับ:

• Permission Name
• Description
• Permission Code
• Action Badge

รอบนี้เป็นการปรับปรุงเฉพาะ UI/UX และ catalog metadata เท่านั้น โดยไม่เปลี่ยน business logic, permission code, authorization, API contract หลัก หรือ database schema

2. Files Modified

• src/features/permission-management/api/types.ts
• src/features/permission-management/server/permission-management-catalog.ts
• src/features/permission-management/components/permission-matrix.tsx
• src/features/permission-management/components/permission-template-form-sheet.tsx

3. UI Changes

สิ่งที่เปลี่ยนในหน้า Permission Matrix:

• เปลี่ยนจากแสดงแค่ action + permission code
• เพิ่ม permission.description ภาษาไทยในแต่ละ card
• แสดง permission.code ด้วย font-mono
• ปรับ typography:
  • name ใช้ text-base font-semibold
  • description ใช้ text-sm text-muted-foreground
  • code ใช้ font-mono text-xs
• คง Action badge เดิมไว้

ผลลัพธ์คือผู้ใช้สามารถอ่านแล้วเข้าใจได้ทันทีว่า permission นั้น “ใช้ทำอะไร” โดยไม่ต้องเดาจาก code

นอกจากนี้ใน Permission Template Form ก็เปลี่ยนให้แสดง description จาก catalog เดียวกันด้วย เพื่อไม่ hardcode ข้อความและรองรับการใช้งานต่อในอนาคต

4. Permission Catalog Changes

ปรับ catalog เดิมใน src/features/permission-management/server/permission-management-catalog.ts โดยเพิ่ม metadata ต่อ permission ดังนี้:

• module
• action
• code
• name
• description
• descriptionEn

และยังคง field compatibility เดิมไว้ด้วย:

• value
• label

ดังนั้น component เดิมที่อิง permission.value ยังใช้ต่อได้ และ component ใหม่สามารถอ่าน permission.description ได้ทันที

5. Permission Coverage

ผลการตรวจสอบ catalog:

• จำนวน permission ทั้งหมดในระบบ: 78
• จำนวน permission ที่มี metadata ครบ: 78
• จำนวน permission ที่ขาดคำอธิบาย: 0
• จำนวน permission ที่ขาด field สำคัญ (module, action, code, name, description): 0

ยืนยันว่า permission ทุกตัวมีข้อมูลครบ:

• module
• action
• code
• name
• description

6. Compatibility

ยืนยันว่าในการเปลี่ยนรอบนี้:

• Permission Code ไม่เปลี่ยน
• Business Logic ไม่เปลี่ยน
• Authorization ไม่เปลี่ยน
• API ไม่เปลี่ยนในเชิงพฤติกรรมการอนุญาต
• Database ไม่เปลี่ยน

รอบนี้เป็น UX improvement ของ catalog และการ render UI เท่านั้น

7. Verification

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

• npx oxlint src/features/permission-management src/app/api/permissions src/features/permission-management/server/permission-management-catalog.ts ผ่าน
• npx tsc --noEmit ผ่าน
• coverage check ของ permission catalog:
  • total permissions = 78
  • coverage = 78
  • missing = 0
  • incomplete = 0
• หน้า Permission Matrix แสดง description จาก permission.description
• Permission Code ยังคงเดิมทุกตัว