Bỏ qua nội dung
VNexus VNexus Requirement

Admin quản lý role của user

Feature URL
Module
admin
Status
in-development
Priority
P2
Platforms
fe · be
AC progress
11 / 14
Last reviewed
2026-05-29

Mục tiêu

Cho phép admin xem, gán, gỡ hoặc thay thế toàn bộ role set của một user để điều chỉnh quyền truy cập. Flow này có audit và guard để không làm hệ thống mất admin cuối cùng.

Phạm vi

Trong phạm vi (In scope):

  • Admin xem role hiện tại của user.
  • Admin gán thêm một role cho user.
  • Admin gỡ một role khỏi user.
  • Admin replace toàn bộ role set của user.
  • Ghi audit row cho các thay đổi assign/revoke.
  • Guard không được revoke admin role nếu kết quả làm hệ thống không còn admin.
  • FE role management section trên user detail.

Ngoài phạm vi (Out of scope):

  • CRUD role/permission catalog.
  • Policy editor nâng cao.
  • Phân quyền theo resource cụ thể ngoài role membership.
  • Ban/unban user, xem feature admin-user-ban-unban.

User Stories

  • Là admin, tôi muốn xem các role hiện tại của user để hiểu quyền họ đang có.
  • Là admin vận hành, tôi muốn gán role phù hợp cho user khi họ được nâng quyền.
  • Là admin bảo mật, tôi muốn gỡ role không còn phù hợp và có audit lý do.
  • Là hệ thống, tôi muốn chặn thao tác khiến không còn admin nào trong platform.

Luồng chức năng

sequenceDiagram
    actor Admin
    participant Web
    participant BE
    participant DB

    Admin->>Web: Mở tab Roles trong user detail
    Web->>BE: GET /api/v1/admin/iam/users/{userId}/roles
    BE-->>Web: List<RoleResponse>

    Admin->>Web: Chọn assign/revoke/replace roles
    alt Assign role
        Web->>BE: POST /api/v1/admin/iam/users/{userId}/roles {roleId, reason}
    else Revoke role
        Web->>BE: DELETE /api/v1/admin/iam/users/{userId}/roles/{roleId}?reason=...
    else Replace role set
        Web->>BE: PUT /api/v1/admin/iam/users/{userId}/roles {roleIds, reason}
    end
    BE->>DB: Validate user/role, last-admin guard
    BE->>DB: Mutate user_roles + ghi user_role_audit
    BE-->>Web: Updated List<RoleResponse>
    Web->>Admin: Hiển thị role set mới

Acceptance Criteria

  • AC-1: Backend có GET /api/v1/admin/iam/users/{userId}/roles, chỉ admin được gọi.
  • AC-2: List roles trả RoleResponse theo priority tăng dần.
  • AC-3: Backend có POST /api/v1/admin/iam/users/{userId}/roles để assign role.
  • AC-4: Assign role là idempotent nếu user đã có role đó.
  • AC-5: Backend có DELETE /api/v1/admin/iam/users/{userId}/roles/{roleId} để revoke role.
  • AC-6: Revoke role là idempotent nếu user không có role đó.
  • AC-7: Backend có PUT /api/v1/admin/iam/users/{userId}/roles để replace full role set.
  • AC-8: Replace dùng full-replace semantics: role thiếu trong roleIds sẽ bị revoke, role mới sẽ được assign.
  • AC-9: Nếu user hoặc role không tồn tại, API trả not found.
  • AC-10: Revoke/replace bị chặn nếu kết quả làm mất admin cuối cùng.
  • AC-11: Mỗi thay đổi assign/revoke thực sự tạo UserRoleAudit với eventType, userId, roleId, actorUserId, reason.
  • AC-12: FE cần UI role management trong admin user detail.
  • AC-13: FE cần gọi đúng path /api/v1/admin/iam/users/{userId}/roles.
  • AC-14: FE cần confirmation cho revoke/replace role, nhất là admin role.

Quy tắc nghiệp vụ

  • Chỉ admin được quản lý role của user.
  • Gán/gỡ role phải audit được actor và reason nếu có.
  • Không được để platform về trạng thái không có user nào giữ role admin.
  • Replace role set là thao tác nguy hiểm; UI phải cho admin nhìn thấy diff trước khi xác nhận.
  • Role management không thay đổi lifecycle status của user; ban/unban là flow riêng.

Dữ liệu & Trạng thái

Entity nghiệp vụ:

  • User: target user có roleEntities.
  • Role: role được gán/gỡ.
  • user_roles: join table membership.
  • UserRoleAudit: audit row cho assign/revoke.
  • AssignRoleRequest / ReplaceUserRolesRequest: mutation payloads.
  • RoleResponse: response role list.

Trạng thái user-facing:

  • roles-loading — đang tải role list.
  • roles-ready — role list đã sẵn sàng.
  • assigning-role — đang gán role.
  • revoking-role — đang gỡ role.
  • replacing-roles — đang replace role set.
  • last-admin-blocked — backend chặn vì sẽ mất admin cuối cùng.

Liên quan