273 lines
8.0 KiB
Markdown
273 lines
8.0 KiB
Markdown
# 大富翁-摇色子 对接文档
|
||
|
||
本文覆盖**平台侧对接接口**（`/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
|
||
- **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`。
|
||
|