916 lines
46 KiB
Markdown
916 lines
46 KiB
Markdown
# 36 Zihua Mobile API Design Draft (V1)
|
||
|
||
This document is based on `docs/36字花-数据库与实施计划.md` and the PRD. It provides an initial mobile-facing API inventory and field definitions.
|
||
|
||
Scope: **platform-wide single period number and single draw result**; channels are used only for attribution, commission sharing, and risk control—not for splitting game rounds.
|
||
|
||
**Addendum (2026-04)**: §**1.5** describes server-side **Redis hot-spot caching** (`GameHotDataRedis`). It does **not** change any interface URL, parameter, or response field contracts; it is for integration testing and operations reference only.
|
||
|
||
## 1. Design Conventions
|
||
|
||
### 1.1 Base Conventions
|
||
- Protocol: HTTPS + JSON
|
||
- Path naming: `/api/{module}/{action}`, must match regex `^/api/[a-z]+/[a-z]+[A-Z][a-zA-Z]*$`
|
||
- **HTTP methods**: All mobile business APIs (`/api/*`, excluding `/api/v1/authToken`) use `POST`. Query-style endpoints also accept `GET` (for browser/debug tools); clients should uniformly use `POST`.
|
||
- For `POST`, header `Content-Type: application/json`; parameters in JSON body
|
||
- In `GET` compatibility mode, parameters go in the URL query string
|
||
- **Exception**: Notice module `/api/notice/noticeList`, `/api/notice/noticeConfirm` support **`GET` only**; parameters always use URL query string
|
||
- **Notice list without auth**: `GET /api/notice/noticeList` does **not** require `auth-token` or `user-token`; if `user-token` is still sent, popout items can return the user’s real `is_read`
|
||
- Auth endpoint `/api/v1/authToken` remains `GET`
|
||
- Time: UTC timestamp (seconds) + server timezone configuration
|
||
- Amounts: numeric transport (e.g. `"100.00"`); client display uses two decimal places (storage remains `decimal(18,2)`)
|
||
- Idempotency: critical write APIs require `idempotency_key`
|
||
- Required headers:
|
||
- `auth-token`: API auth token from `GET /api/v1/authToken` (signature-based API access credential)
|
||
- `user-token`: user session token; required on login-protected APIs
|
||
- Language header:
|
||
- `lang=zh`: Chinese (default)
|
||
- `lang=en`: English
|
||
|
||
### 1.2 Common Response Shape
|
||
```json
|
||
{
|
||
"code": 1,
|
||
"message": "ok",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
- `code=1` means success; any other value is a business error
|
||
- All `/api/*` response messages support Chinese and English: default Chinese; `lang=en` returns English, `lang=zh` returns Chinese
|
||
- Suggested error code ranges (by nature):
|
||
- `1000-1099`: parameter errors (missing fields, type errors, format errors, out of range)
|
||
- `1100-1199`: auth errors (not logged in, token expired, insufficient permission)
|
||
- `2000-2999`: business errors (insufficient balance, round not found, order not found, notice not found)
|
||
- `3000-3099`: flow errors (illegal flow/state, e.g. bet after lock, duplicate confirm, illegal state transition)
|
||
- `5000-5999`: system errors (service exception, dependency timeout, unknown error)
|
||
|
||
- Recommended base error codes (first release):
|
||
- `1`: success
|
||
- `1001`: missing parameter
|
||
- `1002`: invalid parameter format
|
||
- `1003`: illegal parameter value
|
||
- `1101`: not logged in or session expired
|
||
- `1103`: no permission
|
||
- `2001`: insufficient balance
|
||
- `2002`: round not found
|
||
- `2003`: order not found
|
||
- `2004`: notice not found
|
||
- `3001`: operation not allowed in current flow
|
||
- `3002`: betting closed, bets not allowed
|
||
- `3003`: duplicate request (idempotency conflict)
|
||
- `5000`: system busy, try again later
|
||
|
||
### 1.3 Authentication
|
||
- **API auth (`auth-token`)**: all mobile business APIs must send header `auth-token` (issued by `/api/v1/authToken`)
|
||
- **User session (`user-token`)**: login-protected APIs send header `user-token`; on expiry, refresh or log in again
|
||
|
||
### 1.4 Obtain API Auth Token (`auth-token`)
|
||
- **GET** `/api/v1/authToken`
|
||
- Purpose: obtain `auth-token` (required on all API request headers)
|
||
|
||
Request example:
|
||
`/api/v1/authToken?secret=564d14asdasd113e46542asd6das1a2a×tamp=1776331077&device_id=1&signature=AD84C49880896DBC16C59C7B122D1FF7`
|
||
|
||
Request parameters:
|
||
- `secret`: string (client secret; server validates against env `AUTH_TOKEN_SECRET`)
|
||
- `timestamp`: int (request timestamp; server allows ±300 seconds from server time)
|
||
- `device_id`: string (device id)
|
||
- `signature`: string (signature value)
|
||
|
||
Signature algorithm:
|
||
- Parameters in signature (excluding `signature`): `device_id`, `secret`, `timestamp`
|
||
- Sort parameter names **a-z**, concatenate as `key=value&key=value...`
|
||
- Compute: `signature = strtoupper(md5(concatenated string))`
|
||
|
||
Response parameters:
|
||
- `auth_token`: string (API auth token; put in header `auth-token`)
|
||
- `expires_in`: int (TTL in seconds)
|
||
- `server_time`: int (server timestamp for clock sync)
|
||
|
||
Possible error codes:
|
||
- `1001` missing parameter
|
||
- `1002` invalid parameter format
|
||
- `1103` invalid secret / signature error
|
||
- `3001` invalid timestamp
|
||
|
||
### 1.5 Server Performance & Redis Hot-Spot Cache (Implementation Notes)
|
||
|
||
> **No client contract change**: request paths, parameters, response JSON shape, and error codes are unchanged by caching; this section only explains how the server reduces latency, read paths, and consistency notes.
|
||
|
||
**Difference from “framework file cache”**
|
||
|
||
| Config | Scope |
|
||
|--------|--------|
|
||
| `CACHE_DRIVER` (`config/cache.php`, e.g. `file`) | Think-ORM / `get_sys_config()` etc. **system `config` table** model cache under `runtime/cache`; **not** used on this game hot-path. |
|
||
| `GAME_HOT_CACHE_*` (`config/game_hot_cache.php`) | Game **`user` / `game_config` / `game_record`** row-level JSON cache via **`support\Redis`** (`config/redis.php`), key prefix `dfw:v1:`. |
|
||
|
||
**Server cache coverage (read paths relevant to mobile)**
|
||
|
||
- **User**: member auth prefers Redis `user` row snapshot; on miss, DB then backfill. After **balance, streak, bet-flow**, etc. change and commit, **`GameHotDataCoordinator::afterUserCommitted($userId)`**: **`GameHotDataRedis::userReplaceCacheFromDb`** aligns with DB, then enqueues idempotent refresh tasks (`GameHotDataWriteQueue` / `GameHotDataQueueConsumer`) for peak shaving—not a substitute for synchronous reload.
|
||
- **Game config**: `game_config` cached by `config_key`. Direct `Db` updates in admin must call **`GameHotDataCoordinator::afterGameConfigKeyCommitted($key)`** (model `GameConfig` events and standalone form controllers wired); standalone save uses **`GameHotDataLock` (`TYPE_GAME_CONFIG`)** per `config_key`. Do not only delete cache keys without reload—max inconsistency window is TTL.
|
||
- **Round**: active round, round by `id`, latest `game_record`, etc.; after write, **`GameHotDataCoordinator::afterGameRecordCommitted`** refreshes Redis keys and enqueues. Draw/lock paths may use **`GameHotDataLock` (`TYPE_GAME_RECORD`)** per record id.
|
||
|
||
**Environment variables (see repo root `.env-example`)**
|
||
|
||
- `GAME_HOT_CACHE_ENABLED`: enable Redis hot cache (`false` = always DB).
|
||
- `GAME_HOT_CACHE_TTL_GAME_CONFIG` / `GAME_HOT_CACHE_TTL_GAME_RECORD` / `GAME_HOT_CACHE_TTL_USER`: TTL seconds; **write-then-sync reload is primary**, TTL is fallback only.
|
||
- `GAME_HOT_CACHE_ENABLE_WRITE_QUEUE` and queue length, consumer interval, etc.: idempotent refresh after write (`config/game_hot_cache.php`).
|
||
|
||
**Consistency notes (integration / testing)**
|
||
|
||
- Scripts that bypass coordinator and only change DB without **`GameHotDataCoordinator`** may be briefly inconsistent with Redis; avoid in production.
|
||
- **`POST /api/game/betPlace`** debit path uses the same **per-user Redis lock** as admin wallet adjust (`GameHotDataRedis::userAdminMutationLockTry`) and **`WHERE coin = ?` conditional update**, mutually exclusive with concurrent payout/admin adjust; on failure returns Chinese messages listed in **§4.2**.
|
||
- Clients may still use **§3.2 `dictionaryList` `version`** for local cache; server dictionary also has Redis acceleration—both can coexist.
|
||
|
||
---
|
||
|
||
## 2. Auth & Account Module (`user`)
|
||
|
||
### 2.1 Register
|
||
- **POST** `/api/user/register`
|
||
- Purpose: phone-only registration with invite attribution (admin/channel)
|
||
|
||
Request parameters:
|
||
- `username`: string, phone number (registration account; mainland China mobile only)
|
||
- `password`: string, plaintext over HTTPS (login password; server stores salted hash)
|
||
- `invite_code`: string, required (sub-agent invite code; binds `channel_id` and ownership)
|
||
- `device_id`: string, optional (device id for risk control and login logs)
|
||
|
||
Response parameters:
|
||
- `user-token`: string (session token for login-protected APIs)
|
||
- `refresh_token`: string, optional (refresh access token)
|
||
- `expires_in`: int (seconds, token TTL)
|
||
- `user`: object (non-sensitive fields only; no `id`)
|
||
- `uuid`: string (public user id, 10 chars)
|
||
- `username`: string (nickname/display name)
|
||
- `coin`: string (current balance)
|
||
- `channel_id`: int (attribution channel id)
|
||
- `risk_flags`: int (risk status bitmask)
|
||
|
||
### 2.2 Login
|
||
- **POST** `/api/user/login`
|
||
|
||
Request parameters:
|
||
- `username`: string (login account; currently phone)
|
||
- `password`: string (login password)
|
||
- `device_id`: string, optional (risk assist)
|
||
|
||
Response parameters:
|
||
- `user-token`: string (access token for login-protected APIs)
|
||
- `refresh_token`: string, optional
|
||
- `expires_in`: int (access token remaining seconds)
|
||
- `user`: object (non-sensitive fields only; no `id`)
|
||
- `uuid`: string (public user id, 10 chars)
|
||
- `username`: string (nickname/display name)
|
||
- `coin`: string (current balance)
|
||
- `channel_id`: int (attribution channel id)
|
||
- `risk_flags`: int (risk status bitmask)
|
||
|
||
### 2.3 Current User Profile
|
||
- **POST** `/api/user/profile`
|
||
|
||
Response parameters (amount fields as 2-decimal strings, aligned with wallet display):
|
||
|
||
**Basic profile**
|
||
- `uuid`: string (public user id, 10 chars)
|
||
- `username`: string (nickname)
|
||
- `head_image`: string (avatar URL)
|
||
- `phone`: string (mobile)
|
||
- `email`: string (email)
|
||
- `register_invite_code`: string (invite code snapshot at registration)
|
||
- `channel_id`: int (attribution channel id)
|
||
- `risk_flags`: int (risk status bitmask)
|
||
- `current_streak`: int (current win streak count)
|
||
- `last_bet_period_no`: string (period no of last valid bet)
|
||
- `create_time`: int (registration timestamp)
|
||
|
||
**Funds & withdraw quota**
|
||
- `coin` / `coin_balance`: string (current balance; same value)
|
||
- `frozen_balance`: string (frozen balance; fixed `0.00` when none)
|
||
- `total_deposit_coin`: string (lifetime deposits)
|
||
- `total_withdraw_coin`: string (lifetime withdraws; incremented after acceptance)
|
||
- `bet_flow_coin`: string (bet flow / turnover; after settlement, +`total_amount` per bet 1:1)
|
||
- `max_withdrawable`: string (**max single withdraw allowed now** = `min(coin_balance, max_withdraw_by_flow)`)
|
||
- `withdraw_flow`: object (bet-flow / withdraw quota diagnostic snapshot; includes `pending_withdraw`)
|
||
- `ratio`: string (bet-flow multiplier; `0` = unlimited)
|
||
- `net_deposit`: string (net deposit = max(0, total deposit − total withdraw))
|
||
- `required_bet_flow`: string (required bet flow by threshold rule; display only)
|
||
- `remaining_bet_flow`: string (remaining bet flow by threshold; display only)
|
||
- `eligible`: bool (meets overall threshold; display only; actual gate is `max_withdrawable`)
|
||
- `max_withdraw_by_flow`: string/null (cap from bet flow only; `null` when `ratio=0`)
|
||
- `flow_unlimited`: bool (unlimited bet-flow mode)
|
||
- `pending_withdraw`: object
|
||
- `count`: int (pending-review withdraw orders)
|
||
- `max`: int (max pending-review withdraws per user, currently `3`; exceeds → `withdrawCreate` returns `code=2004`)
|
||
|
||
### 2.4 Refresh Token (Optional)
|
||
- **POST** `/api/user/refreshToken`
|
||
|
||
Request parameters:
|
||
- `refresh_token`: string (credential to renew access token)
|
||
|
||
Response parameters:
|
||
- `user-token`: string (new access token)
|
||
- `expires_in`: int (new token TTL)
|
||
|
||
---
|
||
|
||
## 3. Game Lobby & Dictionary Module (`game`/`lobby`)
|
||
|
||
### 3.1 Lobby Init
|
||
- **POST** `/api/game/lobbyInit`
|
||
- Purpose: one-shot current round, config, 36 zihua dictionary, user quick display
|
||
|
||
Response parameters:
|
||
- `server_time`: int (server time for client clock sync)
|
||
- `runtime_enabled`: bool (**game runtime switch**; `false` = admin maintenance—**no new bets**, idle won’t auto-create periods, post-payout won’t auto-create next; **current open round still draws, pays out, and settles**. Mobile should disable bet entry and show maintenance copy)
|
||
- `period`: object
|
||
- `period_no`: string (global period number)
|
||
- `status`: string (`betting`/`locked`/`settling`/`finished`/`void`; `void` = period voided)
|
||
- `countdown`: int (countdown seconds)
|
||
- `lock_at`: int (lock timestamp)
|
||
- `open_at`: int (expected draw timestamp)
|
||
- `bet_config`: object
|
||
- `pick_max_number_count`: int (max numbers per bet; from `game_config.config_key = pick_max_number_count`; default matches seed, usually 10; range 1–36)
|
||
- `chips`: object (quick chip map; fixed keys `"1"`…`"6"`, values are per-number stake strings, 2 decimals; same as admin `game_config.bet_chips`)
|
||
- `default_bet_chip_id`: int (default chip id from `game_config.default_bet_chip_id`; invalid → first valid chip)
|
||
- `min_bet_per_number`: string (min per number; ≤ selected chip and admin limits)
|
||
- `max_bet_per_number`: string (max per number)
|
||
- `dictionary`: array<object>
|
||
- `number`: int (1-36, zihua number)
|
||
- `name`: string (zihua name)
|
||
- `category`: string (category)
|
||
- `icon`: string (icon URL)
|
||
- `user_snapshot`: object (user snapshot + **odds for current player this round**; no full 1–10 table)
|
||
- `coin`: string (balance)
|
||
- `current_streak`: int (current win streak)
|
||
- `streak_level`: int (streak tier 1–10 if win this round: `min(current_streak+1, 10)`)
|
||
- `odds_factor`: int (odds multiplier; payout = bet `total_amount` × `odds_factor`)
|
||
- `is_jackpot`: bool (jackpot tier)
|
||
|
||
### 3.2 36 Zihua Dictionary (Cacheable)
|
||
- **POST** `/api/game/dictionaryList`
|
||
|
||
Response parameters:
|
||
- `version`: string (dictionary version for client cache compare)
|
||
- `items`: same as `dictionary` (36 zihua entries)
|
||
|
||
## 4. Betting & Round Module (`game`/`bet`)
|
||
|
||
### 4.1 Current Period Detail
|
||
- **POST** `/api/game/periodCurrent`
|
||
|
||
Response parameters:
|
||
- `runtime_enabled`: bool (same as `lobbyInit.runtime_enabled`)
|
||
- `period_id`: int (current period primary key)
|
||
- `period_no`: string (current period number)
|
||
- `status`: string (includes `void`)
|
||
- `countdown`: int (remaining seconds)
|
||
- `bet_close_in`: int (seconds until lock)
|
||
- `result_number`: int/null (null before draw)
|
||
|
||
### 4.2 Place Bet
|
||
- **POST** `/api/game/placeBet` (legacy path `/api/game/betPlace` supported)
|
||
- Purpose: manual bet per period; player sends **picked numbers** and **chip id `bet_id` (1–6)**. Stake per number from `game_config.bet_chips`; server debits `per-number amount × count(numbers)` as `total_amount`. One winning number per round; win if that number ∈ picked set.
|
||
|
||
Request parameters:
|
||
- `period_no`: string (target period)
|
||
- `numbers`: string (comma-separated picks, e.g. `1,8,16`; each 1–36; count ≤ `pick_max_number_count`; duplicates deduped)
|
||
- `bet_id`: int (quick chip 1–6; must exist in `lobbyInit.bet_config.chips`; **`single_bet_amount` / `bet_amount` not used**)
|
||
- `idempotency_key`: string, required
|
||
|
||
Response parameters:
|
||
- `order_no`: string (bet order no)
|
||
- `period_no`: string (actual period)
|
||
- `status`: string (`accepted`/`rejected`)
|
||
- `bet_id`: int (chip used)
|
||
- `single_bet_amount`: string (from `bet_id`)
|
||
- `numbers_count`: int (number count)
|
||
- `locked_balance`: string, optional (frozen amount)
|
||
- `balance_after`: string (balance after order)
|
||
- `current_streak`: int (streak snapshot after order)
|
||
|
||
**Additional possible error codes** (see header ranges; debit/cache consistency):
|
||
|
||
- `3001`: game paused (`runtime_enabled=false`, admin live switch off or void without restart; same band as flow errors)
|
||
- `5000`: system busy; or **user Redis lock** not acquired (same serial as admin wallet/concurrent writes: 「该用户正在被其他管理员操作（钱包/并发保存），请稍后再试」); or **`coin` conditional update** miss (concurrent bet/payout/admin: 「扣款失败：该用户余额已被其他请求修改（如下注、派彩或其他管理员已保存），请刷新后重试」).
|
||
|
||
### 4.3 Auto Spin
|
||
- **POST** `/api/game/autoSpin`
|
||
|
||
Request parameters:
|
||
- `action`: string (`start`/`stop`)
|
||
- `period_no`: string (required when `action=start`)
|
||
- `numbers`: string (required when `action=start`, comma-separated)
|
||
- `bet_id`: int (required when `action=start`; same as `placeBet`, chips 1–6)
|
||
- `rounds`: int (required when `action=start`, >=1)
|
||
|
||
Response parameters:
|
||
- `status`: string (`scheduled`/`stopped`)
|
||
- `auto_mode`: bool
|
||
- `bet_id`: int (`start` only)
|
||
- `single_bet_amount`: string (`start` only, from `bet_id`)
|
||
- `remaining_rounds`: int (`start` only)
|
||
|
||
### 4.4 My Bet Orders (Last 1 Month)
|
||
- **POST** `/api/game/betMyOrders`
|
||
|
||
Request parameters:
|
||
- `page`: int, optional, default 1
|
||
- `page_size`: int, optional, default 20
|
||
|
||
Response parameters:
|
||
- `list`: array<object>
|
||
- `order_no`: string
|
||
- `period_no`: string
|
||
- `numbers`: array[int]
|
||
- `bet_amount`: string (same as `total_amount`)
|
||
- `total_amount`: string
|
||
- `result_number`: int/null
|
||
- `win_amount`: string
|
||
- `status`: string
|
||
- `create_time`: int
|
||
- `pagination`: object (`page`, `page_size`, `total`)
|
||
|
||
---
|
||
|
||
## 5. Wallet & Finance Module (`wallet`/`finance`)
|
||
|
||
### 5.1 Balance Sync (Standalone Summary Removed)
|
||
- Removed `/api/wallet/balanceSummary`.
|
||
- Balance sync sources:
|
||
- `placeBet.balance_after`
|
||
- WebSocket `wallet.changed`
|
||
- Deposit/withdraw detail APIs (`depositDetail` / `withdrawDetail`) for order-level reconciliation
|
||
- Multiplier `ratio` from admin **Game Config → `withdraw_bet_flow_ratio`**; effective immediately on new requests.
|
||
- Lifetime fields (`total_deposit_coin` / `total_withdraw_coin` / `bet_flow_coin`) are cumulative; rejections reversed by admin review flow.
|
||
|
||
### 5.2 Wallet Records
|
||
- **POST** `/api/wallet/recordList`
|
||
|
||
Request parameters:
|
||
- `page`: int, optional, default 1
|
||
- `page_size`: int, optional, default 20
|
||
- `type`: string, optional (filter; omit = all):
|
||
- `deposit`: deposit credit
|
||
- `withdraw`: withdraw debit/freeze
|
||
- `bet`: bet debit
|
||
- `payout`: draw payout credit
|
||
- `adjust`: manual adjust (`biz_type=admin_credit/admin_deduct`)
|
||
- `bet_void`: period void refund (admin live void pending bets)
|
||
|
||
Response parameters:
|
||
- `list`: array<object>
|
||
- `record_id`: int
|
||
- `biz_type`: string
|
||
- `direction`: int (1 in, 2 out)
|
||
- `amount`: string
|
||
- `balance_before`: string
|
||
- `balance_after`: string
|
||
- `ref_type`: string
|
||
- `ref_id`: string
|
||
- `create_time`: int
|
||
|
||
Notes:
|
||
- Amount fields display with two decimals on client.
|
||
- Admin credit/deduct creates `biz_type=admin_credit/admin_deduct` records; default remark template: `后台管理员（操作管理员）加点/扣点100（值）` (example).
|
||
|
||
### 5.3 Deposit Tier List
|
||
- **POST** `/api/finance/depositTierList`
|
||
|
||
Notes:
|
||
- Maintained in admin **Config → Deposit Tiers**, stored in `game_config.deposit_tier` (JSON array).
|
||
- Admin “pay currency” dropdown from `game_config.finance_cashier.currencies` (not hardcoded).
|
||
- Init/rebuild: **6 tiers per currency** from `finance_cashier` (ops may edit).
|
||
- Only `status=1` tiers, sorted by `sort`.
|
||
- Tiers describe recharge spec only; collection via third-party `pay_url`.
|
||
- **i18n**: admin stores `title`, `title_en`, `desc`, `desc_en`. API `title` / `desc` follow `lang`:
|
||
- `lang=zh` (default): `title` / `desc`, fallback to English if empty
|
||
- `lang=en`: `title_en` / `desc_en`, fallback to Chinese if empty
|
||
- Mobile sees single `title` / `desc` only
|
||
|
||
Request parameters: none
|
||
|
||
Response parameters:
|
||
- `list`: tier list; each item:
|
||
- `id`: string (stable tier id; pass as `tier_id`; same as `tier_key`)
|
||
- `tier_key`: string (same as `id`, legacy)
|
||
- `title`: string (localized by `lang`)
|
||
- `currency`: string (e.g. `CNY`)
|
||
- `pay_amount`: string (2 decimals, list price)
|
||
- `amount`: string (2 decimals, amount user pays)
|
||
- `bonus_amount`: string (2 decimals, bonus; `0.00` if none)
|
||
- `total_amount`: string (2 decimals, `amount + bonus_amount`)
|
||
- `desc`: string (localized; may be empty)
|
||
- `channels`: array (for `depositCreate` `channel_code`; all enabled channels compatible with all tiers)
|
||
- each: `code`, `name`, `sort`
|
||
|
||
### 5.3A Deposit / Withdraw Config
|
||
- **POST** `/api/finance/depositWithdrawConfig`
|
||
- Legacy: `POST /api/finance/cashierConfig` (same shape; prefer `depositWithdrawConfig`)
|
||
|
||
Purpose:
|
||
- One-shot recharge/withdraw page config: currencies, rates, deposit channels, withdraw banks, limits, copy.
|
||
|
||
Response parameters:
|
||
- `platform_coin_label`: string (localized)
|
||
- `currencies`: array
|
||
- `code`, `label`, `deposit_coins_per_fiat`, `withdraw_coins_per_fiat`
|
||
- `rates`: array (compat)
|
||
- `currency`, `diamonds_per_fiat_unit`
|
||
- `pay_channels`: array (deposit)
|
||
- `code`, `name`, `sort`, `status` (1=enabled), `tier_ids` (compat; empty = all tiers)
|
||
- `withdraw`: object
|
||
- `pay_channels`: array (for `withdrawCreate` `channel_code`; enabled + server-integrated only)
|
||
- `banks`: array
|
||
- `min_ewallet`, `min_bank`, `rate_hint`, `processing_note`, `fee_note`
|
||
- `rate_mode`: `fixed` / `live`
|
||
- `fields`: object (**aligned with DDPay / `withdrawCreate`**; not admin cashier toggles)
|
||
- `receive_type_bank_only`: bool (fixed `true`, bank only)
|
||
- `require_channel_code`: bool (`true`, `channel_code`)
|
||
- `require_receiver_name`: bool (`true`, `receiver_name`)
|
||
- `require_receive_account`: bool (`true`, `receive_account`)
|
||
- `require_receiver_email`: bool (`true`, `receiver_email`)
|
||
- `require_receiver_mobile`: bool (`true`, `receiver_mobile`)
|
||
- `require_bank_code`: bool (`true`, `bank_code`)
|
||
- `require_bank_branch`: bool (`false`, optional; server sends `N/A` to DDPay if omitted)
|
||
|
||
### 5.4 Create Deposit Order
|
||
- **POST** `/api/finance/depositCreate`
|
||
- `Content-Type: application/json` (recommended), `application/x-www-form-urlencoded`, or **`multipart/form-data`**; same field names; server reads unified param names.
|
||
|
||
Notes:
|
||
- **Mock pay (integration)**: `channel_code=mock`, no DDPay merchant; returns `pay_url` (**mock cashier** `GET /api/finance/mockDepositPage`, **3 min** TTL). User confirms → **`pending_review`**; credit after admin approves in **Deposit Orders**.
|
||
- Optional **`GET/POST /api/finance/mockDepositPay`** (login + same `auth-token`): in-app confirm (either cashier or this; idempotent).
|
||
- **DDPay**: `channel_code=ddpay`; pending order then DDPay deposit API; on success `pay_url=payment_url`.
|
||
- Switch: `FINANCE_MOCK_PAY_ENABLED` (default on in dev); off → `mock` unavailable.
|
||
- Settlement: **`POST /api/finance/ddpayDepositNotify`** verified, or sync `transaction_status=completed`; **`mock`** credits only after admin approval.
|
||
- Tiers/channels from `depositTierList`.
|
||
- Max 3 pending deposit orders per user; unpaid orders fail after `DEPOSIT_PENDING_EXPIRE_SECONDS` (default **60s**, `.env`); pay link countdown matches.
|
||
|
||
Request parameters:
|
||
|
||
**A. Common required**
|
||
- `tier_id`: string, required (synonym `tier_key`)
|
||
- `channel_code`: string, required, `mock` or `ddpay`
|
||
- `idempotency_key`: string, required, ≤64
|
||
|
||
**A.1 Mock (`channel_code=mock`)**
|
||
- No `payment_type` / `payer_name` / `payer_bank_name`
|
||
|
||
**B. DDPay required (`channel_code=ddpay`)**
|
||
|
||
> Per DDPay official *Payment Gateway* (`docs/DDPay Payment Gateway_v1.1.3_zh.md` / PDF).
|
||
|
||
- `payment_type`: string, required (**official enum §3.1**): **`01`** FPX, **`02`** duitnow, **`03`** ewallet; confirm other values with DDPay support.
|
||
- Alias: `paymentType`
|
||
- **Note**: values like `FPX`, `duitnow` may be rejected; send **`01` / `02` / `03`**.
|
||
- `payer_name`: string, required (account holder name)
|
||
- Alias: `payerName`
|
||
- `payer_bank_name`: string, required (**`payer_bank[name]`**; full name from DDPay bank list)
|
||
- **MYR**: English full name from deposit bank list (e.g. `Public Bank`, `Maybank2U`); **THB**: THB list English full name. Mismatches may be rejected.
|
||
- Aliases: `payer_bank[name]`, `payerBankName`
|
||
|
||
**B.1 Server-only DDPay fields (integration reference)**
|
||
|
||
Mobile must not send; server fills on deposit API:
|
||
|
||
- `client_id`, `identifier` (if `DDPAY_IDENTIFIER` set), `order_id` (= `order_no`)
|
||
- `transaction_amount`: tier **`pay_amount`** (Decimal); currency per DDPay onboarding (docs often MYR; use your merchant currency).
|
||
- `callback_url`, `redirect_url`: from **`DDPAY_PUBLIC_BASE_URL`** (`.env-example`) or request `Host`; production **HTTPS**.
|
||
|
||
> **Common `1001` (DDPay)**: missing `payment_type` / `payer_name` / `payer_bank_name`; or `payment_type` not `01/02/03`.
|
||
|
||
Example (DDPay, MYR + FPX):
|
||
```json
|
||
{
|
||
"tier_id": "t_xxxxxxxx",
|
||
"channel_code": "ddpay",
|
||
"idempotency_key": "dp_20260429_xxx",
|
||
"payment_type": "01",
|
||
"payer_name": "ZHANG SAN",
|
||
"payer_bank_name": "Public Bank"
|
||
}
|
||
```
|
||
|
||
Response parameters:
|
||
- `order_no`, `amount`, `bonus_amount`, `total_amount`, `pay_channel`, `paid`, `pay_url`, `review_required`, `reject_reason`, `expire_at`, `expire_seconds`, `status` (`pending` / `pending_review` / `paid` / `failed`), `create_time`, `pay_time`
|
||
|
||
#### 5.4.1 DDPay Callback & Status (Current Implementation)
|
||
|
||
- Callback: `POST /api/finance/ddpayDepositNotify` (**`callback_url`** to DDPay; **HTTPS**).
|
||
- Official webhook fields (§3.5, **verify signature first**):
|
||
|
||
| Param | Description |
|
||
|-------|-------------|
|
||
| `client_id` | Merchant id |
|
||
| `order_id` | Reference (= deposit `order_no`) |
|
||
| `transaction_status` | `pending` / `completed` / `failed` (§4.1) |
|
||
| `timestamp` | Notify time |
|
||
| `transaction_amount` | Paid amount |
|
||
| `signature` | Signature |
|
||
|
||
- After verify:
|
||
- `completed` → settle, `paid`
|
||
- `failed` → `failed`
|
||
- Respond HTTP **200**, body **`{"status":"ok"}`**; up to **6** retries per docs.
|
||
- Without callback, `pending` persists; server may use deposit status query (`query_time` `YYYY-MM-DD HH:MM:SS`); not exposed to mobile yet.
|
||
|
||
Error codes:
|
||
- `1001`: missing `tier_id`/`tier_key`, `channel_code`, `idempotency_key`
|
||
- `1001` (DDPay): missing/invalid DDPay fields
|
||
- `1002`: `idempotency_key` too long or cross-user conflict
|
||
- `2000`: generic DB/settle failure; DDPay API failure → 「DDPay 充值发起失败」, see `deposit_order.remark` (`[ddpay]`) or logs
|
||
- `2003`: invalid/disabled tier
|
||
- `2004`: bad `channel_code`; mock off; ddpay off; currency/channel mismatch
|
||
- `2005`: too many pending (`data.max_pending`, `data.pending_count`, `data.expire_seconds`)
|
||
|
||
### 5.4A Mock Pay (Browser Cashier + Optional App Confirm)
|
||
|
||
- **GET/POST** `/api/finance/mockDepositPage`: HTML cashier (no login; `order_no` required; `pay_channel=mock`, `status=pending`, not expired)
|
||
- **GET/POST** `/api/finance/mockDepositConfirm`: cashier confirm (no login; → **`pending_review`**, no credit)
|
||
- **GET/POST** `/api/finance/mockDepositPay`: app confirm (login; idempotent with above)
|
||
|
||
After admin approves/rejects in **Deposit Orders**, mock order succeeds or fails.
|
||
|
||
### 5.5 Deposit Order Detail
|
||
- **POST** `/api/finance/depositDetail`
|
||
|
||
Request parameters:
|
||
- `order_no`: string, required
|
||
|
||
Response parameters (same as `depositCreate`):
|
||
- `order_no`, `amount`, `bonus_amount`, `total_amount`, `pay_channel`, `paid`, `pay_url`, `review_required`, `reject_reason`, `expire_at`, `expire_seconds`, `status`, `create_time`, `pay_time`
|
||
|
||
### 5.6 Deposit Order List
|
||
- **POST** `/api/finance/depositList`
|
||
|
||
Paged recharge history; use `depositDetail` for full fields.
|
||
|
||
Request parameters:
|
||
- `page`, `page_size` (max `100`, over → `20`)
|
||
|
||
Response parameters:
|
||
- `list`: `order_no`, `amount`, `bonus_amount`, `status`
|
||
- `pagination`: `page`, `page_size`, `total`
|
||
|
||
### 5.7 Withdraw Request
|
||
- **POST** `/api/finance/withdrawCreate`
|
||
|
||
Notes:
|
||
- **DDPay payout only**: `channel_code` must be **`ddpay`** (alias `pay_channel`); else `code=2004`.
|
||
- Channels: `depositWithdrawConfig` → `withdraw.pay_channels`.
|
||
|
||
Request parameters:
|
||
- `channel_code`: string, required (`ddpay`; alias `pay_channel`)
|
||
- `withdraw_coin`: string (> 0)
|
||
- `receive_account`: string (DDPay **`receiver_account`**)
|
||
- `receive_type`: string (`bank` only currently)
|
||
- `idempotency_key`: string
|
||
- `receiver_name`: string (required for `bank`; DDPay **`receiver_name`**)
|
||
- `receiver_email`: string (required, valid email, max 255)
|
||
- `receiver_mobile`: string (required, 5–32, digits and `+` `-` space, ≥5 digits)
|
||
- `bank_code`: string (required for `bank`; from `withdraw_banks[].code` → DDPay **`bank[name]`**)
|
||
- `bank_branch`: string (optional; server sends **`N/A`** if omitted per DDPay)
|
||
|
||
**DDPay Payout field map (§3.2, server assembles after approval)**
|
||
|
||
| Official param | Description |
|
||
|----------------|-------------|
|
||
| `client_id` | Merchant id |
|
||
| `bill_number` | Unique ref (= `order_no`) |
|
||
| `amount` | Payout amount |
|
||
| `receiver_name` | Account holder |
|
||
| `receiver_account` | Account / mobile |
|
||
| `bank[name]` | Full bank name (appendix) |
|
||
| `bank_branch` | Branch; default `N/A` |
|
||
| `callback_url` | HTTPS notify URL |
|
||
| `signature` | MD5 lowercase |
|
||
|
||
Response may include `transaction_fee`, `transaction_total`, `transaction_status`, `remark`, etc.
|
||
|
||
Return parameters:
|
||
- `order_no`, `status` (`pending_review`/`approved`/`rejected`; paid merged into `approved`), `fee_coin`, `actual_arrival_coin`, `risk_review_required`
|
||
|
||
Validation order (first failure wins):
|
||
1. Params & amount (`1001`)
|
||
2. Channel: not `ddpay` → `2004 Withdraw only supports DDPay`; disabled → `2004 Pay channel not available`
|
||
3. Pending limit: `status=0` withdraw orders ≤ 3 → `2004 Too many pending withdraw orders` + `max_pending`, `pending_count`
|
||
4. `coin_balance >= withdraw_coin` → `2001 Insufficient balance`
|
||
5. `withdraw_coin <= max_withdrawable` → `2002 Withdraw exceeds available bet flow` + diagnostic `data`
|
||
6. On success in one transaction:
|
||
- `withdraw_order` with `pay_channel`, amounts, `status=0`, user `channel_id` snapshot, receiver fields
|
||
- `user`: `coin -= withdraw_coin`, `total_withdraw_coin += withdraw_coin` with `WHERE coin >= withdraw_coin`
|
||
- `user_wallet_record`: `biz_type=withdraw`, `direction=2`, `idempotency_key=wd_apply_{order_no}` (freeze semantics)
|
||
|
||
Notes (bet-flow withdraw quota):
|
||
- `max_withdrawable = min(coin_balance, max_withdraw_by_flow)`; each withdraw consumes `withdraw_coin × ratio` quota via `total_withdraw_coin`.
|
||
- `ratio = 0`: unlimited bet-flow; cap = `coin_balance` only.
|
||
- Apply-and-freeze: mobile submit debits `user.coin` immediately; admin **reject** refunds in one transaction.
|
||
- Admin **approve** triggers DDPay payout; payout **fail** auto-refund (`withdraw_refund`), `rejected` (`status=2`).
|
||
- After payout, internal `status=3`; mobile shows `approved`.
|
||
- `withdraw_bet_flow_ratio` in game config; default `1.00`.
|
||
|
||
### 5.8 Withdraw Order Detail
|
||
- **POST** `/api/finance/withdrawDetail`
|
||
|
||
Request parameters:
|
||
- `order_no`: string, required
|
||
|
||
Response parameters:
|
||
- `order_no`, `status`, `withdraw_coin`, `fee_coin`, `actual_arrival_coin`, `receive_type`, `receive_account`, `pay_channel`, `receiver_email`, `receiver_mobile`, `reject_reason`, `create_time`, `review_time`
|
||
|
||
### 5.9 Withdraw Order List
|
||
- **POST** `/api/finance/withdrawList`
|
||
|
||
Paged list; use `withdrawDetail` for fees, actual amount, reject reason.
|
||
|
||
Request parameters:
|
||
- `page`, `page_size` (max `100`)
|
||
|
||
Response parameters:
|
||
- `list`: `order_no`, `amount`, `status`
|
||
- `pagination`: `page`, `page_size`, `total`
|
||
|
||
---
|
||
|
||
## 6. Notice Module (`operation`/`notice`)
|
||
|
||
### 6.1 Notice List
|
||
- **GET** `/api/notice/noticeList`
|
||
- **Auth**: no `auth-token` or `user-token` (public)
|
||
|
||
Request parameters (query):
|
||
- `page`, `page_size`
|
||
|
||
Response parameters:
|
||
- `list`: array<object>
|
||
- `notice_id`, `title`, `content`, `notice_type` (`silent`/`popout`), `must_confirm`, `is_read` (**popout only**; `silent` always `false`, no read record), `publish_time`
|
||
|
||
> **Read records**: `user_notice_read` only for popout confirm; silent mailbox never writes/reads records.
|
||
|
||
### 6.2 Popout Confirm Read
|
||
- **GET** `/api/notice/noticeConfirm`
|
||
|
||
Request parameters (query):
|
||
- `notice_id`: int
|
||
|
||
Behavior:
|
||
- **Popout only**; silent returns business error
|
||
- Existing record: update `read_at`; if unconfirmed, set `confirmed=1`
|
||
- No record: create confirmed record
|
||
|
||
Response parameters:
|
||
- `notice_id`, `confirmed`, `confirm_time`
|
||
|
||
---
|
||
|
||
## 7. WebSocket (H5) & State Sync
|
||
|
||
> This version removed webman/push channel mode; H5 uses native WebSocket; HTTP polling is weak-network fallback only.
|
||
|
||
### 7.0 Deployment & Connection Prerequisites (Current Implementation)
|
||
|
||
Aligned with `app/process/GameWebSocketServer.php`, `config/process.php`, `app/common/library/admin/WebSocketConfigHelper.php`:
|
||
|
||
- **Dedicated process**: run Webman process **`gameWebSocketServer`** (`config/process.php`), default **`H5_WEBSOCKET_LISTEN`** (`websocket://0.0.0.0:3131`). Without it, clients cannot connect.
|
||
- **URL**: prefer **`H5_WEBSOCKET_URL`** (full `ws://` / `wss://`, with path per `.env-example`). **Do not use `127.0.0.1` / `localhost` in production** for browser clients. Loopback in `.env` with external HTTP Host → `WebSocketConfigHelper` ignores config and derives `ws(s)://{host}/ws/`. Admin **`GET /admin/test.GameCurrentStatus/wsConfig`**, **`GET /admin/game.Live/wsConfig`** same; local fallback **`ws://127.0.0.1:3131/ws/`**. HTTPS sites need reverse proxy **`/ws/`** → port **3131**.
|
||
- **Mobile gap**: **`POST /api/game/lobbyInit` does not return WebSocket URL**; H5 must use ops/bundle `H5_WEBSOCKET_URL` or remote config (may differ from HTTP API host).
|
||
- **Mixed content**: HTTPS pages require **`wss://`**.
|
||
- **Redis event bus**: HTTP uses **`GameWebSocketEventBus`** (Redis list); if Redis down, broadcast pushes may fail except **`admin.live.snapshot`** has per-second direct snapshot fallback.
|
||
- **Handshake auth (2026-05, mandatory)**: `GameWebSocketServer::onWebSocketConnect` via `GameWebSocketAuthHelper::authorize` on URL query:
|
||
- **mobile**: query **`auth-token`** + **`user-token`** (hyphenated; legacy `auth_token`/`user_token` parsed but **use hyphens for new clients**). Binds `user_id`; user topics only to owner.
|
||
- **admin**: query **`admin-ws-token`** (from admin `wsConfig`, Redis, TTL 7200s). `user_id=0`, full observability.
|
||
- Failure → `{"event":"ws.error","code":1101,"message":"Authentication failed: ..."}` then `close`.
|
||
- **Server filter (user topics)**: `bet.win`, `user.streak`, `wallet.changed`, `bet.accepted`, `auto.spin.progress` only if `data.user_id` equals connection `user_id`. Others broadcast by subscription. Admin mode not filtered.
|
||
- **Idle timeout**: no uplink (incl. `ping`/`subscribe`) for 60s → server `close`.
|
||
- **Log channel `ws`**: `runtime/logs/ws.log` (7 days): enqueue, dispatch, handshake, subscribe, pong, idle close, send failures.
|
||
- **Subscribe required**: after connect, only handshake + subscribed topics; no `subscribe` → no `period.tick` etc.
|
||
|
||
### 7.1 WebSocket Connection & Messages
|
||
|
||
- **URL**: §7.0 (`H5_WEBSOCKET_URL` or admin `ws_url`)
|
||
- **Client**: browser `WebSocket` (`ws://` / `wss://`)
|
||
- **Required query (2026-05+)**:
|
||
- **H5/mobile**: `auth-token` + `user-token`. Optional: `device_id`, `lang`.
|
||
- **Admin**: `admin-ws-token` (in `ws_url`).
|
||
- Examples:
|
||
- H5: `wss://ws.example.com/ws/?auth-token=xxx&user-token=yyy&device_id=ios_001&lang=zh`
|
||
- Admin: `wss://ws.example.com/ws/?admin-ws-token=zzz`
|
||
- Missing/invalid → `ws.error` `1101` then close.
|
||
- **First frame on connect**:
|
||
- `event`: `ws.connected`
|
||
- `message`: `WebSocket connected`
|
||
- `connection_id`, `mode` (`mobile` | `admin`; **no** `user_id`)
|
||
- `server_time` (seconds, int)
|
||
- `heartbeat_interval` (30)
|
||
- `idle_timeout` (60; send `ping` within `idle_timeout - heartbeat_interval`)
|
||
- **Error frames** (not HTTP `code` band):
|
||
- Bad JSON: `ws.error`, `Invalid JSON payload`
|
||
- Unknown `action`: `ws.error`, `Unsupported action`, maybe `received_action`
|
||
- Process error: `ws.error`, `Server internal error`, Workerman `code`/`detail`
|
||
- **Suggested messages**:
|
||
- Heartbeat: `{"action":"ping"}`
|
||
- Pong: `{"event":"pong","server_time":"YYYY-mm-dd HH:ii:ss"}` (**string** local time; business pushes often use int seconds—branch in client)
|
||
- Subscribe: `{"action":"subscribe","topics":["period.tick"]}`
|
||
- Streak/odds: `["user.streak","wallet.changed","bet.accepted"]`
|
||
- Funds: `["bet.accepted","wallet.changed"]`
|
||
- Auto spin: `["auto.spin.progress","wallet.changed"]`
|
||
- Recommended mobile set: `period.tick`, `bet.win`, `user.streak`, `wallet.changed`, `bet.accepted`, `period.opened`, `period.payout`, `jackpot.hit`
|
||
|
||
#### 7.1.1 Message Protocol Fields
|
||
|
||
- Client → server:
|
||
- `action`: `ping` / `subscribe`
|
||
- `topics`: required for `subscribe` (array)
|
||
- Server → client:
|
||
- `event`, `topic`, `data`, `server_time` (seconds)
|
||
|
||
#### 7.1.2 Subscribe Behavior
|
||
|
||
- **Connection alone does not stream all business events**; send `subscribe`.
|
||
- Success: `{"event":"ws.subscribed","topics":[...]}` (deduped, sorted).
|
||
- **`subscribe` replaces** the whole subscription set (not append).
|
||
- Without subscription: handshake + `pong` only.
|
||
- **Server filters by bound user** on mobile; outbound **`data` has no `user_id`** (and other sensitive fields).
|
||
- **Outbound redaction (2026-05)**: removes `user_id`, `uuid`, `phone`, `balance_before`, `channel_id`; `jackpot.hit` `hits[]` keeps `nickname`, `period_no`, `total_win`, `result_number`, etc.
|
||
- **No** full `streak_win_reward` table; odds via `user.streak` / `wallet.changed` / `bet.accepted` and `lobbyInit.user_snapshot`.
|
||
|
||
#### 7.1.2A Streak Odds & Streak Count (WebSocket)
|
||
|
||
- **`user.streak`** (after settlement; current player odds):
|
||
- `data.current_streak`, `streak_level`, `odds_factor`, `is_jackpot`
|
||
- **`wallet.changed` / `bet.accepted` / `bet.win`**: merge **`current_streak`**, **`streak_level`**, **`odds_factor`**, **`is_jackpot`** (no `user_id`).
|
||
- **`bet.accepted` vs `bet.win` `is_jackpot`**: `bet.accepted` = tier at bet time; **`bet.win` authoritative** for settlement jackpot tier (`streak_at_bet` → `streak_win_reward.is_jackpot=true`, usually tier 10).
|
||
|
||
#### 7.1.3 Push Frequency & Triggers (Current)
|
||
|
||
- `period.tick`: **only when `status ∈ {betting, locked}`**, once per second (no full odds table).
|
||
- **Payout silence**: no `period.tick` during `status=payouting`; instead **`period.payout.tick`** per second with `payout_remaining_seconds` / `payout_until`. Wins via `period.opened` / `period.payout` / **`bet.win`** / `jackpot.hit` / `wallet.changed(biz_type=payout)`.
|
||
- **Boundary (once per period)**:
|
||
- `status=finished`: one frame when payout grace ends.
|
||
- `status=void`: one frame on void.
|
||
- **Resume**: new period `betting` restarts ticks.
|
||
- Dedup: Redis `dfw:v1:ws:tick:boundary:{period_no}:{status}` (TTL 300s).
|
||
- `user.streak`: per user after settlement (may reset to 0).
|
||
- `admin.live.snapshot`: every second (admin live page; not affected by payout silence).
|
||
- `period.opened` / `period.payout` / `admin.live.opened`: event-driven.
|
||
- `wallet.changed`: on balance change; payout includes `amount`, `period_no`, `period_id`, `result_number`.
|
||
- **`bet.win` (wins this period, small + jackpot)**:
|
||
- After settlement, aggregated per winning user (same batch as `wallet.changed(payout)`); **personal win UI listens here**; style via `data.is_jackpot`. Jackpot users still get `bet.win`; don’t rely only on `jackpot.hit`.
|
||
- Fields: `period_id`, `period_no`, `result_number`, `total_win`, `balance_after`, `bets[]` `{ bet_id, win_amount }`, **`is_jackpot`**, **`is_win`** (`true`), **`payout_pending_review`** (jackpot admin review pending), merged streak fields, `server_time`.
|
||
- Dedup: `dfw:v1:ws:betwin:{period_id}:{user_id}` (86400s), separate from `dfw:v1:settle:notify:{period_id}`. Payload rebuilt from DB settled orders if memory aggregate empty.
|
||
- **Compensation**: `buildBetWinPayloadsFromSettledOrders` if needed.
|
||
- After **`approveJackpot`**: pushes `bet.win` again post-credit.
|
||
- **`jackpot.hit` (public jackpot broadcast)**:
|
||
- After **`bet.win`** in same batch, if jackpot-tier hits exist, one public frame for marquee; else skip. **Personal UI still `bet.win`**.
|
||
- Order: `bet.win` per user → `jackpot.hit` if applicable.
|
||
- `hits[]`: `nickname`, `period_no`, `total_win`, `result_number` (no `user_id`).
|
||
|
||
#### 7.1.4 Settlement Push Dedup & Ops Republish (2026-05)
|
||
|
||
| Redis Key | Purpose |
|
||
|-----------|---------|
|
||
| `dfw:v1:settle:notify:{period_id}` | Once per period: `user.streak` / settlement-batch `wallet.changed` / `jackpot.hit` |
|
||
| `dfw:v1:ws:betwin:{period_id}:{user_id}` | Once per user per period: `bet.win` |
|
||
|
||
**Ops republish** (settled win but client missed `bet.win`):
|
||
|
||
```bash
|
||
php scripts/republish_bet_win.php --play-record-id=1370
|
||
php scripts/republish_bet_win.php --period-id=123
|
||
php scripts/republish_bet_win.php --period-no=20260526-183418-c9c90ef1
|
||
# force ignore dedup: add --force
|
||
```
|
||
|
||
Integration: `php scripts/verify_ws_topic_subscribe.php`.
|
||
|
||
### 7.1A Admin Connection (Ops Integration)
|
||
|
||
- Menus: `连接服务器websocket` (test), **Game Management → Live Game** (`/admin/game/live`)
|
||
- WS config:
|
||
- `/admin/test.GameCurrentStatus/wsConfig`
|
||
- `/admin/game.Live/wsConfig` (auto subscribe incl. `admin.live.snapshot`, `bet.win`)
|
||
- **HTTP snapshot**: `GET /admin/game.Live/snapshot` read-only (`buildSnapshot`); **no** `recoverLiveRoundState` / auto-draw on this endpoint; progression via **`gameLiveTicker`** and draw flow.
|
||
- Admin page: `ws_url`, `connect_tip`, `sample_messages`; connect/disconnect; manual subscribe/ping; live frame log.
|
||
|
||
### 7.2 HTTP Fallback APIs
|
||
|
||
- Removed: `/api/game/currentStatus`, `/api/game/periodHistory`, `/api/wallet/balanceSummary`.
|
||
- State/balance primarily WebSocket; HTTP for actions/details (`placeBet`, `depositDetail`, `withdrawDetail`).
|
||
|
||
### 7.3 Consistency Rules
|
||
|
||
- Countdown from server time, not local clock drift.
|
||
- After bet, trust `placeBet.balance_after` and `wallet.changed`.
|
||
- On disconnect, reconnect and resubscribe; no `currentStatus`/`periodHistory`/`balanceSummary` backfill.
|
||
|
||
---
|
||
|
||
## 8. Mobile End-to-End Call Flows
|
||
|
||
## 8.1 First Game Entry
|
||
1. `GET /api/v1/authToken?secret=xxx×tamp=xxx&device_id=xxx&signature=xxx` → `auth-token`
|
||
2. `POST /api/user/login` (header `auth-token`)
|
||
3. `POST /api/game/lobbyInit` (header `auth-token`)
|
||
4. WebSocket base URL (**not in lobbyInit today**: ops/bundle `H5_WEBSOCKET_URL` or custom config) → connect, **send `subscribe` immediately** (§7.0/7.1; **include `bet.win`**)
|
||
5. `POST /api/game/placeBet`
|
||
6. Balance: `placeBet.balance_after` + `wallet.changed`; after draw, **`bet.win`** (`is_win=true`), jackpot style via `data.is_jackpot` (no `user_id` in payload)
|
||
7. On disconnect/foreground, reconnect and resubscribe
|
||
|
||
## 8.2 Deposit → Bet → Withdraw
|
||
1. `POST /api/finance/depositTierList` (pick tier + `channels[].code`)
|
||
2. `POST /api/finance/depositCreate` (`tier_id` + **`channel_code=ddpay`** + `idempotency_key` + DDPay fields; JSON / form-data / urlencoded)
|
||
- `paid=false`, `status=pending`, non-empty `pay_url`: open **`pay_url`** (DDPay `payment_url`); credit via **`ddpayDepositNotify`**; poll `depositDetail` or `wallet.changed`
|
||
3. Optional `POST /api/finance/depositDetail`
|
||
4. `POST /api/game/placeBet`
|
||
5. `wallet.changed` or order detail
|
||
6. `POST /api/wallet/recordList`
|
||
7. `POST /api/finance/withdrawCreate` (immediate freeze) → `POST /api/finance/withdrawDetail`
|
||
|
||
## 8.3 Popout Notice Flow
|
||
1. Client listens `notice.popout`
|
||
2. `GET /api/notice/noticeList` (includes `content`, `must_confirm`)
|
||
3. User confirms `GET /api/notice/noticeConfirm?notice_id=...`
|
||
4. Frontend may block bet until confirmed
|
||
|
||
---
|
||
|
||
## 9. Game Sequence (WebSocket + HTTP)
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[User login /api/user/login] --> B[Lobby init /api/game/lobbyInit]
|
||
B --> C[Connect WebSocket and subscribe]
|
||
C --> D{0-20s betting window?}
|
||
D -- yes --> E[Place bet /api/game/placeBet]
|
||
E --> F[Wait wallet.changed for balance]
|
||
D -- no --> G[Lock and draw phase]
|
||
G --> H[Server tally and draw]
|
||
H --> I[WebSocket: period.opened / bet.win / wallet.changed etc.]
|
||
I --> J[Reconnect and resubscribe on disconnect]
|
||
J --> C
|
||
```
|
||
|
||
---
|
||
|
||
## 10. Admin Agent Commission Config (Admin Supplement, 2026-05-29)
|
||
|
||
> Commission rates are maintained in **Administrator Management** `/admin/auth/admin`, not via the channel page “share ratio” dialog.
|
||
|
||
### 10.1 Page & Display
|
||
|
||
- **Tree table** by `parent_admin_id` (role-group style); expand/collapse
|
||
- Columns: username, nickname, **channel**, **parent agent**, **commission share (%)**, role group, invite code, status, etc.
|
||
- Super-admin public search: **channel dropdown filter**
|
||
- Non-super-admin: **self and all downline agents only**; no peers under other channel roots
|
||
|
||
### 10.2 Form Fields
|
||
|
||
| Field | Description |
|
||
|-------|-------------|
|
||
| `channel_id` | Channel (super-admin selectable; others follow role/account) |
|
||
| `parent_admin_id` | Parent agent; **top-level role group** (`admin_group.pid=0`): empty and disabled |
|
||
| `commission_share_rate` | **Top-level role group**: share of channel period total (0–100), required; **sub-agent**: share from parent’s net amount, required when parent set |
|
||
| `group_arr` | Role group (single select, permissions; top-level when `pid=0`) |
|
||
|
||
### 10.3 Validation & Hints
|
||
|
||
**Top-level role group:**
|
||
|
||
- Parent agent field disabled with hint “no parent required”
|
||
- Share rate required; amount = **channel period total × this rate**
|
||
- Under same `channel_id`, top-level agents’ rates **≤ 100% total**
|
||
- **GET** `/admin/auth.Admin/commissionShareRemainder?is_top_level=1&channel_id=&exclude_id=`
|
||
- Role group linkage: **GET** `/admin/auth.Admin/groupMeta?group_id=`
|
||
|
||
**Sub-agent:**
|
||
|
||
- Under same `parent_admin_id`, sum of enabled children’s `commission_share_rate` **≤ 100%**
|
||
- **GET** `/admin/auth.Admin/commissionShareRemainder?parent_admin_id=&exclude_id=` for remaining allocatable %
|
||
- At 100% total: hint that parent retains no share at this level
|
||
|
||
### 10.4 Settlement Split (Channel Settlement Integration)
|
||
|
||
- After channel settlement total commission, **`AdminCommissionDistributionService`** allocates to top-level agents by `commission_share_rate`, then splits recursively downline
|
||
- Each admin’s net amount → `agent_commission_record` and **immediate credit** to `admin_wallet`
|
||
- At least one channel root agent required; else settlement fails
|
||
|
||
### 10.5 Legacy APIs (Deprecated in UI; Do Not Integrate)
|
||
|
||
- ~~GET `/admin/channel/channelAdminShareList`~~
|
||
- ~~POST `/admin/channel/saveChannelAdminShare`~~
|
||
|
||
---
|
||
|
||
## 11. Open Implementation Decisions (Before API Development)
|
||
|
||
1. **Login**: password only, or SMS/email OTP?
|
||
2. **Withdraw receive types**: bank only v1, or e-wallet/crypto too?
|
||
3. **Auto spin**: ship in v1 or hide `auto-bet` APIs?
|
||
4. **WebSocket topics**: fix topic names and payloads per this doc?
|
||
5. **Error codes**: company-wide table to align with this draft?
|
||
|
||
After confirmation: implement controllers + validate + service + routes per this document.
|