Referral

Overview

• Description: Fetch the downline tree structure (agent networking) of the current player, and query the game and financial reports (turnover, wins, deposits, withdrawals) of downline players within a specified time period.

Business Logic & Explanations

TIP

The referral reporting logic involves recursive tree traversal and massive data aggregation. The backend achieves high performance and precision through the following mechanisms:

1. Depth Control (Max Depth): When retrieving the downline tree, the system reads the player_generation configuration from the backend. The recursive query stops once this maximum generation limit is reached, preventing memory exhaustion caused by excessively deep agent hierarchies.
2. Read-Write Separation & ES Aggregation: Daily statistics (turnover, wins/losses, etc.) of downline players are not queried directly from MySQL. Instead, after extracting all downline IDs from the tree, the system performs a batch aggregation query in Elasticsearch (wg_player_daily_stats), massively speeding up report generation.
3. Precision Restoration (Divisor Scaling): Similar to the Finance Personal Report, financial data stored in ES is scaled up by a factor of 100,000 to prevent floating-point loss. After aggregating the results, the interface standardizes the values back to true decimal figures using bcdiv(value, '100000', 3) before sending them to the frontend.

---

1. GET - Get Downline Tree

• Path: /api/promotions/referrals/tree
• Description: Recursively retrieve all downline players for the current user.

Request Headers

Parameter	Type	Required	Description
Authorization	String	Yes	Bearer Token

Response Example

{
  "code": 0,
  "msg": "Success",
  "data": [
    {
      "player_id": 1002,
      "username": "downline_user1",
      "level": 1,
      "children": [
        {
          "player_id": 1005,
          "username": "downline_user1_sub",
          "level": 2,
          "children": []
        }
      ]
    }
  ]
}

2. GET - Get Downline Financial Report

• Path: /api/promotions/referrals/report
• Description: Aggregates the betting turnover, wins/losses, and deposits/withdrawals brought in by downline users within a specific date range.

Request Headers

Parameter	Type	Required	Description
Authorization	String	Yes	Bearer Token

Request Parameters

Parameter	Type	Required	Description
start	String	No	Start date (Y-m-d), defaults to the first day of the current month
end	String	No	End date (Y-m-d), defaults to today
filter	String	No	Exact search by downline username

Response Example

{
  "code": 0,
  "msg": "Success",
  "data": [
    {
      "username": "downline_user1",
      "turnover": "15000.000",
      "win": "14500.000",
      "winlose": "-500.000",
      "deposit": "1000.000",
      "withdraw": "0.000"
    }
  ]
}