764 lines
20 KiB
Markdown
764 lines
20 KiB
Markdown
# Prompt: Refactor Authorization เป็น Permission Template + Permission-first Model
|
|
|
|
## Context
|
|
|
|
โปรเจกต์นี้คือระบบ Training Management System (TMS) ที่ปัจจุบันยังมีการตรวจสอบสิทธิ์จาก `systemRole`, `membership.role`, `businessRole` และ helper เช่น `isHRD()` / `isIT()`
|
|
|
|
ต้องการปรับระบบสิทธิ์ใหม่ให้เป็น **Permission-first Authorization Model** โดยตัดแนวคิดว่า “Role คือสิทธิ์” ออก และเปลี่ยนมาใช้ **Permission Template** เป็นชุดสิทธิ์ต้นแบบแทน
|
|
|
|
อ้างอิงจากแผนเดิมใน `role-permission-migration-plan.md` ที่ระบุว่าควรย้ายระบบจาก role/helper เดิมไปสู่ permission-based model และให้ API/server ใช้ permission เป็นตัวตัดสินสิทธิ์จริง
|
|
|
|
---
|
|
|
|
## Final Direction
|
|
|
|
ให้เปลี่ยนแนวคิดจากเดิม:
|
|
|
|
```text
|
|
User
|
|
-> Role
|
|
-> Permission
|
|
```
|
|
|
|
เป็น:
|
|
|
|
```text
|
|
Organization
|
|
-> Permission Template
|
|
-> Permissions
|
|
-> User Assignment
|
|
-> User Permission Override
|
|
-> Effective Permissions
|
|
```
|
|
|
|
หลักการสำคัญ:
|
|
|
|
- Permission คือ source of truth
|
|
- Permission Template เป็นเพียงชุดสิทธิ์ต้นแบบ
|
|
- User ได้รับสิทธิ์จาก Template
|
|
- User สามารถมี Permission Override รายบุคคลได้
|
|
- ระบบต้องรองรับหลายองค์กร
|
|
- UI ซ่อน/แสดงได้ตาม Permission
|
|
- API/server ต้องตรวจ Permission เสมอ
|
|
- ห้ามใช้ Role เป็นตัวตัดสินสิทธิ์หลักอีกต่อไป
|
|
|
|
---
|
|
|
|
## Required Work
|
|
|
|
### 1. Audit Existing Authorization
|
|
|
|
ตรวจสอบโค้ดทั้งหมดก่อนแก้ไข
|
|
|
|
ค้นหาการใช้งาน:
|
|
|
|
```ts
|
|
systemRole
|
|
membership.role
|
|
businessRole
|
|
isHRD()
|
|
isIT()
|
|
requireHRD()
|
|
requireIT()
|
|
requireUserManagementAccess()
|
|
role === ...
|
|
```
|
|
|
|
ตรวจสอบในส่วน:
|
|
|
|
- API routes
|
|
- Server actions
|
|
- Page guards
|
|
- Navigation
|
|
- Feature components
|
|
- Data helpers
|
|
- Auth/session helpers
|
|
- User management
|
|
- Middleware
|
|
|
|
ให้สรุปก่อนว่าไฟล์ใดยังใช้ role-based authorization อยู่
|
|
|
|
---
|
|
|
|
### 2. Create Permission Catalog
|
|
|
|
สร้าง permission catalog กลาง เช่น:
|
|
|
|
```text
|
|
src/lib/auth/permissions.ts
|
|
```
|
|
|
|
ต้องมี permission constants และ type-safe permission list
|
|
|
|
ตัวอย่างกลุ่ม permission:
|
|
|
|
```ts
|
|
organization:manage
|
|
organization:switch
|
|
|
|
permission_template:read
|
|
permission_template:create
|
|
permission_template:update
|
|
permission_template:clone
|
|
permission_template:delete
|
|
permission_template:assign
|
|
|
|
user_permission:read
|
|
user_permission:update
|
|
user_permission:override
|
|
user_permission:remove_override
|
|
|
|
users:read
|
|
users:create
|
|
users:update
|
|
users:delete
|
|
users:manage
|
|
|
|
employee_directory:read
|
|
employee_directory:write
|
|
employee_import:run
|
|
employee_master_review:approve
|
|
|
|
training_record:self_read
|
|
training_record:self_write
|
|
training_record:read_all
|
|
training_record:write_all
|
|
training_record:submit
|
|
training_record:review
|
|
training_record:approve
|
|
training_record:reject
|
|
training_record:delete_draft
|
|
training_record:manage_attachments
|
|
|
|
announcement:read_public
|
|
announcement:read_all
|
|
announcement:create
|
|
announcement:edit_draft
|
|
announcement:delete_draft
|
|
announcement:submit
|
|
announcement:approve
|
|
announcement:reject
|
|
announcement:publish
|
|
announcement:schedule
|
|
announcement:unpublish
|
|
announcement:archive
|
|
announcement:restore
|
|
announcement:revision
|
|
announcement:preview
|
|
announcement:view_history
|
|
|
|
online_lesson:read_public
|
|
online_lesson:read_all
|
|
online_lesson:create
|
|
online_lesson:edit_draft
|
|
online_lesson:delete_draft
|
|
online_lesson:submit
|
|
online_lesson:approve
|
|
online_lesson:reject
|
|
online_lesson:publish
|
|
online_lesson:schedule
|
|
online_lesson:unpublish
|
|
online_lesson:archive
|
|
online_lesson:restore
|
|
online_lesson:revision
|
|
online_lesson:preview
|
|
online_lesson:view_history
|
|
|
|
reports:self_read
|
|
reports:organization_read
|
|
reports:export
|
|
reports:export_excel
|
|
reports:export_pdf
|
|
|
|
audit_logs:read
|
|
audit_logs:export
|
|
|
|
notifications:read
|
|
notifications:manage
|
|
```
|
|
|
|
---
|
|
|
|
### 3. Add Permission Template Data Model
|
|
|
|
ตรวจสอบ schema เดิมก่อนแก้ไข
|
|
|
|
ให้เพิ่มหรือปรับ database model ให้รองรับ:
|
|
|
|
```text
|
|
organizations
|
|
permission_templates
|
|
permission_template_permissions
|
|
user_permission_template_assignments
|
|
user_permission_overrides
|
|
permission_audit_logs
|
|
```
|
|
|
|
โครงสร้างต้องรองรับ:
|
|
|
|
- หลายองค์กร
|
|
- แต่ละองค์กรมี Permission Template ของตัวเอง
|
|
- Template สร้างได้
|
|
- Template แก้ไขได้
|
|
- Template Clone ได้
|
|
- Template ลบได้
|
|
- Template ที่ถูกใช้งานอยู่ต้องห้ามลบ หรือให้ soft delete เท่านั้น
|
|
- User 1 คนสามารถถูก assign template ได้อย่างน้อย 1 template ต่อ organization
|
|
- User สามารถมี permission override รายบุคคลได้
|
|
- Override ต้องรองรับทั้ง `allow` และ `deny`
|
|
- Override สามารถมี optional expiration date ได้ ถ้าออกแบบได้โดยไม่กระทบระบบมาก
|
|
- ทุกการเปลี่ยนแปลงต้องมี audit log
|
|
|
|
---
|
|
|
|
### 4. Default Permission Templates
|
|
|
|
สร้าง default templates เป็น seed data ไม่ใช่ hard-code role
|
|
|
|
ต้องมี template เริ่มต้นอย่างน้อย:
|
|
|
|
```text
|
|
Employee
|
|
HRD Staff
|
|
HRD Manager
|
|
Org Admin
|
|
IT Admin
|
|
Super Admin
|
|
```
|
|
|
|
ตัวอย่างสิทธิ์:
|
|
|
|
#### Employee
|
|
|
|
```text
|
|
notifications:read
|
|
announcement:read_public
|
|
online_lesson:read_public
|
|
training_record:self_read
|
|
training_record:self_write
|
|
training_record:submit
|
|
reports:self_read
|
|
```
|
|
|
|
#### HRD Staff
|
|
|
|
ได้ Employee permissions และเพิ่ม:
|
|
|
|
```text
|
|
employee_directory:read
|
|
employee_directory:write
|
|
courses:read
|
|
courses:write
|
|
training_matrix:read
|
|
training_matrix:write
|
|
training_record:read_all
|
|
training_record:write_all
|
|
announcement:read_all
|
|
announcement:create
|
|
announcement:edit_draft
|
|
announcement:delete_draft
|
|
announcement:submit
|
|
announcement:preview
|
|
online_lesson:read_all
|
|
online_lesson:create
|
|
online_lesson:edit_draft
|
|
online_lesson:delete_draft
|
|
online_lesson:submit
|
|
online_lesson:preview
|
|
```
|
|
|
|
ห้ามมี:
|
|
|
|
```text
|
|
announcement:approve
|
|
announcement:publish
|
|
announcement:schedule
|
|
announcement:archive
|
|
online_lesson:approve
|
|
online_lesson:publish
|
|
online_lesson:schedule
|
|
online_lesson:archive
|
|
```
|
|
|
|
#### HRD Manager
|
|
|
|
ได้ HRD Staff permissions และเพิ่ม:
|
|
|
|
```text
|
|
training_record:review
|
|
training_record:approve
|
|
training_record:reject
|
|
announcement:approve
|
|
announcement:reject
|
|
announcement:publish
|
|
announcement:schedule
|
|
announcement:unpublish
|
|
announcement:archive
|
|
announcement:restore
|
|
announcement:revision
|
|
announcement:view_history
|
|
online_lesson:approve
|
|
online_lesson:reject
|
|
online_lesson:publish
|
|
online_lesson:schedule
|
|
online_lesson:unpublish
|
|
online_lesson:archive
|
|
online_lesson:restore
|
|
online_lesson:revision
|
|
online_lesson:view_history
|
|
reports:organization_read
|
|
reports:export
|
|
reports:export_excel
|
|
reports:export_pdf
|
|
notifications:manage
|
|
```
|
|
|
|
#### Org Admin
|
|
|
|
```text
|
|
organization:manage
|
|
organization:switch
|
|
users:read
|
|
users:create
|
|
users:update
|
|
users:delete
|
|
users:manage
|
|
employee_directory:read
|
|
employee_directory:write
|
|
permission_template:read
|
|
permission_template:assign
|
|
user_permission:read
|
|
reports:organization_read
|
|
audit_logs:read
|
|
```
|
|
|
|
#### IT Admin / Super Admin
|
|
|
|
```text
|
|
permission_template:read
|
|
permission_template:create
|
|
permission_template:update
|
|
permission_template:clone
|
|
permission_template:delete
|
|
permission_template:assign
|
|
user_permission:read
|
|
user_permission:update
|
|
user_permission:override
|
|
user_permission:remove_override
|
|
users:manage
|
|
audit_logs:read
|
|
audit_logs:export
|
|
organization:manage
|
|
organization:switch
|
|
```
|
|
|
|
---
|
|
|
|
### 5. Permission Helper
|
|
|
|
สร้าง helper กลาง เช่น:
|
|
|
|
```text
|
|
src/lib/auth/authorization.ts
|
|
```
|
|
|
|
ต้องมี function:
|
|
|
|
```ts
|
|
getEffectivePermissions(userId, organizationId)
|
|
|
|
hasPermission(user, permission, context?)
|
|
|
|
hasAnyPermission(user, permissions, context?)
|
|
|
|
hasAllPermissions(user, permissions, context?)
|
|
|
|
requirePermission(user, permission, context?)
|
|
|
|
requireAnyPermission(user, permissions, context?)
|
|
|
|
requireAllPermissions(user, permissions, context?)
|
|
```
|
|
|
|
Effective permissions ต้องคำนวณจาก:
|
|
|
|
```text
|
|
Template permissions
|
|
+ user allow overrides
|
|
- user deny overrides
|
|
- expired overrides
|
|
```
|
|
|
|
เงื่อนไข:
|
|
|
|
- `deny` ต้องมี priority สูงกว่า `allow`
|
|
- expired permission ต้องไม่ถูกนำมาใช้
|
|
- ต้อง scope ตาม organization
|
|
- ต้อง cache ได้ถ้าเหมาะสม
|
|
- ต้อง clear cache เมื่อมีการแก้ template หรือ override
|
|
|
|
---
|
|
|
|
### 6. Session / Auth Update
|
|
|
|
ปรับ session ให้รองรับ permission-first model
|
|
|
|
Session ควรมี:
|
|
|
|
```ts
|
|
userId;
|
|
organizationId;
|
|
organizationIds;
|
|
activeOrganizationId;
|
|
permissionTemplateIds;
|
|
effectivePermissions;
|
|
```
|
|
|
|
คง field เดิม เช่น `businessRole`, `systemRole`, `membership.role` ไว้ชั่วคราวเพื่อ compatibility เท่านั้น
|
|
|
|
ห้ามใช้ field เดิมเป็น source of truth ใหม่
|
|
|
|
---
|
|
|
|
### 7. Permission Template Management UI
|
|
|
|
เพิ่มหน้าจัดการ Permission Template ใน Admin
|
|
|
|
ต้องรองรับ:
|
|
|
|
- ดูรายการ Template
|
|
- สร้าง Template
|
|
- แก้ไข Template
|
|
- Clone Template
|
|
- ลบ Template
|
|
- Soft delete Template ที่เคยถูกใช้งาน
|
|
- ดู Permission ภายใน Template
|
|
- ค้นหา Permission
|
|
- Group Permission ตาม module
|
|
- แสดงจำนวนผู้ใช้งาน Template
|
|
- บันทึกเหตุผลเมื่อแก้ไข
|
|
- เก็บ audit log ทุกครั้ง
|
|
|
|
---
|
|
|
|
### 8. User Permission Assignment UI
|
|
|
|
เพิ่มหรือปรับหน้า User Management ให้รองรับ:
|
|
|
|
- เลือก Organization
|
|
- เลือก User
|
|
- Assign Permission Template ให้ User
|
|
- เปลี่ยน Template
|
|
- แสดง Effective Permissions
|
|
- เพิ่ม Permission เฉพาะราย
|
|
- Deny Permission เฉพาะราย
|
|
- Remove Override
|
|
- กำหนดวันหมดอายุ Override ถ้ารองรับ
|
|
- บันทึกเหตุผล
|
|
- แสดงประวัติการเปลี่ยนสิทธิ์
|
|
|
|
Effective Permission Viewer ต้องแสดง:
|
|
|
|
```text
|
|
Template permissions
|
|
Allow overrides
|
|
Deny overrides
|
|
Expired overrides
|
|
Final effective permissions
|
|
```
|
|
|
|
---
|
|
|
|
### 9. Multi-Organization Support
|
|
|
|
ระบบต้องรองรับหลายองค์กร
|
|
|
|
หลักการ:
|
|
|
|
- Permission Template ต้องผูกกับ organization
|
|
- User assignment ต้องผูกกับ organization
|
|
- User override ต้องผูกกับ organization
|
|
- Effective permissions ต้องคำนวณตาม active organization
|
|
- การ query/write ข้อมูลต้องมี organization context
|
|
- Super Admin / IT Admin อาจ switch organization ได้ตาม permission
|
|
|
|
ต้องตรวจสอบ:
|
|
|
|
- organization switcher
|
|
- membership
|
|
- session
|
|
- API scope
|
|
- audit logs
|
|
- user management
|
|
- reports
|
|
|
|
---
|
|
|
|
### 10. Replace Server-Side Authorization
|
|
|
|
เปลี่ยน API/server guard จาก role-based เป็น permission-based
|
|
|
|
ตัวอย่าง:
|
|
|
|
เดิม:
|
|
|
|
```ts
|
|
if (!isHRD(user)) {
|
|
return forbidden();
|
|
}
|
|
```
|
|
|
|
ใหม่:
|
|
|
|
```ts
|
|
await requirePermission(user, "announcement:create", {
|
|
organizationId,
|
|
});
|
|
```
|
|
|
|
ต้องปรับอย่างน้อย:
|
|
|
|
- Announcements API
|
|
- Online Lessons API
|
|
- Training Records API
|
|
- Users API
|
|
- Employee Directory API
|
|
- Employee Import API
|
|
- Courses API
|
|
- Training Policy API
|
|
- Training Matrix API
|
|
- Reports API
|
|
- Audit Logs API
|
|
- Notifications API
|
|
|
|
สำคัญ:
|
|
|
|
Employee-facing API ต้อง enforce server-side scope เสมอ
|
|
|
|
```text
|
|
announcement / online lesson:
|
|
- status = published
|
|
- is_current = true
|
|
|
|
training records:
|
|
- self-scope เท่านั้น เว้นแต่มี training_record:read_all
|
|
```
|
|
|
|
---
|
|
|
|
### 11. Replace Page Guards And Navigation
|
|
|
|
ปรับ page guard และ navigation ให้ใช้ permission
|
|
|
|
ตัวอย่าง:
|
|
|
|
```ts
|
|
canViewUsers = hasPermission(user, "users:read");
|
|
|
|
canViewPendingReview = hasAnyPermission(user, [
|
|
"training_record:review",
|
|
"announcement:approve",
|
|
"online_lesson:approve",
|
|
]);
|
|
```
|
|
|
|
ห้ามใช้:
|
|
|
|
```ts
|
|
businessRole === "HRD";
|
|
isHRD();
|
|
isIT();
|
|
```
|
|
|
|
เป็นตัวตัดสินหลักอีกต่อไป
|
|
|
|
---
|
|
|
|
### 12. Feature UI Permission Visibility
|
|
|
|
ปรับ component ให้รับ permission context หรือ effective permissions
|
|
|
|
ตัวอย่าง:
|
|
|
|
- ปุ่ม Create แสดงเมื่อมี `announcement:create`
|
|
- ปุ่ม Submit แสดงเมื่อมี `announcement:submit`
|
|
- ปุ่ม Approve แสดงเมื่อมี `announcement:approve`
|
|
- ปุ่ม Publish แสดงเมื่อมี `announcement:publish`
|
|
- ปุ่ม Schedule แสดงเมื่อมี `announcement:schedule`
|
|
- ปุ่ม Archive แสดงเมื่อมี `announcement:archive`
|
|
|
|
แต่ต้องจำไว้ว่า UI visibility ไม่ใช่ security
|
|
|
|
Server/API ต้องตรวจ permission ซ้ำเสมอ
|
|
|
|
---
|
|
|
|
### 13. Audit Log
|
|
|
|
ทุก action ต่อไปนี้ต้องมี audit log:
|
|
|
|
- Create template
|
|
- Update template
|
|
- Clone template
|
|
- Delete template
|
|
- Assign template to user
|
|
- Change user template
|
|
- Add user permission override
|
|
- Deny user permission
|
|
- Remove override
|
|
- Organization switch ที่สำคัญ
|
|
- Permission-based workflow actions เช่น approve, publish, archive
|
|
|
|
Audit payload ควรเก็บ:
|
|
|
|
```text
|
|
actor_user_id
|
|
organization_id
|
|
target_user_id
|
|
target_template_id
|
|
action
|
|
before
|
|
after
|
|
reason
|
|
timestamp
|
|
```
|
|
|
|
---
|
|
|
|
### 14. Backward Compatibility
|
|
|
|
ห้ามลบ logic เดิมทันที
|
|
|
|
ให้ทำ compatibility layer เช่น:
|
|
|
|
```ts
|
|
mapLegacyRoleToPermissionTemplate();
|
|
resolveEffectivePermissionsFromLegacyRole();
|
|
```
|
|
|
|
เป้าหมายคือ:
|
|
|
|
- ระบบเดิมไม่พัง
|
|
- migration ทำเป็น phase ได้
|
|
- ค่อย ๆ ลดการใช้ `businessRole`, `systemRole`, `membership.role`
|
|
- ห้ามเขียน feature ใหม่โดยใช้ role-based authorization
|
|
|
|
---
|
|
|
|
### 15. Testing Checklist
|
|
|
|
ต้องทดสอบอย่างน้อย:
|
|
|
|
#### Employee
|
|
|
|
- เห็นเฉพาะข้อมูลตัวเอง
|
|
- เห็นเฉพาะ published content
|
|
- เข้า draft ผ่าน URL ตรงไม่ได้
|
|
- approve ไม่ได้
|
|
- publish ไม่ได้
|
|
|
|
#### HRD Staff Template
|
|
|
|
- สร้าง draft ได้
|
|
- แก้ draft ได้
|
|
- submit ได้
|
|
- preview ได้
|
|
- approve ไม่ได้
|
|
- publish ไม่ได้
|
|
- schedule ไม่ได้
|
|
- archive ไม่ได้
|
|
|
|
#### HRD Manager Template
|
|
|
|
- approve ได้
|
|
- reject ได้
|
|
- publish ได้
|
|
- schedule ได้
|
|
- archive ได้
|
|
- revision ได้
|
|
- export report ได้
|
|
|
|
#### IT Admin
|
|
|
|
- สร้าง template ได้
|
|
- แก้ template ได้
|
|
- clone template ได้
|
|
- ลบ template ได้ตามเงื่อนไข
|
|
- assign template ให้ user ได้
|
|
- override permission รายบุคคลได้
|
|
- ดู effective permissions ได้
|
|
- audit log ถูกบันทึกครบ
|
|
|
|
#### Multi-Organization
|
|
|
|
- User คนเดียวมีสิทธิ์ต่างกันในแต่ละ organization ได้
|
|
- active organization เปลี่ยนแล้ว permission เปลี่ยนตาม
|
|
- API ไม่ดึงข้อมูลข้าม organization
|
|
- audit log ระบุ organization ถูกต้อง
|
|
|
|
---
|
|
|
|
### 16. Documentation
|
|
|
|
หลังแก้ไขเสร็จ ให้สร้างเอกสารไว้ที่:
|
|
|
|
```text
|
|
docs/permission-template-authorization-implementation.md
|
|
```
|
|
|
|
เอกสารต้องมี:
|
|
|
|
- สรุปสิ่งที่แก้ไข
|
|
- โครงสร้าง Permission-first model
|
|
- Permission catalog
|
|
- Default permission templates
|
|
- Database/schema ที่เพิ่มหรือแก้ไข
|
|
- วิธีคำนวณ effective permissions
|
|
- วิธี assign template ให้ user
|
|
- วิธี override permission รายบุคคล
|
|
- วิธีรองรับหลายองค์กร
|
|
- API/page ที่เปลี่ยนแล้ว
|
|
- compatibility layer ที่ยังเหลือ
|
|
- test checklist
|
|
- known issues
|
|
- next steps
|
|
|
|
---
|
|
|
|
## Acceptance Criteria
|
|
|
|
งานนี้ถือว่าเสร็จเมื่อ:
|
|
|
|
- Permission เป็น source of truth
|
|
- Role ไม่ใช่ตัวกำหนดสิทธิ์หลักอีกต่อไป
|
|
- มี permission catalog กลาง
|
|
- มี Permission Template ที่จัดการผ่าน Admin ได้
|
|
- สร้าง/แก้ไข/Clone/ลบ Template ได้
|
|
- Assign Template ให้ User ได้
|
|
- Override Permission รายบุคคลได้
|
|
- รองรับหลายองค์กร
|
|
- Effective permissions คำนวณถูกต้อง
|
|
- API/server ใช้ `requirePermission()` เป็นหลัก
|
|
- Navigation/page guard ใช้ permission
|
|
- Employee เห็นเฉพาะข้อมูลที่ควรเห็น
|
|
- HRD Staff publish/approve ไม่ได้
|
|
- HRD Manager publish/approve ได้
|
|
- IT Admin จัดการ Template และ Permission ได้
|
|
- ทุกการเปลี่ยนสิทธิ์มี audit log
|
|
- มีเอกสารสรุปใน `docs`
|
|
- ระบบเดิมไม่พังระหว่าง migration
|
|
|
|
---
|
|
|
|
## Important Notes
|
|
|
|
- ห้ามใช้ Role เป็น source of truth
|
|
- ห้าม hard-code role ใน feature ใหม่
|
|
- ห้ามตรวจสิทธิ์เฉพาะ UI
|
|
- Server/API ต้องตรวจ permission เสมอ
|
|
- Permission Template คือชุดสิทธิ์ต้นแบบ ไม่ใช่ตัวตัดสินสิทธิ์
|
|
- User Permission Override ต้องมีผลต่อ effective permissions
|
|
- Multi-Organization ต้องไม่ทำให้ข้อมูลข้ามองค์กรรั่ว
|
|
- ต้อง reuse pattern เดิมของโปรเจกต์ก่อนสร้างของใหม่
|
|
- ต้องทำ migration แบบปลอดภัยและมี compatibility layer
|