Bỏ qua nội dung
VNexus VNexus Requirement

Admin xem subscriber của gói package

Feature URL
Module
admin
Status
shipped
Priority
P1
Platforms
fe · be
AC progress
8 / 8
Last reviewed
2026-06-08

Mục tiêu

Cho phép admin drill-down từ một gói cụ thể xuống danh sách user đang dùng hoặc đã từng dùng gói đó, phục vụ vận hành (chăm sóc khách hàng, kiểm tra gia hạn, xử lý khiếu nại). Đây là bước tra cứu chi tiết tiếp nối từ thống kê tổng hợp, giúp admin trả lời câu hỏi “ai đang dùng gói này”.

Phạm vi

Trong phạm vi (In scope):

  • API tra cứu subscriber GET /admin/subscriptions/packages/{id}/subscribers, chỉ role admin.
  • Filter tuỳ chọn theo status assignment: ACTIVE hoặc EXPIRED; không truyền → trả tất cả.
  • Phân trang qua Pageable (page, size, sort).
  • Trả Page<PackageSubscriberResponse>, mỗi item: userId, fullName, email, phone, status, startedAt, expiredAt, isRenewal.
  • Trả 404 nếu id gói không tồn tại.

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

  • Thống kê tổng hợp số subscriber theo gói — xem admin-package-statistics.
  • Danh sách cấu hình gói — xem admin-package-list.
  • Tạo / cập nhật gói — xem admin-package-create, admin-package-update.
  • Chỉnh sửa / huỷ gói của một user cụ thể — không thuộc feature này.
  • Lưu lịch sử thao tác tra cứu / audit log thao tác admin — đây là endpoint tra cứu danh sách, không phải log thao tác.

User Stories

  • Là admin, tôi muốn xem danh sách user đang dùng một gói để hỗ trợ vận hành và chăm sóc khách hàng.
  • Là admin, tôi muốn lọc theo ACTIVE / EXPIRED để tách user còn hiệu lực với user đã hết hạn.
  • Là admin, tôi muốn thấy thông tin liên hệ cơ bản (fullName, email, phone) cùng mốc thời gian (startedAt, expiredAt) để liên hệ và kiểm tra hạn dùng.
  • Là admin, tôi muốn nhận lỗi 404 khi gói không tồn tại để biết mình đã tra cứu sai id.

Luồng chức năng

sequenceDiagram
    actor Admin
    participant App as FE Admin
    participant BE

    Admin->>App: Chọn 1 gói, xem subscriber
    App->>BE: GET /admin/subscriptions/packages/{id}/subscribers?status&page&size
    BE->>BE: Kiểm tra role admin
    alt Gói id không tồn tại
        BE-->>App: 404 Not Found
    else Gói tồn tại
        alt Có filter status
            BE->>BE: Lọc assignment theo ACTIVE / EXPIRED
        else Không filter
            BE->>BE: Lấy mọi assignment của gói
        end
        BE->>BE: Phân trang theo Pageable
        BE-->>App: Page<PackageSubscriberResponse>
    end

Acceptance Criteria

  • AC-1: GET /admin/subscriptions/packages/{id}/subscribers yêu cầu role admin.
  • AC-2: id gói không tồn tại → 404 Not Found.
  • AC-3: Filter status là tuỳ chọn; chỉ nhận ACTIVE / EXPIRED.
  • AC-4: Không truyền status → trả mọi subscriber (cả ACTIVE và EXPIRED).
  • AC-5: Truyền status=ACTIVE → chỉ subscriber còn hiệu lực; status=EXPIRED → chỉ subscriber đã hết hạn.
  • AC-6: Hỗ trợ phân trang qua Pageable, trả Page<PackageSubscriberResponse>.
  • AC-7: Mỗi item có: userId, fullName, email, phone, status, startedAt, expiredAt, isRenewal.
  • AC-8: isRenewal phản ánh cờ gia hạn của assignment tương ứng.

Quy tắc nghiệp vụ

  • Đây là endpoint TRA CỨU danh sách subscriber read-only phục vụ vận hành; không thay đổi dữ liệu và không phải log thao tác người dùng.
  • status ở đây là trạng thái assignment (UserPackage) của user trong gói, không phải trạng thái catalog gói.
  • Một user có thể xuất hiện nhiều dòng nếu từng dùng gói nhiều lần (mỗi assignment một dòng), gồm cả các bản EXPIRED.
  • startedAt / expiredAt là mốc hiệu lực của từng assignment; isRenewal cho biết assignment đó có bật gia hạn.
  • Số liệu phản ánh trạng thái tại thời điểm gọi; không lưu snapshot.

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

Entity nghiệp vụ:

  • Package: gói được drill-down (định nghĩa tại package-view); 404 nếu id không tồn tại.
  • UserPackage: assignment gói cho user, nguồn dữ liệu subscriber (sinh tại package-purchase).
  • PackageSubscriberResponse: view mỗi subscriber — userId, fullName, email, phone, status, startedAt, expiredAt, isRenewal.
  • Pageable / Page<PackageSubscriberResponse>: tham số phân trang và kết quả.

Trạng thái subscriber (assignment):

  • ACTIVE — user còn đang dùng gói, còn hiệu lực.
  • EXPIRED — assignment đã hết hạn / kết thúc.

Liên quan