mojiahui/webman-buildadmin

Fork 0

Files

zhenhui e163090bc2 1.ws优化bet.win订阅

2026-05-26 18:44:42 +08:00

67 KiB

Raw Blame History

36字花移动端接口设计草案（V1）

本文基于 docs/36字花-数据库与实施计划.md 与 PRD，先给出移动端可对接的接口清单与字段初设。
口径遵循：全平台单期号、单开奖结果；渠道仅用于归属、分润与风控，不拆分对局。

补充（2026-04）：§1.5 描述服务端 Redis 热点缓存（GameHotDataRedis），不改变各接口 URL、参数与响应字段约定，仅供联调与运维对照。

1. 设计约定

1.1 基础约定

协议：HTTPS + JSON
接口命名规范：/api/{module}/{action}，且必须满足正则 ^/api/[a-z]+/[a-z]+[A-Z][a-zA-Z]*$
请求方法：所有移动端业务接口（/api/*，不含 /api/v1/authToken）一律使用 POST 调用；查询类接口同时兼容 GET（便于浏览器/调试工具直接访问），客户端统一走 POST
- POST 时请求头 Content-Type: application/json，参数放在 JSON body
- GET 兼容模式下，参数走 URL query string
- 例外：公告模块 /api/notice/noticeList、/api/notice/noticeConfirm 仅支持 GET，参数一律走 URL query string
- 公告列表免鉴权：GET /api/notice/noticeList 无需 auth-token、user-token；若仍携带 user-token 则强弹窗项可返回该用户真实的 is_read
- 鉴权类接口 /api/v1/authToken 仍为 GET
时间：UTC 时间戳（秒） + 服务端时区配置
金额：数字传输（如 "100.00"），客户端展示统一保留两位小数（存储仍为 decimal(18,2)）
幂等：关键写接口要求 idempotency_key
请求头（必带）：
- auth-token：通过 GET /api/v1/authToken 获取的接口鉴权令牌（含义：接口访问的签名鉴权凭证）
- user-token：用户登录态令牌；需要登录的接口必带
语言请求头：
- lang=zh：返回中文（默认）
- lang=en：返回英文

1.2 通用响应结构

{
  "code": 1,
  "message": "ok",
  "data": {}
}

code=1 表示成功，非 1 为业务错误
/api/* 所有接口返回文案支持中英双语：默认中文；请求头 lang=en 返回英文，lang=zh 返回中文
建议错误码段（按错误性质）：
- 1000-1099：参数错误（字段缺失、类型错误、格式错误、超范围）
- 1100-1199：鉴权错误（未登录、token 失效、权限不足）
- 2000-2999：业务错误（余额不足、对局不存在、订单不存在、公告不存在）
- 3000-3099：流程错误（非法流程/状态不允许，如封盘后下注、重复确认、状态跃迁非法）
- 5000-5999：系统错误（服务异常、依赖超时、未知错误）
推荐基础错误码（首版）：
1：成功
- 1001：参数缺失
- 1002：参数格式错误
- 1003：参数取值非法
- 1101：未登录或登录已过期
- 1103：无权限操作
- 2001：余额不足
- 2002：对局不存在
- 2003：订单不存在
- 2004：公告不存在
- 3001：当前流程不允许该操作
- 3002：已封盘，禁止下注
- 3003：重复请求（幂等冲突）
- 5000：系统繁忙，请稍后重试

1.3 鉴权方式

接口鉴权（auth-token）：所有移动端业务接口请求时必须携带请求头 auth-token（由 /api/v1/authToken 签发）
用户登录鉴权（user-token）：需要登录的接口携带请求头 user-token；token 失效后调用刷新或重新登录

1.4 获取接口鉴权 Token（auth-token）

GET /api/v1/authToken
用途：获取 auth-token（所有接口请求头必带）

请求示例： /api/v1/authToken?secret=564d14asdasd113e46542asd6das1a2a&timestamp=1776331077&device_id=1&signature=AD84C49880896DBC16C59C7B122D1FF7

请求参数：

secret：string（含义：客户端密钥；服务端从环境变量 AUTH_TOKEN_SECRET 校验）
timestamp：int（含义：请求时间戳；服务端允许与服务器时间误差 ±300 秒）
device_id：string（含义：设备码）
signature：string（含义：签名值）

签名算法：

取参与签名的参数（不含 signature）：device_id、secret、timestamp
按参数名 a-z 排序后拼接为字符串：key=value&key=value...
计算：signature = strtoupper(md5(拼接字符串))

返回参数：

auth_token：string（含义：接口鉴权 token；放到请求头 auth-token）
expires_in：int（含义：有效期秒数）
server_time：int（含义：服务器时间戳，用于校时）

可能错误码：

1001 参数缺失
1002 参数格式错误
1103 密钥无效/签名错误
3001 时间戳无效

1.5 服务端性能与 Redis 热点缓存（实现说明）

对客户端无契约变更：请求路径、参数、响应 JSON 形状与错误码均不因缓存而改变；本节仅说明服务端如何降延迟、读路径与一致性注意点。

与「框架文件缓存」的区别

配置	作用域
`CACHE_DRIVER`（`config/cache.php`，如 `file`）	Think-ORM / `get_sys_config()` 等系统参数表 `config` 的模型缓存，落盘在 `runtime/cache`，不参与本游戏业务热点路径。
`GAME_HOT_CACHE_*`（`config/game_hot_cache.php`）	游戏侧 `user` / `game_config` / `game_record` 行级 JSON 缓存，走 `support\Redis`（`config/redis.php` 连接），键前缀 `dfw:v1:`。

服务端缓存覆盖（与移动端直接相关的读路径）

用户：会员鉴权优先读 Redis 中的 user 行快照，未命中再查库并回填。余额、连胜、打码量等变更落库后，统一经 GameHotDataCoordinator::afterUserCommitted($userId)：先 GameHotDataRedis::userReplaceCacheFromDb 与 DB 对齐，再向 Redis 写队列投递幂等刷新任务（见 GameHotDataWriteQueue / GameHotDataQueueConsumer），用于削峰而非替代同步回源。
游戏配置：game_config 按 config_key 缓存。后台直连 Db 更新时须 GameHotDataCoordinator::afterGameConfigKeyCommitted($key)（模型 GameConfig 事件与独立表单控制器已接入）；独立保存接口在写入前对同一 config_key 使用 GameHotDataLock（TYPE_GAME_CONFIG） 互斥。勿仅删除缓存键而不回源，否则最长不一致窗口为 TTL。
对局：当前活跃局、按 id 的局、最新一条 game_record 等；写库后经 GameHotDataCoordinator::afterGameRecordCommitted 同步刷新相关 Redis 键并入队。开奖/封盘等路径另可按记录 id 使用 GameHotDataLock（TYPE_GAME_RECORD） 串行化。

环境变量（示例见仓库根目录 .env-example）

GAME_HOT_CACHE_ENABLED：是否启用上述 Redis 热点缓存（false 时全程回退数据库）。
GAME_HOT_CACHE_TTL_GAME_CONFIG / GAME_HOT_CACHE_TTL_GAME_RECORD / GAME_HOT_CACHE_TTL_USER：各类缓存 TTL（秒）；以写后同步回源为主，TTL 仅作兜底。
GAME_HOT_CACHE_ENABLE_WRITE_QUEUE 及队列长度、消费进程间隔等：控制写库后的幂等刷新任务是否入队及背压策略（见 config/game_hot_cache.php）。

一致性提示（联调/测试）

任何绕过协调入口、只改 DB 不调用 GameHotDataCoordinator 的手工脚本，都可能与 Redis 短期不一致；生产环境应避免。
POST /api/game/betPlace 扣款路径使用与后台钱包加减点相同的 用户维度 Redis 锁（GameHotDataRedis::userAdminMutationLockTry）及 WHERE coin = ? 条件更新，与并发派彩/后台调账互斥；失败时返回 §4.2 所列中文说明。
客户端仍可按 §3.2 dictionaryList 的 version 做本地缓存；服务端字典另有 Redis 加速，二者可同时存在。

2. 认证与账户模块（user）

2.1 注册

POST /api/user/register
用途：仅手机号注册并绑定邀请归属（admin/channel）

请求参数：

username：string，手机号（含义：注册账号，仅支持大陆手机号）
password：string，明文经 HTTPS 传输（含义：登录密码，服务端需加盐哈希存储）
invite_code：string，必填（含义：子代理邀请码，用于绑定渠道 channel_id 与归属）
device_id：string，可选（含义：设备标识，用于风控与登录记录）

返回参数：

user-token：string（含义：后续接口登录态令牌；用于需要登录的接口请求头）
refresh_token：string，可选（含义：用于刷新访问令牌）
expires_in：int（秒，含义：令牌有效期）
user：object（仅返回非私密信息，不返回 id）
- uuid：string（含义：用户对外唯一标识，10 位）
- username：string（含义：用户昵称/展示名）
- coin：string（含义：当前余额）
- channel_id：int（含义：归属渠道 ID）
- risk_flags：int（含义：风控状态位）

2.2 登录

POST /api/user/login

请求参数：

username：string（含义：登录账号，当前支持手机号）
password：string（含义：登录密码）
device_id：string，可选（含义：设备标识，辅助风控）

返回参数：

user-token：string（含义：访问令牌；用于需要登录的接口请求头）
refresh_token：string，可选（含义：用于刷新访问令牌）
expires_in：int（含义：访问令牌剩余有效秒数）
user：object（仅返回非私密信息，不返回 id）
- uuid：string（含义：用户对外唯一标识，10 位）
- username：string（含义：用户昵称/展示名）
- coin：string（含义：当前余额）
- channel_id：int（含义：归属渠道 ID）
- risk_flags：int（含义：风控状态位）

2.3 获取当前用户信息

POST /api/user/profile

返回参数（金额类字段统一 2 位小数字符串，与钱包展示口径一致）：

基础档案

uuid：string（含义：用户对外唯一标识，10 位）
username：string（含义：昵称）
head_image：string（含义：头像地址）
phone：string（含义：手机号）
email：string（含义：邮箱）
register_invite_code：string（含义：注册邀请码快照）
channel_id：int（含义：归属渠道 ID）
risk_flags：int（含义：风控状态位）
current_streak：int（含义：当前连胜次数）
last_bet_period_no：string（含义：最近一笔有效下注所在期号）
create_time：int（含义：注册时间戳）

资金与提现配额

coin / coin_balance：string（含义：当前余额；两字段同值）
frozen_balance：string（含义：冻结余额；无冻结场景，固定 0.00）
total_deposit_coin：string（含义：累计充值）
total_withdraw_coin：string（含义：累计提现；受理后累加）
bet_flow_coin：string（含义：打码量/流水；开奖结算后按每注 total_amount 1:1 累加）
max_withdrawable：string（含义：当前允许发起的单笔最大提现金额 = min(coin_balance, max_withdraw_by_flow)）
withdraw_flow：object（含义：打码量 / 提现配额诊断快照，此处额外附 pending_withdraw）
- ratio：string（打码量倍数；0 表示不限打码）
- net_deposit：string（净充值 = max(0, 累计充值 − 累计提现)）
- required_bet_flow：string（按门槛口径所需打码量，纯展示）
- remaining_bet_flow：string（按门槛口径还差多少打码量，纯展示）
- eligible：bool（是否满足整体门槛，纯展示；真正放行以 max_withdrawable 为准）
- max_withdraw_by_flow：string/null（仅按打码量折算的上限；ratio=0 时为 null）
- flow_unlimited：bool（是否处于"不限打码"状态）
- pending_withdraw：object
  - count：int（当前待审核提现订单数）
  - max：int（单用户最多允许的待审核提现数，当前为 3；超过 withdrawCreate 返回 code=2004）

2.4 刷新令牌（可选）

POST /api/user/refreshToken

请求参数：

refresh_token：string（含义：续签访问令牌的凭证）

返回参数：

user-token：string（含义：新访问令牌）
expires_in：int（含义：新令牌有效期）

3. 游戏大厅与字典模块（game/lobby）

3.1 获取首页初始化数据

POST /api/game/lobbyInit
用途：一次返回本局、配置、36字花字典、用户快捷展示

返回参数：

server_time：int（含义：服务端当前时间，用于客户端校时）
runtime_enabled：bool（含义：游戏运行开关；false 时表示后台维护——禁止下注，且 idle 时不会自动创建新期、派彩结束后也不会自动创建下一期；当前已开盘的局仍会开奖、派彩并结算。移动端应禁用下注入口并提示「维护」类文案）
period：object
- period_no：string（含义：当前全局期号）
- status：string（betting/locked/settling/finished/void，含义：当前期状态；void 表示该期已作废）
- countdown：int（含义：当前期倒计时秒数）
- lock_at：int（含义：封盘时间戳）
- open_at：int（含义：预计开奖时间戳）
bet_config：object
- pick_max_number_count：int（含义：单注最多可选号码数，来自 game_config.config_key = pick_max_number_count，缺省与库内种子一致，通常为 10，合法范围 1–36）
- chips：object（含义：快捷筹码字典，固定 6 个键 "1"…"6"，值为该档单注面额字符串，两位小数；与后台 game_config.bet_chips 语义一致）
- default_bet_chip_id：int（含义：默认选中的筹码标识，来自 game_config.default_bet_chip_id，非法或指向无效档位时服务端回退为首个有效档）
- min_bet_per_number：string（含义：单号码最小下注额，须 ≤ 所选筹码面额且受后台配置约束）
- max_bet_per_number：string（含义：单号码最大下注额）
dictionary：array

67 KiB Raw Blame History Unescape Escape

36字花移动端接口设计草案（V1）

1. 设计约定

1.1 基础约定

1.2 通用响应结构

1.3 鉴权方式

1.4 获取接口鉴权 Token（auth-token）

1.5 服务端性能与 Redis 热点缓存（实现说明）

2. 认证与账户模块（user）

2.1 注册

2.2 登录

2.3 获取当前用户信息

2.4 刷新令牌（可选）

3. 游戏大厅与字典模块（game/lobby）

3.1 获取首页初始化数据

67 KiB

Raw Blame History