Bỏ qua nội dung
VNexus VNexus Requirement

Admin ban và unban user

Feature URL
Module
admin
Status
in-development
Priority
P1
Platforms
fe · be
AC progress
12 / 15
Last reviewed
2026-05-29

Mục tiêu

Cho phép admin vô hiệu hoá tài khoản vi phạm bằng cách ban user và khôi phục user đã ban khi cần. Flow này phải có guard để admin không tự khoá mình, không ban admin khác, và có audit trail cho thao tác kiểm duyệt.

Phạm vi

Trong phạm vi (In scope):

  • Admin ban user non-admin qua POST /api/v1/admin/users/{id}/ban.
  • Admin nhập reason optional, tối đa 500 ký tự, dùng cho audit log.
  • Ban set User.status = BANNED và xoá refresh token đã lưu.
  • Admin unban user đang BANNED qua POST /api/v1/admin/users/{id}/unban.
  • Unban set User.status = ACTIVE.
  • Publish domain events và ghi audit log cho ban/unban.
  • FE action buttons, confirmation dialog, optimistic/refresh detail/list sau mutation.

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

  • Ban listing riêng lẻ.
  • Xoá cứng user hoặc xoá dữ liệu user.
  • Token denylist cho access token đã phát hành.
  • Role management, xem feature admin-user-role-management.

User Stories

  • Là admin kiểm duyệt, tôi muốn ban user vi phạm để chặn họ tiếp tục đăng nhập/sử dụng hệ thống.
  • Là admin support, tôi muốn nhập lý do ban để audit và các admin khác hiểu quyết định.
  • Là admin, tôi muốn unban user khi xử lý nhầm hoặc sau khi user được khôi phục.
  • Là hệ thống, tôi muốn ngăn self-ban và ngăn ban admin để tránh lockout vận hành.

Luồng chức năng

sequenceDiagram
    actor Admin
    participant Web
    participant BE
    participant Audit

    Admin->>Web: Click Ban trên user detail/list
    Web->>Admin: Confirm + nhập reason optional
    Admin->>Web: Xác nhận
    Web->>BE: POST /api/v1/admin/users/{id}/ban {reason}
    BE->>BE: Chặn self-ban, chặn ban admin, chặn user đã BANNED
    BE->>BE: Set status=BANNED, clear refresh token
    BE->>Audit: UserBannedEvent
    BE-->>Web: AdminUserResponse mới
    Web->>Admin: Cập nhật status BANNED

    Admin->>Web: Click Unban user đang BANNED
    Web->>BE: POST /api/v1/admin/users/{id}/unban
    BE->>BE: Chỉ cho user đang BANNED
    BE->>BE: Set status=ACTIVE
    BE->>Audit: UserUnbannedEvent
    BE-->>Web: AdminUserResponse mới

Acceptance Criteria

  • AC-1: Backend có POST /api/v1/admin/users/{id}/ban, chỉ admin được gọi.
  • AC-2: Body ban optional, gồm reason tối đa 500 ký tự.
  • AC-3: Admin không thể ban chính mình; backend trả business rule error.
  • AC-4: Admin không thể ban user có role admin.
  • AC-5: User đã BANNED mà bị ban lại trả conflict.
  • AC-6: Ban thành công set status=BANNED, set refreshToken=null, refreshTokenExpiresAt=null.
  • AC-7: Ban publish UserBannedEvent gồm actor, target, previousStatus, reason, occurredAt.
  • AC-8: Backend có POST /api/v1/admin/users/{id}/unban, chỉ admin được gọi.
  • AC-9: Unban chỉ áp dụng cho user đang BANNED; status khác trả conflict.
  • AC-10: Unban thành công set status=ACTIVE và publish UserUnbannedEvent.
  • AC-11: Audit logger ghi structured log cho ban/unban.
  • AC-12: Ban/unban trả AdminUserResponse mới sau mutation.
  • AC-13: FE cần action UI ban/unban với confirmation rõ ràng.
  • AC-14: FE constants cần trỏ đúng /api/v1/admin/users/{id}/ban|unban; hiện đang khai báo dưới /api/v1/users/admin/{id}/....
  • AC-15: Sau mutation, FE cần refresh detail/list hoặc patch status trong cache.

Quy tắc nghiệp vụ

  • Ban là trạng thái moderation, không xoá user và không xoá dữ liệu liên quan.
  • Banned user bị chặn ở auth flow; refresh token bị xoá để không mint access token mới.
  • Access token đã phát hành trước đó vẫn có thể sống đến khi hết hạn nếu chưa có token denylist.
  • Không được self-ban hoặc ban admin khác qua endpoint này.
  • Unban chỉ chuyển từ BANNED về ACTIVE; không dùng để nâng INACTIVE hoặc PENDING.
  • Reason ban là audit-only, không trả cho user bị ban.

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

Entity nghiệp vụ:

  • User: status, refreshToken, refreshTokenExpiresAt, roleEntities.
  • BanUserRequest: request reason optional.
  • AdminUserResponse: response sau mutation.
  • UserBannedEvent / UserUnbannedEvent: event audit.
  • AdminUserAuditLogger: sink audit log hiện tại.

Trạng thái user-facing:

  • active — user đang hoạt động.
  • banning — admin đang gửi lệnh ban.
  • banned — user đã bị ban.
  • unbanning — admin đang gửi lệnh unban.
  • ban-conflict — user đã banned hoặc thao tác bị rule chặn.
  • unban-conflict — user không ở trạng thái banned.

Liên quan