Chương trình giới thiệu (Affiliate)

Feature URL

Module

payment

Status

shipped

Priority

Platforms

fe · be

AC progress

20 / 20

Last reviewed

2026-05-29

Mục tiêu

Khuyến khích người dùng đang sử dụng gói trả phí giới thiệu người mới đến V-Nexus. Mỗi người giới thiệu (referrer) có một mã giới thiệu duy nhất để chia sẻ; khi người được giới thiệu (referee) đăng ký và kích hoạt gói trả phí, người giới thiệu tự động nhận hoa hồng quy đổi thành V-Credits cộng thẳng vào ví. Mục tiêu: tăng trưởng người dùng trả phí qua kênh truyền miệng và thưởng cho khách hàng trung thành, không cần bộ máy duyệt thủ công.

Phạm vi

Trong phạm vi (In scope):

Sinh mã giới thiệu duy nhất cho user đủ điều kiện (đang có gói trả phí ở trạng thái ACTIVE); mã sinh lazy lần đầu user mở màn affiliate.
Tạo link chia sẻ chứa mã (tham số ref) để referrer gửi cho người khác.
Áp mã giới thiệu lúc đăng ký (referee nhập tay hoặc vào qua link ref), gắn referee với referrer — áp dụng silently.
Tự động tính hoa hồng khi referee kích hoạt gói trả phí; quy đổi VND sang credits và cộng vào ví của referrer.
Áp tỉ lệ hoa hồng theo từng gói, kèm sàn và trần hoa hồng mỗi lượt.
Chống gian lận khi áp mã (tự giới thiệu, trùng tiền tố số điện thoại, trùng email domain riêng, vòng lặp ngược) — thất bại im lặng, không chặn đăng ký.
Đảm bảo mỗi lượt referee mua một gói chỉ sinh tối đa một khoản hoa hồng (idempotent).
Màn hình/endpoint cho referrer xem: tổng quan (mã, link, tổng số người giới thiệu, tổng hoa hồng), danh sách người đã giới thiệu (số điện thoại được mask), danh sách hoa hồng.
Trang tổng thể cho admin xem hiệu quả chương trình (tổng số mã, tổng người được giới thiệu, tổng hoa hồng VND và credits).
Thông báo cho referrer khi có người đăng ký qua mã và khi nhận hoa hồng.

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

Thời gian giữ tiền (holding period) trước khi ghi nhận — hoa hồng cộng ngay.
Rút tiền mặt (payout) — credits chỉ dùng trong hệ thống (xem ví V-Credits).
Duyệt/từ chối hoa hồng thủ công — toàn bộ tự động.
Giới thiệu đa cấp (multi-level) — chỉ một cấp: A giới thiệu B.
Hoa hồng hồi tố — referrer phải đang có gói trả phí ACTIVE vào thời điểm referee mua.
Hoa hồng từ nạp ví hay giao dịch khác ngoài việc mua gói trả phí.
Thiết kế chi tiết màn FE, schema DB, lựa chọn tech stack (thuộc repo source code).

User Stories

Là user đang dùng gói trả phí, tôi muốn có mã giới thiệu và link chia sẻ để mời bạn bè và kiếm hoa hồng.
Là user mới, tôi muốn nhập mã giới thiệu (hoặc vào qua link) khi đăng ký để người giới thiệu tôi được ghi nhận.
Là người giới thiệu, tôi muốn tự động nhận hoa hồng vào ví khi người tôi giới thiệu mua gói trả phí, không phải thao tác gì thêm.
Là người giới thiệu, tôi muốn xem danh sách người tôi đã giới thiệu và tổng hoa hồng để theo dõi hiệu quả.
Là người giới thiệu, tôi muốn xem lịch sử từng khoản hoa hồng (ai mua, gói nào, bao nhiêu) để minh bạch.
Là người giới thiệu, tôi muốn nhận thông báo khi có người đăng ký qua mã và khi nhận hoa hồng.
Là admin, tôi muốn xem tổng quan chương trình affiliate để đánh giá hiệu quả.
Là hệ thống, tôi muốn chặn các liên kết giả mạo khi áp mã và đảm bảo mỗi lượt mua chỉ sinh đúng một hoa hồng.

Luồng chức năng

sequenceDiagram
    actor A as Người giới thiệu
    actor B as Người được giới thiệu
    participant App as FE/Mobile
    participant BE
    participant Wallet as Ví V-Credits
    participant Notify as Thông báo

    Note over A,BE: Bước 1 — Lấy mã giới thiệu
    A->>App: Mở màn affiliate
    App->>BE: GET /users/me/affiliate-info
    BE->>BE: Kiểm tra A đang có gói trả phí ACTIVE
    BE->>BE: Sinh mã duy nhất nếu A chưa có
    BE-->>App: Mã giới thiệu + link chia sẻ + tổng quan

    Note over B,BE: Bước 2 — Đăng ký qua mã
    A->>B: Chia sẻ link có tham số ref
    B->>App: Đăng ký kèm mã giới thiệu
    App->>BE: Tạo tài khoản kèm mã giới thiệu
    BE->>BE: Chạy kiểm tra chống gian lận
    alt Mã hợp lệ và qua kiểm tra
        BE->>BE: Gắn B vào người giới thiệu A
        BE->>Notify: Báo A có người đăng ký qua mã
    else Mã sai hoặc nghi gian lận
        BE->>BE: Bỏ qua im lặng, vẫn cho B đăng ký
    end

    Note over B,Wallet: Bước 3 — Ghi nhận hoa hồng
    B->>App: Mua và kích hoạt gói trả phí
    App->>BE: Thanh toán gói
    BE->>BE: Kiểm tra B có người giới thiệu
    BE->>BE: Kiểm tra A còn gói trả phí ACTIVE
    BE->>BE: Kiểm tra chưa từng tính hoa hồng cho lượt mua này
    BE->>BE: Tính hoa hồng theo tỉ lệ gói rồi áp sàn và trần
    BE->>Wallet: Cộng credits vào ví của A
    BE->>Notify: Báo A đã nhận hoa hồng

    Note over A,BE: Bước 4 — Theo dõi
    A->>App: Xem người đã giới thiệu và hoa hồng
    App->>BE: GET /users/me/affiliate/referrals
    App->>BE: GET /users/me/affiliate/commissions
    BE-->>App: Danh sách phân trang

Phân vai nghiệp vụ:

Vai trò	Trách nhiệm
Người giới thiệu (referrer)	Có gói trả phí ACTIVE; lấy và chia sẻ mã; nhận hoa hồng vào ví; theo dõi danh sách giới thiệu và hoa hồng
Người được giới thiệu (referee)	Đăng ký kèm mã; mua gói trả phí — đây là sự kiện kích hoạt hoa hồng
Backend	Sinh mã, áp mã kèm chống gian lận, tính và ghi hoa hồng idempotent, cộng credits, phát thông báo, cung cấp API tổng quan/danh sách
Admin	Xem tổng thể hiệu quả chương trình

Acceptance Criteria

Quy tắc nghiệp vụ

Điều kiện cấp mã: user phải ACTIVE và đang có gói trả phí ACTIVE. Mã sinh lazy, duy nhất, mặc định 6 ký tự (dự phòng dài hơn nếu trùng nhiều lần liên tiếp), dùng bộ ký tự loại bỏ ký tự dễ nhầm.
Áp mã lúc đăng ký: không phân biệt hoa thường; áp silently (không báo lỗi cho referee).
Chống gian lận khi áp mã (thất bại im lặng):
- Tự giới thiệu: referee trùng chính referrer.
- Trùng tiền tố số điện thoại: 7 ký tự đầu giống nhau.
- Trùng email domain riêng: cùng một domain không thuộc danh sách domain công cộng (gmail.com, yahoo.com, outlook.com, …). Danh sách domain công cộng cấu hình được ở runtime.
- Vòng lặp ngược: referrer lại đang được chính referee giới thiệu.
- Referrer không ACTIVE, hoặc mã không khớp user nào.
Liên kết referee với referrer là bất biến sau lần gắn đầu tiên.
Điều kiện tính hoa hồng (phải đúng tất cả): referee có người giới thiệu; referrer ACTIVE; referrer đang có gói trả phí ACTIVE vào lúc referee mua; giá mua dương; tỉ lệ hoa hồng của gói dương; chưa từng có hoa hồng cho lượt mua đó.
Công thức hoa hồng: hoa hồng (VND) = giá gói nhân tỉ lệ (mặc định 10%, theo từng gói, kẹp trong 0..1); kẹp tiếp trong khoảng sàn 5.000đ đến trần 100.000đ; số credits bằng phần nguyên của (hoa hồng VND chia 1.000); nếu số credits không dương thì bỏ, không ghi nhận.
Idempotency: mỗi lượt referee mua một gói chỉ sinh tối đa một hoa hồng.
Không hồi tố, không holding, không payout, không duyệt thủ công, chỉ một cấp.
Phân quyền: endpoint affiliate của user cần quyền đọc affiliate; endpoint tổng thể cần quyền admin.
Bảo mật hiển thị: số điện thoại của referee hiển thị cho referrer luôn được mask.

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

Entity nghiệp vụ:

User: mỗi user có mã giới thiệu của riêng mình (referral code) và con trỏ “được giới thiệu bởi” trỏ tới referrer. Trạng thái ACTIVE là điều kiện tham gia.
Gói (Package): có tỉ lệ hoa hồng affiliate (mặc định 10%, có thể khác nhau theo gói).
Khoản hoa hồng (Commission): bản ghi phát sinh khi referee mua gói; gắn với lượt mua gói để đảm bảo duy nhất; gồm số tiền VND và số credits, người mua, tên gói, thời điểm.
Ví V-Credits: nơi credits hoa hồng được cộng vào số dư của referrer.

Tham số cấu hình nghiệp vụ:

Tham số	Giá trị mặc định	Ý nghĩa
Tỉ lệ hoa hồng theo gói	10%	Theo từng gói, kẹp trong `0..1`
Sàn hoa hồng mỗi lượt	5.000đ	Dưới mức này không phát hoa hồng
Trần hoa hồng mỗi lượt	100.000đ	Chặn trên mỗi lượt
Quy đổi credit	1 credit cho mỗi 1.000đ	Làm tròn xuống
Độ dài mã giới thiệu	6 ký tự (dự phòng dài hơn)	Loại ký tự dễ nhầm
Tiền tố số điện thoại so trùng	7 ký tự đầu	Dùng cho chống gian lận

Trạng thái eligibility của referrer (user-facing):

eligible — đang có gói trả phí ACTIVE, đã/được cấp mã.
needs_paid_package — chưa có gói trả phí ACTIVE, chưa có mã.
user_inactive — tài khoản không ở trạng thái ACTIVE.

Trạng thái khoản hoa hồng:

Không có vòng trạng thái pending/approved/paid/rejected — hoa hồng được ghi nhận là final ngay khi phát sinh (đồng bộ sau khi referee mua gói thành công).

Liên quan

Phụ thuộc: auth-register-otp — mã giới thiệu được áp dụng ngay trong luồng đăng ký; affiliate dựa trên việc gắn liên kết referee với referrer tại thời điểm tạo tài khoản.
Ảnh hưởng: Chưa có — Ghi chú: hoa hồng cộng vào ví V-Credits và được kích hoạt khi referee mua gói trả phí (xem các feature ví như wallet-topup-create). Nếu thay đổi cơ chế áp mã lúc đăng ký, cân nhắc cập nhật impacts của auth-register-otp.