API对接文档

API对接文档.md

@@ -0,0 +1,272 @@
+# 大富翁-摇色子 对接文档
+
+本文覆盖**平台侧对接接口**（`/api/v1/*`，使用 `auth-token` 鉴权）以及（可选）**玩家侧接口**（`/api/*`，使用 `token` 鉴权）。
+
+---
+
+## 1. 基本约定
+
+### 1.1 服务地址（Base URL）
+
+由部署方提供：
+
+- 测试环境：`https://dice-api.yuliao666.com`
+
+[//]: # (- 生产环境：`https://api.example.com`)
+
+下文所有路径均为相对路径，如：`/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.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.xxx/?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`。
+