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

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

---

## 1. 基本约定

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

由部署方提供：

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

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

### 1.2 请求方式与编码

- **请求方法**：项目路由多数使用 `Route::any`，对接建议统一使用 **POST**（便于 body 传参）；个别接口文档中标注了 GET 参数。
- **编码**：`UTF-8`
- **Content-Type**：建议 `application/x-www-form-urlencoded` 或 `application/json`（以平台实际实现为准）
- **必带凭证**：所有 `/api/v1/*` 接口均需带 `api-key`（与服务端 `.env` 中 `API_KEY` 一致）；除 `/api/v1/authToken` 外另需 `auth-token`。详见 §2.2。

### 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）

平台侧接口需统一携带请求头 **`api-key`**（与服务端 `.env` 中 `API_KEY` 一致），业务接口另需 **`auth-token`**。

1. **获取 `auth-token`**（同时携带 `api-key`）
2. **携带 `api-key` + `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.h55555game.top/storage/20260317/20a0d49f016bcc89afa794ed217e762fe3ef6481.png](server/public/img.png)
- **secret**：xF75oK91TQj13s0UmNIr1NBWMWGfflNO（服务器配置）
- **后台地址**：https://dice.h55555game.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 平台 api-key（所有 /api/v1/* 必填）

- **取值**：与服务端环境变量 `API_KEY` 完全一致（部署在 `server/.env`）
- **适用范围**：所有 `/api/v1/*` 接口（含 `/api/v1/authToken` 与业务接口）
- **携带方式**（任选其一，按优先级读取，先命中即采用）：
  1. 请求头 `api-key: <API_KEY>`（**推荐**）
  2. URL 查询参数 `api_key=<API_KEY>`（或 `api-key=<API_KEY>`）
  3. body 表单/JSON 字段 `api_key`（或 `api-key`）
- **未携带或错误**：`401` / `403`

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

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

- `api-key: <与 API_KEY 一致>`（请求头 / query / body 任选其一，参见 2.2）
- `auth-token: <authtoken>`（仅支持请求头）

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

---

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

### 3.1 获取游戏地址

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

#### 请求参数（body）

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

#### 响应示例

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

### 3.2 获取用户信息

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

#### 请求参数

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

#### 响应说明

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

### 3.3 获取游戏记录

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

#### 请求参数

| 参数名 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| username | 否 | string | 不传则不按用户筛选；数据仅来自「最近 7 天」时间窗（见下） |
| start_create_time | 否 | string | 开始时间；与 `end_create_time` 均不传时，服务端默认最近 7 天 |
| end_create_time | 否 | string | 结束时间 |
| limit | 否 | int | 返回条数上限，默认 20；小于 1 或大于 2000 时按 20 处理 |

**时间规则**：仅允许查询「当前服务器时间起向前 7 天」内的 `create_time`；`start_create_time` 与 `end_create_time` 的跨度不得超过 7 天；`end_create_time` 晚于当前时间时按当前时间截断。非法区间返回参数错误。

#### 响应说明

返回游玩记录列表（按 `id` 倒序，最多 `limit` 条），并附带 `dice_player`（包含 `id/username/phone`）。

### 3.4 获取钱包流水

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

参数与时间规则同 3.3（无 `page`，仅 `limit` 限制条数），返回钱包流水列表（附带 `dice_player`）。

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

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

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

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

- **路径**：`/api/v1/setPlayerWallet`
- **方法**：POST
- **请求头**：`api-key`、`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 | 未授权 | 未携带 `api-key`、`auth-token` 或 `token` |
| 402 | token 无效或已过期 | `auth-token/token` 过期、签名错误、被挤下线等 |
| 403 | 鉴权失败 | `api-key` 无效、`secret` 错误、签名验证失败、时间戳无效等 |
| 404 | 资源不存在 | 用户不存在等 |
| 422 | 业务逻辑错误 | 余额不足、业务校验失败等 |
| 500 | 服务器内部错误 | 服务端异常或配置缺失 |

---

## 6. 联调建议

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