实施基线 / 技术架构
STORM POKER / IB-1.1

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

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

版本: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 系统上下文

玩家 ──浏览器──> 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 推荐代码结构

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/串行命令队列:

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 注册与登录

浏览器打开注册 / 登录页
  → 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 只是新的认证提供者和宿主适配器。

已登录玩家在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 时携带:

{
  "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 资金调整流程

运营输入玩家、币种、金额和原因
  → 若依校验菜单/资源权限
  → 资金敏感操作二次验证
  → 若依生成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玩家密码重置命令

所有写接口返回:

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

8.2 WebSocket 信封

{
  "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 首期推荐拓扑

                         ┌─ 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 提供静态访问即可。示例:

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文档已发布 · 软件开发与验收按门禁推进

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