STORM POKER / IB-1.1
本文为IB-1.1完整摘录/规范化收录。与本包统一基线和冲突裁定配套执行;旧来源状态不代表软件完成。
字段与事件契约
版本:D2.2
状态:产品与 UI 交付契约;正式接口路径、传输协议和数据库结构由技术评审确定。
1. 通用原则
- 客户端只展示服务端确认的业务事实。
- 金额使用整数最小单位传输,并同时返回
asset_id 与展示精度;不得使用浮点数记账。
- 时间使用服务端时间和带时区的 ISO 8601 值;倒计时以服务端截止时间计算。
- 每次产生业务结果的提交携带唯一
request_id;同号同参数返回第一次结果,同号异参数返回 IDEMPOTENCY_CONFLICT,不得因当前状态变化重新解释旧请求。
- 空值、未知值和零值必须区分;无分母统计显示“—”,不显示 0%。
- 所有敏感字段由服务端按权限裁剪,不能先下发再由前端隐藏。
2. 通用响应字段
| 字段 |
类型 |
必填 |
说明 |
request_id |
string |
提交型必填 |
客户端生成的幂等请求号 |
business_id |
string |
成功或已受理时 |
买入、开房、申请、清算等业务记录号 |
status |
enum |
是 |
IDLE/SUBMITTING/UNKNOWN/FAILED/SUCCEEDED 或领域只读状态 |
server_time |
datetime |
是 |
服务端当前时间 |
updated_at |
datetime |
是 |
当前数据版本更新时间 |
error.category |
enum |
失败时 |
前端稳定依赖的错误分类 |
error.code |
string |
失败时 |
后端精确错误码,便于追踪 |
error.message |
string |
否 |
安全、可面向用户的补充说明 |
retry_after_seconds |
integer |
限流时 |
允许再次校验的等待秒数 |
3. 关键对象
3.1 俱乐部与成员
| 字段 |
类型 |
UI 用途 |
约束 |
club_id |
string |
定位当前俱乐部 |
不以名称作为唯一键 |
club_name |
string |
标题与邀请说明 |
服务端过滤不安全字符 |
membership_status |
enum |
当前归属/审核状态 |
归属改变只由服务端终态确认 |
member_count |
integer |
俱乐部摘要 |
不等于在线人数 |
display_name |
string |
成员目录 |
普通成员不可见 TG ID、IP、余额、佣金 |
game_id |
string |
精确搜索与公开身份 |
不等于登录凭据 |
3.2 房间
| 字段 |
类型 |
UI 用途 |
约束 |
room_id |
string |
房间详情、邀请、恢复 |
唯一且不可由前端猜测 |
room_status |
enum |
等待、进行中、暂停、关闭 |
决定是否允许预约和买入 |
game_variant |
enum |
长牌/短牌 |
长牌 8 席;短牌 6 席 |
seat_count |
integer |
座位布局 |
与玩法模板一致 |
occupied_seats |
integer |
列表与详情 |
由服务端快照提供 |
sb_amount / bb_amount |
money |
盲注展示 |
同一资产单位 |
buyin_min / buyin_max |
money |
滑杆范围 |
客户端不得扩大范围 |
rule_version |
string |
入桌披露 |
开房成功后冻结 |
fee_version |
string |
服务费披露 |
与房间规则快照关联 |
ends_at |
datetime |
剩余时间 |
以服务端时间计算 |
3.3 座位预约与买入
| 字段 |
类型 |
UI 用途 |
约束 |
seat_no |
integer |
座位按钮 |
范围由 seat_count 决定 |
seat_status |
enum |
可选/已占/已选/锁定 |
已占与锁定均不可提交 |
reservation_id |
string |
当前预约 |
不作为资金记录号 |
reservation_expires_at |
datetime |
15 秒倒计时 |
到期后必须重新预约 |
buyin_amount |
money |
买入金额 |
必须在冻结范围内 |
available_balance |
money |
可用额度 |
与桌内托管分开 |
effective_timing |
enum |
当前手后生效 |
进行中牌桌不得立即获得底牌 |
seat_session_id |
string |
买入成功后的座位会话 |
账单和战绩关联键 |
3.4 开房与邀请
| 字段 |
类型 |
UI 用途 |
约束 |
template_id |
string |
已授权模板 |
只允许选择服务端返回的已发布模板 |
template_version |
string |
确认页与房间快照 |
创建时冻结 |
create_permission |
boolean |
显示开房入口 |
前端隐藏不替代服务端校验 |
invite_type |
enum |
ROOM/CLUB |
两类邀请不得串流程 |
invite_status |
enum |
有效、过期、撤销、冻结 |
每次进入和批准时重新校验 |
application_id |
string |
加入申请状态 |
重开小程序后可恢复 |
application_status |
enum |
审核中、通过、拒绝、撤销、失效、冻结 |
审核中保留原归属 |
submit_request_id |
string |
申请提交结果查询 |
与审核请求分离;重复提交不新增待审申请 |
review_request_id |
string/null |
审核结果查询 |
批准或拒绝时生成;不得复用提交请求号 |
application_event_id |
string |
状态轨迹与刷新定位 |
审核、撤销、冻结、失效、生效按服务端追加事件返回 |
3.5 牌局与账本
| 字段 |
类型 |
UI 用途 |
约束 |
hand_id |
string |
当前手、回放、账单关联 |
每手唯一 |
street |
enum |
翻前/翻牌/转牌/河牌/摊牌 |
服务端事件推进 |
action_deadline |
datetime |
行动倒计时 |
客户端不自行判定最终超时结果 |
action_source |
enum |
PLAYER/TIMEOUT/SYSTEM |
超时和系统动作由服务端生成稳定幂等号,仍返回动作事实 |
legal_actions |
array |
动作按钮 |
未列出的动作必须禁用 |
to_call |
money |
跟注金额 |
与“加到”目标额分开 |
raise_to_min / raise_to_max |
money |
加注目标范围 |
表示本街目标总额 |
pot_total |
money |
总底池 |
不与本街投入混用 |
ledger_transaction_id |
string |
账单记录 |
查询不重新执行业务 |
ledger_status |
enum |
PENDING/POSTED/REVERSED/FAILED |
展示状态;REVERSED 仅由有效完整冲正交易派生,原交易存储状态仍为 POSTED |
reversal_transaction_id |
string/null |
冲正关联 |
ledger_status=REVERSED 时必填,指向新的 POSTED REVERSAL 交易 |
reversed_at |
datetime/null |
冲正时间 |
ledger_status=REVERSED 时必填,取冲正交易过账时间 |
4. 前端错误分类
前端只依赖稳定的 error.category,后端精确错误码可继续细分。
| 分类 |
用户含义 |
前端动作 |
AUTH_REQUIRED |
TG 身份无效或过期 |
重新完成身份确认 |
FORBIDDEN |
当前角色无权操作 |
隐藏非法入口并展示无权限结果 |
INVALID_CODE |
邀请码格式正确但不可识别 |
保留输入,允许修改 |
INVITE_EXPIRED |
邀请已过期 |
不进入目标页面 |
INVITE_REVOKED |
邀请已撤销 |
不允许申请或加入 |
RATE_LIMITED |
校验过于频繁 |
展示 retry_after_seconds |
ROOM_CLOSED |
房间已关闭 |
返回房间列表 |
SEAT_TAKEN |
座位被其他玩家抢先 |
清除当前预约,不冻结金额 |
RESERVATION_EXPIRED |
预约超时 |
重新选座 |
INSUFFICIENT_BALANCE |
可用额度不足 |
不提交买入 |
INELIGIBLE |
不满足入桌资格 |
说明可公开原因 |
RESULT_UNKNOWN |
原请求结果未知 |
只查询原请求 |
SERVICE_UNAVAILABLE |
服务暂不可用 |
保留合法输入并重试查询 |
5. 分析事件契约
分析事件不作为业务事实来源,不得携带邀请码 token、TG 原始身份、IP、未公开底牌或完整聊天正文。
| 事件 |
触发条件 |
必填属性 |
CLIENT_SCREEN_VIEW |
页面可交互后一次 |
screen_id, source, journey_id? |
INVITE_VALIDATION_RESULT |
邀请校验得到服务端结果 |
invite_type, result, failure_reason? |
CLUB_APPLICATION_SUBMITTED |
申请明确受理 |
application_id, target_club_id |
ELIGIBLE_ROOM_ENTRY |
服务端确认具备房间访问资格 |
journey_id, room_id, entry_source |
SEAT_RESERVED |
座位预约成功 |
journey_id, room_id, seat_no |
BUYIN_SUBMITTED |
买入请求首次发送 |
journey_id, request_id, room_id |
BUYIN_POSTED |
买入明确成功入账 |
journey_id, business_id, room_id |
ROOM_CREATE_SUBMITTED |
开房请求首次发送 |
request_id, template_id, template_version |
ROOM_CREATED |
开房明确成功 |
business_id, room_id, template_version |
TABLE_ACTION_CONFIRMED |
服务端确认合法动作 |
room_id, hand_id, street, action_type |
EXIT_SETTLEMENT_CONFIRMED |
离桌清算明确完成 |
business_id, room_id, seat_session_id |
ELIGIBLE_ROOM_ENTRY 和 BUYIN_POSTED 的旅程窗口及去重规则以综合 PRD 20.3 节为准。