实施基线 / UI字段与事件契约
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 节为准。

风暴扑克 · 统一实施基线 IB-1.1文档已发布 · 软件开发与验收按门禁推进

本地全文索引 · 无在线服务依赖