新增Dicey Fun 第三方接入英文文档

2026-05-08 18:13:53 +08:00
parent 641bb83f7f
commit 90ba5b0068
2 changed files with 536 additions and 1 deletions
--- a/server/docs/DICEY_FUN_THIRD_PARTY_ACCESS_EN.md
+++ b/server/docs/DICEY_FUN_THIRD_PARTY_ACCESS_EN.md
@@ -0,0 +1,535 @@
+# Dicey Fun Third-Party Integration Guide (Based on Existing Project APIs)
+
+## 1. Basic Information
+
+- provider: `Dicey Fun`
+- provider_code: `DF`
+- game_type: `slot`
+- game_list: `["dafuwen"]`
+- provider_logo: ``
+- Lobby URL (reference): `https://dice-v3-lobby.h55555game.top`
+- Admin console URL: `https://dice-v3.h55555game.top/`
+- agent_token: `[View in admin console menu: System Management -> User Management -> Agent ID]`
+- agent_id: `5ef059938ba799aaa845e1c2e8a762bd`
+
+## 2. API Domain and Protocol
+
+- Protocol: `HTTP/HTTPS` (Production is recommended to use `HTTPS`)
+- Base URL: `https://{your-domain}` (Provided by the deployment party)
+- Content-Type: `application/json`
+- Charset: `UTF-8`
+
+### 2.1 Calling Conventions (Recommended for Third Parties)
+
+- `/api/v1/authToken` uses `GET + Query parameters`
+- Other `/api/v1/*` endpoints use `POST + JSON Body` (In this project the route is `Route::any`, but third parties are recommended to standardize on `POST`)
+- Unified headers:
+  - `Content-Type: application/json`
+  - `Accept: application/json`
+  - `auth-token: {authtoken}` (Required for all endpoints except `/api/v1/authToken`)
+- All time-related parameters use Unix timestamps (seconds)
+- Recommended timeouts: connect timeout `3s`, read timeout `10s`
+- Production recommendation: add caller IP whitelist and retry backoff (to avoid burst retry storms)
+
+---
+
+## 3. Common Response Format
+
+All endpoints return the following structure:
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {}
+}
+```
+
+Notes:
+
+- `code=200` indicates success
+- Failures typically return: `400/401/402/403/404/422/500`
+
+Common error codes:
+
+- `400` Invalid parameters
+- `401` Missing token
+- `402` Token invalid or expired
+- `403` Signature or authentication failed
+- `404` Resource not found
+- `422` Business error (e.g., insufficient balance)
+- `500` Server exception
+
+---
+
+## 4. Authentication Flow (Platform Level)
+
+Before calling any `/api/v1/*` endpoint, obtain an `auth-token` first.
+
+### 4.1 Get auth-token
+
+- Path: `GET /api/v1/authToken`
+- Auth parameters (Query):
+  - `agent_id`: Agent identifier (merchant identifier)
+  - `secret`: Shared secret agreed by both parties
+  - `time`: Unix timestamp (seconds)
+  - `signature`: Signature
+
+Signature rule:
+
+```text
+signature = md5(agent_id + secret + time)
+```
+
+Signature example (source string and result):
+
+```text
+agent_id = 9f86d081884c7d659a2feaa0c55ad015
+secret   = xF75oK91TQj13s0UmNIr1NBWMWGfflNO
+time     = 1713753600
+sign_src = 9f86d081884c7d659a2feaa0c55ad015xF75oK91TQj13s0UmNIr1NBWMWGfflNO1713753600
+signature= md5(sign_src)
+```
+
+PHP signature example:
+
+```php
+$agentId = '9f86d081884c7d659a2feaa0c55ad015';
+$secret = 'xF75oK91TQj13s0UmNIr1NBWMWGfflNO';
+$time = (string) time();
+$signature = md5($agentId . $secret . $time);
+```
+
+JavaScript signature example (Node.js):
+
+```javascript
+const crypto = require('crypto');
+
+const agentId = '9f86d081884c7d659a2feaa0c55ad015';
+const secret = 'xF75oK91TQj13s0UmNIr1NBWMWGfflNO';
+const time = Math.floor(Date.now() / 1000).toString();
+const signature = crypto.createHash('md5').update(agentId + secret + time).digest('hex');
+```
+
+Server-side validation logic (key points):
+
+- Missing any of `agent_id/secret/time/signature` => fail (`400`)
+- `secret` mismatch => fail (`403`)
+- `time` outside tolerance window => fail (`403`, default tolerance `300s`)
+- `signature` mismatch => fail (`403`)
+- If validated, the server issues `authtoken`; subsequent requests must include it in the `auth-token` header
+
+Anti-replay and time sync recommendations:
+
+- Caller server must enable NTP time synchronization
+- `time` should be the current seconds timestamp at request time; do not reuse old values
+- If you see “Timestamp expired or invalid”, first check server clock drift
+
+Success response example:
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "authtoken": "xxx.yyy.zzz"
+  }
+}
+```
+
+For subsequent calls to `/api/v1/*`, include the following header:
+
+```text
+auth-token: {authtoken}
+```
+
+### 4.2 Full Call Chain (Recommended)
+
+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`)
+5. If `402` is returned, re-fetch `authtoken` and retry once
+
+---
+
+## 5. Game APIs
+
+All endpoints below require the `auth-token` header.
+
+## 5.1 Get Game List (Supported)
+
+- Path: `POST /api/v1/getGameList`
+- Header:
+  - `auth-token: {authtoken}`
+- Body parameters:
+  - `lang` (optional): `zh`/`en`, default `zh`
+- Response notes:
+  - Reads enabled games (`status=1`) from the `dice_game` table
+  - Currently returns only one game by default: `dafuwen`
+  - Returns `game_name` in Chinese/English according to `lang`
+  - Fields are desensitized: sensitive configs (e.g., `sensitive_config_json`) will not be returned
+
+Response fields (`data.game_list[]`):
+
+- `provider`: Provider name
+- `provider_code`: Provider code
+- `game_code`: Game code
+- `game_key`: Unique game key
+- `game_type`: Game type
+- `logo`: Game logo URL
+- `game_url`: Game URL
+- `hall_url`: Lobby URL
+- `status`: Status (`1` enabled)
+- `sort`: Sort value
+- `game_name`: Game name (Chinese/English based on `lang`)
+
+Success example (`lang=zh`):
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "game_list": [
+      {
+        "provider": "Dicey Fun",
+        "provider_code": "DF",
+        "game_code": "dafuwen",
+        "game_key": "dafuwen",
+        "game_type": "slot",
+        "logo": "",
+        "game_url": "https://dice-v3-game.h55555game.top/",
+        "hall_url": "https://dice-v3-game.h55555game.top/",
+        "status": 1,
+        "sort": 1,
+        "game_name": "大富翁"
+      }
+    ]
+  }
+}
+```
+
+Success example (`lang=en`):
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "game_list": [
+      {
+        "provider": "Dicey Fun",
+        "provider_code": "DF",
+        "game_code": "dafuwen",
+        "game_key": "dafuwen",
+        "game_type": "slot",
+        "logo": "",
+        "game_url": "https://dice-v3-game.h55555game.top/",
+        "hall_url": "https://dice-v3-game.h55555game.top/",
+        "status": 1,
+        "sort": 1,
+        "game_name": "Dafuweng"
+      }
+    ]
+  }
+}
+```
+
+## 5.2 Get Game Hall Info (Supported, Desensitized)
+
+- Path: `POST /api/v1/getGameHall`
+- Header:
+  - `auth-token: {authtoken}`
+- Body parameters:
+  - `lang` (optional): `zh`/`en`, default `zh`
+- Response notes:
+  - Returns lobby URL `hall_url`
+  - Returns game list (from `dice_game`)
+  - Does not return sensitive information fields
+
+Response fields:
+
+- `data.provider`: Provider name
+- `data.provider_code`: Provider code
+- `data.hall_url`: Lobby URL
+- `data.game_list`: Game list (same structure as `/api/v1/getGameList`)
+
+Success example:
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "provider": "Dicey Fun",
+    "provider_code": "DF",
+    "hall_url": "https://dice-v3-game.h55555game.top/",
+    "game_list": [
+      {
+        "provider": "Dicey Fun",
+        "provider_code": "DF",
+        "game_code": "dafuwen",
+        "game_key": "dafuwen",
+        "game_type": "slot",
+        "logo": "",
+        "game_url": "https://dice-v3-game.h55555game.top/",
+        "hall_url": "https://dice-v3-game.h55555game.top/",
+        "status": 1,
+        "sort": 1,
+        "game_name": "大富翁"
+      }
+    ]
+  }
+}
+```
+
+Success example (`lang=en`):
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "provider": "Dicey Fun",
+    "provider_code": "DF",
+    "hall_url": "https://dice-v3-game.h55555game.top/",
+    "game_list": [
+      {
+        "provider": "Dicey Fun",
+        "provider_code": "DF",
+        "game_code": "dafuwen",
+        "game_key": "dafuwen",
+        "game_type": "slot",
+        "logo": "",
+        "game_url": "https://dice-v3-game.h55555game.top/",
+        "hall_url": "https://dice-v3-game.h55555game.top/",
+        "status": 1,
+        "sort": 1,
+        "game_name": "Dafuweng"
+      }
+    ]
+  }
+}
+```
+
+## 5.3 Get Game URL (Supported)
+
+- Path: `POST /api/v1/getGameUrl`
+- Body parameters:
+  - `username` (required): Player username (auto-created if not exists)
+  - `password` (optional): default `123456`
+  - `time` (optional): if omitted, server uses current timestamp
+  - `lang` (optional): `zh`/`en`, default `zh`
+
+Success example:
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "url": "https://{game-domain}/?token=...&lang=zh"
+  }
+}
+```
+
+### 5.4 Lobby URL (Recommendation for This Project)
+
+This project uses `getGameUrl` as the primary entry method, and `game_list` currently contains only `dafuwen`.
+
+- If the third party needs a standalone lobby URL, use your configured value: `[to be filled]`
+- If the third party can jump directly into the game, call `getGameUrl` directly
+
+### 5.5 Game List API (Current Project Status)
+
+An independent endpoint is provided: `POST /api/v1/getGameList`, supporting both Chinese and English, with data from the `dice_game` table.
+
+---
+
+## 6. Game Management Admin (Added)
+
+This update introduces a game management table and menu to centrally manage basic game information.
+
+### 6.1 Database Table
+
+- Table creation SQL: `server/db/dice_game.sql`
+- Table name: `dice_game`
+- Key fields:
+  - `logo`: Game logo
+  - `game_url`: Game URL
+  - `hall_url`: Lobby URL
+  - `game_code`: Game code
+  - `game_key`: Unique game key
+  - `status`: Status (1 enabled / 0 disabled)
+  - `game_type`: Game type
+  - `merchant_config_json`: Merchant-visible extensions
+  - `sensitive_config_json`: Sensitive configuration (not returned by hall APIs)
+
+### 6.2 Menu and Permissions
+
+- Menu SQL: `server/db/dice_game_menu.sql`
+- Menu path: `/dice/game/index`
+- Permission identifiers:
+  - `dice:game:index:index`
+  - `dice:game:index:read`
+  - `dice:game:index:save`
+  - `dice:game:index:update`
+  - `dice:game:index:destroy`
+
+---
+
+## 7. Wallet APIs
+
+All endpoints below require the `auth-token` header.
+
+### 7.1 Query Balance (Supported)
+
+Method 1 (recommended): `POST /api/v1/getPlayerInfo`
+
+- Request parameters:
+  - `username` (required)
+- Balance field:
+  - `data.coin`
+
+### 7.2 Credit In / Credit Out (Supported)
+
+Endpoint: `POST /api/v1/setPlayerWallet`
+
+- Request parameters:
+  - `username` (required)
+  - `coin` (required)
+    - `coin > 0`: Credit in (deposit)
+    - `coin < 0`: Credit out (withdraw)
+    - `coin = 0`: Invalid
+
+On success, returns a `wallet record` including balances before/after transfer.
+
+### 7.3 Get Lobby URL (Wallet-side)
+
+If the integrator’s wallet flow requires “return lobby URL after transfer”, call the following after `setPlayerWallet`:
+
+- `POST /api/v1/getGameUrl`
+
+---
+
+## 8. Merchant (Agent) Configurable Fields
+
+It is recommended to configure the following fields in the integration parameter table:
+
+- `provider`: `Dicey Fun`
+- `provider_code`: `DF`
+- `agent_id`: `5ef059938ba799aaa845e1c2e8a762bd`
+- `secret`: Signature secret (shared by both parties)
+- `agent_token`: `[to be filled by us]` (if an additional business-layer token is needed)
+- `game_url`: Game frontend domain/URL
+- `lobby_url`: Lobby URL (optional)
+- `lang`: Default language (`zh`/`en`)
+- `callback_url`: Business callback URL (for future extension)
+- `ip_whitelist`: Caller IP whitelist (recommended)
+
+---
+
+## 9. Admin Console Information
+
+- Admin console URL: `https://dice-v3.h55555game.top/`
+- Username: `zhuguan`
+- Password: `qwer1234`
+
+---
+
+## 10. Integration Sequence (Recommended)
+
+1. Platform assigns `agent_id` and `secret`
+2. Third party calls `/api/v1/authToken` to obtain `authtoken`
+3. Third party calls `/api/v1/getGameHall` or `/api/v1/getGameList` to obtain lobby/game info
+4. Third party calls `/api/v1/getPlayerInfo` (optional, check user and balance)
+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)
+
+---
+
+## 11. Postman / cURL Examples
+
+### 11.1 Get auth-token
+
+```bash
+curl --location --request GET 'https://{your-domain}/api/v1/authToken?agent_id={agent_id}&secret={secret}&time={time}&signature={signature}'
+```
+
+During integration testing, it is recommended to print the following values locally before sending the request to ease troubleshooting:
+
+- `agent_id`
+- `time`
+- `sign_src` (concatenated source string before hashing)
+- `signature`
+- Final request URL
+
+### 11.2 Get Game URL
+
+```bash
+curl --location --request POST 'https://{your-domain}/api/v1/getGameUrl' \
+--header 'Content-Type: application/json' \
+--header 'auth-token: {authtoken}' \
+--data-raw '{
+  "username":"test_player_001",
+  "lang":"zh"
+}'
+```
+
+### 11.3 Get Game List (Chinese)
+
+```bash
+curl --location --request POST 'https://{your-domain}/api/v1/getGameList' \
+--header 'Content-Type: application/json' \
+--header 'auth-token: {authtoken}' \
+--data-raw '{
+  "lang":"zh"
+}'
+```
+
+### 11.4 Get Game List (English)
+
+```bash
+curl --location --request POST 'https://{your-domain}/api/v1/getGameList' \
+--header 'Content-Type: application/json' \
+--header 'auth-token: {authtoken}' \
+--data-raw '{
+  "lang":"en"
+}'
+```
+
+### 11.5 Get Game Hall (Chinese)
+
+```bash
+curl --location --request POST 'https://{your-domain}/api/v1/getGameHall' \
+--header 'Content-Type: application/json' \
+--header 'auth-token: {authtoken}' \
+--data-raw '{
+  "lang":"zh"
+}'
+```
+
+### 11.6 Credit In
+
+```bash
+curl --location --request POST 'https://{your-domain}/api/v1/setPlayerWallet' \
+--header 'Content-Type: application/json' \
+--header 'auth-token: {authtoken}' \
+--data-raw '{
+  "username":"test_player_001",
+  "coin":100
+}'
+```
+
+### 11.7 Query Balance
+
+```bash
+curl --location --request POST 'https://{your-domain}/api/v1/getPlayerInfo' \
+--header 'Content-Type: application/json' \
+--header 'auth-token: {authtoken}' \
+--data-raw '{
+  "username":"test_player_001"
+}'
+```