URD: Quyền hạn

Module	CORE-02	Phiên bản	v0.4
Trạng thái	Built	Ngày	2026-05-29

1. Mục đích

Định nghĩa cách kiểm soát truy cập tới tính năng và dữ liệu. Quyền hạn cho phép quản trị viên gán vai trò cho người dùng, cấp quyền cho các vai trò đó, giới hạn vai trò theo một tổ chức hoặc merchant cụ thể, và để mọi truy vấn được tự động lọc về những gì người dùng yêu cầu được phép thấy — thực thi qua mô hình RBAC dựa trên ưu tiên của Casbin với domain theo từng merchant.

2. Phạm vi

Bao gồm	Loại trừ
Tám vai trò hệ thống cố định + phân cấp ưu tiên	Quyền wildcard
Bỏ qua với vai trò hệ thống (Super Admin / Admin / Operator)	Phân loại quyền / nhóm giao diện
Lọc dữ liệu theo vai trò tự động	Quyền theo thời gian hoặc ca làm
Tạo vai trò tùy chỉnh với ưu tiên và phạm vi	Ghi log kiểm toán quyền
Catalog quyền (tạo / cập nhật / xóa)	Mẫu vai trò / gói
Cấp / thu hồi quyền cho vai trò	Chuyển vai trò hoạt động theo merchant
Cấp / thu hồi vai trò cho người dùng	Đặc tả API kỹ thuật (xem tài liệu developer)
Truy vấn quyền hiệu lực (trực tiếp + kế thừa)
Phân phạm vi theo tổ chức & theo merchant
Bảo vệ chống nâng quyền

3. Định nghĩa

Thuật ngữ	Định nghĩa
Role	Một mức truy cập có tên với ưu tiên dạng số. SYSTEM (cố định) hoặc CUSTOM (do người dùng tạo).
Permission	Một hành động có tên trên một tài nguyên, định danh bằng một code duy nhất toàn cục.
Grant (policy)	Một bản ghi cấp một quyền cho một vai trò hoặc trực tiếp cho một người dùng.
Membership (group)	Một bản ghi liên kết người dùng với vai trò, người dùng với org/merchant, hoặc vai trò với org/merchant.
Effective permissions	Hợp của mọi quyền một người dùng nắm: cấp trực tiếp + quyền kế thừa qua vai trò.
Scoped role	Một vai trò tùy chỉnh gắn với một tổ chức hoặc merchant cụ thể, giới hạn nơi nó áp dụng.
Domain	Merchant mà một cấp quyền áp dụng trong đó, chọn theo từng yêu cầu bằng header active-merchant.
System-role bypass	Super Admin, Admin và Operator bỏ qua mọi lọc dữ liệu và nắm mọi quyền.
HQ-owner expansion	Một Owner tại merchant trụ sở tự động vươn tới mọi merchant anh em của tổ chức đó.
Privilege escalation	Quản lý một vai trò ở mức hoặc cao hơn ưu tiên của chính người thao tác — luôn bị chặn.

4. Mô hình Khái niệm

Chỉ mang tính khái niệm — mô hình dữ liệu policy đầy đủ nằm trong tài liệu RBAC developer.

5. Yêu cầu Chức năng

Mỗi vùng chức năng một bảng. Mã <AREA> khớp với ID test-case. Mức ưu tiên = MoSCoW (Must / Should / Could / Won't).

5.1 Vai trò Cố định (ROLE)

ID	P	Yêu cầu
URD-ROLE-001	M	Cung cấp tám vai trò cố định seed khi khởi động: Super Admin, Admin, Operator, Owner, Cashier, Employee, Customer, Guest
URD-ROLE-002	M	Vai trò cố định (SYSTEM) không thể sửa hoặc xóa
URD-ROLE-003	M	Mỗi vai trò có một ưu tiên dạng số xác định vị trí của nó trong phân cấp
URD-ROLE-004	M	Super Admin, Admin và Operator bỏ qua mọi lọc dữ liệu và nắm mọi quyền
URD-ROLE-005	M	Owner chỉ thấy tổ chức của mình và các merchant của nó
URD-ROLE-006	M	Employee (và Cashier) chỉ thấy merchant mà họ được gán
URD-ROLE-007	M	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
URD-ROLE-008	M	Lọc tự động không thể bị ghi đè bởi bộ lọc do người dùng cung cấp hoặc truy cập trực tiếp theo ID
URD-ROLE-009	S	Một Owner tại merchant trụ sở vươn tới mọi merchant anh em của tổ chức đó

5.2 Vai trò Tùy chỉnh (CROLE)

ID	P	Yêu cầu
URD-CROLE-001	M	Người dùng được ủy quyền có thể tạo vai trò tùy chỉnh với tên i18n, ưu tiên và phạm vi tùy chọn
URD-CROLE-002	M	Định danh vai trò được tự sinh từ ưu tiên + tên và duy nhất trong phạm vi của nó
URD-CROLE-003	M	Ưu tiên của một vai trò mới phải thấp hơn nghiêm ngặt so với ưu tiên cao nhất của người tạo
URD-CROLE-004	M	Vai trò tùy chỉnh có thể giới hạn theo một tổ chức hoặc merchant cụ thể
URD-CROLE-005	M	Vai trò tùy chỉnh có thể được cập nhật (tên, mô tả, ưu tiên)
URD-CROLE-006	M	Một vai trò không thể bị xóa khi vẫn còn người dùng được gán vào nó
URD-CROLE-007	M	Xóa một vai trò cascade gỡ các cấp quyền và liên kết phạm vi của nó
URD-CROLE-008	S	Một Owner chỉ có thể tạo vai trò giới hạn theo tổ chức hoặc merchant của riêng mình

5.3 Catalog Quyền (PERM)

ID	P	Yêu cầu
URD-PERM-001	M	Admin có thể tạo quyền với code duy nhất, action, scope và subject
URD-PERM-002	M	Code quyền phải duy nhất toàn cục
URD-PERM-003	M	Tên và mô tả quyền hỗ trợ i18n
URD-PERM-004	M	Admin có thể cập nhật và xóa quyền
URD-PERM-005	M	Một quyền có cấp quyền đang hoạt động không thể bị xóa

5.4 Cấp / Thu hồi (GRANT)

ID	P	Yêu cầu
URD-GRANT-001	M	Admin có thể cấp một hoặc nhiều quyền cho một vai trò
URD-GRANT-002	M	Admin có thể thu hồi một hoặc nhiều quyền khỏi một vai trò
URD-GRANT-003	M	Cấp một quyền đã cấp là idempotent (bỏ qua, không nhân đôi)
URD-GRANT-004	M	Admin có thể cấp và thu hồi vai trò cho/khỏi người dùng
URD-GRANT-005	M	Bảo vệ chống nâng quyền được thực thi trên mọi thao tác cấp/thu hồi
URD-GRANT-006	M	Admin có thể xem mọi quyền được cấp cho một vai trò
URD-GRANT-007	M	Admin có thể xem mọi người dùng được gán cho một vai trò và mọi vai trò được gán cho một người dùng

5.5 Quyền Hiệu lực & Phạm vi (EFF)

ID	P	Yêu cầu
URD-EFF-001	M	Tính quyền hiệu lực là hợp của cấp trực tiếp + cấp kế thừa qua vai trò (đã khử trùng)
URD-EFF-002	S	Truy vấn hỗ trợ bộ lọc chế độ: direct, inherit, hoặc cả hai
URD-EFF-003	M	Truy xuất mọi tổ chức và mọi merchant một người dùng thuộc về
URD-EFF-004	M	Một cấp quyền chỉ phân giải trong domain merchant hoạt động được chọn theo từng yêu cầu

6. Tiêu chí Chấp nhận

AC-ROLE-01: Lọc dữ liệu theo vai trò

Cho	Khi	Thì
Người dùng với vai trò khác nhau	Họ gọi cùng một endpoint	Super Admin/Admin/Operator thấy tất cả; Owner thấy org của mình; Employee/Cashier thấy merchant được gán
Bất kỳ truy vấn list/count	Chạy bởi một người dùng có phạm vi	Lọc là tự động và không thể ghi đè
Một người dùng có phạm vi cung cấp bộ lọc rộng hơn hoặc ID lạ	Yêu cầu được thực hiện	Bộ lọc bị bỏ qua / từ chối truy cập

AC-ROLE-02: Bảo vệ vai trò cố định

Cho	Khi	Thì
Bất kỳ trong tám vai trò hệ thống	Người dùng cố sửa hoặc xóa nó	Thao tác bị từ chối
Ưu tiên của một vai trò cố định	Người dùng cố thay đổi nó	Bị từ chối — ưu tiên bất biến

AC-CROLE-01: Tạo vai trò tùy chỉnh

Cho	Khi	Thì
Admin hoặc Owner	Tạo một vai trò với ưu tiên + tên	Vai trò được tạo với type CUSTOM, định danh tự sinh
Ưu tiên ≥ ưu tiên của người tạo	Thử tạo	Bị từ chối (nâng quyền)
Có cung cấp phạm vi org/merchant	Vai trò được tạo	Liên kết phạm vi được tạo
Cùng ưu tiên + tên trong cùng phạm vi	Thử tạo	Bị từ chối (trùng định danh)

AC-GRANT-01: Cấp quyền

Cho	Khi	Thì
ID vai trò + quyền	Admin cấp	Bản ghi cấp được tạo, trả về số lượng
Quyền đã được cấp	Admin cấp lại	Bỏ qua (idempotent), trả về số bỏ qua
Ưu tiên người thao tác ≤ ưu tiên vai trò	Admin cấp	Bị từ chối (nâng quyền)

AC-EFF-01: Quyền hiệu lực

Cho	Khi	Thì
Người dùng có vai trò + cấp trực tiếp	Truy vấn hiệu lực	Hợp của trực tiếp + kế thừa, đã khử trùng
Mode = direct	Truy vấn	Chỉ trả cấp trực tiếp
Mode = inherit	Truy vấn	Chỉ trả cấp kế thừa qua vai trò

AC-CROLE-02: Xóa vai trò

Cho	Khi	Thì
Vai trò tùy chỉnh không có người dùng	Admin xóa	Vai trò + cấp quyền + liên kết phạm vi được soft-delete
Vai trò tùy chỉnh có người dùng được gán	Admin xóa	Bị chặn — phải gỡ gán người dùng trước
Vai trò hệ thống	Admin xóa	Bị từ chối — vai trò cố định bất biến

7. Ràng buộc & Mục tiêu Loại trừ

Ràng buộc

ID	Ràng buộc
C-01	Tám vai trò cố định được seed khi khởi động và bất biến
C-02	Không ai có thể tạo hoặc quản lý vai trò ở mức hoặc cao hơn ưu tiên của chính mình
C-03	Code quyền duy nhất toàn cục
C-04	Thao tác cấp quyền là idempotent
C-05	Mọi bản ghi được soft-delete, không bao giờ xóa vật lý
C-06	Token phiên là phi trạng thái — thay đổi vai trò/quyền có hiệu lực ở lần đăng nhập kế tiếp
C-07	Mọi thao tác yêu cầu xác thực
C-08	Một cấp quyền phân giải trong một domain merchant hoạt động cho mỗi yêu cầu

Mục tiêu Loại trừ

• Quyền wildcard (vd sales.*)
• Phân loại quyền và nhóm giao diện
• Quyền theo thời gian hoặc ca làm
• Nhật ký kiểm toán quyền
• Mẫu vai trò / gói cấu hình sẵn
• Chuyển vai trò hoạt động theo merchant

8. Lịch sử Phiên bản

Ngày	Tác giả	Mô tả	Ver
2026-02-26	P. Do - Product Owner	User story ban đầu	v0.1
2026-04-16	Product	Tái cấu trúc sang định dạng URD	v0.3
2026-05-29	Product	Chuyển sang quy ước module-docs; hòa hợp với RBAC Casbin theo merchant (8 vai trò, ưu tiên, domain); đặt lại khóa vùng (ROLE/CROLE/PERM/GRANT/EFF)	v0.4