# 风暴扑克实施基线

版本：IB-1.1 · 2026-10-21  
状态：统一文档基线已发布；业务软件尚未完成开发、运行验证和上线验收。

## 如何使用这份基线

本包是产品、设计、前端、服务端、数据库、运营后台及测试的统一开发依据。旧文档站点可以回收；本包的阅读、原型、图片、流程图、CSV、数据库脚本和编辑源稿不依赖旧域名。新变更必须更新本包版本，不能以旧链接、旧截图或旧代码默默覆盖本基线。

先阅读本页与[冲突裁定](../docs/decisions.html)，再按职责阅读[前端需求](../docs/frontend.html)、[服务端需求](../docs/server.html)、[UI 设计](../docs/ui.html)、[架构](../docs/architecture.html)及[完整数据字典](../docs/database-dictionary.html)。[需求追踪](../docs/traceability.html)保留产品、后台、设计和测试的稳定编号。

## 权威顺序

1. 后续由用户明确确认且记录入变更日志的决定。
2. IB-1.1 的本页、冲突裁定和范围表。
3. 本包产品需求与配置：产品 V1.2 的完整摘录，不删减本期 P1。
4. 本包后台规格、前后端责任、UI 字段与状态契约。
5. 本包架构、数据字典、迁移及工程验收约束。
6. 原型、上游截图与关键帧仅用于视觉和行为参考。演示数据不是规则或种子，旧源码不是最终规则依据。

如产品目标与技术实现仍有不一致，登记变更或工程缺口；不能通过放宽权限或修改金额口径消除差异。数据库字典控制表结构，产品规格控制业务行为，两个层面必须共同满足。

## 采用的文档版本

| 内容 | 收录依据 | IB-1.1 处理 |
| --- | --- | --- |
| 产品及前端业务 | 综合需求 V1.2 | 完整正文、108 项需求、配置、验收与流程图本地化 |
| 运营后台 | V2.1-review | 完整模块、59 项 BKR、字段、权限、流程、验收；收口默认权限 |
| 玩家 UI | design-next V4 / D2.2 | 本地原型、规范、状态与字段矩阵；修正 TG 首期和越权旧文案，补 Web 认证画板 |
| 运营 UI | 后台 V2.1 页面与字段规格 | 新增本地规格驱动的交互样稿；演示数据，页面验收尚未执行 |
| 技术架构 | V1.1-review | 采用模块化单体、单桌单写、Node 权威写入、REST/WSS、Outbox |
| 数据字典 | V1.5-review | 92 表、1001 个显式业务字段；保留 V001～V014，新增 V015，运行验证仍待完成 |
| 任务 | 任务清单 V1.3 | 提取台账，纠正旧计数及待决状态；不凭文档发布推定代码验收完成 |

“收录”和“发布”只说明文档成为开发依据，不代表被收录软件已经实现。来源版本中的 review、未执行状态在本包中保留，不把计划包装成测试证据。

## 交付范围

| 范围 | 本期要求 | 开放条件 |
| --- | --- | --- |
| Web 身份 | 登录名、密码、展示昵称、服务器会话与单操控接管 | 完成受限写入口、认证及会话测试 |
| 房间与俱乐部 | 单一归属、ROOM/CLUB 邀请、成员目录、授权模板开房 | 对象范围和并发校验通过 |
| 对局 | 长牌 8 席、短牌 6 席；合法行动、边池、超时及恢复 | 先打通长牌，再完成全部本期玩法；不可省略短牌作为最终交付 |
| 资产 | TEST 测试资产、复式账本、买入补码、返还与费用 | 真实 PG16、幂等、并发和守恒验证通过 |
| 后台 | 独立认证、TOTP、授权范围、业务管理、审计及工单 | 若依通过管理 API 发起核心业务写入 |
| 其他本期 | 代理应计、牌谱、战绩、统计、文字/语音转文字、举报与导出 | 按需求优先级和对应资源门禁实施 |
| Telegram | 身份绑定、宿主适配、深链转换 | M6 后续独立阶段；不阻塞首期 Web |
| 保险、真实充提、真实佣金支付、链上核验、锦标赛 | 后续专项 | 本期不开放；保留需求追溯，不伪造订单或成功状态 |

TEST 交付不等于真实经营上线；本期模型保留正式资产的扩展能力，不把产品永久限定为测试币。

## 固定业务裁定

- 登录名 4～32 位 ASCII 字母、数字或下划线，小写规范化唯一；昵称 2～20 个可见 Unicode 字符，允许重复。
- 玩家密码 8～72 字符，禁止空密码；首次注册只建普通玩家，不授管理员、不由客户端设余额。
- 账号连续 5 次认证失败锁定 15 分钟；认证入口每 IP 每分钟最多 30 次；操控会话最长 24 小时。
- 只发布一套初始模板：TEST、长牌 8 席、2 小时、SB/BB=1/2、买入 100–300、Ante/抓头关闭；其他候选模板保持 DRAFT。
- 服务费模板 CSV_STANDARD_V2：5%，默认全手封顶 1.5BB，逐池分配按产品算法执行；提前盈利离座费默认 30%，豁免按离座原因与时点判定。
- 默认俱乐部存在，但玩家开房默认关闭。仅超管创建俱乐部、发布规则与费用、执行资金调整；运营只处理已授权对象及动作。
- 普通角色不默认获得 IP、未公开私牌、全局审计或导出权限；服务端必须裁剪字段。
- 账务使用整数最小单位，数据库存 UTC，业务日与产品展示使用 Asia/Shanghai。文档发布日期使用项目当前日期，不改变产品业务时区。
- 牌谱 180 天；账本、审计、举报工单 365 天；聊天 30 天；证据至少保留至结案；ASR 成功即删原音频、失败最长 24 小时。

## 工程边界

前端使用 Vue 3、TypeScript、Vite、Pinia；Node 采用 22 系列兼容基线并在建项时锁定补丁版本；数据库 PostgreSQL 16+、Flyway。若依选择现有 Vue 3 目录；当前源码内部版本 4.8.2、Java 8 / Spring Boot 2.7.18，仅为隔离迁移起点；目标 Java 21 LTS + 仍获安全维护的 Spring Boot（建项锁定补丁与支持证据），完成安全适配和回归后才可发布。后台唯一认证事实在 Node/poker.admin_*，原生 sys_* 登录与旧令牌在生产禁用，见架构 ADR-010。

Node 游戏业务服务拥有核心玩家、俱乐部、牌桌、钱包和结算写入权；若依是运营工作台。应用身份、迁移身份、后台身份和玩家身份分离。受限数据库写函数未实现时保持拒绝，禁止临时开放表写权限绕过。

## 第一个可验收成果

1. 隔离 PostgreSQL 16 执行 V001～V015、五组 SQL 测试与并发用例，保存日志。
2. 建立可重复构建的 Node / Web / 若依工程、环境模板与 CI。
3. 完成 LOCAL 身份、服务器会话、复式账本和 Outbox。
4. 两个真实浏览器玩家：注册登录 → 授权房间 → 买入 → 完成一手 → 费用结算 → 离桌返还 → 查账 → 进程重启恢复。

该闭环是 M2 的阶段成果；完整本期需求与 M5 发布门槛仍须继续完成。

## 仍待落实的实施门禁

[门禁登记](../docs/gates.html)逐项记录真实 PG16 执行、受限函数、接口契约、密码重置渠道、ASR 接入、生产资源、容量与发布证据。已明确的保留期、首期身份与权限规则不再作为待决问题反复询问。未决事项只阻断对应入口，不阻断无依赖的基础开发。

## IB-1.1 设计修订

修复 A1～A5/B1～B5：Outbox及每消费者租约、持久化会话代际、物理表名对齐、单 poker Schema/角色隔离、若依单一认证、Node/PG职责、手间事务重入、RBAC组合、TOTP单调消费、强制有效预约。详见[修复核对报告](../maintenance/ib11-fixes.md)。既定牌局与费用算法不变；新增迁移及规格不等于业务代码已完成。


---

# 冲突裁定与变更记录

版本：IB-1.1 · 2026-10-21。以下裁定来自已确认的产品与架构，不新增经营功能。

## 本次完成的收口

| 编号 | 旧资料差异 | 统一执行规则 | 本包调整 |
| --- | --- | --- | --- |
| IB-001 | UI 仍以 TG 验证和深链为首期入口 | 普通 Web LOCAL 注册登录，Telegram 后置 M6 | UI 文案、普通 HTTPS 邀请与登录注册画板同步；TG 身份仍只作后续模型 |
| IB-002 | 旧代码昵称唯一、可空密码、首注册提权 | 登录名唯一、昵称可重复、密码必填；首注册为普通玩家 | 前后端认证要求统一；旧实现只作参考 |
| IB-003 | 设计 PERM-06 允许运营创建俱乐部 | 仅超管创建 | 修订收录的 UI 权限矩阵，运营仅可按范围编辑基础资料 |
| IB-004 | 设计 PERM-17 允许运营测试调款 | 资金调整即使在 TEST 也只允许超管，必须账本与审计 | 修订权限矩阵；后台无余额编辑快捷操作 |
| IB-005 | UI 演示 200–600、短牌等像已发布模板 | 初始仅 TEST 1/2、100–300、长牌8席2h | 原型展示非发布玩法时明确标为规则样稿；演示数据不入数据库种子 |
| IB-006 | 已有正式归属的申请批准即切换 | 已有归属走双侧授权迁移，在手时手后生效 | 状态规格区分审核结果与归属实际生效 |
| IB-007 | 战绩示例不同统计范围金额混算 | 已完成会话与进行中暂计分开 | 统一规范；原型样例增加口径说明并修正示例合计 |
| IB-008 | 任务追踪仍称58项后台 | 当前 BKR-001～059 共59项 | 更新统一台账与追踪表，保留原任务ID |
| IB-009 | 数据保留期已定但风险仍待决 | 采用已确认180/365/30天和ASR规则 | 统一决策台账标为已明确，落实清理/归档任务仍待实现 |
| IB-010 | 数据库“待验收”易被视为已执行 | 当前仅静态门禁可执行；真实PG16尚缺证据 | 显式列为运行验证未执行，不以结构文档替代验收 |
| IB-011 | BP-32已在后台规格，DB权限种子仍至BP-31 | 玩家重置仍是待实施闭环 | 新增凭据对象与BP-32迁移属于后续工程任务；不回改已登记checksum的迁移 |
| IB-012 | 旧服务可直接凭user_id恢复身份及任意娱乐补码 | 服务器验证会话，资金均走账本和业务授权 | 禁止把旧入口带入正式环境 |
| IB-013 | 后台“实名负责人和排期”旧文案 | AI按依赖、证据和外部资源推进，不虚构固定人员或日期 | 仅保留实施资源门禁与人工发布决定 |
| IB-014 | 老域名与原目录被视为阅读依赖 | 本包独立阅读、相对路径部署 | 所有导航、UI资源和图片本地化，服务器路径仅ASCII |

## 使用边界

初始种子范围不等于完整本期范围。短牌、统计、聊天、代理等仍保留在本期最终交付，只有实际发布模板和依赖资源受门禁控制。权限默认拒绝；任何新增权限必须明确动作、对象范围、有效期及审计。

## 变更规则

后续修改记录：变更编号、原因、确认来源、受影响需求ID、UI状态/字段、接口、数据库迁移、测试及生效版本。已执行的Flyway迁移不得回改；采用向前迁移。版本号IB-1.1表示兼容的规格补充，破坏性身份、资金或规则改动另行明确迁移方案。

## 本次核查范围

核查本地最新产品、运营、设计、架构、数据字典、迁移、测试脚本和任务台账，固定来源SHA256；未重新逐帧审看原视频，未连接业务数据库或修改服务器。上游截图和视频关键帧保留作证据，不作为额外运行依赖。

## IB-1.1 设计修订记录（2026-10-21）

确认来源：用户要求读取《命令提示符.txt》并解决项目问题；文件仅作为缺陷线索，逐项对照现行源稿后修订。

| 决策 | 变更与依据 | 产物与验证 |
| --- | --- | --- |
| ADR-008 | 单 poker Schema + 最小角色权限替代三 Schema 建议 | 架构7.1、V015；原14迁移哈希不变 |
| ADR-009 | Node 唯一流程规则；PG保不变量和受限持久化 | 架构4.2.1、字典16.2；不移除强资金保护 |
| ADR-010 | poker.admin_*唯一后台身份，Node认证，Java安全适配 | 架构6.6；旧栈迁移及原生入口禁用为上线门禁 |
| ADR-011 | T1手结算/T2原子手间/T3下手准入 | 架构9.3.1；崩溃与并发场景待业务实现验收 |
| ADR-012 | DENY优先，角色动作与scope取交集，匹配上限取最小 | 字典12.10；列表/字段/导出共用判定器 |
| IB-015 | Outbox事件+每消费者投递、代际、TOTP高水位、预约必需 | 字典4.1/4.4/8.6.1/12.2/13.8/13.9、V015、SQL005 |

备选与取舍见对应架构 ADR。新增结构向前迁移，不覆盖任何历史 Flyway 校验和；V015 撤销旧玩家会话要求重新登录。发布文档修订与数据库迁移/业务上线分开验收。


---

# UI设计与交付规范

版本：IB-1.1。玩家端沿用V4/D2设计体系，已对齐首期Web身份与最小权限。后台以V2.1字段和状态规格为依据制作本地交互样稿。

## 本轮设计评审 R01–08（2026-10-27）

- [进入本轮改稿与选座场景](../ui/review/index.html?screen=redo-review)
- [修改记录与验证](../ui/review/review-notes.html) · [预览图片](../ui/review/previews/index.html)

本轮改稿来自“德扑重做01～08”，版本 V3.3，覆盖俱乐部、我的、牌桌选座买入、房间信息、成员与记录账单。真实资金、多人竞抢与对局仍为本地演示。此入口供视觉及交互评审，评审通过前不自动变更下述 IB-1.1 首期范围、数据库和权限裁定；原实施基线玩家原型仍保留作对照。

## 原实施基线原型

- [原实施基线玩家设计工作台](../ui/player/index.html)：俱乐部、游戏、我的、买入、长短牌、记录、聊天及恢复画板。
- [Web登录与注册](../ui/player/auth.html)：新增LOCAL入口，包含输入校验、锁定、限流、提交和成功演示。
- [运营后台交互样稿](../ui/admin/index.html)：16模块导航、表格/详情字段、状态、敏感操作确认与结果未知演示。

原型不访问业务API，不发送真实账户、余额或密码。原型中的操作成功只演示状态；产品验收必须连接真实服务。后台样稿是本次新增的规格表达，不能被称为已经通过生产UI验收。

## 视觉与组件

玩家产品使用暗绿底、荧光绿强调色；优先突出合法主操作、本人底牌、轮到本人和资金结果。界面按逻辑seat_no展示，视觉旋转不得改变规则。设计工作台的网格、状态切换、自动播放不进入正式客户端。

后台样稿使用浅色工作表面、清楚的模块导航、筛选、数据截止、表格和详情抽屉；危险操作不置于行内一键执行。仅超管资金调整，独立TOTP参数确认；默认遮蔽认证标识与敏感数据。

详细规范：[Design Token](../docs/ui-tokens.html)、[字段与事件](../docs/ui-contract.html)、[页面状态](../docs/ui-states.html)、[角色权限](../docs/ui-permissions.html)、[设计验收](../docs/ui-acceptance.html)。

## 页面范围

既有P01～P18全部保留。新增P19登录、P20注册、P21会话过期/设备接管/锁定与限流，身份字段来自产品V1.2。S01设计交付页不是正式路由。L01～L03保险、链上核验和真实充提仅作后续档案，不进入本期产品导航。

初始发布仅一套长牌模板。短牌、抓头、Ante和其他买入档位在原型中表达完整本期规则或候选状态，不代表初始化种子已允许开房。生产列表只显示实际已发布、已授权配置。

## UI执行规则

1. 规则与金额由服务端提供，真实0、缺失和未知分别显示。
2. 每个写动作覆盖IDLE/SUBMITTING/UNKNOWN/FAILED/SUCCEEDED；UNKNOWN只查询原操作。
3. 移动端覆盖320/360/390/430宽度、软键盘与安全区，桌面覆盖工作台布局。
4. 无数据、筛选无结果、权限不足、服务失败与记录过期分别呈现。
5. 图标有可访问名称，键盘能操作，焦点可见，弹窗管理焦点；不只依靠颜色表达状态。
6. 审核通过与归属实际生效分开；已结束战绩和进行中暂计分开。

## 证据与来源

[本地截图与关键帧](../docs/evidence.html)收录已存在的上游截图及抽帧，保留文件指纹。它们是视觉/行为参考，旧Telegram、保险、充提入口不覆盖本期范围。原始视频未纳入静态文档包，规则已通过需求正文和时间定位固化；后续需要重新审片时再取原始资料。


---

# 前端需求

版本：IB-1.1。适用玩家 Web 与若依运营 Web；完整业务正文见[产品需求](../docs/product.html)，每项需求及验收编号见[需求追踪](../docs/traceability.html)。

## 客户端职责

玩家端采用 Vue 3 + TypeScript + Vite + Pinia。渲染服务器确认的状态、合法动作、金额和权限，维护输入草稿、提交中、未知结果、明确失败、成功及重连过程。客户端不裁定余额、结算或业务权限。工作台原型控件不进入正式产品。

## 玩家页面与验收

| 模块 | 必须实现 | 关键状态/验收 |
| --- | --- | --- |
| Web认证 | 登录、注册、退出、会话恢复、设备接管、协议接受 | 登录名与昵称分离；密码不可空；重复昵称合法；锁定、限流、会话过期、旧设备失权明确 |
| 主导航 | 游戏、俱乐部、我的 | 登录后默认俱乐部；不增加一级分享导航 |
| 邀请 | 短码或普通HTTPS链接输入，ROOM/CLUB解析 | 无效、过期、撤销、限流、目标冻结；业务邀请不充当注册邀请码 |
| 俱乐部 | 资料、房间列表、成员目录、本人申请及迁移状态 | 普通成员不出现签发、审核、自退或创建俱乐部入口；在手迁移显示待生效 |
| 房间与开房 | 模板选择、规则费用披露、受权开房、排期展示 | 只选服务端返回已发布且已授权的模板；未授权路由与提交均拒绝 |
| 买入 | 选座、15秒预约、金额与费用确认 | 抢座、到期、余额不足、准入失败、关闭、提交中、未知结果及确认成功 |
| 牌桌 | 长牌8席、短牌6席，公共牌、本人牌、底池、动作、位置与截止时间 | 仅按legal_actions展示操作；加注目标额与增量分开；不可收到他人未公开私牌 |
| 补码与退出 | 冻结、手间生效、费用预估、离桌清算、返还 | 不向当前手直接加筹码；未知结果按原操作号查询；豁免与收费原因清楚 |
| 记录与资产 | 可用/冻结/在桌托管、账单、会话战绩、单手记录、回放 | 不跨币求和；只汇总已完成会话，进行中暂计分列；无分母显示“—” |
| 社交与客服 | 文字、快捷语、免费表情、语音转草稿、举报、本人举报结果 | 旁观只读；禁言不阻止举报；ASR失败可重试或转文字，不伪造已发送 |
| 恢复 | 重连、版本缺口、权威快照、会话接管与结果查询 | 保留座位及资产；展示服务器恢复状态；不可由超时推断退款 |
| 偏好 | 主题、快捷下注、头像昵称与复制Game ID | 稳定玩家ID不变；剪贴板失败可手动复制；声音/振动处理设备授权 |

## 认证字段

注册输入 `login_name`、`password`、`display_name`。登录名4～32位ASCII字母数字下划线、小写唯一；昵称2～20个可见Unicode字符，可重复；密码8～72字符。失败文案不能泄露账号是否存在。5次失败锁15分钟、IP每分钟30次限流由服务端执行，客户端展示安全错误和重试时间。

不提供公开“忘记密码”绕过页。若未来开放受审计重置，独立处理一次性凭据，不以后台代设密码。演示原型的登录跳转不代表认证接口已实现。

## 请求与实时契约

- 业务提交使用唯一请求号；同号同参返回原结果，同号异参拒绝。HTTP、WSS共用业务用例。
- 超时进入UNKNOWN，只查询原号；确认失败后才允许修正并创建新请求。页面刷新、重新登录后仍可恢复原操作结果。
- 金额传整数最小单位并携带资产和精度；未知、缺失和零值区分。
- 时间携带时区及server_time，倒计时根据服务端deadline计算；页面可见性切换后校准。
- WSS按事件版本检测重复、乱序及缺口；缺口拉取权威状态，旧会话不能继续发动作。
- 完整字段见[字段与事件契约](../docs/ui-contract.html)。正式端点、消息类型及错误码由M0接口任务形成可校验契约；本包不把视觉原型事件名冒充已实现API。

## 运营前端

采用若依 Vue 3 目录。包含16个模块：总览待办、玩家、俱乐部、邀请申请、规则费用、房间恢复、代理、资金账本、牌谱、统计、聊天举报、客服、导出、配置、认证授权和审计。逐项表格/详情/筛选/确认字段以[后台模块](../docs/ops-modules.html)、[展示字段](../docs/ops-fields.html)、[权限矩阵](../docs/ops-permissions.html)为准。

默认列表近7天、20条/页、最大100；时间区间[start,end)。筛选、合计、详情和导出保持同资产与同授权范围。详情显示来源、数据截止与完整性、更新时间、对象状态和关联操作。无权字段不由服务端下发；前端隐藏不能代替权限检查。

危险操作先确认对象、影响、原因与范围，敏感动作调用参数绑定TOTP。提交成功、受理、手后生效与清算完成分别显示。资金调整跳专用流程，不允许行内编辑余额。BP-32渠道门禁未关闭前，玩家密码重置入口关闭。

## UI和适配要求

[玩家原型](../ui/player/index.html)、[Web认证原型](../ui/player/auth.html)、[后台交互样稿](../ui/admin/index.html)均只使用演示数据。实现规范包含[Design Token](../docs/ui-tokens.html)、[页面状态](../docs/ui-states.html)、[角色权限](../docs/ui-permissions.html)和[设计验收矩阵](../docs/ui-acceptance.html)。

验证Chrome、Edge、Safari和目标移动浏览器；覆盖320、360、390、430及桌面宽度、安全区、键盘遮挡、弱网和切后台。操作可键盘完成，焦点可见；弹窗限制焦点并关闭后返回；状态不能只靠颜色区分；尊重减少动画设置。

## 前端完成标准

逐项提供需求ID、页面与状态、字段来源、权限拒绝、失败/未知/恢复截图或自动化证据。页面能打开、原型能点击或Mock返回成功，均不能代替连接真实服务后的产品验收。

## 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。适用Node权威业务服务、后台worker及若依管理接入。规则全文见[产品需求](../docs/product.html)，逐表字段见[数据字典](../docs/database-dictionary.html)。

## 服务职责和写入边界

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均属于后端权限、查询、动作和审计实现要求，见[后台需求目录](../docs/ops-catalog.html)、[流程状态](../docs/ops-workflows.html)及[展示字段](../docs/ops-fields.html)。其中标“建议读模型”的字段仍需查询设计，不表示视图已存在。数据字典中的敏感表不能因为前端有展示字段就开放直接读取。

## API契约交付要求

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

## 服务端完成标准

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

## 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完整摘录/规范化收录。与本包[统一基线](../docs/baseline.html)和[冲突裁定](../docs/decisions.html)配套执行；旧来源状态不代表软件完成。

# 风暴扑克产品需求文档

版本：综合稿 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中与该基线冲突的建议已替换，旧稿保留在[历史版本](../docs/product.html)。截至2026-10-21确认的默认方案已写入对应章节与待决事项；本文中的D/B指已形成的产品裁定/商业默认，不表示功能已开发、上线或验收。

**阅读入口：** [需求总表](../docs/product-requirements.html) · [配置字典](../docs/config.html) · [完整验收场景](../docs/product-acceptance.html) · [核心验收用例](../docs/product-core-tests.html) · [待决事项](../docs/gates.html) · [来源文件清单](../docs/sources.html) · [素材索引](../docs/evidence.html)。本次沿用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章，也可打开[业务流程图独立阅读页](../docs/product-flows.html)。

### 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 预设示意与预期

下例为本版数据契约示意，不是已实现接口。仅在指定测试房间、两个账号均实际参局且均属测试白名单时适用。

```json
{
  "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为赛事规则，仅采用明确声明的部分。

- R01 [Poker TDA 2026规则正文](https://www.pokertda.com/view-poker-tda-rules/)：摊牌顺序、零头、累计短全下、BB前注支付顺序。
- R02 [PokerStars抽水表](https://www.pokerstars.com/poker/room/rake/)：收费结构参考，本项目数值为B。
- R03 [PokerStars短牌](https://www.pokerstars.com/poker/games/six-plus/)：36张与牌型变化，庄位盲结构不采用。
- R04 [Telegram Mini Apps](https://core.telegram.org/bots/webapps)：身份校验、宿主接口；单桌是D。
- R05 [PokerTracker统计参考](https://pt4.pokertracker.com/guides/PT3/general/statistical-reference-guide)：VPIP/PFR/W$SD，不包含竞品综合实力公式。
- R06 [PokerStars回桌限制](https://www.pokerstars.com/help/articles/ratholing-rules-ps/)：独立策略参考，不替代本产品离座费用。
- R07 [PokerStars规则帮助](https://www.pokerstars.com/help/articles/poker-rules-master/217459/)：摊牌与加注参考。
- R08 [MDN SpeechRecognition](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition)、[getUserMedia](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia)：V1研究的语音兼容/权限依据，正式接入需按目标端实测。

V3.2新增公开依据（2026-09-19读取官方资料）：

- S01 [OWASP多因素认证](https://cheatsheetseries.owasp.org/cheatsheets/Multifactor_Authentication_Cheat_Sheet.html)：第二因素遗失须有受控恢复机制；本项目TOTP、恢复码及人工恢复为D取舍。
- S02 [OWASP会话管理](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html)：服务端执行空闲及绝对过期；15分钟/8小时是项目默认。
- S03 [OWASP交易授权](https://cheatsheetseries.owasp.org/cheatsheets/Transaction_Authorization_Cheat_Sheet.html)：授权绑定用户确认的操作数据，修改后失效，执行前校验，凭据限时且单次；不把“已登录”当成操作授权。
- S04 [Stripe幂等请求](https://docs.stripe.com/api/idempotent_requests)：同键重试与参数一致性可作设计参考；不引入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](../docs/product.html)、原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章，作为后续专项输入，未被升级为本期购买规则。原始图、采样帧及[素材索引](../docs/evidence.html)保持可追溯。

## 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 验收材料的使用方式

[完整验收场景](../docs/product-acceptance.html)承接归档196个场景，并追加本次OPS-AC01～OPS-AC12；[验收用例](../docs/product-core-tests.html)在原AC01～AC30基础上新增AC31～AC39客户端异步状态案例，并附加12个后台补充案例。两表有重叠，不能相加当作独立覆盖数量。新增OPS编号在[需求总表](../docs/product-requirements.html)映射，不复用归档已有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不变，软件验收仍为“未执行”。图中未展开的金额、计时与授权条件，以标注的正文条款为准。

可打开[流程图独立阅读页](../docs/product-flows.html)，或点击各图下方的SVG矢量文件放大阅读。PNG用于网页和Word嵌入，SVG用于原尺寸查看与后续编辑，两者均为本地静态资源，无需联网渲染。图中橙色表示判断或待确认，红色表示拒绝或冻结核查，绿色表示已确认结果；状态也用文字表达，不只依靠颜色。

### 27.1 玩家完整业务流程

![图01 玩家完整业务流程，含身份资格拒绝与提交结果未知分支](../assets/flows/product-01.png)

[查看图01矢量版](../assets/flows/product-01.svg)。依据第04、05、06、08、11、12、19章。首期普通Web注册/登录和访问资格通过后，玩家先接受规则再买入；成功后依名单及等盲规则参局，退出时核对返还、账单与战绩。身份或资格不满足不扣款。任一写操作结果未知时停留在原业务并查询，明确失败按图04/05处理；图01不表示所有环节均可无条件进入下一步。未来TG入口替换认证提供者，但不改变图中统一账号之后的业务流程。

### 27.2 邀请进入与审核

![图02 邀请进入与审核，区分24小时免审与永久审核以及房间和俱乐部目标](../assets/flows/product-02.png)

[查看图02矢量版](../assets/flows/product-02.svg)。依据第06、6.2、6.3、6.4、16章。ROOM/CLUB与24h免审/永久审核独立组合；默认房间24h免审、俱乐部永久审核，不是固定类型约束。审核在运营后台由有权限者执行，批准瞬间仍须检查邀请、目标与账号状态；拒绝后必须使用新邀请重新申请，不提供解除拒绝动作。邀请撤销、房间关闭或俱乐部冻结不能因已申请绕过。

普通用户收到链接不等于获得签发权限，也不传播邀请者权限；无签发权限不展示邀请按钮。分享仅由用户主动触发。ROOM只授予目标房间访问，不改俱乐部或代理归属；CLUB准入的归属处理接图03。

### 27.3 俱乐部归属与迁移

![图03 俱乐部归属迁移，区分立即生效和手后复核生效以及旧桌临时权限](../assets/flows/product-03.png)

[查看图03矢量版](../assets/flows/product-03.svg)。依据第06、6.4、6.5、25.1、25.2章。自然访问进入默认俱乐部；默认归属接受有效CLUB邀请准入后按生效时点处理，已有正式归属须由授权运营显式迁移，不能仅凭邀请自动覆盖。迁移需源、目标双侧范围和ACTIVE目标，每人最多一笔待生效迁移。

无在手在事务中立即生效；有在手等本手结算或作废后、下一手名单形成前复核生效。复核失效取消并保留旧归属。原桌已买入会话仅保留该房间会话临时权，不得绕过禁用、冻结或关闭；退出后失效。旧成员目录权限即时取消，本人历史账单和牌谱不丢失。

### 27.4 授权开房与规则冻结

![图04 授权开房，区分明确成功明确失败和结果未知](../assets/flows/product-04.png)

[查看图04矢量版](../assets/flows/product-04.svg)。依据第4.3、07、7.1章。运营后台发布模板与配置开房授权；客户端只选已发布模板、编辑允许字段。确认成功前不显示房间号或邀请入口；同request_id返回同一房间，不重复开房。结果未知持续查询原号，确认失败后才允许修正并发起新请求。

图04展示即时开房。单次计划开放仍按7.1节：SCHEDULED不能买入，到时复核权限和模板后转WAITING并开始默认24h邀请有效期；永久审核邀请可以提前申请，但开放前不得入座。循环排班不在本期。

### 27.5 入桌与买入

![图05 预约座位和买入，展示原子校验及未知结果查询](../assets/flows/product-05.png)

[查看图05矢量版](../assets/flows/product-05.svg)。依据第4.3、08、8.1、12章。选空座后预约15秒；身份、资格、余额、币种、房间、座位和已接受规则版本与扣款同事务校验。成功才把可用转入托管；明确失败不残留冻结。请求已提交但结果未知时，预约倒计时结束也不能由客户端推断失败或退款，应按原号取得权威结果。

满桌按观战开关提供旁观或满员说明，不自动排队扣款；进行中买入等待下一手及自然BB，不接收当前手底牌。补码独立执行8.1节：一笔待处理、先冻结、手间应用退差；不是再次买入或向当前手直接加筹码。

### 27.6 牌局状态与合法行动

![图06 牌局状态，含逐街行动超时自动动作一人获池全下亮牌和手后调度](../assets/flows/product-06.png)

[查看图06矢量版](../assets/flows/product-06.svg)。依据第08、09、10、11、19章。名单锁定和强制款提交后才发底牌；每街完成全部合法响应才进下一街。仅一人未弃牌立即结束，不发未来牌；多人且无法互相继续下注则按规则补齐公共牌并自动亮牌。下注目标、完整加注差额和逐玩家重开资格仍严格执行9.3节，不能从简图推断任意加注。

行动超时能过则过，否则弃牌，再执行房间已冻结的A/B缺席策略。计时按BASE/BANK/GRACE/AUTO及11.1节执行；服务故障暂停计时，不作为玩家超时。手牌STARTED→SETTLING→SETTLED原子结算，广播失败只补通知。手后先处理离座、退款、补码和位置，再准备下手；房间到期或DRAINING不再开新手。

### 27.7 资金流转与离座清算

![图07 买入补码手牌结算与离座返还，区分盈利收费和豁免](../assets/flows/product-07.png)

[查看图07矢量版](../assets/flows/product-07.svg)。依据第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 异常恢复，区分结算已提交可恢复可信快照作废以及无法确认冻结核查](../assets/flows/product-08.png)

[查看图08矢量版](../assets/flows/product-08.svg)。依据第4.3、19、20.2、25.4章。客户端请求未知只查询原业务；房间故障才进入全桌恢复。已提交返回原settlement_id，不再派奖；未提交且日志可信则继续原手；不能恢复但有可信手前快照则VOID并去重冲回实付贡献，撤销本手费用与计提，保留前手和独立补码。

不能判定是否提交，或没有可信恢复依据，进入RECOVERY_REQUIRED并冻结核查，不自动退款、不超时生成新单。人工纠错须新授权分录引用原单，不改旧余额或删除历史。自然到期与故障相遇停止下一手，恢复后免离座费清算。图中“仅请求未知”分支与故障恢复分支独立，不代表等待时间届满就进入作废退款。

### 27.9 玩家端与运营后台职责泳道

![图09 玩家端业务服务运营后台三方泳道，配置审核与敏感操作在后台，权威执行在业务服务](../assets/flows/product-09.png)

[查看图09矢量版](../assets/flows/product-09.svg)。依据第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完整摘录/规范化收录。与本包[统一基线](../docs/baseline.html)和[冲突裁定](../docs/decisions.html)配套执行；旧来源状态不代表软件完成。

# 风暴扑克运营后台需求文档 V2.1

版本：V2.1-review · 更新日期：2026-10-21  
受众：产品、UI、研发、测试、运营与交付负责人  
状态：评审稿；默认方案已确认并纳入基线，实名负责人、排期及实施资源仍待提供。

## 1. 产品定位与问题

这套后台让授权人员管理玩家、俱乐部、房间与代理，处理邀请和举报，核对每笔费用与资金，并能区分“操作已提交”和“业务已生效”。它不替玩家行动、不实时透视、不直接改余额或牌局结果。

当前玩家端提供俱乐部、邀请申请、授权开房、买入、牌桌、账单、回顾与举报，但这些入口背后的配置发布、授权、审核、归属迁移、处置反馈与纠错需要独立后台承接。只按旧CSV生成CRUD页面，会遗漏手后执行、撤权复核、日结重算、私牌专项审计和未知结果查询。

证据来自当前产品文档、设计稿和规则附表，不把页面演示当真实实现，不虚构访谈、运营交易量、留存收益或已完成的代码改造。

## 2. 依据与适用规则

1. 本次用户指令及后续确认。
2. 当前综合需求V1.2明确业务规则及其需求、配置、验收附表。
3. 与当前规则一致的设计V4及字段/事件契约，用于推导入口与反馈。
4. 原始运营CSV，用于逐项查漏。
5. 旧《运营后台开发文档-V1》，仅用于查漏及工程参考。

当前规则冲突须在[差异清单](../docs/decisions.html)登记；不得静默选择更宽权限。新编号BKR仅用于后台派生需求，保留原ADMIN、CLUB、MONEY、OPS等基线ID。BKA是新后台验收场景，不与原产品验收数量相加宣称完整覆盖。

需求性质分为“基线展开”和“交互推导”：前者细化已定义能力，后者为其提供页面组织、反馈或导航。后者不是新增收费、角色权力或经营许可。

## 3. 本期范围与非目标

| 范围 | 本期需要 | 不包含 |
| --- | --- | --- |
| 人员与身份 | 后台独立认证、TOTP、激活/恢复、账号与资源范围；玩家 LOCAL 身份状态查询及受控密码重置 | 后台代设/读取玩家密码、玩家凭据登录后台、首注册者自动超管；Telegram 验签/绑定本期后置 |
| 组织与准入 | 俱乐部、成员迁移、邀请签发/撤销/审核、玩家开房授权 | 玩家自建自退俱乐部、普通成员自动获得签发权 |
| 游戏运营 | 规则模板、费用版本、即时开房、单次排期、手后关桌、故障跟踪 | 代买入、代打、改牌、随意作废/强跳结算、循环排班 |
| 玩家与记录 | 玩家/登录查询、禁用解禁、战绩、事件回放 | 旧摘要补造录像、用当前字段覆盖历史快照 |
| 资金与收益 | 分币账本、超管调款/纠错、收入、单层代理、应计日账 | 真实充提、真实佣金付款、多层自动分成、俱乐部独立钱包 |
| 支持与审计 | 巡检、举报工单、公开结论、私牌专项授权、操作及导出审计 | 实时全知视角、自动判作弊并扣款、删除审计 |
| 交付 | 页面状态、真实业务接口契约、验收与证据 | 本次制作后台UI、后端代码、DDL、发布部署或迁移运行数据 |

保险、链上验证、付费礼物、Limit、锦标赛和脚本预设发牌运营入口均不进入本期后台。QA-02仍是独立隔离测试工具，不因此删除产品测试需求。

TEST是不可兑换的测试资产实例，并非把产品永久限定为测试币。真实经营上线的资质、地域、协议主体与支付合规须由业务主体专项核验；本稿不作合法经营判断或上线批准。

## 4. 角色、身份与授权

后台人员账号、统一玩家账号、玩家认证身份和代理实体分别管理。同一玩家可有 LOCAL 及后续 TELEGRAM 身份，但都解析到同一 `player_id/game_id`，不得产生第二套钱包、俱乐部归属或战绩；同一个自然人即使另有后台账号，登录态、权限和数据范围也不互通。代理的业务管理关系不产生多层佣金或全局后台权。

| 角色 | 主要工作 | 默认边界 |
| --- | --- | --- |
| 超管 | 俱乐部创建、授权、费用发布、资金调整和审计 | 全局业务范围不等于实时私牌权；敏感动作须单次授权 |
| 运营/普通管理员/总代理 | 仅授权俱乐部范围内的成员、房间、邀请、代理、等级及查询 | 不创建俱乐部、不调款、不自行增权；比例不超授权上限 |
| 客服/巡检 | 仅已分配或授权范围工单及公开桌面、临时禁言 | 不默认读IP/钱包/私牌；永久禁言交运营或超管 |
| 代理只读工作台 | 仅本人协议、授权汇总及本人佣金 | 绑定后台账号须显式授权，不获取他人完整流水或IP |
| 玩家 | 首期 LOCAL 身份下的本人业务；后续可绑定 TELEGRAM | 不因注册、绑定、邀请、代理身份或设计目录得到后台权限 |

页面、动作、资源范围、执行时业务条件四层均须校验。列表、详情、合计、回放、导出采用同一范围，传入club_id/agent_id只能缩小范围，不能扩大。跨俱乐部迁移需双侧范围；异步动作实际执行前再次校验。

后台人员身份规则详见[流程](../docs/ops-workflows.html)：独立密码12–128字符+TOTP；激活24h单次；空闲15分钟、绝对8小时；敏感授权绑定参数120秒单次。玩家本地凭据使用产品规定的8–72字符密码和15分钟失败锁定；后台只能通过独立 BP-32 发起受审计重置，不能查看、代设或导出密码。后台激活邀请、玩家密码重置凭据和ROOM/CLUB业务邀请是三类不同对象，不得混用。

专项私牌访问是结束手、有效工单、指定用途/玩家及独立授权的受限例外。客服或运营可按其工单范围申请，申请人与审批人必须不同；由具备专项审批权的超管审批，不能因普通超管身份自动获得审批或查看权。批准后30分钟有效，每次实际访问仍须取得绑定本次参数的120秒单次TOTP授权；会话失效、撤权或工单失效时立即失效，每次访问均留审计。

## 5. 信息架构

建议导航为8组、16个业务模块；页面拆分是交互建议，不是16套独立系统。

| 导航组 | 模块 | 主要闭环 |
| --- | --- | --- |
| 工作台 | 运营总览、待办与操作结果 | 指标→明细→异常→原操作结果 |
| 玩家与组织 | 玩家及登录、俱乐部与归属 | 用户→原桌→迁移/禁用→实际生效 |
| 邀请与准入 | 邀请与申请 | 签发→申请→复核→批准→归属/访问 |
| 游戏运营 | 规则模板、房间与排期 | 草稿→发布→授权→开房→手后关闭 |
| 记录与资金 | 战绩回放、资产流水、调款纠错、收入 | 账单→手牌/会话→费用版本→原单与冲正 |
| 代理收益 | 代理与等级、分成日账、代理本人工作台 | 协议→逐手归因→日账→补结调整 |
| 客服风控 | 巡检工单、私牌专项审计 | 举报→处理→公开反馈；专项申请→独立审批→受限访问 |
| 系统治理 | 后台账号权限、审计与导出 | 激活/撤权→会话失效；导出→复核→限时下载 |

页面字段、筛选、允许动作、异常和玩家端反馈见[模块规格](../docs/ops-modules.html)。所有模块都须提供加载、成功、真实空态、权限不足、服务不可用、失败重试；写操作另有结果确认中。

## 6. 三端边界与生效语义

玩家端发起本人操作并展示结果；后台人员在授权范围提交配置、审核、处置或纠错；权威业务服务校验、执行、记账、确认生效并返回结果。后台不能直接更新运行余额、当前手筹码、牌序或结算字段。

| 后台动作 | 立即影响 | 延后影响与结果展示 |
| --- | --- | --- |
| 禁用玩家 | 阻止所有认证身份的新准入/新主动参与 | 在手权益保留，手后免离座费清算；分列准入封禁与清算状态；不删除或解绑身份 |
| 玩家密码重置 | 撤销全部玩家操控会话并创建一次性重置流程 | 不改变 `player_id/game_id`、钱包、俱乐部、战绩或 TG 绑定；未确认交付渠道时入口保持关闭 |
| 冻结俱乐部 | 阻止加入、买入、补码、开房；撤邀请/取消申请 | 当前手结束后清算关闭；恢复异常不得伪造已关闭 |
| 成员迁移 | 无在手立即事务生效 | 有在手等手结算/作废后、下一手名单形成前复核；撤权或目标失效则取消 |
| 关闭房间 | 停新买入、补码、新手 | 当前手完成后清算；未生效补码解冻一次 |
| 模板发布/代理协议更新 | 可用于之后创建/新手快照 | 不覆盖既有桌规则或已开始手协议 |
| 超管补偿 | 成功记入钱包可用 | 不增当前手筹码；必须业务服务返回已入账 |
| 工单结案 | 保存内部轨迹和公开结论 | 玩家端收到本人状态与公开结论，下次登录/回前台刷新 |

“请求已受理”不能等于“迁移已完成/款已到账/房间已清算”。统一操作详情保存operation_id、request_id关联、参数摘要、对象、原因、提交/受理/生效时间、领域状态、错误和原业务号。网络超时仅为UNKNOWN，查原操作号，不造新单，不自动退款。

## 7. 资金、费用与统计口径

金额按资产精度2使用整数最小单位，跨端不能浮点记账。可用、补码冻结、桌内托管分列；资产总额为三者之和，底池已在托管内，不再重复加。币种分别展示，不用汇率或混币总额偷换口径。

| 项目 | 当前确定口径 |
| --- | --- |
| 手工额度 | 初始0；超管TEST_GRANT/MANUAL_ADJUSTMENT/COMPENSATION，默认不可提；TEST单笔≤1000、单人每日≤5000，限额版本化 |
| 扣减/冲正 | 只动足额可用余额，不能负、不动在手；追加有效原单关联的新分录，不改历史 |
| 费用 | CSV_STANDARD_V2翻后抽水，全手封顶一次；默认低档5%/最小买入≥400为3%，默认cap1.5BB；不叠加截图小池/人数减免 |
| 离座费 | EARLY_EXIT_PROFIT_V2，提前盈利默认30%；到期、运营强制处置、故障及无有效手豁免；不参与代理分成 |
| 玩家收益 | 单手收益已扣抽水；会话收益再扣一次离座费；抽水归因只解释，不从钱包重复扣 |
| 代理应计 | 单层、逐池贡献归因；GENERAL默认0%；日汇总高精度后向下取分；不从玩家重复收费 |
| 代理业务日 | 手牌首次成功settled_at转Asia/Shanghai；每天00:10首结前日并补历史脏日，保留版本与调整轨迹 |
| 佣金支付 | 应计、测试支付标记、差额独立；本期无真实支付完成状态，负差额待人工核对 |
| 收入 | 抽水与离座费分别汇总，代理应计为收入内部划分；调整的业务日与记账日分列，不重复计入收入 |
| 有效手/用户 | 正常SETTLED的去重hand_id；时间内至少完成1手的去重user_id；不能把玩家手数相加作全平台手数 |

查询统一Asia/Shanghai显示、UTC存时、区间[start,end)；默认近7天、20条/页、最大100。手牌按settled_at、会话收益按会话结束、代理按业务日、调整另列实际记账时间。历史代理/名称/费率快照不被当前改名覆盖。

总览下钻必须带原时间、资产、俱乐部/代理/用户筛选及当前权限，说明数据截止时间和完整性。旧记录缺失注册时间、充值来源、费用或动作时显示未知或不可回放，不能推断补造。

加入转化承接产品20.3：同用户同房间30分钟旅程、首次合格入口归因；BUYIN_POSTED为成功，跨日等待窗口结束再定稿。没有真实基线时展示无数据/未建立，不编造目标提升百分比。

## 8. 配置分级，不做万能参数后台

| 配置类 | 后台能力 | 生效约束 |
| --- | --- | --- |
| 经营模板 | 超管发布费用/规则版本；运营按权准备非费用草稿及选已发布版本 | 草稿可改；发布不可覆盖；旧桌保持快照 |
| 组织授权 | 超管配置运营范围、比例上限、俱乐部玩家开房开关与模板白名单 | 撤权立即失效；不能给自己加权 |
| 协议等级 | 运营范围内创建/发布本人等级版本，不超比例上限 | 下一手用新协议；已开始手不改 |
| TEST额度限额 | 超管版本化调整 | 不套用于未来真实资产，不把限额修改当调款 |
| 系统固定策略 | 显示配置版本，修改走需求/部署变更流程 | 不自动把61项配置都开放编辑 |
| 用户偏好 | 玩家自行设置 | 不建设运营代改主题/快捷下注业务 |
| 测试预设/凭据 | 开发测试部署管理，运营端不可写；不展示秘密 | 正式环境禁止预设牌，普通日志不含全牌序 |

原七组买入范围为2–10、6–30、10–40、20–80、50–200、100–300、400–1200。V1仅发布TEST资产、SB/BB=1/2、买入100–300、长牌8席2小时、Ante/抓头关闭的完整种子；其余六组保持DRAFT，不推导盲注、资产或授权范围，也不阻塞V1。设计演示200–600不是新增获批档位。模板字段与全部默认值以当前61项配置字典为准；本稿不复制成第二个可独立修改的权威字典。

## 9. 安全、隐私、保留与导出

列表和普通回放只返回权限内公开字段，不先传未公开牌再隐藏。私牌访问只走专项流程，普通排错日志不含凭据、完整牌序或所有私牌。举报内部备注、其他举报人、IP及敏感处置细节不得流向玩家公开结论。

导出与查询同范围，最大31天，默认7天。生成中撤权失败；下载每次复核账号、原会话、范围；生成起15分钟到期，退出/会话过期/撤权立即不可用。建议异步导出任务页，禁止永久公开链接。导出列不超查询权限；CSV公式注入防护为安全交互细化，不能改变原账本金额。

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

## 10. 交付优先级、依赖和验收

P0/P1沿用主需求表：资金、权限、邀请准入、回放隐私、幂等恢复等P0保护先成立；总览、一般运营查询、单次排期、客服等本期P1仍须交付，不能以“第二阶段”为由删除。模块同时涉及P0/P1时按目录内每条BKR及其基线ID判断，不用菜单排序代替优先级。

建议实施批次（未承诺工期）：

| 批次 | 工作 | 准出条件 | 负责角色 / 时间窗口 |
| --- | --- | --- | --- |
| R0 | 冲突确认、权限种子、模板配置、契约与范围评审 | 无未裁决高风险权限冲突 | 产品+运营+技术 / 开发范围冻结前 |
| R1 | 独立认证、查询、范围、操作结果 | 未授权全入口拒绝；未知可追踪 | 前后端+测试 / 业务写入口开放前 |
| R2 | 组织邀请、模板、房间与处置 | 手后生效、撤权复核、冻结清算成立 | 游戏/后端+前端+测试 / 对应联调前 |
| R3 | 账本调整、费用收入、代理日账 | 分币守恒、幂等、迟到重算通过 | 资金/游戏后端+测试 / 资金功能验收前 |
| R4 | 工单、审计、总览、导出及完整回归 | 本期P0/P1均有实际证据，无敏感泄露 | 全体交付角色 / 测试环境交付前 |

实名负责人、资源、日期与值班尚未提供；上表不是已排期路线图。唯一权威业务执行方、操作结果持久化、账本、牌谱和领域事件是后台依赖，后台页面开发不能替代这些能力。

质量门槛：验收资金/规则差异为0、越权与私牌泄露为0、敏感变更审计完整率100%；这些是验收目标，当前无实测。页面存在、模拟返回、旧项目测试通过均不算后台通过。后台10万玩家/100万手/1000万分录、30并发及列表1秒/总览2秒P95仅为旧建议，需测试方案确认；游戏基线按主PRD20章，不擅自替换。

每条功能交付记录BKR、页面、接口能力、源码版本、环境、数据来源、BKA、输入、实际结果和证据。验收至少覆盖正常路径和越权/并发/未知/撤权等风险路径。文档校验与软件验收分开；本包只执行文档结构与链接检查。

## 11. 已确认默认方案与变更控制

已确认的默认方案及仍待资源/范围确认的事项见[差异与决策记录](../docs/decisions.html)。本次确认覆盖私牌专项、最小权限种子、V1模板种子、保留基线、真实充提后置、人工动作、旧数据、PostgreSQL工程默认及首期 Web 身份边界；不等于排期、供应商、实现、上线或验收已确认。玩家密码重置的身份核实和凭据交付渠道在确认前保持 fail-closed。以后任何身份、收费、归属、资金或角色权变更须走受控变更，并同步主PRD、附表、客户端披露、后台模板、验收与生效版本。

## 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完整摘录/规范化收录。与本包[统一基线](../docs/baseline.html)和[冲突裁定](../docs/decisions.html)配套执行；旧来源状态不代表软件完成。

# 模块与页面规格

版本V2.1-review。下列16个模块为导航组织建议；BKR目录是可追溯的功能粒度，不按页面数量计算实现完成率。逐页面的列表列、详情项、确认字段、数据来源、权限裁剪与导出边界见[展示字段契约](../docs/ops-fields.html)和[字段矩阵](../docs/ops-field-matrix.html)。

## 0. 通用页面契约

列表默认近7天、20条/页、最大100，支持清空筛选，查询、合计、明细、导出保持同范围及币种。时间按Asia/Shanghai显示，区间[start,end)。主键用稳定ID，不用昵称/房间展示手号代替。未知字段显示“未知”，零值正常显示0。

详情统一展示来源、最后更新时间、数据截止/完整性、对象状态及关联记录。写动作先展示对象/范围/影响/原因，再确认；提交中禁重复，超时显示结果确认中并查询原号。业务受理、实际生效及清算完成分别反馈。弹窗关闭、刷新、重新登录后仍可在有权限时查原操作。

拒绝原因须可理解且不泄露范围外对象是否存在。无数据、筛选无结果、权限不足、服务失败与记录过期分别设计。危险动作不放在行内一键执行；私牌授权不是普通详情开关。

## M01 运营总览与待办

- 页面：总览、待办列表、操作结果详情。BKR-047/048/051。
- 筛选：业务日期、资产、授权俱乐部/代理、玩法；资产必须分组。
- 指标：有效用户/手数、抽水、离座费、代理净应计、数据截止时间、待重算数量、未知操作、未清算资金异常、邀请待审及待处理工单。无权项不显示不返回；金额异常与客服待办不能混成一个“业务失败数”。
- 动作：下钻保持同筛选；按原操作号查询结果；进入有权限的处理页。总览不能直接加款或确认退款。
- 数据口径：有效用户按至少完成一手去重，手数去重hand_id；应计按业务日，调整保留实际记账日。跨币用户数不相加生成全局去重值。
- 转化：邀请/列表两条入口分别显示合格旅程、买入成功、转化、初始拒绝和后续失败原因；30分钟窗口尚未结束标暂计。
- 异常：未知结果进入待确认，不因等待时间自动失败；积压和差额仅触发核查，不能自动扣款。告警阈值待容量评估。

## M02 玩家管理与登录记录

- 页面：玩家列表、玩家详情（资料/归属历史/资产/会话/战绩/登录/处置）。BKR-006～010、056。
- 列：game_id、展示名、正常/禁用、俱乐部、直接代理、分币可用/冻结/托管、注册时间、最近登录。LOCAL登录名、TELEGRAM subject/username 和所有身份摘要均不进入普通列表、成员目录、导出或代理自助页。
- 筛选：精确game_id、展示名、俱乐部、代理、状态、注册/登录区间；登录日志按时间、结果、玩家查询；敏感IP检索另验权限。
- 认证摘要：显示身份来源 `LOCAL/TELEGRAM`、活动/解绑状态、本地凭据状态、锁定截止及最近认证时间；默认不显示 `provider_subject`、登录名、TG ID/username 或任何摘要原值。TG 接入前只显示“未接入”，不得伪装未绑定异常。
- 登录详情：每次登录的时间、认证来源、方法、设备摘要、IP、结果及安全可见失败原因。支持 `LOCAL_REGISTER/LOCAL_PASSWORD/SESSION_RESUME/DEVICE_TAKEOVER`，后续再启用 `TG_AUTH/TG_BIND`；缺注册时间不以最早日志或updated_at替代，客服默认无IP权限。
- 动作：查询、禁用/解禁、显式归属迁移；具备独立 BP-32 的超管可发起玩家本地密码重置。超管资金调整仅跳专用确认页，不开放余额编辑。不能编辑上级后台人员，这里管理的是统一玩家账号而非后台人员。
- 禁用：选择对象、原因、确认受影响房间；先封全部认证身份的新准入，再显示当前手托管/清算中，保留全下权益；结束后免离座费清算。禁用不解绑身份，解禁不恢复旧邀请、旧桌或旧会话。
- 玩家密码重置：只允许独立 BP-32；复核玩家、原因、当前凭据/锁定状态和会话影响，参数绑定TOTP后由权威认证服务生成一次性短时凭据并撤销全部玩家会话。后台不读取或代填新密码，不更改 `player_id/game_id`、钱包、归属、战绩或 TG 绑定；身份核实和凭据交付渠道未批准时入口保持关闭。
- 迁移：源/目标、目标代理、当前手、预计生效时点、旧桌临时权说明、原因；源目标双侧权限不足拒绝，不提供静默改club_id/agent_id。
- 玩家端：禁用后明确限制；本人账单/资金查询与合法清算不被没收。迁移后目录切换，原会话临时访问仅持续至退出。

## M03 俱乐部与归属

- 页面：俱乐部列表/详情、创建、授权、迁移记录。BKR-010～014。
- 列/筛选：ID、名称、默认标识、直接代理、正常/全部成员数、活动房间数、状态ACTIVE/FROZEN/ARCHIVED；按ID/名称/代理/状态过滤。
- 创建：仅超管，填写名称、头像/简介、一个直接代理或明确无代理、运营范围；不生成独立俱乐部余额。默认俱乐部是初始化对象，不由普通用户创建。
- 编辑：授权运营编辑名称/头像/简介；直接代理与运营范围变更走显式授权动作并保留历史，不能因可改名称推导出可改权限。
- 玩家开房授权：超管设置allow_player_create及可用已发布模板白名单；无权玩家入口隐藏且服务端拒绝。代理身份也不自动继承开房权。
- 冻结：确认影响的房间、邀请、申请、清算与待迁移；立即封新准入/补码/开房，当前手后关桌；待恢复桌保留关闭意图。列表分列俱乐部状态与关联清算进度。
- 解冻：仅恢复ACTIVE；不恢复旧邀请、申请、排期或关闭房间。需新签发/新开房。
- 归档：FROZEN、全部房间CLOSED、无未清算/待迁移、全部成员数0（含禁用）；阻断项逐项列出并可下钻。默认俱乐部禁止冻结/归档。
- 玩家端：只读俱乐部资料、本人钱包可用视图；冻结不能以空列表掩盖服务状态。

## M04 邀请与加入申请

- 页面：邀请列表/签发/详情、待审队列、申请详情。BKR-015～018。
- 邀请字段：invite_id、目标ROOM/CLUB与ID、策略、签发人、签发/到期/撤销时间、使用数、派生有效状态、相关申请数。token不进入日志/导出；短码及深链只向有签发/分享权限的人展示。
- 筛选：目标类型及ID、策略、签发人、有效/过期/撤销/目标不可用、时间；有效性由服务端判断。
- 签发：目标与策略独立组成四种组合。默认ROOM=24h免审、CLUB=永久审核。永久ROOM仍受房间关闭约束，不产生俱乐部归属。
- 撤销：超管可撤销任意业务邀请；运营只能撤销本人签发且目标仍在授权范围内的邀请，不因可查就可撤。撤销阻止新进入和未决批准，已在手正常清算。
- 申请详情：申请人、当前归属、目标、邀请码状态、账号状态、申请/审核时间、审核人、理由、审核结果、归属/房间访问实际生效状态及原操作号。
- 审核：批准瞬间复核目标、码、玩家和权限；已有正式归属必须显式迁移，不能批准即覆盖。审核通过与有在手待生效分列；拒绝后必须使用新邀请重新申请，不提供“解除拒绝”动作。
- 防并发：同申请多审核人竞争只形成一个终态，重复原号返回原结果；撤销/冻结先成功后批准应拒绝。
- 玩家端：展示本人待审/拒绝/失效/撤销/冻结与手后待生效，不暴露审核后台、其他申请人或内部备注。这里只负责业务邀请，不建设玩家注册码体系。

## M05 规则与费用模板

- 页面：模板列表、草稿编辑、版本对比、发布确认、版本详情。BKR-019～021、055。
- 列/筛选：模板ID/名称、版本、状态（草稿/已发布/退役）、玩法、币种、盲注、买入、费用版本、适用俱乐部/授权、发布时间和使用房间数。
- 编辑组：玩法/席数/时长；资产及SB/BB；买入min/max；Ante/抓头；自动开始人数；观战；延迟；VPIP；超时模式/时限；抽水与cap；离座费与豁免；玩家可编辑字段和范围。系统固定字段显示依据而非自由文本编辑器。
- 固定校验：长52张8席2/3h，短36张6席1h，均NLH；短牌Ante/抓头OFF；SB=BB/2、BB为0.02整数倍；金额两位精度；最低买入覆盖最大强制款。
- 七档候选保持原值；V1仅发布TEST资产、100–300、SB/BB=1/2、长牌8席2小时、Ante/抓头关闭的完整种子。其余六档保持DRAFT，不推断盲注、资产或授权范围，不阻塞V1。
- 权限：超管发布规则及费用版本；运营可按明确草稿权准备非费用配置、选择已发布费用；不得默许费用发布或调高比例。默认最小授权，未明确授予的动作保持拒绝。
- 发布：展示完整差异、适用资产/范围、生效只针对新房间；确认后不可覆盖。退役不强关既有桌；计划开放遇退役须取消。
- 费用预览：列CSV算例及离座例，显示rate/cap独立值、整数取分及全手封顶。预览不是已执行结算证明。
- 玩家端：只能从返回的已发布且已授权模板选择，规则、费用说明和账单共享同快照；不把61项配置全做可调开关。

## M06 房间、排期与异常恢复

- 页面：房间列表/详情、即时开房、单次排期、关闭确认、恢复事件。BKR-022～026。
- 列：room_id、俱乐部、玩法、资产、模板/费用版本、参局/占座数、计划/首手/截止时间、状态、累计有效手数、当前手、数据时点。
- 筛选：房间/俱乐部/代理、状态、玩法、时间、币种；详情关联公开桌面、规则快照、资金会话、手牌、费用、邀请和操作轨迹。
- 开房：仅范围内，以已发布版本+允许编辑值确认；提交未知不提前给房间号或签发入口；成功返回唯一room_id，不要求创建者买入。
- 单次排期：现在至未来7天，SCHEDULED仅预告、不可买入；开放时复核操作者/模板/俱乐部，转WAITING并开始默认24h邀请有效期；永久审核邀请可提前申请。无循环排班。
- 排期取消：仅未开放状态，重复幂等；与开放任务竞争由业务服务确认结果，不靠页面本地时间判断取消成功。
- 关闭：显示影响、当前手及资金会话，提交DRAINING，停新买入/补码/新手，当前手后免离座费清算；未生效补码退一次，不删除房间或清空座位绕账。
- 恢复：列最后提交hand_id/动作版本、结算提交是否可证、当前恢复路径、冻结金额、负责人、处置和更新时间。运营可登记/暂停/发起受控恢复请求，不能任意选择退款、改牌或置SETTLED。
- 处置规则：已提交只补通知；可信日志续原手；可信手前快照且确认未提交才VOID冲回；不确定则RECOVERY_REQUIRED冻结核查。
- 玩家端：恢复原手/原会话；停新入桌时说明，未完成清算不展示余额已返还。游戏故障暂停与单次操作UNKNOWN为不同事件。

## M07 战绩、会话与牌谱

- 页面：手牌查询、会话查询、玩家统计、事件回放。BKR-027/028/052/056。
- 筛选：玩家、room_id、hand_id、seat_session_id、玩法、资产、代理/俱乐部、手牌结算/会话结束区间、正常/作废/恢复中。
- 会话字段：买入、生效补码、本金、起止、有效手数、返还、离座费、最终/暂计净收益；手牌字段：贡献、未匹配返还、获池、抽水归因、单手净收益、规则版本。
- 统计：VPIP/PFR/W$SD分子分母、样本和bb/100，玩法/资产分开；不生成“综合实力分”，分母0为—。
- 回放：结构化事件播放/暂停、前后动作、分街、1×/2×；初始公开筹码、强制款、下注目标及增量、公共牌、主边池、费用及赢家一致。
- 隐私：默认仅公开范围；操作者本人作为玩家的私牌权不自动变成后台全牌权。Muck和未公开对手牌不能通过时间轴或接口泄露。
- 历史：LEGACY_SUMMARY标不可回放；未存动作不生成“录像”。保留期内新记录超过3000手仍可分页查询。
- 联动：牌谱→原结算→费用→协议快照→资金，不由回放重新执行结算。

## M08 资产、流水与充值来源

- 页面：资产视图、流水列表/详情、真实充值来源说明。BKR-029/030/033/056。
- 字段：玩家、资产、可用/冻结/托管/总额、transaction_id/business_id、类型/状态、整数金额、前后余额、原因、当时玩家与代理快照、操作者、业务/记账时间、关联手/会话/原单。
- 筛选：稳定ID、时间、币种、用户、代理/俱乐部范围、类型、状态；同筛选合计只按币种。
- 流水详情：借贷分录、请求/操作、规则与协议版本、原单/冲正链、冻结去向和业务终态。只读，不提供编辑余额/删除分录按钮。
- 充值：真实通道未接入，说明未接入并无真实订单；手工额度、补偿、输赢和买入各自分类，不把所有流入当充值/盈利。
- 异常：显示资金在途及来源，不把失败和未知混合，也不把账本对账差额当“应退款金额”。定位原单后进入超管纠错。
- 玩家端：与本人钱包/账单一致；底池不重复计资产，补偿不可直接加当前手。

## M09 超管调款与纠错

- 页面：调整申请、确认/二次授权、执行结果、原单纠错。BKR-031～033。
- 表单：玩家ID及确认身份、资产、类型TEST_GRANT/MANUAL_ADJUSTMENT/COMPENSATION、加/减、精确金额、原因、来源资格、原单（纠错必填）。用户改名不替换稳定ID。
- 确认：显示当前可用/冻结/托管、预期变化、额度上限、不可兑换/默认不可提、单号；再TOTP得到120秒单次参数绑定授权。
- 执行：服务端重验超管、最新权限、授权摘要、限额与可用余额，追加守恒分录；扣减不足拒绝，不取在手钱补足。
- 重试：同号同参数查原结果；同号异参数拒绝；超时保留UNKNOWN，刷新仍恢复原单。明确失败修正后才允许新号。
- 纠错：引用有效原单新增冲正/补偿；不重复冲同一已冲正事件，不删除历史或强行把差额置0。不能回滚已记账资金配合旧代码。
- 权限：运营、客服、代理一律禁止，包括“测试调整”；本期不新增财务角色或双人资金审批权。

## M10 收入与费用明细

- 页面：收入汇总、手牌抽水、会话离座费、备注历史。BKR-034/035。
- 字段/筛选：业务时间、币种、俱乐部/代理、room_id、hand_id/seat_session_id、费率/上限、计费基数、抽水、离座费、规则版本、豁免原因、备注及追加人。
- 抽水和离座费分别下钻，累计/所选期间明确区分；不把买入、补偿或代理应计当额外营业收入。
- 动作：查询、同范围导出、附加备注；备注只追加审计，不修改历史金额、归因或费率。
- 验算：BB2、5%、cap3、池40费2；池400费3；未翻牌0。提前盈利离座按已接受版本算，到期/运营处置免。历史费用始终引用当桌快照。

## M11 代理与等级协议

- 页面：代理列表/新增/详情、成员汇总、等级及协议版本。BKR-036～039。
- 字段：agent_id、名称、状态、注册时间、管理关系、所管俱乐部、授权用户数、等级/比例/版本/生效期、所选期间与累计基数/应计、测试支付标记和差额；充值统计标未接入，补偿另列。
- 动作：超管全局；运营在自己范围内新增代理、编辑名称/状态、创建本人等级版本、设0%–100%且不超授权上限。不能修改别的运营共享等级或增大自己上限。
- 关系：每俱乐部一个直接代理、一个代理可管多个俱乐部；管理层级不自动计佣。不把邀请签发者自动写成归属代理。
- 版本：手开始冻结协议；修改下一手生效、不回改历史。GENERAL明确0%；旧协议缺失CONFIG_ERROR，保留基数供修复而非默用0%。
- 停用：历史不删，未来归因平台直到显式有效绑定；不能删代理后导致历史账失去对象。

## M12 分成日账

- 页面：日账列表/详情、重算轨迹、TEST支付标记。BKR-039～041。
- 字段：代理、资产、业务日、数据截止、协议引用、贡献抽水基数、目标应计、已记净应计、版本调整、测试已标记金额、待处理差额、PENDING_RECALC/CONFIG_ERROR。
- 日账：按首次settled_at归日；每天00:10首结前日及脏日，漏跑恢复补跑；调整=新目标−已记净应计，历史版本保留。重放不改变原settled_at，不重复计事件。
- 算例：高精度0.019→应计0.01；迟到+0.009→目标0.02，补0.01；撤迟到→冲−0.01；再次撤不再冲。
- 测试标记：仅超管，仅TEST，仅写测试标记轨迹；不产生真实付款。应计冲至0.01、测试标记0.02时差额−0.01待核对，不自动追回玩家余额。
- 运营/代理只读；V1不建设人工佣金补结入口，继续由业务服务自动扫描并补结脏日，不因旧V1有“补结”按钮获得手动执行权限。

## M13 代理本人工作台

- 页面：我的协议、授权用户统计、我的佣金账。BKR-042。
- 认证：显式绑定后台账号并完成独立认证，身份标签不授予管理权。
- 字段：本人等级/比例、协议版本与生效期、授权俱乐部/用户汇总、日期/币种基数、应计、调整、测试标记/差额；期间与累计分开。
- 不可见：名下玩家完整钱包流水、IP、LOCAL/TELEGRAM身份标识、他人协议/佣金、未公开牌。不能改URL或导出获取扩大范围。
- 权限种子采用最小只读：仅本人协议、授权汇总和本人佣金；代理身份不自动获得运营角色，也不以“暂未配好”开放全局。

## M14 客服巡检、举报与专项审计

- 页面：巡检桌面、工单队列/详情、私牌申请/审批/访问轨迹。BKR-043～046。
- 工单字段：公开编号、内部案件号、本人提交记录关联、对象消息/手号、原因、状态OPEN/IN_REVIEW/RESOLVED/REJECTED、负责人、证据、内部轨迹、公开结论、最后更新时间。
- 受理：同举报人同对象24h合并追加；不同举报人保留各自私有记录，可关联内部案件，不能相互公开。客服仅分配或授权范围可读。
- 巡检：公开桌面、客服身份提示、不占座、不计人数、不发手牌、不代打。线索只建工单，不自动判作弊或扣钱。
- 禁言：10分钟/24h；永久仅运营/超管。禁言不妨碍举报，不冻结钱、不改变牌局结果。解除禁言如建设需动作权限及审计，不能隐式扩大处罚权。
- 结案：公开结论1–500字必填，内部处置另存；结论不得含私牌、IP、他人身份或资金详情。处置实际结果单列，禁用已提交不等于已清算。
- 玩家反馈：结案公开状态与结论、未读标记；补充说明使已结案重新IN_REVIEW；每账号每分钟3次提交/追加合计。首期通过站内查询/刷新获取，不依赖TG主动推送。
- 私牌专项：已结束手+有效工单+用途+指定玩家/手牌+专项角色权；客服或运营仅能在工单范围内申请，申请人与审批人不同，由具备专项审批权的超管审批。批准后30分钟有效；每次实际访问另需120秒参数绑定TOTP单次授权，并复核会话、权限、工单和对象范围。会话失效、撤权或工单失效时授权立即失效；记录每次申请、审批和访问，未授权请求不返回密文或隐藏JSON。

## M15 后台账号、安全与授权

- 页面：账号列表/创建、激活、角色范围、本人安全、恢复/重置记录。BKR-001～006。
- 账号字段：后台ID、展示名、状态INVITED/ACTIVE/DISABLED/RESET_PENDING、角色/动作、俱乐部/代理范围、佣金上限、认证器绑定状态、最后完整认证、授权版本；不显示密码、密钥、恢复码摘要。
- 创建：超管二次授权，24h单次激活凭据仅显示一次；绑定人员核实渠道交付，不依赖玩家 LOCAL 或 TELEGRAM 身份。首超管本地受控初始化，禁止公开注册提权。
- 激活：设12–128字符密码、绑定6位30秒TOTP（前后1步）、首码验证、10个恢复码仅显示一次；未完成无业务会话。
- 会话：密码+TOTP完整认证；连续5次失败锁15分钟，IP30次/分钟；空闲15分钟/绝对8小时，后台轮询不续期。退出当前会话；改密、停用、重置、角色/范围变更撤销全部会话与待执行授权。
- 改密：旧密码+独立验证；5次错误锁改密15分钟，成功强制重登；后台人员密码与玩家 `local_credential` 完全隔离。
- 恢复：正确密码+一次恢复码进入15分钟只重绑会话；人工重置须另一超管身份核实，唯一超管走受控本地恢复。全部留审计，不公开绕过接口。
- 授权：超管明确动作/资源/上限，不能给自己提权或将平台代理身份等同超管。敏感授权操作号与参数绑定120秒单次，失败计数与登录/改密分别管理。

## M16 审计与导出

- 页面：审计查询、原操作详情、导出任务/下载。BKR-049～054。
- 审计字段：operator_id、角色/范围快照、对象、动作、脱敏前后值、原因、请求/操作/原业务号、提交/生效时间、结果/错误；敏感访问也记录。普通操作者至少能查本人仍在范围的操作，不默认获得全局日志。
- 只读：不提供删除、修改或掩盖历史记录能力；安全拒绝也记录必要事件，不收集密码/TOTP/token全文。
- 导出：按同查询范围/字段/资产和时间区间生成；最大31天。页面显示生成中、可下载、失败、过期、因撤权失效。建议任务式导出，下载入口不是静态公开URL。
- 安全：生成中撤权任务失败；下载须原账号/会话且当前权限通过；15分钟到期、退出即拒绝。导出审计保留条件、行数/数据时点和结果，不向外自动发送。
- 数据格式：文本列做CSV公式注入防护，金额保留精确值/币种/精度，不把ID转科学计数法。没有导出列权就不在文件内生成隐藏列。
- 交付证据：关联BKR/BKA、版本/环境/数据来源、实际结果；模拟显著标识，真实服务不可用不转为真实空集，更不能记验收通过。


---

> 本文为IB-1.1完整摘录/规范化收录。与本包[统一基线](../docs/baseline.html)和[冲突裁定](../docs/decisions.html)配套执行；旧来源状态不代表软件完成。

# 展示字段契约

版本V2.1-review。本清单把[模块与页面规格](../docs/ops-modules.html)中的字段摘要，结合《数据库实施/PostgreSQL数据字典》V1.4-review与已落地安全读视图，展开为设计、API、研发和测试可共同评审的页面字段契约。完整字段矩阵见[fields.csv](../docs/ops-field-matrix.html)。它描述“应该展示什么、从哪里来、如何裁剪”，不证明接口、查询、UI或导出已经实现。

## 1. 使用方式

- `页面/功能 + 区域`是界面字段集边界；“展示字段（按顺序）”是默认桌面端顺序，设计可以调整布局但不得静默删改业务口径。
- 中括号内为建议API字段名或权威数据库字段名；中文为运营界面标签。聚合/派生字段必须由服务端或受控读模型计算，不能由前端拼接后作为资金或状态事实。
- `主要来源`写“已建安全视图”时，指V013迁移已有对象；写“建议读模型”时，仅代表数据字典建议，仍需新增迁移/API实现与测试。
- 每个字段集关联至少一个BKR需求；构建脚本校验16模块和全部59项BKR均被字段清单覆盖。

## 2. 全局展示规则

| 主题 | 统一规则 |
| --- | --- |
| 稳定标识 | 玩家、房间、手牌、会话、操作、流水均显示业务稳定ID；数据库UUID只在排错权限下显示，不以昵称或展示手号替代主键。 |
| 时间 | 默认以Asia/Shanghai显示到秒，并保留原始时区语义；业务日期、提交时间、生效时间、完成时间分列，不把`updated_at`冒充业务时间。 |
| 金额 | 显示“金额 + 资产代码”，按`asset.precision`格式化；API传整数最小单位。跨币种禁止求和，零值显示0。 |
| 比例 | 费率、佣金率按百分比展示并保留足够精度；实际入账金额仍以整数最小单位和权威结算为准。 |
| 状态 | 同时展示业务状态、请求状态和实际生效状态；UNKNOWN、PENDING_EFFECT、SETTLING不得折叠成失败或成功。 |
| 空值 | 数据确实为空显示“—”；历史缺失或不可证明显示“未知”；无权字段不下发、不占位，不用“***”暗示对象存在。 |
| 快照 | 历史昵称、代理、协议、规则和费率优先显示交易/手牌发生时快照，并可在有权限时另链当前对象。 |
| 数据新鲜度 | 汇总、投影、列表详情统一显示`data_cutoff_at`/`projected_at`与完整性状态；服务失败不得伪装成真实空集。 |
| 分页与合计 | 默认近7天、20条/页、最大100；总数、合计、详情和导出复用同一筛选、范围和数据时点。 |
| 敏感信息 | LOCAL/TELEGRAM认证身份、IP、设备、私牌、内部工单、全局审计分别按动作权限裁剪；登录名、provider subject、密码/哈希、令牌、TOTP密钥、恢复码、原始initData和摘要密文永不展示或导出。 |
| 导出 | 仅导出当前字段权限内列；最大31天、默认7天；文本防CSV公式注入，ID按文本，金额不丢精度，下载时再次校验会话和范围。 |

## 3. 数据来源状态

数据库实施基线已建立`v_current_club_membership`、`v_user_wallet_balance`、`v_ledger_transaction_display`、`v_commission_current_statement`、`v_operation_pending_review`、`v_recovery_case_funds`和`v_player_session_result`七个安全读视图。

数据字典中提出但V013尚未建立的`v_ops_daily_metrics`、`v_room_public_summary`、`v_player_stat_period`、`v_hand_replay_public`、`v_revenue_detail`等，在fields.csv中标为“建议读模型”。实现时有两种可接受路径：新增受权限约束的数据库视图/物化视图，或由服务层查询并以同等口径、范围和审计返回。产品要求的是口径一致与最小披露，不预先锁死查询技术。

## 4. 评审与验收门槛

1. 产品确认标签、顺序、空值与状态含义；UI确认列表密度、详情分组和危险动作确认层级。
2. 后端为每个字段给出API类型、来源、查询计划和权限策略；对“建议读模型”明确新增迁移或服务查询方案。
3. 安全评审验证无权字段在响应层被裁剪，而不是只在前端隐藏；导出、详情、下钻和合计使用同一范围。
4. 测试至少覆盖真实零值、历史未知、跨币种、投影延迟、撤权、越权ID、CSV公式注入和导出下载复核。
5. 字段清单中的“可导出”仅代表产品允许进入导出设计，实际开放仍依赖BKR-049、权限种子、查询性能和验收证据。


---

> 本文为IB-1.1完整摘录/规范化收录。与本包[统一基线](../docs/baseline.html)和[冲突裁定](../docs/decisions.html)配套执行；旧来源状态不代表软件完成。

# 关键业务流程与状态验收

V2.1-review。箭头说明业务顺序，不代表后台可以跳过业务服务直接修改状态。枚举未在主PRD明确的页面展示值仅是建议映射，不作为已批准API枚举。

[查看12张业务流程图](../docs/ops-flows.html)：端间职责泳道＋本页F01～F11；图是概览，下方状态表保留完整规则。图中线交叉处若无节点，不代表路径合并，以箭头起止和条件标签为准。

<a id="f01"></a>

## F01 后台人员开通、恢复与撤权

超管确认人员身份和最小范围 → 参数确认+TOTP → 建INVITED账号 → 显示一次24h凭据 → 当事人设置密码/绑定认证器/验证 → ACTIVE → 密码+TOTP登录。

| 状态/事件 | 可执行 | 不可执行及异常 |
| --- | --- | --- |
| INVITED | 有效凭据激活 | 不能查业务；过期/重发废旧凭据 |
| ACTIVE | 当前范围业务 | 仍需动作/范围/状态授权，不能凭角色名越权 |
| 5次登录失败 | 等15分钟后重试 | 不泄露账号是否存在；IP每分钟30次 |
| 受限恢复会话 | 正确密码+单次恢复码，15分钟内重绑 | 不加款、不看私牌、不改权 |
| RESET_PENDING | 单次24h重置邀请 | 验证新认证器前无业务会话；禁止自审人工重置 |
| 改密/停用/重置/角色范围变更 | 记录原因及版本 | 全部旧会话和未执行授权失效，不等缓存过期 |

首超管通过一次性本地受控命令初始化；唯一超管失联使用记录人员/工单的本地恢复，不设计公开绕过网页。

角色与范围授予、撤销由数据库受限函数执行：同一对象的有效区间不得重叠；管理操作必须复合绑定120秒参数授权和operation；变更、`authorization_version`递增、旧会话及未消费授权失效在同一事务完成。除版本化BOOTSTRAP种子外，应用账号不得直接写授权表。

<a id="f02"></a>

## F02 业务邀请签发与审核

有权限人员选择ROOM/CLUB与目标 → 选择24h免审/永久审核 → 服务端验目标与范围 → 签发普通 HTTPS 链接 → 玩家完成首期 Web 认证后打开 → 免审继续准入或创建申请 → 后台审核复核 → 明确访问权/归属结果 → 玩家查询本人状态。未来 TG 深链复用相同业务邀请 token，不改变审核、归属或资金语义。

| 目标×策略 | 正常路径 | 额外限制 |
| --- | --- | --- |
| ROOM×24h免审 | 签发起24h内目标房间准入 | 不改俱乐部/代理；房间关闭立即不可用 |
| ROOM×永久审核 | 逐申请审核后访问目标房间 | 永久不等于房间永不关闭；计划桌未开放不买入 |
| CLUB×24h免审 | 免人工审核的俱乐部准入 | 现有正式归属仍不能被链接静默覆盖，须显式迁移 |
| CLUB×永久审核 | 逐申请审核后按归属流程 | 审核通过与迁移生效分开 |

批准瞬间校验邀请、目标、玩家和权限；撤销/冻结/关闭后不可批准。撤销不撤回已完成合法结算；已入桌继续按状态清算。申请提交与审核使用不同request_id和operation；重复申请只幂等，不新建多个待审；同号异参数拒绝。审核、撤回、撤销联动、冻结、失效和生效均追加状态事件，不覆盖申请操作。拒绝后必须使用新邀请重新申请，不提供解除拒绝动作。

签发、撤销和审核是独立能力；“允许收到/分享链接”不等于可生成新邀请，更不传播签发人的后台权限。

<a id="f03"></a>

## F03 显式归属迁移

范围内玩家详情 → 选源/目标俱乐部与目标直接代理 → 展示当前手、旧会话及归因影响 → 双侧权限/ACTIVE目标校验 → 同request_id提交 → 无在手立即生效，或有在手等待 → 手结算/作废后、下一手名单前复核 → 生效或取消保留旧归属。

| 情形 | 预期 |
| --- | --- |
| 只有源或目标单侧范围 | 拒绝，无归属变更 |
| 已有另一待迁移 | MEMBERSHIP_CONFLICT，不覆盖原迁移 |
| 同ID同参数 | 返回原迁移；异参数拒绝 |
| 等待中撤权/目标冻结 | 生效复核取消，保留旧归属和取消原因 |
| 生效后仍有旧桌资金会话 | 仅旧桌该会话临时权，允许受约束参局/补码/恢复；旧目录立即失权 |
| 退出旧会话后再入 | 不延续临时权，重新验资格 |
| 当前手与下一手佣金 | 当前手沿旧协议；下一手按新归属快照，不改历史 |

后台把“已审核”“待归属生效”“已生效/已取消”分列，不在受理时告诉玩家已加入。

归属迁移的一次operation只允许生成一条目标归属记录；直接代理变更使用不重叠有效区间和唯一当前关系，历史、当前字段及审计在同一数据库事务更新。

<a id="f04"></a>

## F04 俱乐部冻结、解冻与归档

确认俱乐部及影响 → 校验非默认俱乐部/动作范围 → 冻结事务封新准入与开房/买入/补码 → 撤有效邀请、未决申请CANCELLED → 逐桌清算 → 状态持续可查。

| 冻结前房间 | 冻结后 |
| --- | --- |
| SCHEDULED | 取消计划，CLOSED，不再到时开放 |
| WAITING | 取消倒计时、返托管/冻结，清算后CLOSED |
| RUNNING有在手 | DRAINING，本手完成后免离座费清算 |
| RUNNING无在手 | 停下一手，清算后CLOSED |
| DRAINING/PAUSED_RECOVERY | 保存关闭意图；不确定资金保持核查，不强行CLOSED |
| CLOSED | 历史保留，不重开 |

解冻仅FROZEN→ACTIVE，不复活邀请/申请/房间/排期。归档前校验FROZEN、全部CLOSED、无未清算/待迁移、全部成员0；不达标展示阻断项，不批量静默迁出。默认俱乐部禁止冻结/归档；保底对象故障保留本人账单和旧桌恢复入口，停新入桌，不自动造俱乐部/余额。

<a id="f05"></a>

## F05 模板发布、开房与单次排期

填写完整草稿 → 字段/费用/授权校验 → 有权限者发布不可变版本 → 超管配置俱乐部开房权及模板白名单 → 运营或授权玩家选版本 → 只改允许字段 → 确认完整费用 → 提交 → 成功才显示room_id和邀请。

| 状态 | 规则 |
| --- | --- |
| 草稿 | 缺盲注/必需字段不能发布，不出现在玩家选项 |
| 已发布 | 版本不可覆盖；新房间引用独立冻结快照；相同摘要不代表同一房间 |
| 退役 | 不供新开房，不影响已存在房间快照 |
| 创建SUBMITTING/UNKNOWN | 禁重复提交；UNKNOWN只查原号，不提前开邀请 |
| 创建FAILED | 无房间/规则冻结/费用，保留合法草稿；修正后新号 |
| 创建SUCCEEDED | 同号返回同一room_id、版本、结果 |
| SCHEDULED | 未来最多7天；不可买入，永久审核邀请可提前申请 |
| 到计划时间 | 再验人/范围/模板/俱乐部；成功转WAITING并启动默认24h邀请有效期；失效取消留因 |

运营关桌或房间到期进入DRAINING，停新买入/补码/下一手；当前手正常结算、未生效补码解冻、免离座费清算。发布新模板不能改WAITING桌旧版本，错桌须受控关闭后重建。

<a id="f06"></a>

## F06 超管调整、UNKNOWN与纠错

查用户及原单 → 确认玩家/币种/金额/方向/原因/来源 → TOTP产生绑定参数的单次120秒授权 → 业务方再次校验超管/限额/余额 → 追加分录与操作结果 → 返回POSTED → 玩家账单/后台审计可查。

| 请求/领域状态 | 页面含义 | 允许动作 |
| --- | --- | --- |
| SUBMITTING | 本次尚无确认 | 禁重复；保留原操作号 |
| 已受理/处理中 | 业务方接收，未证明完成 | 查原号，展示等待原因 |
| UNKNOWN | 网络断开/超时，不能确定 | 查原号；不退款、不扣第二次、不换新号 |
| FAILED | 权威终态失败 | 原失败及资金结果可查；修正后另起新号 |
| SUCCEEDED | 权威确认完成 | 展示原业务号、金额、前后余额及生效时间 |
| Ledger PENDING/POSTED/REVERSED/FAILED | 账本展示状态 | 与请求状态分列；数据库仅存PENDING/POSTED/FAILED，REVERSED由有效完整冲正交易派生并展示冲正交易ID/时间 |

改金额/对象/范围须重新授权。同号异参数拒绝；重复同号只查原结果。扣减只动可用且不负。纠错先确定原单状态及有效性，追加引用原单的新分录，重复原事件冲正拒绝。无法确认COMMIT时不能通过“超时新补偿单”试探执行。

<a id="f07"></a>

## F07 代理计提、迟到与TEST标记

开手冻结玩家代理/协议 → 正常结算形成逐池抽水归因 → 事件按首次settled_at归业务日 → 日汇总高精度 → 00:10生成前日账并补脏日 → 目标应计减已记净额形成新版本调整 → 查询本人/范围日账。

| 场景 | 预期 |
| --- | --- |
| GENERAL有效协议0% | 明确0%，不当配置缺失 |
| 旧协议缺失/损坏 | CONFIG_ERROR保留基数；不阻断玩家合法结算，不默用0 |
| 23:59开手、00:20首次结算 | 归次日，不按开手日期 |
| 原结算通知重放 | 原settled_at不改、同事件只计一次 |
| 首结0.019，再迟到0.009 | 首记0.01，后只补0.01 |
| 撤迟到/重复撤 | 首次冲−0.01，重复不再冲 |
| 日结漏跑 | 恢复补跑，不跳日，不按新日期挪旧业务 |
| 应计0.01，TEST标记0.02 | 差额−0.01待人工核对，不扣玩家钱、不称真实追回 |

只做单层分成，离座费不入分成；TEST标记是记录能力，不是实际付款。V1不提供人工“立即补结”入口，业务服务继续按日自动扫描并补结脏日；后台查账权不等同执行日结权。

日账当前版本不保存可写 `is_current`，按代理+资产+业务日的最高 `version_no` 查询；TEST标记的operation唯一，重复原号只返回首次标记结果。

<a id="f08"></a>

## F08 举报、巡检与私牌专项

玩家举报 → 同人同对象24h合并/不同人分开记录 → 后台授权受理/分配 → 查询公开证据、巡检或处罚 → 如必要申请结束手私牌专项 → 独立审批 → 限定访问并审计 → 记录实际处置 → 填内部记录+公开结论 → RESOLVED/REJECTED → 玩家本人收到状态和结论。

OPEN→IN_REVIEW→RESOLVED/REJECTED；已结案本人补充说明后重回IN_REVIEW。公开结论必填1–500字，不能包含私牌、IP或其他举报人。禁言不停止举报；设备/IP线索不自动等于作弊证据。

专项授权申请至少指定ticket_id、hand_id、player集合、用途；客服或运营仅能按有效工单范围申请，申请人与审批人必须不同，由具备专项审批权的超管审批，普通超管身份不自动获得该权。审批决定本身复合绑定120秒参数授权和独立operation并单次消费；批准后30分钟有效。每次访问还须取得另一份绑定本次读取参数的120秒TOTP单次授权，并验证已结束手、工单、范围、会话及操作者权限。会话失效、撤权或工单失效时立即失效，每次审批和实际访问均写不可变审计。

<a id="f09"></a>

## F09 故障与资金恢复

发现故障 → 停新准入/暂停全桌计时 → 核对持久结算事实 → 选可信恢复路径 → 保留原hand_id/settlement_id → 对账 → 恢复或手后清算。

| 可证明的事实 | 唯一允许的业务路径 |
| --- | --- |
| 结算已提交 | 原结果/原settlement_id，只补通知，不再派奖 |
| 未提交、日志可信可续 | 同牌序同手继续，不重新洗牌 |
| 未提交、不能续但手前快照可信 | VOID，去重退实付贡献/撤本手费用和计提，保留前手与独立补码 |
| 不能判断提交或缺可信依据 | RECOVERY_REQUIRED，冻结核查，不按超时自动退款 |

自然到期与故障相遇不再开下一手，恢复后免离座费清算。测试/受邀试用运维目标沿产品20.2：可运行后60秒恢复否则升级；告警5分钟确认、30分钟给处置及更新时间。没有真实值班人员不标有人值守，不把目标当正式SLA。

恢复案件不保存无资产的权威冻结总额；每个受影响玩家、资产、账户/原交易/资金会话分别形成资金明细，冲正、释放或继续核查逐项留痕，页面合计始终按资产分组。

<a id="f10"></a>

## F10 导出与撤权

授权查询 → 确认原筛选/列/币种/区间≤31天 → 建任务 → 生成中持续范围校验 → 文件可下载 → 原账号/原会话且当前权限通过 → 15分钟内下载 → 过期拒绝并保留审计。

生成中撤权任务失败；退出/过期/权限变化即使URL未满15分钟也拒绝。重生成按当前权限重新请求，不沿旧宽范围。导出内容不含无权字段/原始token，文本列防公式注入；下载不自动外发。

<a id="f11"></a>

## F11 玩家认证身份与本地密码重置

范围内玩家详情 → 读取脱敏认证摘要 → 具备独立 BP-32 的超管选择 LOCAL 身份、填写原因 → 参数绑定 TOTP → 权威认证服务复核玩家/身份/状态 → 撤销全部玩家操控会话并生成一次性短时重置凭据 → 通过已批准的身份核实和交付渠道送达 → 玩家设置新密码 → 原凭据失效并记录结果。

| 状态/条件 | 页面行为 | 安全边界 |
| --- | --- | --- |
| LOCAL 正常 | 显示来源、凭据状态和最近认证时间 | 不显示登录名、provider subject、密码哈希或摘要原值 |
| 连续5次失败锁定 | 显示锁定中及截止时间 | 不能显示错误密码内容，不允许后台直接清零绕过；重置走独立操作 |
| 仅 TELEGRAM 或 TG 未接入 | 不显示可执行 LOCAL 重置 | 不静默创建 LOCAL 身份，不把 TG 绑定改成第二个玩家 |
| 已有未过期重置 | 同号同参返回原结果；新建前使旧凭据失效 | 一名玩家最多一个活动重置凭据 |
| 身份核实/交付渠道未批准 | 入口关闭并说明发布前置条件 | 不在普通日志、工单正文或聊天中发送重置秘密 |
| 玩家完成重置 | 新口令生效、失败计数和锁定状态按认证规则收口 | 撤销旧会话；不改 `player_id/game_id`、钱包、归属、战绩或 TG 绑定 |

BP-32 与后台人员恢复 BP-02、玩家禁用 BP-06、查看登录 IP BP-05 分开。后台操作者不能代设新密码、读取旧密码或导出口令资料；操作只保存重置对象、原因、操作者、参数摘要、凭据有效期、会话撤销数和结果。重置凭据默认30分钟、单次使用；该默认在认证服务实现前须与身份核实/交付渠道一并确认，未确认时保持 fail-closed。

## 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完整摘录/规范化收录。与本包[统一基线](../docs/baseline.html)和[冲突裁定](../docs/decisions.html)配套执行；旧来源状态不代表软件完成。

# 风暴扑克技术架构与实施方案

> 版本：V1.1 评审稿  
> 日期：2026-10-21  
> 适用范围：首期 Web 玩家端、Node.js 游戏业务服务、PostgreSQL、RuoYi-Vue-Plus 运营后台，以及后续 Telegram Mini App 适配  
> 文档状态：供架构、研发、测试、运维和安全人员共同评审；不表示功能已经实现或通过验收。

## 0. 阅读指南

本报告回答五个问题：

1. 风暴扑克为什么采用 Node.js 模块化单体，而不是首期微服务。
2. 首期 Web 玩家端、后续 Telegram 适配、游戏业务服务、PostgreSQL 和若依运营后台如何分工。
3. 资金流水、牌局状态、运营操作分别由谁写入和负责。
4. 系统如何处理实时通信、并发操作、幂等、断线恢复和发布回滚。
5. 团队按照什么顺序实施，并以什么标准判定可以进入下一阶段。

评审人员应优先阅读“决策摘要”“数据所有权”“关键业务链路”“部署方案”“实施路线”和“评审清单”。

## 1. 决策摘要

### 1.1 推荐结论

采用“两套应用、一个核心业务事实源”的架构：

- **玩家业务系统**：首期浏览器 Web 客户端 + Node.js/TypeScript 模块化单体；后续 Telegram Mini App 通过适配层复用同一客户端和业务接口。
- **运营管理系统**：现有若依 Vue 3 / Java 工程作为运营壳，承载页面、请求转发和文件交付；后台认证及权限事实统一在 Node 与 poker.admin_*。
- **核心业务事实源**：PostgreSQL，由 Node 游戏业务服务拥有玩家、俱乐部、房间、牌局、钱包、账本和结算数据的写入权。
- **实时通信**：HTTPS 处理登录、查询和业务提交；WSS 处理牌桌命令、状态推送、心跳和恢复。
- **一致性策略**：资金与牌局关键状态在同一 PostgreSQL 本地事务内提交；提交后再广播。
- **首期部署**：单区域、单个牌桌写入实例或受控单写模式；不在没有房间所有权协议时做多实例滚动写入。
- **身份入口**：首期使用 `LOCAL` 注册登录；稳定玩家、认证身份、凭据和会话分离，后续绑定 `TELEGRAM` 时不新建第二套钱包、归属或战绩。
- **外部依赖**：首期 Web 开发和验收不依赖 Telegram Bot、`initData` 或 Mini App 配置。

一句话定义：

> Node 是业务执行中枢和资金事实源；若依是运营工作台，不是第二套游戏业务核心。

### 1.2 首期明确不采用

- 不把身份、钱包、俱乐部、牌桌拆成独立微服务。
- 不使用 Serverless 承载长连接和牌桌状态。
- 不让客户端计算权威余额、合法动作或最终结算。
- 不让若依直接更新钱包、账本、牌局终态或运行中牌桌状态。
- 不把 Redis 当作余额、账本或牌局事实的唯一存储。
- 不在首期引入 Kafka 等消息平台；先采用数据库 Outbox 和后台工作进程。
- 不把现有原型通过测试等同于生产业务已经完成。
- 不把 Telegram Bot、Mini App、深链或宿主 SDK 作为首期 Web 闭环的阻断依赖。

### 1.3 选型对比

| 方案 | 优点 | 代价与风险 | 结论 |
| --- | --- | --- | --- |
| Node 模块化单体 + PostgreSQL + 若依运营壳层 | 复用现有引擎和若依能力；关键业务可使用单库事务；部署和排障相对简单 | 需要认真建设模块边界和管理 API | **推荐** |
| 全部使用 Spring Boot 重写 | 语言和后台技术栈统一 | 现有 Node 引擎复用率下降，实时牌桌重写和回归风险更高 | 不作为首选 |
| 身份、钱包、牌桌等首期微服务 | 可独立部署和扩容 | 引入跨服务资金一致性、网络失败、链路追踪和运维复杂度 | 当前不采用 |
| Node 与若依共同直接写核心业务表 | 初期 CRUD 看似更快 | 规则重复、越权和数据竞争难以控制，事故后难以确定责任方 | 禁止 |

## 2. 背景、范围与假设

### 2.1 本期业务范围

本方案覆盖：

- 普通 Web 注册登录、统一玩家账号、本地凭据、服务端会话和新设备接管。
- 认证提供者适配层及后续 Telegram 登录、绑定、冲突拒绝和深链转换能力。
- 长牌/短牌德州扑克房间、买入、补码、行动、结算和离桌。
- 俱乐部、成员、邀请、房间模板及访问资格。
- 钱包可用余额、冻结、桌内托管、平台费用和代理应计。
- 牌谱、战绩、聊天、举报、运营查询和审计。
- 若依后台中的用户、俱乐部、房间、代理、资金、配置、工单和导出。

本期不包含真实充值提现、保险购买、Limit、锦标赛、链上存证和真实佣金支付。未来接入真实资金时，必须单独完成牌照、KYC/AML、支付安全、地区限制和合规评审，不能仅视为增加一个支付接口。

### 2.2 容量与体验基线

当前容量评审基线为：

- 500 个并发连接。
- 50 张同时运行牌桌，每桌最多 8 席。
- 服务端动作处理 P95 不高于 200ms，包含持久化提交和响应生成。
- 同区域端到端往返 P95 不高于 800ms。
- 首屏 P95 不高于 3 秒。
- 断线恢复 P95 不高于 5 秒。
- 非预期错误率不高于 0.1%。
- 重复扣款、重复结算、越权和未公开牌泄露为 0。

这些指标必须在固定资源、固定数据种子和明确并发模型下验证。连接数达标不代表牌局吞吐达标。

### 2.3 AI 驱动实施约束

项目不设置固定人类负责人，也不依据虚构人员配置承诺工期。实施以可独立验证的任务节点推进，每个节点至少记录需求或架构决策、输入依赖、产物路径、校验命令、实际结果、证据和阻断状态。

- AI 可以生成代码、迁移、配置、测试和文档，但资金、权限、私牌和恢复能力必须经过自动门禁与可复现证据验证。
- 任务可以并行，但同一数据或接口契约只能有一个当前权威版本；冲突先回到 ADR、数据字典和产品基线裁定。
- 域名、服务器、证书、密钥、正式协议和未来 Bot 凭据属于外部输入；未提供时允许隔离模拟，但不得写成真实接入完成。
- 未配置真实告警渠道、值班和发布授权时，不得宣称生产有人值守或已批准上线。
- 不通过删除账本、幂等、恢复、安全和审计门槛来制造进度。

## 3. 系统上下文与容器架构

### 3.1 系统上下文

```text
玩家 ──浏览器──> Web 玩家端 ─────────────HTTPS/WSS──────┐
后续 ──Telegram──> Mini App 宿主适配 ───HTTPS/WSS──────┤
运营人员 ──浏览器──> 若依运营后台 ───────管理API────────┤
                                                        │
                                                        ▼
                                                   游戏业务服务
                                                        │
                                                        ▼
                                                   PostgreSQL
                                                        ├─ 备份/恢复
                                                        └─ 报表投影
```

文字说明：首期玩家通过普通浏览器使用玩家业务；后续 Telegram Mini App 只增加宿主能力和认证提供者，不复制业务规则或玩家资产。运营人员只通过若依后台执行授权范围内的管理操作。若依把业务命令提交给 Node 管理 API，Node 在校验权限、幂等和当前状态后修改核心业务数据。

### 3.2 容器职责

| 容器 | 技术建议 | 主要职责 | 不承担的职责 |
| --- | --- | --- | --- |
| Web 玩家端 | Vue 3、TypeScript、Vite、Pinia | 注册登录、页面交互、请求状态、断线恢复展示、响应式浏览器适配 | 不计算权威结算，不保存密码或可信身份事实 |
| Telegram 宿主适配（后续） | Telegram WebApp SDK + 客户端适配接口 | `initData` 获取、主题、安全区、返回按钮、深链和分享 | 不复制账号、钱包、俱乐部或牌桌逻辑 |
| 游戏业务服务 | Node.js 22 LTS、TypeScript | 认证提供者、玩家、俱乐部、房间、牌桌、账本、结算、管理 API | 不把内存视为唯一事实 |
| 实时接入 | `ws` 或兼容封装 | WSS 握手、命令、推送、心跳、重连 | 不复制另一套业务规则 |
| 后台工作进程 | 同一 Node 代码库独立进程 | Outbox、统计、导出、过期任务、通知重试 | 不拥有运行中牌桌写入权 |
| 若依运营后台 | Vue 3 + Spring Boot | 认证页面、流程、查询、导出入口；认证与 RBAC 委托 Node | 不直接写钱包和牌局核心表 |
| PostgreSQL | 生产支持版本 | 业务事实、事务、约束、审计和恢复依据 | 不承担 WebSocket 在线连接管理 |
| Redis（可选） | 生产支持版本 | 限流、在线状态、短时缓存、路由辅助 | 不保存唯一余额或唯一牌局状态 |
| 对象存储 | S3 兼容服务 | 导出文件、语音及受控静态资源 | 不保存可公开访问的敏感牌谱 |

IB-1.1采用Node.js 22系列兼容基线，工程建立时锁定补丁版本并运行依赖/安全兼容检查；旧Node 18只作历史参考。

## 4. Node.js 模块化单体设计

### 4.1 推荐代码结构

```text
apps/
  game-api/             HTTP、WSS、玩家业务和管理API入口
  worker/               Outbox、统计、导出和计划任务
packages/
  auth/                  LOCAL凭据、认证提供者、会话、设备代际、后续TG适配
  player/                玩家资料、状态、偏好
  club/                  俱乐部、成员、邀请、归属
  room/                  房间、模板、准入、座位
  table/                 每桌命令队列、计时、恢复
  poker-engine/          确定性规则、牌型、边池、结算输入
  realtime/              WS协议、连接、投影、广播
  wallet/                可用、冻结、托管账户
  ledger/                平衡分录、幂等、冲正
  settlement/            手牌、费用、离座和代理计提
  history/               牌谱、战绩、统计口径
  admin-api/             若依调用的受控管理用例
  infrastructure/        PostgreSQL、日志、Outbox、配置
```

目录名称可以调整，但依赖方向必须保持：接入层调用应用用例，应用用例协调领域模块，领域模块通过抽象访问基础设施。`poker-engine` 不得直接连接数据库或修改钱包。

### 4.2 模块职责与依赖

| 模块 | 拥有的数据/规则 | 允许依赖 | 禁止行为 |
| --- | --- | --- | --- |
| auth | 统一认证身份、LOCAL凭据、应用会话、设备代际 | player、identity/credential/session repository | 让登录名、昵称或TG字段成为业务主键 |
| club | 俱乐部、成员、邀请、归属迁移 | auth、player | 直接调整余额 |
| room | 房间、规则版本、座位和准入 | club、auth | 绕过账本完成买入 |
| table | 手牌状态机、命令序号、计时器 | poker-engine、room、settlement | 并发修改同一桌 |
| poker-engine | 发牌、合法动作、边池、胜负计算 | 纯算法库 | 读取钱包或网络连接 |
| wallet/ledger | 账户、分录、余额、冲正 | PostgreSQL transaction | 覆盖历史流水 |
| settlement | 手牌终态、派奖、费用和计提依据 | table、ledger | 广播成功后再补写账本 |
| realtime | 连接、视图投影和推送 | auth、table query | 向旁观者推送未公开信息 |
| admin-api | 后台管理用例 | 所有业务应用接口 | 允许若依传入“修改后余额” |

### 4.2.1 Node 与受限数据库函数的单一职责（ADR-009）

Node 是流程规则唯一实现：牌型、合法行动、准入策略、费用公式、状态机编排和缺席策略只在其领域模块计算。PG 不另写一套牌局或资格引擎。Node 在事务中提交规范化命令及预期版本，受限函数只负责确定性持久化、不变量和并发防护：同源 FK、状态字段组合、唯一/排斥、旧版本 CAS、账本零和与非负、参数摘要幂等、授权单次消费。

数据库对摘要、当前版本、授权有效性和资金约束的复核属于不可绕过的安全边界，不是第二套可配置业务流程。锁顺序和事务管理在仓储/函数层唯一实现，Node 不在另一路径重复加锁。未完成函数继续拒绝写入。与“数据库只做普通 CRUD”相比保留强资金保护；与“PG 重写所有领域规则”相比避免业务漂移。领域规则变更只改 Node，约束变化才新增迁移；同一组契约样例同时验领域输出与存储接受/拒绝。

### 4.3 牌桌运行模型

每张牌桌使用逻辑 Actor/串行命令队列：

```text
WSS动作 / HTTP命令 / 超时任务 / 运营关桌
                    │
                    ▼
             room_id 串行队列
                    │
                    ▼
        校验版本、会话代际和动作序号
                    │
                    ▼
             确定性规则引擎
                    │
                    ▼
       PostgreSQL事务：状态 + 账本 + Outbox
                    │
                    ▼
              提交成功后广播
```

同一房间的下注、超时、补码应用、离桌和关房命令必须进入同一队列。Node 单线程不能自动保证跨 `await` 的业务串行，必须显式实现队列和版本校验。不同房间可以并发处理。

### 4.4 确定性规则引擎

规则引擎输入必须包括规则版本、牌序、参局名单、庄位、当前状态和命令；输出新的领域状态和待记账结果。引擎应满足：

- 相同输入得到相同输出。
- 随机牌序在开手时一次生成并持久化，恢复时不能重新洗牌。
- 使用加密安全随机源，不使用 `Math.random` 生成正式牌序。
- 长牌、短牌、烧牌、发牌顺序和牌型比较有独立测试向量。
- 引擎只处理牌局筹码守恒，不直接操作玩家钱包。
- 机器人和模拟器只接收被授权的玩家视图，不能访问对手私牌和剩余牌序。

### 4.5 状态恢复

每张桌至少持久化：

- 房间和规则版本。
- 当前手牌 ID、状态、牌序或可验证恢复材料。
- 参局名单、座位、筹码和当前行动者。
- 已接受动作及单调递增序号。
- 计时截止时间，而不是只保存内存定时器。
- 最近稳定快照及快照之后的持久命令。
- 结算业务号和提交状态。

恢复顺序：加载房间所有权 → 加载稳定快照 → 重放未包含的持久命令 → 检查已过期计时 → 重新建立推送视图。任何无法判断是否已经提交的资金结果进入冻结核查，不能自动再执行一遍。

## 5. Web 玩家端与 Telegram 兼容实施

### 5.1 客户端技术栈

- Vue 3 + TypeScript + Vite。
- Pinia 管理会话、房间摘要和当前桌视图。
- 首期适配桌面与移动浏览器，处理响应式布局、安全区、软键盘、前后台切换和可访问性。
- 将宿主能力封装为 `HostAdapter`；Web 使用标准浏览器实现，后续 Telegram 实现主题、安全区、返回按钮、关闭确认、触觉反馈、深链和分享。
- REST 客户端统一处理 `request_id`、错误码和 `UNKNOWN` 状态。
- WebSocket 客户端统一处理心跳、序号、版本、断线和快照恢复。

### 5.2 首期 LOCAL 注册与登录

```text
浏览器打开注册 / 登录页
  → POST /api/v1/auth/register 或 /api/v1/auth/login
  → 服务端规范化登录名并执行限流与统一失败响应
  → 注册时创建app_user、LOCAL player_identity与local_credential
  → 登录时验证密码哈希、凭据状态和失败锁定
  → 生成应用会话和session_generation
  → 客户端使用应用会话访问HTTPS/WSS
```

约束：

- 登录名只存在于 `provider=LOCAL` 的 `provider_subject`，不能作为牌桌、钱包、俱乐部或账本主键。
- 输入密码长度为8～72字符，服务端只保存抗暴力破解的密码哈希，不记录或回显原始密码。
- 同一登录名无论不存在、密码错误还是凭据不可用，都使用不泄露账号存在性的外部错误语义。
- 连续5次失败锁定15分钟；登录、注册、重置和敏感查询分别限流。
- 新设备合法登录后递增 `session_generation`，旧连接立即失去动作权限。
- 登录成功后只恢复同站点内经过白名单校验的邀请或房间返回目标，禁止开放跳转。
- 玩家凭据不能登录若依后台，后台账号也不能直接冒充玩家。

### 5.3 后续 Telegram 接入与绑定

后续接入不改变 `app_user.id`、`game_id/player_id`、钱包、俱乐部归属或战绩。Telegram 只是新的认证提供者和宿主适配器。

```text
已登录玩家在Telegram打开Mini App
  → 客户端取得initData原文
  → POST /api/v1/me/identities/telegram
  → 服务端用Bot Token验证签名与auth_date
  → 以provider=TELEGRAM + provider_subject=TG user.id建立绑定
  → 冲突则返回IDENTITY_CONFLICT，不静默创建第二个玩家
  → 后续 /api/v1/auth/telegram 解析到同一app_user并生成应用会话
```

- 客户端不能只上传 `user_id` 完成 Telegram 登录或绑定。
- TG 昵称和 username 可以变化，只能作为资料快照，不能作为账号键。
- `initData` 只用于换取绑定或应用会话，不写入日志或数据库。
- 普通 HTTPS 邀请链接是首期权威入口；未来 TG 深链只承载同一业务邀请 Token。
- Telegram 接口、SDK和深链配置在功能开关关闭时不得影响首期 Web 启动、健康检查或验收。

### 5.4 客户端请求状态

所有改变资金、座位和房间的请求使用：

| 状态 | 含义 | 客户端行为 |
| --- | --- | --- |
| `SUBMITTING` | 请求已发出，未收到终态 | 禁止重复点击，保留原 `request_id` |
| `UNKNOWN` | 超时或断线，结果未知 | 查询原请求，不生成新请求 |
| `FAILED` | 服务端明确失败 | 展示错误码；修正后使用新请求号 |
| `SUCCEEDED` | 服务端明确成功 | 根据返回版本进入后续流程 |

网络失败不等于业务失败。这个规则必须在买入、补码、开房、退出和人工资金调整中保持一致。

## 6. RuoYi 运营后台实施

### 6.1 若依负责的能力

- 后台账号邀请激活、密码、TOTP、恢复码、停用和会话撤销。
- 角色、菜单、按钮权限和俱乐部资源范围。
- 玩家、俱乐部、房间、牌局、代理和资金记录查询。
- 规则模板、邀请审核、成员迁移和房间处置工作流。
- 资金调整申请、二次验证、原因记录和原操作查询。
- 工单、举报、审计、导出任务和系统配置界面。
- 运营统计和报表投影展示。
- 玩家认证摘要查询；只展示认证来源、状态、锁定截止和最近认证，不展示登录名、外部subject、密码哈希或Token。
- 具备独立 `BP-32` 的超管可发起 LOCAL 玩家密码重置；权威认证服务负责校验、撤销全部玩家操控会话并生成一次性短时凭据。

### 6.2 若依禁止的行为

- 直接执行 `UPDATE wallet SET balance = ...`。
- 直接插入、修改或删除资金分录。
- 直接修改手牌结算状态和桌内筹码。
- 直接控制运行中 Node 内存对象。
- 把一条后台请求日志视为业务已经成功。
- 使用若依部门权限代替俱乐部资源范围校验。
- 查看、代设或导出玩家密码、密码哈希、登录名、Telegram ID、重置Token及其摘要原值。
- 在身份核实与凭据交付渠道未批准时开放玩家密码重置入口。

### 6.3 管理操作协议

若依调用 Node 管理 API 时携带：

```json
{
  "operation_id": "01J...",
  "operator_id": "admin_123",
  "authorization_id": "authz_456",
  "resource_scope": ["club_1001"],
  "reason": "工单 ST-2026-0012",
  "request": {}
}
```

Node 必须重新校验操作人、授权有效期、资源范围、目标状态和请求摘要。同一 `operation_id` + 同一请求返回原结果；同一操作号但参数不同必须拒绝。

### 6.4 资金调整流程

```text
运营输入玩家、币种、金额和原因
  → 若依校验菜单/资源权限
  → 资金敏感操作二次验证
  → 若依生成operation_id并调用Node
  → Node复核授权、参数、余额和幂等
  → Node事务写入平衡分录、余额和执行审计
  → Node返回终态或结果查询地址
  → 若依展示业务结果并保留请求审计
```

纠错只能追加与原分录关联的冲正或补充分录，不能覆盖历史流水。

### 6.5 玩家本地密码重置边界

若依只提交带 `operation_id`、玩家ID、原因、参数摘要和 `BP-32` 敏感授权的重置命令；Node 认证服务才是执行方。执行时必须确认玩家存在活动 LOCAL 身份、凭据状态允许重置、身份核实与交付渠道已批准，并在同一受控流程中撤销全部玩家操控会话、使旧重置凭据失效、生成默认30分钟单次凭据并记录双侧审计。

重置不能创建新玩家或改变 `game_id/player_id`、钱包、俱乐部、代理、牌局、战绩及已有 Telegram 绑定。专用玩家重置凭据表和交付渠道仍是实施前置条件；数据库迁移未落地前接口保持关闭，不能复用后台人员激活Token或业务邀请Token。

### 6.6 若依认证集成（ADR-010）

状态：本次设计修订采用，运行实现待完成。现存目录名 v4.8.3，pom/npm 实际 4.8.2、Java 8 / Boot 2.7.18；不等同于当前社区同名分支。其源码仅作迁移起点。目标 Java 21 LTS 和构建时仍获安全维护的 Spring Boot 版本，锁定具体补丁、BOM、支持期限证据与依赖扫描；旧栈只用于隔离迁移验证，不作为生产发布目标。版本升级、登录适配与越权回归未通过时阻断后台发布。

采用一套后台身份：poker.admin_user/admin_role/admin_permission/admin_scope_grant/admin_session，由 Node 后台 auth 模块认证、校验 TOTP 和签发会话。无 sys_user→admin_user 隐式映射、无密码同步。历史后台人员只能经受审计的激活流程建立 admin_user 并重新绑 TOTP；初始化不保留 admin/admin123 等原生账号。

Java 将 HTTPS 请求中的不透明后台令牌转交 Node；不记录令牌，不自行延长会话。Node 复查 admin_session、账号状态、15min/8h 时限及 authorization_version，返回裁剪后的菜单/动作/对象能力。原生 /login、/register、/social/callback 以及其他 sys_* 登录、令牌刷新、生成器和运维入口在生产路由与安全配置中禁用；以路由枚举回归验证，无历史令牌兼容。菜单展示不得成为第二层授权源，sys_role/sys_menu 不参与扑克权限决策。

Java→Node 使用独立服务身份与 mTLS（或等价受控服务凭据），并携带原后台令牌、request_id/operation_id；仅服务凭据不能代替操作者授权，禁止信任客户端注入 admin_id/role/header。Node 对每次查询、写入和异步执行重新判权，超时显示 UNKNOWN 并按原操作号查结果。Java 不直连后台密钥表；后台密码/TOTP 域与玩家 LOCAL 凭据永远隔离。

备选“双身份映射”会引入密码、撤权和会话同步失败，本期不采用。代价是需替换若依安全适配层，并保留 Node 审计与 Java 请求审计的 operation_id 关联。

## 7. 数据架构与所有权

### 7.1 Schema 与数据库权限（ADR-008）

采用单一 `poker` Schema，以数据库角色和受限函数隔离能力，与 V001～V015 一致。撤销原 game/admin/report 三 Schema 建议。

| 角色 | 主体 | 能力 |
| --- | --- | --- |
| `poker_owner` | NOLOGIN 对象所有者 | 仅迁移身份可代入；应用禁止继承 |
| `poker_app` | Node 权威服务 | 仅已评审函数 EXECUTE 及必要读取；无表直接写权 |
| `poker_readonly` | 受控查询 | 仅安全视图；不授原始身份、私牌、密钥表读取 |
| `poker_admin` | Java 运营壳 | 无核心表和认证表权限；仅通过 Node 内部 API |
| `poker_worker` | Node 后台投递进程 | 仅专用投递函数；无牌桌/账本写权，函数未完成前不授能力 |

迁移登录与应用登录分离；独立应用登录只能继承自身组角色。Java 不得继承 poker_app/poker_owner。报表是 poker 内安全视图或投影表，不另设 report Schema。新对象同迁移转给 poker_owner、撤销 PUBLIC 权限。选择角色隔离复用既有迁移，代价是必须逐函数审查授权；三 Schema 方案暂不采用。

### 7.2 数据所有权矩阵

| 数据 | 权威写入方 | 若依使用方式 | 一致性要求 |
| --- | --- | --- | --- |
| 统一玩家、认证身份、本地凭据与会话 | Node | 管理API查询脱敏摘要、停用或受控重置 | 强一致 |
| 俱乐部、成员、邀请 | Node | 管理API查询和提交命令 | 强一致 |
| 房间和规则版本 | Node | 发布模板、关房命令 | 强一致 |
| 当前牌桌和手牌 | Node table模块 | 查询受裁剪快照 | 强一致 |
| 钱包、冻结、托管 | Node ledger模块 | 只读查询、调整命令 | 强一致 |
| 资金分录 | Node ledger模块 | 只读、导出 | 不可覆盖 |
| 代理协议与计提依据 | Node settlement模块 | 配置命令、查询 | 版本化 |
| 后台账号、会话、角色与范围 | Node 后台认证/授权模块 | 内部 API；菜单为权限投影 | 强一致 |
| 报表汇总 | Node worker 的 poker 投影 | 安全视图或 API | 最终一致，显示截止时间 |
| 操作审计 | 若依请求审计 + Node执行审计 | 通过operation_id关联 | 不可删除 |

### 7.3 核心实体

下列名称均为数据字典中的物理表，概念名不得直接用于 DDL：

- 身份：`app_user`、`player_identity`、`local_credential`、`player_session`、`player_login_event`、`user_preference`。
- 组织：`club`、`club_membership`、`club_agent_history`、`invite`、`invite_application`。
- 房间：`rule_template`、`rule_template_version`、`room`、`room_seat_occupancy`、`seat_session`。
- 手牌：`hand`、`hand_player`、`hand_action`、`hand_pot_award`、`hand_settlement`、`room_state_snapshot`。
- 账务：`ledger_account`、`wallet_balance_projection`、`ledger_transaction`、`ledger_entry`。
- 结算：`topup_order`、`hand_fee`、`agent_agreement_version`、`commission_attribution`。
- 协作：`business_operation`、`audit_log`、`outbox_event`、`outbox_delivery`、`projection_checkpoint`。

旧概念 fee_detail → hand_fee；seat → room_seat_occupancy；hand_result → hand_pot_award + hand_settlement；hand_snapshot → room_state_snapshot；balance_snapshot → wallet_balance_projection；pending_rebuy → topup_order；agent_accrual → commission_attribution；audit_event → audit_log。全量表清单以数据字典为准，静态门禁核对迁移与字典。

`app_user.id` 是业务关系使用的稳定玩家键；LOCAL登录名和未来TG `user.id`只存在于 `player_identity`。`local_credential` 只挂载到 LOCAL 身份，认证成功后签发的 `player_session` 同时引用玩家与所用身份。玩家密码重置需要新增专用单次凭据对象；其结构、索引、并发约束和清理策略必须通过新增 Flyway 迁移落地，不能回改已登记的迁移。

### 7.4 账本不变量

- 金额使用最小货币单位整数，数据库使用 `BIGINT`，接口使用十进制字符串。
- 一笔业务交易内借方合计必须等于贷方合计。
- 账户余额不能通过覆盖历史流水得到。
- 买入是“可用余额 → 桌内托管”，玩家总资产不凭空变化。
- 待生效补码是“可用余额 → 冻结”；手间生效后“冻结 → 桌内托管”。
- 每个 `seat_session` 的离座费最多结算一次。
- 每个手牌结算业务号只能成功一次。
- 扣款使用行锁或带余额条件的原子更新，禁止先查余额再无条件更新。
- 数据库约束、事务代码和自动化对账共同保障不变量。

### 7.5 幂等与并发约束

建议数据库约束至少包括：

- `(provider, provider_subject)` 全局唯一；同一玩家同一提供者最多一个活动身份。
- LOCAL登录名规范化后唯一；未来TG `user.id`只在 `provider=TELEGRAM` 内唯一。
- 同一玩家最多一个活动操控会话；新设备接管撤销旧会话并推进 `session_generation`。
- 同一 LOCAL 身份最多一个活动密码重置凭据，Token只保存带密钥摘要且单次消费。
- 单玩家最多一个活动真人桌 `seat_session`。
- 同一房间座位最多一个有效占用。
- 同一手牌动作序号唯一。
- 业务 `request_id` 唯一并保存请求摘要。
- 手牌结算业务号唯一。
- 账本交易业务号唯一。
- Outbox 事件 ID 唯一。
- 后台 `operation_id` 唯一。

请求处理必须保存原始业务结果，使重复请求返回原结果，而不是再次执行。

## 8. 接口与事件契约

### 8.1 HTTP API 分组

| 分组 | 示例 | 用途 |
| --- | --- | --- |
| 身份 | `POST /api/v1/auth/register` | 创建稳定玩家、LOCAL身份、本地凭据和应用会话 |
| 身份 | `POST /api/v1/auth/login` | 验证LOCAL凭据并换取应用会话 |
| 身份 | `DELETE /api/v1/auth/session` | 撤销当前玩家会话 |
| 身份 | `POST /api/v1/auth/password-resets/{token}/complete` | 使用一次性凭据由玩家设置新密码 |
| 身份（后续） | `POST /api/v1/auth/telegram` | TG验签并解析到已绑定的统一玩家 |
| 身份（后续） | `POST /api/v1/me/identities/telegram` | 为当前玩家绑定已验签且无冲突的TG身份 |
| 玩家 | `GET /api/v1/me` | 当前玩家资料和权限摘要 |
| 俱乐部 | `GET /api/v1/clubs/current` | 当前归属和可见房间 |
| 房间 | `POST /api/v1/rooms/{id}/seat-reservations` | 预约座位 |
| 买入 | `POST /api/v1/rooms/{id}/buy-ins` | 创建幂等买入 |
| 操作结果 | `GET /api/v1/operations/{request_id}` | 查询未知结果 |
| 账单 | `GET /api/v1/me/ledger-entries` | 查询本人流水 |
| 后台内部API | `/internal/admin/v1/...` | 若依受控管理操作，包括BP-32玩家密码重置命令 |

所有写接口返回：

```json
{
  "request_id": "01J...",
  "status": "SUCCEEDED",
  "resource_version": 42,
  "data": {},
  "error": null
}
```

### 8.2 WebSocket 信封

```json
{
  "type": "table.command",
  "request_id": "01J...",
  "room_id": "room_123",
  "hand_id": "hand_456",
  "expected_version": 41,
  "session_generation": 8,
  "sequence": 102,
  "payload": {}
}
```

服务端推送必须包含 `room_id`、`hand_id`、`resource_version`、`server_time` 和披露策略生成的玩家视图。客户端检测到版本缺口时停止猜测增量状态并请求完整快照。

### 8.3 错误语义

错误响应至少区分：

- `AUTH_INVALID`
- `AUTH_LOCKED`
- `AUTH_EXPIRED`
- `IDENTITY_CONFLICT`
- `PASSWORD_RESET_NOT_AVAILABLE`
- `SESSION_REPLACED`
- `FORBIDDEN_RESOURCE_SCOPE`
- `ROOM_NOT_JOINABLE`
- `SEAT_ALREADY_TAKEN`
- `INSUFFICIENT_AVAILABLE_BALANCE`
- `STALE_RESOURCE_VERSION`
- `ACTION_NOT_ALLOWED`
- `IDEMPOTENCY_CONFLICT`
- `RESULT_UNKNOWN`
- `SERVICE_DRAINING`

错误码由服务端定义并版本化，客户端不能依赖错误文案判断业务分支。

### 8.4 Outbox 事件

与核心业务事实同事务写入 `outbox_event`，后台 worker 提交后投递。典型事件：

- `player.created`
- `club.membership.changed`
- `room.status.changed`
- `hand.settled`
- `ledger.transaction.posted`
- `agent.accrual.created`
- `admin.operation.completed`

事件结构及每消费者投递状态以字典 §13.8/13.9 和 V015 为准。业务事务同时插入不可变 outbox_event 与所需 outbox_delivery；未创建投递行的事件视为生产者缺陷，禁止提交成功后补插通知。

worker 短事务以 FOR UPDATE SKIP LOCKED 领取 available_at 到期的 READY 行或租约到期的 LEASED 行，更新随机 lease_token、lease_expires_at=数据库当前时刻+30秒、attempt_count+1 后提交；网络调用在事务外。ACK/失败回写必须匹配 id、LEASED 和 lease_token；旧租约回执不得覆盖新投递。成功写 DELIVERED，失败清租约并 READY、指数退避（1秒起、上限5分钟，带抖动）；第20次失败转 DEAD 告警。人工重投复用 event_id，审计后重置投递状态。禁止通过删除事件“重试”。

消费者以 (consumer_name,event_id) 在自身持久存储去重，并与业务效果、水位同事务提交；崩溃后重投依然安全。projection_checkpoint 只能在连续已处理水位推进，不能取并行 ACK 的最大时间充当完整截止时间。按对象版本发现缺口时暂停该对象并拉取权威快照，不盲目丢弃迟到资金事件。WSS 只发送按接收人裁剪的 payload，禁止包含未公开私牌、口令或令牌。交付至少一次；消费者幂等实现业务效果一次。

DELIVERED 事件和投递在线保留至少30天、且所有消费者水位覆盖后归档；READY/LEASED/DEAD 与保全引用不得清理。账本和审计按各自365天策略保留，Outbox 不替代权威事实。

## 9. 关键业务链路

### 9.1 入座与买入

1. 客户端生成 `request_id` 并预约座位。
2. Node 在事务内复查玩家状态、俱乐部资格、房间状态、座位、币种、规则版本和余额。
3. Node 创建唯一 `seat_session`，将可用余额转入桌内托管。
4. Node 写业务操作结果和 Outbox。
5. 事务提交后，客户端才进入牌桌；响应丢失时查询原请求。

事务失败不得残留座位占用、冻结或半笔账。

### 9.2 玩家动作

1. WSS 接收动作并验证应用会话和设备代际。
2. 校验房间、手牌、轮次、动作序号和期望版本。
3. 动作进入该房间串行队列。
4. 规则引擎判断合法动作并生成新状态。
5. 持久化动作、状态版本和必要快照。
6. 提交后向不同身份推送各自裁剪视图。

### 9.3 手牌结算

1. 状态由 `STARTED` 进入 `SETTLING`。
2. 引擎输出边池、赢家和筹码变化。
3. 同一事务写入手牌终态、桌内托管变更、抽水、代理归因依据和 Outbox。
4. 事务提交后状态进入 `SETTLED`。
5. 广播失败只重试通知，不能重新计算或重复记账。

### 9.3.1 手间边界事务（ADR-011）

采用“手牌结算 T1 + 原子手间处理 T2 + 下手准入 T3”，不把网络广播、3秒等待或外部调用放进事务。T1 将手牌 SETTLED、分录、归因和 outbox 一起提交。只看到 SETTLED 不代表可以开下一手。

T2 使用确定性 request_id=UUIDv5(固定命名空间, room_id+hand_id+HAND_BOUNDARY)，以 business_operation 唯一键和摘要保存结果；room_state_event 以 reason_code=HAND_BOUNDARY_APPLIED 追加边界事实，details 保存 hand_id、boundary_at 与房间版本，from_status/to_status 使用实际合法房间状态（不把边界事件名写成状态）。同号同参返回原结果，异参拒绝。所有步骤一个本地事务，失败全回滚，不按内存步骤号续跑。

统一锁序：business_operation 幂等锁（含整批账本业务键按规范化键排序取得的幂等锁） → 所涉 app_user 按 UUID 排序 → club/归属仲裁行按 UUID 排序 → room 按 UUID 排序 → hand → room_seat_occupancy 按(room_id,seat_no) → seat_session/topup_order 按 UUID → 所有 ledger_account 按 UUID。涉及多类对象的买入、迁移、补码、离座和手结算采用同序；先读候选集合、锁后重验，发现集合变化则回滚重试；不能持有 room 锁再去拿用户锁。账户需预先收集整批，不能多次调用账本函数后反向拿较小账户锁。

| T2 顺序 | 原子处理 |
| --- | --- |
| 1 | 锁后检查 T1 已 SETTLED、room 当前版本及本手边界未完成；固定数据库 boundary_at |
| 2 | 判断房间到期/已 DRAINING；收口本手离座/强制离座请求，按既定豁免和 E−F+U 清算；关房时所有入座进入清算，待补码冻结额退回 |
| 3 | 对仍有效的 seat_session 应用待补码，超最大买入差额退回；终止会话仅退款，不先补后扣；账本和订单终态一起写 |
| 4 | 生效本手结束允许落地的待归属/代理迁移，锁后复核批准事实与双侧范围；若旧房间已不合资格则清算离座，不用新归属重算本手历史费用/代理 |
| 5 | 对仍在座者判零筹码：补码后仍为0且首次进入 ZERO_STACK_HOLD，deadline=boundary_at+60秒；重试/连续空手不重置；有效补码清 deadline；超期离座按产品豁免 |
| 6 | 处理已批准换座/位置和缺席策略的下一手生效状态；写房间版本、边界事件、审计、结果与 outbox |

T2 某一步失败：全回滚，房间不准开下一手；死锁/序列化失败以同请求号重试，连续失败转 PAUSED_RECOVERY 并建恢复案，不能跳过退款或迁移。崩溃发生于 T1 后/T2 前，由扫描“已结算且无边界完成事件”的任务重新投递。T2 提交后响应丢失，查询同 operation 结果，不重复收费/补码/延长60秒。

T3 最早在 T2 持久化 boundary_at+3秒后进入房间队列；重启从结果中的 boundary_at 恢复计时。再次持锁检查边界结果、版本、人数、零筹码/缺席状态、房间到期/DRAINING；到期优先关房并清算，不发新手。T2/T3 之间新补码和离座仍入同一队列；事件按版本推送，客户端不得据 SETTLED 自行开局。验收覆盖每步故障、提交后断线、同边界并发、到期与补码/迁移同刻、重启计时及全账户守恒。

### 9.4 断线与恢复

- 关闭浏览器标签、浏览器切到后台或未来关闭 TG 宿主都不等于离桌。
- 断线期间服务端继续执行合法超时策略。
- 重连先验证会话代际，再返回当前权威快照和允许动作。
- 已结算手返回原结算结果；不能因为客户端未收到广播而重算。
- 新设备接管后旧连接只能收到失效通知，不能继续下注。

### 9.5 运营冻结俱乐部

1. 若依校验后台权限并取得敏感操作授权。
2. Node 复核 `operation_id`、资源范围和俱乐部当前状态。
3. 禁止新加入、买入、补码和开房。
4. 正在进行的手牌完成后关桌和返还。
5. 邀请撤销、待审核申请和房间处置均产生业务审计。
6. 解冻不会自动恢复旧邀请或已关闭房间。

## 10. 安全架构

### 10.1 玩家端

- 首期由服务端验证 LOCAL 密码哈希、凭据状态、失败次数与锁定时间；任何外部响应都不泄露登录名是否存在。
- 应用会话使用短期访问令牌和可撤销服务端状态；密码、重置Token和未来 `initData` 都不能作为长期会话。
- 后续 Telegram 接入由服务端验证 `initData` 签名与 `auth_date`，绑定冲突时拒绝而不是合并或新建业务账号。
- HTTPS/WSS 强制 TLS，设置 HSTS、CSP、`frame-ancestors` 和严格来源校验。
- 每次动作校验玩家、房间、座位、手牌和设备代际。
- 牌桌状态按玩家、旁观者、运营审计分别投影，禁止前端隐藏代替后端隔离。
- 登录、加入、邀请、聊天和敏感查询设置独立限流。

### 10.2 运营后台

- 后台账号与统一玩家账号、LOCAL/TELEGRAM认证身份分离。
- 密码 + TOTP；激活、恢复、停用和重置均有审计。
- 连续失败锁定按登录、敏感验证和改密分别计数。
- 高风险操作使用短时、单次、绑定对象和参数的授权。
- 资源范围在若依和 Node 执行端双重校验。
- 导出文件短期有效，下载时重新验证当前权限。

### 10.3 服务间与密钥

- 若依调用 Node 使用独立服务身份，建议 mTLS 或短期签名凭据。
- 用户权限上下文不能只由若依声明；Node 通过可信签名和服务端权限数据复核。
- 数据库密码、密码摘要Pepper、TOTP加密密钥、会话签名密钥和未来Bot Token进入密钥管理系统，不写入仓库、镜像或日志。
- 历史材料中如存在明文 Telegram Bot Token，仍须立即撤销、扫描并移出仓库和交付包；但新 Bot 与 Mini App 配置只属于后续 Telegram 接入条件，不阻塞首期 Web 开发验收。

## 11. 部署拓扑

### 11.1 首期推荐拓扑

```text
                         ┌─ Web玩家端静态资源/CDN
Internet ── WAF/Nginx ──┤
                         ├─ Node game-api（单写）
                         └─ RuoYi admin-api
                                  │
             ┌────────────────────┼───────────────────┐
             ▼                    ▼                   ▼
      Node worker          PostgreSQL HA       Redis（可选）
             │                    │
             └─ 对象存储          └─ PITR备份/恢复演练
```

推荐首期使用单区域部署。牌桌写入实例可以单实例运行并依靠快速重启恢复；如果部署两个实例，必须保证任何时刻同一房间只有一个合法 owner，不能只靠负载均衡粘性会话。

### 11.2 环境划分

| 环境 | 用途 | 数据要求 |
| --- | --- | --- |
| local | 开发与单元测试 | 本地匿名测试数据 |
| test | 集成、自动化和测试牌序 | 隔离 TEST 资产，不连接生产 Bot 或真实玩家数据 |
| staging | 目标浏览器、弱网、容量和发布演练 | 生产近似配置，匿名数据；TG接入阶段再增加真机宿主 |
| production | 正式业务 | 最小权限、备份、审计和告警 |

测试机器人、固定牌序和调试端点必须通过构建配置及网络策略双重隔离，生产环境启动时发现相关开关应直接失败。

### 11.3 静态报告部署

本报告站点不依赖 Node、Java 或数据库。将本目录中的发布文件上传到服务器目录，并由 Nginx 提供静态访问即可。示例：

```bash
sudo mkdir -p /var/www/storm-architecture
sudo cp -R ./site/* /var/www/storm-architecture/
sudo nginx -t
sudo systemctl reload nginx
```

正式部署时请根据服务器账号和目录调整命令。不要把项目源代码、`.env`、密码、密钥、Bot Token 或数据库备份放入报告站点目录。首期应用启动和健康检查不得要求配置 Bot Token。

## 12. 可观测性与运行指标

### 12.1 日志关联字段

所有关键日志至少包含：

- `trace_id`、`request_id`、`operation_id`。
- `player_id`、`room_id`、`hand_id`、`seat_session_id`。
- `resource_version`、`rule_version`、`session_generation`。
- 结果状态、错误码、耗时和应用版本。

日志不得记录登录名原值、外部subject、密码、密码哈希、重置Token、Bot Token、Telegram `initData`、TOTP密钥、完整会话令牌、未授权私牌和完整牌序。

### 12.2 核心指标

| 指标 | 目标/告警方向 |
| --- | --- |
| 活跃WSS连接、活跃桌数、每桌队列长度 | 容量与热点识别 |
| 动作处理P50/P95/P99 | P95目标≤200ms |
| PostgreSQL事务耗时、锁等待、死锁和连接池 | 防止结算阻塞 |
| Node事件循环延迟、堆内存和GC | 防止实时响应抖动 |
| Outbox积压数量与最老事件年龄 | 通知和报表延迟 |
| 重连成功率与恢复耗时 | P95目标≤5秒 |
| `UNKNOWN`请求数量和持续时间 | 发现网络或事务异常 |
| 待核查结算和账本不平衡数量 | 必须为0并立即告警 |
| 登录失败/锁定、权限拒绝、会话接管、重置拒绝和后续TG验签失败 | 安全监控 |

### 12.3 建议服务目标

业务需求已经定义动作、首屏和恢复性能。可用性、RPO 和 RTO 需要结合预算正式批准。建议评审目标：

- 已提交资金和结算不因单个应用进程故障丢失。
- 数据库启用时间点恢复并定期执行恢复演练。
- 应用进程故障后优先恢复权威状态，再开放新动作。
- 可用性指标按月统计，并把计划维护与非计划故障分开。

## 13. CI/CD 与发布回滚

### 13.1 流水线门槛

每次合并至少执行：

1. TypeScript/Java 编译、格式和静态检查。
2. 规则引擎单元测试与筹码守恒性质测试。
3. PostgreSQL 事务、幂等、并发和迁移测试。
4. WebSocket 双真人完整牌局测试。
5. 权限矩阵和越权测试。
6. Web注册登录、响应式浏览器与关键业务路径测试；后续TG接入单独增加宿主契约测试。
7. 依赖、镜像和密钥扫描。
8. 文档断链和版本检查。

### 13.2 数据库迁移

- 使用 Flyway、Liquibase 或 Node 侧迁移工具中的一种，M0 阶段锁定。
- 采用 expand/contract：先增加兼容结构，再切换应用，最后移除旧结构。
- 迁移脚本只向前执行；资金数据纠正使用业务冲正，不使用回滚脚本覆盖历史。
- 大表索引和回填必须在 staging 验证锁时间和磁盘空间。

### 13.3 发布流程

1. 发布前停止创建新房间和新买入，服务进入 `DRAINING`。
2. 完成当前手或持久暂停到可恢复边界。
3. 确认 Outbox、结算和数据库迁移状态。
4. 切换应用版本并完成就绪检查。
5. 恢复牌桌所有权，再开放玩家动作和新业务。
6. 观察核心指标后解除排空状态。

应用回滚不能回滚已经提交的资金事实。数据纠错使用向前修复或冲正分录。

## 14. 测试与验收策略

### 14.1 测试层级

| 层级 | 重点 |
| --- | --- |
| 单元测试 | 牌型、合法动作、边池、短牌规则、费用和舍入 |
| 性质测试 | 随机合法动作下筹码守恒、无负余额、无重复赢家 |
| 集成测试 | PostgreSQL事务、锁、死锁重试、幂等和Outbox |
| 协议测试 | HTTP/WS契约、版本缺口、乱序、重复和断线 |
| E2E测试 | Web注册/登录→俱乐部→买入→一手→离桌→查账 |
| 安全测试 | LOCAL认证与锁定、会话接管、重置、越权、私牌隔离、导出撤权；后续增加TG验签与绑定冲突 |
| 故障测试 | 数据库断开、广播丢失、进程重启、结算重放 |
| 容量测试 | 500连接、50桌×8席、2小时稳态及热点桌 |
| 目标端测试 | Chrome、Edge、Safari及目标移动浏览器、弱网和后台切换；后续增加iOS/Android/Desktop Telegram |

### 14.2 阻断性验收

以下任一失败都阻断上线：

- 重复请求造成重复扣款、重复派奖或重复离座费。
- 同一玩家同时控制两个活动真人座位。
- 旁观者或其他玩家获得未公开私牌、牌序或延迟公共牌。
- 若依越权查看或修改其他俱乐部数据。
- 结算已提交但广播失败时发生再次结算。
- 重启后无法区分已结算、未结算和结果未知。
- 正式环境可以使用昵称登录、弱口令绕过、测试牌序或机器人调试入口。
- 无 `BP-32`、仅TELEGRAM身份、交付渠道未批准或重放旧凭据时仍可完成玩家密码重置。
- 账本借贷不平衡，或人工直接覆盖历史余额。

## 15. 分阶段实施路线

阶段按依赖和退出证据推进，不以固定人类负责人、虚构工期或页面数量判定完成。AI任务总清单记录每项输入、产物、校验、证据、实际完成时间和阻断状态。

### M0：基线与契约

交付：

- 锁定 Node、Java、PostgreSQL、迁移工具和部署方式。
- 完成模块边界、数据所有权、ER 图和权限矩阵。
- 定义 HTTP/WS 信封、错误码、金额和版本契约。
- 建立 ADR、代码规范、CI 和环境配置模板。
- 建立密钥管理流程；扫描并撤销历史泄漏凭据，首期配置不依赖Bot Token。

退出条件：所有团队使用同一份接口和数据所有权定义；没有“若依直接改余额”等未决边界。

### M1：可信身份与账本底座

交付：

- LOCAL注册登录、统一玩家/身份/凭据模型、应用会话、设备接管和正式入口隔离。
- 认证提供者接口与Telegram数据形状预留；TG验签、绑定和宿主接入保持关闭。
- 玩家、钱包、平衡账本、幂等操作和Outbox。
- Node 后台账号、TOTP、角色、范围与若依安全适配及服务间认证。

退出条件：LOCAL注册、登录、失败锁定、单操控会话与身份隔离通过；并发扣款、重复请求、越权和账本平衡测试通过。

### M2：完整对局闭环

交付：

- 确定性长牌引擎、房间Actor、计时、座位、买入和补码。
- 手牌结算、抽水、离桌返还、快照和重启恢复。
- Web牌桌、WSS协议和版本缺口恢复。

退出条件：Web注册/登录→买入→完成一手→费用结算→离桌→查账→进程重启恢复全链路通过。

### M3：俱乐部与运营闭环

交付：

- 俱乐部、邀请、成员迁移、规则模板和房间处置。
- 若依玩家、俱乐部、房间、资金、配置和工单页面。
- 管理API、敏感授权、资金调整和双侧审计。
- 玩家认证摘要与 `BP-32` 本地密码重置；专用凭据、会话撤销、身份核实和交付渠道全部通过门禁后才开放。

退出条件：跨俱乐部访问被服务端阻断；后台操作结果与业务事实可通过 `operation_id` 关联。

### M4：完整范围与体验

交付：

- 短牌、代理协议与计提、牌谱、战绩、聊天、举报和导出。
- 统计投影、截止时间和原日重算。
- Chrome、Edge、Safari及目标移动浏览器适配。

退出条件：需求追踪矩阵中的本期范围全部有实现、接口和验收证据。

### M5：容量、安全与首期 Web 上线

交付：

- 容量、弱网、故障恢复、安全和备份恢复演练。
- 监控仪表盘、告警、值班手册、发布和回滚演练。
- 生产环境密钥、网络、最小权限和数据保留策略。

退出条件：全部阻断性验收通过；每项遗留风险有任务ID、证据、门禁状态和明确处置条件，外部资源状态如实记录。

### M6：Telegram 接入（后续独立工作流）

交付：

- `initData` 验签、TG身份绑定/登录、冲突处理和认证审计。
- Telegram宿主适配、深链/分享、主题、安全区、返回按钮和真机兼容。
- Web与Telegram使用同一 `app_user`、邀请Token、业务API、WSS协议、钱包、归属和战绩。

退出条件：TG身份已绑定其他玩家时可靠拒绝；绑定与登录不产生第二套业务身份；iOS/Android/Desktop Telegram真机、弱网及切后台场景通过。M6未完成不计为首期Web缺陷。

## 16. AI 任务流与交付门禁

| 任务流 | 主要产物 | 自动与证据门禁 |
| --- | --- | --- |
| 架构与契约 | ADR、模块边界、HTTP/WSS契约、错误码 | 版本一致性、依赖方向和断链检查 |
| Node业务 | 身份、牌桌、账本、结算、恢复、管理API | 单元/性质/集成/E2E、幂等和故障注入证据 |
| 玩家端 | Web页面、WSS状态机、响应式与弱网体验；后续TG适配 | 目标浏览器矩阵、无障碍、弱网与版本恢复证据 |
| 运营后台 | 后台认证、权限、运营页面、流程和管理API调用 | 权限矩阵、越权、双侧审计和撤权即时性证据 |
| 数据库 | Flyway迁移、约束、索引、函数、视图和恢复脚本 | 迁移连续性、结构校验、并发测试、备份恢复演练 |
| 测试与发布 | 需求追踪、容量、安全、部署和回滚记录 | 阻断场景全部通过，环境/版本/输入/实际结果可复现 |

资金、结算、权限和恢复变更必须通过独立检查任务，不以同一生成步骤的自我声明作为通过证据。数据库迁移和生产配置必须经过静态检查、隔离环境执行、回滚边界核对及实际恢复演练。需要人类或外部机构批准的发布、合规和凭据操作保持显式外部门禁，不虚构签字人。

## 17. 风险登记

| 风险 | 影响 | 应对 | 验证门禁或处置证据 |
| --- | --- | --- | --- |
| 现有引擎与最终规则有差异 | 结算错误 | 固定规则测试向量，逐项替换随机、发牌和烧牌 | 规则向量、性质测试与结算对账全部通过 |
| 若依与Node边界失控 | 双写、越权、审计断裂 | 管理API单一写入口，数据库权限强制隔离 | 权限测试证明若依账号不能写核心表 |
| LOCAL与TELEGRAM身份误合并 | 第二套钱包、归属或战绩 | 统一身份映射、绑定冲突拒绝、核心表只引用app_user | 身份冲突与绑定回归场景通过 |
| 玩家重置渠道未确认 | 账号接管 | BP-32、参数绑定TOTP、单次凭据、全会话撤销，未确认时关闭 | 专用迁移、渠道批准及正常/风险验收证据齐全 |
| 单实例故障 | 短时牌桌不可用 | 持久命令与快照、快速恢复、明确排空发布 | 重启恢复和结算不重放故障测试通过 |
| 多实例过早上线 | 同桌双写和重复结算 | 未完成owner/epoch前保持单写 | 部署拓扑与运行时门禁证明单写 |
| 报表查询拖慢结算 | 动作延迟 | report投影、只读库或异步导出 | 容量报告记录数据库等待与动作P95 |
| 浏览器/未来TG弱网和切后台 | 重复操作、状态跳变 | `request_id`、UNKNOWN查询、版本快照恢复 | 目标端弱网、断开与恢复用例通过 |
| 旧Bot Token泄漏 | Bot被接管 | 立即撤销、轮换、扫描历史和密钥管理 | 扫描报告与撤销记录；新Token不进入交付物 |
| 真实资金合规不明确 | 法律和经营风险 | 独立合规门禁，不在技术迭代中默认开启 | 未获批准时真实资产功能保持关闭 |

## 18. 扩容演进

当前目标不需要首期微服务。达到以下证据之一后再评估扩容：

- 单实例事件循环、CPU 或数据库延迟持续超过目标。
- 热点房间影响其他房间，需要故障域隔离。
- 多团队必须独立发布不同业务边界。
- 单库报表和在线事务无法通过投影、索引或只读副本解决。

扩容顺序：

1. 静态资源 CDN、查询缓存、数据库索引和报表投影。
2. 将 worker 与 game-api 分进程部署。
3. 按 `room_id` 分配牌桌 owner，持久化 `owner_id + epoch`。
4. 数据库在写入时校验 epoch，失效实例不能提交。
5. 网关根据房间路由 WSS；重连可以重新发现 owner。
6. 最后才评估将稳定边界拆为独立服务。

Redis 锁、Kubernetes 或粘性会话都不能替代持久化的房间所有权和代际校验。

## 19. 架构决策记录摘要

### ADR-001：采用 Node.js 模块化单体

状态：提议接受。  
理由：现有引擎可复用，当前范围和容量不需要微服务；模块化单体能让关键牌局和账本共享本地事务。  
代价：必须通过目录、接口和数据库权限维持模块边界。

### ADR-002：PostgreSQL 是核心业务事实源

状态：提议接受。  
理由：需要事务、唯一约束、行锁、审计和时间点恢复。  
代价：需要严格迁移、索引、备份和恢复演练。

### ADR-003：若依是运营工作台，不是核心业务写入方

状态：提议接受。  
理由：避免两套规则和资金双写。  
代价：运营功能需要建设受控管理 API，不能全部依赖 CRUD 代码生成。

### ADR-004：REST + WSS，共用业务用例

状态：提议接受。  
理由：REST 适合登录、查询和可重试提交；WSS 适合实时牌桌。两种入口必须调用同一业务层。  
代价：需要统一信封、错误码和幂等语义。

### ADR-005：每桌单写，提交后广播

状态：提议接受。  
理由：消除同桌命令竞争，并避免通知成功但账务失败。  
代价：需要房间队列、恢复和未来扩容时的 owner/epoch 协议。

### ADR-006：首期使用数据库 Outbox，不引入消息平台

状态：提议接受。  
理由：当前吞吐目标下，Outbox 能满足可靠通知并减少运维组件。  
代价：需要监控积压和定期归档；规模增长后可能迁移到消息平台。

### ADR-007：统一玩家与认证提供者分离，首期采用 LOCAL

状态：提议接受。  
理由：首期普通Web入口不依赖Telegram资源；稳定玩家与LOCAL/TELEGRAM认证身份分离后，未来接入不会复制钱包、归属或战绩。  
代价：需要认证提供者适配层、绑定冲突处理、独立凭据与会话模型，以及跨入口回归测试。

### IB-1.1 新增决策索引

ADR-008 单Schema与角色能力见7.1；ADR-009 Node/PG单一职责见4.2.1；ADR-010 若依唯一认证集成见6.6；ADR-011 手间事务见9.3.1；ADR-012 RBAC组合见数据字典12.10。上述为本次修订采用的设计，运行实现均按对应门禁验证。

## 20. 技术评审清单

每项结论填写“通过 / 有条件通过 / 不通过”，并关联任务ID、验证证据与阻断状态；不以填写固定负责人代替交付闭环。

| 评审问题 | 结论 |
| --- | --- |
| Node 是否是玩家、俱乐部、房间、牌局和资金的唯一业务写入方？ | 待评审 |
| 若依是否只通过管理API执行核心业务操作？ | 待评审 |
| 买入、结算、离桌和人工调整是否具备持久化幂等？ | 待评审 |
| 同一桌是否存在唯一串行写入者？ | 待评审 |
| 结算、账本和Outbox是否在同一事务边界？ | 待评审 |
| LOCAL注册登录、失败锁定、会话接管和账号存在性保护是否有独立测试？ | 待评审 |
| 核心业务是否只引用稳定玩家ID，不引用登录名或TG字段？ | 待评审 |
| 玩家密码重置是否具备BP-32、单次凭据、全会话撤销和关闭门禁？ | 待评审 |
| 未公开牌是否在所有HTTP、WSS、回放和导出通道被服务端裁剪？ | 待评审 |
| 数据库账号和Schema权限是否阻止若依直接写核心表？ | 待评审 |
| 发布流程是否避免两个进程同时拥有同一桌？ | 待评审 |
| 备份是否完成过实际恢复演练？ | 待评审 |
| 500连接、50桌×8席的容量模型是否与真实动作率一致？ | 待评审 |
| 密码Pepper、会话密钥及历史Bot Token等凭据是否完成管理、轮换和交付扫描？ | 待评审 |
| 后续TG接口关闭时，首期Web启动、健康检查和E2E是否完全不依赖Bot？ | 待评审 |

## 21. 待项目组确认

以下信息会影响最终资源、周期和上线门槛，但不改变核心架构方向：

1. 生产部署地区、云厂商、预算和是否允许托管 PostgreSQL。
2. 可用性、RPO、RTO 和计划维护窗口。
3. 峰值在线人数、峰值活跃桌数、平均每分钟动作数和增长预期。
4. 正式资产币种、是否存在可兑换价值以及对应合规要求。
5. 已确定保留策略的存储容量、归档与清理资源。
6. 按 ADR-010 锁定 Java21/受维护Boot补丁、支持证据和兼容回归，不再保留旧栈生产分支。
7. 玩家密码重置的身份核实材料、批准交付渠道和默认30分钟有效期。
8. 后续Telegram阶段所需的Bot账号、域名、证书、Main Mini App、深链和凭据输入。

## 22. 术语表

| 术语 | 含义 |
| --- | --- |
| 模块化单体 | 一个主要部署单元，内部以明确模块和依赖边界组织 |
| 事实源 | 对某类业务数据拥有最终解释权和写入权的系统 |
| 桌内托管 | 玩家买入后留在牌桌结算范围内的资产 |
| 幂等 | 相同业务请求重复到达时只产生一次业务效果 |
| Outbox | 与业务事实同事务写入、提交后异步投递的事件表 |
| Actor/单写 | 同一房间任何时刻只有一个串行命令处理者 |
| epoch | 房间所有权代际，用于阻止旧实例继续提交 |
| 投影 | 从权威业务事实生成的只读查询或报表模型 |
| `UNKNOWN` | 调用方没有获得终态，但不能推断业务失败的状态 |

## 23. 依据与维护

本报告依据综合产品需求V1.2、PostgreSQL数据字典V1.4-review、运营后台需求V2.1-review、现有 Node.js 牌桌项目和既有改造方案形成。重点参考：

- 综合产品需求 V1.2（首期 Web 认证范围调整版）。
- `texas-holdem` 改造方案 V3.2、`README.md` 与 `package.json`。
- 运营后台架构与模块边界 V1，以及运营后台需求 V2.1-review。
- PostgreSQL 数据字典与 Flyway 实施基线 V1.4-review。

维护规则：

- 核心架构、数据所有权或API契约变化必须更新本报告和对应ADR。
- 安全章节至少每季度复核一次。
- 每次正式发布记录应用版本、数据库迁移版本和报告版本。
- 本报告描述目标架构和实施门槛，不应用于证明功能已经开发或验收通过。


---

> 本文为IB-1.1完整摘录/规范化收录。与本包[统一基线](../docs/baseline.html)和[冲突裁定](../docs/decisions.html)配套执行；旧来源状态不代表软件完成。

# 风暴扑克 PostgreSQL 数据字典

版本：V1.5-review（IB-1.1）  
生成日期：2026-10-21  
数据库：PostgreSQL 16+  
默认 Schema：`poker`  
状态：依据需求推导的技术评审稿；已纳入方案 A 的数据库强约束裁定、跨表约束责任矩阵及需求覆盖复审修订，不是已执行 DDL

## 1. 文档目的与依据

本文把产品需求、运营后台需求、设计字段契约和参考项目实现统一为可落地的 PostgreSQL 逻辑数据模型，供后端实现、DDL 编写、接口评审、测试造数和验收追踪使用。

推导优先级如下：

1. `docs/docs/product.html` 及其 `docs/config.html`。
2. `文档/运营后台需求文档-V2` 中的 PRD、模块、流程与权限矩阵。
3. `ui/player/docs/ui-contract.html`。
4. `texas-holdem` 的 `docs/schema.sql`、`docs/数据库字段.md` 与存储代码，仅作既有实现和迁移线索。

参考项目中的 `th_accounts`、`th_rooms`、`th_hands`、`th_login_logs` 等概念被保留，但以下实现不沿用：

- 金额使用 `double precision`；新模型统一使用整数最小单位 `bigint`。
- 用嵌套快照表直接表达业务账；新模型采用复式账本和不可变业务记录。
- 用昵称、数组位置或 JSON 路径充当业务关联；新模型使用稳定主键和显式外键。
- 每个玩家仅保留最近 3000 手；新模型改为按统一保留策略归档和游标分页查询，V1先使用普通表与时间索引，达到容量阈值后再按ADR-DB-001评审分区。
- `is_admin` 单布尔权限；新模型使用独立后台身份、角色、动作权限和资源范围。

## 2. 设计基线

### 2.1 命名和类型

| 项目 | 约定 |
| --- | --- |
| 表、字段 | `snake_case`；表名使用单数名词 |
| 内部主键 | `uuid`，默认 `gen_random_uuid()`；不向普通页面暴露顺序信息 |
| 外部业务号 | `varchar(32~64)`，带对象前缀，例如 `USR_`、`ROM_`、`HND_` |
| 金额 | `bigint`，单位为对应资产的最小单位；当前精度 2 时 `100` 表示 `1.00` |
| 账本分录 | `delta_amount bigint`；正数增加账户余额、负数减少账户余额，同一事务合计必须为 0 |
| 比例 | `numeric(9,6)`，范围 `0 <= value <= 1` |
| 高精度计提 | `numeric(30,12)`，日汇总后才向下取到资产精度 |
| 时间 | `timestamptz`，数据库存 UTC；展示统一转 `Asia/Shanghai` |
| 业务日 | `date`，明确按 `Asia/Shanghai` 计算 |
| IP | `inet` |
| 可扩展属性 | 仅低频、非核心查询字段允许 `jsonb`；账务、权限、状态和关联不得藏入 JSON |
| 状态枚举 | 首期用 `varchar + CHECK`，避免 PostgreSQL 原生 ENUM 阻碍灰度演进 |

### 2.2 标记

| 标记 | 含义 |
| --- | --- |
| PK | 主键 |
| FK | 外键 |
| UQ | 唯一约束 |
| CK | 检查约束 |
| IDX | 普通索引 |
| PII | 个人或敏感信息，接口必须按权裁剪 |
| SECRET | 密钥、令牌或私牌数据，不得写普通日志或导出 |

### 2.3 通用字段

除不可变明细表和明确使用共享主键的一对一表另有说明外，业务实体默认包含以下字段。后续各表不重复列出时，仍视为包含这些字段。`user_preference`、`user_timebank` 使用 `user_id` 作为共享主键，不再额外包含 `id`。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `id` | `uuid` | PK | 内部主键 |
| `created_at` | `timestamptz` | NOT NULL, default `now()` | 服务端创建时间 |
| `updated_at` | `timestamptz` | NOT NULL, default `now()` | 最近一次持久化更新时间；不得冒充业务发生时间 |
| `row_version` | `bigint` | NOT NULL, default `0` | 乐观锁版本；更新时递增 |

不可变流水表只保留 `id`、业务发生时间和 `created_at`，禁止更新或软删。历史对象原则上不物理删除；状态终止、归档或法定清理应保留独立审计记录。

### 2.4 已接受的 P0 架构决策

| ADR | 决策 | V1 处理 | 放弃/延后 |
| --- | --- | --- | --- |
| ADR-DB-001 | 全局唯一约束优先于提前分区 | 账本、手牌事件、审计、聊天和分析事件均先使用普通表及时间索引 | 达到容量阈值后再引入全局 ID 注册表和时间分区，不在 V1 承担复合主键传播成本 |
| ADR-DB-002 | 私牌授权目标关系化 | 申请目标和实际访问目标使用子表；私牌只允许通过受限函数读取 | 不使用 `uuid[]` 承载授权边界，不允许应用角色直接查询私牌密文 |
| ADR-DB-003 | 座位竞争使用统一占用行 | 每个物理座位一条 `room_seat_occupancy`，预约、买入和离座均锁同一行 | 不依赖两张业务表各自的唯一索引解决跨表竞争，不以约定式 advisory lock 作为主方案 |
| ADR-DB-004 | 账本采用有符号零和分录 | 正数增加、负数减少；POSTED 事务分录合计为 0；冲正新建交易 | 不使用未冻结会计口径的 `D/C` 字段，不修改已 POSTED 原交易表达冲正 |
| ADR-DB-005 | 动作请求与动作事实分离 | `hand_action_request` 保存接受和拒绝结果，`hand_action` 只保存已接受事实 | 不让失败请求随事务异常回滚，不依赖内存缓存实现 action_id 幂等 |
| ADR-DB-006 | 资金授权和代理归因由数据库防重 | 调款授权与操作复合绑定且只能消费一次；原始归因和冲正分别使用部分唯一索引 | 不使用包含可空列的普通唯一约束表达原始归因唯一性，不只依赖服务层判重 |
| ADR-DB-007 | 消息发送者显式建模 | 玩家、后台和系统发送者分别约束幂等；用户屏蔽独立关系化 | 不把系统消息冒充后台人员消息，不把屏蔽列表藏入偏好 JSON/数组 |
| ADR-DB-008 | 存储状态与展示状态分离 | 账本存储状态保持 `PENDING/POSTED/FAILED`；`REVERSED` 由有效冲正交易派生 | 不更新原 POSTED 交易来迎合前端状态枚举 |
| ADR-DB-009 | 相同规则允许创建多个独立房间快照 | `room_rule_snapshot.content_digest` 仅作校验与普通索引，每个房间持有独立不可变快照 | 不以全局摘要唯一约束误阻止相同模板重复开房，也不在V1共享房间快照 |
| ADR-DB-010 | 请求幂等与领域状态轨迹分离 | `business_operation` 保存请求结果；一对一领域结果唯一绑定操作；邀请申请的多次状态迁移写追加事件 | 不用一个 `operation_id` 同时冒充申请、审核、撤销等多次操作 |
| ADR-DB-011 | 权限、代理与禁言关系使用数据库排斥约束 | 活动记录防重、有效区间不得重叠，当前字段和历史在受限函数内原子同步 | 不仅依赖应用查询后再写入，不允许重复活动授权掩盖撤权 |
| ADR-DB-012 | 高风险授权必须参数绑定并由受限函数消费 | 权限变更、私牌审批/读取和资金调整均复合绑定 `sensitive_authorization` 与 `business_operation` | 不允许应用角色直接更新高风险终态，不接受只在接口层检查TOTP |
| ADR-DB-013 | 恢复资金按明细关系化 | `recovery_case_item` 记录玩家、资产、账户、原交易和最终处置，案件总额由明细汇总 | 不用单个无资产的 `frozen_amount` 充当资金事实 |
| ADR-DB-014 | 恢复快照采用检查点加事件重放 | `room_state_snapshot` 只保存周期检查点；恢复时选择不超过 `room.state_version` 的最新完整快照并重放后续事件 | 不要求每个动作版本写完整快照，不把 `room.state_version` 冒充快照外键 |
| ADR-DB-015 | 玩家账号与认证身份分离 | `app_user` 只承载稳定玩家身份；`player_identity` 统一 LOCAL/TELEGRAM 来源；本地口令单独存入 `local_credential` | 不把 Telegram 字段写入玩家主表，不让绑定外部身份新建钱包、归属或战绩，不让玩家凭据进入后台认证域 |

上述决策是数据模型与 Flyway DDL 的强制边界。替代方案只有在新 ADR 说明容量证据、迁移路径和回滚方式后才能采用。

## 3. 领域关系总览

```mermaid
flowchart LR
  U[app_user 玩家] --> M[club_membership 归属历史]
  U --> PI[player_identity 认证身份]
  PI --> LC[local_credential 本地口令]
  U --> PS[player_session 操控会话]
  M --> C[club 俱乐部]
  C --> R[room 房间]
  R --> SO[room_seat_occupancy 座位占用]
  SO --> SS[seat_session 入座资金会话]
  R --> SS[seat_session 入座资金会话]
  SS --> H[hand 手牌]
  H --> HAR[hand_action_request 动作请求]
  HAR --> HA[hand_action 已接受动作]
  H --> P[hand_pot 底池]
  H --> LS[ledger_transaction 账务事务]
  U --> LA[ledger_account 账务账户]
  LS --> LE[ledger_entry 复式分录]
  H --> CA[commission_attribution 分成归因]
  CA --> DS[commission_daily_statement 代理日账]
  AU[admin_user 后台人员] --> BO[business_operation 操作结果]
  BO --> AL[audit_log 审计]
  T[support_ticket 工单] --> PA[private_card_access_request 私牌专项]
  PA --> PT[private_card_access_request_player 批准目标]
  PA --> PL[private_card_access_log 逐次访问]
  PL --> PRT[private_card_access_log_player 实际目标]
  PL --> AL
  U --> UCB[user_chat_block 用户屏蔽]
```

文字说明：玩家核心业务只引用稳定 `app_user.id`；本地登录和未来 Telegram 绑定均通过 `player_identity` 解析到同一玩家，本地口令与外部资料不进入钱包、俱乐部或牌局主键。玩家在一个时点只有一个当前俱乐部归属；房间引用不可变规则快照；每个座位通过统一占用行仲裁预约和入座，一次入座对应一个资金会话；每手先持久化动作请求结果，再由已接受动作、牌、底池、派奖和零和账务共同构成；私牌目标关系化并逐次授权审计；聊天屏蔽是接收侧关系，不删除消息或屏蔽系统提示；后台人员只通过业务操作请求权威服务，不能直接改余额、筹码、牌序或结算终态。

## 4. 身份与玩家域

### 4.1 `app_user` — 玩家主账号

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `game_id` | `varchar(32)` | NOT NULL, UQ | 对外稳定玩家 ID，不因登录名、昵称或外部身份变化而改变 |
| `display_name` | `varchar(20)` | NOT NULL | 玩家展示昵称；去首尾空格后 2–20 个可见 Unicode 字符，允许重复；控制字符和纯空白由服务端拒绝 |
| `avatar_url` | `text` | NULL | 头像地址；失效时客户端用默认头像 |
| `status` | `varchar(24)` | NOT NULL, CK `ACTIVE/DISABLED` | 禁用只阻止新准入，不没收资产 |
| `disabled_reason` | `varchar(500)` | NULL | 禁用原因；仅后台按权可见 |
| `disabled_at` | `timestamptz` | NULL | 禁用生效时间 |
| `registered_at` | `timestamptz` | NOT NULL | 新环境真实注册时间；旧数据未知时不得写入主表或用 `updated_at` 补造，只能留在可空的只读迁移暂存表 |
| `session_generation` | `bigint` | NOT NULL, default 0, CK >=0 | 玩家操控会话代际，只增不减；不是设备编号 |
| `last_login_at` | `timestamptz` | NULL | 最近一次任一合法身份完整登录成功时间 |

索引：`(status, registered_at desc, id)`、`lower(display_name)` 的 `pg_trgm` GIN 索引；昵称不唯一。注册只创建普通玩家；`app_user` 不包含后台角色、初始余额或 Telegram 专用字段。

### 4.2 `player_identity` — 玩家认证身份

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 统一玩家；绑定身份不得创建第二套玩家、钱包、归属或战绩 |
| `provider` | `varchar(24)` | NOT NULL, CK `LOCAL/TELEGRAM` | 认证提供者；首期只开放 LOCAL，TELEGRAM 为后续接入预留 |
| `provider_subject` | `varchar(128)` | NOT NULL, PII | 提供者内稳定键；LOCAL 为小写规范化登录名，TELEGRAM 为十进制 `user.id` 字符串 |
| `provider_username` | `varchar(64)` | NULL, PII | 外部 username 快照，可变且不作账号键；LOCAL 为空 |
| `provider_display_name` | `varchar(128)` | NULL, PII | 外部展示名快照；仅在玩家显式选择时同步到主账号资料 |
| `provider_avatar_url` | `text` | NULL, PII | 外部头像快照；不自动覆盖主账号资料 |
| `verified_at` | `timestamptz` | NOT NULL | 本次身份完成服务端验证时间；TG 接入后须先校验 `initData` 和时效 |
| `bound_at` | `timestamptz` | NOT NULL | 绑定到统一玩家的时间 |
| `unbound_at` | `timestamptz` | NULL | 外部身份解绑时间；LOCAL 登录停用使用凭据状态而非解绑 |
| `last_authenticated_at` | `timestamptz` | NULL | 该身份最近一次成功认证时间 |

约束：`UNIQUE(provider, provider_subject)` 防止同一身份属于两个玩家；部分唯一索引 `UNIQUE(user_id, provider) WHERE unbound_at IS NULL` 防止同一玩家同时存在两个活动同源身份。LOCAL subject 必须匹配 `^[a-z0-9_]{4,32}$`；TELEGRAM subject 必须是非零开头十进制数字。用户名展示、TG username 和 TG display name 永远不作业务关联键。

### 4.3 `local_credential` — 本地登录凭据

使用 `identity_id` 作为与 `player_identity` 的共享主键；除该主键外仍包含 `created_at/updated_at/row_version`。登录名只存于对应 LOCAL 身份的 `provider_subject`，不在凭据表重复保存。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `identity_id` | `uuid` | PK, FK → `player_identity.id` | 一条 LOCAL 身份最多一条本地凭据 |
| `provider` | `varchar(24)` | NOT NULL, default `'LOCAL'`, CK `LOCAL` | 用于复合外键保证凭据只能挂到 LOCAL 身份 |
| `password_hash` | `varchar(255)` | NOT NULL, SECRET | Argon2id 或经评审的现代口令哈希；禁止明文、可逆密文、空值及写普通日志 |
| `failed_login_count` | `smallint` | NOT NULL, default 0, CK 0–5 | 连续失败次数；成功后清零，第 5 次失败进入锁定 |
| `locked_until` | `timestamptz` | NULL | 连续 5 次失败后至少锁定 15 分钟；到期收口和失败计数更新须原子执行 |
| `password_changed_at` | `timestamptz` | NOT NULL | 最近一次设置或重置口令时间 |
| `status` | `varchar(24)` | NOT NULL, CK `ACTIVE/RESET_REQUIRED/DISABLED` | 本地凭据状态，不等同于玩家资产状态 |
| `last_failed_at` | `timestamptz` | NULL | 最近一次口令失败时间，供安全审计和锁定计算 |

约束：`(identity_id, provider)` 复合外键必须命中 `player_identity(id, provider)` 且 provider 固定为 LOCAL；`password_hash` 至少 20 个字符且不得为空白。输入密码 8–72 个字符、IP 每分钟最多 30 次属于认证服务与限流存储的入口规则，不保存原始密码。首个注册玩家不得由数据库种子或服务逻辑自动获得 `admin_user`、后台角色或初始余额。

### 4.4 `player_session` — 玩家操控会话

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `session_generation` | `bigint` | NOT NULL, CK >0 | 本次会话创建时复制的玩家代际；UNIQUE(user_id,session_generation) |
| `identity_id` | `uuid` | FK → `player_identity.id`, NOT NULL | 建立本次会话所使用的认证身份；业务授权仍以 `user_id` 为准 |
| `session_token_hash` | `bytea` | NOT NULL, UQ, SECRET | 仅存会话令牌摘要 |
| `device_id_hash` | `bytea` | NULL, PII | 设备稳定摘要，不存可逆设备指纹 |
| `user_agent` | `varchar(1024)` | NULL, PII | 设备摘要来源 |
| `ip_address` | `inet` | NULL, PII | 建立会话时 IP |
| `authenticated_at` | `timestamptz` | NOT NULL | 本次身份认证完成时间 |
| `expires_at` | `timestamptz` | NOT NULL | 最长 24 小时 |
| `revoked_at` | `timestamptz` | NULL | 新设备接管、退出或安全事件撤销时间 |
| `revoke_reason` | `varchar(64)` | NULL | `DEVICE_TAKEOVER/LOGOUT/EXPIRED/ADMIN_DISABLED/GENERATION_MIGRATION` 等 |
| `active_room_id` | `uuid` | FK → `room.id`, NULL | 当前真人桌恢复入口；同一玩家最多一个活动值 |

约束：`identity_id` 必须属于同一 `user_id`；部分唯一索引 `UNIQUE(user_id) WHERE revoked_at IS NULL`，确保一个未撤销操控会话。建立新会话必须调用受限函数：先锁定 `app_user`，把 `expires_at <= now()` 但尚未撤销的旧会话写为 `revoked_at=now(), revoke_reason='EXPIRED'`，再撤销其他接管会话并插入新会话；所有鉴权同时要求 `revoked_at IS NULL AND expires_at > now()`。不得把依赖 `now()` 的条件写入部分索引，客户端也不得仅凭 `user_id` 恢复会话。

代际写入协议：认证成功后 create_player_session 先锁 app_user，撤销旧会话、将 app_user.session_generation 加1，再以该值创建 player_session，同事务写审计和接管通知。普通 WSS 重连沿用原会话/代际，不递增；退出、禁用、密码重置撤销会话并推进代际。迁移 V015 将历史会话全部撤销，历史会话按(created_at,id)编号，玩家计数置为其历史最大代际（无历史置0）；上线后重新登录取得更大的正数代际，禁止给仍活动的旧会话猜测代际。

每个动作必须在事务内锁同一 app_user，要求 token 命中会话、会话未撤销且未过期、信封代际=player_session.session_generation=app_user.session_generation，才可持锁提交。登录接管也争同一锁，因此接管提交后旧连接不能提交新动作；此前已持锁的动作按提交先后线性化。旧连接关闭只是通知优化，不能代替每次鉴权。代际不一致返回 SESSION_REPLACED。受限会话/动作函数未实现前保持关闭。

### 4.5 `player_login_event` — 玩家登录审计

不可变。V1 使用普通表并按 `occurred_at` 建索引，以保留单列 UUID 主键和跨时间全局约束；达到容量阈值后再按 ADR-DB-001 演进。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `occurred_at` | `timestamptz` | NOT NULL | 服务端收到请求时间 |
| `method` | `varchar(24)` | NOT NULL | `LOCAL_REGISTER/LOCAL_PASSWORD/SESSION_RESUME/DEVICE_TAKEOVER/TG_AUTH/TG_BIND` |
| `user_id` | `uuid` | FK → `app_user.id`, NULL | 未识别账号时为空，审计记录仍保留 |
| `identity_id` | `uuid` | FK → `player_identity.id`, NULL | 已识别身份；失败或会话恢复事件可为空 |
| `auth_provider` | `varchar(24)` | NULL, CK `LOCAL/TELEGRAM` | 本次认证来源；与未识别账号的失败事件一起保留 |
| `login_identifier_hash` | `bytea` | NULL, PII | 登录名或外部 subject 的带密钥不可逆摘要；不存密码、原始 initData 或会话令牌 |
| `success` | `boolean` | NOT NULL | 是否成功 |
| `failure_code` | `varchar(64)` | NULL | 安全可记录的失败码，不存凭据 |
| `ip_address` | `inet` | NULL, PII | 经可信代理解析后的来源 IP |
| `user_agent` | `varchar(1024)` | NULL, PII | 客户端摘要 |
| `request_id` | `uuid` | NULL | 链路请求号 |

索引：`(user_id, occurred_at desc)`、`(occurred_at desc)`；IP 查询另验 `BP-05`。

### 4.6 `user_preference` — 玩家偏好

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `user_id` | `uuid` | PK, FK → `app_user.id` | 一人一行 |
| `card_theme` | `varchar(24)` | NOT NULL | `CLASSIC/FOUR_COLOR/FULL_COLOR/RANK_ONLY` |
| `table_theme` | `varchar(24)` | NOT NULL | `EMERALD/GRAPHITE/MIDNIGHT_BLUE` |
| `card_back_theme` | `varchar(24)` | NOT NULL | `CLASSIC_RED/DEEP_BLUE/INK_GREEN` |
| `sound_enabled` | `boolean` | NOT NULL, default false | 账号偏好；设备授权另行处理 |
| `vibration_enabled` | `boolean` | NOT NULL, default false | 同上 |
| `hide_balance` | `boolean` | NOT NULL, default false | 仅显示偏好，不改变权限 |
| `quick_bets` | `varchar(16)[]` | NOT NULL | 3–5 个去重选项；服务端校验候选集 |
| `preference_version` | `integer` | NOT NULL | 主题下架或规则变更时迁移版本 |

### 4.7 `user_timebank` — 账号级时间银行

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `user_id` | `uuid` | PK, FK → `app_user.id` | 跨房间、换座、重买不重置 |
| `remaining_ms` | `integer` | NOT NULL, CK 0–60000 | 当前剩余时间；初始 30000 |
| `valid_hand_count` | `bigint` | NOT NULL, default 0 | 累计有效手数 |
| `last_bonus_hand_count` | `bigint` | NOT NULL, default 0 | 防止每 10 手奖励重复发放 |

### 4.8 `protocol_acceptance` — 协议接受记录

不可变。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `protocol_type` | `varchar(32)` | NOT NULL | `TERMS/PRIVACY/RULE_DISCLOSURE` |
| `protocol_version` | `varchar(32)` | NOT NULL | 正式发布版本 |
| `content_digest` | `bytea` | NOT NULL | 接受内容摘要 |
| `accepted_at` | `timestamptz` | NOT NULL | 服务端确认时间 |
| `room_id` | `uuid` | FK → `room.id`, NULL | 房间规则披露接受时关联 |
| `rule_snapshot_id` | `uuid` | FK → `room_rule_snapshot.id`, NULL | 对应冻结规则 |
| `source` | `varchar(24)` | NOT NULL | `WEB_CLIENT/TG_CLIENT/ROOM_BUYIN`；首期注册协议来自 WEB_CLIENT |

唯一约束：`(user_id, protocol_type, protocol_version, coalesce(room_id, zero_uuid))`。

## 5. 组织、代理与邀请域

### 5.1 `agent` — 代理实体

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `agent_code` | `varchar(32)` | NOT NULL, UQ | 稳定代理业务 ID |
| `name` | `varchar(80)` | NOT NULL | 当前名称；历史显示使用快照 |
| `status` | `varchar(24)` | NOT NULL, CK `ACTIVE/DISABLED` | 停用不删除历史计提 |
| `manager_agent_id` | `uuid` | FK → `agent.id`, NULL | 仅管理关系，不自动产生多层佣金 |
| `created_by_admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 创建人 |
| `registered_at` | `timestamptz` | NOT NULL | 代理建立时间 |

### 5.2 `agent_agreement_version` — 代理协议/等级版本

发布后不可覆盖。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `agreement_code` | `varchar(32)` | NOT NULL | 协议族 ID |
| `version_no` | `integer` | NOT NULL | 递增版本 |
| `agent_id` | `uuid` | FK → `agent.id`, NOT NULL | 代理 |
| `level_code` | `varchar(32)` | NOT NULL | 默认 `GENERAL` |
| `rate` | `numeric(9,6)` | NOT NULL, CK 0–1 | GENERAL 默认 0；不得超操作者上限 |
| `status` | `varchar(24)` | NOT NULL | `DRAFT/PUBLISHED/RETIRED/CONFIG_ERROR` |
| `effective_from` | `timestamptz` | NULL | 发布后的生效时间；新手引用 |
| `effective_to` | `timestamptz` | NULL | 版本结束时间，左闭右开 |
| `published_by_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 发布人 |
| `content_digest` | `bytea` | NOT NULL | 防止版本内容被静默修改 |

唯一约束：`(agreement_code, version_no)`；同代理有效区间不得重叠（建议 `tstzrange` 排斥约束）。

### 5.3 `club` — 俱乐部

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `club_code` | `varchar(32)` | NOT NULL, UQ | 对外俱乐部 ID |
| `name` | `varchar(80)` | NOT NULL | 名称 |
| `avatar_url` | `text` | NULL | 头像 |
| `description` | `varchar(500)` | NULL | 简介 |
| `status` | `varchar(24)` | NOT NULL | `ACTIVE/FROZEN/ARCHIVED` |
| `is_default` | `boolean` | NOT NULL, default false | 系统保底俱乐部；禁止冻结和归档 |
| `direct_agent_id` | `uuid` | FK → `agent.id`, NULL | 首期最多一个直接代理；空表示平台 |
| `allow_player_create` | `boolean` | NOT NULL, default false | 玩家开房总开关 |
| `frozen_at` | `timestamptz` | NULL | 冻结时间 |
| `archived_at` | `timestamptz` | NULL | 归档时间 |
| `status_reason` | `varchar(500)` | NULL | 冻结/归档原因 |

约束：全库最多一条 `is_default=true`；默认俱乐部状态必须为 `ACTIVE`。

### 5.4 `club_agent_history` — 俱乐部直接代理历史

历史记录除关闭当前有效区间时首次写入 `effective_to` 外不可修改；已关闭区间完全不可变。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `club_id` | `uuid` | FK → `club.id`, NOT NULL | 俱乐部 |
| `agent_id` | `uuid` | FK → `agent.id`, NULL | 空表示平台归因 |
| `effective_from` | `timestamptz` | NOT NULL | 生效起点 |
| `effective_to` | `timestamptz` | NULL | 结束时点 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL | 变更操作 |
| `agent_code_snapshot` | `varchar(32)` | NULL | 历史展示快照 |
| `agent_name_snapshot` | `varchar(80)` | NULL | 历史展示快照 |

约束：`effective_to IS NULL OR effective_to > effective_from`；`UNIQUE(club_id) WHERE effective_to IS NULL`；使用 `btree_gist` 建立同俱乐部 `tstzrange(effective_from, coalesce(effective_to, 'infinity'), '[)')` 不重叠的排斥约束；`operation_id` 唯一。应用角色不得直接写入本表或 `club.direct_agent_id`，只能调用 `change_club_agent`，在同一事务内锁定俱乐部、关闭旧区间、创建新区间、更新当前代理并写审计。

### 5.5 `club_membership` — 玩家归属与迁移历史

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `club_id` | `uuid` | FK → `club.id`, NOT NULL | 目标俱乐部 |
| `agent_id_snapshot` | `uuid` | FK → `agent.id`, NULL | 生效时直接代理快照 |
| `status` | `varchar(24)` | NOT NULL | `PENDING/CURRENT/ENDED/CANCELLED` |
| `source_club_id` | `uuid` | FK → `club.id`, NULL | 迁移来源；首次归属为空 |
| `requested_at` | `timestamptz` | NOT NULL | 提交时间 |
| `effective_at` | `timestamptz` | NULL | 实际生效时间 |
| `ended_at` | `timestamptz` | NULL | 归属终止时间 |
| `wait_hand_id` | `uuid` | FK → `hand.id`, NULL | 有在手时等待完成的手 |
| `cancel_code` | `varchar(64)` | NULL | 撤权、目标冻结等取消原因 |
| `reason` | `varchar(500)` | NOT NULL | 迁移原因 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL, UQ | 幂等业务操作；一次迁移只创建一条目标归属记录 |

约束：每个玩家最多一条 `CURRENT`、最多一条 `PENDING` 的部分唯一索引。生效前再次校验双侧权限和目标 `ACTIVE`。

### 5.6 `club_template_allowlist` — 玩家开房模板白名单

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `club_id` | `uuid` | FK → `club.id`, NOT NULL | 俱乐部 |
| `rule_template_version_id` | `uuid` | FK → `rule_template_version.id`, NOT NULL | 仅已发布版本 |
| `enabled` | `boolean` | NOT NULL | 是否允许 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL | 授权操作 |

唯一约束：`(club_id, rule_template_version_id)`。

### 5.7 `invite` — ROOM/CLUB 业务邀请

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `invite_code` | `char(6)` | NULL, UQ | 大写短码，排除 `0/O/1/I`；可与深链并存 |
| `token_hash` | `bytea` | NOT NULL, UQ, SECRET | 深链不透明 token 的摘要；原 token 不落日志/导出 |
| `target_type` | `varchar(16)` | NOT NULL, CK `ROOM/CLUB` | 邀请目标类型 |
| `target_id` | `uuid` | NOT NULL | 目标 ID；由服务层按类型校验 |
| `policy` | `varchar(32)` | NOT NULL | `EXPIRING_24H/PERMANENT_REVIEW` |
| `issuer_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 后台签发者 |
| `issuer_user_id` | `uuid` | FK → `app_user.id`, NULL | 获授权的玩家签发者 |
| `expires_at` | `timestamptz` | NULL | 永久审核策略可为空；ROOM 仍受关闭约束 |
| `revoked_at` | `timestamptz` | NULL | 撤销时间 |
| `revoked_by_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 撤销人 |
| `revoke_reason` | `varchar(500)` | NULL | 撤销原因 |
| `status_hint` | `varchar(24)` | NOT NULL | `ACTIVE/REVOKED`；`EXPIRED/TARGET_UNAVAILABLE` 查询时派生 |

约束：`issuer_admin_id` 与 `issuer_user_id` 恰有一个非空。

### 5.8 `invite_application` — 邀请申请与审核

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `application_code` | `varchar(32)` | NOT NULL, UQ | 对外申请号 |
| `invite_id` | `uuid` | FK → `invite.id`, NOT NULL | 来源邀请 |
| `applicant_user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 申请人 |
| `status` | `varchar(24)` | NOT NULL | `PENDING/APPROVED/REJECTED/WITHDRAWN/EXPIRED/FROZEN/CANCELLED` |
| `reviewer_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 审核人 |
| `reviewed_at` | `timestamptz` | NULL | 审核时间 |
| `review_reason` | `varchar(500)` | NULL | 审核理由；与玩家公开结论分离 |
| `membership_id` | `uuid` | FK → `club_membership.id`, NULL | CLUB 审批后产生的即时或待生效归属 |
| `room_access_status` | `varchar(24)` | NULL | ROOM 访问 `PENDING/GRANTED/REVOKED/EXPIRED` |
| `submit_operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL, UQ | 创建申请的幂等操作 |
| `review_operation_id` | `uuid` | FK → `business_operation.id`, NULL, UQ | 批准或拒绝操作；PENDING 时为空，与提交操作分离 |

唯一约束：同一邀请、同一申请人最多一个未决申请；并发审核锁定申请行并以唯一 `review_operation_id` 保证一个审核终态。审核操作通过 `business_operation.parent_operation_id` 引用提交操作；撤销、冻结、失效和生效轨迹写入追加事件，不覆盖原操作号。

### 5.9 `invite_application_event` — 邀请申请状态轨迹

不可变；申请、审核、撤回、邀请撤销联动、目标冻结、失效和归属生效均追加事件。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `application_id` | `uuid` | FK → `invite_application.id`, NOT NULL | 邀请申请 |
| `seq_no` | `integer` | NOT NULL | 申请内递增序号 |
| `from_status` | `varchar(24)` | NULL | 创建事件为空 |
| `to_status` | `varchar(24)` | NOT NULL | 新状态 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL | 触发该次迁移的幂等操作；批量冻结/撤销可影响多个申请 |
| `operator_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 后台审核或处置人；玩家/系统事件为空 |
| `reason_code` | `varchar(64)` | NOT NULL | 稳定原因码 |
| `reason_text` | `varchar(500)` | NULL | 安全可展示或内部原因，按接口裁剪 |
| `occurred_at` | `timestamptz` | NOT NULL | 权威发生时间 |

唯一约束：`(application_id, seq_no)`、`(operation_id, application_id)`。状态更新与事件插入必须在同一受限函数事务内完成；事件不可更新或删除。

### 5.10 `invite_redemption` — 邀请校验和使用事实

不可变。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `invite_id` | `uuid` | FK → `invite.id`, NOT NULL | 邀请 |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 使用人 |
| `application_id` | `uuid` | FK → `invite_application.id`, NULL | 审核型邀请关联申请 |
| `result` | `varchar(32)` | NOT NULL | `VALIDATED/ACCESS_GRANTED/REJECTED` |
| `failure_code` | `varchar(64)` | NULL | 过期、撤销、房间关闭等 |
| `occurred_at` | `timestamptz` | NOT NULL | 发生时间 |
| `request_id` | `uuid` | NOT NULL, UQ | 幂等及旅程归因 |
| `parameter_digest` | `bytea` | NOT NULL | 规范化邀请、用户、申请和校验用途；同号异参数拒绝 |

重复 `request_id` 且摘要相同返回首次保存的 `result/failure_code`，摘要不同返回 `IDEMPOTENCY_CONFLICT`，不得在邀请状态变化后重新解释原请求。

## 6. 规则、费用与系统配置域

### 6.1 `fee_template_version` — 抽水模板版本

发布后不可变。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `fee_code` | `varchar(32)` | NOT NULL | 例如 `CSV_STANDARD_V2` |
| `version_no` | `integer` | NOT NULL | 递增版本 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 费率模板资产 |
| `rake_rate` | `numeric(9,6)` | NOT NULL, CK 0–1 | 默认 5% 或 3% |
| `rake_cap_amount` | `bigint` | NOT NULL, CK >=0 | 明确金额封顶；房间快照同时保存对应 BB |
| `postflop_only` | `boolean` | NOT NULL, default true | 未发翻牌费为 0 |
| `whole_hand_cap` | `boolean` | NOT NULL, default true | 全手只封顶一次 |
| `rounding_mode` | `varchar(24)` | NOT NULL | 当前 `FLOOR_TO_PRECISION` |
| `status` | `varchar(24)` | NOT NULL | `DRAFT/PUBLISHED/RETIRED` |
| `effective_from` | `timestamptz` | NULL | 发布生效时间 |
| `published_by_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 发布人 |
| `content_digest` | `bytea` | NOT NULL | 内容摘要 |

唯一约束：`(fee_code, version_no)`。

### 6.2 `exit_fee_template_version` — 提前盈利离座费版本

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `exit_fee_code` | `varchar(32)` | NOT NULL | 默认 `EARLY_EXIT_PROFIT_V2` |
| `version_no` | `integer` | NOT NULL | 版本 |
| `profit_rate` | `numeric(9,6)` | NOT NULL, CK 0–1 | 默认 30% |
| `exempt_natural_end` | `boolean` | NOT NULL, default true | 自然到期豁免 |
| `exempt_operator_close` | `boolean` | NOT NULL, default true | 运营关闭/禁用/移除豁免 |
| `exempt_service_failure` | `boolean` | NOT NULL, default true | 服务故障豁免 |
| `exempt_no_valid_hand` | `boolean` | NOT NULL, default true | 无有效手豁免 |
| `status` | `varchar(24)` | NOT NULL | `DRAFT/PUBLISHED/RETIRED` |
| `effective_from` | `timestamptz` | NULL | 生效时间 |
| `published_by_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 发布人 |
| `content_digest` | `bytea` | NOT NULL | 摘要 |

### 6.3 `rule_template` — 规则模板族

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `template_code` | `varchar(32)` | NOT NULL, UQ | 模板稳定 ID |
| `name` | `varchar(80)` | NOT NULL | 模板名称 |
| `owner_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 运营草稿所属人；超管模板可为空 |
| `description` | `varchar(500)` | NULL | 用途说明 |

### 6.4 `rule_template_version` — 可发布规则版本

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `template_id` | `uuid` | FK → `rule_template.id`, NOT NULL | 模板族 |
| `version_no` | `integer` | NOT NULL | 版本号 |
| `status` | `varchar(24)` | NOT NULL | `DRAFT/PUBLISHED/RETIRED` |
| `deck_mode` | `varchar(16)` | NOT NULL | `LONG/SHORT` |
| `betting` | `varchar(8)` | NOT NULL, CK `NLH` | 本期不支持 Limit |
| `seat_count` | `smallint` | NOT NULL | 长牌 8、短牌 6 |
| `room_seconds` | `integer` | NOT NULL | 长牌 7200/10800，短牌 3600 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 币种 |
| `sb_amount` | `bigint` | NOT NULL, CK >0 | 小盲 |
| `bb_amount` | `bigint` | NOT NULL, CK >0 | 大盲；应为最小单位 2 的倍数，且 `sb*2=bb` |
| `buyin_min_amount` | `bigint` | NOT NULL, CK >0 | 最小买入 |
| `buyin_max_amount` | `bigint` | NOT NULL, CK >= min | 最大买入 |
| `ante_mode` | `varchar(16)` | NOT NULL | `OFF/EACH/BB_PAYS` |
| `ante_amount` | `bigint` | NOT NULL, CK >=0 | OFF 时为 0 |
| `straddle_mode` | `varchar(24)` | NOT NULL | `OFF/FORCED_UTG_2BB` |
| `start_players` | `smallint` | NOT NULL | 2 到座位上限 |
| `allow_spectate` | `boolean` | NOT NULL | 默认允许 |
| `delay_mode` | `varchar(24)` | NOT NULL | `OFF/BOARD_EACH_STREET/HOLE_PREFLOP` |
| `vpip_threshold` | `smallint` | NULL, CK 1–100 | 空表示关闭 |
| `absence_mode` | `varchar(32)` | NOT NULL | `EXIT_AFTER_HAND/AUTO_PLAY_UNTIL_DEADLINE` |
| `absence_deadline_mode` | `varchar(24)` | NOT NULL | `FIXED_SECONDS/ROOM_END` |
| `absence_seconds` | `integer` | NULL, CK 30–1800 | 固定时限模式必填 |
| `action_seconds` | `smallint` | NOT NULL, CK 10–60 | 默认 20 |
| `reconnect_grace_seconds` | `smallint` | NOT NULL, default 15 | 每手共享离线宽限 |
| `fee_template_version_id` | `uuid` | FK → `fee_template_version.id`, NOT NULL | 抽水版本 |
| `exit_fee_template_version_id` | `uuid` | FK → `exit_fee_template_version.id`, NOT NULL | 离座费版本 |
| `player_editable_fields` | `varchar(32)[]` | NOT NULL | 玩家可调字段白名单 |
| `editable_limits` | `jsonb` | NOT NULL, default `{}` | 仅保存白名单字段的允许范围 |
| `published_at` | `timestamptz` | NULL | 发布时间 |
| `published_by_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 发布人 |
| `content_digest` | `bytea` | NOT NULL | 规范化内容摘要 |

唯一约束：`(template_id, version_no)`。短牌必须 `seat_count=6` 且 Ante/抓头关闭；长牌必须 8 席和 2/3 小时。

### 6.5 `system_policy_version` — 固定系统策略版本

该表不是“万能参数后台”；只允许代码内白名单键，发布须走部署或受控配置流程。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `policy_key` | `varchar(64)` | NOT NULL | 如 `seat_reserve_seconds`、`zero_stack_reserve_seconds` |
| `version_no` | `integer` | NOT NULL | 版本 |
| `value_json` | `jsonb` | NOT NULL | 经过该键专属 schema 校验的值 |
| `status` | `varchar(24)` | NOT NULL | `DRAFT/PUBLISHED/RETIRED` |
| `effective_from` | `timestamptz` | NULL | 生效时间；PUBLISHED 必填 |
| `effective_to` | `timestamptz` | NULL | 结束时间；左闭右开，当前版本为空 |
| `published_by_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 发布人或部署主体映射 |
| `reason` | `varchar(500)` | NOT NULL | 变更原因 |
| `content_digest` | `bytea` | NOT NULL | 摘要 |

唯一约束：`(policy_key, version_no)`；`effective_to IS NULL OR effective_to > effective_from`；同键 PUBLISHED 有效区间使用 `btree_gist` 与 `tstzrange(effective_from, coalesce(effective_to, 'infinity'), '[)')` 排斥重叠。发布新版本必须在同一受限函数事务内锁定策略键、关闭旧区间并打开新区间。

## 7. 资产与复式账本域

### 7.1 `asset` — 资产定义

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `asset_code` | `varchar(16)` | NOT NULL, UQ | 如 `TEST`；不可用展示名关联 |
| `display_name` | `varchar(64)` | NOT NULL | 展示名称 |
| `precision` | `smallint` | NOT NULL, CK 0–8 | 当前桌面资产为 2 |
| `transferability` | `varchar(24)` | NOT NULL | `NON_TRANSFERABLE/FUTURE_REAL`；TEST 不可兑换 |
| `status` | `varchar(24)` | NOT NULL | `ACTIVE/INACTIVE` |
| `withdrawable_default` | `boolean` | NOT NULL, default false | 手工额度默认不可提 |

### 7.2 `ledger_account` — 账务账户

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `account_code` | `varchar(64)` | NOT NULL, UQ | 稳定账户号 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 资产 |
| `owner_type` | `varchar(16)` | NOT NULL | `USER/PLATFORM/AGENT/SYSTEM` |
| `owner_id` | `uuid` | NULL | USER/AGENT 时分别引用业务实体；由服务层和触发器校验 |
| `account_type` | `varchar(32)` | NOT NULL | `AVAILABLE/TOPUP_FROZEN/TABLE_ESCROW/RAKE_INCOME/EXIT_FEE_INCOME/COMMISSION_PAYABLE/ADJUSTMENT_CLEARING` |
| `balance` | `bigint` | NOT NULL, default 0 | 分录余额的同步缓存；只由受限过账函数按 `balance + delta_amount` 更新，可从完整账本校验 |
| `allow_negative` | `boolean` | NOT NULL, default false | 玩家可用/冻结/托管为 false；清算类系统账户按种子显式设为 true |
| `status` | `varchar(16)` | NOT NULL | `ACTIVE/FROZEN/CLOSED` |
| `withdrawable` | `boolean` | NOT NULL, default false | 账户余额是否具备提款资格；不等于资产可提款 |

唯一约束：`(asset_id, owner_type, owner_id, account_type)`，平台/系统空 owner 使用规范化生成列或 `NULLS NOT DISTINCT` 唯一约束。

### 7.3 `ledger_transaction` — 账务事务头

事务头仅允许一次受控状态变化：`PENDING → POSTED/FAILED`；到达终态后不可修改。冲正另建 `REVERSAL` 事务，原交易始终保持 `POSTED`。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `transaction_code` | `varchar(40)` | NOT NULL, UQ | 玩家账单可见交易号 |
| `business_id` | `varchar(64)` | NOT NULL | 买入、补码、结算、离座、调整等业务号 |
| `business_type` | `varchar(32)` | NOT NULL | `MANUAL_ADJUSTMENT/BUYIN/TOPUP_HOLD/TOPUP_APPLY/TOPUP_RELEASE/HAND_SETTLEMENT/EXIT/COMMISSION/REVERSAL` 等 |
| `idempotency_key` | `varchar(128)` | NOT NULL, UQ | 业务级幂等键；与网络 request 分离 |
| `parameter_digest` | `bytea` | NOT NULL | 规范化资产、账户、金额和业务引用摘要；同幂等键异参数拒绝 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 单事务只允许一种资产 |
| `status` | `varchar(16)` | NOT NULL | `PENDING/POSTED/FAILED`；冲正不修改原交易状态 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NULL | 后台或客户端操作结果 |
| `user_id` | `uuid` | FK → `app_user.id`, NULL | 主要玩家；多玩家结算可为空，明细在分录 |
| `user_game_id_snapshot` | `varchar(32)` | NULL | 发生时玩家公开 ID 快照 |
| `user_name_snapshot` | `varchar(80)` | NULL | 发生时玩家名称快照 |
| `club_id_snapshot` | `uuid` | FK → `club.id`, NULL | 发生时归属俱乐部 |
| `agent_id_snapshot` | `uuid` | FK → `agent.id`, NULL | 发生时直接代理 |
| `agent_name_snapshot` | `varchar(80)` | NULL | 发生时代理名，当前改名不覆盖 |
| `room_id` | `uuid` | FK → `room.id`, NULL | 房间 |
| `hand_id` | `uuid` | FK → `hand.id`, NULL | 手牌 |
| `seat_session_id` | `uuid` | FK → `seat_session.id`, NULL | 入座资金会话 |
| `rule_snapshot_id` | `uuid` | FK → `room_rule_snapshot.id`, NULL | 使用的规则快照 |
| `agreement_version_id` | `uuid` | FK → `agent_agreement_version.id`, NULL | 代理协议快照 |
| `reason_code` | `varchar(64)` | NOT NULL | 稳定原因码 |
| `reason_text` | `varchar(500)` | NULL | 可审计补充原因 |
| `original_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL | `REVERSAL` 必填；其他纠错可选引用原单 |
| `posted_at` | `timestamptz` | NULL | 成功过账时间 |
| `failed_at` | `timestamptz` | NULL | 明确失败时间 |
| `failure_code` | `varchar(64)` | NULL | 失败原因；UNKNOWN 属于操作状态，不写成账本失败 |

索引：`(user_id, created_at desc, id)`、`(room_id, created_at desc)`、`(hand_id)`、`(original_transaction_id)`、`(business_type, status, created_at)`。完整冲正采用 `UNIQUE(original_transaction_id) WHERE business_type='REVERSAL'`，防止同一原交易被重复完整冲正。

对外账单使用派生 `display_status`：底层 `PENDING/FAILED` 原样返回；POSTED 原交易不存在有效冲正时显示 `POSTED`，存在引用它的 POSTED `REVERSAL` 交易时显示 `REVERSED`，并同时返回 `reversal_transaction_id`、`reversed_at`。`REVERSED` 不是 `ledger_transaction.status` 的可写值。V1仅支持完整冲正；未来如增加部分冲正，须新增 `PARTIALLY_REVERSED` 口径而不能复用 `REVERSED`。

### 7.4 `ledger_entry` — 复式账本分录

不可变，V1 使用普通表并按 `posted_at` 建索引。每个 `POSTED` 事务至少两条分录，全部 `delta_amount` 合计必须为 0。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `transaction_id` | `uuid` | FK → `ledger_transaction.id`, NOT NULL | 事务头 |
| `line_no` | `smallint` | NOT NULL | 事务内顺序 |
| `account_id` | `uuid` | FK → `ledger_account.id`, NOT NULL | 账户 |
| `delta_amount` | `bigint` | NOT NULL, CK <>0 | 有符号最小单位；正数增加账户余额、负数减少账户余额 |
| `balance_before` | `bigint` | NOT NULL | 过账前账户余额 |
| `balance_after` | `bigint` | NOT NULL | 必须等于 `balance_before + delta_amount` |
| `posted_at` | `timestamptz` | NOT NULL | 过账时间；V1时间索引列，未来分区候选键 |
| `memo` | `varchar(255)` | NULL | 安全摘要，不写私牌或秘密 |

唯一约束：`(transaction_id, line_no)`；同一事务同一账户默认只允许一条净分录，建立 `UNIQUE(transaction_id, account_id)`。账户更新须按 `account_id` 稳定顺序加锁，防止死锁。

#### 7.4.1 统一过账契约

应用角色不得直接写 `ledger_transaction`、`ledger_entry` 或 `ledger_account.balance`，所有账务写入必须调用受限函数 `post_ledger_transaction`。函数与买入、补码、结算、离座或调款的业务终态在同一数据库事务内执行：

1. 按 `idempotency_key` 锁定或创建 PENDING 事务；同键同 `parameter_digest` 返回原结果，同键异摘要拒绝。
2. 校验至少两条分录、所有账户资产等于事务 `asset_id`、`sum(delta_amount)=0`。
3. 按 `account_id` 排序加行锁，计算 `balance_after`；`allow_negative=false` 的账户不得小于 0。
4. 插入不可变分录并同步更新账户余额，随后把事务改为 POSTED；任一步失败则整个业务事务回滚或明确记为 FAILED。
5. 冲正复制原交易的相反 `delta_amount` 生成新的 POSTED `REVERSAL` 事务；不得修改或删除原交易和原分录。

`wallet_balance_projection` 是可延迟重建的查询模型；`ledger_account.balance` 是由同一过账函数维护的当前余额缓存；`ledger_entry` 是最终资金事实。三者不一致时以完整分录重算并报警，不以页面投影反向覆盖账本。

### 7.5 `wallet_balance_projection` — 玩家资产读模型

该表用于列表和客户端展示，不是账务真相来源；必须可由账本重建。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 资产 |
| `available_amount` | `bigint` | NOT NULL | 可用 |
| `topup_frozen_amount` | `bigint` | NOT NULL | 未生效补码冻结 |
| `table_escrow_amount` | `bigint` | NOT NULL | 桌内托管；底池已包含在内，不重复相加 |
| `total_amount` | `bigint` | GENERATED/投影 | 三者之和 |
| `last_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NOT NULL | 投影水位 |
| `projected_at` | `timestamptz` | NOT NULL | 数据截止时间 |

唯一约束：`(user_id, asset_id)`。

### 7.6 `manual_adjustment` — 超管调款/补偿业务记录

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `adjustment_code` | `varchar(40)` | NOT NULL, UQ | 业务号 |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 资产 |
| `adjustment_type` | `varchar(32)` | NOT NULL | `TEST_GRANT/MANUAL_ADJUSTMENT/COMPENSATION/CORRECTION` |
| `delta_amount` | `bigint` | NOT NULL, CK <>0 | 调整账户的有符号最小单位；正数增加、负数减少，过账时生成对应零和清算分录 |
| `withdrawable` | `boolean` | NOT NULL, default false | 默认不可提 |
| `reason` | `varchar(500)` | NOT NULL | 必填原因 |
| `original_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL | 纠错时必填 |
| `operator_admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 仅超管 |
| `sensitive_authorization_id` | `uuid` | FK → `sensitive_authorization.id`, NOT NULL, UQ | 120 秒单次授权，只能绑定一条调款记录 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL, UQ | 一次业务操作只产生一条调款记录 |
| `ledger_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL, UQ | 成功后关联唯一账务事务 |

`sensitive_authorization` 建立 `UNIQUE(id, operation_id)`，本表建立复合外键 `(sensitive_authorization_id, operation_id) → sensitive_authorization(id, operation_id)`，禁止把其他操作的授权挪用于调款。应用角色不得直接写本表，只能调用 `execute_manual_adjustment`：函数锁定授权和相关账户，重验超管身份、会话、权限版本、参数摘要、120秒期限及未消费状态，在同一事务内消费授权、创建调款记录并调用统一过账函数；同操作号同参数返回原结果，同号异参数拒绝。

### 7.7 `revenue_note` — 收入明细追加备注

备注只追加，不修改历史费用、归因或金额。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `revenue_type` | `varchar(16)` | NOT NULL | `HAND_RAKE/EXIT_FEE` |
| `hand_fee_id` | `uuid` | FK → `hand_fee.id`, NULL | 抽水备注目标 |
| `seat_session_id` | `uuid` | FK → `seat_session.id`, NULL | 离座费备注目标 |
| `content` | `varchar(1000)` | NOT NULL | 备注正文 |
| `operator_admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 追加人 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL | 权限与审计操作 |
| `noted_at` | `timestamptz` | NOT NULL | 追加时间 |

约束：`hand_fee_id` 与 `seat_session_id` 恰有一个非空，并与 `revenue_type` 一致。

## 8. 房间、座位与资金会话域

### 8.1 `room` — 房间

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `room_code` | `varchar(32)` | NOT NULL, UQ | 对外房间 ID，不应可猜测 |
| `club_id` | `uuid` | FK → `club.id`, NOT NULL | 所属俱乐部 |
| `creator_user_id` | `uuid` | FK → `app_user.id`, NULL | 授权玩家创建时填写 |
| `creator_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 运营创建时填写 |
| `rule_template_version_id` | `uuid` | FK → `rule_template_version.id`, NOT NULL | 来源模板版本 |
| `rule_snapshot_id` | `uuid` | FK → `room_rule_snapshot.id`, NOT NULL, UQ | 房间冻结快照 |
| `status` | `varchar(24)` | NOT NULL | `SCHEDULED/WAITING/RUNNING/DRAINING/PAUSED_RECOVERY/CLOSED` |
| `scheduled_open_at` | `timestamptz` | NULL | 最远未来 7 天 |
| `opened_at` | `timestamptz` | NULL | 进入 WAITING 时间 |
| `first_hand_at` | `timestamptz` | NULL | 房间计时起点 |
| `ends_at` | `timestamptz` | NULL | 第一手开始后按时长确定 |
| `draining_at` | `timestamptz` | NULL | 停新业务时间 |
| `closed_at` | `timestamptz` | NULL | 完成清算时间 |
| `close_intent` | `boolean` | NOT NULL, default false | 恢复中仍要保留关桌意图 |
| `close_reason` | `varchar(64)` | NULL | `NATURAL_END/OPERATOR/CLUB_FROZEN/EMPTY_TIMEOUT/RECOVERY` 等 |
| `current_hand_id` | `uuid` | FK → `hand.id`, NULL | 当前手恢复入口 |
| `hand_count` | `integer` | NOT NULL, default 0 | 已创建手数；有效手统计另算 |
| `state_version` | `bigint` | NOT NULL, default 0 | 房间状态并发版本 |

约束：创建者玩家/后台二选一；SCHEDULED 必须有 `scheduled_open_at`。索引：`(club_id, status, created_at desc)`、`(status, scheduled_open_at)`、`(ends_at) WHERE status IN ('WAITING','RUNNING')`。

### 8.2 `room_rule_snapshot` — 房间不可变规则快照

从模板复制并应用允许修改项后写入；开房成功后禁止更新。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `template_version_id` | `uuid` | FK → `rule_template_version.id`, NOT NULL | 来源 |
| `template_version_label` | `varchar(32)` | NOT NULL | 玩家披露版本 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 资产 |
| `deck_mode` | `varchar(16)` | NOT NULL | `LONG/SHORT` |
| `betting` | `varchar(8)` | NOT NULL | `NLH` |
| `seat_count` | `smallint` | NOT NULL | 8/6 |
| `room_seconds` | `integer` | NOT NULL | 时长 |
| `sb_amount` | `bigint` | NOT NULL | SB |
| `bb_amount` | `bigint` | NOT NULL | BB |
| `buyin_min_amount` | `bigint` | NOT NULL | 买入下限 |
| `buyin_max_amount` | `bigint` | NOT NULL | 买入上限 |
| `ante_mode` | `varchar(16)` | NOT NULL | Ante 模式 |
| `ante_amount` | `bigint` | NOT NULL | Ante 金额 |
| `straddle_mode` | `varchar(24)` | NOT NULL | 抓头模式 |
| `start_players` | `smallint` | NOT NULL | 自动开局人数 |
| `allow_spectate` | `boolean` | NOT NULL | 是否允许观战 |
| `delay_mode` | `varchar(24)` | NOT NULL | 延迟模式 |
| `vpip_threshold` | `smallint` | NULL | 准入阈值 |
| `absence_mode` | `varchar(32)` | NOT NULL | 缺席策略 |
| `absence_deadline_mode` | `varchar(24)` | NOT NULL | 缺席截止模式 |
| `absence_seconds` | `integer` | NULL | 缺席秒数 |
| `action_seconds` | `smallint` | NOT NULL | 基础行动时间 |
| `reconnect_grace_seconds` | `smallint` | NOT NULL | 每手离线宽限 |
| `rake_rate` | `numeric(9,6)` | NOT NULL | 抽水比例快照 |
| `rake_cap_amount` | `bigint` | NOT NULL | 封顶金额快照 |
| `fee_version_label` | `varchar(32)` | NOT NULL | 费用披露版本 |
| `exit_profit_rate` | `numeric(9,6)` | NOT NULL | 离座盈利费率 |
| `exit_fee_version_label` | `varchar(32)` | NOT NULL | 离座费版本 |
| `editable_values` | `jsonb` | NOT NULL, default `{}` | 创建者实际修改且在白名单内的字段及来源值 |
| `content_digest` | `bytea` | NOT NULL, IDX | 完整规则摘要；相同模板和参数可以创建多个独立房间快照 |

`content_digest` 仅用于完整性校验和普通索引，不得建立全局唯一约束。每次开房仍创建独立不可变快照，并由 `room.rule_snapshot_id` 一对一引用，避免共享对象的生命周期和审计耦合。

同源约束：`room_rule_snapshot` 建立 `UNIQUE(id, template_version_id)`，`room` 建立复合外键 `(rule_snapshot_id, rule_template_version_id) → room_rule_snapshot(id, template_version_id)`；`room` 再建立 `UNIQUE(id, rule_snapshot_id)`，`hand` 以 `(room_id, rule_snapshot_id) → room(id, rule_snapshot_id)` 保证手牌只能使用所属房间的冻结快照。上述复合外键在循环依赖收口迁移中后置创建。

### 8.3 `room_state_snapshot` — 游戏引擎恢复快照

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间 |
| `state_version` | `bigint` | NOT NULL | 与动作事件版本连续 |
| `hand_id` | `uuid` | FK → `hand.id`, NULL | 当前手 |
| `snapshot_json` | `jsonb` | NOT NULL | 可恢复的非账务引擎状态；不得作为余额或结算唯一事实 |
| `snapshot_digest` | `bytea` | NOT NULL | 完整性摘要 |
| `last_event_id` | `uuid` | FK → `hand_event.id`, NULL | 投影水位 |
| `captured_at` | `timestamptz` | NOT NULL | 快照时间 |

唯一约束：`(room_id, state_version)`；该表是周期检查点，不要求每个房间版本都有完整快照。恢复时读取同一房间中 `state_version <= room.state_version` 的最大版本，验证摘要和 `last_event_id` 后重放后续事件至当前版本；不得把 `room.state_version` 建成要求精确命中快照的外键。清理旧快照时每个活动房间至少保留一个已验证检查点。

### 8.4 `room_seat_occupancy` — 统一座位占用仲裁

每个房间的每个物理座位预创建一行。预约、买入、取消、过期和离座都必须先 `SELECT ... FOR UPDATE` 锁定该行；应用角色不得绕过受限座位函数直接改变占用状态。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间 |
| `seat_no` | `smallint` | NOT NULL, CK >=0 | 物理座位号，必须小于规则快照席数 |
| `status` | `varchar(16)` | NOT NULL | `VACANT/RESERVED/OCCUPIED` |
| `user_id` | `uuid` | FK → `app_user.id`, NULL | RESERVED/OCCUPIED 时必填 |
| `reservation_id` | `uuid` | FK → `seat_reservation.id`, NULL | RESERVED 时唯一非空业务引用 |
| `seat_session_id` | `uuid` | FK → `seat_session.id`, NULL | OCCUPIED 时唯一非空业务引用 |
| `expires_at` | `timestamptz` | NULL | RESERVED 的服务端期限，其他状态为空 |
| `changed_at` | `timestamptz` | NOT NULL | 最近一次合法状态变化时间 |

唯一约束：`(room_id, seat_no)`。检查约束要求：VACANT 时三个引用及 `expires_at` 均为空；RESERVED 时只有 `reservation_id/user_id/expires_at` 非空；OCCUPIED 时只有 `seat_session_id/user_id` 非空。由于占用表和业务表互相引用，先创建表结构，再在 Flyway 的跨域约束阶段增加可延迟外键。

### 8.5 `seat_reservation` — 15 秒座位预约

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `reservation_code` | `varchar(40)` | NOT NULL, UQ | 客户端恢复用业务号 |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间 |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `seat_no` | `smallint` | NOT NULL, CK >=0 | 物理座位号，范围由快照席数决定 |
| `occupancy_id` | `uuid` | FK → `room_seat_occupancy.id`, NOT NULL | 竞争的统一座位行 |
| `status` | `varchar(24)` | NOT NULL | `ACTIVE/CONSUMED/EXPIRED/CANCELLED` |
| `expires_at` | `timestamptz` | NOT NULL | 服务端截止时间 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL, UQ | 预约请求；一次操作只生成一条预约 |

约束：每房间座位最多一个 ACTIVE、每用户每房间最多一个 ACTIVE 的部分唯一索引；预约不冻结资金。上述索引用于查询和历史防重，真正的预约/入座互斥由 `room_seat_occupancy` 主键行锁保证。

### 8.6 `seat_session` — 入座资金会话

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `session_code` | `varchar(40)` | NOT NULL, UQ | 客户端/账单关联 `seat_session_id` |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间 |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `seat_no` | `smallint` | NOT NULL | 当前物理座位 |
| `occupancy_id` | `uuid` | FK → `room_seat_occupancy.id`, NOT NULL | 当前统一座位行 |
| `status` | `varchar(24)` | NOT NULL | `WAIT_NEXT_HAND/PLAYING/AUTO_PLAY/LEAVE_PENDING/ZERO_STACK_HOLD/SETTLING/CLOSED` |
| `membership_id_at_join` | `uuid` | FK → `club_membership.id`, NOT NULL | 入座时归属 |
| `agent_id_snapshot` | `uuid` | FK → `agent.id`, NULL | 会话展示快照；每手仍单独冻结协议 |
| `buyin_amount` | `bigint` | NOT NULL, CK >0 | 初始买入本金 |
| `applied_topup_amount` | `bigint` | NOT NULL, default 0 | 已生效补码本金累计 |
| `stack_amount` | `bigint` | NOT NULL, CK >=0 | 当前桌内可行动筹码投影；账本托管仍为资金真相 |
| `started_at` | `timestamptz` | NOT NULL | 买入明确成功时间 |
| `first_hand_at` | `timestamptz` | NULL | 第一手参与时间 |
| `last_hand_id` | `uuid` | FK → `hand.id`, NULL | 最近参与手 |
| `leave_requested_at` | `timestamptz` | NULL | 主动/超时离座申请 |
| `leave_reason` | `varchar(64)` | NULL | 主动、超时、自然到期、运营、故障等 |
| `zero_stack_deadline` | `timestamptz` | NULL | 零筹码 60 秒截止 |
| `ended_at` | `timestamptz` | NULL | 清算完成时间 |
| `returned_amount` | `bigint` | NULL | 返回可用余额 |
| `exit_fee_amount` | `bigint` | NULL | 离座费 |
| `net_result_amount` | `bigint` | NULL | 会话净收益，含离座费 |
| `exit_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL, UQ | 退出幂等账 |

约束：一个玩家最多一条活动真人 `seat_session`；同一房间座位最多一条活动会话。旧俱乐部临时访问权由此活动会话表达，关闭后失效。活动会话必须与占用行的 `seat_session_id/user_id/room_id/seat_no` 一致。

#### 8.6.1 预约、买入与离座事务

预约函数锁定 `(room_id, seat_no)` 占用行，仅允许 `VACANT → RESERVED`；过期或取消仅在占用行仍指向同一预约时执行 `RESERVED → VACANT`。买入在一个事务内完成：

1. 锁定玩家活动会话约束、座位占用行和相关账本账户；占用行必须仍指向请求 reservation_id、属于该玩家且为 RESERVED，并在获得锁后以 clock_timestamp() 判断 expires_at > 当前时刻；等于截止即过期。禁止从 VACANT 直接买入。
2. 调用 `post_ledger_transaction` 完成可用余额到桌内托管的零和转移。
3. 创建 `seat_session`，把预约改为 CONSUMED，并将占用行原子改为 OCCUPIED。
4. 任一步失败全部回滚，不允许出现已扣款无座位或有座位无托管资金。

买入请求必须带 reservation_id 和 request_id。先查询同键已提交结果再判断预约：成功响应丢失即使预约后来过期也返回原成功。首次提交预约已过期则同事务把仍指向原预约的占用行释放、预约标 EXPIRED、business_operation 保存 RESERVATION_EXPIRED，提交该拒绝结果；不得先抛异常导致清理与拒绝记录回滚。拒绝不建 seat_session、不扣款、不隐式续期。客户端重新预约并用新 request_id 提交；新键同座但已 OCCUPIED 返回 SEAT_TAKEN。锁后验有效并开始本次原子消费，即使事务提交越过预约截止仍可成功，因为座位锁已仲裁；另一玩家不得同时抢得该座。

离座先停止新手准入并完成资金清算，再在同一事务中关闭 `seat_session`、把占用行改回 VACANT。换座按 `(room_id, seat_no)` 排序锁定两行，避免双向换座死锁。

### 8.7 `seat_move_request` — 换座请求

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `seat_session_id` | `uuid` | FK → `seat_session.id`, NOT NULL | 不新开资金会话 |
| `from_seat_no` | `smallint` | NOT NULL | 原座位 |
| `to_seat_no` | `smallint` | NOT NULL | 目标座位 |
| `status` | `varchar(24)` | NOT NULL | `PENDING/APPLIED/CANCELLED/FAILED` |
| `wait_until_bb_paid` | `boolean` | NOT NULL | 防止逃避下一次 BB |
| `requested_at` | `timestamptz` | NOT NULL | 请求时间 |
| `applied_at` | `timestamptz` | NULL | 手间实际生效时间 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL, UQ | 幂等操作；一次操作只生成一条换座请求 |

每会话最多一条 PENDING；应用时按固定顺序同时锁定源、目标 `room_seat_occupancy` 行，两个状态在同一事务内切换。

### 8.8 `topup_order` — 补码冻结、应用与退款

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `topup_code` | `varchar(40)` | NOT NULL, UQ | 补码业务号 |
| `seat_session_id` | `uuid` | FK → `seat_session.id`, NOT NULL | 入座会话 |
| `request_id` | `uuid` | NOT NULL, UQ | 客户端幂等请求号 |
| `requested_amount` | `bigint` | NOT NULL, CK >0 | 申请并冻结金额 |
| `stack_at_request` | `bigint` | NOT NULL, CK >=0 | 申请时剩余可行动筹码 C |
| `status` | `varchar(24)` | NOT NULL | `PENDING/APPLIED/CANCELLED/REFUNDED/FAILED` |
| `hold_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NOT NULL, UQ | 可用→冻结 |
| `applied_amount` | `bigint` | NULL | 手间实际进入托管的 X |
| `refunded_amount` | `bigint` | NULL | 退回 A-X 或全额退款 |
| `resolution_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL, UQ | 应用/取消竞争的唯一终态账 |
| `resolved_at` | `timestamptz` | NULL | 终态时间 |
| `failure_code` | `varchar(64)` | NULL | `TOPUP_MIN_REQUIRED` 等 |

约束：每 `seat_session` 最多一条 `PENDING` 的部分唯一索引；取消和应用必须在同一数据库事务内竞争。

### 8.9 `room_state_event` — 房间状态轨迹

不可变。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间 |
| `seq_no` | `bigint` | NOT NULL | 房间内连续序号 |
| `from_status` | `varchar(24)` | NULL | 初始创建为空 |
| `to_status` | `varchar(24)` | NOT NULL | 新状态 |
| `reason_code` | `varchar(64)` | NOT NULL | 状态原因 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NULL | 操作来源 |
| `occurred_at` | `timestamptz` | NOT NULL | 生效时间 |
| `details` | `jsonb` | NOT NULL, default `{}` | 只存非敏感补充信息 |

唯一约束：`(room_id, seq_no)`。

## 9. 手牌、动作、底池与结算域

### 9.1 `hand` — 手牌主记录

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `hand_code` | `varchar(40)` | NOT NULL, UQ | 全局唯一 hand_id |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间 |
| `hand_no` | `integer` | NOT NULL | 房间内递增手号 |
| `rule_snapshot_id` | `uuid` | FK → `room_rule_snapshot.id`, NOT NULL | 冻结规则 |
| `status` | `varchar(24)` | NOT NULL | `PREPARING/STARTED/SETTLING/SETTLED/VOID/RECOVERY_REQUIRED` |
| `street` | `varchar(16)` | NOT NULL | `PREFLOP/FLOP/TURN/RIVER/SHOWDOWN/COMPLETE` |
| `state_version` | `bigint` | NOT NULL, default 0 | 动作并发版本 |
| `button_seat_no` | `smallint` | NOT NULL | 庄位 |
| `sb_seat_no` | `smallint` | NOT NULL | 小盲位 |
| `bb_seat_no` | `smallint` | NOT NULL | 大盲位 |
| `straddle_seat_no` | `smallint` | NULL | 有效抓头位 |
| `current_actor_seat_no` | `smallint` | NULL | 当前行动座位 |
| `current_bet_amount` | `bigint` | NOT NULL, default 0 | 本街最高有效下注 H |
| `last_full_raise_delta` | `bigint` | NOT NULL | 最近完整差额 L |
| `action_deadline` | `timestamptz` | NULL | 当前阶段截止 |
| `deal_source` | `varchar(24)` | NOT NULL | `RANDOM/SCRIPTED_TEST` |
| `test_deal_run_id` | `uuid` | FK → `test_deal_run.id`, NULL | 预设测试手关联 |
| `deck_commitment` | `bytea` | NULL, SECRET | 恢复完整性摘要；未接入公平证明时不对外宣称验证 |
| `started_at` | `timestamptz` | NULL | 强制款与开手原子提交时间 |
| `settled_at` | `timestamptz` | NULL | 首次成功结算时间；代理业务日依据 |
| `voided_at` | `timestamptz` | NULL | 作废时间 |
| `settlement_id` | `uuid` | FK → `hand_settlement.id`, NULL, UQ | 结算记录 |

唯一约束：`(room_id, hand_no)`。索引：`(status, started_at)`、`(room_id, started_at desc)`、`(settled_at)`。

### 9.2 `hand_player` — 每手玩家状态与统计事实

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL | 手牌 |
| `seat_session_id` | `uuid` | FK → `seat_session.id`, NOT NULL | 资金会话 |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `seat_no` | `smallint` | NOT NULL | 本手固定物理座位 |
| `display_name_snapshot` | `varchar(80)` | NOT NULL | 回放历史昵称 |
| `club_id_snapshot` | `uuid` | FK → `club.id`, NOT NULL | 开手归属快照 |
| `agent_id_snapshot` | `uuid` | FK → `agent.id`, NULL | 开手代理快照 |
| `agreement_version_id` | `uuid` | FK → `agent_agreement_version.id`, NULL | 开手协议快照；缺失时归因标 CONFIG_ERROR |
| `starting_stack_amount` | `bigint` | NOT NULL | 开手筹码 |
| `ending_stack_amount` | `bigint` | NULL | 正常结算/作废后筹码 |
| `total_contribution_amount` | `bigint` | NOT NULL, default 0 | 本手全部实际投入 |
| `current_street_contribution` | `bigint` | NOT NULL, default 0 | 当前街有效投入 |
| `unmatched_return_amount` | `bigint` | NOT NULL, default 0 | 无人匹配返还，不抽水 |
| `award_amount` | `bigint` | NOT NULL, default 0 | 各池派奖合计 |
| `net_amount` | `bigint` | NULL | 派奖+返还−投入 |
| `folded` | `boolean` | NOT NULL, default false | 是否弃牌 |
| `all_in` | `boolean` | NOT NULL, default false | 是否全下 |
| `reached_showdown` | `boolean` | NOT NULL, default false | 是否进入摊牌 |
| `cards_revealed` | `boolean` | NOT NULL, default false | 是否依规则公开底牌 |
| `mucked` | `boolean` | NOT NULL, default false | 是否 Muck |
| `remaining_stack_amount` | `bigint` | NOT NULL, CK >=0 | 当前可行动桌内筹码，不含已投入底池 |
| `has_acted_this_street` | `boolean` | NOT NULL, default false | 本街是否已主动响应 |
| `last_response_price` | `bigint` | NOT NULL, default 0 | 该玩家上次响应的最高有效下注 |
| `reopen_threshold` | `bigint` | NOT NULL, default 0 | 再次获得加注权所需的完整累计增量 |
| `connection_state` | `varchar(16)` | NOT NULL | `ONLINE/OFFLINE/AUTO` |
| `timer_phase` | `varchar(16)` | NOT NULL | `BASE/BANK/GRACE/AUTO` |
| `base_deadline` | `timestamptz` | NULL | 本轮基础时间截止 |
| `absence_deadline` | `timestamptz` | NULL | B 模式缺席截止；A 模式为空 |
| `vpip_flag` | `boolean` | NOT NULL, default false | 严格口径主动入池 |
| `pfr_flag` | `boolean` | NOT NULL, default false | 翻前提高最高下注 |
| `won_competed_pot` | `boolean` | NOT NULL, default false | 获得至少一个有竞争池份额 |
| `timebank_before_ms` | `integer` | NOT NULL | 行动前账号时间银行快照 |
| `timebank_after_ms` | `integer` | NULL | 本手结束后值 |
| `disconnect_grace_remaining_ms` | `integer` | NOT NULL | 本手共享离线预算 |

唯一约束：`(hand_id, user_id)`、`(hand_id, seat_no)`。

### 9.3 `hand_card` — 牌序、底牌、公共牌与烧牌

该表为 SECRET。HOLE/DECK/BURN 使用应用层信封加密，密钥由 KMS/Vault 管理；普通查询视图只暴露合法公开字段。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL | 手牌 |
| `deck_position` | `smallint` | NOT NULL | 固定完整牌序位置 |
| `card_role` | `varchar(16)` | NOT NULL | `HOLE/BOARD/BURN/REMAINDER` |
| `street` | `varchar(16)` | NULL | 公共牌/烧牌所属街 |
| `owner_user_id` | `uuid` | FK → `app_user.id`, NULL | 底牌持有人 |
| `owner_card_no` | `smallint` | NULL | 玩家第 1/2 张底牌 |
| `public_code` | `char(2)` | NULL, CK 标准牌码 | 已公开公共牌或依法公开底牌；否则为空 |
| `card_ciphertext` | `bytea` | NOT NULL, SECRET | 牌码密文 |
| `key_version` | `varchar(32)` | NOT NULL, SECRET | 加密密钥版本，不存密钥 |
| `revealed_at` | `timestamptz` | NULL | 实际公开时间 |
| `visibility` | `varchar(24)` | NOT NULL | `SERVER_ONLY/OWNER_ONLY/PUBLIC/MUCKED` |

唯一约束：`(hand_id, deck_position)`、`(hand_id, owner_user_id, owner_card_no) WHERE owner_user_id IS NOT NULL`。长牌牌码 52 张唯一，短牌只允许 6–A。

### 9.4 `hand_action_request` — 动作请求与幂等结果

每个玩家、超时或系统动作请求无论接受或拒绝都保存终态结果，防止旧版本、非法加注等拒绝请求在状态变化后被重新解释。应用角色不得直接写入，只能调用 `submit_hand_action`。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `action_code` | `varchar(48)` | NOT NULL, UQ | 全局动作请求幂等键；PLAYER 使用客户端 action_id，TIMEOUT/SYSTEM 由服务端确定性生成 |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL | 请求所针对的手牌 |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 请求玩家 |
| `seat_session_id` | `uuid` | FK → `seat_session.id`, NOT NULL | 请求时的入座会话 |
| `requested_state_version` | `bigint` | NOT NULL | 请求所依据的权威状态版本 |
| `action_type` | `varchar(16)` | NOT NULL | 请求动作 |
| `source` | `varchar(16)` | NOT NULL | `PLAYER/TIMEOUT/SYSTEM`；服务端动作也必须先形成请求事实 |
| `target_amount` | `bigint` | NOT NULL | 请求的本街目标总额 |
| `parameter_digest` | `bytea` | NOT NULL | 规范化手牌、玩家、版本、动作和金额摘要 |
| `result` | `varchar(16)` | NOT NULL | `PENDING/ACCEPTED/REJECTED` |
| `error_category` | `varchar(32)` | NULL | 前端稳定错误分类；接受时为空 |
| `error_code` | `varchar(64)` | NULL | `STALE_ACTION/ILLEGAL_RAISE/...`；接受时为空 |
| `result_state_version` | `bigint` | NULL | 接受后的版本或拒绝时服务端当前版本 |
| `response_summary` | `jsonb` | NULL | 裁剪后的合法动作、跟注成本、目标范围和截止时间；不得含未公开牌 |
| `requested_at` | `timestamptz` | NOT NULL | 首次收到时间 |
| `resolved_at` | `timestamptz` | NULL | 明确接受或拒绝时间 |

`submit_hand_action` 先按 `action_code` 锁定或创建 PENDING 行；同 ID 同 `parameter_digest` 返回已存结果，同 ID 异摘要返回 `IDEMPOTENCY_CONFLICT`。超时和系统动作以 `hand_id + state_version + user_id + source` 规范化后生成稳定服务端请求号，同样经过本函数。可预期的业务拒绝必须写成 REJECTED 并提交，不能通过抛异常回滚幂等证据；接受时创建 `hand_action`、`hand_event`、更新手牌状态和请求终态必须同一事务提交。

### 9.5 `hand_action` — 已接受的结构化动作

不可变。V1 使用普通表并按 `accepted_at` 建索引；请求幂等键保存在 `hand_action_request`，本表保证 `(hand_id, seq_no)` 和一个请求至多一个动作事实。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `action_request_id` | `uuid` | FK → `hand_action_request.id`, NOT NULL, UQ | 已接受的原请求；拒绝请求没有动作事实 |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL | 手牌 |
| `seq_no` | `integer` | NOT NULL | 手牌内全局动作序号 |
| `state_version_before` | `bigint` | NOT NULL | 校验旧版本 |
| `state_version_after` | `bigint` | NOT NULL | 接受后的新版本 |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 行动玩家 |
| `seat_no` | `smallint` | NOT NULL | 座位快照 |
| `street` | `varchar(16)` | NOT NULL | 街道 |
| `action_type` | `varchar(16)` | NOT NULL | `FOLD/CHECK/CALL/BET/RAISE/ALL_IN/AUTO_CHECK/AUTO_FOLD` |
| `target_amount` | `bigint` | NOT NULL | 本街目标总额 T；弃牌/过牌为 0 |
| `delta_amount` | `bigint` | NOT NULL | 本次实际扣除 T-c |
| `to_call_before` | `bigint` | NOT NULL | 动作前跟注成本 C |
| `pot_before` | `bigint` | NOT NULL | 动作前总池 |
| `full_raise_delta_before` | `bigint` | NOT NULL | 动作前 L |
| `reopened_betting` | `boolean` | NOT NULL | 此动作是否构成完整增量并重开 |
| `is_short_all_in` | `boolean` | NOT NULL | 是否短全下 |
| `source` | `varchar(16)` | NOT NULL | `PLAYER/TIMEOUT/SYSTEM` |
| `accepted_at` | `timestamptz` | NOT NULL | 服务端接收且提交时间 |

唯一约束：`(hand_id, seq_no)`；`action_request_id` 唯一保证一个接受请求只产生一个动作事实。重复 action_id 由 `hand_action_request` 返回原结果，不再次执行。

### 9.6 `hand_event` — 可重放领域事件

不可变。V1 使用普通表并按 `occurred_at` 建索引；与 `hand_action` 的区别是它还记录发牌、换街、强制款、退款、摊牌和结算阶段。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL | 手牌 |
| `seq_no` | `bigint` | NOT NULL | 严格递增 |
| `event_type` | `varchar(48)` | NOT NULL | `HAND_STARTED/CARD_DEALT/FORCED_BET_POSTED/ACTION_ACCEPTED/STREET_CHANGED/POT_BUILT/SETTLED/VOIDED` 等 |
| `state_version` | `bigint` | NOT NULL | 事件后版本 |
| `payload` | `jsonb` | NOT NULL | 结构化事件；不得包含明文未公开牌、凭据或密钥 |
| `occurred_at` | `timestamptz` | NOT NULL | 权威时间 |
| `request_id` | `uuid` | NULL | 来源请求 |
| `payload_digest` | `bytea` | NOT NULL | 防篡改与重放校验 |

唯一约束：`(hand_id, seq_no)`。

### 9.7 `hand_pot` — 主池、边池和公共 Ante 池

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL | 手牌 |
| `pot_no` | `smallint` | NOT NULL | 从 0 递增，决定同余分配顺序 |
| `pot_type` | `varchar(16)` | NOT NULL | `MAIN/SIDE/BB_ANTE_COMMON` |
| `layer_from_amount` | `bigint` | NOT NULL | 分层下界 |
| `layer_to_amount` | `bigint` | NOT NULL | 分层上界 |
| `gross_amount` | `bigint` | NOT NULL, CK >=0 | 抽水前池额 G 的组成 |
| `rake_amount` | `bigint` | NOT NULL, CK >=0 | 分摊到该池的费用 |
| `net_amount` | `bigint` | NOT NULL, CK >=0 | 可派奖净额 |
| `is_competed` | `boolean` | NOT NULL | 是否存在竞争；无人匹配部分不建池而走返还 |

唯一约束：`(hand_id, pot_no)`；`gross_amount = rake_amount + net_amount`。

### 9.8 `hand_pot_contribution` — 池贡献与获池资格

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `pot_id` | `uuid` | FK → `hand_pot.id`, NOT NULL | 底池 |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `contribution_amount` | `bigint` | NOT NULL, CK >0 | 该池实际贡献；含弃牌者 |
| `eligible_to_win` | `boolean` | NOT NULL | 未弃牌且达到该层才可获池 |
| `folded` | `boolean` | NOT NULL | 快照 |
| `attribution_base_exact` | `numeric(30,12)` | NOT NULL | 抽水逐池贡献归因基数 |

唯一约束：`(pot_id, user_id)`。

### 9.9 `hand_pot_award` — 每池派奖与尾分

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `pot_id` | `uuid` | FK → `hand_pot.id`, NOT NULL | 底池 |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 获奖玩家 |
| `base_share_amount` | `bigint` | NOT NULL | 平分基础额 |
| `odd_chip_amount` | `bigint` | NOT NULL, CK 0 或最小单位 | 从庄左顺时针产生的尾分 |
| `award_amount` | `bigint` | NOT NULL | 合计派奖 |
| `hand_category` | `varchar(24)` | NULL | `HIGH_CARD/.../STRAIGHT_FLUSH`；弃牌获胜可空 |
| `rank_vector` | `smallint[]` | NULL | 同牌型比较向量，不使用花色破平 |

唯一约束：`(pot_id, user_id)`；每池 award 合计必须等于 `hand_pot.net_amount`。

### 9.10 `hand_fee` — 单手抽水事实

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL, UQ | 一手一条抽水总额 |
| `fee_template_version_id` | `uuid` | FK → `fee_template_version.id`, NOT NULL | 来源版本 |
| `gross_competed_pot_amount` | `bigint` | NOT NULL | 全部有竞争池之和 G |
| `rate_snapshot` | `numeric(9,6)` | NOT NULL | 费率 |
| `cap_snapshot_amount` | `bigint` | NOT NULL | 全手 cap |
| `rake_amount` | `bigint` | NOT NULL | `floor(min(G*rate, cap))` |
| `flop_dealt` | `boolean` | NOT NULL | false 时当前模板费用 0 |
| `ledger_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL, UQ | 结算账务事务 |
| `reversed_by_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL | VOID 冲正 |

### 9.11 `hand_settlement` — 原子结算结果

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `settlement_code` | `varchar(40)` | NOT NULL, UQ | 重试返回同一 settlement_id |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL, UQ | 一手一个结算 |
| `status` | `varchar(24)` | NOT NULL | `PENDING/POSTED/REVERSED/FAILED` |
| `total_contribution_amount` | `bigint` | NOT NULL | 全部投入 |
| `total_unmatched_return_amount` | `bigint` | NOT NULL | 无人匹配返还 |
| `total_rake_amount` | `bigint` | NOT NULL | 抽水 |
| `total_award_amount` | `bigint` | NOT NULL | 派奖 |
| `ledger_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL, UQ | 结算账和终态同事务提交 |
| `posted_at` | `timestamptz` | NULL | 首次成功时间，等于 `hand.settled_at` |
| `result_digest` | `bytea` | NOT NULL | 规则、池、赢家和金额摘要 |
| `failure_code` | `varchar(64)` | NULL | 守恒失败等明确错误 |

守恒：`total_contribution = total_unmatched_return + total_rake + total_award`。广播失败不得重做结算。

### 9.12 `player_hand_stat` — 玩家单手统计读模型

由结算事件生成，可重建。V1 使用普通表并按 `settled_at` 建索引。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL | 手牌 |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间 |
| `seat_session_id` | `uuid` | FK → `seat_session.id`, NOT NULL | 会话 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 资产 |
| `deck_mode` | `varchar(16)` | NOT NULL | 长/短牌分开统计 |
| `settled_at` | `timestamptz` | NOT NULL | 时间筛选依据 |
| `valid_hand` | `boolean` | NOT NULL | 已发底牌且正常 SETTLED |
| `vpip_flag` | `boolean` | NOT NULL | VPIP 分子 |
| `pfr_flag` | `boolean` | NOT NULL | PFR 分子 |
| `showdown_flag` | `boolean` | NOT NULL | W$SD 分母 |
| `showdown_won_flag` | `boolean` | NOT NULL | 获任一池份额 |
| `won_pot_flag` | `boolean` | NOT NULL | 获池率分子 |
| `net_amount` | `bigint` | NOT NULL | 单手净收益，不再减一次归因抽水 |
| `bb_amount` | `bigint` | NOT NULL | bb/100 分母换算快照 |
| `deal_source` | `varchar(24)` | NOT NULL | SCRIPTED_TEST 不混入正式指标 |

唯一约束：`(user_id, hand_id)`。

## 10. 代理归因与日账域

### 10.1 `commission_attribution` — 逐手逐池代理归因

不可变；玩家结算不得因计提异常而回滚。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `event_code` | `varchar(48)` | NOT NULL, UQ | 计提事件唯一号 |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL | 手牌 |
| `pot_id` | `uuid` | FK → `hand_pot.id`, NOT NULL | 底池 |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 贡献玩家 |
| `agent_id` | `uuid` | FK → `agent.id`, NULL | 空表示平台 |
| `agreement_version_id` | `uuid` | FK → `agent_agreement_version.id`, NULL | 开手协议快照 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 资产 |
| `business_date` | `date` | NOT NULL | 首次 settled_at 转 Asia/Shanghai |
| `pot_rake_amount` | `bigint` | NOT NULL | 该池实收抽水 |
| `player_contribution_amount` | `bigint` | NOT NULL | 玩家该池贡献 |
| `pot_contribution_amount` | `bigint` | NOT NULL | 全池贡献 |
| `attribution_base_exact` | `numeric(30,12)` | NOT NULL | `pot_rake * player/pot` |
| `rate_snapshot` | `numeric(9,6)` | NULL | 协议费率 |
| `commission_exact` | `numeric(30,12)` | NULL | 未取分的佣金 |
| `status` | `varchar(24)` | NOT NULL | `VALID/CONFIG_ERROR/REVERSED` |
| `original_event_id` | `uuid` | FK → `commission_attribution.id`, NULL | 冲正事件引用 |
| `occurred_at` | `timestamptz` | NOT NULL | 投影写入时间；不改变业务日 |

唯一约束拆分为：`UNIQUE(hand_id, pot_id, user_id) WHERE original_event_id IS NULL`，防止可空列使原始归因重复；`UNIQUE(original_event_id) WHERE original_event_id IS NOT NULL`，保证一个原事件最多冲正一次。检查约束要求 `VALID/CONFIG_ERROR` 的 `original_event_id` 为空，`REVERSED` 必须非空。

应用角色不得直接写入，统一调用 `post_commission_attribution`。函数按业务键或原事件加锁，校验手牌、池、玩家、资产和金额一致；冲正必须引用尚未冲正的原始事件并写入相反的归因/佣金数值。重复同一原始事件或重复冲正返回原结果，不新增第二条记录。

### 10.2 `commission_daily_statement` — 代理业务日日账

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `statement_code` | `varchar(40)` | NOT NULL, UQ | 日账号 |
| `agent_id` | `uuid` | FK → `agent.id`, NOT NULL | 代理 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 资产 |
| `business_date` | `date` | NOT NULL | 业务日 |
| `version_no` | `integer` | NOT NULL | 重算版本 |
| `status` | `varchar(24)` | NOT NULL | `FINAL/PENDING_RECALC/CONFIG_ERROR` |
| `attribution_base_exact` | `numeric(30,12)` | NOT NULL | 高精度归因基数净额 |
| `commission_target_exact` | `numeric(30,12)` | NOT NULL | 高精度目标应计 |
| `target_accrued_amount` | `bigint` | NOT NULL | 向下取资产精度后的目标 |
| `booked_net_amount` | `bigint` | NOT NULL | 截至该版本已记净应计 |
| `test_marked_paid_amount` | `bigint` | NOT NULL, default 0 | 仅 TEST 标记，不代表真实付款 |
| `pending_difference_amount` | `bigint` | NOT NULL | 目标应计−测试标记等待核对差额 |
| `data_cutoff_at` | `timestamptz` | NOT NULL | 数据截止时间 |
| `calculated_at` | `timestamptz` | NOT NULL | 计算时间 |

唯一约束：`(agent_id, asset_id, business_date, version_no)`。不保存 `is_current`，也不建立无法稳定表达“最高版本”的部分索引；`v_commission_current_statement` 按每个代理、资产、业务日的最高 `version_no` 返回当前版本。生成新版本时锁定已存在的最高版本行并依赖唯一约束串行化；首次版本并发冲突时读取胜出记录后按幂等规则返回或重算。

### 10.3 `commission_statement_adjustment` — 日账版本调整轨迹

不可变。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `statement_id` | `uuid` | FK → `commission_daily_statement.id`, NOT NULL | 日账版本 |
| `adjustment_code` | `varchar(48)` | NOT NULL, UQ | 调整业务号 |
| `adjustment_amount` | `bigint` | NOT NULL | 可正可负；新目标−已记净额 |
| `reason` | `varchar(32)` | NOT NULL | `INITIAL/LATE_EVENT/REVERSAL/CORRECTION` |
| `source_event_id` | `uuid` | FK → `commission_attribution.id`, NULL | 导致重算的事件 |
| `ledger_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL, UQ | 平台收入内划分账 |
| `booked_at` | `timestamptz` | NOT NULL | 实际记账时间，与业务日分列 |

### 10.4 `commission_test_payment_mark` — TEST 支付标记

不可变，不调用真实支付。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `statement_id` | `uuid` | FK → `commission_daily_statement.id`, NOT NULL | TEST 日账 |
| `amount` | `bigint` | NOT NULL, CK >0 | 标记金额 |
| `operator_admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 仅超管 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL, UQ | 幂等操作；一次操作只产生一条TEST标记 |
| `marked_at` | `timestamptz` | NOT NULL | 标记时间 |
| `reason` | `varchar(500)` | NOT NULL | 原因 |

## 11. 聊天、举报与客服域

### 11.1 `chat_message` — 牌桌消息

V1 使用普通表并按 `sent_at` 建索引，默认保留 30 天；保留全局消息号和客户端幂等约束。未来分区须先引入非分区消息 ID 注册表。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `message_code` | `varchar(48)` | NOT NULL, UQ | 服务端 message_id |
| `client_message_id` | `varchar(64)` | NULL | USER/ADMIN 必填的发送端幂等 ID；SYSTEM 可空 |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间 |
| `sender_type` | `varchar(16)` | NOT NULL | `USER/ADMIN/SYSTEM` |
| `sender_user_id` | `uuid` | FK → `app_user.id`, NULL | 玩家消息 |
| `sender_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 客服巡检消息 |
| `system_event_code` | `varchar(64)` | NULL | SYSTEM 必填的来源事件幂等键 |
| `sender_public_id_snapshot` | `varchar(32)` | NOT NULL | 对外身份快照 |
| `message_type` | `varchar(16)` | NOT NULL | `TEXT/QUICK/EMOJI/SYSTEM` |
| `content` | `varchar(500)` | NOT NULL | 文字 1–200 可见字符；系统消息可更长，渲染必须转义 |
| `status` | `varchar(16)` | NOT NULL | `SENT/REJECTED/REDACTED` |
| `sent_at` | `timestamptz` | NOT NULL | 服务端时间 |
| `moderation_flags` | `varchar(32)[]` | NOT NULL, default `{}` | 风控标记，不等于处罚事实 |

检查约束要求：USER 只有 `sender_user_id/client_message_id` 非空；ADMIN 只有 `sender_admin_id/client_message_id` 非空；SYSTEM 的两个发送者外键和 `client_message_id` 均为空且 `system_event_code` 非空；`message_type='SYSTEM'` 当且仅当 `sender_type='SYSTEM'`。分别建立 `UNIQUE(room_id, sender_user_id, client_message_id) WHERE sender_type='USER'`、`UNIQUE(room_id, sender_admin_id, client_message_id) WHERE sender_type='ADMIN'` 和 `UNIQUE(room_id, system_event_code) WHERE sender_type='SYSTEM'`，使玩家、客服和系统重试都只生成一条消息。

### 11.2 `asr_job` — 语音转文字任务

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 录音用户 |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间上下文 |
| `status` | `varchar(24)` | NOT NULL | `UPLOADED/TRANSCRIBING/SUCCEEDED/FAILED/DELETED` |
| `audio_object_key` | `text` | NULL, SECRET | 临时对象键；不存公开 URL |
| `audio_size_bytes` | `integer` | NOT NULL, CK <=2097152 | 最大 2 MiB |
| `duration_ms` | `integer` | NOT NULL, CK <=15000 | 最大 15 秒 |
| `transcript_draft` | `varchar(500)` | NULL, PII | 草稿，用户确认前不发送 |
| `failure_code` | `varchar(64)` | NULL | 失败原因 |
| `delete_after` | `timestamptz` | NOT NULL | 成功后立即删除；失败最长 24h |
| `deleted_at` | `timestamptz` | NULL | 实际删除时间 |

### 11.3 `mute_record` — 禁言记录

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 被禁言玩家 |
| `room_id` | `uuid` | FK → `room.id`, NULL | 房间级；空可表示授权范围级 |
| `duration_type` | `varchar(16)` | NOT NULL | `MIN_10/HOUR_24/PERMANENT` |
| `starts_at` | `timestamptz` | NOT NULL | 起始 |
| `ends_at` | `timestamptz` | NULL | 永久为空 |
| `status` | `varchar(16)` | NOT NULL | `ACTIVE/EXPIRED/REVOKED` |
| `reason` | `varchar(500)` | NOT NULL | 原因 |
| `operator_admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 永久禁言仅运营/超管 |
| `issued_operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL, UQ | 创建禁言的幂等操作 |
| `revoked_operation_id` | `uuid` | FK → `business_operation.id`, NULL, UQ | 主动撤销禁言的幂等操作；自然到期为空 |

约束：`ends_at IS NULL OR ends_at > starts_at`；ACTIVE 时 `revoked_operation_id` 为空，REVOKED 时必须非空，EXPIRED 时为空；同一用户和同一作用域最多一条 `ACTIVE` 记录，房间为空的范围级禁言使用规范化零UUID表达唯一键。禁言、撤销和到期收口只能调用受限函数；创建新禁言前先锁定该用户与作用域并把已自然到期但仍为ACTIVE的旧记录转为EXPIRED。

### 11.4 `user_chat_block` — 玩家主动屏蔽关系

屏蔽是接收侧过滤关系，不删除消息、不改变举报和禁言事实。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `blocker_user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 发起屏蔽的玩家 |
| `blocked_user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 被屏蔽的玩家 |
| `status` | `varchar(16)` | NOT NULL | `ACTIVE/REVOKED` |
| `blocked_at` | `timestamptz` | NOT NULL | 生效时间 |
| `revoked_at` | `timestamptz` | NULL | 解除时间 |
| `blocked_operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL, UQ | 屏蔽幂等操作 |
| `revoked_operation_id` | `uuid` | FK → `business_operation.id`, NULL, UQ | 解除幂等操作 |

检查约束：不得屏蔽自己；ACTIVE 时 `revoked_at/revoked_operation_id` 为空，REVOKED 时二者均非空。建立 `UNIQUE(blocker_user_id, blocked_user_id) WHERE status='ACTIVE'`。服务端仅在普通玩家 `TEXT/QUICK/EMOJI` 的订阅和历史查询中应用过滤；SYSTEM、安全提示和客服巡检消息不可被屏蔽，原消息、举报证据和审计记录不删除。

### 11.5 `report_submission` — 玩家私有举报记录

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `public_report_code` | `varchar(32)` | NOT NULL, UQ | 举报人可见编号，不可枚举他人记录 |
| `reporter_user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 举报人 |
| `target_type` | `varchar(16)` | NOT NULL | `MESSAGE/HAND/PLAYER/OTHER` |
| `target_id` | `uuid` | NULL | 对象 ID；文本对象另存安全摘要 |
| `reason_code` | `varchar(32)` | NOT NULL | `ABUSE/HARASSMENT/COLLUSION/OTHER` |
| `description` | `varchar(500)` | NULL | 补充说明 |
| `status` | `varchar(24)` | NOT NULL | `SUBMITTED/IN_REVIEW/RESOLVED/REJECTED` |
| `ticket_id` | `uuid` | FK → `support_ticket.id`, NOT NULL | 内部案件；不同举报人可关联同一案件 |
| `submitted_at` | `timestamptz` | NOT NULL | 首次提交时间 |
| `last_submitted_at` | `timestamptz` | NOT NULL | 24h 合并判断 |
| `public_conclusion` | `varchar(500)` | NULL | 结案 1–500 字，禁止私牌/IP/他人身份 |
| `conclusion_read_at` | `timestamptz` | NULL | 玩家已读时间 |

唯一合并规则：同举报人、同对象 24h 内追加原记录；不同举报人不得合并其私有前台记录。

### 11.6 `report_appendix` — 举报补充说明

不可变。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `report_id` | `uuid` | FK → `report_submission.id`, NOT NULL | 举报 |
| `content` | `varchar(500)` | NOT NULL | 补充说明 |
| `submitted_at` | `timestamptz` | NOT NULL | 提交时间 |
| `reopened_ticket` | `boolean` | NOT NULL | 已结案追加会重回 IN_REVIEW |

### 11.7 `support_ticket` — 内部客服/风控案件

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `ticket_code` | `varchar(32)` | NOT NULL, UQ | 内部案件号 |
| `ticket_type` | `varchar(24)` | NOT NULL | `REPORT/RECOVERY/RISK/OTHER` |
| `club_id` | `uuid` | FK → `club.id`, NULL | 范围 |
| `room_id` | `uuid` | FK → `room.id`, NULL | 房间 |
| `hand_id` | `uuid` | FK → `hand.id`, NULL | 手牌 |
| `status` | `varchar(24)` | NOT NULL | `OPEN/IN_REVIEW/RESOLVED/REJECTED` |
| `assignee_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 负责人 |
| `priority` | `varchar(8)` | NOT NULL | `P0/P1/P2/P3` |
| `internal_summary` | `text` | NULL, PII | 内部摘要，不返回玩家 |
| `resolution_code` | `varchar(64)` | NULL | 处置类型 |
| `resolved_at` | `timestamptz` | NULL | 结案时间 |
| `retention_until` | `timestamptz` | NOT NULL | 证据至少保留至结案并按策略延长 |

### 11.8 `ticket_event` — 工单处理轨迹

不可变。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `ticket_id` | `uuid` | FK → `support_ticket.id`, NOT NULL | 工单 |
| `seq_no` | `integer` | NOT NULL | 轨迹顺序 |
| `event_type` | `varchar(32)` | NOT NULL | `ASSIGNED/NOTE_ADDED/MUTED/STATUS_CHANGED/ACCESS_REQUESTED` 等 |
| `operator_admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 操作者 |
| `internal_note` | `text` | NULL, PII | 内部备注 |
| `public_note` | `varchar(500)` | NULL | 可公开内容；必须显式填写，不从内部备注复制 |
| `occurred_at` | `timestamptz` | NOT NULL | 时间 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NULL | 实际业务操作 |

唯一约束：`(ticket_id, seq_no)`。

### 11.9 `ticket_evidence` — 工单证据元数据

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `ticket_id` | `uuid` | FK → `support_ticket.id`, NOT NULL | 工单 |
| `evidence_type` | `varchar(24)` | NOT NULL | `MESSAGE/HAND_EVENT/LOGIN_LINK/FILE` |
| `object_type` | `varchar(32)` | NOT NULL | 对象类型 |
| `object_id` | `uuid` | NULL | 对象主键 |
| `object_key` | `text` | NULL, SECRET | 独立证据存储键，不存永久公开 URL |
| `content_digest` | `bytea` | NOT NULL | 完整性摘要 |
| `retention_until` | `timestamptz` | NOT NULL | 保留截止 |
| `added_by_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 添加人；系统保全可为空 |

### 11.10 `private_card_access_request` — 私牌专项申请与审批

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `request_code` | `varchar(40)` | NOT NULL, UQ | 专项申请号 |
| `ticket_id` | `uuid` | FK → `support_ticket.id`, NOT NULL | 有效工单 |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL | 必须已结束手 |
| `purpose` | `varchar(500)` | NOT NULL | 指定用途 |
| `requester_admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 申请人 |
| `authorized_admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 获准访问人；V1必须等于申请人 |
| `approver_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 审批人，不得与申请人相同 |
| `status` | `varchar(24)` | NOT NULL | `PENDING/APPROVED/REJECTED/EXPIRED/REVOKED` |
| `approved_at` | `timestamptz` | NULL | 审批时间 |
| `valid_until` | `timestamptz` | NULL | APPROVED 时等于 `approved_at + 30 minutes`；工单关闭时即使未到期也拒绝 |
| `decision_reason` | `varchar(500)` | NULL | 审批理由 |
| `decision_authorization_id` | `uuid` | FK → `sensitive_authorization.id`, NULL, UQ | 审批或拒绝动作自身的单次敏感授权；不得替代每次访问授权 |
| `decision_operation_id` | `uuid` | FK → `business_operation.id`, NULL, UQ | 审批/拒绝业务操作；PENDING 时为空 |
| `revoked_at` | `timestamptz` | NULL | 主动撤销时间 |
| `revoke_reason` | `varchar(500)` | NULL | 撤销原因 |

约束：`authorized_admin_id=requester_admin_id`；审批人不得等于申请人；APPROVED/REJECTED 必须同时具备审批人、决定授权和决定操作，APPROVED 还必须具备审批时间和到期时间，REJECTED 必须有理由。目标玩家由子表保存，不得恢复为数组。`sensitive_authorization` 建立 `UNIQUE(id, operation_id)`，本表建立复合外键 `(decision_authorization_id, decision_operation_id) → sensitive_authorization(id, operation_id)`。

应用角色不得直接更新审批终态，只能调用 `decide_private_card_access_request`。函数锁定申请和授权，复核专项审批权限、非自审、工单、手牌、参数摘要、会话、权限版本和120秒期限，在同一事务内消费授权、写审批终态、业务操作结果和不可变审计；同操作号同参数返回原结果，同号异参数拒绝。

### 11.11 `private_card_access_request_player` — 私牌申请目标玩家

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `request_id` | `uuid` | FK → `private_card_access_request.id`, NOT NULL | 专项申请 |
| `hand_id` | `uuid` | NOT NULL | 冗余绑定申请手牌，用于复合外键 |
| `user_id` | `uuid` | NOT NULL | 获准读取的玩家 |

主键/唯一约束：`(request_id, user_id)`；申请表建立 `UNIQUE(id, hand_id)`，本表以 `(request_id, hand_id) → private_card_access_request(id, hand_id)` 锁定申请手牌，并以 `(hand_id, user_id) → hand_player(hand_id, user_id)` 保证目标确为该手参与者。每个申请至少一条目标记录；应用角色不得直接写入本表。

### 11.12 `private_card_access_log` — 私牌实际访问轨迹

不可变。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `access_attempt_code` | `varchar(48)` | NOT NULL, UQ | 每次实际读取或拒绝尝试的稳定编号 |
| `access_request_id` | `uuid` | FK → `private_card_access_request.id`, NOT NULL | 已批准申请 |
| `admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 实际访问者 |
| `session_id` | `uuid` | FK → `admin_session.id`, NOT NULL | 原会话 |
| `sensitive_authorization_id` | `uuid` | FK → `sensitive_authorization.id`, NOT NULL, UQ | 本次访问对应的120秒参数绑定TOTP单次授权，不得复用 |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL | 手牌 |
| `accessed_at` | `timestamptz` | NOT NULL | 时间 |
| `purpose_snapshot` | `varchar(500)` | NOT NULL | 用途快照 |
| `result` | `varchar(16)` | NOT NULL | `ALLOWED/DENIED` |
| `failure_code` | `varchar(64)` | NULL | 过期、撤权、越范围等 |

约束：申请表的 `UNIQUE(id, hand_id)` 同时作为复合引用目标，`(access_request_id, hand_id) → private_card_access_request(id, hand_id)`，防止访问日志替换为另一手牌；`admin_id` 必须等于申请的 `authorized_admin_id`，由受限读取函数和约束触发器双重保证。

### 11.13 `private_card_access_log_player` — 私牌实际访问目标

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `access_log_id` | `uuid` | FK → `private_card_access_log.id`, NOT NULL | 一次实际访问 |
| `hand_id` | `uuid` | NOT NULL | 冗余绑定访问手牌，用于复合外键 |
| `user_id` | `uuid` | NOT NULL | 实际请求读取的玩家；拒绝尝试也记录 |

主键/唯一约束：`(access_log_id, user_id)`；访问日志表建立 `UNIQUE(id, hand_id)`，本表以 `(access_log_id, hand_id) → private_card_access_log(id, hand_id)` 锁定访问手牌，并以 `(hand_id, user_id) → hand_player(hand_id, user_id)` 保证目标确为该手参与者。`ALLOWED` 时目标集合必须是申请目标集合的子集，由唯一受限读取函数校验；`DENIED` 仍可记录越范围目标。

应用运行角色没有 `hand_card.card_ciphertext` 的直接 SELECT 权限，只能调用 `read_private_cards(request_id, sensitive_authorization_id, hand_id, player_ids)` 安全定义函数。函数在同一事务中锁定申请和单次授权，验证结束手、工单处于 `OPEN/IN_REVIEW`、获准访问人、独立审批、30分钟期限、会话、权限版本、参数摘要及目标子集；随后原子消费授权并写访问日志。拒绝路径返回安全错误码并提交 DENIED 日志，不通过抛异常回滚掉审计证据。

## 12. 后台身份、权限与安全域

### 12.1 `admin_user` — 独立后台人员账号

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `admin_code` | `varchar(32)` | NOT NULL, UQ | 后台稳定 ID |
| `login_name` | `citext` | NOT NULL, UQ, PII | 登录名；与 TG 玩家身份分离 |
| `display_name` | `varchar(80)` | NOT NULL | 展示名 |
| `password_hash` | `text` | NULL, SECRET | Argon2id 等现代口令哈希；INVITED 可为空 |
| `status` | `varchar(24)` | NOT NULL | `INVITED/ACTIVE/DISABLED/RESET_PENDING` |
| `linked_user_id` | `uuid` | FK → `app_user.id`, NULL | 同一自然人的可选关联，不继承玩家权限 |
| `linked_agent_id` | `uuid` | FK → `agent.id`, NULL | 代理只读工作台关联，不自动获得管理权 |
| `authorization_version` | `bigint` | NOT NULL, default 1 | 角色/范围变更递增，撤销旧会话和授权 |
| `failed_login_count` | `smallint` | NOT NULL, default 0 | 登录失败计数 |
| `login_locked_until` | `timestamptz` | NULL | 5 次失败锁 15 分钟 |
| `failed_password_change_count` | `smallint` | NOT NULL, default 0 | 与登录计数分离 |
| `password_change_locked_until` | `timestamptz` | NULL | 改密锁定 |
| `failed_sensitive_auth_count` | `smallint` | NOT NULL, default 0 | 敏感操作验证失败计数，与登录/改密分离 |
| `sensitive_auth_locked_until` | `timestamptz` | NULL | 5 次失败锁敏感验证 15 分钟，不影响只读会话 |
| `last_full_auth_at` | `timestamptz` | NULL | 最近密码+TOTP 完整认证 |
| `activated_at` | `timestamptz` | NULL | 激活时间 |
| `disabled_at` | `timestamptz` | NULL | 停用时间 |

### 12.2 `admin_totp_authenticator` — 后台认证器

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 后台账号 |
| `secret_ciphertext` | `bytea` | NOT NULL, SECRET | TOTP 密钥信封加密 |
| `key_version` | `varchar(32)` | NOT NULL, SECRET | KMS 密钥版本 |
| `status` | `varchar(16)` | NOT NULL | `PENDING/ACTIVE/REVOKED` |
| `verified_at` | `timestamptz` | NULL | 首个 TOTP 验证时间 |
| `last_used_step` | `bigint` | NULL, CK >=0 | 已消费最大时间步；成功必须严格递增 |
| `revoked_at` | `timestamptz` | NULL | 重绑时撤销 |

约束：每账号最多一个 ACTIVE 认证器。TOTP 校验服务器当前步 N 的 [N−1,N+1]；密码和码验证成功后锁定认证器，以 `UPDATE ... SET last_used_step=:matched_step WHERE status='ACTIVE' AND (last_used_step IS NULL OR last_used_step < :matched_step) RETURNING id` 原子消费，必须恰一行。与登录会话或单次 sensitive_authorization 创建同事务提交，失败回滚不能签发任何会话/授权。并发同一步仅一次成功；先消费 N+1 后，N 和 N+1 均拒绝（即使 N 从未用过），N+2 在进入容差窗口后才可用。服务器时钟回拨不降低高水位，等待时钟恢复或受审计重绑新认证器，不清零旧认证器。V015 触发器禁止减小/清空高水位；仅字段不变并不代表验证成功，认证入口必须用上述条件更新。单值方案足够，不能只判断 step != last_used_step。同一码在窗口内匹配多个时间步时确定性选择大于高水位的最大匹配步，再原子消费，不进行多次签发尝试。

### 12.3 `admin_activation_token` — 激活/人工重置凭据

只存摘要，24 小时单次使用。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 目标账号 |
| `token_hash` | `bytea` | NOT NULL, UQ, SECRET | 凭据摘要 |
| `purpose` | `varchar(16)` | NOT NULL | `ACTIVATE/RESET` |
| `expires_at` | `timestamptz` | NOT NULL | 24h |
| `used_at` | `timestamptz` | NULL | 使用时间 |
| `revoked_at` | `timestamptz` | NULL | 重发作废旧凭据 |
| `created_by_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 超管创建；本地初始化可空并写审计主体 |
| `identity_verification_channel` | `varchar(128)` | NULL, PII | 人工重置核验渠道摘要，不存多余隐私 |
| `reason` | `varchar(500)` | NOT NULL | 创建原因 |

约束：同一账号、同一用途最多一个未使用且未撤销凭据，建立 `UNIQUE(admin_id, purpose) WHERE used_at IS NULL AND revoked_at IS NULL`。重发必须在同一受限函数事务内锁定账号、撤销旧凭据并创建新凭据；已过期但未收口的记录先写 `revoked_at`。人工 RESET 的 `created_by_admin_id` 不得等于 `admin_id`；受控本地恢复允许创建者为空，但必须绑定工单号并写系统审计。

### 12.4 `admin_recovery_code` — 单次恢复码

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 账号 |
| `code_hash` | `bytea` | NOT NULL, UQ, SECRET | 仅存强哈希 |
| `batch_no` | `uuid` | NOT NULL | 每次生成 10 个为一批 |
| `used_at` | `timestamptz` | NULL | 单次使用 |
| `revoked_at` | `timestamptz` | NULL | 重绑后整批撤销 |

### 12.5 `admin_session` — 后台会话

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 账号 |
| `session_token_hash` | `bytea` | NOT NULL, UQ, SECRET | 令牌摘要 |
| `session_type` | `varchar(16)` | NOT NULL | `BUSINESS/RECOVERY` |
| `authorization_version` | `bigint` | NOT NULL | 建立时权限版本；不匹配即拒绝 |
| `created_ip` | `inet` | NULL, PII | 来源 IP |
| `user_agent` | `varchar(1024)` | NULL, PII | 设备摘要 |
| `authenticated_at` | `timestamptz` | NOT NULL | 完整认证时间 |
| `last_active_at` | `timestamptz` | NOT NULL | 仅主动查询/操作更新；轮询不续期 |
| `idle_expires_at` | `timestamptz` | NOT NULL | 15 分钟 |
| `absolute_expires_at` | `timestamptz` | NOT NULL | 8 小时；恢复会话 15 分钟 |
| `revoked_at` | `timestamptz` | NULL | 撤销时间 |
| `revoke_reason` | `varchar(64)` | NULL | 改密、停用、改权、重置等 |

### 12.6 `admin_role` — 后台角色

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `role_code` | `varchar(32)` | NOT NULL, UQ | `SUPER_ADMIN/OPERATOR/SUPPORT/AGENT_READONLY` |
| `name` | `varchar(64)` | NOT NULL | 展示名 |
| `is_system` | `boolean` | NOT NULL | 系统角色不可任意删除 |
| `status` | `varchar(16)` | NOT NULL | `ACTIVE/INACTIVE` |

### 12.7 `admin_permission` — 原子动作权限

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `permission_code` | `varchar(32)` | NOT NULL, UQ | 对应权限矩阵 `BP-01`～`BP-31` 或更细动作码 |
| `action_code` | `varchar(64)` | NOT NULL, UQ | 如 `CLUB.CREATE`、`LEDGER.ADJUST` |
| `resource_type` | `varchar(32)` | NOT NULL | 资源类型 |
| `sensitive` | `boolean` | NOT NULL | 是否要求单次 TOTP 授权 |
| `description` | `varchar(255)` | NOT NULL | 权限说明 |

### 12.8 `admin_role_permission` — 角色动作映射

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `role_id` | `uuid` | FK → `admin_role.id`, NOT NULL | 角色 |
| `permission_id` | `uuid` | FK → `admin_permission.id`, NOT NULL | 权限 |
| `effect` | `varchar(8)` | NOT NULL, CK `ALLOW/DENY` | 明确拒绝优先 |

唯一约束：`(role_id, permission_id)`。

### 12.9 `admin_user_role` — 人员角色授予

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 人员 |
| `role_id` | `uuid` | FK → `admin_role.id`, NOT NULL | 角色 |
| `valid_from` | `timestamptz` | NOT NULL | 起始 |
| `valid_until` | `timestamptz` | NULL | 可选截止 |
| `granted_by_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 授权人；初始化可空 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL | 授权操作 |
| `sensitive_authorization_id` | `uuid` | FK → `sensitive_authorization.id`, NULL | ADMIN来源必填；受控初始化为空 |
| `grant_source` | `varchar(16)` | NOT NULL | `ADMIN/BOOTSTRAP`；BOOTSTRAP只允许版本化种子迁移 |
| `revoked_at` | `timestamptz` | NULL | 撤权时间 |

约束：`valid_until IS NULL OR valid_until > valid_from`；同一 `admin_id + role_id` 的未撤销有效区间不得重叠。ADMIN来源必须同时具备授权人和敏感授权，BOOTSTRAP来源二者均为空并由Flyway种子迁移专用角色写入。建立复合外键 `(sensitive_authorization_id, operation_id) → sensitive_authorization(id, operation_id)`；同一授权可在一次原子操作内授予多个角色/范围，不能在操作外复用。

### 12.10 `admin_scope_grant` — 资源范围与业务上限

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 人员 |
| `scope_type` | `varchar(24)` | NOT NULL | `GLOBAL/CLUB/AGENT/TICKET/ROOM` |
| `scope_id` | `uuid` | NULL | GLOBAL 为空，其余对应资源 |
| `permission_id` | `uuid` | FK → `admin_permission.id`, NULL | 空表示角色内所有可范围化动作 |
| `commission_rate_ceiling` | `numeric(9,6)` | NULL, CK 0–1 | 运营比例授权上限 |
| `valid_from` | `timestamptz` | NOT NULL | 起始 |
| `valid_until` | `timestamptz` | NULL | 截止 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL | 授权操作 |
| `granted_by_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 授权人；受控初始化可空 |
| `sensitive_authorization_id` | `uuid` | FK → `sensitive_authorization.id`, NULL | ADMIN来源必填；受控初始化为空 |
| `grant_source` | `varchar(16)` | NOT NULL | `ADMIN/BOOTSTRAP` |
| `revoked_at` | `timestamptz` | NULL | 撤权时间 |

约束：`scope_type='GLOBAL'` 当且仅当 `scope_id IS NULL`；`valid_until IS NULL OR valid_until > valid_from`。使用规范化 `scope_id/permission_id` 和 `tstzrange` 排斥同一管理员、作用域、权限的未撤销重叠区间；`permission_id IS NULL` 的全动作范围与同一作用域下任一具体权限区间也不得重叠，由受限函数和约束触发器保证，避免撤销宽授权后仍残留重复窄授权。ADMIN来源必须具备授权人和敏感授权，BOOTSTRAP仅允许种子迁移。建立复合外键 `(sensitive_authorization_id, operation_id) → sensitive_authorization(id, operation_id)`。索引：`(admin_id, scope_type, scope_id) WHERE revoked_at IS NULL`。源/目标迁移需分别命中授权范围。

应用角色不得直接写 `admin_user_role` 或 `admin_scope_grant`，统一调用 `apply_admin_grant`。函数锁定目标管理员和单次授权，校验不可自提权、操作者当前范围与上限、参数摘要及未消费状态，在同一事务内写入/撤销授权、递增目标 `authorization_version`、撤销目标全部旧会话和未消费授权并写审计。撤权时把 `valid_until` 收口到撤权时间，保证历史区间与实际生效时点一致。

#### 权限组合判定（ADR-012）

在数据库事务时刻 t，仅使用 ACTIVE 账号/角色、未撤销且 valid_from<=t<valid_until（空截止为无穷）的授权。先校验原会话、authorization_version、资源实时归属，再判下表；所有 SUPER_ADMIN 也适用显式 DENY 与单次敏感授权，独立字段无隐式超管绕过。

| 条件 | 结果 |
| --- | --- |
| 任一有效角色对该 permission 显式 DENY | DENY，其他角色 ALLOW、GLOBAL/窄范围均不能覆盖 |
| 无 DENY，至少一有效角色 ALLOW | 取得动作候选能力；还须命中 scope |
| 只有 scope（即使 permission_id 明确）但角色无 ALLOW | DENY；scope 仅限缩能力，不创造动作权限 |
| scope.permission_id 为空 | 匹配已有角色 ALLOW 的可范围化动作，不授 IP/私牌/导出等独立动作 |
| 动作 ALLOW 且至少一个有效范围覆盖当前资源 | 按该动作继续验证业务条件；无匹配默认 DENY |
| 多个匹配范围带上限 | 采用所有匹配非空 commission_rate_ceiling 的最小值，空值不增权；若动作要求上限且全为空则拒绝 |
| 源/目标迁移或批量请求 | 每一个资源分别命中同一动作权限和范围；禁止只用源范围授权目标 |
| 敏感动作 | 前述通过后仍须参数、操作号、会话及权限版本绑定的未过期单次授权 |

GLOBAL 覆盖所有对象；CLUB/ROOM/AGENT/TICKET 仅按当前权威关系覆盖相应对象，不从名称或前端过滤条件推断。不同范围可以重叠，组合采用上述最小上限。相同规范化 scope 的同动作重叠，以及同 scope 的空 permission 与具体 permission 重叠仍按现有触发器拒绝；不新增“窄范围覆盖宽范围”优先级。所有列表/详情/汇总/回放/导出共用判定器和行过滤，字段独立权限逐项裁剪。异步执行与下载重新判定当前权限；撤权、版本推进和旧授权失效原子提交。若依菜单只展示判定结果。

### 12.11 `admin_auth_event` — 后台认证与安全事件

不可变。V1 使用普通表并按 `occurred_at` 建索引，以保留全局事件追踪和单列 UUID 主键。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `admin_id` | `uuid` | FK → `admin_user.id`, NULL | 未识别账号时为空 |
| `login_name_hash` | `bytea` | NULL, PII | 失败登录关联，不保存多余明文 |
| `event_type` | `varchar(32)` | NOT NULL | `LOGIN/ACTIVATE/RECOVERY/PASSWORD_CHANGE/TOTP_RESET/SENSITIVE_AUTH` |
| `success` | `boolean` | NOT NULL | 结果 |
| `failure_code` | `varchar(64)` | NULL | 统一文案背后的安全码 |
| `ip_address` | `inet` | NULL, PII | 来源 |
| `user_agent` | `varchar(1024)` | NULL, PII | 客户端 |
| `occurred_at` | `timestamptz` | NOT NULL | 时间 |
| `request_id` | `uuid` | NULL | 链路号 |

### 12.12 `sensitive_authorization` — 参数绑定单次授权

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 操作者 |
| `session_id` | `uuid` | FK → `admin_session.id`, NOT NULL | 原会话 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL, UQ | 绑定操作 |
| `action_code` | `varchar(64)` | NOT NULL | 敏感动作 |
| `parameter_digest` | `bytea` | NOT NULL | 对象、金额、币种、范围等规范化摘要 |
| `authorization_version` | `bigint` | NOT NULL | 生成时权限版本 |
| `verified_totp_step` | `bigint` | NOT NULL | 不可与登录或其他授权复用 |
| `status` | `varchar(16)` | NOT NULL | `ISSUED/CONSUMED/EXPIRED/REVOKED` |
| `expires_at` | `timestamptz` | NOT NULL | 默认 120 秒 |
| `consumed_at` | `timestamptz` | NULL | 仅一次 |

执行时必须同时校验会话、权限版本、参数摘要、时效和未消费状态。

唯一约束：`(id, operation_id)`，供资金调整等敏感业务建立复合外键，确保授权对象、参数和业务操作不可被重新组合。消费授权的受限函数必须对本行执行 `SELECT ... FOR UPDATE`；应用角色不得直接修改授权状态。

## 13. 业务操作、审计、恢复与导出域

### 13.1 `business_operation` — 统一请求与实际生效状态

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `operation_code` | `varchar(40)` | NOT NULL, UQ | 后台/客户端可查询操作号 |
| `request_id` | `uuid` | NOT NULL, UQ | 调用方生成幂等号 |
| `actor_type` | `varchar(16)` | NOT NULL | `USER/ADMIN/SYSTEM` |
| `actor_id` | `uuid` | NOT NULL | 对应主体；系统主体使用固定服务 ID |
| `operation_type` | `varchar(64)` | NOT NULL | 开房、买入、迁移、调款、关桌等 |
| `target_type` | `varchar(32)` | NOT NULL | 对象类型 |
| `target_id` | `uuid` | NULL | 对象可能在成功后才生成 |
| `parameter_digest` | `bytea` | NOT NULL | 同 ID 异参数检测 |
| `parameter_summary` | `jsonb` | NOT NULL | 脱敏参数摘要，不存 token/TOTP/私牌 |
| `request_status` | `varchar(24)` | NOT NULL | `SUBMITTING/UNKNOWN/FAILED/SUCCEEDED` |
| `domain_status` | `varchar(32)` | NULL | `ACCEPTED/PENDING_EFFECT/APPLIED/CANCELLED/SETTLING/SETTLED` 等 |
| `submitted_at` | `timestamptz` | NOT NULL | 提交时间 |
| `accepted_at` | `timestamptz` | NULL | 业务方受理时间 |
| `effective_at` | `timestamptz` | NULL | 实际生效时间 |
| `completed_at` | `timestamptz` | NULL | 终态时间 |
| `reason` | `varchar(500)` | NULL | 写操作原因 |
| `error_category` | `varchar(32)` | NULL | 前端稳定错误分类 |
| `error_code` | `varchar(64)` | NULL | 精确错误码 |
| `error_message` | `varchar(500)` | NULL | 安全可展示信息 |
| `result_summary` | `jsonb` | NULL | 脱敏结果；查询原号直接返回 |
| `parent_operation_id` | `uuid` | FK → `business_operation.id`, NULL | 审核、纠错、撤销等关系 |

索引：`(actor_type, actor_id, submitted_at desc)`、`(request_status, submitted_at)`、`(target_type, target_id, submitted_at desc)`。UNKNOWN 不能自动转失败或产生退款。

### 13.2 `audit_log` — 不可删除审计日志

不可变。V1 使用普通表并按 `occurred_at` 建索引，默认保留 365 天；未来分区须先处理全局 `audit_code` 与外键策略。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `audit_code` | `varchar(48)` | NOT NULL, UQ | 审计事件号 |
| `operator_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 后台操作者；系统事件可空 |
| `operator_user_id` | `uuid` | FK → `app_user.id`, NULL | 玩家写操作 |
| `role_snapshot` | `varchar(32)[]` | NOT NULL | 当时角色 |
| `scope_snapshot` | `jsonb` | NOT NULL | 当时范围的脱敏摘要 |
| `action_code` | `varchar(64)` | NOT NULL | 动作 |
| `object_type` | `varchar(32)` | NOT NULL | 对象类型 |
| `object_id` | `uuid` | NULL | 对象 |
| `before_value` | `jsonb` | NULL | 脱敏前值 |
| `after_value` | `jsonb` | NULL | 脱敏后值 |
| `reason` | `varchar(500)` | NULL | 原因 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NULL | 操作号 |
| `request_id` | `uuid` | NULL | 请求号 |
| `original_business_id` | `varchar(64)` | NULL | 原业务号 |
| `result` | `varchar(16)` | NOT NULL | `ALLOWED/DENIED/SUCCEEDED/FAILED` |
| `error_code` | `varchar(64)` | NULL | 错误 |
| `occurred_at` | `timestamptz` | NOT NULL | 提交/访问时间 |
| `effective_at` | `timestamptz` | NULL | 延迟动作实际生效时间 |

禁止记录密码、TOTP、完整 token、完整牌序和无关 PII。应用角色仅 INSERT/SELECT，无 UPDATE/DELETE。

### 13.3 `recovery_case` — 游戏/资金故障恢复事件

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `case_code` | `varchar(40)` | NOT NULL, UQ | 恢复事件号 |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间 |
| `hand_id` | `uuid` | FK → `hand.id`, NULL | 原手 |
| `settlement_id` | `uuid` | FK → `hand_settlement.id`, NULL | 可证结算 |
| `status` | `varchar(24)` | NOT NULL | `OPEN/RECOVERING/RECOVERED/VOIDED/RECOVERY_REQUIRED/CLOSED` |
| `evidence_state` | `varchar(32)` | NOT NULL | `SETTLEMENT_COMMITTED/LOG_REPLAYABLE/PREFLOP_SNAPSHOT_ONLY/UNKNOWN` |
| `selected_path` | `varchar(32)` | NULL | `RENOTIFY/RESUME_SAME_HAND/VOID_AND_REVERSE/HOLD_FOR_REVIEW` |
| `last_committed_event_id` | `uuid` | FK → `hand_event.id`, NULL | 最后可信事件 |
| `owner_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 负责人 |
| `decision_reason` | `varchar(1000)` | NULL | 恢复依据 |
| `opened_at` | `timestamptz` | NOT NULL | 发现时间 |
| `updated_business_at` | `timestamptz` | NOT NULL | 最近处置更新时间 |
| `closed_at` | `timestamptz` | NULL | 完成时间 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NULL | 受控恢复请求 |

案件冻结资金总额按 `recovery_case_item` 分资产汇总，不在案件头保存无资产的可写总额。恢复处置只能追加或更新明细终态，不能覆盖原账本和原交易。

### 13.4 `recovery_case_item` — 恢复资金与对象明细

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `case_id` | `uuid` | FK → `recovery_case.id`, NOT NULL | 恢复案件 |
| `item_no` | `integer` | NOT NULL | 案件内顺序 |
| `user_id` | `uuid` | FK → `app_user.id`, NULL | 受影响玩家；纯平台项目可空 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 资产，禁止跨资产汇总金额 |
| `ledger_account_id` | `uuid` | FK → `ledger_account.id`, NULL | 受影响账户 |
| `original_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL | 原买入、补码、结算或退出交易 |
| `seat_session_id` | `uuid` | FK → `seat_session.id`, NULL | 受影响资金会话 |
| `amount` | `bigint` | NOT NULL, CK >0 | 等待核查或处置金额 |
| `status` | `varchar(24)` | NOT NULL | `FROZEN/CONFIRMED/REVERSED/RELEASED/HELD_FOR_REVIEW` |
| `disposition_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL | 最终冲正或释放交易；一个多方零和交易可处置多个明细 |
| `decision_reason` | `varchar(500)` | NULL | 明细处置依据 |
| `resolved_at` | `timestamptz` | NULL | 明细终态时间 |

唯一约束：`(case_id, item_no)`。至少关联账户、原交易或资金会话之一；终态 `REVERSED/RELEASED` 必须关联处置交易。案件、明细处置、账本交易和审计在同一受限恢复函数事务内提交。

### 13.5 `export_task` — 异步导出任务

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `task_code` | `varchar(40)` | NOT NULL, UQ | 任务号 |
| `admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 发起人 |
| `session_id` | `uuid` | FK → `admin_session.id`, NOT NULL | 绑定原会话 |
| `export_type` | `varchar(32)` | NOT NULL | 账本、审计、房间、分成等 |
| `filter_json` | `jsonb` | NOT NULL | 原筛选，时间区间不得超过 31 天 |
| `column_codes` | `varchar(64)[]` | NOT NULL | 申请列；不含无权隐藏列 |
| `scope_digest` | `bytea` | NOT NULL | 生成时权限范围摘要 |
| `status` | `varchar(24)` | NOT NULL | `QUEUED/GENERATING/READY/FAILED/EXPIRED/REVOKED` |
| `object_key` | `text` | NULL, SECRET | 私有存储键，不是公开 URL |
| `row_count` | `bigint` | NULL | 导出行数 |
| `data_cutoff_at` | `timestamptz` | NULL | 数据时点 |
| `ready_at` | `timestamptz` | NULL | 生成完成 |
| `expires_at` | `timestamptz` | NULL | 生成起 15 分钟 |
| `failure_code` | `varchar(64)` | NULL | 撤权、服务失败等 |

生成中和每次下载都重验账号、原会话、当前权限与范围；CSV 文本防公式注入，ID 保持文本格式。

### 13.6 `export_download_log` — 导出下载审计

不可变。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `export_task_id` | `uuid` | FK → `export_task.id`, NOT NULL | 任务 |
| `admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 下载人，必须等于任务发起人 |
| `session_id` | `uuid` | FK → `admin_session.id`, NOT NULL | 原会话 |
| `downloaded_at` | `timestamptz` | NOT NULL | 时间 |
| `result` | `varchar(16)` | NOT NULL | `ALLOWED/DENIED` |
| `failure_code` | `varchar(64)` | NULL | 过期、撤权、会话失效等 |
| `ip_address` | `inet` | NULL, PII | 下载来源 |

### 13.7 `projection_checkpoint` — 报表投影水位与完整性

用于向运营页面明确数据截止时间和完整性；不得用“最后更新时间”冒充源业务时间。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `projection_name` | `varchar(64)` | NOT NULL, UQ | 如 `OPS_DAILY_METRICS/COMMISSION_DAILY/WALLET_BALANCE` |
| `status` | `varchar(24)` | NOT NULL | `CURRENT/PARTIAL/REBUILDING/FAILED` |
| `last_event_id` | `uuid` | NULL | 已处理的最后事件；不同源可改用业务游标 |
| `last_business_at` | `timestamptz` | NULL | 已覆盖的最晚业务时间 |
| `data_cutoff_at` | `timestamptz` | NOT NULL | 页面展示的数据截止时间 |
| `completeness_note` | `varchar(500)` | NULL | 缺失范围、旧摘要或重建说明 |
| `last_success_at` | `timestamptz` | NULL | 最近完整成功时间 |
| `failure_code` | `varchar(64)` | NULL | 失败原因 |

### 13.8 `outbox_event` — 不可变业务事件

不可变，包含 id/created_at，不含 updated_at/row_version；id 即全局 event_id。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL | 同事务业务操作；系统事件也须有幂等操作 |
| `aggregate_type` | `varchar(32)` | NOT NULL | 聚合类型 |
| `aggregate_id` | `uuid` | NOT NULL | 聚合主键；类型由生产者白名单约束 |
| `aggregate_version` | `bigint` | NOT NULL, CK >=0 | 已提交版本 |
| `event_type` | `varchar(64)` | NOT NULL | 版本化事件名 |
| `schema_version` | `smallint` | NOT NULL, default 1, CK >0 | payload 契约版本 |
| `payload` | `jsonb` | NOT NULL | 对象类型 JSON；最小必要字段，不含凭据或未公开私牌 |
| `occurred_at` | `timestamptz` | NOT NULL | 业务发生时刻 |

id PK；UNIQUE(operation_id,aggregate_type,aggregate_id,aggregate_version,event_type) 防同操作重复事件；索引(aggregate_type,aggregate_id,aggregate_version)、(created_at,id)。应用不能直接 INSERT/UPDATE/DELETE；事件与预期消费者 delivery 行由未来受限业务函数在同事务写入，不开放孤立 append API。

### 13.9 `outbox_delivery` — 每消费者投递与租约

包含通用 id/created_at/updated_at/row_version。UNIQUE(event_id,consumer_name)，一个事件可以投递到多个消费者，ACK 相互独立。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `event_id` | `uuid` | FK → `outbox_event.id`, NOT NULL | 不可变源事件 |
| `consumer_name` | `varchar(64)` | NOT NULL | 部署白名单消费者，不接受客户端任意目标 |
| `status` | `varchar(16)` | NOT NULL, default 'READY' | `READY/LEASED/DELIVERED/DEAD` |
| `attempt_count` | `integer` | NOT NULL, default 0, CK >=0 | 领取次数 |
| `available_at` | `timestamptz` | NOT NULL, default now() | 下次可领时间 |
| `lease_token` | `uuid` | NULL | 每次领取随机防栅令牌 |
| `lease_expires_at` | `timestamptz` | NULL | 租约截止 |
| `delivered_at` | `timestamptz` | NULL | 消费者确认成功时间 |
| `last_error_code` | `varchar(64)` | NULL | 无敏感信息的错误码 |

LEASED 当且仅当 lease_token/lease_expires_at 同时非空；DELIVERED 当且仅当 delivered_at 非空。READY/DEAD 不得残留租约。领取、ACK 与失败重试协议见架构 §8.4；索引(status,available_at)、(lease_expires_at) WHERE status='LEASED'。V015 仅落地结构与保护，不声称业务生产者、worker 和消费者已实现。投递入口未完成前保持 fail-closed。

## 14. 测试预设与分析事件域

### 14.1 `test_deal_run` — 隔离环境预设发牌运行

无运营后台写入口，仅受控部署工具写入；保留 365 天。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `scenario_id` | `varchar(64)` | NOT NULL | 场景 ID |
| `run_id` | `varchar(64)` | NOT NULL, UQ | 整个测试部署唯一；清理后也不支持复用 |
| `schema_version` | `smallint` | NOT NULL, CK =1 | 文件结构版本 |
| `content_digest` | `bytea` | NOT NULL | 规范化完整内容摘要；同 run_id 异内容冲突 |
| `target_type` | `varchar(16)` | NOT NULL | `ROOM/USER_SET` |
| `target_room_code` | `varchar(32)` | NULL | ROOM 定位 |
| `target_user_ids` | `uuid[]` | NULL | USER_SET 定位，必须同桌且全参局 |
| `deck_mode` | `varchar(16)` | NOT NULL | 与目标房间一致 |
| `payload_ciphertext` | `bytea` | NOT NULL, SECRET | 公共牌、指定底牌和规范化预设的密文 |
| `key_version` | `varchar(32)` | NOT NULL, SECRET | 加密密钥版本 |
| `status` | `varchar(24)` | NOT NULL | `REGISTERED/NOT_MATCHED/BOUND/CONSUMED/FAILED/VOIDED` |
| `bound_hand_id` | `uuid` | FK → `hand.id`, NULL, UQ | 与开手提交一致 |
| `registered_at` | `timestamptz` | NOT NULL | 登记时间 |
| `consumed_at` | `timestamptz` | NULL | 成功开手消费时间 |
| `failure_code` | `varchar(64)` | NULL | 文件错误、冲突、账号缺席等 |

约束：目标房间与用户集合恰有一个；正式环境或非 TEST 资产拒绝绑定。普通客户端只看到 `deal_source=SCRIPTED_TEST`。

### 14.2 `conversion_journey` — 加入转化旅程

业务读模型，可由服务端业务事件重建。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `journey_code` | `varchar(40)` | NOT NULL, UQ | journey_id |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间 |
| `entry_source` | `varchar(16)` | NOT NULL | `INVITE/CLUB_LIST`，首次合格入口归因 |
| `first_eligible_at` | `timestamptz` | NOT NULL | 服务端确认合格时间 |
| `window_ends_at` | `timestamptz` | NOT NULL | 30 分钟后 |
| `status` | `varchar(24)` | NOT NULL | `OPEN/BUYIN_POSTED/EXPIRED` |
| `buyin_operation_id` | `uuid` | FK → `business_operation.id`, NULL | 首次成功买入 |
| `buyin_posted_at` | `timestamptz` | NULL | 成功时间 |
| `initial_rejection_code` | `varchar(64)` | NULL | 非合格入口拒绝另行统计时使用 |
| `later_failure_code` | `varchar(64)` | NULL | 窗口内满桌、余额变化等，不删除分母 |
| `business_date` | `date` | NOT NULL | 按首次合格进入的 Asia/Shanghai 日期 |
| `is_test` | `boolean` | NOT NULL | 隔离测试不混正式指标 |

唯一规则：同 `user_id + room_id` 的未结束 30 分钟窗口只保留一条。

### 14.3 `analytics_event` — 非权威分析事件

V1 使用普通表并按 `occurred_at` 建索引；不得作为账务或业务终态来源。未来分区须先引入非分区事件 ID 注册表。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `event_code` | `varchar(48)` | NOT NULL, UQ | 事件 ID |
| `event_name` | `varchar(64)` | NOT NULL | 设计契约事件名 |
| `user_id` | `uuid` | FK → `app_user.id`, NULL | 玩家 |
| `room_id` | `uuid` | FK → `room.id`, NULL | 房间 |
| `journey_id` | `uuid` | FK → `conversion_journey.id`, NULL | 旅程 |
| `request_id` | `uuid` | NULL | 提交事件关联 |
| `business_id` | `varchar(64)` | NULL | 业务号 |
| `properties` | `jsonb` | NOT NULL | 按事件 schema 校验；禁止邀请码 token、TG 原始身份、IP、私牌、完整聊天正文 |
| `occurred_at` | `timestamptz` | NOT NULL | 服务端接收时间 |
| `is_test` | `boolean` | NOT NULL | 测试隔离 |

## 15. 建议视图与物化读模型

| 名称 | 类型 | 用途 | 关键口径 |
| --- | --- | --- | --- |
| `v_current_club_membership` | 视图 | 当前归属 | 仅 `club_membership.status='CURRENT'` |
| `v_user_wallet_balance` | 视图/投影 | 玩家资产与后台列表 | 可用+补码冻结+桌内托管；底池不重复 |
| `v_ledger_transaction_display` | 安全视图 | 账单/API展示状态 | 存储状态保持 `PENDING/POSTED/FAILED`；存在有效完整冲正时派生 `REVERSED` 并返回冲正交易与时间 |
| `v_room_public_summary` | 视图 | 俱乐部房间列表 | 只含公开人数、规则与状态，无私牌/钱包 |
| `v_player_session_result` | 物化读模型 | 战绩会话列表 | 单手净收益合计−离座费；结束时间归属 |
| `v_player_stat_period` | 参数化查询/汇总表 | VPIP/PFR/W$SD/bb100 | 玩法、资产分开；分母 0 返回 NULL |
| `v_hand_replay_public` | 安全视图 | 普通回放 | 本人底牌+当时公开牌，Muck/他人未公开牌不返回 |
| `v_ops_daily_metrics` | 物化视图 | 运营总览 | 去重 user_id/hand_id；按资产分组；显示 data_cutoff_at |
| `v_revenue_detail` | 视图 | 抽水与离座费 | 两类收入分列，代理应计不重复算收入 |
| `v_commission_current_statement` | 视图 | 当前代理日账 | 每代理/资产/业务日取最高版本 |
| `v_operation_pending_review` | 视图 | 待确认操作 | UNKNOWN、待生效、未清算、待重算分别分类 |
| `v_recovery_case_funds` | 视图 | 恢复案件资金明细与分资产合计 | 从 `recovery_case_item` 汇总，不跨资产合并，不以案件头缓存覆盖账本 |

所有后台视图必须在服务层叠加动作权限和资源范围；不能只靠前端筛选 `club_id`。如采用 PostgreSQL RLS，应把 RLS 作为纵深防御，仍保留服务层鉴权和审计。

## 16. 核心约束与索引清单

### 16.1 必须由数据库保证

1. 玩家最多一个活动操控会话、一个活动真人入座会话。
2. 玩家最多一个当前归属、一个待生效归属迁移。
3. 每个物理座位只有一条 `room_seat_occupancy`；预约、正式入座和空闲状态互斥，所有流转锁定同一行。
4. 每个 `seat_session` 最多一个 PENDING 补码。
5. `request_id`、`action_id`、`settlement_id`、账务幂等键均唯一；动作接受和拒绝结果都持久化，同号同参数返回原结果，同号异参数拒绝。
6. 每手房间号+手号唯一；动作、事件、底池在手内顺序唯一。
7. 结算守恒；复式账本每个 POSTED 事务至少两条分录、同一资产且 `sum(delta_amount)=0`，每行满足 `balance_after=balance_before+delta_amount`。
8. 金额为正整数最小单位；账户和玩家可用余额不得在不允许时为负。
9. 发布后的规则、费用、协议版本和房间快照不可更新。
10. 审计、账本分录、动作、事件、派奖、计提调整只追加，不更新不删除；账本原交易不得因冲正改状态。
11. 私牌申请目标和实际访问目标必须引用同手 `hand_player`；每次访问只消费一个唯一120秒授权，访问者必须等于获准人。
12. 调款的敏感授权、业务操作、调款记录和账本交易一一绑定；同一授权不得被第二次消费。
13. 原始代理归因按手牌、池和玩家唯一；每条原始归因最多一个冲正事件，不使用可空列普通唯一约束替代部分唯一索引。
14. 玩家、后台和系统消息分别满足幂等；发送者字段组合与 `sender_type` 一致。
15. 用户屏蔽不得指向自己；同一对用户最多一条ACTIVE关系，屏蔽不作用于SYSTEM或客服巡检消息。
16. 相同规则摘要允许创建多个独立房间快照；摘要只校验内容，不承担业务唯一性。
17. 邀请提交、审核和后续状态迁移分别绑定业务操作；邀请校验请求同号同参只保存一个结果。
18. 同俱乐部直接代理历史、同管理员角色/范围授权的有效区间不得重叠；撤权与权限版本、会话失效同事务提交。
19. 私牌审批决定和实际读取分别消费参数绑定的敏感授权，授权与操作号复合绑定。
20. 恢复冻结金额必须按玩家、资产、账户或原交易落到 `recovery_case_item`，不得只保存无资产汇总值。

跨行守恒、发布不可变和状态迁移使用受限数据库函数与约束触发器兜底；业务逻辑只在 Node 权威服务执行；数据库只保不可绕过的不变量、持久化与并发安全，见架构 ADR-009。账本、调款、动作、代理归因、座位占用、邀请状态、代理变更、权限授予、恢复处置和私牌审批/读取函数为强制写/读入口，不只是实现建议。

### 16.2 跨表约束实现矩阵

本矩阵是新增 Flyway 迁移的强制输入；V001～V014 已冻结，不重新生成。标记为受限函数的规则必须同时撤销应用角色对底层表的直接写权限；不能仅在 Java 服务中实现同名校验。

| 规则 | 主要对象 | 数据库实现 | 最低验证 |
| --- | --- | --- | --- |
| 模板、快照、房间、手牌同源 | `room_rule_snapshot`、`room`、`hand` | 复合唯一键与复合外键；循环引用后置创建 | 交叉替换模板或快照必须触发 FK 失败 |
| 当前会话、归属和活动关系唯一 | `player_session`、`seat_session`、`club_membership`、`mute_record` | 不依赖 `now()` 的部分唯一索引；受限函数先收口自然过期记录 | 100 并发只允许一个活动结果 |
| 座位预约、会话和占用行一致 | `room_seat_occupancy`、`seat_reservation`、`seat_session` | 可延迟循环外键、字段组合 CHECK、统一座位受限函数和行锁；预约为必选前置，过期拒绝 | 抢座、过期、买入、离座无悬空引用 |
| 动作请求和动作事实一致 | `hand_action_request`、`hand_action`、`hand_player` | 受限函数锁定请求；约束触发器校验手牌、玩家、会话和来源一致；请求到事实一对零或一 | 拒绝请求无动作；接受请求最多一条且上下文相同 |
| 手牌玩家、底牌、底池和派奖一致 | `hand_player`、`hand_card`、`hand_pot*` | 同手复合外键或 DEFERRABLE 约束触发器；发牌/结算函数一次提交 | 非参与者不得持牌、贡献或获池；牌组不得重复 |
| 账本同资产、零和及余额不越界 | `ledger_transaction`、`ledger_entry`、`ledger_account` | 撤销直接写权限；`post_ledger_transaction` 排序锁账户并校验跨行合计 | POSTED 至少两行、同资产、合计零；受限账户不为负 |
| 敏感授权与业务操作绑定 | `sensitive_authorization` 及调款、权限、私牌对象 | `(id, operation_id)` 复合引用、授权行锁和单次消费函数 | 错配、过期、重复消费、撤权和旧会话全部拒绝 |
| 权限和代理有效区间不重叠 | `admin_user_role`、`admin_scope_grant`、`club_agent_history`、`system_policy_version` | `btree_gist`、规范化空值和 `tstzrange` 排斥约束；同一 scope 的宽/窄授权重叠另用约束触发器；跨 scope 按 ADR-012 组合 | 并发重叠写入最多一个成功 |
| 多态目标真实存在且类型匹配 | `invite.target_id`、`admin_scope_grant.scope_id`、`ledger_account.owner_id`、审计对象 | 受限函数加约束触发器；按类型查询对应目标，核心对象不得只由前端或 ORM 校验 | 不存在目标或类型错配写入失败 |
| 恢复明细与资产、来源、处置一致 | `recovery_case_item`、账户、原交易、处置交易、资金会话 | `num_nonnulls` CHECK；复合资产外键或约束触发器；案件内规范化来源防重；受限恢复函数校验处置分录 | 跨资产、空来源、重复来源、错误处置交易均拒绝 |
| 发布对象和事实表不可改写 | 版本表、快照、账本分录、动作、事件、审计、访问日志 | 表级权限加拒绝 UPDATE/DELETE 触发器；允许的状态收口只通过专用函数 | 应用角色直接更新或删除失败 |
| 状态枚举和字段组合合法 | 所有 `status/type/mode/source/result` 字段 | `varchar + CHECK`；终态时间、原因、引用采用组合 CHECK | 非法枚举和不完整终态写入失败 |

### 16.3 高价值索引

| 表 | 索引 |
| --- | --- |
| `app_user` | `(game_id)`、`(status, registered_at desc)`、昵称 trigram |
| `player_identity` | `(provider, provider_subject)`唯一、`(user_id, provider) WHERE unbound_at IS NULL`唯一、`(id, user_id)`和`(id, provider)`复合引用键 |
| `local_credential` | `(identity_id)`共享主键；通过复合外键限定 LOCAL 身份 |
| `player_session` | `(user_id) WHERE revoked_at IS NULL`唯一、`(expires_at) WHERE revoked_at IS NULL`、`(session_token_hash)`唯一；身份与玩家复合同源 |
| `club_agent_history` | `(club_id) WHERE effective_to IS NULL`唯一、同俱乐部有效时间范围排斥、`(operation_id)`唯一 |
| `club_membership` | `(user_id) WHERE status='CURRENT'` 唯一、`(user_id) WHERE status='PENDING'` 唯一、`(club_id, status, user_id)` |
| `invite` | `(invite_code)`、`(token_hash)`、`(target_type, target_id, created_at desc)` |
| `invite_application` | `(status, created_at)`、`(applicant_user_id, created_at desc)`、`(submit_operation_id)`唯一、`(review_operation_id) WHERE review_operation_id IS NOT NULL`唯一 |
| `invite_application_event` | `(application_id, seq_no)`唯一、`(operation_id, application_id)`唯一、`(application_id, occurred_at desc)` |
| `invite_redemption` | `(request_id)`唯一、`(invite_id, user_id, occurred_at desc)` |
| `system_policy_version` | `(policy_key, version_no)`唯一、同策略 PUBLISHED 有效区间排斥 |
| `room` | `(club_id, status, created_at desc)`、`(status, scheduled_open_at)`、`(status, ends_at)` |
| `room_rule_snapshot` | `(content_digest)`普通索引，不唯一 |
| `room_seat_occupancy` | `(room_id, seat_no)` 唯一、`(user_id) WHERE status IN ('RESERVED','OCCUPIED')`、`(status, expires_at) WHERE status='RESERVED'` |
| `seat_session` | `(user_id) WHERE status NOT IN ('CLOSED')` 唯一、`(room_id, seat_no) WHERE status NOT IN ('CLOSED')` 唯一 |
| `hand` | `(room_id, hand_no)` 唯一、`(settled_at desc)`、`(status, updated_at)` |
| `hand_action_request` | `(action_code)` 唯一、`(hand_id, requested_at desc)`、`(result, requested_at)` |
| `hand_action` | `(hand_id, seq_no)`唯一、`(action_request_id)`唯一 |
| `ledger_transaction` | `(idempotency_key)`、`(user_id, created_at desc, id)`、`(hand_id)`、`(status, created_at)` |
| `ledger_entry` | `(account_id, posted_at desc, id)`、`(transaction_id, line_no)`、`(transaction_id, account_id)` 唯一 |
| `manual_adjustment` | `(sensitive_authorization_id)`唯一、`(operation_id)`唯一、`(ledger_transaction_id) WHERE ledger_transaction_id IS NOT NULL`唯一 |
| `commission_attribution` | `(hand_id, pot_id, user_id) WHERE original_event_id IS NULL`唯一、`(original_event_id) WHERE original_event_id IS NOT NULL`唯一、`(agent_id, asset_id, business_date)`、`(status, business_date)` |
| `commission_daily_statement` | `(agent_id, asset_id, business_date, version_no desc)` |
| `chat_message` | 玩家/后台/系统三组部分唯一幂等索引、`(room_id, sent_at desc, id)` |
| `mute_record` | 规范化`(user_id, room_id) WHERE status='ACTIVE'`唯一、`(issued_operation_id)`唯一、`(revoked_operation_id) WHERE revoked_operation_id IS NOT NULL`唯一、`(status, ends_at)` |
| `user_chat_block` | `(blocker_user_id, blocked_user_id) WHERE status='ACTIVE'`唯一、`(blocked_user_id, status)` |
| `support_ticket` | `(assignee_admin_id, status, updated_at desc)`、`(club_id, status)` |
| `admin_activation_token` | `(token_hash)`唯一、`(admin_id, purpose) WHERE used_at IS NULL AND revoked_at IS NULL`唯一、`(expires_at) WHERE used_at IS NULL AND revoked_at IS NULL` |
| `admin_user_role` | 同管理员角色有效时间范围排斥、`(admin_id, revoked_at, valid_until)` |
| `admin_scope_grant` | 规范化作用域与权限有效时间范围排斥、`(admin_id, scope_type, scope_id) WHERE revoked_at IS NULL` |
| `business_operation` | `(request_id)`、`(request_status, submitted_at)`、`(target_type, target_id)` |
| `audit_log` | `(operator_admin_id, occurred_at desc)`、`(object_type, object_id, occurred_at desc)`、`(operation_id)` |
| `recovery_case_item` | `(case_id, item_no)`唯一、`(original_transaction_id)`、`(user_id, asset_id, status)` |

### 16.4 分区与保留

| 数据 | V1物理结构 | 未来分区前置条件 | V1统一保留基线 |
| --- | --- | --- | --- |
| `hand_event`、`hand_action_request`、`hand_action`、`player_hand_stat` | 普通表+时间索引 | 表规模或维护窗口达到已记录阈值；建立全局 ID 注册表并完成复合外键迁移 | 牌谱及动作请求结果 180 天 |
| `ledger_entry` | 普通表+时间索引 | 不以删除权威账本换取分区便利；先完成可验证冷归档和期初余额方案 | 在线查询 365 天，权威分录按归档策略可恢复 |
| `audit_log`、玩家/后台认证事件 | 普通表+时间索引 | 建立全局审计事件注册表并处理工单/安全引用 | 365 天 |
| `chat_message` | 普通表+时间索引 | 建立非分区消息 ID/客户端幂等注册表 | 30 天；工单证据单独保全 |
| `report_*`、`ticket_*` | 普通表 | 若未来按年分区，先迁移证据和私牌访问外键 | 365 天，证据至少至结案 |
| `analytics_event` | 普通表+时间索引 | 建立非分区事件 ID 注册表后可按月 RANGE | 由指标策略确认 |
| `test_deal_run` | 普通表 | 若清理主体记录，须另存永久 `run_id` 墓碑以禁止复用 | 365 天 |
| `asr_job` 临时音频对象 | 不以主表分区代替对象生命周期 | 不适用 | 成功即删；失败最长 24 小时 |

以上是产品与技术共同采用的V1基线，不宣称满足任何特定法域的法律要求。到期清理不能删除仍被工单、纠错、审计或法定保全引用的记录；工单证据至少保留至结案。“账本365天”表示在线查询基线，不得直接销毁无法恢复的权威分录。未来启用分区必须先通过真实 PostgreSQL 16 DDL、外键、全局幂等和分区删除测试，不得为删除分区而取消核心引用完整性。

## 17. 关键枚举字典

| 枚举 | 值 |
| --- | --- |
| 玩家状态 | `ACTIVE, DISABLED` |
| 俱乐部状态 | `ACTIVE, FROZEN, ARCHIVED` |
| 房间状态 | `SCHEDULED, WAITING, RUNNING, DRAINING, PAUSED_RECOVERY, CLOSED` |
| 座位会话状态 | `WAIT_NEXT_HAND, PLAYING, AUTO_PLAY, LEAVE_PENDING, ZERO_STACK_HOLD, SETTLING, CLOSED` |
| 手牌状态 | `PREPARING, STARTED, SETTLING, SETTLED, VOID, RECOVERY_REQUIRED` |
| 街道 | `PREFLOP, FLOP, TURN, RIVER, SHOWDOWN, COMPLETE` |
| 操作请求状态 | `SUBMITTING, UNKNOWN, FAILED, SUCCEEDED` |
| 动作请求结果 | `PENDING, ACCEPTED, REJECTED` |
| 账本存储状态 | `PENDING, POSTED, FAILED`；冲正使用新的 POSTED `REVERSAL` 交易 |
| 账本展示状态 | `PENDING, POSTED, REVERSED, FAILED`；`REVERSED` 由有效完整冲正派生，不回写原交易 |
| 消息发送者 | `USER, ADMIN, SYSTEM` |
| 用户屏蔽状态 | `ACTIVE, REVOKED` |
| 邀请目标 | `ROOM, CLUB` |
| 邀请策略 | `EXPIRING_24H, PERMANENT_REVIEW` |
| 邀请申请 | `PENDING, APPROVED, REJECTED, WITHDRAWN, EXPIRED, FROZEN, CANCELLED` |
| 规则版本 | `DRAFT, PUBLISHED, RETIRED` |
| 后台账号 | `INVITED, ACTIVE, DISABLED, RESET_PENDING` |
| 工单 | `OPEN, IN_REVIEW, RESOLVED, REJECTED` |
| 预设发牌来源 | `RANDOM, SCRIPTED_TEST` |
| 前端错误分类 | `AUTH_REQUIRED, FORBIDDEN, INVALID_CODE, INVITE_EXPIRED, INVITE_REVOKED, RATE_LIMITED, ROOM_CLOSED, SEAT_TAKEN, RESERVATION_EXPIRED, INSUFFICIENT_BALANCE, INELIGIBLE, RESULT_UNKNOWN, SERVICE_UNAVAILABLE` |

精确错误码继续细分，客户端只稳定依赖错误分类。空值表示未知/不适用，零值表示真实的 0，两者不得混用。

## 18. 参考项目迁移映射

| 参考对象 | 新模型 | 处理 |
| --- | --- | --- |
| `th_accounts` | `app_user` + `player_identity` + `local_credential` + `ledger_account` + `wallet_balance_projection` + 后台身份表 | 旧登录名/密码默认不迁；`chips` 不直接迁为可信余额；需逐币种对账。若未来迁移资金，仅允许以平衡的有符号零和分录过账，禁止直接写账户余额。`is_admin` 不迁为授权 |
| `th_invites` | `invite` / `invite_application` | 旧表是注册邀请码，语义不足；只读留存，不能冒充 ROOM/CLUB 邀请 |
| `th_rooms` / `th_room_games` | `room` + `room_rule_snapshot` + `room_state_snapshot` | 将元数据、冻结规则和引擎快照分离 |
| `th_room_seats` | `room_seat_occupancy` + `seat_session` + `hand_player` | 当前座位占用、资金会话与单手状态分离；同座位并发由唯一占用行仲裁，金额转整数最小单位 |
| `th_room_actions` / seat actions | `hand_action_request` + `hand_action` + `hand_event` | 接受和拒绝请求均保存幂等结果；已接受事实统一 state_version、目标额与增量 |
| `th_room_deck_cards` / board/cards | `hand_card` | 补足牌序位置、角色、可见性和加密 |
| `th_room_results` / awards | `hand_pot` + contribution + award + settlement | 明确主边池、资格、尾分、抽水与守恒 |
| `th_room_summaries` | `seat_session` 终态 + `v_player_session_result` | 不覆盖历史快照，可由手牌事实聚合 |
| `th_hands` | `hand` + `player_hand_stat` + 安全回放视图 | 删除 3000 手硬截断；修正 VPIP 历史口径 |
| `th_login_logs` | `player_login_event` | 保留追加审计，统一 LOCAL/TELEGRAM 来源并增强 request_id、方法和脱敏；不导入旧密码、令牌或原始身份载荷 |
| JSON `accounts/rooms/hands` | 只读迁移源 | 新环境默认不导入；未来迁移须映射、对账、幂等和异常清单 |

参考项目没有可安全继承的私牌审批/访问授权模型。`private_card_access_request_player`、`private_card_access_log_player` 及其受限读取函数属于新建安全域，不从旧库迁移授权、会话或历史访问资格。

## 19. 默认方案裁定

以下裁定于2026-10-20形成，并于2026-10-21补充首期 Web 身份入口，是V1建模与实施基线；“已裁定”不表示DDL、代码、部署或验收已经完成。

| # | 主题 | 默认方案 | 状态 |
| --- | --- | --- | --- |
| 1 | 私牌专项 | 仅已结束手、有效工单、限定手牌/玩家/用途；申请人与审批人不同，由具备专项审批权的超管审批；批准后30分钟；每次访问另需120秒参数绑定TOTP；会话、撤权或工单失效立即失效；逐次审计 | 已裁定 |
| 2 | 权限种子 | 最小授权；运营仅俱乐部范围，客服仅分配/授权工单及公开桌面，代理仅本人协议/汇总/佣金只读；IP、私牌、全局审计/导出独立权限且角色默认不继承；资金调整仅超管；导出不超页面查询字段权 | 已裁定 |
| 3 | 七组买入 | V1仅发布TEST资产、`SB/BB=1/2`、买入`100–300`、长牌8席2小时、Ante/抓头关闭；其余六组DRAFT，不推导盲注、资产或授权范围，也不阻塞V1 | 已裁定 |
| 4 | 数据保留 | 牌谱180天；账本、审计、举报/工单365天；聊天30天；工单证据至少至结案；ASR成功即删、失败最长24小时；不作特定法域合规声明 | 已裁定 |
| 5 | 真实充提 | 正式列为P2独立专项；本期仅TEST资产，不创建虚假充值订单、地址或到账状态 | 明确后置 |
| 6 | 人工动作 | 不提供人工佣金补结，继续自动扫描脏日；拒绝后须使用新邀请重新申请，不提供解除拒绝；超管可撤销任意业务邀请，运营仅撤本人签发且仍在范围的邀请 | 已裁定 |
| 7 | 旧数据 | 使用新环境；旧库只读留存；不迁移余额、管理员、密码、令牌、认证身份或权限 | 已裁定 |
| 18 | 玩家认证身份 | 首期 LOCAL 注册登录；`app_user` 与身份/凭据分离；未来 TELEGRAM 只绑定既有玩家且冲突拒绝，不新建第二套钱包、归属或战绩 | 已裁定 |
| 8 | PostgreSQL工程 | PostgreSQL 16、Flyway、HikariCP；生产托管主备或同等高可用；每日全量备份+WAL连续归档；初期不分库分表 | 已裁定 |
| 9 | 动作请求幂等 | 接受与拒绝结果均写 `hand_action_request`；已接受动作另写不可变 `hand_action`，同ID同参返回原结果、异参拒绝 | 已裁定 |
| 10 | 资金与归因防重 | 调款授权和operation复合绑定且单次消费；代理原始归因与冲正采用两组部分唯一索引及受限函数 | 已裁定 |
| 11 | 账本展示状态 | 数据库存储 `PENDING/POSTED/FAILED`；客户端 `REVERSED` 由有效完整冲正派生并返回冲正交易ID/时间 | 已裁定 |
| 12 | 消息与屏蔽 | USER/ADMIN/SYSTEM分别幂等；用户屏蔽关系化且仅过滤普通玩家消息，系统和客服巡检不可屏蔽 | 已裁定 |
| 13 | 房间快照摘要 | 同一模板和参数允许创建多个独立不可变快照；摘要仅作完整性校验和普通索引，不作全局唯一键 | 已裁定 |
| 14 | 邀请与领域幂等 | 提交、审核和状态事件分别绑定业务操作；一对一领域结果数据库防重；同请求号异参数拒绝 | 已裁定 |
| 15 | 权限及代理历史 | 活动授权和当前代理唯一、有效区间排斥；变更通过受限函数与权限版本、会话撤销原子提交 | 已裁定 |
| 16 | 高风险授权边界 | 权限变更和私牌审批/读取均复合绑定敏感授权与业务操作，由受限函数单次消费 | 已裁定 |
| 17 | 恢复资金明细 | 恢复案件按玩家、资产、账户/原交易保存明细，案件总额按资产汇总，不保存无资产权威总额 | 已裁定 |

## 20. DDL 落地顺序

工程基线：使用Flyway管理版本化迁移且禁止修改已发布迁移；Java服务使用HikariCP并按数据库容量设置连接池上限。生产采用托管主备或同等高可用拓扑，每日全量备份并连续归档WAL，恢复演练须验证备份可用性；V1不分库分表、核心事实表暂不分区，优先通过索引、读模型和容量监控演进，达到容量阈值后再按ADR-DB-001的前置条件引入分区。具体RPO/RTO、托管服务、密钥与归档介质仍由部署评审在不降低本基线的前提下确定。

建议按以下依赖顺序生成迁移脚本：

1. 扩展与 Schema：`pgcrypto`、`citext`、`btree_gist`、可选 `pg_trgm`，创建 `poker` Schema。
2. 基础身份、资产与控制面：`app_user`、`asset`、后台身份、角色、权限和 `business_operation`；后续所有敏感写操作均可先引用业务操作记录。
3. 组织与版本：代理、俱乐部、互斥代理历史、归属、邀请申请事件、规则/费用/协议版本。
4. 房间与座位：规则快照、房间、`room_seat_occupancy`、预约、资金会话和补码；先创建可独立成立的列与约束。
5. 账本：账户、事务、有符号分录、余额投影和调款，并创建仅对服务角色开放的 `post_ledger_transaction`、`execute_manual_adjustment` 受限函数及账本展示视图。
6. 手牌：手牌、玩家、牌、动作请求、已接受动作、事件、底池、结算和统计，并创建 `submit_hand_action` 受限函数。
7. 代理日账、关系化代理归因、三类发送者消息、用户屏蔽、工单、恢复资金明细和关系化私牌授权目标/访问目标，以及 `post_commission_attribution`、`change_club_agent`、`apply_admin_grant`、`decide_private_card_access_request`、受限私牌读取/恢复处置函数、审计、导出和分析事件。
8. 跨域与循环依赖收口：追加 `room_seat_occupancy` 与 `seat_reservation`/`seat_session`、`ledger_transaction` 与 `seat_session`/`hand`、权限授予与敏感授权等后置外键，以及其他循环外键、部分唯一索引、`btree_gist` 排斥约束、安全视图和只追加权限；V1不创建核心事实表分区。
9. 种子数据：TEST 资产、GENERAL 0% 协议、默认俱乐部、系统角色/权限、费用与规则测试种子。
10. 使用真实 PostgreSQL 16 执行全量 Flyway 迁移、回滚替代演练、约束与事务集成测试；不得仅用H2或SQL语法静态检查代替。

### 20.1 P0及需求覆盖验收门禁

以下测试是进入联调环境前的最低架构适应度门禁，任何一项失败都不得以应用层补偿或人工操作替代数据库约束。

| 门禁 | 必测场景 | 通过标准 |
| --- | --- | --- |
| 分区与全局唯一 | 在全新 PostgreSQL 16 实例顺序执行全部 Flyway 脚本，并验证外键、全局业务号/幂等键和保留清理脚本 | V1普通表模型可一次建成；核心外键和全局唯一约束真实生效；清理任务不删除仍被引用或保全的数据 |
| 房间快照 | 使用同一模板及完全相同参数并发创建100个不同房间；同request_id重复创建 | 不同请求可各自创建独立快照和房间；同一请求只返回同一房间；摘要相同不触发唯一冲突 |
| 私牌授权 | 自审、审批授权与operation错配、审批授权重复消费、请求非本手玩家、30分钟审批过期、120秒访问授权过期、同一访问授权重复使用、撤权、会话失效、权限版本变化 | 仅合法首次审批/读取成功；其余均拒绝且留下不可回滚的 `DENIED` 审计；成功访问留下唯一 `ALLOWED` 审计并精确记录玩家范围 |
| 权限与代理区间 | 并发授予相同角色/范围、重叠有效区间、自提权、撤权后旧会话继续调用、并发切换同俱乐部代理 | 不存在重叠活动授权或代理历史；自提权拒绝；撤权、版本递增及会话/授权失效原子生效；当前代理与历史一致 |
| 邀请幂等 | 同一提交、审核、撤销和校验请求各100并发，同号异参数，并发审核与撤销竞争 | 每个操作只形成一个领域结果和一条状态事件；申请与审核操作可分别追溯；失败重试不重新解释原结果 |
| 座位并发 | 100个并发事务抢同一房间同一座位，并覆盖预约转买入、预约过期与离座重入 | 同一时点最多一个事务成功占用；`room_seat_occupancy`、预约、会话和账本要么全部提交，要么全部回滚；无超卖、悬空预约或孤立托管资金 |
| 复式账本 | POSTED零和、同键同参重试、同键异参重试、完整冲正、受限账户余额不足，并对并发账户过账做死锁测试 | 每笔POSTED交易至少两条同资产分录且 `sum(delta_amount)=0`；同参返回原结果、异参拒绝；冲正后原交易与冲正交易净额为0；受限账户不为负且锁顺序稳定 |
| 动作幂等 | 已接受和已拒绝 action_id 重试、同ID异参数、旧state_version和100并发同ID | 同参始终返回首次结果；异参拒绝；拒绝结果不随异常回滚；最多生成一条 `hand_action` 和对应事件 |
| 调款授权 | 同一120秒授权100并发执行、授权与operation错配、过期/撤权/会话失效、同操作异参数 | 只有合法首次调用成功；授权、调款、操作和账本一一绑定；其余拒绝且不产生资金分录 |
| 代理归因 | 100并发写同一手/池/玩家归因、并发重复冲正、包含NULL的原始事件唯一性 | 原始归因仅一条；每条原始事件最多一条冲正；不存在因PostgreSQL NULL唯一语义产生的重复计提 |
| 账本展示状态 | 查询未冲正、已完整冲正及冲正失败交易 | 原交易数据库状态始终POSTED；仅存在有效POSTED冲正时API派生REVERSED并返回冲正ID和时间 |
| 聊天与屏蔽 | 玩家/客服/系统消息分别100次重试；玩家屏蔽、解除、屏蔽自己；读取普通、系统和客服消息 | 每类消息仅一条；普通被屏蔽玩家消息过滤；SYSTEM和客服巡检仍可见；原消息及举报证据不删除 |
| 恢复资金明细 | 多玩家、多资产测试数据进入同一恢复流程，分别冲正、释放或保持核查 | 每笔金额均关联资产及账户/原交易/会话之一；不同资产不合并；处置交易与明细、案件和审计一致 |

除上述门禁外，还应覆盖权限越权、结算守恒、恢复演练、保留清理、只追加审计和脱敏导出。未来若引入分区，必须新增跨分区外键、全局幂等、分区裁剪和安全删除的专项验收，不得复用V1普通表测试结论。

本字典刻意不提供可直接执行的 DDL：评审通过后应从本模型生成独立版本化迁移，并用 Testcontainers/PostgreSQL 16 验证约束、事务和查询计划。






---

> 本文为IB-1.1完整摘录/规范化收录。与本包[统一基线](../docs/baseline.html)和[冲突裁定](../docs/decisions.html)配套执行；旧来源状态不代表软件完成。

# PostgreSQL 数据库实施基线

状态：`V1.5-review`，面向 PostgreSQL 16+。本目录把《PostgreSQL数据字典》落成可评审的 Flyway 基线；它不是“软件已完成”或“验收已通过”的证明。

## 当前结论

- 数据字典是表结构的唯一来源：92 张表、1001 个显式业务字段。
- 首期身份基线为普通 Web 注册登录：`app_user` 是稳定玩家，`player_identity` 统一 LOCAL/TELEGRAM 身份，`local_credential` 隔离本地口令；Telegram 接入后置且不得新建第二套钱包、归属或战绩。
- Flyway 迁移为 `V001`～`V015`，版本连续，V015为前向修订；V001～V014保持原校验和。
- `V002`～`V010` 由生成器机械生成；复杂约束、触发器、函数、视图和种子在后续人工迁移中维护。
- 已实现可执行的 `post_ledger_transaction`：同幂等键事务级串行、参数摘要冲突拒绝、账户按 UUID 排序加锁、同资产校验、受限账户不为负、分录合计为零。
- 应用角色默认没有表写权限。尚未完成受限函数的业务域保持 fail-closed，不得为了联调临时开放直接 `INSERT/UPDATE/DELETE`。
- 已有静态检查记录；本包将再次执行静态门禁。迁移和SQL测试尚无真实PostgreSQL 16运行证据。

## 目录

```text
数据库实施/
├─ docs/database-dictionary.html        数据模型唯一来源
├─ flyway/sql/                  V001～V015
├─ tools/generate_flyway.py     数据字典到机械 DDL 的生成器
├─ tests/static_validate.py     无数据库依赖的静态门禁
├─ tests/sql/                   PostgreSQL 16 执行测试
└─ docs/database-trace.html 关键 P0 追踪与缺口
```

## 迁移分层

| 版本 | 内容 |
| --- | --- |
| V001 | 扩展、schema、NOLOGIN 角色和默认权限 |
| V002～V009 | 原90张表，按身份、组织规则、账本、房间、手牌、客服、后台、分析分组 |
| V010 | 数据字典声明的单列外键 |
| V011 | 部分唯一、排斥约束、复合同源外键、跨表强约束和查询索引 |
| V012 | 更新时间、只追加、发布不可变、多态目标、恢复一致性触发器及账本函数 |
| V013 | 7 个安全读视图 |
| V014 | TEST/默认俱乐部/角色权限/费用规则/固定策略种子及对象所有权收口 |
| V015 | Outbox事件/消费者投递、会话代际、TOTP高水位和后台/worker最小角色 |

本包 V001～V014 已冻结；禁止重新生成或回改，只能新增更高版本迁移。

## 生成与静态验证

在发布包根目录执行：

```powershell
python "database/tests/static_validate.py"
```

生成器的解析器会在 `database/dictionary.md` 不是 92 表/1001 显式字段、出现重复表/字段或声明了不存在的外键目标时失败。静态门禁检查迁移连续性、DDL 与字典表名一致、外键列存在、身份/凭据强约束、约束/索引名、括号和美元引用、不可变表形状、钱包生成列、枚举约束、权限种子与关键函数签名。

静态通过不等于 PostgreSQL 语法、事务或并发通过。

## 在 PostgreSQL 16 上验证

迁移账号需要创建四个扩展、创建 NOLOGIN 角色、创建 schema 及转移对象所有权的权限。建议使用一次性部署账号，不使用应用账号迁移。

Flyway 示例：

```powershell
flyway `
  -url="jdbc:postgresql://127.0.0.1:5432/storm_poker" `
  -user="poker_migrator" `
  -schemas="poker" `
  -locations="filesystem:database/flyway/sql" `
  migrate
```

然后用 `psql -v ON_ERROR_STOP=1` 依次执行：

```powershell
psql -d storm_poker -f "database/tests/sql/001_smoke.sql"
psql -d storm_poker -f "database/tests/sql/002_constraints.sql"
psql -d storm_poker -f "database/tests/sql/003_ledger.sql"
psql -d storm_poker -f "database/tests/sql/004_security.sql"
```

这些测试都在事务中并最终 `ROLLBACK`。还必须补 Testcontainers/独立 PG16 环境中的并发测试：相同幂等键、同账户不同业务键、余额 100 并发扣减 80、座位争抢、有效区间重叠及撤权与执行竞态。

## 种子边界

- 仅创建不可兑换的 `TEST` 资产，不创建充值订单、提现地址或真实付款状态。
- 只发布已确认的长牌 8 席、2 小时、SB/BB=1/2、买入 100–300、Ante/抓头关闭模板；金额以两位精度最小单位保存，即 100/200、10000/30000。
- 发布 `CSV_STANDARD_V2` 5% / cap 1.5BB（300 最小单位）及 `EARLY_EXIT_PROFIT_V2` 30% 和四类豁免。
- 创建默认俱乐部，但默认关闭玩家开房；未伪造管理员、玩家、代理、钱包或演示业务记录。
- `GENERAL` 0% 先作为固定策略发布。代理协议表要求真实 `agent_id`，因此创建真实代理时必须物化不可变的 0% `agent_agreement_version`，基线不创建虚假代理。
- 创建四个系统角色和 BP-01～BP-31 权限目录。IP、私牌、全局审计/导出及后台禁止项不由任何系统角色默认继承；非超管只继承最小只读集合，仍必须另有对象范围。

## 已实现与阻断项

已实现：结构、声明外键、LOCAL/TELEGRAM 身份分离、本地凭据及锁定形状约束、身份与会话同源约束、关键复合外键、部分唯一、时间排斥、不可变/发布保护、多态目标校验、恢复资产校验、安全视图、账本函数、最小种子和直接写封锁。

以下函数尚未实现，因此相关写流程仍被数据库权限阻断：

- 本地注册、口令验证、5 次失败锁定、IP 限流及 `create_player_session` 受限入口
- 座位预约、买入、补码、换座和离桌清算
- `submit_hand_action` 及结算提交
- `post_commission_attribution`
- `change_club_agent` 及成员迁移
- `apply_admin_grant` 与敏感授权消费
- `decide_private_card_access_request`、受限私牌读取
- 恢复处置与冲正编排

不能用 ORM 直写、临时授予表写权限或空函数绕过这些缺口。实现每个函数时需同步新增 Flyway 迁移、并发/越权测试和追踪矩阵证据。

## 与 RuoYi / Spring Boot 集成

1. 应用连接使用能 `SET ROLE poker_app` 的独立登录角色，禁止拥有 `poker_owner` 或迁移角色成员资格。
2. Flyway 使用独立迁移数据源，生产启动账号不应具有 `CREATEROLE`、`CREATE EXTENSION` 或对象所有权。
3. Hibernate/MyBatis 只查询表或安全视图；领域写入调用经评审的函数。
4. API 金额使用整数最小单位，幂等键和规范化参数摘要由服务端生成并持久化。
5. 新迁移创建的 `poker` 对象必须在同一迁移内把 owner 转给 `poker_owner`，并重新核对 PUBLIC 与应用权限。

## 验收状态

追踪矩阵覆盖关键 P0 数据边界，但产品 51 项、后台 136 项和设计软件验收仍未执行；数据库也尚未完成真实 PG16、并发、备份恢复、容量与故障注入验证。当前产物可进入数据库评审和测试环境迁移，不可据此宣称项目满足上线条件。


## 本包数据库脚本下载

以下相对路径可直接下载；命令示例从本包站点根目录执行。

- [V001__extensions_schema_and_roles.sql](../database/flyway/sql/V001__extensions_schema_and_roles.sql)
- [V002__identity.sql](../database/flyway/sql/V002__identity.sql)
- [V003__organization_and_rules.sql](../database/flyway/sql/V003__organization_and_rules.sql)
- [V004__ledger.sql](../database/flyway/sql/V004__ledger.sql)
- [V005__room_and_seat.sql](../database/flyway/sql/V005__room_and_seat.sql)
- [V006__hand_and_settlement.sql](../database/flyway/sql/V006__hand_and_settlement.sql)
- [V007__commission_and_support.sql](../database/flyway/sql/V007__commission_and_support.sql)
- [V008__admin_and_operations.sql](../database/flyway/sql/V008__admin_and_operations.sql)
- [V009__test_and_analytics.sql](../database/flyway/sql/V009__test_and_analytics.sql)
- [V010__declared_foreign_keys.sql](../database/flyway/sql/V010__declared_foreign_keys.sql)
- [V011__strong_constraints_and_indexes.sql](../database/flyway/sql/V011__strong_constraints_and_indexes.sql)
- [V012__guards_and_ledger_function.sql](../database/flyway/sql/V012__guards_and_ledger_function.sql)
- [V013__safe_views.sql](../database/flyway/sql/V013__safe_views.sql)
- [V014__review_baseline_seed.sql](../database/flyway/sql/V014__review_baseline_seed.sql)
- [V015__outbox_session_generation_and_totp.sql](../database/flyway/sql/V015__outbox_session_generation_and_totp.sql)
- [001_smoke.sql](../database/tests/sql/001_smoke.sql)
- [002_constraints.sql](../database/tests/sql/002_constraints.sql)
- [003_ledger.sql](../database/tests/sql/003_ledger.sql)
- [004_security.sql](../database/tests/sql/004_security.sql)

- [005_ib11_security_outbox.sql](../database/tests/sql/005_ib11_security_outbox.sql)

- [静态校验工具](../database/tests/static_validate.py)
- [冻结DDL解析工具（禁止回写）](../database/tools/generate_flyway.py)

## IB-1.1 前向修订

当前权威源在本发布包 downloads/source/database-dictionary.md；database/dictionary.md 由重建同步。V015增加 outbox_event/outbox_delivery、玩家与会话代际、TOTP高水位保护及 poker_admin/poker_worker 最小角色，历史14个迁移不回写。V015使旧玩家会话全部撤销，部署前评估重新登录影响。运行005_ib11_security_outbox.sql（与原4组一样在事务内回滚）。生成器保留解析能力，写旧迁移功能已禁用；修改当前字典后只能手写新迁移。

本次落地结构和存储保护；create_player_session、动作鉴权、TOTP认证消费、业务事务写Outbox、租约领取/ACK函数、消费者去重、若依安全适配及手间编排仍需业务实现。禁止把DDL或静态PASS写成这些功能已运行；未实现入口保持拒绝。架构4.2.1/6.6/8.4/9.3.1与字典12.10分别规定唯一规则归属、认证、投递、手间和RBAC。


---

> 本文为IB-1.1完整摘录/规范化收录。与本包[统一基线](../docs/baseline.html)和[冲突裁定](../docs/decisions.html)配套执行；旧来源状态不代表软件完成。

# 数据库测试说明

当前环境只执行了 `DB-S01`。`DB-PG01`～`DB-PG04` 已编写但因本机缺少 PostgreSQL 16 / `psql` / Docker 尚未执行；`DB-C01`～`DB-C17` 是追踪矩阵中的后续领域与并发用例，须随相应受限函数实现。

| 测试ID | 文件或范围 | 状态 |
| --- | --- | --- |
| DB-S01 | `static_validate.py`：迁移、表、字段、外键、约束名、关键签名与种子静态门禁 | 已通过 |
| DB-PG01 | `sql/001_smoke.sql`：对象数量、视图、函数及种子冒烟 | 未执行 |
| DB-PG02 | `sql/002_constraints.sql`：身份规范化唯一、空哈希拒绝、失败锁定、TG绑定冲突、会话同源、枚举、默认俱乐部、发布不可变、策略区间排斥 | 未执行 |
| DB-PG03 / DB-L01 | `sql/003_ledger.sql`：零和、余额、幂等重试和摘要冲突 | 未执行 |
| DB-PG04 / DB-A01 | `sql/004_security.sql`：直接写拒绝、函数授权、owner、独立权限不继承 | 未执行 |
| DB-C01～DB-C17 | 会话、组织、邀请、房间、座位、动作、结算、费用、代理、权限、私牌、恢复的领域/并发用例 | 待函数实现 |

真实数据库测试必须使用 PostgreSQL 16，不能用 H2/SQLite 代替排斥约束、延迟约束触发器、`jsonb`、`SECURITY DEFINER` 和并发锁行为。

## IB-1.1追加验收

执行 V015 后运行第五组 SQL `005_ib11_security_outbox.sql`，覆盖代际回退、N+1后N/同一步TOTP重放、Outbox不可变、消费者防重、无令牌租约/无ACK时间拒绝与新增角色隔离。另须在真实PG16执行并发同一步消费/接管与动作竞态、租约过期旧ACK、T1/T2崩溃、预约锁等待过期及RBAC组合矩阵；当前未执行，不以静态门禁替代。


---

> 本文为IB-1.1完整摘录/规范化收录。与本包[统一基线](../docs/baseline.html)和[冲突裁定](../docs/decisions.html)配套执行；旧来源状态不代表软件完成。

# 组件与 Design Token 规范

版本：D2.0  
适用范围：风暴扑克 Web 客户端（Telegram适配后置）设计稿。  
实现基准：[styles.css](../ui/player/styles.css)。本文记录语义和验收要求，CSS 是当前原型实现，不替代正式前端组件库。

## 1. 视觉原则

- 暗色、克制、单一荧光绿强调色；不使用纯黑作为主背景。
- 合法主操作、本人手牌、当前行动和资金结果保持第一视觉层级。
- 错误、禁用、成功、等待和座位状态同时使用文字、形状或边框，不只依赖颜色。
- 玩家产品界面使用实用文案，不显示设计评论、技术实现或运营后台说明。

## 2. 核心 Token

| Token | 当前值 | 用途 |
| --- | --- | --- |
| `--bg` | `#06150f` | 工作台深色背景 |
| `--bg-deep` | `#03100b` | 最深层背景 |
| `--surface` | `#0b241a` | 内容表面 |
| `--surface-2` | `#102e22` | 次级表面 |
| `--text` | `#effff5` | 主要文字 |
| `--muted` | `#a9beb3` | 辅助文字 |
| `--subtle` | `#839f91` | 低优先级元数据 |
| `--lime` | `#9cf51c` | 主操作、焦点、当前状态 |
| `--lime-soft` | `#c9ff72` | 强调文字 |
| `--gold` | `#f2cf6b` | 金额提示、警告、牌局投入 |
| `--red` | `#ff745f` | 错误与危险动作 |
| `--blue` | `#71b7ff` | 技术验证标签 |
| `--line` | `rgba(201,255,226,.13)` | 默认分隔线 |
| `--line-strong` | `rgba(201,255,226,.24)` | 强分隔线与控件边界 |
| `--radius` | `18px` | 默认圆角 |
| `--safe-top` | `18px` | 原型安全区占位；生产使用 浏览器/系统实际值，后续适配TG |
| `--safe-bottom` | `18px` | 原型安全区占位；生产使用 浏览器/系统实际值，后续适配TG |

正式实现应将语义 Token 与具体色值分离。业务组件只引用 `text-primary`、`action-primary`、`state-danger` 等语义变量，不能散落硬编码颜色。

## 3. 排版与间距

- 字体：系统字体栈；不依赖在线字体。
- 正文最小 12px；关键正文建议 13px；低频元数据不得低于 10px。
- 页面标题 18–34px，按层级使用，不以字重和字号同时制造多套竞争层级。
- 常用间距采用 4 / 6 / 8 / 10 / 12 / 14 / 16 / 18 / 22 / 24px 序列。
- 内容左右安全边距默认 22px；360px 以下可降至 16px。
- 正文行高不低于 1.5；说明与规则正文建议 1.6–1.75。

## 4. 组件状态

| 组件 | 必须状态 | 核心要求 |
| --- | --- | --- |
| 主按钮 | 默认、按压、焦点、禁用、提交中 | 高度≥52px；提交中防重复；禁用仍可辨认文案 |
| 次按钮 | 默认、按压、焦点、禁用 | 不得与主按钮争夺视觉层级 |
| 图标按钮 | 默认、焦点、禁用 | 点击区≥44×44px；必须有可访问名称 |
| 输入框 | 空、已输入、焦点、错误、禁用 | 错误文字靠近字段；不只红边；保留用户合法输入 |
| 滑杆 | 默认、焦点、拖动、禁用 | 有名称、当前值、最小值、最大值；键盘方向键可操作 |
| 座位 | 可选、已选、已占、业务锁定 | 文字+边框+底纹；`aria-pressed`；不可用座位禁用 |
| 房间列表项 | 可进入、满桌、关闭、受限 | 状态与人数可扫读；整行点击区≥44px |
| Bottom Nav | 默认、当前、焦点 | 三栏固定；当前项具文字和底纹反馈；内容预留底部空间 |
| Toast | 成功、失败、提示 | 单次短消息使用 `role=status`；不播报整页 |
| 状态通知 | 警告、错误、成功、等待 | 标题说明发生了什么，正文说明影响和下一步 |
| 抽屉/Dialog | 打开、滚动、关闭 | 底层 `inert`；焦点循环；Esc/遮罩关闭；焦点返回入口 |
| 牌桌动作 | 弃牌、跟注/过牌、加注/下注、禁用 | 跟注/过牌为主操作；目标额与本次投入不得混淆 |

## 5. 页面布局

- 产品画布在 320 / 360 / 390 / 430px 下不得横向滚动。
- 独立预览在宽屏最大 430px 并居中；这只是验收容器，不是生产桌面布局承诺。
- 可滚动页面使用内容区滚动；Bottom Nav 和粘性 CTA 不遮挡末尾内容与焦点。
- 牌桌为固定画布：行动 Dock、本人手牌和牌桌区域不得重叠；公共牌、底池和当前行动者优先。
- TG 顶部栏、系统安全区和软键盘必须以运行时数据处理，不能只使用原型固定值。

## 6. 动效

- 页面和抽屉过渡控制在 120–250ms；动效只用于层级、进入和反馈。
- 业务结果必须由服务端状态驱动，动效不得先行制造成功。
- 动作气泡不得遮挡手牌、公共牌或合法动作。
- `prefers-reduced-motion: reduce` 时关闭非必要动画，保留状态变化本身。

## 7. 无障碍验收

- 正文对比度≥4.5:1，重要标题和关键状态目标≥7:1。
- 主要触控目标≥44×44px；焦点环至少 2px，当前原型为 3px。
- 所有操作使用原生按钮/输入控件或提供等价语义。
- 页面标题在路由变化后获得程序焦点；路由变化通过单次礼貌播报通知。
- Dialog 提供名称、`aria-modal`、焦点陷阱和关闭后焦点恢复。
- 金额、倒计时和牌局状态不能依靠颜色区分；读屏文本必须包含单位和状态。

## 8. 资源交付

- Logo、图标、四种牌面和品牌素材必须记录来源、授权、格式、尺寸和版本。
- 演示文本、人员、房间号、邀请码和 TEST 金额不得进入生产种子数据。
- SVG 优先用于图标；信息图像必须有替代文本，装饰图像使用空替代文本。
- 资源变更与页面版本一起发布，不能由开发自行替换近似素材。


---

> 本文为IB-1.1完整摘录/规范化收录。与本包[统一基线](../docs/baseline.html)和[冲突裁定](../docs/decisions.html)配套执行；旧来源状态不代表软件完成。

# 字段与事件契约

版本：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完整摘录/规范化收录。与本包[统一基线](../docs/baseline.html)和[冲突裁定](../docs/decisions.html)配套执行；旧来源状态不代表软件完成。

# D2 正式交付规范

版本：D2.0  
日期：2026-10-19  
状态：设计交付基线已形成；软件开发与产品验收尚未执行。

## 1. 名称与边界

本文使用 **D2（Design Delivery 2）** 表示设计交付阶段，避免与综合 PRD 中“需求优先级 P2＝后置功能”混淆。

D2 的目标是让产品、设计、前端、后端和测试对以下内容使用同一套定义：

- 本期开发哪些页面，不开发哪些页面；
- 每个页面从哪里进入、完成后去哪里；
- 页面依赖哪些服务端字段、权限和状态；
- 异步、失败、结果未知和恢复如何表现；
- 研发完成后用什么证据判定通过。

D2 不新增玩家功能，不把保险、真实充提、公平性专项重新纳入本期，也不替工程团队确定接口 URL、框架、数据库或排期。

## 2. 权威来源顺序

发生冲突时按以下顺序处理：

1. 用户明确确认和综合 PRD 已冻结裁定；
2. 综合 PRD 的需求总表、配置字典和验收场景；
3. 本交付包的页面、状态、字段和权限映射；
4. 原产品视频与截图，仅用于上游规则和行为证据；
5. `texas-holdem`，仅用于验证已有可运行能力；
6. 原型演示数据，不得作为生产默认值、种子数据或业务结果。

规则发生变化时，不能只修改画面。必须同步更新需求、配置、字段契约、状态矩阵、验收用例和版本记录。

## 3. 交付包索引

| 文件 | 用途 | 主要读者 |
| --- | --- | --- |
| [README](../docs/baseline.html) | 设计稿入口、来源边界和整体说明 | 全角色 |
| [交付页面清单](../docs/ui-pages.html) | 本期页面与连续牌局验收时间轴 | 产品、前端、测试 |
| [页面状态矩阵](../docs/ui-states.html) | 页面范围、逻辑路由、入口、退出和状态 | 前端、后端、测试 |
| [组件与 Design Token 规范](../docs/ui-tokens.html) | 视觉变量、组件状态、响应式和无障碍 | 设计、前端、测试 |
| [字段与事件契约](../docs/ui-contract.html) | UI 字段、异步语义、错误分类和分析事件 | 前端、后端、数据、测试 |
| [角色权限矩阵](../docs/ui-permissions.html) | 玩家端显示规则与后台执行边界 | 产品、前后端、测试 |
| [埋点与失败原因字典](../docs/ui-events.html) | 关键旅程事件及失败原因口径 | 产品、数据、前后端 |
| [验收追踪矩阵](../docs/ui-acceptance.html) | 页面、场景、责任和证据要求 | 产品、测试、交付 |
| [P1 验收报告](../docs/sources.html) | 视觉与交互基线证据 | 设计、前端、测试 |
| [版本变更记录](../docs/decisions.html) | 基线、变更影响和审批轨迹 | 全角色 |

## 4. 本期范围

### 4.1 进入研发页面清单

P01～P18 为本期客户端设计范围。逻辑页面标识以[页面状态矩阵](../docs/ui-states.html)为准，最终技术路由由前端在工程实施时固化。

### 4.2 不属于客户端路由

- S01“正式交付规范”只存在于设计工作台；
- L01 保险、L02 公平性、L03 真实充提是后续规则档案；
- 邀请签发、申请审核、规则模板发布和俱乐部创建属于运营后台；
- 设计工作台中的状态切换器、规格网格和自动播放控件不进入客户端。

## 5. 全局状态契约

所有读取型页面必须覆盖：加载中、真实空态、权限不足、服务不可用和恢复重试。所有产生业务结果的提交统一遵循：

| 状态 | UI 含义 | 允许操作 | 禁止行为 |
| --- | --- | --- | --- |
| `IDLE` | 尚未提交 | 编辑并提交 | 展示业务已完成 |
| `SUBMITTING` | 原请求处理中 | 等待或取消仅客户端输入 | 重复提交、新建请求号 |
| `UNKNOWN` | 原请求结果未知 | 按原 `request_id` 查询 | 自动退款、显示明确失败、创建新请求 |
| `FAILED` | 服务端明确失败 | 修正后使用新请求 | 沿用失败请求再次执行业务 |
| `SUCCEEDED` | 服务端明确成功 | 进入下一状态 | 由客户端自行生成业务结果 |

客户端只呈现服务端确认结果。动效、Toast、页面跳转和本地缓存都不能先于业务确认改变资金、归属、房间或牌局事实。

## 6. 开发准备门槛（Definition of Ready）

页面进入开发前必须同时满足：

- 页面在范围矩阵中标记为“本期”；
- 正常、加载、空态、权限、失败和恢复状态已定义；
- 所需字段、可空规则、金额单位、服务端时间和隐私级别已定义；
- 入口角色与服务端权限校验已定义；
- 主流程和返回路径无断点；
- 对应验收 ID、责任角色和证据类型已经登记；
- 未决外部资源不会被假数据伪装成正式接入。

缺少任一项时，页面保持“待细化”，不能仅凭原型存在进入完成统计。

## 7. 开发完成定义（Definition of Done）

功能只有在以下条件全部满足时才能标记完成：

1. 正常、边界、失败、权限和恢复用例均通过；
2. 设计状态与真实 API 返回一致，演示数据不进入生产；
3. P0 资金、权限、私牌和幂等问题为零；
4. 320 / 360 / 390 / 430px 及 TG iOS/Android 真机通过；
5. 键盘、焦点、对比度、44px 触控和减少动画模式通过；
6. 证据记录包含版本、环境、输入、预期、实际结果和附件；
7. 文档、字段、错误分类、埋点和版本记录与实现同步；
8. 后置入口保持关闭，运营能力不混入玩家客户端。

“页面已开发”“接口返回 200”“演示点击成功”均不能单独视为完成。

## 8. 责任边界

| 角色 | 交付责任 |
| --- | --- |
| 产品 | 规则裁定、范围、Non-Goals、状态语义和验收结论 |
| 设计 | 页面流、组件状态、视觉 Token、文案、无障碍和原型版本 |
| 前端 | 页面实现、客户端状态管理、焦点、安全区、埋点和错误映射 |
| 后端 | 身份、权限、幂等、账本、业务终态、服务端时间和审计字段 |
| 游戏服务 | 合法动作、计时、牌局事件、主边池、摊牌和恢复快照 |
| 测试 | 场景执行、真机/弱网/并发测试、证据归档和回归结论 |
| 数据 | 事件口径、去重、旅程归因、指标校验和隐私审查 |
| 交付负责人 | 版本冻结、实名责任人、发布门槛、值守与回滚证据 |

## 9. 变更控制

冻结后变更必须记录：变更编号、提出人、原因、受影响需求、页面、字段、配置、接口、验收和生效版本。涉及资金、权限、私牌、牌局规则或归属的变更必须由产品、技术和测试共同评审。

旧版本保留用于追溯，不覆盖或删除。未经确认的建议标记为“提案”，不得悄然并入本期范围。

## 10. 当前外部条件

以下内容尚未由本设计包完成，不能写成已接入或已有人负责：

- 七组候选模板的最终盲注与发布版本；
- 代理字段与后台角色的最终授权种子；
- 正式数据保留策略、归档介质和容量方案；
- Bot、HTTPS 域名、服务器、存储、ASR 与正式协议；
- 实名负责人、排期、值班与故障升级渠道；
- 最终工程边界、依赖版本及部署方式。

这些条件按综合 PRD 的 D07、D10、D16～D19 跟踪，不阻止设计交付，但会阻止对应工程阶段或正式发布。


---

# 实施顺序与交付门禁

版本：IB-1.1。文档发布不改变未执行的软件验收状态。

## 阶段和退出证据

| 阶段 | 主要内容 | 退出证据 |
| --- | --- | --- |
| M0 | 本包统一基线、工程版本、ADR、接口与状态机、规则测试向量 | 同一来源、同一写权限和业务契约；接口规范及规则用例可校验 |
| M1 | Web身份、会话、账本、Outbox、若依认证、环境与CI | LOCAL认证/锁定/接管、账本并发/幂等/平衡、权限测试通过 |
| M2 | 长牌完整对局、房间单写、买入补码、结算离桌、恢复 | 两真人Web完整闭环及进程重启恢复，通过且有日志 |
| M3 | 俱乐部、邀请、运营管理API、核心后台及受控密码重置 | 跨俱乐部拒绝、管理操作与实际结果可关联；重置渠道获确认 |
| M4 | 全部本期范围、短牌、代理、统计、牌谱、聊天、举报、导出 | 产品与59项后台需求逐项有实现和验收证据 |
| M5 | 容量、安全、弱网、备份恢复、发布与回滚 | 阻断性验收通过，真实环境资源和发布决定明确 |
| M6 | Telegram绑定与宿主适配 | 绑定不复制业务账号；目标Telegram客户端真机测试通过 |

## 完成定义

每项任务记录需求ID、代码/迁移版本、接口/字段/状态、权限与范围、自动校验、真实测试环境及证据。仅文档已写、页面已做或Mock可点，不满足业务软件完成定义。

本包形成统一基线和追踪，但M0接口契约、规则向量、工程安全兼容及后续实现仍按[任务台账](../docs/tasks.html)推进。所有本期P0/P1最终都必须验收，不用第一条闭环替代全量交付。

## 发布阻断项

- 重复扣款/派奖/离座费、账本不平、并发负余额。
- 同一玩家同时控制两个活动真人座位，或旧会话仍能下注。
- 玩家/旁观者得到他人未公开底牌或牌序；后台跨范围或越权读取。
- 若依直接写核心表、客户端覆盖余额或以旧昵称登录绕过正式认证。
- 结算已提交后再次结算，或重启无法区分已结算、未结算、未知。
- 无BP-32、交付渠道未确认或重放凭据时仍能重置玩家密码。
- 无可信备份恢复及回滚证据，或正式环境启用测试牌序/机器人调试入口。

## 本次文档验证

[验证报告](../validation-report.json)记录文件名/引用ASCII、本地断链、锚点、旧域名依赖、需求追踪、数据库静态检查、根目录/子目录HTTP、浏览器交互及解压内容一致性。此报告只验证文档交付，不代表PostgreSQL运行、业务功能、安全或容量验收通过。


---

# ZIP部署与维护

版本：IB-1.1。部署包为已构建的纯静态站，不需要Node、Java、Python、数据库或在线CDN。正文使用UTF-8中文，所有服务器目录、文件名和引用路径只含ASCII。

## 宝塔或Nginx部署

1. 新建站点目录，绑定你选择的新域名。旧域名不作为本包依赖。
2. 上传ZIP，将包内全部内容解压到站点目录。站点根应直接出现index.html，不要遗漏assets、docs、ui、downloads、database等目录。
3. 默认首页设为index.html，以静态文件方式提供；不需要SPA history重写。
4. 域名根目录部署时访问域名首页；子目录部署时访问该子目录的index.html。链接均为相对路径，同一包兼容两种方式。
5. 检查首页、全文、数据字典、玩家登录画板、长牌画板、后台样稿、流程图和CSV下载；对照release.json确认版本IB-1.1。

## Nginx位置配置示例

以下为站点server块中的配置片段，需要把root替换为实际解压目录。域名、证书由服务器现有站点配置负责；示例尚未在你的服务器执行。

```nginx
root /var/www/storm-baseline;
index index.html;
charset utf-8;
location / {
    try_files $uri $uri/ =404;
}
location = /index.html {
    add_header Cache-Control "no-cache";
}
location = /release.json {
    add_header Cache-Control "no-cache";
}
```

子目录部署直接保留目录结构并由父站点静态服务提供，不将所有请求改写到首页。更新时建议新目录完整解压后切换站点根，避免混用旧资源。

## 完整性和内容

外部SHA256文件校验ZIP；manifest.json记录每个站点文件的大小和SHA256（清单自身除外）。readme.txt提供简要说明，llms.txt和llms-full.txt供AI读取。downloads/master-baseline.md是合并阅读稿，downloads/source/保存可编辑的分篇源稿和表格，build脚本可在维护目录重建。

## 访问地址

本次只交付ZIP，由你自行绑定新域名和部署，因此不提供虚构的在线地址。部署后使用你的域名首页或子目录index.html；站点不写死任何业务域名。

## 更新和权限

修改对应源稿并记录变更影响，重新构建、验证、打包，再发布整个新版本。本包无业务凭据、玩家数据、数据库转储或真实日志。静态站不自带登录，若需要限制查阅，应在服务器或网关保护整个目录及下载资源。


## 2026-10-27 设计评审更新包

本次文件名为 `storm-poker-implementation-baseline-ib-1.1-review-20261027.zip`。解压后 `index.html` 直接位于站点根目录，无额外外层文件夹。首页主按钮进入本轮设计评审 `ui/review/index.html?screen=redo-review`，原实施基线文档、数据库和玩家／后台原型完整保留。支持站点根目录与任意子目录部署。

静态托管即可，无需安装 Node、Python 或数据库。Nginx 使用包内 `nginx.conf.example` 并按实际目录调整 root。配置 UTF-8，尤其为 Markdown 返回 `text/plain; charset=utf-8`；修改记录同时提供带 UTF-8 声明的 HTML 阅读页。上传全部文件后刷新浏览器缓存，切勿只覆盖 index.html。已有站点请先备份，再将新包完整解压到新目录并切换站点目录。

包内 maintenance 为本地维护与校验脚本，公开评审站可按包内 Nginx 示例限制访问；业务验收及 PostgreSQL 运行验收不包含在此静态部署检查中。
