实施基线 / 完整产品需求
STORM POKER / IB-1.1

本文为IB-1.1完整摘录/规范化收录。与本包统一基线和冲突裁定配套执行;旧来源状态不代表软件完成。

风暴扑克产品需求文档

版本:综合稿 V1.2 · 首期 Web 认证范围调整版 · 含流程图
更新日期:2026 年 10 月 21 日
业务基线:归档 PRD V3.2(2026-09-19)
适用对象:产品、设计、研发、测试、运营、技术评审

本次从产品经理视角,将归档中已形成的业务裁定、异常流程和验收要求补回综合需求文档,并补充运营后台的执行反馈和数据可信度要求。2026-10-21进一步确认:首期先以普通 Web 注册登录完成端到端开发和评测,Telegram Mini App 对接后置,但账号模型、邀请链接和客户端适配必须保留未来无损转换能力。玩家应能在入桌前看懂费用、在对局中执行合法行动、在退出后核清资产;运营应能在授权范围完成处理,并知道操作是否真正生效。

状态说明:这是文档补充,不是新功能上线批准或功能验收报告。 第01~23章承接归档V3.2的完整规格和章节编号,便于与102项需求、196个验收场景、61项配置逐项对应;第24~26章为本次来源整合、后台产品补充和剩余交付事项。旧V1.0中与该基线冲突的建议已替换,旧稿保留在历史版本。截至2026-10-21确认的默认方案已写入对应章节与待决事项;本文中的D/B指已形成的产品裁定/商业默认,不表示功能已开发、上线或验收。

阅读入口: 需求总表 · 配置字典 · 完整验收场景 · 核心验收用例 · 待决事项 · 来源文件清单 · 素材索引。本次沿用102项基线需求,另补6项后台产品要求;新增验收独立使用OPS-AC前缀,全部执行状态为“未执行”。

01 产品摘要与目标

风暴扑克是以俱乐部组织对局的多人扑克产品。首期以普通 Web 注册登录和浏览器牌桌为入口,玩家从归属俱乐部、普通邀请链接或邀请码进入长牌/短牌房间,先了解费用与规则,再买入、对局、结算和查看记录;运营管理成员、房间和代理;超管控制资金调整与配置授权。后续可增加 Telegram Mini App 入口并绑定同一玩家账号,不为同一玩家另建钱包、归属或战绩。产品的价值是让加入、对局和结算连续且可核对,而非只有一个牌桌演示。

1.1 当前问题与证据

原始资源分散在12份CSV、5页汇总PDF、31张截图、1段视频、205张设计画板、旧项目源码及历史交付中。此前发现35项需求差异,包括规则互相矛盾、费用方案混用、权限被收窄以及部分页面未落成验收。V2已给出裁定,本版将这些裁定与全部功能整合,并补全导航、资产展示、快捷设置、俱乐部管理和交付边界。

不把用户访谈、市场规模、留存提升或实际交易量当成已知:当前没有这些数据。现有源码与设计用于复用评估,不证明本PRD已实现。

1.2 用户价值说明

对玩家:在入桌前看清规则、在行动时只看到可执行操作、在断线后恢复同一牌局、离开后查清余额变化。对运营:在授权范围管理俱乐部、代理和房间,解释每一笔费用与分成。对开发与测试:只依照一套可计算、带边界和追溯的规则交付。

1.3 目标与度量

目标 指标定义 基线 验收或观测目标
资金可信 重复扣款、重复派奖、跨币种串账次数 未实测 验收为0;任一例阻断交付
规则一致 服务端、客户端、牌谱和后台同手结算差异 未实测 验收为0
权限可信 越权操作或未公开牌泄露次数 未实测 验收为0
加入顺畅 有资格邀请访问到成功买入的转化;排除余额不足/满桌 无运营基线 上线首14天建立基线,不虚构业务百分比
恢复可用 网络恢复后取得可操作状态耗时 未实测 P95≤5秒,按第20章环境验收
运营可追溯 加款/规则/权限/代理变更包含完整审计字段的比例 未实测 验收100%

02 资料、优先级与范围

2.1 当前有效来源

优先顺序:本次用户明确指令 → 本文承接的归档PRD V3.2明确裁定 → CSV具体回复 → CSV一般描述 → 产品汇总PDF → 当前设计 → 参考截图/外部资料。原始资料相互冲突时以本PRD明示规则为准。不能用PDF中的Limit、截图中的收费减免或原型中的演示充币覆盖当前范围。

K为原资料明确需求;R为公开规则研究;D为项目产品裁定;B为商业默认;X为真实外部接入条件。D/B已给开发默认,不再等待不存在的产品经理,但不伪装成竞品事实。沿用V2的35项裁定,本版新增完整性裁定另见第22章;N21记录首期 Web 身份入口及后续 Telegram 转换边界。

归档V3.2新增来源为2026-09-19 17:34—17:35的脚本预设发牌消息。第20.1节区分原文明示、既有约束与归档V3.2裁定;原文1~54仅为编码示意,不改变52/36张牌组。

F01~F09对应的最终规则均为D裁定;外部S01~S04只支持认证、授权与幂等原则,不替项目决定金额、时间、迁移或佣金口径。第22章汇总全部N01~N21,具体规则以对应章节为准。

2.2 本期与后续

模块 本期交付内容 后续内容/明确边界
身份/入口 普通 Web 注册登录、统一玩家账号、默认俱乐部、普通邀请链接与单操控会话 Telegram Mini App、initData验签、TG深链/分享和账号绑定后置;实名/KYC流程未接入
房间/俱乐部 单一归属、成员目录、跨俱乐部邀请、权限开房、长短牌 玩家自建/自退俱乐部不开放
玩法 长牌/短牌NLH、Ante、抓头、合法下注、边池、超时 Limit、锦标赛、多人多桌操控不在本期
资金 账本、超管加款、买入补码、返还、服务费、离座费 真实充值提现、OKPay/KKPay/链通道后置
运营/代理 用户/房间/俱乐部/代理/等级/收入/审计/工单 多层自动计佣、真实佣金支付后置
数据/外观 战绩、牌谱、VPIP/PFR/W$SD三环、主题/快捷键 不生成未经验证的综合实力分
聊天 文字、快捷语、免费表情、语音转文字、举报禁言 付费礼物、公开社交动态后置
公平性 服务端随机、动作记录、说明与明确演示状态 链上存证、SGX证明、密钥全牌组复验后置
测试工具 隔离测试环境脚本指定房间/账号、公共牌与底牌 不设运营入口,不在正式环境启用,不包含自动动作脚本引擎
保险 数据可空、入口不提供购买 赔率、投保、赔付按原明确回复后置

测试环境使用不可兑换TEST;产品模型保留正式资产,不能把本期业务目标改成永久仅测试币。产品功能完成、测试环境交付和真实经营上线是三个不同状态。

2.3 全量资源盘点

归档资源总目录记录当时适用文件的路径、大小、指纹和使用方式;历史压缩包只读成员目录,不解包覆盖当前工作区。原始CSV全文、PDF逐页文本、截图文件索引、视频格式信息、205张画板目录以及旧源码能力均有追溯。敏感凭据和实际用户/余额运行数据只登记存在,不收集内容、不打进交付包。

归档整理时,31张截图已通过联系表逐项视觉核对,重要细节回到原图与文字说明;并非逐像素复刻验收。原资料曾写29张,以归档文件盘点31张为准。归档所覆盖的本地视频为29.4秒、464×848,抽取0/7.35/14.7/22.05/28.4秒五帧核对:可见上一手公共牌结尾、新手扣强制款、庄位、抓头、跟注/弃牌和行动计时。仅作视觉/流程参考,不声称逐帧复算或完整规则验证。外链单独记录可读/失败/历史访问状态,不以链接存在视作已核验。

03 用户角色与权限模型

角色 核心任务 可以获得的数据 权限限制
普通玩家 加入、买入、行动、退出、查记录 自己资产/私牌/记录、公开桌面、归属俱乐部基础成员 不能自改归属、费率或管理权限
代理 邀请玩家、看名下人数和佣金 本人协议、授权俱乐部汇总、本人佣金明细 代理身份不自动获得加款或他人私牌权
运营/普通管理员/总代理 管成员、房间、代理与等级 授权范围用户、收入、记录、配置 不可加款、跨范围、提高自己权限
客服/巡检 巡桌、处理举报、发身份提示 授权房间公开状态、工单必要基础资料 无加款、改牌、代理比例、实时他人私牌权
超级管理员 发布规则、授权、资金调整、事后审计 全局业务数据;私牌须结束后工单审计 无前台实时透视;资金修改必须新分录

同一自然人可拥有玩家与后台角色,但身份认证、数据范围、操作权限分别校验。角色标签不能自动推导全局数据权。首个注册者不得自动成为超管;管理员名单来自显式配置。

04 信息架构、页面与核心旅程

4.1 客户端结构

本期一级导航为“游戏 / 俱乐部 / 我的”,启动默认“俱乐部”。原截图“分享”独立导航取消,邀请收敛到已授权的房间或俱乐部入口;不提供分享他人牌谱/底牌或公开动态。品牌统一风暴扑克/Storm Poker,沿用项目风暴标识;OK标识仅作为参考资料。

  • 游戏:输入邀请码、受权创建房间、查看当前在桌恢复入口。
  • 俱乐部:归属信息、本人可用余额、成员、房间筛选和本人参与记录。
  • 我的:本地展示资料、资产与账单、战绩/牌局、综合数据、偏好、账号安全、帮助与客服(含我的举报);后续绑定Telegram后可显示绑定状态。
  • 牌桌:当前手状态、合法动作、聊天、最近手记录;侧栏含规则、房间信息、主题、BB显示、牌型提示、公平性说明、快捷设置、退出。
  • 后台:总览、用户、俱乐部、房间、代理与等级、收入/资金记录、邀请、巡检工单、规则配置、系统设置、审计。

4.2 主要流程

旅程 正常路径 必须提供的失败/恢复路径
首次到访 浏览器打开→注册或登录→统一玩家账号→规则说明→默认/受邀俱乐部 重复登录名、凭据错误、锁定分别明确;待审核仍在默认俱乐部;不伪造审核成功
房间邀请 短码/普通链接→必要时登录→检查策略/房间→规则与费用→选座→买入 登录后恢复原邀请上下文;失效/待审/满桌/禁止观战/余额不足/VPIP不满足各自明确
俱乐部入桌 筛选房间→详情→选座买入→等下手→参局 抢座失败不扣款;房间关闭不产生新冻结
开房 校验开房授权→选已发布模板→配置允许参数→确认→成功页邀请 未授权隐藏入口且API拒绝;失败保留草稿
对局 开手→翻前→翻牌→转牌→河牌→摊牌→结算→下手 短全下/弃牌/断线/余额0均有状态;旧动作不能执行到下一手
离桌 费用预估→确认→当手完成→离座清算→钱包/摘要 不按遮罩误触确认;结算未定显示处理中,不重复退钱
恢复 网络回来→验会话→获取同手快照→恢复合法动作 已结算返回原结果;新设备接管旧设备失权
运营补偿 查用户→超管二次验证→输入原因金额→提交→账单/审计 重复请求不重复加款;运营/客服调用直接拒绝

主链路:统一玩家身份 → 俱乐部/邀请 → 规则接受 → 买入托管 → 手牌结算 → 离座费用 → 余额返还 → 记录核对。每一步由服务端确认;失败停留在最近的已确认状态。完整可视化见第27章,也可打开业务流程图独立阅读页。

4.3 客户端异步提交状态与业务结果

开房、买入等会改变房间、座位或资金的提交,统一使用以下状态契约。客户端在发出请求前生成并保存request_id;服务端终态是业务结果的唯一依据,网络超时或响应丢失本身不代表业务失败。

状态 判定依据 业务和资金含义 客户端允许操作
SUBMITTING 原请求已发送,服务端尚未返回终态 不得推断扣款、冻结、开房或归属变化 禁用重复提交;保留原request_id
UNKNOWN 超时、响应丢失或断线,当前无法确认原请求结果 既不能显示成功,也不能显示失败、自动退款或重新扣款 仅按原request_id查询;禁止生成新请求
FAILED 服务端明确返回终态失败 本次业务结果未成立;响应须给出错误码及对应资金、冻结处理结果 保留仍合法的输入;修正后使用新request_id提交
SUCCEEDED 服务端明确返回终态成功 按业务契约展示已确认结果 才允许进入牌桌、展示room_id或开放依赖成功结果的后续操作

状态转换为:初始→SUBMITTING→SUCCEEDED/FAILED;SUBMITTING超时转UNKNOWN;UNKNOWN只可查询原请求并最终转SUCCEEDED或FAILED,不得直接生成新请求。FAILED修正后属于新请求;SUCCEEDED及其他终态被同一request_id重复查询时返回原结果,不重复执行业务。

业务 SUCCEEDED FAILED UNKNOWN
买入 创建唯一seat_session,可用余额按确认金额转入桌内托管;进行中牌桌从下一手生效 无可用余额转入桌内托管;预约或临时冻结按错误结果释放 不自行推断是否扣款、退款、入座或进入牌桌;只查询原请求
开房 返回唯一room_id并冻结模板与规则版本;确认后才展示邀请入口 不创建房间、不冻结规则、不产生费用;保留仍合法的草稿 不展示房间号、不开放邀请,也不自行推断房间未创建;只查询原请求

05 身份、资料与导航详细需求

需求ID:AUTH-01、AUTH-02、AUTH-03、NAV-01、PROFILE-01。

首期提供普通 Web 注册、登录、退出和会话恢复。注册时填写登录名、密码和展示昵称:登录名为4~32位ASCII字母、数字或下划线,按小写规范化后全局唯一;密码为8~72个字符,允许粘贴与密码管理器,禁止空密码,服务端仅保存现代口令哈希;展示昵称为2~20个可见Unicode字符且允许重复。注册只创建普通玩家及稳定game_id,首个注册账号不得自动成为管理员,也不能由客户端提交角色或初始余额。

登录失败统一返回不泄露账号是否存在的文案;同一账号连续5次失败锁定15分钟,认证入口按IP每分钟最多30次。注册成功、登录成功或合法设备接管后建立服务器操控会话,最长24小时;客户端不可仅传user_id恢复本人或他人会话。会话过期时停止新动作并按断线规则托管,不销毁当前筹码;重新合法登录后恢复同一账号、座位和手牌。首期不提供公开的“忘记密码”绕过入口,密码重置须作为受审计的运营操作另行实施,且不得读回原密码。

身份实现必须经过认证提供者适配层:核心业务只依赖统一player_id,不得依赖密码字段或Telegram字段。后续接入Telegram时,由服务端验证initData签名与auth_date,以provider=TELEGRAM + provider_subject=TG user.id建立外部身份;登录用户可将其绑定到既有player_id,禁止静默新建第二个钱包、俱乐部归属或战绩。若TG身份已绑定其他玩家,必须拒绝并进入受审计的冲突处理;TG展示名和username可变,永远不能作账号键。验签接收窗口暂保留5分钟、未来容差30秒,待TG接入阶段复核。

一个账号最多一桌真人局、一个活动操控会话。新设备合法登录使旧会话失效,接管同一座位与手牌;不创建第二笔买入。普通邀请链接或后续TG深链指向的目标不同于已入座桌时展示“当前在另一桌”,允许先返回当前桌处理;不能后台隐式离桌。

首期展示昵称来自注册输入,后续可在资料页修改;去首尾空格、拒绝控制字符/纯空白,重复昵称允许,game_id不变。头像为空或失效时使用项目默认头像,不出现破图。未来绑定Telegram后,只有用户显式选择“使用Telegram资料”才同步头像和昵称;已自定义资料不被后台静默覆盖,解绑也不删除玩家账号。game_id复制有成功/失败反馈,剪贴板失败提供手动选择。偏好按统一账号保存,声音/振动设备授权仍分别处理。

返回优先关闭最上层弹窗,再回上级页面;回牌桌恢复相同room_id/hand_id与滚动位置。关闭浏览器标签页、刷新或切后台不等于离座,统一触发断线处理。资金确认弹层仅明确取消或确认关闭。重连或通过邀请链接重新进入不能丢掉未执行表单草稿,但下单前重新校验实时余额和房间状态。

普通浏览器是首期玩家正式入口;未登录访问受保护页面时跳转登录,并在成功后恢复同站点内的合法邀请或房间目标。玩家认证与运营后台认证完全分离,玩家凭据不能登录若依后台,后台账号也不能直接冒充玩家。正式协议版本、内容摘要和接受时间留记录,未配置正式文本不能伪造“已同意正式协议”;测试环境用清楚的测试说明。协议内容与经营主体为发布接入条件,不自行捏造实名认证已完成。

06 俱乐部、邀请与成员

需求ID:CLUB-01~CLUB-05、INV-01~INV-03。

邀请对象ROOM/CLUB与策略独立:EXPIRING_24H(免审、签发起24h)或PERMANENT_REVIEW(无时间失效、每个申请审核)。四种组合都支持;房间“永久”仍不能越过房间关闭,只是不自动按24h过期。默认房间24h免审、俱乐部永久审核。后者是默认组合,不是类型强约束。

字段:id、token_hash、target_type/id、policy、created_at、expires_at可空、issuer、revoked_at、use_count。申请另表记录applicant/status/reviewer/reviewed_at。进入时复查邀请、目标、账号、批准状态;审核通过瞬间也复查有效性,房间关闭拒绝批准。撤销阻止新加入/待审核批准;已入桌者正常完成结算,不能追溯吞款。拒绝重复申请但可幂等重试;拒绝后必须使用新邀请重新申请,不提供解除拒绝动作。

永久房间邀请只授予该房间访问权,不能改俱乐部/代理归属。俱乐部申请通过后按第6.4节生效时点更改归属,已结算历史不改;已有正式归属者由授权运营显式迁移。无效码不修改当前归属。自然访问进入默认俱乐部。

game_id/player_id是业务唯一玩家键;本地登录名和未来TG user.id都只是认证身份,不能进入牌桌、俱乐部、钱包和账本的业务主键。服务端会话24小时、单账号单操控会话与单真人桌是D规则。[R04] 后续TG验签和auth_date检查遵循Telegram文档;新设备接管同一座位,旧设备失去操作权,下注不能跨会话重放。

成员目录:同归属俱乐部的正常成员均可查看全部正常成员基础信息,不依赖是否好友/代理;显示game_id、展示名、头像。仅支持当前俱乐部范围分页(默认20、最大100;超出范围返回INVALID_PAGE_SIZE),按game_id稳定排序,搜索展示名或精确game_id。不给普通成员余额、TG ID/username、IP、佣金、登录时间;跨俱乐部邀请访客只看当桌公开座位信息,无全俱乐部目录权限。禁用成员不出现在普通目录;后台保留。成员详情失败显示无访问权限,不泄露该ID是否在其他俱乐部。

6.1 俱乐部列表与资产语义补全

俱乐部头部显示头像、名称、ID、身份、正常成员数和“本人可用余额”。此前截图的“俱乐部账户余额”不足以证明存在一个可充值的独立资金账户,本版统一为当前用户同币种钱包可用余额的视图;不在每个俱乐部另建余额、不复制钱、不支持玩家间或俱乐部间转账。显示/隐藏余额仅本机偏好,不改变访问权限。“+”在测试环境打开额度说明,在真实充提未接入时不得跳到虚假充值成功页。

房间筛选全部/长牌/短牌;默认可入座RUNNING房间在前,其次WAITING,再满桌可观战;同组按创建时间倒序、room_id稳定破同序。CLOSED不在当前列表,历史可查。展示实际参局/占座人数与上限、玩法NLH、SB/BB、Ante/抓头标识、观战开关、剩余时间、room_id、买入范围和VPIP条件;不显示保险已开通标识。5秒刷新或事件推送更新,后台时暂停无意义轮询,回前台立即刷新。加载/空态/失败/旧数据过期提示不能混成空列表。

俱乐部记录:玩家只看本人参与记录,不能从“俱乐部牌局”入口获得别人的私牌或钱包;运营可按范围查询。访客离开跨俱乐部房间后回本人俱乐部,归属不随导航变化。

6.2 俱乐部管理

超管创建俱乐部、指定直接代理和运营范围;授权运营编辑名称/头像/简介、签发邀请、审核和调整范围内成员。俱乐部状态ACTIVE/FROZEN/ARCHIVED。冻结停止新房间、新加入和新买入,已有手正常结算返还;无未关闭桌/未清算资金后才能归档。归属调整有原因和历史记录,按第6.4节手间或立即生效;玩家本人无退籍按钮。一个俱乐部首期一个直接代理,一个代理可管理多个俱乐部;未绑定代理的默认俱乐部收入归平台。

6.3 邀请码输入与分享细节

支持6位大写字母/数字短码(排除易混淆0/O/1/I)或普通HTTPS邀请链接,粘贴去空格后转大写;手动点击“加入”提交,避免输入最后一位即意外进入收费流程。服务端随机生成并检查有效码唯一性,码只定位邀请对象,不能替代登录与授权。未登录用户先完成登录并恢复原邀请上下文。每账号每分钟最多10次校验、连续10次无效锁60秒;返回明确错误但不暴露他人资料。长链接使用随机不透明token,后台存token_hash。未来TG深链复用同一邀请token和服务端校验,不另建邀请对象。短码空间紧张时停止签发并告警,不复用仍有效码。

只在用户主动点击时复制链接或调用浏览器Web Share;后续TG接入可增加宿主分享适配。内容仅名称、玩法、邀请链接/码及到期提示,无余额、手牌、代理分成或用户列表。不自动发送消息。无签发权限者不显示邀请按钮;收到邀请不等于获得转发后免审核的特权。

6.4 归属迁移与原房间访问(F03,D)

关联CLUB-01、CLUB-03、AGENT-01。无在手(含未入座、等待席、手间)时迁移在提交事务中立即生效;有在手则记录一笔待生效迁移,在该手结算或作废完成后、下一手名单及协议快照形成前生效。当前手继续使用旧归属/协议。账号被禁用不妨碍合法迁移记账,但不会恢复参局权。

迁移操作需同时覆盖源、目标俱乐部范围;普通运营只有单侧范围时拒绝,交由具备双侧范围者或超管处理。目标必须ACTIVE。每人最多一笔待生效迁移;同request_id同参数返回原结果,异参数或另一笔并发迁移返回MEMBERSHIP_CONFLICT。提交和生效时均校验操作者权限及目标状态,失效则取消并保留旧归属;取消原因可查。

生效后立刻失去旧俱乐部成员目录和列表权限,获得新俱乐部权限;本人的历史牌谱、账单仍可查。已在旧俱乐部买入的seat_session保留仅该房间、仅该会话的临时访问权,允许继续参局、补码和恢复,仍受禁用、房间/俱乐部关闭与冻结约束;既有会话的VPIP不重验。下一手按新代理计提,不改当前手和历史账。临时权不授予旧俱乐部目录、签发邀请或别桌权限,退出会话即失效;再次买入需独立有效邀请或成员资格,不能隐式延续。未买入的观战访问不获临时权。

6.5 冻结、解冻与归档(F05,D)

冻结采用手后关闭,不允许冻结俱乐部继续开下一手。冻结事务立即封住新加入、买入、补码、开房;所属房间分别处理:

房间状态 冻结后的结果
SCHEDULED 取消计划,记CLUB_FROZEN,进入CLOSED,不再自动开放
WAITING 取消开局倒计时,返还托管和补码冻结,完成清算后CLOSED
RUNNING且有在手 DRAINING,当前手正常结算后免离座费清算
RUNNING且无在手/空桌 立即停止下一手,清算并CLOSED
DRAINING / PAUSED_RECOVERY 保持清算/恢复,设置关闭意图;无法判定资金时继续冻结核查,不强行置CLOSED
CLOSED 保留历史,不重开

冻结同时撤销所有仍有效的该俱乐部/所属房间邀请,未决邀请申请标CANCELLED,原因CLUB_FROZEN;已批准但未买入也不得绕过冻结。已迁出的旧会话临时权不能绕过房间关闭。解冻只使俱乐部回ACTIVE;不恢复旧房间、旧邀请或已取消申请,需显式重建/签发。

归档须俱乐部FROZEN、所有房间CLOSED、无未清算资金、无待迁移事项且成员数为0(禁用成员也计入);不满足返回CLUB_NOT_EMPTY或CLUB_NOT_SETTLED。普通成员由授权运营先迁移,禁止归档时批量静默改归属。默认俱乐部为系统保底对象,不允许冻结/归档;若异常不可用,登录进入“俱乐部服务暂不可用”并保留资产、账单和原桌恢复入口,停止新入桌,不自动新建俱乐部或改余额。

07 房间创建与配置

需求ID:ROOM-01~ROOM-05、CFG-01。

长牌52张、8席、2或3小时,默认2小时;短牌36张6–A、6席、1小时。均仅NLH。长牌6席/1小时不进入本期选项;Limit明确后置而不是漏做。短牌正常SB/BB,同花大于葫芦、A6789为最低顺子;短牌Ante与抓头固定关闭,其中“无抓头”为K,“同时关闭个人Ante”为D。[R03]

金额使用整数分,币种精度为2;超过精度拒绝而非截断。SB=BB/2,BB必须是0.02的整数倍。保留七组绝对买入范围:2–10、6–30、10–40、20–80、50–200、100–300、400–1200。不使用10–1000BB硬限制和40–200BB自动替代。

原文未给盲注配对;V1仅发布一个完整种子:TEST资产、SB/BB=1/2、买入100–300、长牌8席2h、Ante/抓头关闭。其余六组候选保留为DRAFT,不出现在开房菜单,也不推导盲注、资产或授权范围;这不阻塞V1。模板校验最小买入至少覆盖本玩法一手最大强制款、最小≤最大。该种子是D配置,不是原七组与盲注的推定映射。

观察的3%/5%与档位关系保留,裁定为默认模板:最小买入<400为5%,≥400为3%,所以100和400的边界分别为5%和3%。100–400间采用5%是B补全,不声称原文已定义。运营可选择已发布费率模板;超管可新建费率版本,房主不能临时改费率。封顶默认1.5BB(B,复现CSV的BB2/cap3),支持明确金额封顶;不得从不同币种模板自动换算。每桌创建冻结全部规则版本,调参只影响新桌。

长牌Ante/抓头默认OFF;观战默认允许;延迟默认OFF;VPIP准入默认OFF,启用时门槛1–100整数、同玩法最近100手至少20手,低样本允许入座并提示。各字段完整类型/范围见附表《配置字典》。

其余:自动开局人数2至座位上限、默认2,倒计时5秒;房间从第一手开始计时;30分钟未开局关闭并返还。最低买入不妨碍已在桌上亏损后以短筹码继续;补码上限按手后筹码判断。

7.1 权限、草稿与发布

默认仅运营和超管开房;超管按俱乐部设置allow_player_create并限定已发布模板,授权玩家才显示入口。权限同时在页面路由和创建请求检查,不能通过复制链接越权。玩家仅能修改模板允许的自动开始人数、观战和时长等字段,不能自行改收费、分成、资产或超时政策。模板明确哪项可编辑;默认盲注、买入、费用均固定,运营发布新模板改变。

创建表单字段与本章配置一致,确认页完整展示抽水与离座费,创建成功后显示room_id及签发的邀请策略。不要求创建者必须入座。开房提交遵循4.3节状态契约:提交中与结果未知均不得再次创建或提前开放邀请;明确失败保留合法输入;重复提交同request_id返回同room_id。房间WAITING阶段也不直接覆盖规则版本;有错误时关闭旧房新建,已经冻结的买入原额返还。

本期运营可手动创建和选择单次计划开放时间,最长未来7天(D补全运营定时开房场景);SCHEDULED期间只展示预告、不能买入。到计划时转WAITING并签发默认24h房间邀请,不提前消耗有效期;用户指定永久审核邀请可提前申请,但开放前不得入座。计划时操作人失去权限或模板退役则取消并记录原因。循环排班不在本期。

08 买入、补码、位置与房间生命周期

需求ID:SEAT-01~SEAT-06、RECOVER-01。

状态:房间SCHEDULED→WAITING→RUNNING→DRAINING→CLOSED,异常进入PAUSED_RECOVERY;座位EMPTY→RESERVED→WAIT_NEXT_HAND→PLAYING,缺席可AUTO_PLAY,退出LEAVE_PENDING→EMPTY。服务端时间决定截止,客户端只做倒计时展示。

买入流程:展示房间规则/费用/当前余额→选空座→预约15秒→输入[min,max]金额→提交→服务端同一事务校验身份、资格、余额、币种、房间状态、座位和已接受规则版本→扣可用余额到桌内托管。买入提交遵循4.3节状态契约:未取得明确终态时不自行判定扣款、退款或入座;结果未知只查询原request_id;重复request_id只成交一次。预约到期或抢座失败不遗留冻结。进行中的桌买入成功须等下一手,不能获取当前手底牌。

第一手达到人数门槛倒计时5秒,不额外要求所有人点“准备”;人数不足取消。结算完成后先处理离座/退款/补码/位置,再间隔3秒准备下手。未参局的等待席可以取消并全额返还,不收离座费。

运行中新增/返回玩家默认等自然BB入局,不额外补盲。为消除“等待BB”停桌歧义,位置轮转以固定物理座位顺时针计算候选,等待新入局者可以在轮到其BB时进入名单;不能因未在手而永远跳过。若不足两名可参局但至少两名有筹码等待者,则重建新开局名单、随机首庄;所有人在已记录的同一开局规则下开始。位置算法需记录每手按钮与跳过理由。

换座仅手间生效,当前手位置不变;不开始新资金会话、不触发离座费、不重置等盲资格/缺席截止。新位置不得逃避本来应付的BB;若会跳过本人的下一次BB,换座延迟到已支付该次BB后再生效。换座冲突只允许一人占座。站起会结束资金会话、返款并按离座规则结算;观战允许时留房旁观,禁止观战时返回俱乐部。

补码先冻结钱包金额,当前手筹码不变;下一手应用=min(冻结额,max(0,最大买入−手后筹码)),超额解冻退回。例最大100、原筹码80、冻结20、当手赢到90,则加10退10。未生效补码可取消,取消和应用竞争由服务端原子处理,只能成功一种。桌内余额≥最大买入时仍可继续玩,但补码入口禁用。

桌内筹码为0无法参局。手间保座60秒供补码(D);超时且未补码释放座位、结束会话。该60秒仅零筹码补码场景,不替代超时A模式手后离座;两种退出条件同时出现取更早的合法退出时点。资金冻结中的补码必须先确认取消/应用,不能以释放座位吞款。

房间自然到期或运营关闭进入DRAINING:不接新买入/补码/下一手,当前手正常结束;未生效补码全额解冻,桌内余额完成清算。房间没人时仍记录关闭原因;不能用重开房跳过账本。满桌时允许观战则给旁观入口,否则告知满员;没有排队自动扣款功能。

8.1 补码准入与单笔待处理(F02,D)

关联SEAT-02、SEAT-05。每个seat_session最多一笔PENDING补码。不同request_id再次申请返回TOPUP_PENDING,不追加、不覆盖;同ID同参数返回原记录,异参数返回IDEMPOTENCY_CONFLICT。取消成功后可新申请;冻结和本规则校验同事务执行。

以申请时剩余可行动桌内筹码C(不含已投入底池、钱包冻结)校验:C>0时补码额A∈[0.01,最大买入−C],不强迫亏损玩家补足最低买入;C=0时A∈[最小买入,最大买入]。A须正数、整数分、钱包足额;C≥最大买入拒绝。允许全下期间申请,但此时C=0按零筹码区间校验。该规则避免把继续短筹码参局与零筹码重新补码混为一谈。

手间按实际手后筹码E计算X=min(A,max(0,最大买入−E))。E>0时应用X并退A−X;E=0且X<最小买入时整笔取消退款并提示TOPUP_MIN_REQUIRED,不让不足额预申请绕过零筹码门槛。例范围100–300:C=50补0.01合法;C=0补0.01拒绝、补100合法;C=50申请20后输至0,20全部解冻。E>0的原有短筹码继续资格不变。

自然到期、冻结、禁用清算、主动退出先取消未生效补码,再清算;不能先加码又收离座费。零筹码60秒从该手结算完成起计,退款或重新申请不重置;到截止前已提交且足额的补码优先原子应用,截止后才提交则拒绝并释放座位,不能遗留冻结。当前手不存在时,在下一次手间调度立即应用,无需等到已释放座位后的下一手。

09 牌组、行动、摊牌与结算规则

需求ID:GAME-01~GAME-07、POT-01、SHOW-01。

9.1 牌型与发牌

长牌52张,牌型从强到弱:同花顺(含皇家同花顺)、四条、葫芦、同花、顺子、三条、两对、一对、高牌。短牌36张,只将同花排到葫芦之前,其余顺序相同。A2345仅长牌有效,A6789为短牌最低顺子,不允许QKA67环绕。七选五,不比第六张、花色或座位。

同牌型比较:同花顺/顺子比较最高点,最低A顺按5或9高处理;四条比较四条点数再踢脚;葫芦比较三条再对子;同花/高牌按五张降序比较;三条比三条再两踢脚;两对先高对、低对、踢脚;一对先对子再三踢脚。全都相同则平分。帮助页可将皇家同花顺单列为10种展示,但引擎仍视其为同花顺最高形式。

完整加注按净差额:6→20,下一最低34。短全下不改变最近完整差额;分别记录各玩家上次响应价格、当时阈值及是否已行动,判断是否面对完整增量,补跟不替别人重开。A20/B跟20/C全下30,A/B都只能跟10或弃牌;再有未行动D加到50则重开。多个短全下累计到40可对仍停在20的A/B重开;已跟到30者面对40不能加注。TDA 2026第49条及算例支持逐玩家判断;它是赛事参考,我们明确选作本项目NLH规则。[R01]

不足BB首笔全下采用H+BB的明示房规(BB2,首注1,后手最低3),不冒充现金桌统一标准。任意待跟为0的在行动玩家可过牌;不能限制为BB。下注圈结束依靠所有可行动者已响应当前价格,不固定某个座位;BB未行动的免费选项不能跳过。无人可继续互相下注时发完公共牌。

跟注=max(0,当前最高有效下注−本人本轮有效投入),Ante不抵扣。抓头2BB后跟到2BB。四条先比四条点数,再比踢脚;其他同型按最佳五张比较,不用第六张或花色破平。

摊牌为服务端结算结果的展示流程,展示超时不能改变应得款:河牌有下注时最后激进者先亮,再顺时针;河牌全过时庄位左侧首个未弃牌者先亮。单挑全过则非庄BB先亮。若有人全下且所有剩余下注完成,全部未弃牌者自动亮牌(含有边池资格者),不允许Muck;这是本项目采用的房规,非所有现金平台一致。[R01/R07]

非全下摊牌:首位强制展示;后续玩家只有在每个有资格池均已有公开牌严格胜过本人、本人无任何获池/平分份额时可Muck。按钮“亮牌/不亮输牌”3秒选择,默认不亮输牌;仍有赢家资格自动亮牌,不能误操作放弃应得份额。客户端隐藏输牌不等于弃牌;引擎必须先评完全部合法手。赢家取得任何有竞争池份额必须亮两张牌。其他人行动中已全部弃牌时,赢家默认不亮,可在3秒内自愿亮两张;无需为无人争池强制亮牌。Muck底牌不进入其他玩家推送、重连及回放,本人仍可看本人记录。

尾分:对每个池独立,从庄位左侧顺时针扫描该池赢家;跳过空座、弃牌者和无该池资格者。若小盲是首名合资格赢家就给小盲,不能排除小盲本人。例如BTN8,赢家1和3,池0.05,座1得0.03、座3得0.02;座1非赢家则由座3优先。[R01用于消歧,位置选择明确为D]

发牌:先锁定参局名单并扣强制款,再从庄位左侧首个参局者开始顺时针发两轮底牌;单挑先给非庄BB、最后给庄SB。先付Ante全下者仍发牌。每街烧一张;烧牌及未来牌不下发。原文“庄家起手”不采用。客户端可做动画,但所有扣款须先在服务端提交,动画不得改变实际顺序。

测试环境可按第20.1节预设牌序(QA-02),仍执行上述发牌顺序与正常公开时机;仅替换牌序生成来源。

9.2 行动起点与轮转

首手庄位在本手合资格名单中均匀随机选择,后续按固定物理座位顺时针寻找下一合资格位置;换座、等盲候选规则见第08章。多人SB为庄左首位、BB为下一位;无抓头翻前由BB左侧首个可行动玩家开始,有足额抓头则由抓头左侧开始,抓头保留翻前最后行动机会。翻后由庄左首个未弃牌且非全下者开始。两人时庄家兼SB、对方BB,庄家翻前先、翻后后;从多人转单挑时调整按钮避免同一玩家无故连续支付BB,位置变更记事件。

每手只在开手扣一次盲/前注,不在每街重复扣。翻牌/转牌/河牌开始时本轮有效下注清零,历史投入留在底池;所有合法行动者响应当前价格且已匹配后进入下一街。只剩一名未弃牌立即结束,无须发完未来牌;无法继续互相下注但仍有多名未弃牌则按公开规则发完公共牌比牌。抓头位在支付其他强制款后不足2BB时本手抓头不触发、不换人,跟注基准回到标称BB。

9.3 合法动作的完整金额契约

H=本轮最高有效下注,c=本人本轮已投入,S=剩余桌内筹码,L=最近完整下注/加注差额。跟注C=max(0,H−c),实际跟注min(C,S)。下注/加注请求统一为本轮目标T,本次实际扣T−c,UI同时显示“加到”和“本次投入”。

翻前H与L初始为标称BB,有足额有效抓头则为2BB;翻后H=0,完整首下注至少BB。有完整下注后最低完整加注目标H+L,合法完整加注后L=T−旧H。少于此目标仅允许真实全部S投入且本人有加注权;全下跟注S≤C不要求加注权。本人无加注权且S>C时不能用全下按钮绕过。

服务端逐玩家保存是否主动行动、最近响应价格及重开阈值;未主动行动者可加注,已行动者面对自上次响应以来至少一个完整差额才重开。曾在H=0过牌者面对新的下注仍保留加注选择。没有能够继续匹配筹码的对手时仅允许完成必要跟注/弃牌,不制造无人竞争边池。超筹码目标拒绝,不自动转全下。

输入 预期
BB2,首加6,再加15 下一最低24
A20/B20/C全下30 A/B补10或弃牌,不可加注
上例未行动D加50 L20,A/B重开后最低70
A20/B20/C30/D40连续短全下 停留20者面对累计20,可最低60
A20/C30/B先跟30/D40 B只面对10,不重开
BB2,翻后首注全下1 本项目后手最低加到3;跟1仍合法

9.4 快捷下注与动作交互

无待跟时可自选3–5个快捷项,候选1/5、1/4、1/3、2/5、1/2、3/5、2/3、3/4、4/5、1、1.5、2、3倍当前总池及ALL-IN,默认1/3、1/2、1。比例项按包含当前街已投入的总池计算,向上取到0.01后校验最低合法目标;低于最低时显示最低目标并标“已按最低下注调整”。高于可用筹码则该快捷项不可用,独立ALL-IN按合法动作集合判断。选择去重,少于3/多于5禁止保存,取消不改旧设置,账号持久化。此为对截图明确3–5项设置的恢复。

面对待跟时不使用Raise Pot,切换为最低加注、最低目标+1BB、最低目标+2BB、全下,并直接显示金额。滑杆区间[最低合法目标,c+S],步进0.01,可输入精确金额;若只允许短全下则不画虚假连续区间。点快捷项先填金额,明确提交才行动;提交中禁重发,结果以服务端accepted/rejected为准。最后5秒用文字/进度提示,不能用闪烁或仅颜色区别。

10 费用、底池与代理分成

需求ID:FEE-01~FEE-03、POT-02、AGENT-01~AGENT-03。

10.1 当前收费模板 CSV_STANDARD_V2

采用CSV示例的“翻后收费、明确费率、全手封顶”。不采用截图的小于5BB免抽、少人减半、平分免抽。截图方案记为历史备选,不混入当前默认,也不要求本期增加第二套收费引擎。公开运营商的费率表证明费率/封顶需分开定义,不能替本项目选数值。[R02]

先返还无人匹配下注,然后逐层拆池。G为全部有竞争底池之和(含实际已支付Ante、含弃牌者贡献,不含未匹配返还)。未发翻牌R=0;发过翻牌则:

R = floor_cent(min(G × rate, cap))

无人数折扣、无最小池门槛、平分池同样收费。先按每池金额/G分摊R,整数分向下取整;剩余分按余数降序、同余按pot_id升序分配。各池费之和必须等于R。每池扣费后再平分,尾分按第09章位置规则。全手仅封顶一次。退款、作废不产生抽水,完成后重试返回同一结算结果。

场景 固定输入 费用/派奖
CSV示例1 BB2、5%、cap3、翻后池40、2人 费2,派奖38
CSV示例2 同模板、翻后池400 费3,派奖397
小池 BB1、5%、cap1.50、翻后4.99 费0.24,派奖4.75
平分 cap3、5%、池40、两赢家 费2,各19
主边池 A20/B50/C100;BB2、cap3、5% 先返C50;主60/边60,各费1.50
部分平分 上例主池A/B平分、边池B胜 A29.25、B87.75、C返50、平台3,总170

10.2 Ante和强制款

长牌Ante支持OFF/EACH/BB_PAYS;默认OFF。EACH金额0.5BB或1BB;BB_PAYS总前注1BB。Ante不抵扣跟注;抓头为至少三人才启用的UTG有效2BB,不混同Ante。

EACH按个人全部实付贡献逐层分池,先付个人前注后付盲。BB_PAYS先付BB再付前注;TDA推荐支持“先大盲”顺序,但不能据此推导所有现金桌分池方案。[R01] 本项目明确选择:BB代付前注形成独立公共池,所有本手未弃牌且已发牌者可争,独立于有效下注边池;短筹码玩家也有公共池资格。该资格是D房规,不标成CSV原规则。公共池与其他池共同参与全手抽水与封顶,归因的贡献者是实际付款的BB。

例:BB1、BB筹码1.50,实际有效盲1、公共前注0.50,跟注价仍1。公共前注1、A有效下注0.20、B/C各1时:公共池1、有效主池0.60、边池1.60;A只能争前两池,全部实收3.20。若大家弃牌只剩A,所有池与未匹配返还按合法资格清算,不再强制亮牌。没有任何合法受益人的池视为引擎异常,暂停恢复,不把筹码自动吞入平台。

10.3 代理分成

选择单层直接代理、逐池贡献抽水归因、Asia/Shanghai每天00:10结前日。这是B/D产品方案;上级管理关系不自动产生多层佣金。每手冻结玩家代理和协议版本,跨俱乐部不重复计佣。每池实收抽水×该玩家该池贡献/全池贡献=玩家归因基数;包含弃牌贡献,不含未匹配返还。公共前注归实际付款者。保留高精度有理数,代理按日汇总后向下取分,余数留平台。

默认代理等级GENERAL比例0%,后台明确显示0%而不是“待产品确认”;演示20%仅用于算例,不自动成为合同。允许授权运营设定0%–100%范围内且不超过其授权上限的比例。正式外部协议导入时版本化覆盖,不能回改历史计提。新手只引用其开始前生效版本;等级修改不追溯已开始手牌。抽水3、贡献20/30/50、P名下A+B、比例20%时,P基数1.50、佣金0.30。

未配置/损坏的旧代理记录:阻止其新计提,显示CONFIG_ERROR,历史基数保留供修复;不是静默套用0%。佣金只是抽水内部划分,不从玩家扣第二次。离座费不参与代理分成。日账幂等键为代理+币种+日期+结算版本,纠错走新分录。计提与已支付分开;真实佣金支付接口仍后置。

10.3.1 计提日期、迟到与纠错(F06,D)

关联AGENT-03、RECOVER-03。业务日以手牌结算首次成功提交的settled_at转换Asia/Shanghai决定,不用开手时间或统计服务接收时间。23:59开手、次日00:20首次结算,属于次日,并在再次日00:10结算该日代理账。重放已提交手沿用原settled_at;规则与代理比例仍使用开手快照。

00:10仅为首轮日账生成时点,不代表历史业务日永久不可补结。事件投影迟到时,补入原settled_at业务日;日结作业每天00:10同时扫描有新事件/纠错的历史脏日并补结。页面展示数据截止时间及PENDING_RECALC,下一轮完成后清除。进程故障错过作业时恢复即补跑,不跳过日期。

同代理+币种+业务日计算高精度净佣金总额C,目标应计=floor_cent(C),本次调整=目标应计−该日已记净应计。首结、迟到与冲正均用此差额生成新版本分录,保留旧版本/原单/记账时间;不把每条迟到金额单独舍入。同一事件ID仅入一次,版本递增串行提交;并发相同事件不产生两个调整。C不得因重复冲正变负;纠错必须引用有效原事件。

算例:首结C=0.019,应计0.01;迟到增加0.009后C=0.028,目标0.02,仅补0.01;撤销迟到事件后C=0.019,仅冲−0.01,再次撤销同事件不再冲减。撤销全部后目标0,净应计归零。原日账显示重算净额和调整轨迹,另保留本次调整实际记账日供对账,不把同一调整重复算进两个收入日。

“已结算”测试标记与应计独立。若已标记支付0.02后应计冲至0.01,显示已支付0.02、应计0.01、待处理差额−0.01,标记待人工核对;不自动扣玩家余额、不生成真实追回支付。计提异常不得阻塞合法玩家结算,异常基数保留重算。

10.4 标准逐层分池算法

对每名玩家累计实付贡献排序取不同阈值,每层池额=(本阈值−前阈值)×贡献达到本阈值的人数。池内资金包含弃牌者贡献,获池候选仅未弃牌且达到该层者。只有一人贡献而无人匹配的有效下注先返还,该部分不抽水、不计“获池”。EACH前注进入个人贡献,BB_PAYS公共前注独立按上节房规处理。每池有独立赢家集合、费用、净额和尾分分配记录。

例A20/B50/C100,最高50无人匹配退C,主池60三人争,边池60仅B/C争。A即使最强也不能获得边池。断线或界面未看见结算不能改变资格。任何无合资格赢家、金额不守恒或重复池ID均进入恢复异常,不能给平台兜底吞款。

11 离座、缺席与超时

需求ID:EXIT-01~EXIT-03、TIME-01~TIME-03。

保留盈利离座扣费能力,定义提前离座费用模板 EARLY_EXIT_PROFIT_V2。默认费率30%取自CSV举例,归档V3.2将其裁定为可配置B默认;不是行业惯例。不用回桌最低筹码规则替代该功能;本期不额外叠加120分钟回桌限制。[R06,仅证明其他产品存在不同方案]

收费条件:房间自然到期前,玩家主动离桌、站起返款或玩家超时自动退出;盈利才收。自然到期、运营关闭、服务故障强制退出、未完成任何有效手均免收。后台强制禁用/移除视作运营退出,免收并记录原因。用户断线属于玩家超时,不伪装为服务故障。到期和退出同一时点,先判断房间截止时间,已到期则免收。入座前展示当前模板、费率、豁免和计算例子并记录规则版本;未记录接受不得买入。

一笔入座会话不允许中途取走部分筹码,补码只增加本金。B=初始买入+实际生效补码,U=尚未生效的补码冻结(不算本金),E=手后应返桌内余额(已扣每手抽水)。净盈利P=max(0,E−B),费用F=floor_cent(P×q),实际返还=E−F+U。示例买入100、生效补50、未生效20、E180:P30、F9、返191。E120时F0、返140。房间自然到期则F0、返200。

手中离开仅登记LEAVE_PENDING,按原超时自动过牌/弃牌;全下权益保留。手后一次性收F并返还,以seat_session_id+EXIT幂等,重连不新建会话。离座费单列账单和会话净收益;不再分摊进已结算手牌的净收益。服务故障作废手不计盈利。F≤E,借贷守恒。禁止通过站起旁观绕过返款费用。

超时两种房间配置,创建时冻结并入座披露:

  • A=EXIT_AFTER_HAND,默认:本手超时过牌或弃牌,手结束自动离座返还;A模式不设置120秒保座。玩家在手结束前点击“我回来了”可取消由超时触发的待离座,但不能撤回已经执行的过牌/弃牌。
  • B=AUTO_PLAY_UNTIL_DEADLINE:首次超时标记缺席,继续正常发牌、扣盲/前注并自动过牌/弃牌;截止策略为FIXED_SECONDS(默认120秒,可30–1800)或ROOM_END。到截止先设待离座,当前手结束才返还,不发下一手。明确点击“我回来了”取消缺席;仅网络重连不清计时。

“手结束”与“房间结束”分开。房间到期优先停止新手并走免离座费清算。服务故障暂停全桌计时,不把玩家当作自行超时。行动20秒、时间银行初始30/每10手+5/上限60、每手共享断线宽限15秒为D配置,具体阶段与账号银行持久化见11.1。

11.1 断线宽限的执行顺序

关联TIME-03。本节V3.2以“每手共享的15秒离线宽限预算”明确原“每手一次宽限”含义,不因跨街或重复连接再次发放。以下为D裁定,时间统一服务端单调计时,金额动作须在截止前收到(收到时间等于截止视为超时)。

  1. 每次轮到行动先启动基础时间(默认20秒,按房间action_seconds);基础计时不因离线暂停。基础尚未耗尽就重连,继续原基础截止,不消费银行或宽限。
  2. 基础耗尽后,在线则按实际时间消耗银行;离线则冻结银行,消耗该手剩余宽限。银行阶段掉线,从掉线时开始消耗剩余宽限,不追溯扣除基础截止至掉线期间。在线且银行为0立即超时;离线且宽限为0立即超时,离线不自动消费银行。
  3. 宽限内重连立即停止消耗宽限,恢复剩余银行;不赠送新基础时间。余下宽限可供同手后续掉线使用,累计最多15秒;下一手重置为15秒。手间离线不消耗该手行动宽限,但A/B缺席和房间到期规则仍独立执行。
  4. 银行按user_id持久化,首次建立记录初始30秒、最多60秒;有效手累计每10手+5秒,只发一次。重连、换座、重新买入、换房不重置,也不重置有效手计数。服务故障暂停基础、银行、宽限及缺席倒计时,房间自然截止仍按第19章判断;撤销手不计有效手。重启恢复计时快照,不补满银行。
  5. 服务端快照包含BASE/BANK/GRACE/AUTO状态、基础剩余、银行余额、该手宽限余额及当前阶段截止;连接事件发生即更新,客户端不能用旧deadline宣称动作有效。
时间线(秒,基础20/银行30/宽限15) 明确结果
t=5离线,一直未回 基础至20;宽限20~35;t=35自动动作,银行仍30
t=5离线,t=25重连 宽限已用5、余10;银行25~55;t=55仍未动作则超时
在线至t=30后离线,t=40重连 银行已用10、余20;宽限已用10、余5;恢复在线银行至t=60
上例t=45再次离线 银行余15冻结;宽限最后5秒至t=50;仍离线则超时,不重发15秒

超时自动动作进入A/B策略;打开弹层不暂停时间。本期不提供带金额的回合外预操作。

12 钱包、账本与资产

需求ID:MONEY-01~MONEY-06、ASSET-01。

产品领域采用asset_id/precision/transferability,钱包、桌内托管和代理账按币种隔离。TEST是本期唯一资产实例,初始0、超管发放、不可兑换。完整首期功能仍包含资金记录、代理管理和房间业务;真实充值提现正式列为P2独立专项。正式通道未接入显示未开通,本期不创建虚假充值订单、地址或到账状态。

超管加款须记录来源类型TEST_GRANT/MANUAL_ADJUSTMENT/COMPENSATION,未来提现不得将所有手工加款自动视作可提:withdrawable默认false、变更需专项资金规则和审计。保留补偿、真实资产和提现资格字段;既有测试额度不得自动改成真实余额。

新环境为默认交付方式;旧库只读留存,不迁移余额、管理员、密码、令牌或权限。若以后另行批准迁移,必须用户映射、逐币种对账、重复导入幂等、异常清单后才导入。真人桌禁机器人和实时教练,隔离测试环境可用;这是归档V3.2的公平性产品裁定,不假称CSV明确要求删除全部旧功能。

12.1 账本与业务记录

采用可用余额、补码冻结、桌内托管、平台服务费、离座费、代理应计等账户。客户端余额仅是账本读模型,不可直接编辑。初始余额0;超管测试分配使用独立调整账户,默认单笔≤1000 TEST、单用户每日≤5000 TEST,可由超管版本化调整;实际资产限额独立配置。扣减只允许可用余额且不得为负,不能动用在手资金。

事件 转移 原子与幂等要求
超管加款/补偿 调整账户→可用 原因、二次验证、前后余额;重复业务号只一笔
买入 可用→托管 座位、资格、扣款同成同败
补码申请 可用→冻结 不进入当前手
补码应用/取消 冻结→托管或可用 竞争只成功一个;超上限退差
手牌结算 玩家贡献→合法赢家+平台抽水 hand_id/settlement_id唯一;规则快照一致
离座 托管→可用+离座费,另退冻结 seat_session_id唯一退出账,不能重复
代理计提 平台收入内划分应计 不从玩家再扣;日结键唯一
纠错/冲正 新反向或补偿分录 引用原单,不删除历史

字段:transaction_id、business_id、idempotency_key、user_id、asset_id、账户、整数有符号金额、前后余额、room_id、hand_id、seat_session_id、规则/协议版本、reason、operator_id、server_time、status、original_transaction_id。数据库交易状态为PENDING/POSTED/FAILED;冲正使用新的POSTED REVERSAL交易且不修改原交易。客户端可展示PENDING/POSTED/REVERSED/FAILED,其中REVERSED仅在存在有效完整冲正时由服务端派生,并同时返回冲正交易ID和时间;不能同时显示成功和失败,查询不重新执行业务。

我的资产展示可用、冻结、在桌托管及其总额,标清币种;账单默认近7天、可24h/7d/30d/自定义,按时间倒序+ID稳定排序,支持类型/状态筛选。详情可联动手牌、离座、买入或补码;看不到对手钱包。余额不足只显示缺口和额度/未开通说明,保留原房间上下文;余额恢复后重新校验座位,不保证原空座仍在。

P2真实支付专项必须补通道、币种/链、确认数、限额、手续费、状态机、冲正和提款资格需求;本期只保留后续建模边界,不创建真实充值订单,不拿截图中的OKPay/KKPay/USDT/TRC20演示当已签约通道。禁止在当前界面显示假的收款地址或到账成功。

13 统计、记录与回放

需求ID:STAT-01~STAT-05、REPLAY-01、BILL-01。

指标 当前统一定义
有效手数 本人已发底牌且正常结算的手数,作废/未发牌等待排除
牌局数 在一个room_id的一次入座资金会话且至少完成1手,重连不新增
VPIP 翻前主动追加筹码的手数/有效手数;盲/Ante/强制抓头不算主动;SB补跟算
PFR 翻前主动提高最高有效下注的手数/有效手数;全下跟注不算
获池率 获得至少一个有竞争池份额的手数/有效手数;未匹配返还不算
W$SD 进入摊牌且取得任一池份额的手数/进入摊牌手数;Muck输牌仍算进入摊牌;平分/边池获款计获胜
单手净收益 扣抽水后派奖+未匹配返还−本手全部投入;不再减一次归因抽水
会话净收益 全部单手净收益−离座费;未生效补码退款不算盈利
bb/100 100×Σ(单手净收益/本手BB)/有效手数;离座费另列,名称为“牌局bb/100”

个人“净收益”总览按已完成会话含离座费统计;进行中会话单独展示暂计、不混成最终。未来保险接入后净收益增加赔付、扣保费;目前保险字段null/未开通而非虚构0笔已完成业务。不同币种分开、不跨币种相加;长短牌分开;时间过滤按结算server_time的[start,end),会话收益按会话结束时间归属,明示两种筛选口径。

百分比1位小数、bb/100两位、金额两位;分母0显示—。VPIP/PFR按同玩法样本,W$SD分母独立。界面不将高VPIP/高胜率直接评为“强玩家”,不显示旧源码未经验证的盈利或升级盲注建议。

战绩会话列表:room_id、玩法、SB/BB、入座/离座时间、有效手数、买入、生效补码、返还、抽水归因(仅说明)、离座费、最终净收益、币种、状态。详情按手展示hand_id、时间、本人合法可见底牌、公共牌、动作、投入、派奖和结果,未结束手仅能看已公开内容。

牌谱回放以结构化事件重建,支持播放/暂停、上/下一动作、各街跳转,1×/2×速度;不需要存整屏视频。记录规则版本、初始座位筹码、强制款、各街动作目标及增量、公开牌、主边池、费额、赢家/尾分。普通玩家只能访问本人参与手,自己的底牌与当时已公开牌;其他人未公开牌不能通过拖动时间轴或直接接口泄露。后台回放同样遵循范围,私牌专项审计另走工单。

验算:两手净收益+2/-2,BB1/2,牌局bb/100=50;4次摊牌中一次平分、一次边池获款,W$SD50%。净收益总览因离座收费会不同于单手收益和,差额明确列出,不冒充账目不一致。

14 综合数据、主题、延迟与界面规范

需求ID:UI-01~UI-06、INFO-01。

延迟模式主需求为BOARD_EACH_STREET,默认OFF;本人每街第一次轮到行动才收到新增公共牌,已可见牌保留;弃牌/全下/观战者街末收到,自动发完阶段无需等不存在的轮次。HOLE_PREFLOP作为截图来源的可选扩展保留,默认不展示给普通开房者,仅运营模板启用;两种模式互斥。HOLE_PREFLOP中本人首次翻前轮到行动才收到本人底牌;开手强制款即全下者,在剩余下注完成进入自动亮牌时收到;公共牌正常广播。OFF模式本人底牌发牌后可见,公共牌随街广播。所有消息、重连和回放按服务端策略裁剪,不声称实测可防伙牌。

“综合圆环”未查得OK德州可验证的公开计算公式,CSV附带的循环加注解释也不能推出个人综合评分。自主裁定为综合数据三环,保留综合展示功能而不是改成单个VPIP:三条独立同心圆分别为VPIP、PFR、W$SD,每环角度=360×该指标比例,固定标名,不相加、不加权生成实力分。中心显示有效手数,点击展开三个分子/分母及解释。指标定义按第13章与公开统计参考,W$SD平分获款计胜。[R05]

长短牌分开,24h/7d/30d/全部;分母0显示“—”且不绘制进度。有效手不足20标“样本不足”;W$SD按自身摊牌样本数标注,不用总手数掩盖小样本。VPIP准入仍以同玩法最近100手、至少20手为默认,只在入座校验;本期不以三环判定强弱或准入。例100手、主动入池40、翻前加注15、摊牌20/获款9:三环40%/15%/45%,角度144°/54°/162°。该展示是D,不能声称复刻了竞品算法。

归档已记录对《assets/evidence/screenshot-001.jpg》的核对:牌面四项“经典、四色、全色、点数”,全部保留;预览两张牌,选中描边、保存后应用并关弹层返回来源,取消不保存。归档当时的design.js也列四项。牌桌/牌背截图无完整选项,裁定复用本项目现有素材:牌桌翡翠/石墨/午夜蓝,牌背经典红/深海蓝/墨绿;默认经典牌面+翡翠+经典红。牌桌/牌背属于自主补全,不标为OK德州已验证选项。配置按账号保存,当前设备立即应用、下次登录同步;非法或下架主题回退默认,保留用户其余选项。

移除页面自绘“中国移动”、系统时间、电量等假状态栏;首期遵循浏览器视口、移动端安全区和安装为PWA时的真实宿主区域,未来TG接入再适配其宿主导航与安全区。经典/四色/全色/点数必须在各花色、大小牌、当前底牌及回放均一致;改主题只改展示,不改牌值或他人界面。

14.1 通用交互与字段来源

逻辑基准360×640,首期验证320/360/390/430宽度及桌面Chrome/Edge/Safari兼容浏览器;未来TG阶段追加iOS/Android/Desktop Telegram宿主验证。最小触控区44×44逻辑像素。长规则、开房表单、账单可滚动,底部主按钮与软键盘、安全区不互相遮挡。状态不能只靠红绿区分;金额、倒计时、错误具有文字。字号放大后优先保留合法动作及金额可见。

牌桌显示座位头像/昵称/筹码/操作状态、D/SB/BB/抓头标记、当前街、公共牌、主/边池、轮到谁与截止、连接状态。公共桌内筹码不同于钱包余额,其他玩家只见桌内公开筹码。当前用户默认固定视觉底部,但所有位置规则以逻辑seat_no为准,旋转视角不能改变行动顺序。

BB显示=金额/该桌BB,最多两位用于阅读;提交确认仍显示精确原币金额。牌型提示只基于本人已收到的牌计算,牌张不足5张时可展示已成对子等事实,不预测未来牌/对手牌/胜率;被延迟牌不能被提示泄露。音效与振动默认关闭,开启后遵循宿主授权,失败可静默回退并保留开关说明。

查询型异步页面至少具有加载、成功、空、失败重试、权限不足状态;会改变房间、座位或资金的提交另须遵循4.3节SUBMITTING、UNKNOWN、FAILED、SUCCEEDED状态契约。UNKNOWN不能当作FAILED,不得自动退款或发起新请求;明确失败保留仍合法的输入。旧余额标最后更新时间,不能当作下单依据。房间信息、买入确认、费用说明、手牌记录及后台从同一规则对象取值,禁止分别写死“5%”。

15 聊天、语音与客服

需求ID:CHAT-01~CHAT-04、SUPPORT-01。

聊天默认(D): 同桌已入座玩家可发文字、快捷语和免费表情;旁观者只读,客服可发带身份标识的巡检提示。每条文字1–200字符,最多每2秒1条、每分钟10条;服务端过滤控制字符并转义显示。禁止链接自动跳转,提供举报和禁言。禁言期限10分钟/24h/永久,必须记录原因,永久仅运营/超管。

语音转文字纳入本期范围: 点击录音前申请麦克风权限,最长15秒、文件≤2MB;由ASR接口转写,先展示可编辑草稿,用户确认后才发聊天;不能把录音直接广播。转写失败、超时或权限拒绝保留文字输入。建议请求超时10秒、文本成功回填率≥95%、正常网络P95≤5秒;验收使用50段授权普通话样本,包含扑克术语和背景噪声,指标为产品目标,尚未实测。

浏览器SpeechRecognition兼容性有限,首期采用HTTPS录音+可替换服务端ASR,供应商和密钥是外部接入条件。原始音频转写后删除,失败缓存最长24h。录音和语音输入先在目标移动浏览器验收;iOS/Android Telegram真机验收随TG接入阶段执行。[R08]

快捷语候选:“你好”“打得不错”“稍等一下”“谢谢”“我先离开”;不自动发送手牌内容。文字聊天保留30天(内测建议),举报关联记录保留至工单结束;付费礼物后置。实时反伙牌初期仅做异常提示和人工审查,不能声称自动识别准确率。

15.1 消息、举报与巡检契约

message_id与client_message_id幂等,字段含room_id、sender_public_id、类型TEXT/QUICK/EMOJI/SYSTEM、服务端时间和状态。断线重发同ID不重复入列;被禁言请求拒绝。只在用户主动确认时发出语音转写结果,不广播原音频;表情从免费目录选择,不允许注入任意HTML/远程脚本。用户屏蔽只影响自己接收普通聊天,系统结算/安全提示不能屏蔽。

举报提供对象消息/手号、原因(辱骂/骚扰/疑似伙牌/其他)、补充说明≤500字,生成工单ID和提交成功状态。客服只能看分配或授权范围工单;重复同对象24h合并追加。处理状态OPEN→IN_REVIEW→RESOLVED/REJECTED,记录处理人、理由、时间与实际操作。禁言10分钟/24h/永久;永久仅运营/超管。禁言不冻结筹码、不改变手牌结果。

客服巡检身份显著标识,默认只看公开桌面、不占玩家座位,不计开局人数、不发手牌;可发巡检提示、登记异常,不能代替玩家下注。已加入房间被禁止发言的旁观者仍可提交举报,不获得聊天权。反伙牌线索(重复同桌、设备/IP关联、异常让利)只产生工单,不自动判作弊或扣款。

15.2 我的举报与结果反馈(F07,D)

关联CHAT-03、SUPPORT-01。“我的→帮助与客服→我的举报”提供本人记录列表和详情,默认近30天、分页20/最大100;显示提交时间、本人填写的对象/原因、工单公开编号、状态(已提交/处理中/已处理/未采纳)、最后更新时间及客服填写的公开结论。普通用户只能查自己提交记录,不能通过编号枚举别人的举报。

同举报人+同对象24h内重复提交合并为原编号的追加内容;不同举报人保持各自私有提交记录,后台可关联同一内部案件,前台不显示其他举报人及内容。结案必须填写公开结论(1–500字)与内部处置记录,不能公开私牌、IP、他人身份或处罚资金详情。RESOLVED与REJECTED均回传公开结果;结案时站内显示未读标记,下次登录/回前台刷新,打开详情已读;不要求TG主动推送。

用户不同意结果可在详情点击“补充说明”,追加至原记录,已结案则重新进入IN_REVIEW;遵循每账号每分钟最多3次提交/追加的限流。记录随工单/审计保留365天,关联证据至少保留至结案;超过保留期明确“记录已过保留期”,不泄露其他对象。

16 运营后台完整功能

需求ID:ADMIN-01~ADMIN-10、AUDIT-01。

恢复普通管理员代理管理功能,并明确scope。运营角色默认拥有其授权俱乐部范围的创建代理、编辑代理名称/等级/状态、设置等级分成比例、邀请审核能力;服务端检查agent_id、club_id和授权上限,不以UI隐藏代替权限控制。跨范围、给自己增权、编辑超管均拒绝。超管配置权限边界/佣金比例上限;运营可在范围内创建自己的等级版本,不能修改其他运营的共享等级。停用代理不删除历史计提,后续归因默认平台,直至显式指定有效代理。

能力 超管 普通管理员/运营 客服 代理 普通成员
创建代理/编辑等级/配置比例 全局 授权范围+比例上限 否 否 否
设置运营授权范围/上限 是 否 否 否 否
开房/关闭/成员管理 全局 授权范围 巡检 按专项授权 玩家开房开关
手工加款/扣款/纠错 是 否 否 否 否
结算账/分成统计 全局 范围内 否 本人 本人账单
修改自身后台密码 是 是 有后台账号时 有后台账号时 不适用;玩家登录密码与后台密码分离
成员基础目录 全局 范围内 范围内 归属俱乐部 归属俱乐部

后台“系统设置”包含:修改自身密码、系统邀请码列表及签发/撤销、授权管理(超管)。后台改密需旧密码和二次验证成功,新密码至少12字符、最长128字符;服务端按现代口令哈希保存;成功后失效该后台账号所有后台会话、要求重新登录,失败不影响现有会话。连续5次验证失败锁定改密操作15分钟并留审计;恢复通过第16.2节受审计的重置流程,不提供读回明文。此阈值是D,不是安全标准宣称。玩家本地登录凭据属于独立认证域,不与后台账号、密码策略或会话互通。

系统邀请码属于第06章的同一对象体系,列表有目标、策略、签发人、使用数、状态和申请入口;后台超级权限不在邀请码里传播。邀请审核、签发、撤销均为独立能力:超管可撤销任意业务邀请;运营只能撤销本人签发且目标仍在其授权范围内的邀请。

补齐显示列:收入备注;加款记录user_id、发生时用户名、当时所属代理ID/名称、金额、币种、原因、操作者、时间、前后余额;代理列表名称、等级、注册时间、所属人数、累计/已结算/未结算佣金。快照用于历史展示,另可链接当前对象,改名/转代理不改旧记录。实际充值未接入显示“未接入”,不把手工加款当充值。列表/汇总/导出统一Asia/Shanghai、同筛选、同币种,时间区间[start,end)。默认近7天、20条/页。

16.1 后台信息架构与页面操作

页面 必备字段/筛选 允许动作 关键异常
运营总览 日期、币种、有效用户/手数、抽水、离座费、代理计提、异常数 下钻同口径明细 无数据与加载失败分开,不混币合计
用户列表/详情 ID、展示名、状态、代理/俱乐部、分币余额、注册/最近登录 查记录、范围内禁用/解禁、归属申请、超管资金调整 不可操作上级管理员;在手禁用正常结算
登录记录 时间、IP、设备摘要、结果、user_id 授权查询/工单关联 客服/普通成员不见敏感IP
俱乐部 ID、名称、代理、成员数、状态、房间数 创建/编辑/冻结/归档/运营授权 未清算不能归档;冻结不吞款
房间 ID、模板版本、人数、起止时间、状态、累计手数、收费 创建/单次排期、手后关闭、故障暂停 不能强跳结算/改牌/实时透视
用户战绩/牌谱 用户、房间、日期、币种、玩法、单手/会话结果 公开权限回放、工单审计申请 范围外拒绝,私牌审计不能只改前端开关
充值/消费/加款记录 类型、状态、原因、金额、快照、关联业务号 查询/导出;超管纠错 实充未接入显示未接入,手工加款独立类别
收入 hand_id、room_id、费率、cap、抽水、离座费、备注、币种 查看/筛选/导出、附加备注 不修改历史费用;备注修改需审计
代理/等级 ID、名称、状态、等级、邀请码、人数、比例、生效期、分成合计 授权创建/编辑/停用/发布等级 超上限或跨范围拒绝;历史协议不覆盖
分成结算 代理、日期、币种、基数、应计、冲正、已结/未结 账单查询、超管测试结算标记 不伪装真实支付已完成;重复日结幂等
邀请/审核 目标、策略、签发者、使用数、申请人、状态 签发/撤销/批准/拒绝 房间关闭或码撤销不能批准
巡检/工单 原因、对象、状态、负责人、处理轨迹 分配、禁言、结案、申请私牌审计 无工单不得读取隐藏牌
规则模板 模式、盲注、费用、买入、时间、版本、状态 草稿、校验、发布、退役 发布后不可覆盖;旧桌冻结版本
系统/审计 本人账号、角色范围、授权上限、行为记录 改密;超管授权;只读审计 首账号不自提权,审计不可删

高风险操作(加款/扣款/资金纠错/授权/私牌审计)要求独立二次验证和原因;不在通用列表行内直接一步成功。IP、私牌、全局审计和导出均使用独立动作权限,任何角色默认不因获得列表/详情权而自动获得这些权限。导出采用相同授权和筛选,字段不得超过页面查询字段权;记录导出人/范围,文件链接仅供当前授权会话访问,自生成15分钟到期且撤权立即失效(见16.3);最大区间31天,超出拆分,避免无限同步导出。普通列表20条默认/100条上限,超限返回INVALID_PAGE_SIZE。

俱乐部/代理停用影响未来归因与准入,过去账单仍可查;历史用户名、代理名和比例快照不可被当前字段覆盖。按Asia/Shanghai显示,后端存UTC;统计自定义区间用左闭右开,所有合计按币种分组。

16.2 后台认证与敏感操作授权(F01,D)

需求ID:ADMIN-10(P0),关联ADMIN-06、ADMIN-01、MONEY-01、AUDIT-01。采用独立后台账号+密码+认证器TOTP;普通玩家登录或未来TG登录均不代替后台认证。密码规则沿用12–128字符。TOTP采用6位、30秒步长、允许前后各1步时钟偏差,已成功使用的时间步不能用于另一登录/授权;仅为本项目实现参数,不宣称防钓鱼认证。认证与恢复原则参考S01,项目未要求采购第三方身份平台。

超管在具备二次验证的操作中创建后台账号和最小授权范围,状态INVITED;服务端生成24h有效、单次使用的激活凭据,仅向创建者显示一次,由其通过已核实的人员联系渠道交付。激活页只能设密码、绑定认证器、验证首个TOTP并生成10个一次性恢复码(仅显示一次);完成后ACTIVE。未完成不发业务会话;过期/重发使旧凭据失效,停用为DISABLED,激活凭据不能赋予超出记录的权限。首位超管由部署负责人通过一次性本地初始化命令创建,不能依赖首注册者自动提权;初始化后关闭入口。

登录须密码和TOTP均成功。连续5次密码/TOTP失败锁账号登录15分钟,IP每分钟最多30次认证请求;账号不存在也返回同样失败文案。成功完整认证清连续失败数,锁定不泄露账号存在性。后台会话空闲15分钟、绝对8小时;空闲只由用户主动查询/操作延长,心跳、轮询不续期。退出当前会话;改密、停用、认证器重置或角色/范围变更使该账号全部会话及未执行授权立即失效,下一请求按最新权限拒绝。服务端执行过期检查(S02)。

加款/扣款/纠错/授权/私牌审计/创建后台账号/认证器重置,均先显示对象、金额币种或权限范围、原因,再重新输入TOTP。验证成功产生绑定admin_id、session_id、operation_id与规范化参数摘要的单次授权,有效120秒;只有该次操作可用,不提供120秒全局免验证。修改对象/金额/范围须重新授权,执行前重验权限、时效和摘要;相同operation_id重试查询原结果,不再次执行。授权失败5次锁敏感验证15分钟并作废当前挑战,不影响只读会话;已登录TOTP不能复用到敏感操作。改密额外要求旧密码,沿用其5次错误锁改密15分钟。设计依据见S03;所列时间为D默认。

恢复码只能配合正确密码进入受限恢复会话(15分钟),仅允许重新绑定认证器;不能直接加款、改权或看私牌。重绑后废除旧密钥、旧恢复码及所有会话,重新生成10码并要求正常登录。密码或全部第二因素遗失时,由另一超管在验证人员身份并记录核验渠道/理由后,执行单次24h重置邀请;管理员不能审核自己的人工重置。唯一超管失联时,部署负责人通过受控本地恢复命令记录工单号和操作者生成同类重置邀请;无公开网页绕过接口,不恢复旧明文凭据。新认证器验证完成前保持RESET_PENDING、无业务会话;恢复与重置操作写审计,用户下次登录强制展示变更时间和原因。

16.3 导出与运营指标补充(D)

导出链接自生成起15分钟有效,绑定发起后台账号、会话和原筛选范围;每次下载重新校验当前权限,退出/会话过期/撤权后立即拒绝,不因链接尚未到期放行。生成期间权限变化则任务失败,禁止缓存文件继续下载。过期需重新请求,历史导出审计仍保留。

总览“有效用户”=筛选业务时间内至少完成一手有效手的去重user_id;按第13章settled_at及币种过滤,跨币种总览显示分组,不能相加去重人数。“有效手数”=正常SETTLED的去重hand_id,不把每名玩家的有效手计数相加。抽水、离座费分别按其业务提交时间;代理应计按第10.3.1节业务日列示,并显示重算状态和调整明细。原“已结/未结”佣金分列应计、测试支付标记和差额,避免混淆真实支付。

17 公平性、隐私与风控

需求ID:FAIR-01、PRIVACY-01、RISK-01。

除第20.1节明确标识的隔离测试预设手外,首期使用服务端安全随机源和正确洗牌,开手后牌序固定并持久化,恢复不能重洗。普通客户端仅收到本人合法时点的底牌与已公开公共牌;烧牌、未来牌、未公开对手牌从未发出,而不是用CSS挡住。日志按用途拆分,普通排错日志不能输出完整牌序、凭据或所有私牌。

公平性页面保留机制介绍和单手记录入口。演示样例必须标“演示,未进行链上核验”;实际手牌proof_id/commitment/verification_result未接入为空,不显示验证成功。历史截图中SGX、量子随机数、公证码和全牌组公开属于后续目标材料,不成为现阶段技术承诺。展示“当前手/已结束”来自手牌状态,不能出现并不存在的下一手已生成证明。

后续链上核验需另定承诺生成时间、随机输入、牌序编码、切牌/烧牌、密钥公开时点、弃牌隐私、验证失败处置;在未定义前不开放全牌组下载。管理员私牌审计只对结束手、有效工单、限定手牌/玩家/用途开放;申请人与审批人不同,由具备专项审批权的超管审批,批准后30分钟有效。每次实际访问还需120秒参数绑定TOTP单次授权;会话失效、撤权或工单失效立即失效,并记录目的、访问时间、对象和结果。超管前台也不实时看对手底牌。

账户禁用禁止新买入和新主动参与,在手按已定义托管结算并返余额;不把禁用等同没收资产。设备/IP线索不自动证明伙牌;处罚和资金纠错分别记录。真人不允许旧机器人/实时教练接口,测试环境物理或逻辑隔离,不计入真人统计。

18 数据对象与跨模块契约

需求ID:DATA-01、DATA-02、API-01。

业务对象 必备信息与不变量
User/Identity/Session 稳定game_id/player_id、LOCAL/TELEGRAM身份映射、展示资料、状态;核心账号、认证身份、凭据与会话分离
Club/MembershipHistory 归属及生效时点、代理、运营范围;一人当前一个归属
Agent/Agreement 等级、比例、授权上限、生效版本;每手快照
Invite/Application 目标/策略/期限/撤销与独立审核对象
RuleTemplate/Room 完整规则版本、允许编辑字段、状态、起止时间、币种
SeatSession 用户房间座位、买入/补码本金、开始结束、退出账和原因
Hand/Action/Pot 固定初始快照、合法动作序列、贡献、资格、牌序和结算
TestDealRun scenario_id、run_id、内容摘要、目标、hand_id、消费状态;绑定与开手提交一致,不向普通客户端公开完整预设
LedgerTransaction 业务唯一号、有符号零和分录、币种、金额、前后余额、原单与冲正引用;REVERSED为展示派生状态
CommissionAccrual 实收抽水归因、代理协议快照、计提日与冲正
Chat/Report/Ticket 消息幂等号、范围、举报关联、状态和处理记录
Audit/ConfigVersion 操作者、时间、对象、前后值、理由、请求号

数据库实施采用强约束方案:相同模板和参数允许创建不同房间的独立不可变规则快照,内容摘要不作为房间唯一键;邀请申请提交、审核和后续状态事件分别绑定业务操作;玩家归属、直接代理、后台角色/范围和禁言的活动关系不得重复或重叠;权限变更和私牌审批/读取必须由参数绑定的单次授权及受限数据库函数执行;恢复冻结资金按玩家、资产、账户/原交易保存明细,页面只做分资产汇总。以上是现有业务要求的技术落地边界,不新增玩家功能,也不表示DDL已经执行。

动作输入至少session、room_id、hand_id、state_version、action_id、action_type、target_amount。响应包括accepted/rejected、错误码、新版本、合法动作、跟注成本、最小/最大目标、deadline及经过裁剪的状态。重复action_id返回原结果;旧手/版本拒绝,不重解释为新轮下注。并发买入、退出、补码和结算均有业务幂等键。

接口能力清单(能力契约,非宣称已有端点):玩家注册/登录/退出/会话刷新与设备接管;预留外部身份绑定;俱乐部资料/房间/成员查询;邀请校验/申请/审批;房间创建/关闭/模板查询;座位预约/买入/补码/取消/换座/退出;动作/恢复快照;账单/战绩/回放;偏好;聊天/转写/举报;后台用户/代理/等级/资金/审计。所有写请求须鉴权、范围检查和审计;具体URL与数据库结构由实现设计细化,不影响业务定义。

关键错误语义:AUTH_INVALID表示凭据无效但不泄露账号是否存在;AUTH_LOCKED返回可重试时点;AUTH_EXPIRED要求重新登录并保留合法返回目标;IDENTITY_CONFLICT用于未来外部身份已绑定其他玩家;FORBIDDEN不重试越权;INVITE_INVALID/EXPIRED/REVOKED/REVIEW_REQUIRED明确邀请状态;ROOM_FULL/ROOM_CLOSED/ROOM_NOT_OPEN保持房间上下文;INSUFFICIENT_BALANCE显示金额缺口;VPIP_REQUIRED显示阈值与样本;STALE_ACTION刷新状态;ILLEGAL_RAISE显示当前最低目标;SETTLEMENT_PENDING查询原业务不重新下单;RATE_LIMIT显示可重试时点。错误不能把尚未扣款显示成已退款。

19 故障恢复与结算一致性

需求ID:RECOVER-02~RECOVER-04。

预设测试手同样遵守本章:恢复已提交牌序和运行消费记录,不重新读取预设替换当前手,不重复消费run_id;具体见第20.1节。

房间故障暂停全桌计时,恢复最后已提交动作和牌序。手牌状态STARTED→SETTLING→SETTLED;异常可VOID或RECOVERY_REQUIRED。结算账本与终态原子提交,广播失败只补发通知。客户端断线后恢复同一hand_id、state_version和合法动作,不自动重送失效下注。

已提交结算返回同settlement_id与金额。未提交且日志可恢复,继续原手。未提交且无法恢复但有可信手前快照,作废本手、冲回实付贡献、撤销本手费与计提,保留前手结果和独立补码;已返未匹配款要去重。无法判断是否提交则冻结核查,不自动再次退款。冻结核查按玩家、资产、账户/原交易/资金会话保存明细,不能只保存无币种总额;冲正、释放或继续冻结逐项记录。人工纠错通过新授权分录引用原单,不覆盖余额或删记录。

自然到期与故障相遇不再开新手,完成恢复后按到期免离座费清算。重启保留邀请撤销、禁用状态和规则版本,不回到宽松默认。后台导出/统计可延迟更新但要显示数据截止时间,不能改变原账本结果。

20 非功能需求与发布条件

需求ID:NFR-01~NFR-05。

类别 验收要求 测量条件/失败处理
正确性 任意手筹码守恒、零重复业务账;服务端规则唯一 金额错误阻断交付,暂停受影响桌并核查
性能 500在线连接、50桌×8席,服务端动作P95≤200ms 固定部署资源、2小时稳态;记录CPU/内存与并发模型
网络/首屏 同区域动作往返P95≤800ms;首屏P95≤3秒 标注4G网络、设备、冷/热缓存;失败不宣称达标
重连 网络恢复后P95≤5秒;弱网不重复下注 真机切后台/重连/服务重启分别测
ASR 50段授权普通话扑克样本,草稿回填≥95%,P95≤5秒 回填不等于词准确率;保留识别错误清单并确认后发送
兼容 首期移动/桌面浏览器,320–430宽及大字;后续追加iOS/Android/Desktop TG 每端记录OS、浏览器与设备;TG未接入前不得宣称已通过TG真机
安全 TLS、服务端会话/RBAC、口令安全哈希、认证限流、资金幂等与二次验证 空密码、未公开牌/凭据泄露或越权均阻断交付
可访问性 44×44触控、非仅颜色、键盘不遮关键操作 长内容滚动与焦点恢复检查
可观测性 请求ID、业务ID、规则版本、错误率/延迟/对账告警 日志不含密钥与普通访问者无权看的私牌
备份与恢复 测试环境每日备份;生产每日全量备份+WAL连续归档及恢复演练 已确认动作不丢失为目标;未提交动作允许拒绝重试

V1统一保留基线:牌谱180天,账本、审计、举报及工单365天,聊天30天;工单证据至少保留至结案,超过聊天默认期的关联证据单独保全;ASR成功后立即删除音频,失败缓存最长24小时。该基线适用于产品和技术实施,不宣称满足任何特定法域的法律要求;法定保全或已被纠错/工单引用的数据不得按普通到期任务删除。

首期上线资源条件:域名HTTPS、服务器与存储、玩家认证密钥/会话配置、初始管理员范围、ASR服务、正式协议主体/内容;Telegram Bot及凭据属于后续TG接入条件,不阻塞首期Web开发验收。未来正式资产另需通道及提款策略。缺真实资源时可通过隔离模拟完成对应契约测试,交付报告必须区分模拟与真实接入。

发布方式:先测试环境全流程→受邀小范围试用→根据实测扩容。任意P0资金/权限/私牌问题立即暂停新买入,保留当前手恢复与清算,回滚应用版本不能回滚已记账资金。没有容量证据不承诺全量生产SLA。

20.1 测试环境脚本预设发牌

需求ID:QA-02。优先级P1;环境隔离、隐私和恢复继续遵守现有P0要求。开发与测试通过预设牌面稳定复现皇家同花顺等低概率场景。本节“原文明示”来自2026-09-19原始txt,“既有约束”沿用原PRD,“D裁定”为归档合入采用的开发默认。

部署配置:test_deal_enabled默认false;test_deal_script_path默认空、启用时必须指定受控服务端本地文件;test_deal_user_allowlist默认空、启用时须配置稳定game_id集合。三项均由开发/测试部署管理,运营后台不可写;环境资格由受控部署环境判定,不能由预设文件自报。预设场景的deck_mode必须与目标房间一致。

20.1.1 入口与适用范围

  1. 原文明示: 开发、测试人员通过服务端脚本配置目标房间或测试账号、公共牌和底牌。运营后台不提供该能力。
  2. D裁定: 仅隔离开发/测试环境允许启用,且目标房间使用不可兑换TEST。不能只凭币种为TEST判断环境安全;正式环境即使误设开关也拒绝启用并报告配置错误。
  3. D裁定: 服务端启动开关默认关闭。关闭时不读取预设文件,所有房间遵循正常随机发牌。脚本生成本地结构化预设文件,服务端读取数据;不增加上传脚本或远程执行任意代码的入口。
  4. D裁定: 启用期间,在开手准备阶段、扣强制款之前读取并校验预设;只影响之后的新手。已开始的手牌不受开关切换、文件修改影响。

20.1.2 房间与账号匹配

  1. 原文明示: 支持房间号定位,也支持指定某几个测试账号所在房间。
  2. D裁定: 每条预设使用且仅使用一种定位方式:room_id或test_user_ids。账号使用稳定game_id,不使用登录名、昵称、TG展示名或易变username。
  3. D裁定: 账号方式要求所列账号均在同一房间,并全部进入本手锁定的参局名单;不采用“任意一个账号所在房间都生效”的宽泛匹配。匹配阶段先于底牌资格校验;未聚齐或尚未全部参局时为NOT_MATCHED,预设不消费、提供等待原因,相关房间继续正常随机,不执行下一条的已命中校验。
  4. D裁定: 目标房间所有本手参局者均须属于测试账号白名单。底牌按稳定账号绑定;仅在目标已命中后,指定底牌的账号缺席、等盲未入局或不在该房间时,目标手准备失败,不把其牌移交其他座位。
  5. D裁定: 同一房间同时命中多条预设视为冲突,阻止该桌开新手并报告原因;不按文件顺序偷偷覆盖。不同房间的预设互不影响。

匹配裁定补充(F08,D):room_id方式在目标桌准备新手时即命中,底牌账号等盲则阻止该桌开手;test_user_ids方式只有所列账号全部在同桌本手名单中才命中,等盲账号导致NOT_MATCHED,不暂停。账号方式的hole_cards键必须是test_user_ids的子集;禁止用额外底牌账号引入第二套定位。语法/重复ID/非法牌/容器等静态错误在匹配前校验;文件静态校验失败按20.1.4阻止该实例新手。运行状态如账号等盲只影响匹配,不属于文件损坏。

20.1.3 牌面编码与完整牌序

  1. 既有约束: 长牌52张、短牌36张(6~A),均无大小王。本版统一用AS、TH等编码:点数2–9/T/J/Q/K/A,花色S/H/D/C分别表示黑桃、红桃、方块、梅花。编码属于归档V3.2裁定,不是原文强制格式。
  2. D裁定: 每条预设给出恰好5张公共牌,顺序为翻牌3张、转牌1张、河牌1张;每个指定账号恰好2张底牌。可只指定部分参局者,其余底牌由剩余合法牌补齐。
  3. D裁定: 全部指定牌必须互不重复;非法编码、大小王、短牌中的2~5、牌数错误均拒绝。公共牌和各玩家底牌之间也不能重复。
  4. D裁定: 先锁定参局名单和庄位,按第9.1节底牌两轮及三个烧牌位置,将指定牌映射到完整牌堆。剩余合法牌只洗一次并填充未指定底牌、烧牌和其余牌堆;完整牌序在开手时持久化。此处确定的是指定牌,未指定部分不承诺每次新执行都相同。
  5. 既有约束: 不跳过烧牌、盲注、Ante、合法行动、摊牌和结算。只有正常推进到对应街才公开预设公共牌;若其他玩家全部弃牌导致提前结束,剩余公共牌仍不展示。

20.1.4 生效次数、异常与恢复

以下为归档V3.2裁定:

  • 每条预设具有唯一scenario_id、内容版本摘要和独立run_id,默认单次使用。再次执行需创建新的run_id,避免文件留在服务器便无限重复。
  • 命中预设但校验失败时,目标桌暂停开新手并输出原因,尚未扣强制款;不能悄悄回退为随机发牌并让测试人员误以为预设成功。文件无法读取或解析时,启用预设的实例阻止开新手;已有手继续按持久状态运行。
  • 预设绑定hand_id、消费记录、初始完整牌序和强制款提交保持一致;开手失败不消费,成功后同一运行不能被并发开手再次使用。
  • 重连、进程重启及事件重放均恢复原hand_id与原牌序,不重新读取文件替换当前手;手牌作废按第19章冲正,保留该次预设执行记录。重测显式创建新运行。
  • 单次执行完毕、且没有其他命中预设时,该桌后续手恢复正常随机发牌。

预设文件统一为schema_version=1与scenarios数组,空数组表示无预设;不接受裸单对象。每文件最多100条、1MiB,超过拒绝;scenario_id/run_id为1–64字符的字母数字、下划线或连字符,分别在文件内唯一。未知字段拒绝,更新通过完整文件原子替换,不读取半写文件。示例TEST_USER_A/B仅为稳定账号占位值。

run_id在整个测试部署中唯一,首次校验通过登记其规范化内容摘要,绑定后不可改;即使尚未消费,同run_id异内容也返回RUN_ID_CONFLICT并阻止实例新手,须换新run_id。同ID同内容且已消费则跳过,不再参与多预设命中竞争。运行登记与消费记录保留365天;清理后重用run_id不受支持,脚本须始终产生新ID。不同实例共享登记与消费语义,不能各自执行一次(S04仅支持幂等原则)。

20.1.5 标识、隐私与证据

  1. 既有约束: 预设不能改变底牌、未来牌、烧牌、Muck及延迟模式的访问权限。普通消息、重连和回放依照第09、13、14、17章裁剪。
  2. D裁定: 测试手标记deal_source=SCRIPTED_TEST,关联场景、运行、摘要和手号;普通客户端只显示“测试预设牌局”,不返回预设文件或完整牌序。正常手标记RANDOM。
  3. D裁定: 预设测试手保留测试账本、战绩和牌谱,供金额与展示核对;不得混入正式玩家统计或被作为随机公平性验证成功的证据。完整预设和牌堆仅在受控服务端持久化与测试证据中保存,普通日志只记录定位信息与错误原因。

20.1.6 预设示意与预期

下例为本版数据契约示意,不是已实现接口。仅在指定测试房间、两个账号均实际参局且均属测试白名单时适用。

{
  "schema_version": 1,
  "scenarios": [{
  "scenario_id": "long-royal-flush-01",
  "run_id": "long-royal-flush-01-run-001",
  "target": { "room_id": "TEST_ROOM_001" },
  "deck_mode": "LONG",
  "board": ["QS", "JS", "TS", "2D", "3C"],
  "hole_cards": {
    "TEST_USER_A": ["AS", "KS"],
    "TEST_USER_B": ["AH", "AD"]
  }
  }]
}

账号定位的替代写法为:"target": { "test_user_ids": ["TEST_USER_A", "TEST_USER_B"] },与room_id二选一。

两名玩家均未弃牌并推进至摊牌时,A为皇家同花顺,B为一对A,A在其有资格争夺的池中获胜;具体金额仍按投入、边池和收费规则计算。该示例含2、3,不能直接用于短牌。

预设牌面本身不能完整构造边池、超时或断线场景,还需要测试步骤控制筹码、行动和故障。该项原文没有要求自动代操作,故不将动作脚本引擎纳入新增需求。

20.2 交付测量基线与异常处置(D)

容量验收固定基线:应用节点4vCPU/8GiB,持久化节点4vCPU/8GiB、SSD、同区域;报告记录操作系统、CPU型号、数据库版本及磁盘实测,不将本基线冒充已部署资源。预热10分钟后稳态2小时,500连接=400入座(50桌×8长牌席,均选3小时房间避免稳态期间自然到期)+100旁观;50桌持续按合法动作推进,平均每桌每2秒一次动作,额外每5秒一次房间查询/每30秒一次本人记录查询,20桌每10秒一条合法聊天。测量正常业务,不使用忙循环或非法动作凑吞吐。另用相同连接规模进行一次10%连接断开30秒再恢复的故障段,单独统计不混入稳态延迟。

服务端动作延迟从接收完整合法请求到持久提交并生成响应;网络往返从客户端提交到收到确认;首屏可用从目标浏览器导航开始,到本地身份已确认且俱乐部列表或真实空态可交互(失败页不算可用)。4G基线使用下行10Mbps/上行2Mbps、RTT80ms,冷/热各30次、分别计算P95,记录实际设备及限速方式;真实移动网络抽测另报,不用模拟取代目标设备。未来TG接入后,以相同口径补测WebView首屏并单独报告。绝对时延目标沿用上表,非预期错误率≤0.1%、资金/权限错误必须0;负载脚本记录随机种子、版本和原始结果。

故障自动恢复目标:服务进程可重新运行后60秒内恢复已提交事件,未恢复则升级RECOVERY_REQUIRED并进入自动告警/待处理队列;无法确认资金仍禁止自动退款。告警后5分钟内必须产生已确认状态,30分钟内记录继续恢复/作废冲正/保持冻结的处置及下次更新时间;超时按发布时配置的升级渠道通知,不设“到时强制退款”。这是测试/受邀试用的运维验收目标,不承诺正式经营SLA。未配置真实当值渠道时不得标记有人值守。

20.3 加入转化与事件口径(D)

由服务端成功鉴权、确认房间访问资格且未被满桌/关闭/VPIP/资金不足阻断时记录ELIGIBLE_ROOM_ENTRY,生成journey_id,标entry_source=INVITE或CLUB_LIST;同用户+同房间30分钟内重复进入/重连沿用同journey_id,使用第一次合格入口归因,不跨两个入口重复计数。窗口内首次BUYIN_POSTED为成功,超30分钟新建旅程;后续发生满桌/余额变化计失败原因,不事后删除已合格分母。跨日旅程按首次合格进入日计,次日等足30分钟后再定稿。

加入转化率=成功买入journey数/合格journey数;无分母显示“—”。发布首14天分别列邀请/列表分母、分子、转化率和失败原因,不设虚构提升目标。候选入口被初始资格校验拒绝另列拒绝数,避免只报告成功链路。测试预设手及隔离环境事件不混入正式业务指标。

21 验收、需求追溯与实施顺序

需求ID:QA-01、PLAN-01。

本期优先级以《需求总表》每个稳定ID为唯一权威。P0包括后台认证、统一玩家账号与本地注册登录、授权、邀请审核与撤销规则(INV-02)、回放权限与一致性(REPLAY-01)、牌组/下注/分池、费用、买入补码/退出、账本、恢复、信息隔离。P1包括其余表内标P1的页面体验、统计、运营、聊天语音、主题快捷、单次运营排期和测试预设工具。Telegram Mini App验签、TG深链/分享和账号绑定列入后续接入阶段,不应记作首期未完成缺陷;身份模型不具备转换能力则属于首期缺陷。P2为已明确后置功能,不应将后置保险/真实充提记作本期未完成缺陷。所有列入本期的P1仍须交付,优先级不等于可任意删除。

QA-02保留QD-01~QD-12并追加匹配边界用例;V3.2新增ADMIN-10及F01~F09定向验收,数量以附表为准。全部产品验收仍未执行;引用存在不等于子行为全覆盖,问题闭环表只证明归档完整性审查发现已有裁定和对应场景。

第01~23章承接的每条需求在《需求总表》有稳定ID、角色、用户价值、正文位置、来源、优先级和验收引用;《CSV逐记录映射》保留12份CSV的全部逻辑记录(含空行和标题)及处理类型。引用到章节表示追溯路径,不意味着该记录全部子要求已自动测试。35项原差异另有V3章节映射。当前全部产品验收均“未执行”,文档校验仅证明编号/链接/映射和算例一致。

阶段:M0本PRD与参数基线形成;M1本地身份/权限/账本/持久事件;M2规则引擎与费用/恢复(含QA-02脚本预设工具,供稀有牌型及恢复测试使用);M3浏览器客户端和后台联调;M4目标浏览器真机、弱网、并发、故障与全验收,并在不影响首期交付的独立工作流接入Telegram身份、宿主与深链;后续支付/保险/链上核验专项。项目由AI驱动执行,以任务、证据和验收门禁分配工作,不设置固定人类负责人或虚构具体人员、工期和值班状态。

开发完成定义:对应需求正常/边界/失败场景通过,证据包含版本、环境、输入、实际结果;P0全部通过、无未处理金额或权限问题;设计展示与真实API统一;后置入口正确;操作说明与字段一致。历史原型205张画板及旧README“20测试通过”均不用于计算本版完成率。

执行边界:产品规格由本文D裁定给出;认证/归属/资金、规则引擎、客户端、测试、部署和发布证据分别形成可独立验证的AI任务。每项任务以输入、产物、校验命令、证据和依赖状态闭环,不以“指定某个人”代替责任追踪。ASR、服务器及未来Bot等实际凭据只在部署系统配置。缺资源可做明确标识的模拟,但不能写成真实接入已完成或有人值守。

22 版本裁定与现有资源处置

沿用V2的抽水、提前离座30%、单层分成、三环、短牌、权限及邀请裁定,不重新恢复历史冲突。归档完整性梳理形成以下D裁定:

编号 补全问题 本版结果 理由
N01 分享页未定义 3个一级导航;邀请放回目标入口 无公开社交需求,仍保留邀请能力
N02 俱乐部余额含义 展示本人同币种可用余额,不设重复资金账户 避免相同资金被多俱乐部累计
N03 快捷项3–5项遗漏 恢复14个候选及3–5项设置,无待跟按池比例 原截图明确功能;面对下注仍禁Raise Pot
N04 记录净收益与离座费 单手不重复扣离座费,会话总览扣一次;bb/100标牌局口径 对齐费用与统计可解释性
N05 运营定时开房 支持一次性未来7天计划开放,无循环排期 补运营组织流程且控制范围
N06 等BB与零筹码 明确轮转/全桌等待重开;零筹码保座60秒 避免等盲死锁和长期空占座
N07 个人资料/偏好 本地昵称2–20字、默认头像、账号偏好同步;未来TG资料仅显式选择后使用 覆盖截图编辑、多端恢复且避免外部资料静默覆盖
N08 俱乐部后台 创建/冻结/归档及归属历史 后台可管理而不让玩家自行退籍
N09 邀请短码/限流 6位无歧义字母数字、10次/分、手动提交 补齐输入与滥用边界
N10 工单/导出 明确状态、范围、31天导出上限与过期访问 使后台操作有闭环与权限约束
N11 稀有牌型难以稳定复现 隔离测试环境脚本预设发牌,默认关闭,无运营写入口 2026-09-19新增原文+归档合入授权;定位、编码和幂等为D裁定
N12 后台认证与二次验证 独立密码+TOTP,单次参数绑定授权,受控激活/恢复;见16.2节 F01完整性审查;本版D裁定
N13 补码边界与单笔待处理 一笔待处理;有筹码可小额补,零筹码须最低买入;见8.1节 F02完整性审查;本版D裁定
N14 迁移后的权限与生效时点 无在手立即迁移;在手手后迁移;当前会话临时访问;见6.4节 F03完整性审查;本版D裁定
N15 时间银行与断线时序 每手15秒共享离线预算;银行按账号持久化;见11.1节 F04完整性审查;本版D裁定
N16 俱乐部冻结归档闭环 冻结关桌撤邀请;归档先迁完成员;默认俱乐部保护;见6.5节 F05完整性审查;本版D裁定
N17 跨日计提与迟到冲正 按首次结算提交日;原日补结及累计目标差额冲正;见10.3.1节 F06完整性审查;本版D裁定
N18 举报结果反馈 我的举报私有列表、公开结论、站内未读与补充说明;见15.2节 F07完整性审查;本版D裁定
N19 预设文件与匹配顺序 先静态校验再匹配;账号未聚齐正常随机;room_id命中才阻止;见20.1节 F08完整性审查;本版D裁定
N20 优先级与验收追溯 需求总表优先级唯一;新增具体行为场景并双向映射;见21节 F09完整性审查;本版D裁定
N21 首期入口与TG转换能力 首期普通Web注册登录;核心业务只认统一玩家ID;TG验签、宿主、深链和绑定后置 降低首期外部依赖,同时避免未来产生第二套账号、钱包和战绩

裁定来源、取舍与验收映射详见调研与问题闭环(历史来源;现行规则已收录本包)。

设计处置:继续风暴视觉和四种牌面;首期增加普通Web注册、登录、退出、凭据错误/锁定和邀请上下文恢复页面;更新短牌排序、费率/离座披露、邀请审核、成员目录、三环、后台;隐藏Limit、保险购买、真实充提、机器人教练及伪核验成功;移除独立分享导航和玩家自行加俱乐部资金提案。TG宿主按钮、深链分享和绑定页只保留后续扩展位,不在首期伪装可用。历史画板保留归档,不能整体当作本期功能清单。

源码处置:texas-holdem中的昵称/密码注册、登录、会话恢复、邀请码和独立tmaAuth分支可作首期入口与未来提供者适配的交互参考,但不得照搬空密码、首注册者自动管理员、JSON文件持久化或把昵称当业务主键等行为。现有Node/WebSocket项目的牌型评估、房间状态、TG验签与统计模块只作复用参考;旧engine默认Math.random、旧resume和旧统计空分母/输赢口径须逐项改造验证。不得将参考项目、既有部署文档或旧“测试通过”称作当前已上线;运行账户、余额和凭据不迁移、不读取、不打包。

23 术语、帮助与来源

手牌/一手(Hand):从本次强制款和发牌到结算;房间(Room):多手对局的容器;入座会话(SeatSession):一次买入到退出;街(Street):翻前/翻牌/转牌/河牌下注阶段。三者不可在截止、费用或统计中混称“牌局结束”。

SB小盲、BB大盲、BTN/D庄位、UTG大盲左侧、CO庄右位;Ante前注不抵跟注,抓头为有效额外盲注;Bet首下注、Raise提高当前价格、Call补齐、Check免费过牌、Fold弃牌、All-in全下;Pot底池、Side Pot边池、Kicker踢脚、Muck不亮输牌、Split平分。前端帮助应配中英名称、牌型图及项目自身例子,不照抄原资料错误公式。Fish/Shark等带评价的术语仅在术语资料中保留,不自动贴玩家标签。

23.1 公开研究依据

以下为归档V3.2记录的历史研究依据;本次仅承接本地文档,未重新访问或验证外部网页的当前内容。外部规则支持相应概念,不替本项目设定经营收费。TDA为赛事规则,仅采用明确声明的部分。

V3.2新增公开依据(2026-09-19读取官方资料):

  • S01 OWASP多因素认证:第二因素遗失须有受控恢复机制;本项目TOTP、恢复码及人工恢复为D取舍。
  • S02 OWASP会话管理:服务端执行空闲及绝对过期;15分钟/8小时是项目默认。
  • S03 OWASP交易授权:授权绑定用户确认的操作数据,修改后失效,执行前校验,凭据限时且单次;不把“已登录”当成操作授权。
  • S04 Stripe幂等请求:同键重试与参数一致性可作设计参考;不引入Stripe支付或复制其保留期限。

归档曾记录的原CSV外链状态:Taiwan Rounders、德扑之家、GGPoker、宅神爷当时可访问;知乎、YouTube和设计站访问结果单独登记。第三方教学资料中存在顺序与加注表述冲突,只作参考,不覆盖本PRD。竞品私有综合公式、完整后台和所有视频细节不宣称已经核验;本产品已作自主定义。

23.2 产品FAQ

为什么钱包余额与桌内筹码不同? 买入后资金进入桌内托管,钱包可用余额减少,资产总额包含可用、冻结与托管。

为什么离座返还少于桌内显示? 提前盈利离座按已接受模板扣一次离座费,详情列本金、净盈利、费率与豁免;抽水已在手牌派奖内扣除,不再扣第二次。

为什么我进入另一个俱乐部的房间仍属于原俱乐部? 房间邀请只授予临时参局权,归属和代理需后台显式调整。

为什么对方全下后我不能再加注? 短全下未达到重开差额时,已行动玩家只能跟注或弃牌;界面显示当前合法动作。

为什么有些牌我晚一点看到? 房间可能开启公共牌延迟或可选底牌延迟,入桌前有说明,服务器在对应时点发送。

为什么看不到充值、保险和链上验证成功? 这些功能按原回复后置,当前不以演示状态冒充真实接入。

23.3 阅读与交付入口

正文为当前统一需求;需求总表用于拆任务;验收场景用于实施验收;来源目录用于追溯;页面处置表用于同步设计。本目录HTML和Word由同一Markdown生成,修改需求应先更新Markdown及机读附表再重新导出。归档PDF保持原版本,不代表本次综合稿。

24 本次资料整合与差异处理

24.1 来源、适用性与证据边界

来源编号 资料 本次用途与限制
A01 交付文档导航(历史来源;现行规则已收录本包) 明确当前业务基线为V3.2,历史目录仅追溯
A02 归档PRD V3.2(历史来源;现行规则已收录本包)及需求/配置/验收附表 本文01~23章的业务规则依据;不能由竞品截图覆盖
A03 V3.2问题闭环(历史来源;现行规则已收录本包)、页面补充(历史来源;现行规则已收录本包) F01~F09规格已解决;不把旧完整性审查重新当作未决清单
A04 运营后台范围与权限(历史来源;现行规则已收录本包)、数据与业务规则(历史来源;现行规则已收录本包) 补运营操作、数据来源和账务边界;源码情况只是2026-09-28快照
A05 接口与交互约定(历史来源;现行规则已收录本包)、任务验收与交付(历史来源;现行规则已收录本包) 提取操作状态、未知结果查询、导出和验收要求;URL、模块、技术性能数值仍属实施建议
A06 后台架构与模块边界(历史来源;现行规则已收录本包)、游戏改造方案(历史来源;现行规则已收录本包) 提取唯一业务执行方、历史数据与交付依赖;不据此宣布框架选型已批准或源码已完成
L01 综合稿V1.0、原CSV/截图与两段视频 保留本地证据及视频定位;参考产品画面不覆盖本项目规则

优先级:本次用户明确指令 → 归档V3.2明确业务裁定 → 与其一致的后台产品细化 → 原CSV明确回复 → 参考设计、截图和视频。架构建议不能自行改变业务范围;确需改变已裁定规则时,应记录变更原因、受影响需求/配置/算例及生效版本。本次没有新增经营费用方案或真实资金接入。

本地V1.0的S01~S12是CSV来源编号,归档正文23.1的S01~S04是公开研究编号,两个命名空间不同;引用本地CSV时使用“L01/Sxx”以免误认。V1为7分08秒的QMOA1458.MP4,V2为29.40秒的牌局2.MP4;归档提及的单段视频对应V2,不能覆盖本地V1证据。本次保留此前采样记录,没有重新逐帧观看视频或验证外部站点。

24.2 关键差异及处理结果

原综合稿缺口或冲突 本次统一口径 依据/落点
原CSV未关闭事项被全部保留为待决 承接V3.2已裁定部分,剩余资源/正式接入问题单列 A01/A03;26章
分享栏、俱乐部余额未定义 三栏导航;头部显示本人同币种可用余额 04、06章
邀请有效期二选一,归属仍是候选 ROOM/CLUB各支持24h免审和永久审核;单一归属及迁移流程 06章
房间时长、盲注配对及七组买入范围未锁定 长8席2/3h、短6席1h;七组模板候选,发布前补齐盲注;首手计时 07章
公共牌不允许延迟 主模式BOARD_EACH_STREET;HOLE_PREFLOP为互斥可选扩展,默认均不启用 14章
按截图小池免收/少人减半/平分免收 CSV_STANDARD_V2:翻后全手按比例封顶、向下取分、逐池分摊;不叠加截图减免 10.1节
建议首期关闭30%离座费 沿用EARLY_EXIT_PROFIT_V2;盈利才收、默认30%,运营关闭/到期/故障等豁免 11章
多笔补码、零筹码、等盲及换座缺边界 单笔待处理;零筹码补至最低;手后应用退差;等盲、换座不逃盲 08章
超时与断线阈值待决 A/B模式、20秒行动、持久银行、每手15秒离线宽限,明确定时算例 11章
抽水归因、代理层级/日结待决 单层直接代理、逐池贡献归因、GENERAL 0%、按首次结算日补结冲正 10.3节
综合圆环建议隐藏,VPIP准入无样本规则 VPIP/PFR/W$SD三环;同玩法最近100手、至少20手,准入默认关闭 13、14章
语音仍为待验证范围,举报缺闭环 语音转文字为本期P1,供应商为接入依赖;我的举报、公开结论、补充说明 15章
超管补偿只有确认框/原因 独立后台认证、TOTP、120秒参数绑定授权、恢复/撤权流程 12、16章
牌谱保存期、性能指标待定或另提更严目标 承接测试保留期和有测量条件的容量目标;原建议恢复3秒替换为基线5秒 20章
无测试预设发牌要求 恢复P1隔离测试工具,禁止运营入口及正式环境启用 20.1节

24.3 本地视频与截图补充到页面验收

本节细化可见交互,不引入竞品资金规则;与规则不同的画面只保留为证据。

页面/用户任务 保留的证据 产品要求与验收观察点
手牌回顾 V1 03:20~03:30抽屉、结果/详情、前后手 提供结果和逐街详情、上一手/下一手;首末手禁用对应方向;字段遵循13章可见权限
实时战绩 V1 03:40买入/手数/盈亏/费用及旁观列表 展示本桌已确认事实和数据时点,未结算不得冒充最终净收益;保险标未开通;旁观列表不公开余额/IP
钱包与账单 V1 00:20、01:00及空态 可用/冻结/托管分列;筛选无记录与加载失败分开;只展示已实现账务类型
个人设置 V1 00:30语言、版本、支付密码 首期可展示简体中文和实际版本信息;支付密码随真实支付专项,不提供无效保存入口
主题与牌桌 V1 02:30、04:20~05:30及短牌段 主题预览/取消/保存;BB显示不改变实际金额;长短牌布局各验收,不能只测8人长牌
后续支付 V1 00:40~00:55充值/提币 仅作为后续设计输入;10 USDT下限、快捷金额、支付渠道均不是当前配置
公平性 V1 04:00~04:10及4张介绍截图 保留介绍、记录与映射阅读入口;明确演示,无真实证明不得显示成功

本地原稿保险赔率表和候选充值字段保留在历史稿第14~15章,作为后续专项输入,未被升级为本期购买规则。原始图、采样帧及素材索引保持可追溯。

25 运营后台产品闭环补充

本章将A04~A06的交互与数据边界整理为可验收的产品补充,编号OPS-01~OPS-06;优先级沿用其所保护的资金、权限和记录需求。技术实现可采用若依运营端与游戏业务服务协作;数据库工程基线采用PostgreSQL 16、Flyway和HikariCP,生产使用托管主备或同等高可用、每日全量备份+WAL连续归档,初期不分库分表。其余框架和模块边界由工程设计在不降低该基线的前提下确定。

25.1 OPS-01 操作结果与实际生效(P0)

用户故事:作为运营,我需要区分“已提交”和“已生效”,以免因超时重复禁用、迁移或补偿。后台保存操作号、对象、动作、原因、提交时间、当前状态、生效时间和结果;页面显示“已提交/处理中/已完成/失败/结果确认中”。只有业务执行方确认成功才显示完成。

网络超时或提交结果未知时保留原操作号,提供“查询结果”;重试同号同参数只能返回原结果,同号改金额/对象拒绝。查询不是再次执行。手后生效动作展示当前手及等待原因;用户禁用的“新准入已禁止”与“桌内清算中”分开。建议按1/2/5/10秒退避查询,60秒仍未确认时进入待确认列表;这些轮询数值是实施建议,不是资金失败判据。禁止因超时自动生成新单或退款。

25.2 OPS-02 业务执行与权限边界(P0)

用户故事:作为超管,我需要授权真实约束所有入口。后台人员账号、统一玩家账号、认证身份和代理实体分别管理;本地或TG玩家身份均不自动获得后台权,代理绑定后台账号也不获得超管能力,总代理仅表示管理关系,不自动产生多层佣金。

权限须覆盖菜单/按钮、接口动作、资源范围、执行时业务条件,列表、详情、汇总、回放、导出一致。改变玩家权益/资金/牌局状态的请求由唯一权威业务执行方确认,后台不能直接改玩家余额或用前端状态代替业务结果。迁移需双侧范围;延迟执行前再次检查权限与目标。测试分成标记不生成真实付款,资金敏感动作复用16.2节单次授权。

25.3 OPS-03 旧数据与报表可信度(P0)

用户故事:作为客服和运营,我需要知道记录是否完整,避免用旧摘要解释不存在的牌谱。历史摘要标“历史摘要/不可回放”,缺失注册时间、费用或充值来源显示“未知/无该记录”,不以首条登录或当前修改时间冒充注册时间,不补造成功账单。

新结构须按20章保留期存储并分页,超过3000手不能沿用旧内存截断;这不是无限保存承诺。查询展示数据截止时间和完整性状态;总览下钻继承日期、币种、用户/代理/俱乐部与权限范围,资产分组。无通道的充值页显示未接入及真实空状态,补偿单独分类;佣金应计、测试已标记、未标记和调整分列。

25.4 OPS-04 资金异常定位与纠错(P0)

用户故事:作为超管,我需要从未知操作追查原单并纠错,同时让玩家在途资产继续有据可查。提供操作/流水号、玩家、币种、时间、业务类型与状态筛选;详情联动原单、分录、手牌/会话、规则快照和冲正链。

补偿只进入钱包可用,不能直接增当前手筹码;扣减仅动可用且不为负;冲正追加并引用有效原单。失败与未知分开,未知结果先核查,重复冲正拒绝。收入备注仅追加审计,不改历史金额。账本差额、未知操作积压、日结待重算作为运营待办;阈值依容量评估配置,不能把发现告警等同于自动扣款或自动判作弊。

25.5 OPS-05 代理与客服工作台(P1)

用户故事:作为代理,我需要看清名下贡献和应计;作为客服,我需要处理授权工单而不泄露私牌。代理页显示本人协议、等级/比例与生效期、授权用户统计、归因基数、日账及调整,区分所选期间和历史累计;不得显示名下玩家完整钱包流水/IP,除非另有明确专项授权。

客服仅查询分配或授权范围内工单及公开桌面,公开结论与内部备注分开;私牌查询仅结束手、有效工单、用途、限定玩家及专项授权,申请人与审批人不同,由具备专项审批权的超管审批,批准后30分钟有效,每次访问另需120秒参数绑定TOTP授权。页面记录申请/审批/逐次访问轨迹,不把勾选“管理员视角”当作授权。代理只读本人协议、汇总和佣金;权限种子未落库时保持拒绝,不能开放全局数据。

25.6 OPS-06 可交付证据与页面状态(P1)

用户故事:作为验收人,我需要区分原型、模拟联调、真实接口与产品验收通过。每个交付功能记录需求ID、页面、接口能力、实施版本、环境、数据来源、验收ID、实际结果和证据;禁止用页面存在或框架CRUD生成完成作为业务完成依据。

页面统一具有加载、真实空态、权限不足、服务不可用、处理失败、结果待确认状态。开发阶段模拟数据必须标识且隔离;验收需验证真实业务服务的返回及错误处理。后台10万玩家/100万手/1000万分录、30名并发运营及列表P95≤1秒/总览≤2秒仅是A05提出的容量建议,须在测试方案冻结前确认,不能覆盖20章已定义的游戏容量基线。

26 验收索引、待决事项与交付检查

26.1 验收材料的使用方式

完整验收场景承接归档196个场景,并追加本次OPS-AC01~OPS-AC12;验收用例在原AC01~AC30基础上新增AC31~AC39客户端异步状态案例,并附加12个后台补充案例。两表有重叠,不能相加当作独立覆盖数量。新增OPS编号在需求总表映射,不复用归档已有ID。

文档验证只检查数量、编号、链接、附表映射和导出内容一致。所有软件验收均未执行;102项基线、196个场景和61项配置是归档规模,不代表本次新增工作量或实现完成率。

26.2 原待决项处理与仍需补齐的交付条件

“已承接”指已有归档默认,不要求重新发明规则;“部分关闭”只保留外部资源或正式接入条件。项目采用AI驱动执行,表中记录执行方式和门禁节点,不设置或虚构固定人类负责人。以下表与待决事项CSV同步。

ID 事项 状态 处理结果及剩余条件 依据 执行方式 / 门禁节点
D01 名称、Logo、分享栏 已承接 风暴扑克/Storm Poker;三栏导航;上线品牌资产授权与正式素材版本另核 04、14、22章 产品/视觉 / 设计交付前
D02 邀请有效期与审核 已承接 ROOM/CLUB四种组合及默认值、撤销和审核;代理推广不自动改归属 06章 产品+运营 / 按基线实施
D03 俱乐部归属与迁移 已承接 单一归属;玩家不可自退;双侧权限、手后迁移、临时会话权 06章 后端+运营 / 按基线实施
D04 Ante与抓头 已承接 长牌OFF/EACH/BB_PAYS及公共池;短牌两者关闭;活盲不足规则 09、10章 规则开发 / 按基线实施
D05 超时、离座费 已承接 A/B超时、持久银行及宽限;提前盈利30%模板和豁免 11章 规则开发 / 按基线实施
D06 服务费与分池 已承接 CSV_STANDARD_V2;默认cap1.5BB;无截图减免;逐池分配 07、10章 运营+规则开发 / 按基线实施
D07 买入档位与房间参数 已裁定 V1仅发布TEST、1/2、100–300、长牌8席2h、Ante/抓头关闭的完整种子;其余六组保持DRAFT,不推导参数 07章 运营+后端 / 按种子实施
D08 快捷按钮 已承接 无待跟选3~5项池比例;有待跟用明确加注目标,不使用Raise Pot 09章 客户端 / 按基线实施
D09 准入与统计 已承接 同玩法最近100手至少20手;三环独立指标;无分母显示— 13、14章 数据+客户端 / 按基线实施
D10 代理层级与权限 已裁定 最小授权:运营仅俱乐部范围;客服仅分配/授权工单及公开桌面;代理只读本人协议、汇总、佣金;IP/私牌/全局审计/导出独立授权;资金调整仅超管 10、16、25章 运营+后端 / 按权限种子实施
D11 资金环境与可提资格 后续专项 本期仅TEST资产;真实充值提现列为P2独立专项,不建虚假订单、地址或到账状态 12章 资金负责人 / P2立项前
D12 语音与旁观发言 部分关闭 本期语音、旁观只读已定;ASR供应商/凭据与真机兼容需实测 15、20章 后端+部署+测试 / 语音联调前
D13 公平性与底牌公开 后续专项 首期随机/隐私/明确演示已定;真实证明方案及隐私冲突留后续专项 17章 技术+产品 / 真实核验立项前
D14 保险规则 后续专项 首期关闭;触发、赔率、续保、赔付独立定义,保留历史素材 02、24章 规则负责人 / 保险立项前
D15 发牌与摊牌 已承接 庄左发牌、每街烧牌、逐玩家短全押重开、Muck及尾分 09章 规则开发 / 按基线实施
D16 记录保存与性能 已裁定 V1基线:牌谱180天,账本/审计/举报工单365天,聊天30天,证据至少至结案,ASR成功即删、失败最长24h;不作法域合规声明 20、25章 技术+运营+测试 / 按基线实施
D17 首期Web与后续TG接入资源 部分关闭 首期需要域名HTTPS、服务器/存储、认证密钥和正式协议;Bot及凭据只在后续TG阶段提供;不写入明文凭据 05、20、22章 AI生成配置清单并执行门禁 / 对应联调及发布前
D18 AI执行与排期 已裁定 不设固定人类负责人;按任务依赖、自动校验、验收证据和外部资源状态推进;未配置真实值班渠道不得宣称有人值守 21章 AI任务清单持续更新 / 各里程碑前
D19 工程实施与版本 已裁定 PostgreSQL 16、Flyway、HikariCP;生产采用托管主备或同等高可用,每日全量备份+WAL连续归档,初期不分库分表;不承诺已完成源码改造 25章、A06 AI按工程门禁实施并留证 / 按工程基线实施

26.3 评审与实施边界

本次完成规则补充与差异消解;没有替团队承诺研发排期、采购ASR、选定框架版本、迁移运行余额或批准发布。第21章M0~M4是产品全链路里程碑;后台开发文档的M0~M4是其子项目阶段,不直接按相同编号视为同一交付物。

启动前在开发实施任务总清单中登记产品、规则、前后端、测试、部署任务的依赖、自动校验、产物路径和实际完成日期,不设置固定人类负责人。P0资金/权限/私牌问题阻断交付;本期P1仍须在完整产品交付时验收,不因安排在后阶段而取消。真实支付、保险、链上核验和真实佣金付款继续独立立项。全部旧规则变更须同步需求表、配置、算例、接口提示及用户入桌披露,不只改后台默认值。

26.4 核心验收用例

以下场景为未执行的验收规格;前30项沿用本地ID便于评审追溯,AC31~AC39为客户端异步提交状态补充。

编号 条件与操作 预期结果 执行状态
AC01 同一登录名注册一次后重复登录并修改展示昵称 始终命中同一内部账号,不新增余额账户,game_id不变 未执行
AC02 错误密码连续尝试、伪造user_id恢复或会话已过期 返回安全错误并按规则锁定;不能进入受保护业务或恢复他人状态 未执行
AC03 后台关闭玩家开房,玩家直接调用创建能力 前端隐藏入口且服务端拒绝 未执行
AC04 输入无效/过期/已关闭房间邀请码 提示具体原因,不扣余额、不改归属 未执行
AC05 两人同时争同一座位并买入 一人成功,另一人不丢失余额 未执行
AC06 相同买入请求重复提交 只扣一次钱包、只增一次桌内筹码 未执行
AC07 当前手申请补码 当前手筹码不增加;先冻结,一笔待处理,手后按上限应用并退差;输至0且不足最低买入则整笔解冻 未执行
AC08 两人桌翻前及翻后轮次 庄家兼SB翻前先、翻后后;非庄BB先收底牌;不启用抓头,每街不重复扣盲 未执行
AC09 A 下注 6,B 加到 20 后手最小加到 34 未执行
AC10 A 下注 20、B 跟 20、C 全押到 30,A 跟 10 B 只可跟 10 或弃牌,不能加到 100 未执行
AC11 AC10 中另有未行动深筹码玩家 可作合法完整加注;重新开放权按新完整增量计算 未执行
AC12 剩余 5,需跟 10 可全押投入 5,保留主池资格,不产生负筹码 未执行
AC13 A/B/C 投入 50/100/200 主池 150、边池 100、C 返还 100 未执行
AC14 弃牌者贡献过底池 金额留池,但不能获得主池或边池 未执行
AC15 两人最佳五张一致且有最小单位余数 每池独立,庄左顺时针首个合格赢家获尾分;BTN8,赢家1/3,净池0.05分0.03/0.02 未执行
AC16 同花与葫芦分别在长牌和短牌比较 长牌葫芦胜,短牌同花胜 未执行
AC17 短牌出现 A6789 识别为有效顺子;牌组中不出现 2–5 未执行
AC18 翻前全部对手弃牌 无服务费,退回未匹配额,剩余有效底池正确派奖 未执行
AC19 翻后底池低于/等于 5BB,或 3/4 人发牌 已发翻牌、BB1、5%、cap1.50:池4.99费0.24;池5费0.25;3/4人同额同费,不减半;两人平分池40且cap3时费2各得19 未执行
AC20 结算写入后广播失败再重试 筹码和流水只变动一次 未执行
AC21 重连与行动超时同时发生 基础20/银行30/宽限15,t5离线且未回,t35自动过牌或弃牌且银行仍30;恰好截止才收到的动作拒绝,不执行两次 未执行
AC22 已全押玩家断线 保留底池资格并完成结算 未执行
AC23 旁观者发消息或请求未公开手牌 按权限拒绝,不泄露底牌 未执行
AC24 非超管提交人工充值 拒绝且留存必要审计;超管成功有原因和流水 未执行
AC25 查询自己以外的账单或其他代理数据 未获授权则拒绝,不能靠更换 ID 绕过 未执行
AC26 VPIP:10 手中 3 手主动投入、1 手仅 BB 过牌 VPIP=30%,强制注不计主动投入 未执行
AC27 跨 BB 级别统计 bb/100 逐手用各自 BB 换算,不以最后一桌 BB 统一除 未执行
AC28 打开公平性演示页 明示演示,不显示真实核验成功承诺 未执行
AC29 真实充值/保险功能未上线 无可执行收费入口,不生成模拟成功账单 未执行
AC30 房间到时且当前手尚未结束 停止新买入/补码/下一手,完成本手;未生效补码全退,免离座费返还,退出仅记一次 未执行
AC31 买入请求处于SUBMITTING时连续点击或重复触发提交 提交入口禁用;沿用同一request_id,服务端只产生一次买入业务 未执行
AC32 买入请求已发送但响应超时或连接中断 显示结果未知;不显示成功或失败、不自动退款;仅允许按原request_id查询 未执行
AC33 买入处于UNKNOWN,查询原请求后返回成功 仅一笔可用余额转桌内托管、仅一条seat_session;确认成功后才进入牌桌 未执行
AC34 买入处于UNKNOWN,查询原请求后返回失败 无资金转入桌内托管;预约或临时冻结按结果释放;保留房间上下文 未执行
AC35 开房处于SUBMITTING时重复点击,或重放同一request_id 返回同一room_id,只创建一个房间且只冻结一份规则版本 未执行
AC36 开房请求已发送但响应超时或连接中断 显示结果未知;不显示房间号、不开放邀请;保留草稿且仅查询原请求 未执行
AC37 开房请求收到明确失败终态 显示明确原因;无room_id、无规则冻结、无费用;修正后以新request_id提交 未执行
AC38 开房处于UNKNOWN,查询原请求后返回成功 返回同一room_id与规则版本;确认成功后才开放邀请入口 未执行
AC39 客户端在SUBMITTING或UNKNOWN期间刷新、断线或重新进入 根据原request_id恢复并查询状态,不创建新的买入或房间业务 未执行
OPS-AC01 补偿已提交但响应超时;按原操作号查询并重试 仅一笔余额变动;未知不显示失败退款,最终返回同一结果 未执行
OPS-AC02 迁移有在手玩家;提交迁移,等待结算 先显示待生效;手后复核并生效才显示完成;撤权则取消保留旧归属 未执行
OPS-AC03 代理只有自身范围;篡改ID请求列表/详情/统计/导出/回放 全部按服务端范围拒绝越权,菜单可见不扩大权限 未执行
OPS-AC04 旧会话有敏感授权,管理员范围已撤销;用原授权执行原敏感动作 拒绝执行;不能凭有效期尚余绕过撤权 未执行
OPS-AC05 旧记录只有手牌摘要、无完整动作与注册时间;打开历史详情、回放及用户资料 标历史摘要/不可回放、未知注册时间;不生成虚构动作或费用 未执行
OPS-AC06 真实充值未接入,新手牌超过3000手且在保留期内;查询充值页和历史手牌 充值显示未接入/空集,补偿独立展示;新记录分页可查不被截断 未执行
OPS-AC07 账户可用50、在桌100;超管扣减60或修改原流水 拒绝扣减且不动在桌资金;原流水不可改,只能授权追加纠错 未执行
OPS-AC08 同一原单已完成冲正;重新提交冲正或重放原请求 原结果可查且不重复记账;新号重复冲正同样拒绝 未执行
OPS-AC09 代理拥有名下汇总权限;查看自身账单及尝试读取玩家钱包/IP 展示协议版本、基数、应计/测试标记/差额;额外敏感字段拒绝返回 未执行
OPS-AC10 客服申请已结束手专项私牌审计;尝试自审、无授权访问,再按有效独立授权查询 自审及未授权拒绝;授权后仅限定玩家/手牌可查,访问留审计且公开结论无私牌 未执行
OPS-AC11 页面有模拟数据,真实服务不可用;进入联调或交付验收 模拟明确标识,服务失败与空态区分,不能记为真实API验收通过 未执行
OPS-AC12 后台验收缺版本、环境或实际结果;提交交付记录 保持未验收/证据待补;页面存在不能使状态自动通过 未执行

27 业务流程图

本章面向产品、设计、研发、测试与运营,帮助读者确认操作顺序、异常处理和端间职责。9张流程图已在2026年10月21日按综合稿V1.2更新首期身份入口;本次没有新增收费、资金或后台权限,稳定需求与验收ID不变,软件验收仍为“未执行”。图中未展开的金额、计时与授权条件,以标注的正文条款为准。

可打开流程图独立阅读页,或点击各图下方的SVG矢量文件放大阅读。PNG用于网页和Word嵌入,SVG用于原尺寸查看与后续编辑,两者均为本地静态资源,无需联网渲染。图中橙色表示判断或待确认,红色表示拒绝或冻结核查,绿色表示已确认结果;状态也用文字表达,不只依靠颜色。

27.1 玩家完整业务流程

图01 玩家完整业务流程,含身份资格拒绝与提交结果未知分支

查看图01矢量版。依据第04、05、06、08、11、12、19章。首期普通Web注册/登录和访问资格通过后,玩家先接受规则再买入;成功后依名单及等盲规则参局,退出时核对返还、账单与战绩。身份或资格不满足不扣款。任一写操作结果未知时停留在原业务并查询,明确失败按图04/05处理;图01不表示所有环节均可无条件进入下一步。未来TG入口替换认证提供者,但不改变图中统一账号之后的业务流程。

27.2 邀请进入与审核

图02 邀请进入与审核,区分24小时免审与永久审核以及房间和俱乐部目标

查看图02矢量版。依据第06、6.2、6.3、6.4、16章。ROOM/CLUB与24h免审/永久审核独立组合;默认房间24h免审、俱乐部永久审核,不是固定类型约束。审核在运营后台由有权限者执行,批准瞬间仍须检查邀请、目标与账号状态;拒绝后必须使用新邀请重新申请,不提供解除拒绝动作。邀请撤销、房间关闭或俱乐部冻结不能因已申请绕过。

普通用户收到链接不等于获得签发权限,也不传播邀请者权限;无签发权限不展示邀请按钮。分享仅由用户主动触发。ROOM只授予目标房间访问,不改俱乐部或代理归属;CLUB准入的归属处理接图03。

27.3 俱乐部归属与迁移

图03 俱乐部归属迁移,区分立即生效和手后复核生效以及旧桌临时权限

查看图03矢量版。依据第06、6.4、6.5、25.1、25.2章。自然访问进入默认俱乐部;默认归属接受有效CLUB邀请准入后按生效时点处理,已有正式归属须由授权运营显式迁移,不能仅凭邀请自动覆盖。迁移需源、目标双侧范围和ACTIVE目标,每人最多一笔待生效迁移。

无在手在事务中立即生效;有在手等本手结算或作废后、下一手名单形成前复核生效。复核失效取消并保留旧归属。原桌已买入会话仅保留该房间会话临时权,不得绕过禁用、冻结或关闭;退出后失效。旧成员目录权限即时取消,本人历史账单和牌谱不丢失。

27.4 授权开房与规则冻结

图04 授权开房,区分明确成功明确失败和结果未知

查看图04矢量版。依据第4.3、07、7.1章。运营后台发布模板与配置开房授权;客户端只选已发布模板、编辑允许字段。确认成功前不显示房间号或邀请入口;同request_id返回同一房间,不重复开房。结果未知持续查询原号,确认失败后才允许修正并发起新请求。

图04展示即时开房。单次计划开放仍按7.1节:SCHEDULED不能买入,到时复核权限和模板后转WAITING并开始默认24h邀请有效期;永久审核邀请可以提前申请,但开放前不得入座。循环排班不在本期。

27.5 入桌与买入

图05 预约座位和买入,展示原子校验及未知结果查询

查看图05矢量版。依据第4.3、08、8.1、12章。选空座后预约15秒;身份、资格、余额、币种、房间、座位和已接受规则版本与扣款同事务校验。成功才把可用转入托管;明确失败不残留冻结。请求已提交但结果未知时,预约倒计时结束也不能由客户端推断失败或退款,应按原号取得权威结果。

满桌按观战开关提供旁观或满员说明,不自动排队扣款;进行中买入等待下一手及自然BB,不接收当前手底牌。补码独立执行8.1节:一笔待处理、先冻结、手间应用退差;不是再次买入或向当前手直接加筹码。

27.6 牌局状态与合法行动

图06 牌局状态,含逐街行动超时自动动作一人获池全下亮牌和手后调度

查看图06矢量版。依据第08、09、10、11、19章。名单锁定和强制款提交后才发底牌;每街完成全部合法响应才进下一街。仅一人未弃牌立即结束,不发未来牌;多人且无法互相继续下注则按规则补齐公共牌并自动亮牌。下注目标、完整加注差额和逐玩家重开资格仍严格执行9.3节,不能从简图推断任意加注。

行动超时能过则过,否则弃牌,再执行房间已冻结的A/B缺席策略。计时按BASE/BANK/GRACE/AUTO及11.1节执行;服务故障暂停计时,不作为玩家超时。手牌STARTED→SETTLING→SETTLED原子结算,广播失败只补通知。手后先处理离座、退款、补码和位置,再准备下手;房间到期或DRAINING不再开新手。

27.7 资金流转与离座清算

图07 买入补码手牌结算与离座返还,区分盈利收费和豁免

查看图07矢量版。依据第08、8.1、10、11、12章。B为初始买入加实际生效补码,U为未生效补码冻结,E为已扣每手抽水的手后托管余额。先取消未生效补码,再确定退出原因及费用;总返还为E−F+U。图中“取消U”对应将U解冻返可用,最终总额包含这笔解冻,不能把U退两次。

仅自然到期前主动离桌、站起返款或玩家超时退出且有盈利、已完成有效手,才收F=floor_cent(max(0,E−B)×q)。默认q=30%,按已接受的模板版本计算,不从图中生成新费率。到期优先、运营关闭/强制禁用移除、服务故障及未完成有效手免收;亏损不收。每手抽水不再二扣,离座费不参与代理分成,seat_session_id+EXIT只执行一次。

27.8 故障与结算异常恢复

图08 异常恢复,区分结算已提交可恢复可信快照作废以及无法确认冻结核查

查看图08矢量版。依据第4.3、19、20.2、25.4章。客户端请求未知只查询原业务;房间故障才进入全桌恢复。已提交返回原settlement_id,不再派奖;未提交且日志可信则继续原手;不能恢复但有可信手前快照则VOID并去重冲回实付贡献,撤销本手费用与计提,保留前手和独立补码。

不能判定是否提交,或没有可信恢复依据,进入RECOVERY_REQUIRED并冻结核查,不自动退款、不超时生成新单。人工纠错须新授权分录引用原单,不改旧余额或删除历史。自然到期与故障相遇停止下一手,恢复后免离座费清算。图中“仅请求未知”分支与故障恢复分支独立,不代表等待时间届满就进入作废退款。

27.9 玩家端与运营后台职责泳道

图09 玩家端业务服务运营后台三方泳道,配置审核与敏感操作在后台,权威执行在业务服务

查看图09矢量版。依据第06、07、12、16、19、25章。超管在后台创办俱乐部,发布模板和权限按角色能力执行;普通玩家不自建/自退俱乐部,不在玩家界面操作邀请审核后台。后台也不能直接覆盖余额或以按钮成功代替业务生效。

泳道箭头表示不同场景的请求与反馈,不表示所有玩家均需逐步经过每一项后台操作。玩家只看本人合法可见数据;服务端负责准入、合法行动、资金、原子幂等与实际生效;后台人员在资源范围和敏感授权内配置、审核、追查与纠错。后台账号、统一玩家账号、LOCAL/TELEGRAM认证身份与代理实体分别管理,不因注册、邀请、绑定或代理关系自动获得超管权限。

附录 A 视频证据定位

本附录沿用本地V1.0采样记录,其旧需求编号不能用于替代当前需求总表。当前功能对应见24.3节;本次未重新审片。

时间为从视频开头计的采样点,描述不代表两采样点间所有操作均已确认。

视频 时间 可见内容 本地V1.0需求编号(仅追溯)
V1 00:00 Telegram Bot 资料页和打开应用入口 AUTH-01
V1 00:10 进入俱乐部大厅 CLUB-02
V1 00:20、00:30 资产页;语言、版本、支付密码 AUTH-03、WALLET
V1 00:40、00:43 链上充值二维码区域;KKPay 金额与快捷金额 PAY-01
V1 00:50、00:55 链上提币表单;三种提现方式 PAY-02
V1 01:00、01:10 账单分类空态、战绩筛选 WALLET-02、HISTORY
V1 01:30、01:40 大厅列表和不同房间占用状态 CLUB-02
V1 02:00、02:10 规则教学、房间参数、抓头解释 ROOM-02、规则基线
V1 02:20 Outs 10/11/12 为 2.5/2.2/2 INS-01
V1 02:30 牌背选项与主题预览 PREF-01
V1 03:20、03:30 手牌结果、手牌详情、前后手切换 HISTORY-01
V1 03:40 实时买入、手数、盈亏、费用、旁观列表 HISTORY-02
V1 03:50 旁观状态禁止发言 CHAT-01
V1 04:00、04:10 公平性列表与牌桌映射 FAIR-01
V1 04:20–05:30 的采样点 BB 显示、抓头、跟注、加注、弃牌和翻牌 TABLE-01/02、ACT
V1 06:00–07:00 的采样点 短牌 6 座、翻牌转牌、过牌与弃牌 短牌桌面、动作表现
V2 00:03、00:06、00:09、00:12 河牌下注、弃牌、获胜动画和结算后画面 SETTLE-01;不能单凭动画推导费率
V2 00:15、00:18、00:21、00:24、00:27 新手强制注、抓头、行动倒计时与跟注 TABLE-01、ACT-03

关键帧保存在同目录“素材索引”,文件名含视频编号及秒数。原始截图与两份旧文档保持不变。

28 2026-10-27 德扑重做修正补充(截至 2026-11-02)

本章依据《NewGame修正意见-1027》及《修正计划-1027》补充,保留原需求和旧版追溯编号;如有冲突,以已确认的新口径为准,未确认事项不得视为最终规则。以下“已实现”仅指当前玩家前端相应代码,不等同服务端闭环、视觉验收或上线批准。历史需求总表、任务映射和原型未同步改写;不得用其原有计数宣称本补充已覆盖或验收。

28.1 房间与牌桌

编号 修正要求 当前状态及边界
#2 房间列表长牌/短牌标签背景提高辨识度。 前端已调整。
#5–7 空位显示“入座”;座位对称、上方上移并为底部按钮留白;调整头像、昵称、筹码比例及公牌下方信息密度。 前端已调整;以参考图进行视觉验收。
#8 放大断线重连提示。 前端已调整。
#10 允许旁观的房间即使满员也可进入;禁止旁观且满员时提示房间已满。 前端已有入口及提示;服务端授权与真实链路仍需独立验证。
#11 不允许换座;退出后更换房间。暂定:盈利退出且未满30手收取盈利部分30%,输局可随时退出。 前端移除换座入口;后端接口仍保留,未硬禁换座;30手阈值清算与预估尚未实现,手数和盈利口径需最终确认。
#17 个人设置只保留语言选择和修改密码,其余牌局设置回到房间内。 部分完成:牌桌主题、快捷下注和音效已移至牌桌设置;语言及密码仍待确认/接入,当前个人页还保留公开资料与退出。
#22 操作区按照参考稿调整弃牌、下注等布局;快捷下注支持配置3–5个位置。 前端已调整;默认数量与交互仍待确认。

28.2 数据、回顾与聊天

编号 修正要求 当前状态及边界
#16 我的数据展示手牌数、入池率、翻前加注率、摊牌率、All-in胜率。 前四项前端可展示现有数据;All-in胜率依赖服务端统计和契约,未实现;统计分母和摊牌率口径须确认。
#18 牌桌内牌局回顾改左侧半页侧栏,包含手牌结果与详情。 前端侧栏已接入,视觉与功能按参考图验收。
#19 实时战绩改左侧半页侧栏,展示玩家买入、手数、盈亏、服务费、保险和旁观名单。 尚未实现;需要房间级聚合接口、授权裁剪及前端侧栏。
#21 牌桌聊天改侧边半页。 前端右侧聊天抽屉已接入;沿用现有聊天权限与服务端行为。

28.3 新增功能与待确认规则

编号 需求 当前状态及待确认
新3 点击其他玩家头像查看资料,提供双向屏蔽、发消息、送钱、付费表情及举报。 已有资料弹窗框架;仅展示快照昵称及座位。双向屏蔽、私信、送钱、付费表情均禁用。现有举报按手牌/消息提交,不自动关联玩家。现有聊天屏蔽为单向接收过滤,不等于双向屏蔽;身份标识、授权、举报契约、金额和币种待确认。
新2 弃牌后付费查看剩余玩家底牌。 未实现;价格、资格、可见范围和时机待确认。未经服务端授权不得提前下发底牌;需设计扣费幂等及审计。
新1 每局开始前付费切牌。 未实现,仅文档预留;参与者、时机、费用和次数待确认,不改变现有发牌流程。
#1、#3–4、#12–13 创建游戏选项、俱乐部余额、加注资金流与保险规则。 待最终确认。俱乐部=独立盘仅为暂定口径;不据此宣称资金模型已验收。
#9、#14–15 40–41暂不变;不存在的验证未通过场景不实现;验牌展示暂不改。 本轮明确不改。

28.4 本补充的验收与发布边界

已执行的前端验证见修正计划:截至2026-11-02,单元测试242项通过、构建通过,玩家资料新增端到端测试1项通过;该次未运行完整端到端套件。资料框尚未完成参考截图视觉验收。未执行的服务端资金规则、统计、实时战绩、双向屏蔽与付费功能不得标记完成。原有发布门禁和 NO_GO 状态不因本文档更新或静态包生成而改变。

28.5 玩家资料与基础表情规则补充(2026-11-02 确认)

  • 点击其他玩家头像打开小弹窗,显示昵称、玩家 ID、备注及玩家自己填写的一句话留言;“我 → 个人信息”增加留言的填写和修改入口。备注暂按仅设置者可见理解,待确认。
  • 信息下方依次提供屏蔽、发消息、赠送、举报;再下方展示表情,不同表情价格可由低到高展示。现有资料弹窗只是框架,相关字段、操作与收费尚未完成。
  • 所有基础表情共用每日 5 次免费发送额度;超出后收费。表情价格、币种、赠送规则、屏蔽和私信等服务端契约仍待确认。
  • 免费额度按玩家手机当前时区的本地 00:00 重置,服务端记录和控制重置。距离上一次重置不足 24 小时,即使因修改时区或跨时区旅行再次到达本地 00:00,也不重置;须等待间隔满 24 小时后的下一个本地 00:00。此规则同样适用于正常旅行,可能跳过一次本地午夜。
  • 客户端提供的时区不能单独证明玩家真实所在地;服务端须校验和审计额度、时区变更及收费操作,不能信任客户端自行扣减额度或直接决定扣款结果。展示“今日免费剩余 X/5 次”;具体的时区上报、首次额度、并发幂等、价格和付费确认交互仍待设计和验收。
风暴扑克 · 统一实施基线 IB-1.1文档已发布 · 软件开发与验收按门禁推进

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