Admin tạo gói package

Feature URL

Module

admin

Status

shipped

Priority

Platforms

fe · be

AC progress

15 / 15

Last reviewed

2026-06-08

Mục tiêu

Cho phép admin tạo một gói thuê bao mới trong catalog mà không cần deploy code: đặt tên, mã code duy nhất, mô tả, giá theo từng chu kỳ, các flag quyền lợi, trust score band, listing limit, daily listing distribution limit, affiliate rate. Hệ thống tự sinh các giá trị mặc định hợp lý khi admin không truyền (default plans, affiliate rate, status) để giảm sai sót khi nhập liệu.

Phạm vi

Trong phạm vi (In scope):

API tạo gói POST /admin/subscriptions/packages, chỉ role admin.
Body CreateSubscriptionPackageRequest: name, code, description, monthlyPriceVnd, monthlyPriceCredits, annualPriceCredits?, annualBonusMonths?, plans?, packageTypes?, listingLimit?, dailyListingDistributionLimit?, addressMasked, aiToolsEnabled, ownerLikelihoodEnabled, trustScoreMaxExclusive, status?, affiliateRate?.
Validate đầy đủ input: range giá, trust score, affiliate rate, plans theo cycle.
Đảm bảo code unique (normalize uppercase trước khi so sánh).
Sinh default khi thiếu: plans[] (1 tháng + 12 tháng), affiliateRate = 0.1000, status = ACTIVE, các flag theo defaults của code.
Trả 201 Created + SubscriptionPackageResponse.

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

Cập nhật gói đã có — xem admin-package-update.
Xem / list gói cho admin (gồm INACTIVE) — xem admin-package-list.
Xoá gói — không hỗ trợ; dùng INACTIVE để ngừng bán.
Seed default packages tự động (thuộc khởi tạo hệ thống, không phải thao tác admin).
Các flow phía user (xem / mua / đổi / gia hạn) — thuộc module subscription-package.

User Stories

Là admin, tôi muốn tạo gói mới với mã code duy nhất, các flag quyền lợi và giá theo chu kỳ để bổ sung vào catalog mà không cần dev deploy.
Là admin, tôi muốn chỉ nhập các field tối thiểu và để hệ thống tự sinh plans/affiliate rate/status mặc định để tạo gói nhanh.
Là admin, tôi muốn nhận lỗi rõ ràng khi code trùng để không vô tình ghi đè gói khác.
Là hệ thống, tôi muốn validate chặt giá, trust score và affiliate rate để catalog luôn hợp lệ.

Luồng chức năng

sequenceDiagram
    actor Admin
    participant App as FE Admin
    participant BE

    Admin->>App: Nhập form tạo gói
    App->>BE: POST /admin/subscriptions/packages (CreateSubscriptionPackageRequest)
    BE->>BE: Kiểm tra role admin
    BE->>BE: Validate name, prices, trustScore, affiliateRate, plans
    BE->>BE: Normalize code uppercase
    alt Code đã tồn tại
        BE-->>App: 409 ResourceAlreadyExists
    else OK
        BE->>BE: Sinh default plans/affiliateRate/status nếu thiếu
        BE->>BE: Build Package entity, normalize plans
        BE-->>App: 201 SubscriptionPackageResponse
    end

Acceptance Criteria

Quy tắc nghiệp vụ

code là machine-readable identifier viết hoa, unique trong catalog; dùng để tham chiếu từ business code.
Giá có 2 đơn vị độc lập: priceVnd (hiển thị, reconciliation) và priceCredits (trừ ví khi mua). MVP: 1 VND ≈ 1 V-Credit nhưng có thể tách rời.
annualPriceCredits mặc định = monthlyPriceCredits × 12 nếu không truyền.
bonusMonths mở rộng thời gian hưởng lợi nhưng không tính vào kỳ trả phí / pro-rata refund.
listingLimit = null nghĩa là không giới hạn; dailyFreeUnlockLimit lấy từ packageTypes hoặc defaults theo code.
dailyListingDistributionLimit là số tin hệ thống tự phân phối cho broker mỗi ngày; 0 nghĩa là tắt phân phối tự động.
trustScoreMaxInclusive (DB) suy từ trustScoreMaxExclusive (input): inclusive = exclusive - 0.01.
Một số flag mặc định gắn theo code chuẩn: smartPush bật cho PREMIUM/PRO/MAX/TEAM; vipFlashDeal chỉ MAX/TEAM; displayPriorityRank MAX/TEAM=1, PRO=2, PREMIUM=3, còn lại null.
Không cho phép xoá gói qua API; ngừng bán bằng INACTIVE.
Tạo gói chỉ thêm vào catalog (Package), không ảnh hưởng các UserPackage đã tồn tại.

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

Entity nghiệp vụ:

Package: gói mới được tạo trong catalog (định nghĩa đầy đủ tại package-view).
PackagePlan: entry trong plans[] (JSONB) — cycleMonths, priceVnd, priceCredits, bonusMonths.
PackageTypeMetadata: metadata tuỳ chọn (trust score band, dailyFreeUnlockLimit, các flag quyền lợi).
CreateSubscriptionPackageRequest: payload tạo gói.
SubscriptionPackageResponse: view trả về sau khi tạo.

Field đáng chú ý:

dailyListingDistributionLimit: số tin hệ thống tự phân phối cho broker mỗi ngày, 0 = tắt. Lưu trên Package entity và trả về trong SubscriptionPackageResponse.

Trạng thái Package (lúc tạo):

ACTIVE — mặc định, bán ngay, hiện trên catalog public.
INACTIVE — tạo nhưng chưa bán / tạm ẩn.

Liên quan

Phụ thuộc: Chưa có.
Ảnh hưởng: package-view, package-purchase
Cập nhật gói: admin-package-update