Đặc tả Tính năng: RBAC & Quyền hạn

1. Tổng quan & Tầm nhìn

RBAC (Kiểm soát Truy cập dựa trên Vai trò) là công cụ quản trị của nền tảng. Nó đảm bảo rằng mọi hành động do người dùng hoặc dịch vụ thực hiện đều được ủy quyền dựa trên một tập hợp chính sách tập trung, cung cấp khả năng kiểm soát cấp tổ chức đối với các dữ liệu và tính năng nhạy cảm.

2. Các Vai trò & Bên liên quan

Vai trò	Mục tiêu
Quản trị viên Tổ chức	Định nghĩa các vai trò tùy chỉnh và gán quyền hạn cho các thành viên trong nhóm.
Thành viên	Thực hiện các nhiệm vụ được ủy quyền mà không gặp phải rào cản bảo mật.
Quản trị viên Hệ thống	Định nghĩa các vai trò hệ thống toàn cầu và giám sát việc tuân thủ chính sách.

3. Câu chuyện Người dùng (User Stories)

• Với tư cách là quản trị viên, tôi muốn tạo vai trò "Quản lý Tài chính" có thể xem hóa đơn nhưng không thể thay đổi hồ sơ nhân sự.
• Với tư cách là quản trị viên, tôi muốn tạm dừng tất cả các quyền hạn của một người dùng mà không cần xóa tài khoản của họ.

4. Yêu cầu Chức năng (FR)

• REQ-RBAC-001: Hỗ trợ định nghĩa vai trò tùy chỉnh cho mỗi tổ chức.
• REQ-RBAC-002: Danh mục quyền hạn tập trung cho tất cả các ứng dụng satellite.
• REQ-RBAC-003: Kiểm tra quyền hạn thời gian thực qua Casbin.
• REQ-RBAC-004: Vai trò kế thừa (ví dụ: admin kế thừa tất cả quyền hạn của member).

5. Yêu cầu Phi chức năng (NFR)

• Độ trễ: Kiểm tra quyền hạn < 10ms (được cache trong Redis).
• Khả năng kiểm toán: Mọi thay đổi quyền hạn PHẢI được ghi lại trong nhật ký kiểm toán.

6. Logic & Quy tắc Nghiệp vụ

• Chủ thể-Đối tượng-Hành động (SOA): Các chính sách tuân theo mô hình Casbin: p, sub, obj, act.
• Vai trò mặc định: Mỗi tổ chức mới được cấp phát các vai trò Owner, Admin, và Member.
• Phạm vi: Quyền hạn có thể được giới hạn trong một module satellite cụ thể (ví dụ: drive:*).

7. Giao diện Người dùng (UI/UX)

• Trình chỉnh sửa "Vai trò & Quyền hạn" với lưới checkbox dạng ma trận.
• Giao diện gán Người dùng vào Vai trò với quản lý hàng loạt.
• Chỉ báo trực quan cho các quyền hạn được kế thừa so với quyền hạn được cấp trực tiếp.

8. Kiến trúc Thông tin

• Nằm trong phần "Cài đặt Tổ chức" của Shell.
• Được nhóm theo module satellite để rõ ràng.

9. Mô hình Dữ liệu & Lưu trữ

• Các bảng: roles, permissions, role_permissions, user_roles.
• Engine: Casbin với adapter PostgreSQL.

10. Lớp API & Dịch vụ

• GET /api/roles
• POST /api/roles/:id/permissions
• RbacService.CheckPermission (gRPC)

11. Các Mẫu Tích hợp

• Các ứng dụng satellite thực hiện kiểm tra quyền hạn từ xa qua cổng gRPC của Shell.
• Các decorator @authorize() khai báo trong các controller của satellite.

12. Bảo mật & Quyền hạn

• Chỉ Owner hoặc Admin mới có thể sửa đổi các vai trò.
• Việc gán vai trò chéo thuê bao bị nghiêm cấm tuyệt đối.

13. Xử lý Lỗi & Khả năng Phục hồi

• Phản hồi 403 Forbidden thân thiện với mô tả về quyền hạn còn thiếu.
• Dự phòng về "Deny All" (Từ chối tất cả) nếu engine Casbin bị lỗi.

14. Hiệu năng & Khả năng Mở rộng

• Các chính sách thực thi được cache trong Redis để đánh giá nhanh.
• Cache chính sách cục bộ tại các module satellite (dự kiến v1.2).

15. Toàn cầu hóa & Bản địa hóa

• Tên và mô tả quyền hạn được bản địa hóa (EN/VI).

16. Khả năng Tiếp cận (a11y)

• Lưới quyền hạn có thể tiếp cận (điều hướng bàn phím, độ tương phản cao).

17. Khả năng Quan sát & Phân tích

• Theo dõi "Các hành động bị từ chối" để xác định các mối đe dọa bảo mật tiềm ẩn hoặc ma sát UX.

18. Kiểm thử & Chất lượng

• Kiểm thử đơn vị chính sách để đảm bảo Admin luôn có toàn quyền truy cập.
• Kiểm thử phủ định để xác minh sự cô lập dữ liệu.

19. Các Ràng buộc & Giả định

• Giả định các ứng dụng satellite định nghĩa đúng các mã quyền hạn của họ trong danh mục Shell.

20. Các Cải tiến Tương lai

• Quyền hạn dựa trên tài nguyên (ví dụ: "Chỉ truy cập vào Thư mục X").
• Gán vai trò theo thời gian (quyền hạn tạm thời).