Ví đối tác & Chính sách tỷ lệ giá (Partner Wallet & Price Ratio Policy)

I. Tổng quan

1. Vấn đề

  • Hiện tại UCALL chưa có cơ chế quản lý ví riêng biệt cho Đối tác (Đại lý/Partner) để hỗ trợ mô hình phân phối dịch vụ.
  • Chưa có cơ chế cấu hình và áp dụng tỷ lệ giá tự động cho tài khoản của Khách hàng (KH) trực thuộc Đối tác khi sử dụng dịch vụ Callbot.
  • Chưa có cơ chế đối soát và khấu trừ tự động phần doanh thu chia sẻ chênh lệch giữa Đối tác và UCALL khi Đối tác áp dụng tỷ lệ giá cao ($\ge 2$).

2. Giải pháp

  • Xây dựng hệ thống Ví Đối tác cho phép quản lý số dư độc lập và thực hiện các giao dịch chuyển tiền hai chiều giữa ví Đối tác và ví KH.
  • Tích hợp tính năng cấu hình tỷ lệ giá bán lẻ ($\ge 1$) cho mỗi đối tác. Khi nạp tiền cho KH, số tiền nạp được nhân với tỷ lệ giá này, đồng thời đơn giá các tính năng Callbot trên tài khoản KH cũng được nhân với tỷ lệ tương ứng.
  • Áp dụng nguyên tắc FIFO đối với số dư ví của KH để đảm bảo tính chính xác khi chuyển tiền ngược lại từ ví KH về ví Đối tác dưới nhiều tỷ lệ giá khác nhau.
  • Tự động hóa việc theo dõi, tính toán và khấu trừ 10% doanh thu chia sẻ chênh lệch khi Đối tác áp dụng tỷ lệ giá $\ge 2$ tại mỗi lần Đối tác nạp tiền mua gói mới từ UCALL.

3. Đối tượng

  • Admin UCALL: Cấu hình tỷ lệ giá của đối tác, nạp tiền vào ví đối tác, đối soát doanh thu chênh lệch.
  • Đối tác/Đại lý: Quản lý ví đối tác, thực hiện nạp tiền cho khách hàng của mình, rút tiền từ ví khách hàng về ví đối tác.
  • Khách hàng của Đối tác: Sử dụng số dư ví được nạp để tiêu dùng các tính năng Callbot theo đơn giá đã nhân với tỷ lệ giá của Đối tác.

II. Yêu cầu chức năng

1. Danh sách tính năng

  • Cấu hình tỷ lệ giá đối tác: Cấu hình hệ số nhân giá bán cho khách hàng.
  • Nạp tiền cho ví đối tác: Ghi nhận số dư ví đối tác theo số tiền thực thanh toán.
  • Nạp tiền từ đối tác sang KH (Top-up): Chuyển tiền từ ví đối tác sang ví KH và nhân với tỷ lệ giá tương ứng.
  • Chuyển tiền từ KH về đối tác (Refund/Withdrawal): Chuyển tiền ngược lại và chia cho tỷ lệ giá tương ứng theo nguyên lý FIFO.
  • Khấu trừ doanh thu chia sẻ chênh lệch: Tự động khấu trừ 10% doanh thu chênh lệch khi nạp gói mới cho các đối tác có tỷ lệ giá $\ge 2$.

2. Đặc tả chi tiết & Nghiệp vụ

UC-01: Cấu hình tỷ lệ giá của Đối tác (Admin UCALL)

  • Hệ số tỷ lệ giá ($R$): Là một con số thực, điều kiện $R \ge 1$. Mặc định ban đầu khi tạo đối tác là $1$.
  • Ràng buộc khi thay đổi tỷ lệ giá:
    • Khi thay đổi tỷ lệ giá từ $R_{\text{old}}$ sang $R_{\text{new}}$, các gói dịch vụ/tài nguyên mà KH của Đối tác đã mua trước thời điểm thay đổi phải giữ nguyên giá cũ trước khi thay đổi tỷ lệ giá.
    • Đơn giá dịch vụ mới hoặc các khoản nạp mới phát sinh sau thời điểm thay đổi sẽ áp dụng theo tỷ lệ giá mới $R_{\text{new}}$.

UC-02: Nạp tiền cho Đối tác (Admin UCALL)

  • Ví đối tác lưu trữ số dư bằng Việt Nam Đồng (VND).
  • Khi Đối tác thanh toán mua gói của UCALL, Admin thực hiện nạp tiền vào ví đối tác: \(\text{Số dư cộng thêm vào ví Đối tác} = \text{Số tiền Đối tác thanh toán thực tế}\) (Lưu ý: Số tiền này chưa trừ khoản doanh thu chia sẻ lũy kế nếu có - xem nghiệp vụ UC-05).

UC-03: Nạp tiền từ Đối tác sang Khách hàng của đối tác (Partner Portal)

  • Đối tác thực hiện hành động nạp tiền từ ví đối tác sang ví KH của đối tác.
  • Công thức tính toán:
    • Gọi $A_{\text{deduct}}$ là số tiền thực tế bị trừ trong ví Đối tác.
    • Gọi $A_{\text{receive}}$ là số tiền ví KH nhận được.
    • Gọi $R$ là tỷ lệ giá của đối tác tại thời điểm nạp.
    • Công thức: \(A_{\text{receive}} = A_{\text{deduct}} \times R\)
    • Ví dụ: Chuyển $5,000,000$ VND từ ví Đối tác với tỷ lệ giá là $2.0$.
      • Ví Đối tác bị trừ: $5,000,000$ VND.
      • Ví KH nhận được: $10,000,000$ VND.
  • Ghi nhận lịch sử giao dịch (Ledger):
    • Hệ thống tạo một bản ghi giao dịch nạp tiền, lưu vết các thông tin: Mã GD, ID Đối tác, ID Khách hàng, Số tiền trừ đối tác, Số tiền nạp khách hàng, Tỷ lệ giá áp dụng (R), Số dư nạp còn lại của lô tiền (Remaining Balance) phục vụ cho việc rút tiền sau này.

UC-04: Chuyển tiền từ ví Khách hàng về lại ví Đối tác (Partner Portal)

  • Đối tác thực hiện rút tiền từ ví KH về lại ví của mình khi cần thu hồi số dư chưa sử dụng.
  • Giải quyết bài toán nhiều tỷ lệ giá khác nhau (Nguyên tắc FIFO):
    • Khi số dư ví của KH được tích lũy từ nhiều lần nạp với các tỷ lệ giá khác nhau, hệ thống sẽ tự động trừ số dư từ các giao dịch nạp (lô tiền) cũ nhất còn số dư (FIFO).
    • Đối với mỗi lô tiền bị khấu trừ, số tiền hoàn lại ví đối tác sẽ được chia cho tỷ lệ giá tương ứng của lô tiền đó.
  • Công thức hoàn tiền: \(\text{Số tiền hoàn lại ví Đối tác} = \sum \left( \frac{\text{Số tiền trừ ở ví KH từ lô } i}{R_i} \right)\)
  • Ví dụ minh họa:
    • Giao dịch nạp 1: Đối tác nạp $5,000,000$ VND với tỷ lệ $2.0$ $\rightarrow$ Ví KH nhận $10,000,000$ VND.
    • Giao dịch nạp 2: Đối tác nạp $10,000,000$ VND với tỷ lệ $1.5$ $\rightarrow$ Ví KH nhận $15,000,000$ VND.
    • Tổng số dư ví KH hiện tại: $25,000,000$ VND.
    • Đối tác thực hiện rút $15,000,000$ VND từ ví KH về lại ví đối tác:
      • Bước 1 (Khấu trừ lô 1): Lô 1 (cũ nhất) còn số dư $10,000,000$ VND. Khấu trừ toàn bộ $10,000,000$ VND ở ví KH $\rightarrow$ Hoàn lại ví đối tác: $10,000,000 / 2.0 = 5,000,000$ VND. Số dư còn lại của lô 1 cập nhật về $0$.
      • Bước 2 (Khấu trừ lô 2): Cần khấu trừ thêm $5,000,000$ VND nữa để đủ $15,000,000$ VND yêu cầu. Khấu trừ $5,000,000$ VND từ lô 2 (còn $15,000,000$ VND) $\rightarrow$ Hoàn lại ví đối tác: $5,000,000 / 1.5 = 3,333,333$ VND. Số dư còn lại của lô 2 cập nhật về $10,000,000$ VND.
      • Kết quả: Ví KH bị trừ $15,000,000$ VND (còn lại $10,000,000$ VND). Ví Đối tác được cộng lại: $5,000,000 + 3,333,333 = 8,333,333$ VND.

UC-05: Khấu trừ doanh thu chia sẻ chênh lệch (Revenue Sharing)

  • Điều kiện áp dụng: Đối tác áp dụng tỷ lệ giá $R \ge 2$.
  • Tỷ lệ chia sẻ doanh thu: 10% trên phần doanh thu chênh lệch tăng thêm.
  • Công thức tính toán: \(\text{Doanh thu chia sẻ} = (\text{Doanh thu thực thu từ KH} - \text{Doanh thu theo đơn giá gốc UCALL}) \times 10\%\) Trong đó:
    • Doanh thu thực thu từ KH: Là số tiền thực tế đối tác thu từ khách hàng cuối (được đối tác khai báo minh bạch trên hệ thống khi tạo/kích hoạt tài khoản KH hoặc thông qua các hợp đồng đối soát định kỳ).
    • Doanh thu theo đơn giá gốc UCALL: Số tiền quy đổi tương đương theo đơn giá gốc của UCALL (bằng Doanh thu thực thu từ KH / R).
  • Thời điểm tính toán & khấu trừ:
    • Khoản chia sẻ này được tính lũy kế theo chu kỳ hàng tháng.
    • Hệ thống tự động khấu trừ phần chênh lệch phát sinh chưa thanh toán này tại thời điểm Đối tác nạp tiền mua gói mới của UCALL (thanh toán trả trước).
    • Ví dụ:
      • Đối tác áp dụng tỷ lệ $2.0$. Doanh thu thực thu từ KH trong tháng là $20,000,000$ VND.
      • Doanh thu theo đơn giá gốc UCALL: $20,000,000 / 2.0 = 10,000,000$ VND.
      • Doanh thu chia sẻ phát sinh: $(20,000,000 - 10,000,000) \times 10\% = 1,000,000$ VND.
      • Khi đối tác thực hiện nạp tiền mua gói mới trị giá $10,000,000$ VND:
        • Hệ thống tự động khấu trừ $1,000,000$ VND doanh thu chia sẻ.
        • Số dư thực nhận được ghi nhận vào ví đối tác là: $10,000,000 - 1,000,000 = 9,000,000$ VND.

3. Giao diện (Figma Reference)

  • Thiết kế Figma - Quản lý Đại lý & Ví
  • Yêu cầu UI Admin:
    • Form cấu hình tỷ lệ giá của Đối tác trong danh sách Đối tác/Đại lý.
    • Màn hình lịch sử giao dịch ví đối tác (hiển thị rõ số tiền thực nạp, tiền khấu trừ doanh thu chia sẻ, tiền chuyển cho KH).
    • Popup thực hiện chuyển tiền Đối tác $\leftrightarrow$ Khách hàng.

III. Yêu cầu phi chức năng

  • Audit Log: Mọi hành động thay đổi tỷ lệ giá, chuyển tiền qua lại và khấu trừ tự động đều phải ghi nhận log chi tiết bao gồm: người thực hiện, thời gian, số dư trước và sau giao dịch.

VI. Test Case

  • TC1 (Happy Path - Cấu hình & Nạp tiền KH):
    • Cấu hình tỷ lệ đối tác $R = 2$.
    • Thực hiện nạp $1,000,000$ VND từ đối tác sang KH.
    • Kết quả: Ví đối tác trừ $1,000,000$ VND, ví KH cộng $2,000,000$ VND. Lịch sử giao dịch lưu tỷ lệ $2.0$.
  • TC2 (Happy Path - Chuyển tiền ngược lại FIFO):
    • Thực hiện tiếp từ TC1: Đối tác đổi tỷ lệ sang $1.5$, nạp tiếp $1,500,000$ VND sang KH $\rightarrow$ KH nhận thêm $2,250,000$ VND. Tổng ví KH là $4,250,000$ VND.
    • Thực hiện chuyển ngược $3,000,000$ VND từ KH về đối tác.
    • Kết quả mong muốn:
      • Trừ hết lô 1 ($2,000,000$ VND ở ví KH $\rightarrow$ hoàn đối tác $1,000,000$ VND).
      • Trừ tiếp lô 2 ($1,000,000$ VND ở ví KH $\rightarrow$ hoàn đối tác $1,000,000 / 1.5 = 666,667$ VND).
      • Tổng ví đối tác nhận: $1,666,667$ VND. Ví KH còn $1,250,000$ VND.
  • TC3 (Ngoại lệ - Thay đổi tỷ lệ giá ảnh hưởng gói cũ):
    • Khách hàng đã mua gói Callbot $1,000$ phút với giá cũ khi tỷ lệ là $1.5$.
    • Đối tác đổi tỷ lệ thành $2.0$.
    • Kiểm tra: Giá tiêu dùng của gói $1,000$ phút cũ vẫn phải được tính theo tỷ lệ $1.5$ ban đầu, không bị tăng lên theo tỷ lệ mới.
  • TC4 (Business Rule - Khấu trừ doanh thu chia sẻ):
    • Đối tác có doanh thu chia sẻ chưa thanh toán là $500,000$ VND.
    • Đối tác nạp $5,000,000$ VND mua gói mới.
    • Kết quả: Hệ thống trừ $500,000$ VND doanh thu chia sẻ, ví đối tác chỉ được cộng $4,500,000$ VND.