推荐返利 (Referral)

概述

• 接口说明：获取当前玩家的下级代理（裂变）树状结构，并查询下级玩家在指定时间段内的游戏与财务报表（注单流水、输赢、充提）。

底层业务逻辑与说明 (Business Logic)

TIP

推荐返利报表的查询逻辑涉及树状结构遍历和海量数据统计，底层通过以下机制实现高性能与高精度：

1. 深度控制 (Max Depth)：获取下级树状图时，系统会读取后台配置的 player_generation（最大代数上限），递归查询至指定代数即停止，防止代理层级过深导致内存溢出。
2. 读写分离与 ES 聚合查询：对于下级玩家的注单流水、输赢等日结数据，不再直连 MySQL 查询，而是将所有下级玩家的 ID 提取后，通过 Elasticsearch (wg_player_daily_stats) 进行批量聚合计算，极大提升了报表拉取速度。
3. 精度复原 (Divisor Scaling)：与 Finance 个人报表类似，ES 中存储的财务数据均放大了 100000 倍以避免浮点数丢失。接口在汇总计算后，统一通过 bcdiv(value, '100000', 3) 还原为真实金额返回给前端。

---

1. GET - 获取下级树状图

• 路径: /api/promotions/referrals/tree
• 说明: 递归获取当前用户的所有下线用户。

请求 Header

参数名	类型	必填	说明
Authorization	String	是	Bearer Token

响应示例

{
  "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 - 获取下级流水与财务报表

• 路径: /api/promotions/referrals/report
• 说明: 根据日期范围，聚合查询下线用户带来的投注流水与充提表现。

请求 Header

参数名	类型	必填	说明
Authorization	String	是	Bearer Token

请求参数

参数名	类型	必填	说明
start	String	否	开始日期 (Y-m-d)，默认本月第一天
end	String	否	结束日期 (Y-m-d)，默认今天
filter	String	否	精确搜索某个下级代理的用户名

响应示例

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