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

## 一、通用说明

### 1.1 基础信息

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

### 1.2 统一响应格式

**成功：**

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

**失败：**

```json
{
  "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`：**

```json
{ "message": "Tier selected" }
```

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

---

### 2.3 升级今日任务档位

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

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

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

**成功时 `data`：**

```json
{ "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`：**

```json
{ "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 | 结算使用的系数 |

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

---

## 三、前端流程建议

1. **进入活动页**  
   调 `/superball/info`，用返回的 `yesterday`、`today`、`user_task`、`multiplier`、`lucky_numbers_7_days` 渲染页面。

2. **今日未选档**  
   展示档位列表（`tiers`），用户选择后调 `/superball/select-tier?tier=X`（建议二次确认）。

3. **今日任务进行中**  
   用 `user_task.recharge_progress/turnover_progress` 与 `recharge_required/turnover_required` 做进度条；若 `task_completed` 且 `can_upgrade`，可展示「升级档位」；若 `can_claim`，展示「领取奖励」按钮。

4. **领取今日奖励（领球）**  
   调 `/superball/claim-reward`，成功后根据返回的 `ball_count` 进入选号页。

5. **选号页**  
   可为每个球选 0-9，支持手动/随机，选满后调 `/superball/submit-numbers`，body 传 `numbers: [1,2,3,...]`。

6. **昨日奖金**  
   若 `yesterday.can_claim_yesterday === true`，展示「领取昨日奖金 ￥XX」（用 `pending_prize_display`）；用户点击后调 `/superball/claim-yesterday-reward`。

7. **金额展示**  
   接口中带 `_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 单位展示金额）。

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