代理返佣接口

agent_rebate

代理返佣活动的 list / detail / claim 走通用活动接口（kind=agent_rebate，详见 活动接口）。系统按商户时区每日 T+1 结算，产生一条 Claim 行；玩家可一次性领取所有未过期 pending 流水。本章除补充 detail / claim 字段外，另新增「我的团队」接口用于展示下级当日打码与今日预估佣金。

---

活动详情字段

通用接口 GET /promotion/agent_rebate/detail 的 data 字段：

字段	类型	说明
description	string	活动说明
mode	string	返佣模式：direct 仅直属 / three_level 三级代理 / unlimited 无限级极差
tiers	list<Tier>	当前模式的档位列表，结构随 mode 变化（见下方）
tier_index	number	最近一次结算日命中的档位下标，未结算过为 -1
claimable_amount	number	当前可领总额（所有未过期 pending 流水之和，保留 2 位）
pending_days	number	当前未过期 pending 流水的条数（按结算日计数）
min_claim_amount	number	最低领取门槛
bet_multiple	number	领取后入账金额对应的打码倍数
expire_days	number	pending 流水保留天数，0 表示永不过期
last_claim_at	string	上次领取时间（RFC3339），从未领取为空串
today	object	今日实时预估（见下方 Today 对象）
days	list<Day>	最近 30 条结算流水（按 day 倒序）

Tier 当 mode=direct / mode=unlimited 时（RateTier）：

字段	类型	说明
threshold	number	当日计佣基数门槛（≥ 该值进入该档）
rate_percent	number	佣金比例 %

Tier 当 mode=three_level 时（LevelTier）：

字段	类型	说明
threshold	number	当日计佣基数门槛
l1_percent	number	直属（L1）下级返佣比例 %
l2_percent	number	L2 下级返佣比例 %
l3_percent	number	L3 下级返佣比例 %

Today 字段：

字段	类型	说明
day	string	商户本地日期 YYYY-MM-DD
is_today	bool	恒为 true
basis_total	number	今日截至当前的计佣基数
estimate_amount	number	今日截至当前的预估佣金（随下级打码持续变化）
tier_index	number	按今日基数实时定档的档位下标
rate_percent	number	当前档位自身比例 %（three_level 模式恒为 0，分层比例见 tiers）

Day 字段：

字段	类型	说明
day	string	结算日 YYYY-MM-DD（商户本地时区）
basis_total	number	该日计佣基数
amount	number	该日返佣金额
expire_at	string	过期时间（RFC3339），expire_days=0 时为空串
status	string	pending 待领取 / claimed 已领取 / expired 已过期（响应中按当前时间判定）

未登录或会员不存在时，动态字段（tier_index / claimable_amount / pending_days / last_claim_at / today / days）为零值或空数组。

---

领取

通用接口 POST /promotion/agent_rebate/claim。一次领取所有未过期的 pending 流水，在同一事务内按各结算日分别入账，响应返回汇总金额；后端防止重复领取。命中条件：存在至少一条未过期 pending + 合计金额 ≥ min_claim_amount。

双钱包版本中，每条返佣按该结算记录固化的倍数处理：有码计入奖金余额 bonus_money 并分别建立任务，无码计入现金余额 user_money；任务的 can_abandon 取领取时的活动配置并固化。提现须满足 全部任务与旧打码门槛，不能仅凭本次返佣任务完成判断。

输入: {}

输出:

字段	类型	说明
amount	number	本次入账金额（保留 2 位）
days	number	本次领取覆盖的结算日数（即本次结算的 pending 流水条数）
bet_multiple	number	当前活动配置倍数，兼容展示字段；各结算日实际按自身记录的倍数生成任务，不能用本字段乘汇总 amount 推算新增要求，须查看 任务列表

---

我的团队

返回当前玩家代理子树下，当日有打码的下级明细 + 今日预估佣金摘要。需要登录且活动已启用。下级层级按 mode 截断：direct 仅 L1、three_level L1~L3、unlimited 全部子树。结果服务端 60 秒缓存。

URL: GET /agent_rebate/team

Query:

字段	类型	必填	说明
page	number	否	页码，默认 1
size	number	否	每页条数，默认 20，范围 1~100
username	string	否	按下级用户名模糊筛选（不区分大小写），命中后 betting_count 为筛选后的总条数

输出:

字段	类型	说明
data.today	object	今日预估摘要，同 活动详情 的 Today 对象
data.team	object	团队下级分页数据

data.team 字段：

字段	类型	说明
team_count	number	计佣层级内的下级总数（含当日无打码者）
betting_count	number	当日有打码的下级数（即 items 总条数，未受分页影响；传 username 时为筛选后的条数）
page	number	当前页码
size	number	每页条数
items	list<TeamItem>	当前页下级明细，按 valid_bet 倒序

TeamItem 字段：

字段	类型	说明
member_id	string	下级会员 ID
username	string	下级会员用户名
level	number	下级在代理链中的层级（直属为 1）
valid_bet	number	该下级今日有效打码
rebate_amount	number	该下级今日打码贡献给当前玩家的预估返佣

---

代理数据看板

一次性返回当前会员的时段维度新下属统计（new_downline，受 range 影响）与历史累计统计（overall，与 range 无关）。需登录。未启用 agent_rebate 活动时，commission_* 字段全部为 0，但下属计数仍会返回。

URL: GET /agent_rebate/agent_stats

Query:

字段	类型	必填	说明
range	string	是	时段筛选枚举，取值见下表

range 枚举（商户时区下的日历区间）：

取值	语义
today	今日 00:00 起到明日 00:00
yesterday	昨日 00:00 起到今日 00:00
this_week	本周一 00:00 起 7 天（周起点固定为周一）
last_week	上周一 00:00 起 7 天
this_month	本月 1 日 00:00 起到下月 1 日 00:00
last_month	上月 1 日 00:00 起到本月 1 日 00:00

输出:

字段	类型	说明
data.range	string	回显请求的 range
data.start_at	string	时段起点（UTC，RFC3339 格式）
data.end_at	string	时段终点（UTC，RFC3339，半开区间 [start_at, end_at)）
data.new_downline	object	时段内新下属统计，见 NewDownline
data.overall	object	历史累计统计（与 range 无关），见 Overall

响应示例:

{
    "code": 0,
    "message": "",
    "data": {
        "range": "today",
        "start_at": "2026-06-30T16:00:00Z",
        "end_at": "2026-07-01T16:00:00Z",
        "new_downline": {
            "direct_count": 5,
            "other_count": 12,
            "direct_commission": "123.45",
            "other_commission": "67.89"
        },
        "overall": {
            "direct_count": 50,
            "other_count": 200,
            "direct_valid_bet": "12345.67",
            "commission_claimed": "1000.00",
            "commission_pending": "300.00",
            "direct_commission": "800.00",
            "other_commission": "500.00",
            "total_commission": "1300.00"
        }
    }
}

NewDownline 字段（时段内统计，受 range 约束）：

字段	类型	说明
direct_count	number	时段内新注册且 inviter_id = 当前会员 的下属数
other_count	number	时段内新注册、位于当前会员整棵下线子树中、但 inviter_id != 当前会员（通过直属间接加入）
direct_commission	string	时段内产生的所有代理返佣 claim 中，basis_levels[] 里 level=1（直属贡献）的 amount 累加，decimal 字符串（2 位小数）
other_commission	string	同上，但取 level>=2（间接下属贡献）的 amount 累加

Overall 字段（历史累计，与 range 无关）：

字段	类型	说明
direct_count	number	历史累计直属下线数（inviter_id = 当前会员）
other_count	number	历史累计间接下线数（整棵子树数减去直属数）
direct_valid_bet	string	直推下线在游戏行为聚合表 a_stats_member_all_30m 中的历史 valid_bet_amount 累加（"有效投注"即已排除对冲注/无效注/平局的名义下注）
commission_claimed	string	SUM(claim.amount) WHERE status='claimed'
commission_pending	string	SUM(claim.amount) WHERE status='pending' AND (expire_at IS NULL OR expire_at > NOW())，过期的 pending 不计入 pending
direct_commission	string	全部 claim（不限 status，含 pending / claimed / 已过期）的 basis_levels[] 里 level=1 部分 amount 累加
other_commission	string	全部 claim 的 basis_levels[] 里 level>=2 部分 amount 累加
total_commission	string	全部 claim.amount 累加，即 direct_commission + other_commission

错误响应:

message	触发场景
请先登录	未登录（缺少或无效的 JWT）
非法的时间段类型: <值>	range 缺失或不在枚举中
无效的会员 ID	极少发生，登录态下的会员 ID 不能解析为整数

时区说明:

• 服务端按商户时区（merchant.time_zone）解析 range，例如 today 表示商户所在时区当天 00:00~次日 00:00
• 响应中 start_at / end_at 已经转成 UTC 并使用 RFC3339 格式，前端如需按用户本地时区展示，请自行做 new Date(start_at).toLocaleString() 类似转换
• 区间语义为半开区间 [start_at, end_at)，即 end_at 那一刻的数据不属于本时段
• 商户时区口径与代理返佣 T+1 结算写入 claim.day 的口径一致，保证时段内佣金汇总不会因时区跨越出现偏差