Phân quyền (RBAC) Phase 1 Built

Tài liệu nghiệp vụ (BA)

UC — Use Case · SRS — Đặc tả yêu cầu · UI — Đặc tả giao diện

Sau khi xác thực danh tính, module này quyết định người dùng được phép làm gì - truy cập module nào, thực hiện hành động nào. Áp dụng mô hình RBAC với 4 vai trò mặc định (Owner · Manager · Cashier · Viewer), một ma trận quyền per module, và phân quyền theo chi nhánh để bảo mật dữ liệu đa cơ sở của chuỗi sân.

1. Định danh

Thuộc tính	Giá trị
Module ID	F-03
Hạng	Core
Trạng thái	Built (P1) · In-progress (vai trò tuỳ chỉnh)
Giai đoạn	P1 (4 vai trò, ma trận quyền, branch scope) · P2 (custom role)
Ưu tiên	HIGH
Người dùng chính	Chủ sân · Quản lý ca · Thu ngân · Xem báo cáo

2. Mục đích & Phạm vi

Bao gồm	Loại trừ
4 vai trò mặc định: Owner · Manager · Cashier · Viewer	Xác thực danh tính & cấp JWT (do Người dùng & Xác thực sở hữu)
Ma trận quyền per module (✅ toàn quyền · 👁 chỉ xem · ➕ tạo · ✏️ sửa · ❌ chặn)	Giao diện tạo/sửa nhân viên (nằm trong quản lý nhân sự)
Phân quyền theo chi nhánh (branch scope trong JWT)	Ghi log thay đổi quyền (do Audit Log lưu)
Gán / thay đổi vai trò; áp dụng ngay qua WebSocket	Định nghĩa nội dung từng module nghiệp vụ
Middleware kiểm tra quyền 2 lớp (UI + API 403)
Vai trò tuỳ chỉnh (P2) với trần quyền ≤ Manager

3. Năng lực

Năng lực	Người dùng làm được gì
4 vai trò mặc định	Owner toàn quyền · Manager vận hành ca · Cashier POS + lịch (đọc) · Viewer chỉ đọc báo cáo/hoá đơn
Ma trận quyền	Owner xem bảng tổng hợp quyền của tất cả vai trò × module
Gán vai trò	Owner chọn vai trò khi tạo nhân viên; thay đổi role bất kỳ lúc nào
Áp dụng tức thì	Thay đổi role có hiệu lực ngay qua WebSocket - nhân viên đang online bị refresh session
Branch scope	JWT mang branch_id; Manager chỉ thấy dữ liệu chi nhánh được gán, Owner thấy tất cả
Báo cáo scoped	Module báo cáo chỉ hiển thị dữ liệu của chi nhánh trong token
Defense in depth	Chặn ở cả 2 lớp: UI ẩn menu + API trả 403; không chỉ dựa vào UI
Vai trò tuỳ chỉnh (P2)	Owner định nghĩa vai trò mới với bộ quyền riêng, trần quyền không vượt Manager

4. Phụ thuộc Module

Phụ thuộc vào	Vì sao
Người dùng & Xác thực	JWT chứa role + branch_id được RBAC dùng để kiểm tra; giao diện gán role nằm trong quản lý nhân sự
Nền tảng	Ghi mọi thay đổi role / thu hồi quyền vào audit log; thông báo gửi theo branch scope
Mọi module nghiệp vụ	Mọi API nghiệp vụ gọi middleware RBAC để kiểm tra quyền trước khi xử lý
Redis	Cache permission matrix tránh tra DB mỗi request; lưu user blacklist

5. Backend Packages

Chi tiết triển khai nằm trong tài liệu lập trình viên - mục này chỉ ánh xạ module tới các service vận hành nó.

Package	Vai trò	Tài liệu lập trình viên
@nx/rbac	Định nghĩa vai trò, ma trận quyền, branch scope, middleware kiểm tra 403, áp dụng role qua WebSocket	rbac

6. Luồng người dùng chính

Kiểm tra quyền truy cập

Gán & thu hồi vai trò

7. Vai trò & Phân quyền

Vai trò	Được phép	Không được phép
Owner (Chủ sân)	Toàn quyền mọi module + mọi chi nhánh; xem ma trận quyền; gán/đổi vai trò	Xoá hoặc downgrade Owner duy nhất; tự sửa role của chính mình
Manager (Quản lý ca)	POS, lịch sân, kho, sự kiện, khách hàng, báo cáo trong chi nhánh được gán	Cài đặt hệ thống, phân quyền RBAC, onboarding
Cashier (Thu ngân)	POS (bán hàng) + lịch sân (chỉ đọc) + tạo nhanh khách hàng	Báo cáo, kho, sửa/xoá hồ sơ khách, mọi module quản trị
Viewer (Xem báo cáo)	Chỉ đọc báo cáo + hoá đơn trong chi nhánh được gán	Tạo/sửa booking, đơn hàng hay bất kỳ dữ liệu vận hành

8. Trạng thái & Lộ trình

Giai đoạn	Năng lực
P1	4 vai trò mặc định, ma trận quyền per module, branch scope trong JWT, gán/đổi role, áp dụng tức thì qua WebSocket, middleware 403
P2	Vai trò tuỳ chỉnh, override quyền per nhân viên, gán Manager nhiều chi nhánh, audit trail phân quyền theo timeline
P3	Uỷ quyền tạm thời (Permission Delegation), kiểm soát theo thuộc tính dữ liệu (ABAC - ví dụ chỉ xem booking của ca mình)

9. Trang liên quan

• Người dùng & Xác thực
• Nền tảng (Thông báo · Cài đặt · Audit)
• Tài liệu lập trình viên: RBAC Service