Bỏ qua nội dung
VNexus VNexus Requirement

Admin xem và tìm kiếm danh sách user

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

Mục tiêu

Cho phép admin xem danh sách user trong hệ thống trên một màn quản trị, tìm nhanh theo keyword và lọc theo trạng thái, role, khu vực hoặc ngày tạo. Đây là màn entry để admin đi tới chi tiết user, ban/unban hoặc quản lý role.

Phạm vi

Trong phạm vi (In scope):

  • Admin truy cập trang /admin/users.
  • API GET /api/v1/admin/users trả danh sách user ở mọi lifecycle status.
  • Filter theo keyword, status, roleCode, province, ward, createdFrom, createdTo.
  • Pagination/sort theo Spring Pageable, mặc định size=20, createdAt DESC.
  • Response dùng AdminUserSummaryResponse để hiển thị dữ liệu list gọn nhẹ.
  • FE hiển thị table/list, filter controls, pagination, loading/error/empty state.

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

  • Xem full detail user, xem feature admin-user-detail.
  • Ban/unban user, xem feature admin-user-ban-unban.
  • Gán/gỡ role, xem feature admin-user-role-management.
  • Export CSV hoặc bulk action.

User Stories

  • Là admin, tôi muốn xem toàn bộ user ở mọi trạng thái để giám sát hệ thống.
  • Là admin support, tôi muốn tìm user theo tên, email hoặc số điện thoại để xử lý yêu cầu nhanh.
  • Là admin vận hành, tôi muốn lọc user theo status/role/khu vực/ngày tạo để phát hiện account bất thường.

Luồng chức năng

sequenceDiagram
    actor Admin
    participant Web
    participant BE
    participant DB

    Admin->>Web: Mở /admin/users
    Web->>BE: GET /api/v1/admin/users?keyword=&status=&page=0&size=20
    BE->>BE: Kiểm tra role admin
    BE->>BE: Validate filters và sort whitelist
    BE->>DB: Query users theo Specification
    BE->>DB: Hydrate role membership cho page hiện tại
    BE-->>Web: PageResponse<AdminUserSummaryResponse>
    Web->>Admin: Render danh sách user + filter + pagination

Acceptance Criteria

  • AC-1: Backend có GET /api/v1/admin/users, class-level @PreAuthorize("hasRole('admin')").
  • AC-2: API trả user ở mọi status: ACTIVE, INACTIVE, BANNED, PENDING.
  • AC-3: keyword match case-insensitive trên fullName, email, phone, tối đa 200 ký tự.
  • AC-4: status chỉ nhận ACTIVE|INACTIVE|BANNED|PENDING.
  • AC-5: roleCode filter theo exact role code và không làm duplicate row trong pagination.
  • AC-6: province, ward, createdFrom, createdTo là optional filters.
  • AC-7: Sort chỉ cho phép field whitelist: id, fullName, email, phone, status, province, ward, createdAt, updatedAt, lastLoginAt.
  • AC-8: Sort field ngoài whitelist bị từ chối bằng business error, không echo raw field vào safe message.
  • AC-9: Response item gồm id, fullName, email, phone, avatarUrl, status, roles, createdAt, lastLoginAt.
  • AC-10: Backend hydrate roles cho page bằng một query phụ để tránh N+1.
  • AC-11: FE /admin/users cần thay placeholder bằng table/list thật.
  • AC-12: FE route constants cần khớp backend path /api/v1/admin/users; hiện đang khai báo dưới ROUTES_API_USER dạng /api/v1/users/admin.
  • AC-13: FE cần filter controls, pagination và xử lý loading/error/empty.

Quy tắc nghiệp vụ

  • Chỉ admin được truy cập danh sách user quản trị.
  • Admin thấy cả user bị ban/inactive/pending; đây là khác biệt với public/user endpoints.
  • Response list không trả field nặng hoặc nhạy cảm hơn detail như bio, signupUserAgent, quota counters.
  • Sort whitelist bảo vệ các private columns như password, refreshToken, providerId, signupIp, signupUserAgent.
  • List là entry point, các thao tác nhạy cảm phải vào detail/action riêng để có confirmation rõ ràng.

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

Entity nghiệp vụ:

  • User: nguồn dữ liệu danh sách user.
  • Role: role membership dùng cho filter và summary.
  • AdminUserSearchRequest: filter query params.
  • AdminUserSummaryResponse: row hiển thị trong admin list.
  • PageResponse<AdminUserSummaryResponse>: pagination contract.

Trạng thái user-facing:

  • list-loading — đang tải danh sách.
  • list-ready — có dữ liệu.
  • list-empty — không có user khớp filter.
  • filter-invalid — filter/sort không hợp lệ.
  • list-error — lỗi tải danh sách.

Liên quan