实施基线 / 服务端需求
STORM POKER / IB-1.1

服务端需求

版本:IB-1.1。适用Node权威业务服务、后台worker及若依管理接入。规则全文见产品需求,逐表字段见数据字典。

服务职责和写入边界

Node.js / TypeScript模块化单体拥有玩家、俱乐部、邀请、房间、牌局、钱包、账本及结算核心写入权。REST处理身份、查询和业务提交,WSS处理牌桌动作和推送;两种入口共用业务用例。若依负责独立后台认证、权限与运营流程,通过受认证管理API调用Node,不另建游戏规则或资金事实源。

每桌单写;首期不得在缺乏所有权协议时横向多实例写同桌。关键状态和账务在同一PostgreSQL事务内提交,提交后广播;通知失败重发通知,不重复业务。

按领域实施

领域 服务端必须负责 重点拒绝/恢复场景
身份 稳定player_id、LOCAL身份、现代口令哈希、登录审计、锁定限流、会话与设备接管 伪造user_id、旧generation、客户端角色/余额、重复登录名;昵称允许重复
组织邀请 默认俱乐部、归属历史、ROOM/CLUB四组合邀请、审核和迁移 撤销与批准竞争、目标冻结、范围不足、手后迁移、普通玩家自退
模板房间 发布/退役不可变版本、授权白名单、独立规则快照、排期与DRAINING 未发布或越权开房、开放瞬间权限变化、已关闭桌重入
座位资产 锁统一占用行、15秒预约、买入、补码冻结/应用/释放、换座和离桌 抢座、余额竞争、重复买入、补码与清算竞态、孤立冻结
牌局 服务端随机、长短牌规则、发牌烧牌、行动顺序、合法加注、边池、尾分及超时 截止时间竞争、动作重放、非本人/非当前回合、他人私牌泄露
费用结算 CSV_STANDARD_V2、逐池抽水分配、离座费与豁免、不可变结算 同手重复派奖、广播失败重结、重复离座费、重启后状态未知
钱包账本 整数最小单位、有符号零和分录、余额非负约束、幂等、冲正及对账 同键异参、跨币平衡、并发负余额、覆盖原单和手改余额
代理 不可变协议、GENERAL默认0%、高精度计提、业务日汇总、迟到重算 跨范围查看、重复计提、把应计伪装真实付款、离座费计佣
统计记录 全量保留/归档策略、游标查询、投影截止与完整性、同玩法样本 3000手截断、缺数据当零、跨币求和、进行中与已结束混算
聊天客服 消息权限、旁观只读、禁言/屏蔽、ASR草稿、举报证据与公开结果 内部备注泄露、私牌直查、原音频超期留存、禁言屏蔽举报
管理安全 动作+对象范围、服务间认证、独立后台账号/TOTP、敏感授权消费及审计 伪造来源、跨俱乐部访问、授权过期/撤销、参数变化、重放
worker与运维 事务Outbox、可重试投影/导出/过期任务、指标和发布排空 worker抢桌写权、导出后撤权仍可下载、重试重复记账

数据库实施约束

应用角色默认无表写权限;通过受限函数执行领域变更,函数必须固定search_path、验证对象范围并最小授权。迁移账号独立,应用账号不能拥有对象或迁移权限。若依不能凭管理身份直接写核心表。

现有V001~V015包含92表、强约束、安全视图、最小种子、post_ledger_transaction及Outbox/代际存储保护;尚未在真实PG16验证。下列业务写入口仍需实现并测试,新增Outbox生产投递、会话代际与TOTP认证消费也属于待实现入口:

  • 本地注册/凭据更新/会话创建与接管、失败计数及锁定。
  • 座位预约、买入、补码、换座、离桌及房间生命周期。
  • submit_hand_action及结算提交、恢复处置和冲正编排。
  • 俱乐部/代理迁移、邀请签发审核撤销、模板发布。
  • post_commission_attribution、apply_admin_grant及敏感授权消费。
  • 私牌工单批准与受限读取、玩家密码重置凭据/消费及BP-32种子。

不得以空函数、ORM直写或临时GRANT绕过。真实环境登记checksum后仅新增更高迁移;对尚未执行的评审基线也应记录变更来源。

身份与认证

核心业务只依赖稳定player_id。认证提供者分离LOCAL与后续TELEGRAM;Telegram绑定不得复制玩家、钱包、归属或战绩。口令采用Argon2id等现代实现,库参数和资源成本在工程配置中锁定并验证。凭据、摘要、initData与原始重置令牌不能进入普通日志和导出。

玩家会话最长24h;过期阻止新动作但保留在桌权益。后台空闲15分钟、绝对8小时,轮询不续期。后台密码与玩家密码独立。TOTP按产品规定6位/30秒/前后1步,成功时间步不可跨授权重放。

资金和结果不确定性

request_id用于请求幂等,operation_id绑定持久业务结果;同号同参返回原结果,同号异参拒绝。UNKNOWN是结果尚未取得,不是业务失败。按账户UUID排序加锁、同资产分录零和、非负账户不透支。结算后广播失败仅重投Outbox。

房间恢复加载所有权、可信检查点、持久事件及已过期计时。已结算返回原结果;可信未结算继续原手;可信手前快照可按规则作废冲回;无法判断是否提交则冻结核查,不自动退款或再结算。

管理功能完整范围

59项BKR均属于后端权限、查询、动作和审计实现要求,见后台需求目录、流程状态及展示字段。其中标“建议读模型”的字段仍需查询设计,不表示视图已存在。数据字典中的敏感表不能因为前端有展示字段就开放直接读取。

API契约交付要求

开发前补齐可校验OpenAPI 3.1与WSS消息契约:认证、对象ID、请求号、金额、版本、错误、限流、恢复、过期与服务认证。接口路径以独立工程契约为准,旧好友房WebSocket消息不自动成为新API。提供正常、权限拒绝、幂等冲突、并发和恢复测试。

服务端完成标准

真实PG16迁移和SQL门禁、并发与权限测试通过;固定牌序规则向量与独立守恒检查通过;两真人Web对局、结算、离桌和重启恢复通过。500连接/50桌×8席及性能、安全、备份恢复属于M5发布证据,未测不宣称达标。完整要求见技术架构及交付与门禁。

IB-1.1接缝约束

后台唯一认证与权限事实为 Node/poker.admin_*,若依原生 sys_* 登录在生产禁用;采用架构6.6及数据字典12.10的统一判定。买入必须携带有效reservation_id,过期返回RESERVATION_EXPIRED;重试先返回同request_id原结果,不从VACANT直接买入。WSS代际来自player_session及app_user持久字段,每次动作在事务中复查。TOTP使用严格递增高水位的条件更新,与授权签发同事务。手间处理按架构9.3.1,不凭SETTLED直接启动下一手。

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

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