Bỏ qua nội dung
VNexus VNexus Requirement

Admin xem thống kê gói package

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

Mục tiêu

Cung cấp cho admin một cái nhìn tổng hợp về catalog gói và lượng subscriber từng gói trong một lần gọi, phục vụ ra quyết định kinh doanh (gói nào bán chạy, gói nào nên ngừng bán). Toàn bộ số liệu được tính trong một truy vấn grouped duy nhất để tránh N+1, đảm bảo trang dashboard tải nhanh kể cả khi catalog lớn.

Phạm vi

Trong phạm vi (In scope):

  • API thống kê GET /admin/subscriptions/packages/statistics, chỉ role admin.
  • Trả PackageStatisticsResponse gồm số liệu scalar và mảng items per-package.
  • Scalar: totalPackages (tổng số gói), activePackages (số gói ACTIVE), totalActiveSubscribers (tổng subscriber còn active toàn hệ thống).
  • Mảng items mỗi gói: packageId, code, name, status, activeSubscriberCount, totalSubscriberCount.
  • Tính trong một query grouped duy nhất (không N+1).

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

User Stories

  • Là admin, tôi muốn xem tổng số gói và số gói đang bán để nắm nhanh quy mô catalog.
  • Là admin, tôi muốn biết mỗi gói có bao nhiêu subscriber đang active để đánh giá gói nào bán chạy.
  • Là admin, tôi muốn so sánh subscriber active với tổng subscriber (kể cả đã hết hạn) để đánh giá khả năng giữ chân.
  • Là hệ thống, tôi muốn tổng hợp số liệu trong một query grouped để dashboard tải nhanh, tránh N+1.

Luồng chức năng

sequenceDiagram
    actor Admin
    participant App as FE Admin
    participant BE

    Admin->>App: Mở dashboard thống kê gói
    App->>BE: GET /admin/subscriptions/packages/statistics
    BE->>BE: Kiểm tra role admin
    BE->>BE: Một query grouped: đếm gói + subscriber active/total per package
    BE->>BE: Tính scalar totalPackages, activePackages, totalActiveSubscribers
    BE-->>App: PackageStatisticsResponse (scalar + items[])

Acceptance Criteria

  • AC-1: GET /admin/subscriptions/packages/statistics yêu cầu role admin.
  • AC-2: Trả PackageStatisticsResponse gồm các field scalar và mảng items.
  • AC-3: totalPackages = tổng số gói trong catalog.
  • AC-4: activePackages = số gói ở trạng thái ACTIVE.
  • AC-5: totalActiveSubscribers = tổng subscriber còn active trên toàn bộ gói.
  • AC-6: Mỗi entry trong items có: packageId, code, name, status, activeSubscriberCount, totalSubscriberCount.
  • AC-7: activeSubscriberCount = số subscriber còn active của gói đó; totalSubscriberCount = mọi assignment kể cả đã hết hạn.
  • AC-8: Toàn bộ số liệu tính trong một query grouped duy nhất (không N+1).
  • AC-9: Gói không có subscriber vẫn xuất hiện trong items với count = 0.

Quy tắc nghiệp vụ

  • Đây là endpoint TRA CỨU thống kê tổng hợp read-only; không thay đổi dữ liệu và không ghi lại thao tác xem.
  • activeSubscriberCount chỉ đếm subscriber còn hiệu lực; totalSubscriberCount đếm mọi assignment lịch sử (gồm EXPIRED).
  • totalActiveSubscribers (scalar) là tổng activeSubscriberCount toàn hệ thống, dùng cho KPI nhanh.
  • Số liệu phản ánh trạng thái tại thời điểm gọi; không lưu snapshot lịch sử.
  • Hiệu năng: bắt buộc gom đếm trong một query grouped để dashboard không phát sinh N+1.

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

Entity nghiệp vụ:

  • Package: catalog gói (định nghĩa tại package-view).
  • UserPackage: assignment gói cho user, nguồn để đếm subscriber (sinh tại package-purchase).
  • PackageStatisticsResponse: kết quả tổng hợp — scalar + items[].
  • PackageStatisticsItem: dòng thống kê per-package — packageId, code, name, status, activeSubscriberCount, totalSubscriberCount.

Trạng thái subscriber dùng để đếm:

  • active — subscriber còn hiệu lực, tính vào activeSubscriberCount.
  • expired — đã hết hạn, vẫn tính vào totalSubscriberCount.

Liên quan