PRD: Vai trò cố định & tùy chỉnh
| Module | Quyền hạn (CORE-02) | PRD ID | PRD-ROLE-001 |
| Status | Shipped | Owner | Permissions squad |
| Date | 2026-05-27 | Version | v1.0 |
| Packages | @nx/identity · @nx/core · apps/client · apps/bo | URD | ROLE · CROLE |
TL;DR
Cung cấp cho mọi tenant của KICKO một lớp role hoạt động đầy đủ trên nền Casbin RBAC engine: tám fixed system role được seed sẵn với phân cấp priority dạng số, còn administrator và owner có thể tự định nghĩa custom role phân phạm vi theo organization hoặc merchant. Kết quả: các mức truy cập có sẵn ngay từ đầu một cách dự đoán được, các role cao nhất bỏ qua việc lọc dữ liệu trong khi Owner/Cashier/Employee vẫn bị giới hạn phạm vi, và không ai có thể tạo hoặc quản lý một role ngang bằng hay cao hơn priority của chính mình.
1. Context & Problem
KICKO kiểm soát truy cập tính năng và dữ liệu thông qua mô hình Casbin RBAC dựa trên priority với domain theo từng merchant, nhưng bản thân engine không quy định role nào tồn tại hay ai được tạo chúng. Nếu không có lớp role, mỗi tenant sẽ khởi đầu trống rỗng - không có mức truy cập mặc định, không có cơ chế chặn một admin tạo ra role mạnh hơn chính mình, và không có cách giới hạn một role vào một organization hay merchant cụ thể.
Một merchant cần các mặc định hợp lý ngay khi vừa được tạo, một tập fixed system role không thể bị can thiệp, và sự linh hoạt để administrator và owner định nghĩa các role hẹp hơn cho nhân sự của mình. Các role cũng phải được nối với mô hình domain theo merchant để domain của một role đi kèm trong token đăng nhập, và danh sách role được lọc theo merchantId/organizer. Đây là nền tảng để phần còn lại của module Quyền hạn (grant, effective permission, phân cấp) xây dựng tiếp.
2. Goals & Non-Goals
Goals
- Seed tám fixed system role lúc khởi động với phân cấp priority dạng số - Super Admin / Admin / Operator bỏ qua việc lọc dữ liệu, trong khi Owner / Cashier / Employee bị giới hạn theo organization hoặc các merchant họ thuộc về; seed một role
GUESTmặc định cho đăng ký. - Bảo vệ SYSTEM role: chặn sửa, xóa và đổi priority; loại chúng khỏi việc đếm role-merchant mapping.
- Cho administrator và owner tạo custom role với tên i18n, priority thấp hơn hẳn priority của chính họ, và phạm vi organization/merchant tùy chọn; tự sinh role identifier từ priority + tên.
- Hỗ trợ cập nhật role (tên, mô tả, priority) và xóa an toàn (bị chặn khi vẫn còn người dùng được gán; xóa cascade các grant và scope link).
- Phân phạm vi role CRUD theo organizer/merchant; biến
merchantIdthành query param tùy chọn; HQ owner bỏ qua bộ lọc merchant/identifier. - Trả về domain của role trong JWT token, để việc phân quyền được giải quyết trong domain merchant đang hoạt động.
- Cung cấp giao diện quản lý role: danh sách role có bộ lọc, form tạo/sửa với ô nhập priority và đồng bộ merchant, và một cây permission có thể thu gọn.
Non-Goals
- Wildcard / glob permission và permission category - xem Non-Goals trong URD.
- Phân cấp resource/action/domain và các grant thô
manage/write- thuộc increment Phân cấp Resource, Action & Domain. - Permission catalog và grant/revoke - thuộc Cấp quyền theo Policy-Definition.
- Permission theo thời gian hoặc ca làm, ghi log audit permission, chuyển đổi role đang hoạt động theo từng merchant.
3. Success Metrics
| Metric | Target / signal |
|---|---|
| Sẵn sàng từ đầu | 100% merchant mới có sẵn tám fixed role ngay lần đăng nhập đầu tiên |
| Toàn vẹn system role | Không có thao tác sửa/xóa/đổi-priority nào thành công trên SYSTEM role; system role không bao giờ bị đếm trong role-merchant mapping |
| Chặn leo thang đặc quyền | Không có custom role nào được tạo ngang bằng hay cao hơn priority của người tạo |
| Đúng phạm vi | Danh sách/đếm role luôn được lọc về phạm vi của người dùng yêu cầu; không bao giờ trả về ID lạ |
| Mức độ sử dụng | Số custom role được tạo trên mỗi organizer tăng dần khi merchant tinh chỉnh truy cập nhân sự |
4. Personas & Use Cases
| Persona | Mục tiêu trong tính năng |
|---|---|
| Super Admin / Admin / Operator | Quản lý role trên toàn nền tảng với tầm với dữ liệu đầy đủ |
| Owner | Tạo và quản lý role giới hạn trong organization và merchant của riêng mình |
| Administrator (BO) | Bảo trì role và cây permission của chúng từ back office |
| Employee / Cashier | Nhận một role cố định, có phạm vi, giới hạn họ vào các merchant được gán |
Core scenarios: một merchant được tạo với tám fixed role đã seed sẵn → một admin hay owner tạo custom role với priority thấp hơn priority của chính mình và phạm vi organization/merchant tùy chọn → họ sửa tên, priority và cây permission của role → và xóa an toàn khi không còn người dùng được gán, với system role luôn được bảo vệ.
5. User Stories
- Là owner, tôi muốn có sẵn một tập role ngay khi merchant của tôi tồn tại, để tôi gán nhân sự mà không phải cấu hình các mức truy cập từ đầu.
- Là administrator, tôi muốn tạo một custom role với priority thấp hơn hẳn của mình, để tôi ủy quyền mà không cấp nhiều quyền hơn mình đang có.
- Là administrator, tôi muốn phân phạm vi một custom role vào một organization hay merchant, để nó chỉ áp dụng đúng nơi cần.
- Là administrator, tôi muốn cập nhật tên, mô tả và priority của role, để các định nghĩa role luôn chính xác theo thời gian.
- Là administrator, tôi muốn việc xóa bị chặn khi vẫn còn người dùng được gán, để tôi không bao giờ bỏ rơi một người dùng không có role.
- Là owner, tôi muốn các system role là bất khả xâm phạm, để mô hình truy cập nền tảng không thể bị phá vỡ.
- Là administrator, tôi muốn một màn hình quản lý role với cây permission thu gọn được, để tôi thấy và định hình một role có thể làm gì chỉ trong một cái nhìn.
6. Functional Requirements
| # | Requirement | URD ref |
|---|---|---|
| FR-1 | Seed tám fixed system role lúc khởi động (Super Admin, Admin, Operator, Owner, Cashier, Employee, Customer, Guest); seed GUEST mặc định cho đăng ký | URD-ROLE-001 |
| FR-2 | Mỗi role mang một priority dạng số xác định vị trí của nó trong phân cấp | URD-ROLE-003 |
| FR-3 | Super Admin / Admin / Operator bỏ qua mọi việc lọc dữ liệu và nắm mọi permission | URD-ROLE-004 |
| FR-4 | Owner chỉ thấy organization của mình và các merchant của nó; Employee/Cashier chỉ thấy các merchant được gán | URD-ROLE-005..006 |
| FR-5 | Mọi thao tác list và count được lọc theo phạm vi của người dùng yêu cầu và không thể bị ghi đè | URD-ROLE-007..008 |
| FR-6 | Một HQ owner với tới mọi merchant cùng cấp của organizer; HQ bỏ qua bộ lọc merchant/identifier | URD-ROLE-009 |
| FR-7 | SYSTEM role không thể bị sửa, xóa hay đổi priority; bị loại khỏi việc đếm role-merchant mapping | URD-ROLE-002 |
| FR-8 | Người dùng được phép tạo custom role với tên i18n, priority và phạm vi organization/merchant tùy chọn | URD-CROLE-001 · URD-CROLE-004 |
| FR-9 | Role identifier được tự sinh từ priority + tên và duy nhất trong phạm vi của nó | URD-CROLE-002 |
| FR-10 | Priority của role mới phải thấp hơn hẳn priority cao nhất của người tạo | URD-CROLE-003 |
| FR-11 | Custom role có thể được cập nhật (tên, mô tả, priority) | URD-CROLE-005 |
| FR-12 | Một role không thể bị xóa khi vẫn còn người dùng được gán; xóa sẽ cascade các grant và scope link | URD-CROLE-006..007 |
| FR-13 | Một Owner chỉ có thể tạo role giới hạn trong organization hoặc các merchant của riêng mình | URD-CROLE-008 |
| FR-14 | Domain của một role được trả về trong JWT token đăng nhập | URD-ROLE-004 |
Toàn văn requirement và tiêu chí nghiệm thu 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 |
|---|---|
| Toàn vẹn dữ liệu | Mọi bản ghi đều soft-delete, không bao giờ xóa vật lý; xóa một role sẽ cascade tới các grant và scope link của nó như một thao tác duy nhất |
| Tenancy & authz | Mọi role CRUD phân phạm vi theo merchant (x-merchant-id) và organizer; được gác bởi permission; chặn leo thang đặc quyền trên mọi thao tác tạo/quản lý |
| Tính phi trạng thái | Token phiên là phi trạng thái - thay đổi role có hiệu lực ở lần đăng nhập kế tiếp; domain của role được mang trong JWT |
| Hiệu năng / quy mô | Việc lọc danh sách/đếm role theo phạm vi tránh nạp các role ngoài tầm với của người dùng |
| i18n | Tên và mô tả role song ngữ ({ en, vi }) |
| Tính nhất quán | Việc tự sinh identifier và tạo scope link diễn ra trong một thao tác; lỗi một phần không để lại role mồ côi |
8. UX & Flows
Các màn hình chính: trong apps/client, màn hình quản lý role với cây permission thu gọn được, form tạo/sửa có ô nhập priority, mô tả đa ngôn ngữ và đồng bộ merchant; trong apps/bo, các màn hình role với bộ lọc và form cập nhật cho admin.
9. Data & Domain
| Entity | Vai trò |
|---|---|
Role | Mức truy cập có tên - tên i18n, priority dạng số, type SYSTEM hoặc CUSTOM, identifier tự sinh |
| Scope link role-merchant / role-organizer | Membership ràng buộc một custom role vào một organization hoặc merchant cụ thể |
| Membership user-role | Nối một user với một role; việc xóa bị chặn khi vẫn còn membership |
| Permission grant | Bản ghi policy bị xóa cascade khi một role bị xóa |
| Token đăng nhập (JWT) | Mang các role của user và domain merchant đang hoạt động |
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 identity.
10. Dependencies & Assumptions
Phụ thuộc vào
- User Management (CORE-01) - user là chủ thể nhận role.
- Commerce (organization & merchant) - organization và merchant là các phạm vi mà role gắn vào.
- Casbin RBAC engine (
@nx/core) - mô hình dựa trên priority với domain theo merchant mà lớp role đặt lên trên.
Giả định
- Mỗi merchant được tạo với quyền truy cập tới tám fixed role đã seed.
- Merchant đang hoạt động được chọn theo từng request qua header active-merchant; domain của role được giải quyết trong đó.
- Organizer/merchant mà custom role được phân phạm vi tới đã tồn tại.
11. Risks & Open Questions
| Risk / question | Mitigation / status |
|---|---|
| Một admin tạo ra role mạnh hơn chính mình | Chặn leo thang đặc quyền - priority mới phải thấp hơn hẳn của người tạo |
| System role bị can thiệp hoặc đếm sai | SYSTEM role bất biến và bị loại khỏi việc đếm role-merchant mapping |
| Xóa role bỏ rơi người dùng được gán | Việc xóa bị chặn khi vẫn còn người dùng; phải bỏ gán trước |
| Token phi trạng thái nghĩa là permission cũ | Chấp nhận - thay đổi role/permission có hiệu lực ở lần đăng nhập kế tiếp |
| Tầm với của HQ owner qua các merchant cùng cấp | HQ owner bỏ qua bộ lọc merchant/identifier; hành vi được ghi nhận là mở rộng |
12. Release Plan & Launch Criteria
| Aspect | Plan |
|---|---|
| Phase | ROLE là P1, CROLE là P2 - xem feature catalog của URD |
| Rollout | Mọi merchant; không feature flag |
| Migration | Tám fixed role + GUEST mặc định được seed lúc khởi động; không migration dữ liệu |
| Launch criteria | Tám role được seed và bảo vệ; tạo/cập nhật/xóa custom được kiểm chứng với cơ chế chặn priority và cascade; danh sách/đếm role có phạm vi đúng; domain role có mặt trong JWT |
| Monitoring | Số lượng tạo custom role, số lần bị chặn leo thang đặc quyền, tính nhất quán của bộ lọc role-scope |
13. FAQ
Có thể sửa hoặc xóa một system role không? Không - tám SYSTEM role là bất biến: sửa, xóa và đổi priority đều bị từ chối, và chúng bị loại khỏi việc đếm role-merchant mapping.
Vì sao tôi không thể tạo một role có priority bằng của mình? Cơ chế chặn leo thang đặc quyền yêu cầu priority của role mới phải thấp hơn hẳn priority cao nhất của bạn, nên bạn không bao giờ có thể ủy quyền nhiều hơn mình đang nắm.
Một custom role áp dụng cho phạm vi nào? Nó có thể được phân phạm vi vào một organization hay merchant cụ thể; một Owner chỉ có thể phân phạm vi vào organization hoặc các merchant của riêng mình.
Vì sao tôi không thể xóa một role? Việc xóa bị chặn khi vẫn còn người dùng được gán - hãy bỏ gán họ trước. Khi đã trống, việc xóa sẽ cascade các grant và scope link của role.
Khi nào thay đổi role có hiệu lực? Ở lần đăng nhập kế tiếp - token phiên là phi trạng thái và mang các role cùng domain của user.
References
- URD: Quyền hạn - Vai trò cố định · Vai trò tùy chỉnh
- PRD liên quan: Cấp quyền theo Policy-Definition · Per-merchant Casbin Authorization · Phân cấp Resource, Action & Domain
- Module: Quyền hạn - tổng quan + traceability
- Developer: @nx/identity · RBAC & Policy Definitions