> 本文为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。
- 安全章节至少每季度复核一次。
- 每次正式发布记录应用版本、数据库迁移版本和报告版本。
- 本报告描述目标架构和实施门槛，不应用于证明功能已经开发或验收通过。
