PRD: Policy definition, permission catalog & grants
| Module | Quyền hạn (CORE-02) | PRD ID | PRD-PERM-001 |
| Status | Shipped | Owner | Permissions squad |
| Date | 2026-05-28 | Version | v1.0 |
| Packages | @nx/identity · @nx/core · apps/bo · apps/client | URD | PERM · GRANT · EFF |
TL;DR
Cung cấp cho administrator và merchant owner một bề mặt quản lý dùng được cho mô hình authorization của KICKO: duyệt và bảo trì permission catalog dưới dạng màn hình CRUD, rồi hiển thị policy definition thành các section theo từng target - role, user, merchant và organizer - mỗi section có dialog grant/revoke và bảng riêng. Luồng grant/revoke là idempotent và giới hạn trong active merchant domain, nhờ đó authorization cuối cùng có thể được quản lý ngay trong sản phẩm thay vì sửa database trực tiếp.
1. Context & Problem
Mô hình authorization của KICKO - Casbin RBAC theo priority với domain theo từng merchant - đã lưu permission catalog và các policy grant trong package identity, và các service grant/revoke/effective-permission bên dưới cũng đã tồn tại. Thứ còn thiếu là một bề mặt dùng được để điều khiển chúng: administrator không thể duyệt permission catalog, gắn hoặc gỡ permission, hay kiểm tra một policy áp dụng cho những role, user, merchant và organizer nào nếu không động trực tiếp vào database.
Increment này dựng bề mặt quản lý đó trên nền các service identity hiện có. Nó hiển thị permission catalog dưới dạng màn hình CRUD và render policy definition thành một tập section theo target (role, user, merchant, organizer), mỗi section có dialog grant/revoke và bảng riêng. Cùng bề mặt đó được nhân bản vào team module (client) hướng đến merchant để owner có thể quản lý policy trong phạm vi merchant của chính mình, được hỗ trợ bởi một đợt i18n trong @nx/core cung cấp các nhãn en/vi mà những màn hình này render.
2. Goals & Non-Goals
Goals
- Hiển thị permission catalog dưới dạng màn hình create/edit/list - code duy nhất, action, scope, subject, và name/description i18n.
- Hiển thị policy definition với grant/revoke theo từng target: role, user, merchant và organizer target - mỗi cái là một section + bảng + dialog grant.
- Làm cho luồng grant/revoke idempotent và tôn trọng merchant domain theo từng request, điều khiển các service grant/revoke identity hiện có.
- Nhân bản bề mặt policy-definition vào team module (client) để owner quản lý policy trong phạm vi merchant của mình, có lọc danh sách theo target.
- Ship các chuỗi i18n en/vi (
@nx/core) mà các màn hình phụ thuộc vào.
Non-Goals
- Phân cấp resource/action/domain và bộ công cụ declaration - các grant thô
manage/writevà roll-up theo module là một increment riêng (PRD-HIER-001). - Permission dạng wildcard/glob, phân nhóm permission category / gom nhóm UI, role template / bundle (Non-Goals trong URD).
- Permission theo thời gian hoặc theo ca, và ghi log audit permission.
- Bản thân engine authorization - increment này là UI quản lý, không phải Casbin enforcer hay các service identity mà nó tiêu thụ.
3. Success Metrics
| Metric | Mục tiêu / tín hiệu |
|---|---|
| Tự phục vụ quản lý | Permission catalog và grant được quản lý ngay trong sản phẩm; không sửa database trực tiếp để grant/revoke |
| Toàn vẹn catalog | Mỗi permission có code duy nhất toàn cục; permission đang được dùng không thể xóa |
| An toàn khi grant | Grant lại một permission đã được grant là no-op (idempotent), không bao giờ trùng lặp |
| Đúng scope | Mỗi grant/revoke resolve trong active merchant domain được chọn theo từng request |
| Tầm với của owner | Merchant owner có thể quản lý policy trong phạm vi của mình qua team module |
4. Personas & Use Cases
| Persona | Mục tiêu trong tính năng này |
|---|---|
| Admin (bo) | Bảo trì permission catalog và grant/revoke permission trên role, user, merchant và organizer |
| Owner (team module ở client) | Quản lý policy trong phạm vi merchant của mình |
| Operator | Kiểm tra một policy áp dụng cho những target nào mà không cần truy cập database |
Core scenarios: bảo trì permission catalog (create/edit/list) → mở policy definition → chọn một section target (role / user / merchant / organizer) → grant hoặc revoke permission qua dialog của section → thay đổi resolve trong active merchant domain, theo cách idempotent.
5. User Stories
- Là một admin, tôi muốn tạo, sửa và liệt kê permission với code duy nhất, action, scope và subject, để catalog được bảo trì ngay trong sản phẩm.
- Là một admin, tôi muốn grant hoặc revoke permission cho một role qua section role-target, để kiểm soát role được làm gì.
- Là một admin, tôi muốn grant hoặc revoke permission cho một user, merchant hoặc organizer qua section target riêng của chúng, để policy có thể gắn ở đúng cấp.
- Là một admin, tôi muốn việc grant lại một permission đã có được bỏ qua thay vì trùng lặp, để thao tác grant an toàn khi thử lại.
- Là một owner, tôi muốn bề mặt policy-definition tương tự nằm trong team module ở client, để quản lý policy trong phạm vi merchant của mình.
- Là một admin, tôi muốn grant/revoke resolve trong active merchant domain, để thay đổi chỉ áp dụng đúng nơi mong muốn.
6. Functional Requirements
| # | Requirement | URD ref |
|---|---|---|
| FR-1 | Permission catalog CRUD - create/edit/list với code duy nhất, action, scope, subject, và name/description i18n | URD-PERM-001..004 |
| FR-2 | Permission code là duy nhất toàn cục; permission đang được dùng không thể xóa | URD-PERM-002 · URD-PERM-005 |
| FR-3 | Grant/revoke role-target - section + bảng + dialog grant điều khiển các service grant/revoke identity | URD-GRANT-001..002 |
| FR-4 | Grant/revoke user-target - gán/gỡ qua một section user-target | URD-GRANT-004 |
| FR-5 | Grant/revoke merchant-target và organizer-target - mỗi cái là một section + bảng + dialog grant | URD-GRANT-001..002 · URD-EFF-004 |
| FR-6 | Grant/revoke là idempotent - permission đã được grant sẽ bị bỏ qua, không trùng lặp | URD-GRANT-003 |
| FR-7 | Xem một role đang giữ những permission nào và một policy target áp dụng cho những user/role nào | URD-GRANT-006..007 |
| FR-8 | Mỗi grant/revoke resolve trong active merchant domain được chọn theo từng request | URD-EFF-004 |
| FR-9 | Bản clone trong team module (client) - cùng bề mặt target role/user/merchant/organizer giới hạn theo một merchant, lọc được theo target | URD-GRANT-001..007 · URD-EFF-004 |
| FR-10 | Chuỗi i18n en/vi (@nx/core) cho màn hình permission và policy-definition | URD-PERM-003 |
Toàn văn requirement và acceptance criteria nằm trong URD Quyền hạn. PRD này tham chiếu chúng thay vì lặp lại.
7. Non-Functional Requirements
| Area | Requirement |
|---|---|
| Data integrity | Permission code duy nhất toàn cục; permission đang dùng không thể xóa; bản ghi được soft-delete, không bao giờ xóa vật lý |
| Idempotency | Thao tác grant/revoke an toàn khi thử lại - grant lại bị bỏ qua, trả về số lượng skip thay vì lỗi |
| Tenancy & authz | Mỗi grant/revoke resolve trong một active merchant domain theo từng request (header active-merchant); guard chống leo thang đặc quyền do các service bên dưới thực thi |
| Performance / scale | Màn hình list đọc catalog và grant theo target mà không fan-out theo từng dòng; subquery grant phải đọc toàn bộ dòng grant (không bị cắt bởi default-limit) |
| i18n | Mọi nhãn và mô tả hiển thị cho người dùng đều song ngữ ({ en, vi }), do đợt locale @nx/core cung cấp |
8. UX & Flows
Key screens: trong apps/bo, permission catalog (permission/{create,edit,list}) và policy definition (policy-definition/{create,edit,list}) cùng các section target role/user/merchant/organizer của nó, mỗi cái là một section + bảng + dialog grant. Trong apps/client, cùng bề mặt target nằm dưới team module (team/policy-definition), giới hạn theo một merchant và lọc được theo target.
9. Data & Domain
| Entity | Vai trò |
|---|---|
Permission | Một mục catalog - code duy nhất toàn cục, action, scope, subject, name/description i18n |
PolicyDefinition | Bản ghi grant/policy gắn một permission vào một target |
| Role target | Một grant permission cho một role |
| User target | Một grant permission cho một user (và gán role-to-user) |
| Merchant / Organizer target | Một grant giới hạn theo domain merchant hoặc organizer |
Chỉ ở mức khái niệm - schema đầy đủ và mô hình dữ liệu policy nằm trong tài liệu RBAC cho developer.
10. Dependencies & Assumptions
Depends on
- Service policy/grant của identity (
@nx/identity) - các service PolicyDefinition / Permission / grant-revoke mà bề mặt này điều khiển. - Casbin RBAC theo từng merchant (
@nx/core) - model + policy adapter theo từng merchant + enforcer resolve grant trong một domain. - Vai trò cố định & tùy chỉnh (URD-ROLE · URD-CROLE) - grant gắn vào các role đã tồn tại.
- Chuỗi i18n (
@nx/core) - các nhãn en/vi mà màn hình render.
Assumptions
- Các service catalog/grant/revoke và effective-permission của identity đã tồn tại sẵn (có trước increment này).
- Một active merchant domain được chọn theo từng request qua header active-merchant.
- Role, user, merchant và organizer tồn tại dưới dạng grant target.
11. Risks & Open Questions
| Risk / câu hỏi | Mitigation / trạng thái |
|---|---|
| Subquery grant bị cắt bởi default query limit | Đọc toàn bộ dòng grant (không bị giới hạn default-limit) để user có nhiều grant không bị âm thầm bỏ sót |
| Grant trùng lặp khi thử lại | Grant/revoke là idempotent - grant lại bị bỏ qua, không bao giờ trùng lặp |
| Đúng cú pháp truy vấn policy-definition | Được kiểm chứng với các service identity; một vấn đề cú pháp truy vấn được sửa trước khi launch |
| Hai bề mặt (bo + team module ở client) lệch nhau | Dùng chung component/hook/util target; bề mặt team-module là bản clone có giới hạn scope, không phải fork |
| Grant thô theo từng target không mở rộng được cho truy cập thô | Được thay thế bởi phân cấp resource/action/domain (PRD-HIER-001) |
12. Release Plan & Launch Criteria
| Aspect | Plan |
|---|---|
| Phase | P2 - xem feature catalog trong URD (PERM / GRANT / EFF đánh dấu Built) |
| Rollout | Tất cả merchant; bề mặt admin ở bo + bản clone team module ở client; không có feature flag |
| Migration | Không - điều khiển các entity/service identity hiện có; thêm chuỗi i18n @nx/core |
| Launch criteria | CRUD catalog được kiểm chứng; grant/revoke được kiểm chứng idempotent trên role/user/merchant/organizer target trong một merchant domain; bản clone team module được kiểm chứng trong phạm vi merchant |
| Monitoring | Tỷ lệ lỗi grant/revoke, số lượng skip idempotent, độ đúng cú pháp truy vấn policy-definition |
13. FAQ
Increment này có dựng engine authorization không? Không - Casbin enforcer và các service grant/revoke/effective-permission của identity đã tồn tại. Increment này là UI quản lý điều khiển chúng.
"Target sections" là gì? Policy definition được render thành bốn section - role, user, merchant và organizer - mỗi section có dialog grant/revoke và bảng riêng, để một grant có thể gắn ở đúng cấp.
Vì sao grant/revoke là idempotent? Để thao tác an toàn khi thử lại - grant lại một permission đã được grant sẽ bị bỏ qua (và được đếm), không bao giờ trùng lặp.
Owner có tự quản lý policy được không? Có - cùng bề mặt policy-definition được nhân bản vào team module ở client, giới hạn theo merchant của owner và lọc được theo target.
Một grant có áp dụng ở mọi nơi không? Không - mỗi grant/revoke resolve trong active merchant domain được chọn theo từng request qua header active-merchant.
Còn các grant thô manage/write thì sao? Ngoài phạm vi ở đây - roll-up theo module và phân cấp resource/action/domain thuộc về PRD-HIER-001.
References
- URD: Quyền hạn - Permission Catalog · Grant / Revoke · Effective Permissions & Scope
- Related PRD: Resource, Action & Domain Hierarchy
- Module: Quyền hạn - overview + traceability
- Developer: @nx/identity · RBAC · Casbin Authorization