# 流水抽奖接口文档（Cocos 客户端对接）

## 一、功能说明

玩家**无需额外付费**，仅凭当日已发生的游戏下注流水自动累计抽奖资格。

核心规则：

| 规则 | 说明 |
|------|------|
| 流水来源 | 仅统计游戏消费流水，**排除** Roll 房、商城消费、福利类 |
| 兑换比例 | 每个宝箱可单独配置流水门槛（默认 3000 流水 = 1 次） |
| 过期机制 | 按自然日统计，次日零点自动清零，不累积 |
| 抽奖消耗 | **只消耗"今日流水额度"，不扣余额、不扣积分** |
| 中奖发放 | 饰品直接进背包（`tt_box_records.source = 14`） |
| 余额变动 | 只有玩家在背包**分解**该饰品时才产生余额/积分变动（`source = 63` 流水抽奖奖励） |
| 同时开启 | 全站同一时间只有一个抽奖活动为开启状态 |

参与统计的流水来源码（`TtAccountRecordSource.getTurnoverLotteryCodes()`）：

| source | 含义 |
|--------|------|
| 2 | 经典开箱消费 |
| 4 | 对战消费 |
| 40 | 幸运升级消费 |
| 38 | 疯狂转盘消费 |
| 60 | 奥林匹斯消费 |

---

## 二、通用约定

- **Base URL**：`{host}/api/turnoverLottery`
- **请求方式**：全部为 `POST`
- **Content-Type**：`application/json`
- **鉴权**：需登录态，请求头携带 token。`userId` 由后端从 token 解析，**客户端不要传 userId**

### 统一响应结构

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}
```

| code | 含义 |
|------|------|
| 200 | 成功 |
| 500 | 业务失败，提示语见 `msg` |
| 701 | 未实名认证，客户端统一弹实名认证窗口 |

> 客户端判定成功请以 `code === 200` 为准；失败时直接向玩家展示 `msg`。

---

## 三、接口清单

| # | 接口 | 路径 | 用途 |
|---|------|------|------|
| 1 | 获取抽奖信息 | `POST /api/turnoverLottery/myStats` | 进入抽奖页拉取流水、次数、宝箱与奖品 |
| 2 | 执行抽奖 | `POST /api/turnoverLottery/draw` | 点击抽奖，返回中奖结果供播放动画 |
| 3 | 我的抽奖记录 | `POST /api/turnoverLottery/myRecords` | 展示玩家历史中奖记录 |
| 4 | 全服中奖记录 | `POST /api/turnoverLottery/globalRecords` | 展示全服玩家中奖公示（跑马灯/滚动列表） |

---

## 四、接口详情

### 1. 获取抽奖信息

**`POST /api/turnoverLottery/myStats`**

进入抽奖页时调用，一次性返回玩家流水统计 + 所有开启中的抽奖宝箱及其奖品。

#### 请求参数

无需参数，body 可不传（或传空对象 `{}`）。

#### 响应示例

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "totalTurnover": 12000.00,
    "usedTurnover": 3000.00,
    "availableTurnover": 9000.00,
    "lotteryList": [
      {
        "id": 1,
        "lotteryName": "每日流水抽奖",
        "status": 1,
        "turnoverThreshold": 3000,
        "sort": 0,
        "lotteryChances": 3,
        "totalValue": 8250.00,
        "prizes": [
          {
            "id": 6,
            "ornamentName": "M9 刺刀 | 渐变之色",
            "price": 8200.00,
            "imageUrl": "/profile/upload/2026/08/08/xxx.png",
            "ornamentLevel": 3,
            "exteriorName": "略有磨损",
            "levelImg": "/profile/upload/level/red.png",
            "displayCount": 10,
            "displayPercent": "50.00%",
            "realCount": 5,
            "realPercent": "45.45%",
            "sort": 0
          }
        ]
      }
    ]
  }
}
```

#### 字段说明

**顶层字段**

| 字段 | 类型 | 说明 |
|------|------|------|
| `totalTurnover` | Decimal | 今日累计有效流水总额 |
| `usedTurnover` | Decimal | 今日已消耗的流水（抽奖已用掉的部分） |
| `availableTurnover` | Decimal | **当前可用流水** = `totalTurnover - usedTurnover`，不会为负 |
| `lotteryList` | Array | 开启中的抽奖宝箱列表，按 `sort` 升序 |

**`lotteryList[]` 宝箱字段**

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | Long | 宝箱 ID，抽奖时作为 `lotteryId` 传入 |
| `lotteryName` | String | 宝箱名称 |
| `status` | Int | 状态，始终为 1（接口只返回开启中的） |
| `turnoverThreshold` | Int | 该宝箱的流水门槛（多少流水抽 1 次） |
| `sort` | Int | 展示排序，越小越靠前 |
| `lotteryChances` | Int | **该宝箱可抽次数** = `availableTurnover ÷ turnoverThreshold` 向下取整 |
| `totalValue` | Decimal | 奖池总价值（按初始真实数量 × 单价累加） |
| `prizes` | Array | 奖品列表，按 `sort` 升序 |

**`prizes[]` 奖品字段**

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | Long | 奖品 ID |
| `ornamentName` | String | 饰品名称 |
| `price` | Decimal | 饰品价值 |
| `imageUrl` | String | 饰品图片 |
| `ornamentLevel` | Int | 品质等级 ID |
| `exteriorName` | String | 磨损度（崭新出厂/略有磨损/久经沙场/破损不堪/战痕累累/无涂装），可能为 `null` |
| `levelImg` | String | 品质底图，可用于饰品卡片背景 |
| `displayCount` | Int | 展示数量 |
| `displayPercent` | String | **展示爆率**，如 `"50.00%"`，用于前端展示给玩家 |
| `realCount` | Int | 当前剩余库存 |
| `realPercent` | String | 真实爆率（内部数据，**不建议展示给玩家**） |
| `sort` | Int | 展示排序 |

> **图片路径处理**：`imageUrl` / `levelImg` 若以 `/` 开头（且非 `//`），是服务器相对路径，需拼接资源域名前缀；否则为完整 URL 直接使用。

> **展示建议**：转盘/宝箱格子的爆率请使用 `displayPercent`，`realPercent` 是后台真实概率，不要展示。

---

### 2. 执行抽奖

**`POST /api/turnoverLottery/draw`**

玩家点击抽奖时调用。**建议点击立即请求接口，拿到结果后再播放动画**——饰品在接口返回成功时已经入背包，动画只是表现层，即使动画中途活动被关闭也不影响已发的奖。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `lotteryId` | Long | 是 | 宝箱 ID，取 `myStats` 返回的 `lotteryList[].id` |

```json
{
  "lotteryId": 1
}
```

#### 成功响应

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "prizeId": 6,
    "ornamentName": "M9 刺刀 | 渐变之色",
    "price": 8200.00,
    "imageUrl": "/profile/upload/2026/08/08/xxx.png",
    "ornamentLevel": 3,
    "exteriorName": "略有磨损",
    "lotteryName": "每日流水抽奖",
    "costTurnover": 3000,
    "msg": "抽奖成功！获得: M9 刺刀 | 渐变之色"
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `prizeId` | Long | 中奖奖品 ID，可与 `myStats` 的 `prizes[].id` 对应，用于定位动画停留格子 |
| `ornamentName` | String | 中奖饰品名称 |
| `price` | Decimal | 饰品价值 |
| `imageUrl` | String | 饰品图片 |
| `ornamentLevel` | Int | 品质等级 ID |
| `exteriorName` | String | 磨损度，可能为 `null` |
| `lotteryName` | String | 宝箱名称 |
| `costTurnover` | Int | 本次消耗的流水值 |
| `msg` | String | 中奖文案，可直接展示 |

#### 失败响应（`code = 500`，提示语在外层 `msg`）

| msg | 触发场景 | 客户端处理建议 |
|-----|----------|----------------|
| `抽奖活动不存在或未开启` | 活动被后台关闭或已删除 | 提示后刷新 `myStats` |
| `抽奖次数不足` | 可用流水不够一次门槛 | 提示玩家去游戏累计流水 |
| `奖品配置为空` | 该宝箱未配置奖品 | 提示"活动准备中" |
| `奖品库存不足` | 全部奖品初始数量为 0 | 提示"活动准备中" |
| `抽奖流水门槛配置错误，请联系管理员` | 门槛配置为 0 或负数 | 提示联系客服 |
| `抽奖处理中，请勿重复操作` | 同一用户并发点击被锁拦截 | **禁用按钮防连点**，稍后可重试 |
| `抽奖处理中，请稍后再试` | 同一宝箱有其他玩家正在抽 | 短暂延迟后自动重试一次 |
| `系统繁忙，请稍后重试` | 服务端异常（事务已回滚，未扣流水未发奖） | 提示重试 |

> **重要**：抽奖接口已加**双层 Redis 分布式锁**（用户级 + 宝箱级），客户端仍需在按钮上做防连点，避免频繁触发"抽奖处理中"。

#### 抽奖成功后的处理

1. 用 `prizeId` 定位动画停留位置并播放中奖动画
2. 动画结束后重新调用 `myStats` 刷新可用流水与剩余次数
3. 饰品已在背包，如需"立即分解"走通用背包分解接口 `/api/userPackSack/decompose`，分解产生的余额/积分变动来源为 `63 流水抽奖奖励`

---

### 3. 我的抽奖记录

**`POST /api/turnoverLottery/myRecords`**

分页查询当前登录玩家的历史中奖记录，按抽奖时间倒序。

#### 请求参数

| 参数 | 类型 | 必填 | 默认 | 说明 |
|------|------|------|------|------|
| `lotteryId` | Long | 否 | 全部 | 按宝箱筛选，不传查全部 |
| `pageNum` | Int | 否 | 1 | 页码，从 1 开始 |
| `pageSize` | Int | 否 | 10 | 每页条数，**最大 100** |

```json
{
  "pageNum": 1,
  "pageSize": 20
}
```

#### 响应示例

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total": 35,
    "pageNum": 1,
    "pageSize": 20,
    "rows": [
      {
        "id": 128,
        "userId": 688660,
        "lotteryId": 1,
        "prizeId": 6,
        "ornamentId": null,
        "ornamentName": "M9 刺刀 | 渐变之色",
        "imageUrl": "/profile/upload/2026/08/08/xxx.png",
        "ornamentsPrice": 8200.00,
        "costTurnover": 3000,
        "createTime": "2026-08-08 17:18:37"
      }
    ]
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `total` | Long | 总记录数，用于分页组件 |
| `pageNum` | Int | 当前页码 |
| `pageSize` | Int | 每页条数 |
| `rows` | Array | 记录列表 |
| `rows[].id` | Long | 记录 ID |
| `rows[].lotteryId` | Long | 宝箱 ID |
| `rows[].prizeId` | Long | 奖品 ID |
| `rows[].ornamentName` | String | 饰品名称 |
| `rows[].imageUrl` | String | 饰品图片 |
| `rows[].ornamentsPrice` | Decimal | 奖品价值 |
| `rows[].costTurnover` | Int | 该次消耗的流水值 |
| `rows[].createTime` | String | 抽奖时间 `yyyy-MM-dd HH:mm:ss` |

失败时返回 `code = 500`，`msg` 为 `查询失败，请稍后重试`。

---

### 4. 全服中奖记录

**`POST /api/turnoverLottery/globalRecords`**

分页查询**全服所有玩家**的中奖记录，按中奖时间倒序。用于抽奖页的中奖公示区（跑马灯、滚动榜单）。

> **已在服务端过滤**：机器人（`user_type='03'`）、白号（`is_blank_account=1`）、封禁用户（`status='1'`）、已删除用户（`del_flag!='0'`）的记录不会出现在结果里，客户端无需再做过滤。

#### 请求参数

| 参数 | 类型 | 必填 | 默认 | 说明 |
|------|------|------|------|------|
| `lotteryId` | Long | 否 | 全部 | 按宝箱筛选，不传查全部宝箱 |
| `minPrice` | Decimal | 否 | 不限 | 最低奖品价值门槛，只展示价值 ≥ 该值的记录（做"大奖公示"时用） |
| `pageNum` | Int | 否 | 1 | 页码，从 1 开始 |
| `pageSize` | Int | 否 | 20 | 每页条数，**最大 100** |

```json
{
  "minPrice": 1000,
  "pageNum": 1,
  "pageSize": 20
}
```

#### 响应示例

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total": 1286,
    "pageNum": 1,
    "pageSize": 20,
    "rows": [
      {
        "id": 128,
        "userId": 688660,
        "nickName": "云深不知",
        "avatar": "/profile/avatar/2026/08/08/aaa.png",
        "lotteryId": 1,
        "lotteryName": "每日流水抽奖",
        "prizeId": 6,
        "ornamentName": "M9 刺刀 | 渐变之色",
        "imageUrl": "/profile/upload/2026/08/08/xxx.png",
        "ornamentsPrice": 8200.00,
        "ornamentLevel": 3,
        "levelImg": "/profile/upload/level/red.png",
        "exteriorName": "略有磨损",
        "createTime": "2026-08-08 17:18:37"
      }
    ]
  }
}
```

#### 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `total` | Long | 总记录数 |
| `pageNum` | Int | 当前页码 |
| `pageSize` | Int | 每页条数 |
| `rows` | Array | 记录列表，按中奖时间倒序 |
| `rows[].id` | Long | 记录 ID |
| `rows[].userId` | Int | 中奖用户 ID |
| `rows[].nickName` | String | **中奖用户昵称**，用于公示展示 |
| `rows[].avatar` | String | **中奖用户头像** |
| `rows[].lotteryId` | Long | 宝箱 ID |
| `rows[].lotteryName` | String | 宝箱名称 |
| `rows[].prizeId` | Long | 奖品 ID |
| `rows[].ornamentName` | String | 饰品名称 |
| `rows[].imageUrl` | String | 饰品图片 |
| `rows[].ornamentsPrice` | Decimal | 奖品价值 |
| `rows[].ornamentLevel` | Int | 品质等级 ID |
| `rows[].levelImg` | String | 品质底图，可作饰品卡片背景 |
| `rows[].exteriorName` | String | 磨损度，可能为 `null` |
| `rows[].createTime` | String | 中奖时间 `yyyy-MM-dd HH:mm:ss` |

失败时返回 `code = 500`，`msg` 为 `查询失败，请稍后重试`。

> **与 `myRecords` 的区别**：`myRecords` 只返回当前登录玩家自己的记录（不含昵称/头像/品质图）；`globalRecords` 返回全服记录并附带中奖者昵称、头像、品质底图，专供公示展示。

> **轮询建议**：公示区如需实时滚动，建议 15~30 秒轮询一次 `pageNum=1`，不要高频请求。

---

## 五、典型调用流程

```
进入抽奖页
   │
   ├─→ POST /myStats
   │      拿到 availableTurnover、lotteryList
   │      渲染宝箱、奖品格子（爆率用 displayPercent）
   │      显示可抽次数 lotteryChances
   │
   ├─→ 玩家点击抽奖（按钮置灰防连点）
   │      POST /draw { lotteryId }
   │         ├─ code=200 → 用 prizeId 定位并播放动画
   │         │              动画结束后重新 POST /myStats 刷新
   │         └─ code=500 → 按钮恢复，展示 msg
   │
   ├─→ 查看我的中奖记录
   │      POST /myRecords { pageNum, pageSize }
   │
   └─→ 中奖公示区（跑马灯，15~30s 轮询）
          POST /globalRecords { pageNum: 1, pageSize: 20 }
```

---

## 六、对接注意事项

1. **不要传 userId**：所有接口的用户身份从 token 解析，传了也会被忽略。
2. **`myStats` 无需 body**：之前该接口曾要求传 `{}`，现已改为无参，body 传或不传都可以。
3. **次数按宝箱各算**：`lotteryChances` 在每个宝箱内单独计算（因为门槛可能不同），不是全局共享的次数。多个宝箱的次数是"同一份可用流水"的不同换算结果，抽任一宝箱都会消耗同一份流水。
4. **抽奖不动余额**：客户端不要在抽奖后刷新余额，抽奖不产生金币/积分变化；只有分解饰品才会变。
5. **动画与发奖解耦**：接口返回成功即已发奖入背包，动画播放期间活动被关闭不影响结果。
6. **爆率字段区分**：给玩家看 `displayPercent`，`realPercent` / `realCount` 属于内部数据。
7. **奖池自动重置**：当宝箱所有奖品剩余库存耗尽时，下一次抽奖会自动按后台配置的初始真实数量重置奖池，客户端无需处理。
8. **全服记录已过滤脏数据**：`globalRecords` 服务端已排除机器人、白号、封禁及已删除用户，客户端直接展示即可。
9. **公示区别高频轮询**：`globalRecords` 建议 15~30 秒轮询一次，`pageSize` 上限 100。

---

## 七、相关代码位置

| 内容 | 文件 |
|------|------|
| 用户端接口 | `skins-service/service-admin/src/main/java/com/ruoyi/admin/controller/TurnoverLotteryUserController.java` |
| 业务实现 | `skins-service/service-admin/src/main/java/com/ruoyi/admin/service/impl/TurnoverLotteryServiceImpl.java` |
| 全服记录查询 | `skins-service/service-admin/src/main/java/com/ruoyi/admin/mapper/TurnoverLotteryRecordMapper.java` |
| 全服记录 VO | `skins-model/src/main/java/com/ruoyi/domain/vo/lottery/TurnoverLotteryWinVO.java` |
| 奖品实体 | `skins-model/src/main/java/com/ruoyi/domain/entity/lottery/TtTurnoverLotteryPrize.java` |
| 记录实体 | `skins-model/src/main/java/com/ruoyi/domain/entity/lottery/TtTurnoverLotteryRecord.java` |
| 建表 SQL | `docs/updata_sql.md`（搜索"流水抽奖"） |