更新对接平台文档

2026-05-12 15:50:45 +08:00
parent 90ba5b0068
commit 80d39ed1cd
2 changed files with 170 additions and 2 deletions
--- a/server/docs/DICEY_FUN_THIRD_PARTY_ACCESS.md
+++ b/server/docs/DICEY_FUN_THIRD_PARTY_ACCESS.md
@@ -148,7 +148,7 @@ auth-token: {authtoken}
 1. 计算 `signature = md5(agent_id + secret + time)`
 2. 调用 `GET /api/v1/authToken` 获取 `authtoken`
 3. 在 Header 添加 `auth-token: {authtoken}`
-4. 调用业务接口（如 `getPlayerInfo`、`setPlayerWallet`、`getGameUrl`）
+4. 调用业务接口（如 `getPlayerInfo`、`setPlayerWallet`、`getGameUrl`、`getPlayerGameRecord`、`getPlayerWalletRecord`、`getPlayerTicketRecord`）
 5. 若返回 `402`，重新获取 `authtoken` 后重试一次

 ---
@@ -345,6 +345,23 @@ auth-token: {authtoken}

 已提供独立接口：`POST /api/v1/getGameList`，支持中英文格式，且数据来自 `dice_game` 表。

+## 5.6 获取玩家游戏记录（已支持）
+
+- 路径: `POST /api/v1/getPlayerGameRecord`
+- Header:
+  - `auth-token: {authtoken}`
+- Body 参数：
+  - `username`（可选）：玩家账号；不传则**不按玩家筛选**（返回库内符合条件的记录，请谨慎使用）
+  - `start_create_time`（可选）：创建时间下限，与表字段 `create_time` 比较（`>=`）；不传则不限制
+  - `end_create_time`（可选）：创建时间上限（`<=`）；不传则不限制
+  - `page`（可选）：页码，默认 `1`，小于 `1` 时按 `1` 处理
+  - `limit`（可选）：每页条数，默认 `20`；若小于 `1` 或大于 `100` 则按 `20` 处理
+- 返回说明：
+  - 成功时 `data` 为**数组**（当前页记录列表），每条为 `dice_play_record` 行数据，并附带 `dice_player`：`{ id, username, phone }`（若批量关联不到则为 `null`）
+  - 若传了 `username` 且玩家不存在：`data` 为空数组 `[]`
+
+记录主要字段（与库表一致，节选）：`id`、`player_id`、`admin_id`、`lottery_config_id`、`lottery_type`、`ante`、`paid_amount`、`is_win`、`win_coin`、`super_win_coin`、`reward_win_coin`、`use_coins`、`direction`、`reward_tier`、`lottery_id`、`start_index`、`target_index`、`roll_array`、`roll_number`、`lottery_name`、`status`、`create_time`、`update_time` 等。
+
 ---

 ## 6. 游戏管理后台（新增）
@@ -411,6 +428,33 @@ auth-token: {authtoken}

 - `POST /api/v1/getGameUrl`

+### 7.4 获取钱包流水（已支持）
+
+- 路径: `POST /api/v1/getPlayerWalletRecord`
+- Header:
+  - `auth-token: {authtoken}`
+- Body 参数：
+  - `username`（可选）：玩家账号；不传则**不按玩家筛选**
+  - `start_create_time`、`end_create_time`（可选）：同 `getPlayerGameRecord`，作用于 `create_time`
+  - `page`、`limit`（可选）：分页规则同上
+- 返回说明：
+  - 成功时 `data` 为数组；每条为 `dice_player_wallet_record` 数据，并含关联 `dice_player`（`id, username, phone`）
+  - 若传了 `username` 且玩家不存在：`data` 为空数组 `[]`
+
+`type` 含义：`0` 充值、`1` 提现、`2` 购买抽奖次数（与业务写入一致）。
+
+### 7.5 获取抽奖券获取记录（已支持）
+
+- 路径: `POST /api/v1/getPlayerTicketRecord`
+- Header:
+  - `auth-token: {authtoken}`
+- Body 参数：与 **7.4** 相同（`username`、`start_create_time`、`end_create_time`、`page`、`limit`）
+- 返回说明：
+  - 成功时 `data` 为 `dice_player_ticket_record` 列表，含关联 `dice_player`
+  - 若传了 `username` 且玩家不存在：`data` 为空数组 `[]`
+
+主要字段（节选）：`id`、`player_id`、`admin_id`、`use_coins`、`ante`、`total_ticket_count`、`paid_ticket_count`、`free_ticket_count`、`remark`、`create_time`、`update_time` 等。
+
 ---

 ## 8. 商户（代理）可配置字段
@@ -447,6 +491,7 @@ auth-token: {authtoken}
 5. 第三方调用 `/api/v1/setPlayerWallet` 进行额度转入（如有）
 6. 第三方调用 `/api/v1/getGameUrl` 获取游戏地址并跳转
 7. 结束后调用 `/api/v1/setPlayerWallet` 执行额度转出（如有）
+8. （可选）对账或客服：调用 `/api/v1/getPlayerWalletRecord`、`/api/v1/getPlayerGameRecord`、`/api/v1/getPlayerTicketRecord` 拉取流水

 ---

@@ -533,3 +578,42 @@ curl --location --request POST 'https://{your-domain}/api/v1/getPlayerInfo' \
  "username":"test_player_001"
 }'
 ```
+
+### 11.8 获取玩家游戏记录
+
+```bash
+curl --location --request POST 'https://{your-domain}/api/v1/getPlayerGameRecord' \
+--header 'Content-Type: application/json' \
+--header 'auth-token: {authtoken}' \
+--data-raw '{
+  "username":"test_player_001",
+  "page":1,
+  "limit":20
+}'
+```
+
+### 11.9 获取钱包流水
+
+```bash
+curl --location --request POST 'https://{your-domain}/api/v1/getPlayerWalletRecord' \
+--header 'Content-Type: application/json' \
+--header 'auth-token: {authtoken}' \
+--data-raw '{
+  "username":"test_player_001",
+  "page":1,
+  "limit":20
+}'
+```
+
+### 11.10 获取抽奖券获取记录
+
+```bash
+curl --location --request POST 'https://{your-domain}/api/v1/getPlayerTicketRecord' \
+--header 'Content-Type: application/json' \
+--header 'auth-token: {authtoken}' \
+--data-raw '{
+  "username":"test_player_001",
+  "page":1,
+  "limit":20
+}'
+```
--- a/server/docs/DICEY_FUN_THIRD_PARTY_ACCESS_EN.md
+++ b/server/docs/DICEY_FUN_THIRD_PARTY_ACCESS_EN.md
@@ -148,7 +148,7 @@ auth-token: {authtoken}
 1. Compute `signature = md5(agent_id + secret + time)`
 2. Call `GET /api/v1/authToken` to obtain `authtoken`
 3. Add header `auth-token: {authtoken}`
-4. Call business endpoints (e.g., `getPlayerInfo`, `setPlayerWallet`, `getGameUrl`)
+4. Call business endpoints (e.g., `getPlayerInfo`, `setPlayerWallet`, `getGameUrl`, `getPlayerGameRecord`, `getPlayerWalletRecord`, `getPlayerTicketRecord`)
 5. If `402` is returned, re-fetch `authtoken` and retry once

 ---
@@ -345,6 +345,23 @@ This project uses `getGameUrl` as the primary entry method, and `game_list` curr

 An independent endpoint is provided: `POST /api/v1/getGameList`, supporting both Chinese and English, with data from the `dice_game` table.

+## 5.6 Get Player Game Records (Supported)
+
+- Path: `POST /api/v1/getPlayerGameRecord`
+- Header:
+  - `auth-token: {authtoken}`
+- Body parameters:
+  - `username` (optional): Player username; if omitted, **no player filter** is applied (returns matching rows from the database—use with care)
+  - `start_create_time` (optional): Lower bound on `create_time` (`>=`); if omitted, no lower bound
+  - `end_create_time` (optional): Upper bound on `create_time` (`<=`); if omitted, no upper bound
+  - `page` (optional): Page number, default `1`; values less than `1` are treated as `1`
+  - `limit` (optional): Page size, default `20`; if less than `1` or greater than `100`, it is treated as `20`
+- Response notes:
+  - On success, `data` is an **array** (current page). Each item is a `dice_play_record` row plus `dice_player`: `{ id, username, phone }` (or `null` if the player cannot be resolved)
+  - If `username` is provided but the player does not exist: `data` is an empty array `[]`
+
+Main fields (same as table columns, partial list): `id`, `player_id`, `admin_id`, `lottery_config_id`, `lottery_type`, `ante`, `paid_amount`, `is_win`, `win_coin`, `super_win_coin`, `reward_win_coin`, `use_coins`, `direction`, `reward_tier`, `lottery_id`, `start_index`, `target_index`, `roll_array`, `roll_number`, `lottery_name`, `status`, `create_time`, `update_time`, etc.
+
 ---

 ## 6. Game Management Admin (Added)
@@ -411,6 +428,33 @@ If the integrator’s wallet flow requires “return lobby URL after transfer”

 - `POST /api/v1/getGameUrl`

+### 7.4 Get Player Wallet Records (Supported)
+
+- Path: `POST /api/v1/getPlayerWalletRecord`
+- Header:
+  - `auth-token: {authtoken}`
+- Body parameters:
+  - `username` (optional): Player username; if omitted, **no player filter** is applied
+  - `start_create_time`, `end_create_time` (optional): Same as `getPlayerGameRecord`, applied to `create_time`
+  - `page`, `limit` (optional): Same pagination rules as above
+- Response notes:
+  - On success, `data` is an array of `dice_player_wallet_record` rows with related `dice_player` (`id`, `username`, `phone`)
+  - If `username` is provided but the player does not exist: `data` is an empty array `[]`
+
+`type` meaning: `0` deposit, `1` withdraw, `2` purchase draw chances (consistent with how records are written in business logic).
+
+### 7.5 Get Player Ticket Acquisition Records (Supported)
+
+- Path: `POST /api/v1/getPlayerTicketRecord`
+- Header:
+  - `auth-token: {authtoken}`
+- Body parameters: Same as **7.4** (`username`, `start_create_time`, `end_create_time`, `page`, `limit`)
+- Response notes:
+  - On success, `data` is a list of `dice_player_ticket_record` rows with related `dice_player`
+  - If `username` is provided but the player does not exist: `data` is an empty array `[]`
+
+Main fields (partial list): `id`, `player_id`, `admin_id`, `use_coins`, `ante`, `total_ticket_count`, `paid_ticket_count`, `free_ticket_count`, `remark`, `create_time`, `update_time`, etc.
+
 ---

 ## 8. Merchant (Agent) Configurable Fields
@@ -447,6 +491,7 @@ It is recommended to configure the following fields in the integration parameter
 5. Third party calls `/api/v1/setPlayerWallet` to credit in (if applicable)
 6. Third party calls `/api/v1/getGameUrl` to get the game URL and redirect
 7. After the session, call `/api/v1/setPlayerWallet` to credit out (if applicable)
+8. (Optional) Reconciliation or support: call `/api/v1/getPlayerWalletRecord`, `/api/v1/getPlayerGameRecord`, `/api/v1/getPlayerTicketRecord` to pull history

 ---

@@ -533,3 +578,42 @@ curl --location --request POST 'https://{your-domain}/api/v1/getPlayerInfo' \
  "username":"test_player_001"
 }'
 ```
+
+### 11.8 Get Player Game Records
+
+```bash
+curl --location --request POST 'https://{your-domain}/api/v1/getPlayerGameRecord' \
+--header 'Content-Type: application/json' \
+--header 'auth-token: {authtoken}' \
+--data-raw '{
+  "username":"test_player_001",
+  "page":1,
+  "limit":20
+}'
+```
+
+### 11.9 Get Player Wallet Records
+
+```bash
+curl --location --request POST 'https://{your-domain}/api/v1/getPlayerWalletRecord' \
+--header 'Content-Type: application/json' \
+--header 'auth-token: {authtoken}' \
+--data-raw '{
+  "username":"test_player_001",
+  "page":1,
+  "limit":20
+}'
+```
+
+### 11.10 Get Player Ticket Records
+
+```bash
+curl --location --request POST 'https://{your-domain}/api/v1/getPlayerTicketRecord' \
+--header 'Content-Type: application/json' \
+--header 'auth-token: {authtoken}' \
+--data-raw '{
+  "username":"test_player_001",
+  "page":1,
+  "limit":20
+}'
+```