# 大富翁-摇色子 对接文档

本文覆盖**平台侧对接接口**（`/api/v1/*`，使用 `auth-token` 鉴权）以及（可选）**玩家侧接口**（`/api/*`，使用 `token` 鉴权）。

---

## 1. 基本约定

### 1.1 服务地址（Base URL）

由部署方提供：

- 测试环境：`https://dice-api.yuliao666.top`

下文所有路径均为相对路径，如：`/api/v1/getGameUrl`。

### 1.2 请求方式与编码

- **请求方法**：项目路由多数使用 `Route::any`，对接建议统一使用 **POST**（便于 body 传参）；个别接口文档中标注了 GET 参数。
- **编码**：`UTF-8`
- **Content-Type**：建议 `application/x-www-form-urlencoded` 或 `application/json`（以平台实际实现为准）

### 1.3 统一返回结构

所有接口统一返回 JSON：

```json
{
  "code": 200,
  "message": "success",
  "data": {}
}
```

- `code`：业务状态码（见“返回 code 对照表”）
- `message`：提示信息（可根据请求头 `lang` 返回中英文）
- `data`：成功时返回数据；失败时通常不返回该字段

### 1.4 多语言（lang）

服务端会根据请求头 `lang` 翻译 `message`（以及部分接口字段）：

- `lang: zh`（默认）
- `lang: en`

> 注意：平台 v1 接口的 `getGameUrl` 还支持 body 参数 `lang`（`zh/en`），用于拼接游戏地址语言参数。

---

## 2. 鉴权与对接流程（平台侧 /api/v1）

平台侧接口分两步：

1. **获取 `auth-token`**
2. **携带 `auth-token` 调用 `/api/v1/*` 业务接口**

### 2.1 获取 auth-token

- **路径**：`/api/v1/authToken`
- **方法**：GET / POST 均可（建议 GET，参数放 query）
- **说明**：用于平台调用 v1 业务接口的授权 token（JWT）

#### 请求参数（query/body）

| 参数名 | 必填 | 类型 | 说明                                                |
| --- | --- | --- |---------------------------------------------------|
| agent_id | 是 | string | 平台/代理标识（后台查看对应管理员agent_id）                        |
| secret | 是 | string | 双方约定的密钥（服务端配置 `xF75oK91TQj13s0UmNIr1NBWMWGfflNO`） |
| time | 是 | int/string | Unix 时间戳（秒），服务端会做时间容忍校验                           |
| signature | 是 | string | 签名：`md5(agent_id + secret + time)`                |
- **agent_id**：通过后台获取系统管理-用户管理-代理ID![http://dice-api.yuliao666.top/storage/20260317/20a0d49f016bcc89afa794ed217e762fe3ef6481.png](server/public/img.png)
- **secret**：xF75oK91TQj13s0UmNIr1NBWMWGfflNO（服务器配置）
- **后台地址**：https://dice.yuliao666.top 账号: zhuguan 密码：123456
#### 签名规则

- **签名字符串**：直接拼接 `agent_id.secret.time`（无分隔符）
- **算法**：MD5（32 位小写/大写均可，按实现一致即可）

示例（伪代码）：

```text
signature = md5(agent_id + secret + time)
```

#### 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "authtoken": "xxxx.yyyy.zzzz"
  }
}
```

#### 失败场景

- 缺少参数：`code=400`
- 密钥错误/签名错误/时间戳无效：`code=403`
- 服务端未配置密钥或生成失败：`code=500`

### 2.2 调用 v1 业务接口（携带 auth-token）

除 `/api/v1/authToken` 外，其余 `/api/v1/*` 接口需要在请求头携带：

- `auth-token: <authtoken>`

当 `auth-token` 过期或失效，返回 `code=402`，需要重新调用 `/api/v1/authToken` 获取新 token。

---

## 3. 平台 v1 业务接口清单（/api/v1）

### 3.1 获取游戏地址

- **路径**：`/api/v1/getGameUrl`
- **方法**：POST
- **请求头**：`auth-token`
- **说明**：根据平台用户名创建/登录玩家并生成登录 JWT，返回可直接打开的游戏地址。

#### 请求参数（body）

| 参数名 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| username | 是 | string | 玩家唯一账号（平台侧用户名） |
| password | 否 | string | 默认 `123456` |
| time | 否 | int/string | 默认当前时间戳 |
| lang | 否 | string | `zh` / `en`，默认 `zh` |

#### 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "url": "https://dice-game.yuliao666.top/?token=...&lang=zh"
  }
}
```

### 3.2 获取用户信息

- **路径**：`/api/v1/getPlayerInfo`
- **方法**：POST
- **请求头**：`auth-token`

#### 请求参数

| 参数名 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| username | 是 | string | 玩家账号 |

#### 响应说明

返回玩家基础信息（已隐藏敏感字段，如 `password` 等）。

### 3.3 获取游戏记录

- **路径**：`/api/v1/getPlayerGameRecord`
- **方法**：POST
- **请求头**：`auth-token`

#### 请求参数

| 参数名 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| username | 否 | string | 不传则查询全量（按时间/分页） |
| start_create_time | 否 | string | 开始时间（与数据库存储格式一致） |
| end_create_time | 否 | string | 结束时间（与数据库存储格式一致） |
| page | 否 | int | 默认 1 |
| limit | 否 | int | 默认 20，最大 100 |

#### 响应说明

返回游玩记录列表，并附带 `dice_player`（包含 `id/username/phone`）。

### 3.4 获取钱包流水

- **路径**：`/api/v1/getPlayerWalletRecord`
- **方法**：POST
- **请求头**：`auth-token`

参数与分页规则同 3.3，返回钱包流水列表（附带 `dice_player`）。

### 3.5 获取中奖券获取记录

- **路径**：`/api/v1/getPlayerTicketRecord`
- **方法**：POST
- **请求头**：`auth-token`

参数与分页规则同 3.3，返回中奖券记录列表（附带 `dice_player`）。

### 3.6 平台钱包转入/转出

- **路径**：`/api/v1/setPlayerWallet`
- **方法**：POST
- **请求头**：`auth-token`
- **说明**：平台为玩家加币/扣币，生成钱包流水。

#### 请求参数

| 参数名 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| username | 是 | string | 玩家账号 |
| coin | 是 | number | 转入：`>0`；转出：`<0`；不允许为 0 |

#### 业务规则

- 当 `coin < 0` 且余额不足时：`code=422`，`message=余额不足，无法转出`

---

## 4. 玩家侧接口（可选 /api）

若甲方平台需要在**服务端**直接调用“购买抽奖券/开局”等接口，可按本节对接（此类接口需要 `token`，与 `auth-token` 不同）。

### 4.1 获取 token（玩家登录）

- **路径**：`/api/user/Login`
- **方法**：POST
- **说明**：创建/登录玩家并返回登录 token 以及游戏地址。

请求参数：`username`、`password`（必填），`lang/coin/time`（可选）。

响应 `data.token` 可用于后续 `/api/*` 请求头 `token` 或 `Authorization: Bearer <token>`。

### 4.2 需要 token 的接口

请求头携带（任选一种）：

- `token: <token>`
- `Authorization: Bearer <token>`

接口列表：

- `/api/user/logout`
- `/api/user/info`
- `/api/user/balance`
- `/api/user/walletRecord`
- `/api/user/playGameRecord`
- `/api/game/config`
- `/api/game/buyLotteryTickets`
- `/api/game/lotteryPool`
- `/api/game/playStart`

---

## 5. 返回 code 对照表

项目定义的统一状态码如下（与 HTTP 语义对齐）：

| code | 含义 | 常见场景 |
| --- | --- | --- |
| 200 | 成功 | 请求成功 |
| 400 | 请求参数错误 | 缺参、参数格式不合法、范围错误 |
| 401 | 未授权 | 未携带 `auth-token` 或 `token` |
| 402 | token 无效或已过期 | `auth-token/token` 过期、签名错误、被挤下线等 |
| 403 | 鉴权失败 | `secret` 错误、签名验证失败、时间戳无效等 |
| 404 | 资源不存在 | 用户不存在等 |
| 422 | 业务逻辑错误 | 余额不足、业务校验失败等 |
| 500 | 服务器内部错误 | 服务端异常或配置缺失 |

---

## 6. 联调建议

- **时间戳校验**：`/api/v1/authToken` 会校验 `time` 与服务器时间差（默认容忍 300 秒），请确保平台服务器时间同步。
- **token 失效处理**：当 `code=402` 时，按业务类型重新获取 `auth-token` 或重新登录获取 `token`。
- **语言**：如需英文提示，请在请求头带 `lang: en`。