Superball 活跃活动 - 前端接口文档

一、通用说明

1.1 基础信息

接口前缀：与现有 Game 接口一致（需带登录态）
请求方式：支持 GET / POST（均可，建议 POST 传参）
鉴权：所有接口需在「已登录」状态下调用（checkGameLogin + mustGameLogin）

1.2 统一响应格式

成功：

{
  "data": { /* 业务数据 */ },
  "result": "",
  "msg": "success",
  "code": 200
}

失败：

{
  "data": [],
  "msg": "错误信息或多语言 key",
  "code": 301
}

业务数据在 data 中，前端以 res.data 取用。
code !== 200 时按失败处理，msg 可做提示或走多语言。

二、接口列表

2.1 获取活动完整信息

用途：进入活动页时调用，拿到昨日数据、今日数据、档位配置、当前任务进度、系数、近 7 天幸运号等，用于整页展示与按钮状态。

项目	说明
路径	`/superball/info`
方法	GET / POST
请求参数	无（用户身份从登录态取）

成功时 data 结构：

字段	类型	说明
yesterday	object	昨日相关数据
yesterday.pool_amount	number	昨日奖池（内部单位，一般用 display）
yesterday.pool_amount_display	number	昨日奖池展示金额
yesterday.base_reward_per_ball	number	昨日每球基础奖励（内部单位）
yesterday.base_reward_per_ball_display	number	昨日每球基础奖励展示金额
yesterday.lucky_number	number	昨日幸运号码（0-9）
yesterday.completed_count	number	昨日完成人数
yesterday.total_balls	number	昨日总奖励球数
yesterday.my_balls	array	昨日我拥有的球（原始对象列表）
yesterday.my_balls_with_lucky	array	昨日我的球及是否中幸运号，项：`{ number, is_lucky }`
yesterday.my_prize	number	昨日已领奖金（内部单位），未领为 0
yesterday.my_prize_display	number	昨日已领奖金展示金额
yesterday.my_multiplier	number	昨日结算时使用的奖励系数
yesterday.can_claim_yesterday	boolean	是否可以领取昨日奖金（次日领一次）
yesterday.pending_prize	number	待领取昨日奖金（内部单位），仅 can_claim_yesterday 为 true 时有意义
yesterday.pending_prize_display	number	待领取昨日奖金展示金额
today	object	今日实时数据
today.pool_amount	number	今日奖池（内部单位）
today.pool_amount_display	number	今日奖池展示金额
today.completed_count	number	今日已完成人数
today.total_balls	number	今日当前总奖励球数
today.base_reward_per_ball	number	今日当前每球基础奖励（内部单位）
today.base_reward_per_ball_display	number	今日当前每球基础奖励展示金额
today.my_balls	array	今日我选的球及号码，项：`{ ball_index, number }`；未选号为空数组 `[]`
today.number_counts	object	每个号码被选的次数，如 `{"3": 2, "7": 1}` 表示 3 选了 2 次、7 选了 1 次；未选号为空对象 `{}`
tiers	array	档位配置列表
tiers[].tier	string	档位：A / B / C / D / E
tiers[].recharge_required	number	该档充值要求（金额）
tiers[].turnover_required	number	该档流水要求（金额）
tiers[].ball_count	number	该档奖励球数
user_task	object \| null	今日任务，未选档则为 null
user_task.tier	string	当前档位
user_task.recharge_required	number	当前档充值要求
user_task.turnover_required	number	当前档流水要求
user_task.recharge_progress	number	当日已达成充值金额（仅统计当天）
user_task.turnover_progress	number	当日已达成流水金额（仅统计当天，非累计）
user_task.task_completed	boolean	今日任务是否已完成（充值+流水都达标）
user_task.status	number	0=未领球，1=已领球
user_task.can_claim	boolean	是否可领取今日奖励（领球）
user_task.can_upgrade	boolean	是否可升级到更高档位
user_task.ball_count	number	当前档可获得球数
multiplier	object	当前用户系数相关
multiplier.value	number	当前奖励系数（1~3）
multiplier.consecutive_days	number	连续完成任务天数
multiplier.min	number	系数下限（常量 1）
multiplier.max	number	系数上限（常量 3）
multiplier.step	number	系数步长（常量 0.5）
lucky_reward_per_ball	number	每个中奖球对应的幸运号奖励金额（展示单位，常量 10）；选号可重复，多个球选同一号码则按球数累加
lucky_numbers_7_days	array	近 7 天幸运号码，项：`{ date, lucky_number }`

2.2 选择今日任务档位

用途：用户选择今日要做的档位（A/B/C/D/E），选后不可改，只能升级到更高档。建议前端做二次确认弹窗。

项目	说明
路径	`/superball/select-tier`
方法	GET / POST
请求参数	tier（必填）

参数名	类型	必填	说明
tier	string	是	档位：A / B / C / D / E（大小写均可）

成功时 data：

{ "message": "Tier selected" }

常见失败： 今日已选过档、档位不合法等，msg 会返回错误说明。

2.3 升级今日任务档位

用途：今日任务已完成且当前不是 A 档时，可升级到更高档（如 D→C），进度保留，需满足新档的充值和流水要求。

项目	说明
路径	`/superball/upgrade-tier`
方法	GET / POST
请求参数	tier（必填）

参数名	类型	必填	说明
tier	string	是	目标档位：A / B / C / D / E

成功时 data：

{ "message": "Tier upgraded" }

常见失败： 未完成任务、目标档不高于当前档、进度不足等。

2.4 领取今日任务奖励（领球）

用途：今日任务（充值+流水）达标且未领过时，调用后获得对应档位的「球」，之后需去选号。会更新奖池统计和用户系数。

项目	说明
路径	`/superball/claim-reward`
方法	GET / POST
请求参数	无

成功时 data：

字段	类型	说明
ball_count	number	本次获得的球数
message	string	提示文案（如：领取成功，请为球选号）

常见失败： 未完成任务、今日已领过等。

2.5 提交球的选号

用途：用户为今日领到的每个球选择号码（0-9），可重复。全部选完并确认后调用，提交后不可改。

项目	说明
路径	`/superball/submit-numbers`
方法	GET / POST
请求参数	numbers（必填）

参数名	类型	必填	说明
numbers	array	是	每个球的号码，顺序对应球序号，如 `[3, 7, 3, 9, 0]`，长度须等于今日获得的球数

成功时 data：

{ "message": "Numbers submitted" }

常见失败： 数量与球数不一致、今日已提交过、号码非 0-9 等。

2.6 查询我的球及选号

用途：选号页或结果页查看某天「我的球」及已选号码。

项目	说明
路径	`/superball/my-balls`
方法	GET / POST
请求参数	date（可选）

参数名	类型	必填	说明
date	string	否	日期，格式 `YYYY-MM-DD`，不传默认当天

成功时 data：

字段	类型	说明
balls	array	球列表，项：`{ ball_index, number }`，ball_index 从 1 开始

2.7 近 7 天幸运号码

用途：展示最近 7 天的幸运号码（0-9），用于说明与展示。

项目	说明
路径	`/superball/lucky-numbers`
方法	GET / POST
请求参数	无

成功时 data：

字段	类型	说明
lucky_numbers	array	项：`{ date, lucky_number }`，date 为 `YYYY-MM-DD`

2.8 领取昨日奖金

用途：次日用户主动领取「昨日」的奖金。昨日有选号球且未领过时，info 里 yesterday.can_claim_yesterday 为 true，并给出 pending_prize_display；用户点击「领取昨日奖金」后调此接口，金额入账，仅可领一次。

项目	说明
路径	`/superball/claim-yesterday-reward`
方法	GET / POST
请求参数	无

成功时 data：

字段	类型	说明
total_amount	number	本次发放总金额（内部单位）
total_amount_display	number	本次发放总金额展示用
base_amount	number	其中基础奖励部分（内部单位）
lucky_amount	number	其中幸运号奖励部分（内部单位）
multiplier	number	结算使用的系数

常见失败： 昨日已领过、昨日无球可领、奖池未就绪等。

三、前端流程建议

进入活动页
调 /superball/info，用返回的 yesterday、today、user_task、multiplier、lucky_numbers_7_days 渲染页面。
今日未选档
展示档位列表（tiers），用户选择后调 /superball/select-tier?tier=X（建议二次确认）。
今日任务进行中
用 user_task.recharge_progress/turnover_progress 与 recharge_required/turnover_required 做进度条；若 task_completed 且 can_upgrade，可展示「升级档位」；若 can_claim，展示「领取奖励」按钮。
领取今日奖励（领球）
调 /superball/claim-reward，成功后根据返回的 ball_count 进入选号页。
选号页
可为每个球选 0-9，支持手动/随机，选满后调 /superball/submit-numbers，body 传 numbers: [1,2,3,...]。
昨日奖金
若 yesterday.can_claim_yesterday === true，展示「领取昨日奖金￥XX」（用 pending_prize_display）；用户点击后调 /superball/claim-yesterday-reward。
金额展示
接口中带 _display 的字段为前端展示用金额；未带 display 的为内部单位，一般仅做兼容或特殊逻辑使用。

四、档位与规则速查

档位	充值要求	流水要求	奖励球数
A	500	2000	30
B	200	1000	10
C	100	500	5
D	50	200	2
E	29	100	1

奖励系数：初始 1，连续完成 +0.5/天（上限 3），间隔 1 天未完成 -0.5（下限 1）。
昨日奖金：次日由用户主动领取，不自动发放；金额 = 基础奖励 × 系数 + 幸运号奖励（每中一球 10 单位展示金额）。

文档版本：基于当前后端实现整理，如有新增字段或约定以实际接口为准。

Superball_Activity_API.md 11 KB Постоянная ссылка История Исходник

Superball 活跃活动 - 前端接口文档

一、通用说明

1.1 基础信息

1.2 统一响应格式

二、接口列表

2.1 获取活动完整信息

2.2 选择今日任务档位

2.3 升级今日任务档位

2.4 领取今日任务奖励（领球）

2.5 提交球的选号

2.6 查询我的球及选号

2.7 近 7 天幸运号码

2.8 领取昨日奖金

三、前端流程建议

四、档位与规则速查

Superball_Activity_API.md 11 KB

Постоянная ссылка История Исходник