风暴扑克技术架构与实施方案
版本:V1.1 评审稿
日期:2026-10-21
适用范围:首期 Web 玩家端、Node.js 游戏业务服务、PostgreSQL、RuoYi-Vue-Plus 运营后台,以及后续 Telegram Mini App 适配
文档状态:供架构、研发、测试、运维和安全人员共同评审;不表示功能已经实现或通过验收。
0. 阅读指南
本报告回答五个问题:
- 风暴扑克为什么采用 Node.js 模块化单体,而不是首期微服务。
- 首期 Web 玩家端、后续 Telegram 适配、游戏业务服务、PostgreSQL 和若依运营后台如何分工。
- 资金流水、牌局状态、运营操作分别由谁写入和负责。
- 系统如何处理实时通信、并发操作、幂等、断线恢复和发布回滚。
- 团队按照什么顺序实施,并以什么标准判定可以进入下一阶段。
评审人员应优先阅读“决策摘要”“数据所有权”“关键业务链路”“部署方案”“实施路线”和“评审清单”。
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_INVALIDAUTH_LOCKEDAUTH_EXPIREDIDENTITY_CONFLICTPASSWORD_RESET_NOT_AVAILABLESESSION_REPLACEDFORBIDDEN_RESOURCE_SCOPEROOM_NOT_JOINABLESEAT_ALREADY_TAKENINSUFFICIENT_AVAILABLE_BALANCESTALE_RESOURCE_VERSIONACTION_NOT_ALLOWEDIDEMPOTENCY_CONFLICTRESULT_UNKNOWNSERVICE_DRAINING
错误码由服务端定义并版本化,客户端不能依赖错误文案判断业务分支。
8.4 Outbox 事件
与核心业务事实同事务写入 outbox_event,后台 worker 提交后投递。典型事件:
player.createdclub.membership.changedroom.status.changedhand.settledledger.transaction.postedagent.accrual.createdadmin.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 入座与买入
- 客户端生成
request_id并预约座位。 - Node 在事务内复查玩家状态、俱乐部资格、房间状态、座位、币种、规则版本和余额。
- Node 创建唯一
seat_session,将可用余额转入桌内托管。 - Node 写业务操作结果和 Outbox。
- 事务提交后,客户端才进入牌桌;响应丢失时查询原请求。
事务失败不得残留座位占用、冻结或半笔账。
9.2 玩家动作
- WSS 接收动作并验证应用会话和设备代际。
- 校验房间、手牌、轮次、动作序号和期望版本。
- 动作进入该房间串行队列。
- 规则引擎判断合法动作并生成新状态。
- 持久化动作、状态版本和必要快照。
- 提交后向不同身份推送各自裁剪视图。
9.3 手牌结算
- 状态由
STARTED进入SETTLING。 - 引擎输出边池、赢家和筹码变化。
- 同一事务写入手牌终态、桌内托管变更、抽水、代理归因依据和 Outbox。
- 事务提交后状态进入
SETTLED。 - 广播失败只重试通知,不能重新计算或重复记账。
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 运营冻结俱乐部
- 若依校验后台权限并取得敏感操作授权。
- Node 复核
operation_id、资源范围和俱乐部当前状态。 - 禁止新加入、买入、补码和开房。
- 正在进行的手牌完成后关桌和返还。
- 邀请撤销、待审核申请和房间处置均产生业务审计。
- 解冻不会自动恢复旧邀请或已关闭房间。
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 流水线门槛
每次合并至少执行:
- TypeScript/Java 编译、格式和静态检查。
- 规则引擎单元测试与筹码守恒性质测试。
- PostgreSQL 事务、幂等、并发和迁移测试。
- WebSocket 双真人完整牌局测试。
- 权限矩阵和越权测试。
- Web注册登录、响应式浏览器与关键业务路径测试;后续TG接入单独增加宿主契约测试。
- 依赖、镜像和密钥扫描。
- 文档断链和版本检查。
13.2 数据库迁移
- 使用 Flyway、Liquibase 或 Node 侧迁移工具中的一种,M0 阶段锁定。
- 采用 expand/contract:先增加兼容结构,再切换应用,最后移除旧结构。
- 迁移脚本只向前执行;资金数据纠正使用业务冲正,不使用回滚脚本覆盖历史。
- 大表索引和回填必须在 staging 验证锁时间和磁盘空间。
13.3 发布流程
- 发布前停止创建新房间和新买入,服务进入
DRAINING。 - 完成当前手或持久暂停到可恢复边界。
- 确认 Outbox、结算和数据库迁移状态。
- 切换应用版本并完成就绪检查。
- 恢复牌桌所有权,再开放玩家动作和新业务。
- 观察核心指标后解除排空状态。
应用回滚不能回滚已经提交的资金事实。数据纠错使用向前修复或冲正分录。
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 或数据库延迟持续超过目标。
- 热点房间影响其他房间,需要故障域隔离。
- 多团队必须独立发布不同业务边界。
- 单库报表和在线事务无法通过投影、索引或只读副本解决。
扩容顺序:
- 静态资源 CDN、查询缓存、数据库索引和报表投影。
- 将 worker 与 game-api 分进程部署。
- 按
room_id分配牌桌 owner,持久化owner_id + epoch。 - 数据库在写入时校验 epoch,失效实例不能提交。
- 网关根据房间路由 WSS;重连可以重新发现 owner。
- 最后才评估将稳定边界拆为独立服务。
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. 待项目组确认
以下信息会影响最终资源、周期和上线门槛,但不改变核心架构方向:
- 生产部署地区、云厂商、预算和是否允许托管 PostgreSQL。
- 可用性、RPO、RTO 和计划维护窗口。
- 峰值在线人数、峰值活跃桌数、平均每分钟动作数和增长预期。
- 正式资产币种、是否存在可兑换价值以及对应合规要求。
- 已确定保留策略的存储容量、归档与清理资源。
- 按 ADR-010 锁定 Java21/受维护Boot补丁、支持证据和兼容回归,不再保留旧栈生产分支。
- 玩家密码重置的身份核实材料、批准交付渠道和默认30分钟有效期。
- 后续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。
- 安全章节至少每季度复核一次。
- 每次正式发布记录应用版本、数据库迁移版本和报告版本。
- 本报告描述目标架构和实施门槛,不应用于证明功能已经开发或验收通过。