Backoffice · Tạo role và phân quyền user qua role

Mô hình đang triển khai: user → bo_account_role → bo_role_permission. Quyền hiệu lực là hợp không trùng các permission của tất cả role user đang giữ. Nguồn: CachedPermissionEvaluator.java:73–94.
Trong màn hình/API đã kiểm tra, phân quyền một user nghĩa là PUT /v1/admin/accounts/{id}/roles với roleIds. Chưa có API hay UI gán permission trực tiếp riêng cho user. Nguồn: BackofficeAdminController.java:78–88; frontend src/api/backoffice.ts:38–40; AccountRoleModal.tsx:57–64.
Ví dụ muốn cấp thêm một quyền cho riêng user A: dùng một role chứa quyền đó và gán role ấy cho A. Sửa quyền của role dùng chung tác động tới mọi user đang giữ role. Ví dụ mô tả mô hình, không tạo role hay thay quyền thật trong tác vụ này.

RoleCreatePage tải GET /v1/admin/permissions, nhập code/name/rankLevel/description và chọn quyền. Khi lưu: POST /v1/admin/roles trước, rồi chỉ khi có quyền đã chọn mới PUT /v1/admin/roles/{id}/permissions. Nguồn frontend @3a95fda: RoleCreatePage.tsx:33–43,76–98.
Role mới trả permissions=[]; createRole không nhận bộ permission. Backend kiểm tra code trùng và rank, ghi bo_role và audit CREATE_ROLE. Nếu request gán quyền tiếp theo thất bại, role đã tạo ở request trước vẫn tồn tại. Nguồn: BackofficeRoleServiceImpl.java:65–96; frontend RoleCreatePage.tsx:79–94.
Chỉnh quyền của role có sẵn dùng cùng PUT permissions. Backend distinct danh sách, xóa quyền cũ rồi lưu toàn bộ tập mới; [] gỡ hết quyền role. Nguồn: BackofficeRoleServiceImpl.java:160–175; frontend RoleDetailPage.tsx:78–90.

GET catalog cần backoffice:LIST:PERMISSION_LIST; POST role cần backoffice:CREATE:ROLE; cả thay permission của role và gán role user đều cần backoffice:UPDATE:PERMISSIONS. Nguồn: BackofficePermissionCatalogController.java:19–25; BackofficeRoleController.java:54–103; BackofficeAdminController.java:78–88.
Gateway xác minh JWT Backoffice, đọc quyền từ Redis rồi gắn X-User-Permissions; PermissionAspect kiểm tra code yêu cầu trước controller. Nguồn: JwtAuthenticationFilter.java:92–124,233–253; PermissionAspect.java:23–40.
Actor thường chỉ tạo/sửa/gán role có rank thấp hơn max rank của mình. Khi thay bộ quyền role, còn phải giữ điều kiện mọi permission được gán đều thuộc quyền actor đang có. Backend miễn hai hạn chế này cho actor rank ≥999; vẫn áp dụng quyền endpoint và kiểm tra catalog. Nguồn: BackofficeRoleServiceImpl.java:70–77,136–157; BackofficeAccountServiceImpl.java:226–242.
Lối cache hit của actor được vẽ trong bước 2; khi miss, CachedPermissionEvaluator truy CSDL lấy hợp quyền từ role rồi ghi cache. Super admin bỏ qua kiểm tra tập con quyền. Nguồn: CachedPermissionEvaluator.java:49–94.

AccountRoleModal tải danh sách role, lọc role rank thấp hơn actor (trừ super admin), tải chi tiết role để hiện quyền và tải role hiện tại của user. Nguồn frontend: AccountRoleModal.tsx:27–55.
Khi lưu, body là {roleIds:[...]}. Backend kiểm tra user và các role tồn tại, kiểm tra rank, xóa bo_account_role cũ rồi lưu tập mới và audit ASSIGN_ROLES. Đây là thay thế, không cộng thêm vào tập cũ. [] gỡ hết role vì DTO chỉ yêu cầu danh sách khác null. Nguồn: BackofficeAccountServiceImpl.java:219–266; AssignRolesRequest.java:1–6.
Sau thay đổi, response trả user và các role; khi đăng nhập hoặc GET /v1/me, quyền được tính từ hợp permission của bộ role. Nguồn: BackofficeAccountServiceImpl.java:264–280; CachedPermissionEvaluator.java:73–94.

Thay quyền role: tìm mọi user giữ role và publish accountId:PERMISSIONS_UPDATED cho từng user. Thay role của user: publish cho user đích. Nguồn: BackofficeRoleServiceImpl.java:177–181; BackofficeAccountServiceImpl.java:262; PermissionEventPublisher.java:19–22.
Fanout exchange chuyển sự kiện tới queue riêng của mỗi instance. Listener thuộc backoffice-service, xóa backoffice:permissions:{accountId} và đặt backoffice:token-invalid-before:{accountId} theo giây, TTL 24 giờ. Nguồn: RabbitTopologyConfig.java:18–36; PermissionCacheEvictionListener.java:20–38.
Phần cuối là nhánh bất đồng bộ của mỗi event; có thể xử lý trước hoặc sau response HTTP. Gateway từ chối request tiếp theo khi JWT.issuedAt < invalid-before. Điều kiện so sánh là nhỏ hơn, không phải nhỏ hơn hoặc bằng. Nguồn: JwtAuthenticationFilter.java:108–122.
Web nhận 401 thì xóa token và chuyển /login; không có thao tác đẩy logout trực tiếp tới trình duyệt trong luồng này. Khi đăng nhập lại, backend nạp cache quyền từ role rồi tạo JWT mới; frontend tải /v1/me để cập nhật quyền hiển thị. Nguồn frontend: src/api/axios.ts:30–54; src/store/useAuthStore.ts:25–32,54–63; backend: BackofficeAuthServiceImpl.java:28–49.

JWT thiếu/sai hoặc đã bị thu hồi → 401; thiếu quyền endpoint → 403. Code role trùng → ROLE_CODE_ALREADY_EXISTS (409). Role/user không tồn tại → ROLE_NOT_FOUND / ACCOUNT_NOT_FOUND (404). Nguồn: JwtAuthenticationFilter.java:78–116; PermissionAspect.java:28–40; ErrorCode.java:13–21.
Permission ngoài catalog → UNKNOWN_PERMISSION (400). Rank không được phép → UNAUTHORIZED_ROLE_ASSIGNMENT (403). Cấp quyền mình không có → UNAUTHORIZED_PERMISSION_GRANT (403). Nguồn: BackofficeRoleServiceImpl.java:131–157; ErrorCode.java:15–30.
Nguồn SRC ghim backend @7d194faf47212d41797d24f1e8eb230a63325915. Admin Web được đối chiếu riêng tại @3a95fdaf357c9b5cf8db5a6ee59445a8b0b0477c; SRC trên nút Admin Web là hợp đồng backend mà web gọi. Các link frontend chi tiết nằm trong source-evidence.md cạnh HTML.
Các file backoffice/gateway được dùng đang khớp commit. Worktree còn sửa ngoài phạm vi ở savings-service/, notification-service/ và Savings Service E2E Flow.postman_collection.json. Chỉ tạo tài liệu, không gọi API thay đổi role/quyền. Khoảng cách dọc thể hiện thứ tự, không đo thời gian; một số nút Viewer dùng tiếng Anh.