# 世界杯接口说明

本文件记录 `src/api/worldCup.js` 中世界杯活动专用接口的参数、返回字段和页面对接注意事项。页面后续补比赛、竞猜、我的记录、排行榜模块时，先对照本文件和 `页面创建信息.md`。

## 1. 接口文件

- 文件：`src/api/worldCup.js`
- 公共前缀：`/activity/worldcup`
- 请求封装：`src/utils/http.js` 中的 `get`、`post`

## 2. POST 接口

### 2.1 比赛列表

- 方法名：`apiPostWorldCupMatchList(data)`
- 请求方式：`POST`
- 路径：`/activity/worldcup/match/list`
- 用途：分页获取比赛列表。

Body 参数：

```json
{
  "size": 0,
  "current": 0,
  "tab": 0
}
```

页面当前调用固定为：

```json
{
  "size": 10,
  "current": 1,
  "tab": 0
}
```

切换到 `Ended` 时仅把 `tab` 改为 `1`，暂不做上拉加载。

参数说明：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| size | 是 | 每页数量 |
| current | 是 | 当前页 |
| tab | 是 | `0` 进行中，可投注或比赛中；`1` 已结束 |

返回示例：

```json
{
  "records": [
    {
      "matchId": 0,
      "homeTeam": "string",
      "awayTeam": "string",
      "homeFlag": "string",
      "awayFlag": "string",
      "kickoffTime": 0,
      "status": 0,
      "result": 0,
      "totalPool": 0,
      "totalPoolFormat": "string",
      "homePoolFormat": "string",
      "drawPoolFormat": "string",
      "awayPoolFormat": "string",
      "homePercent": 0,
      "drawPercent": 0,
      "awayPercent": 0,
      "myHomeBetFormat": "string",
      "myDrawBetFormat": "string",
      "myAwayBetFormat": "string",
      "joinCount": 0,
      "joined": true,
      "myPayout": 0
    }
  ],
  "total": 0,
  "size": 0,
  "current": 0
}
```

字段说明：

| 字段 | 说明 |
| --- | --- |
| matchId | 比赛 ID |
| homeTeam / awayTeam | 主队 / 客队国家名称 |
| homeFlag / awayFlag | 主队 / 客队旗帜图片链接 |
| kickoffTime | 开赛时间戳，毫秒 |
| status | `0` 未开赛，`1` 比赛中，`2` 已结束 |
| result | `1` 主胜，`2` 平局，`3` 客胜，未结算为 `null` |
| totalPool | 总奖池 |
| totalPoolFormat | 总奖池格式化显示，例如 `123.12M` |
| homePoolFormat / drawPoolFormat / awayPoolFormat | 主胜 / 平局 / 客胜各选项奖池格式化显示，例如 `123.12M` |
| homePercent / drawPercent / awayPercent | 主胜 / 平局 / 客胜占比，百分比，保留 1 位 |
| myHomeBetFormat / myDrawBetFormat / myAwayBetFormat | 当前用户在主胜 / 平局 / 客胜各选项的累计下注额格式化显示，未下注为 `null` |
| joinCount | 参与人次 |
| joined | 当前用户是否已在本场投注 |
| myPayout | 当前用户本场赢得金额（中奖且已结算时有值，其余为null）. |

页面对接注意：

- `Predict Now` 和 `Ended` 底部总奖池入口优先展示 `totalPoolFormat`，没有格式化字段时回退 `totalPool`。
- `Ended` 列表三列押注项的上方金额展示 `homePoolFormat` / `drawPoolFormat` / `awayPoolFormat`。
- `Ended` 列表三列押注项的下方金额展示 `myHomeBetFormat` / `myDrawBetFormat` / `myAwayBetFormat`；字段不为 `null` 的选项视为当前用户已押注并展示选中态。

### 2.2 押注

- 方法名：`apiPostWorldCupBet(data)`
- 请求方式：`POST`
- 路径：`/activity/worldcup/bet`
- 用途：对指定比赛提交竞猜押注。

Body 参数：

```json
{
  "matchId": "0",
  "betOption": 0,
  "betAmount": 0
}
```

参数说明：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| matchId | 是 | 比赛 ID，必须使用字符串格式传参，避免大整数精度丢失 |
| betOption | 是 | 押注选项：`1` 主胜，`2` 平局，`3` 客胜 |
| betAmount | 是 | 押注金额：`100` / `1000` / `10000` / `100000` |

### 2.3 我的竞猜记录

- 方法名：`apiPostWorldCupMyBetList(data)`
- 请求方式：`POST`
- 路径：`/activity/worldcup/my/bet/list`
- 用途：分页获取我的竞猜记录。

Body 参数：

```json
{
  "size": 0,
  "current": 0,
  "matchId": "0"
}
```

参数说明：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| size | 是 | 每页数量 |
| current | 是 | 当前页 |
| matchId | 否 | 比赛 ID，为空查全部；有值时必须使用字符串格式传参，避免大整数精度丢失 |

返回示例：

```json
{
  "records": [
    {
      "betId": 0,
      "matchId": 0,
      "betOption": 0,
      "betOptionName": "string",
      "betAmount": 0,
      "betStatus": 0,
      "payout": 0,
      "betTime": 0
    }
  ],
  "total": 0,
  "size": 0,
  "current": 0
}
```

字段说明：

| 字段 | 说明 |
| --- | --- |
| betId | 竞猜记录 ID |
| matchId | 比赛 ID |
| betOption | 押注选项：`1` 主胜，`2` 平局，`3` 客胜 |
| betOptionName | 押注选项展示文案，队名或平局 |
| betAmount | 押注金额 |
| betStatus | `0` 待结算，`1` 中奖，`2` 未中奖 |
| payout | 派彩金额，中奖时展示 |
| betTime | 下注时间戳，毫秒 |

### 2.4 排行榜

- 方法名：`apiPostWorldCupRankList()`
- 请求方式：`POST`
- 路径：`/activity/worldcup/rank/list`
- Body 参数：无业务参数，POST 请求仍传空对象 `{}`
- 用途：获取世界杯活动排行榜和当前用户排名。
- 页面字段映射：
  - `rankingList` 对应页面排行榜列表，第四名以后才进入展开列表。
  - `currentUserRank` 对应贴底“我的排名”模块。
  - `quantity` 对应页面贡献值 `amount`。
  - 带 `user_id_prefix` 的展示 ID 取 `account`；打开用户资料使用 `userId`。
  - 昵称取 `nickname`，头像取 `avatar`，魅力等级取 `charmLevel`，财富等级取 `wealthLevel`，VIP 取 `vipLevelName`；`userLevel` 当前页面暂不使用。

返回示例：

```json
{
  "activityType": 0,
  "activityTypeName": "string",
  "cycleType": 0,
  "cycleTypeName": "string",
  "cycleKey": "string",
  "cycleDisplay": "string",
  "dimension": 0,
  "dimensionName": "string",
  "dimensionUnit": "string",
  "rankingList": [
    {
      "userId": 0,
      "encryptedId": "string",
      "account": "string",
      "specialAccount": "string",
      "nickname": "string",
      "avatar": "string",
      "userSex": 0,
      "userLevel": 0,
      "rank": 0,
      "quantity": "string",
      "quantityNumber": 0,
      "activityType": 0,
      "activityTypeName": "string",
      "cycleType": 0,
      "cycleTypeName": "string",
      "cycleKey": "string",
      "dimension": 0,
      "dimensionName": "string",
      "dimensionUnit": "string",
      "extData": "string",
      "age": 0,
      "wealthLevel": 0,
      "vipLevelName": "string",
      "isCurrentUser": true
    }
  ],
  "currentUserRank": {
    "userId": 0,
    "account": "string",
    "userSex": 0,
    "nickname": "string",
    "avatar": "string",
    "rank": 0,
    "quantity": "string",
    "quantityNumber": 0,
    "isRanked": true,
    "quantityToRank": 0,
    "rankChange": 0,
    "lastRank": 0,
    "age": 0,
    "wealthLevel": 0,
    "userLevel": 0,
    "vipLevelName": "string"
  },
  "totalParticipants": 0,
  "updateTime": "string"
}
```

字段说明：

| 字段 | 说明 |
| --- | --- |
| cycleDisplay | 周期显示文本，例如日榜 `2025-01-01`、周榜 `2025年第1周`、月榜 `2025年1月` |
| dimension / dimensionName / dimensionUnit | 排行统计维度编码、名称、单位 |
| rankingList | 排行榜 TOP N 列表 |
| currentUserRank | 当前用户排名，`rank=0` 表示未上榜 |
| quantity / quantityNumber | 统计数值展示文本 / 数值 |
| quantityToRank | 距离上榜还需要的数值，仅未上榜时有值 |
| rankChange | 排名变化，正数上升，负数下降，0 不变 |
| totalParticipants | 参与总人数 |
| updateTime | 榜单更新时间 |

页面对接注意：

- 排行榜用户头像、昵称、VIP、魅力等级、财富等级按 `apiPostWorldCupRankList` 当前返回字段映射。
- 页面贡献值别名 `amount` 使用 `quantity`，`quantityNumber` 原样保留备用。
- `encryptedId` 可用于隐身用户和 `currentUserRank` 匹配。

## 3. GET 接口

### 3.1 比赛详情

- 方法名：`apiGetWorldCupMatchDetail(matchId)`
- 请求方式：`GET`
- 路径：`/activity/worldcup/match/detail`
- Query 参数：`matchId` 必填
- 用途：获取比赛详情和当前用户本场竞猜记录。

返回示例：

```json
{
  "match": {
    "matchId": 0,
    "homeTeam": "string",
    "awayTeam": "string",
    "homeFlag": "string",
    "awayFlag": "string",
    "kickoffTime": 0,
    "status": 0,
    "result": 0,
    "totalPool": 0,
    "totalPoolFormat": "string",
    "homePoolFormat": "string",
    "drawPoolFormat": "string",
    "awayPoolFormat": "string",
    "homePercent": 0,
    "drawPercent": 0,
    "awayPercent": 0,
    "myHomeBetFormat": "string",
    "myDrawBetFormat": "string",
    "myAwayBetFormat": "string",
    "joinCount": 0,
    "joined": true
  },
  "homePool": 0,
  "drawPool": 0,
  "awayPool": 0,
  "myBets": [
    {
      "betId": 0,
      "matchId": 0,
      "betOption": 0,
      "betOptionName": "string",
      "betAmount": 0,
      "betStatus": 0,
      "payout": 0,
      "betTime": 0
    }
  ]
}
```

字段说明：

| 字段 | 说明 |
| --- | --- |
| match | 比赛基础信息，字段同比赛列表 |
| match.totalPoolFormat | 总奖池格式化显示，例如 `123.12M` |
| match.homePoolFormat / match.drawPoolFormat / match.awayPoolFormat | 主胜 / 平局 / 客胜各选项奖池格式化显示 |
| match.myHomeBetFormat / match.myDrawBetFormat / match.myAwayBetFormat | 当前用户在主胜 / 平局 / 客胜各选项的累计下注额格式化显示，未下注为 `null` |
| homePool / drawPool / awayPool | 主胜 / 平局 / 客胜奖池明细 |
| myBets | 我的本场竞猜列表，字段同我的竞猜记录 |
