实施基线 / 数据库实施说明
STORM POKER / IB-1.1

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

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运行证据。

目录

数据库实施/
├─ 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 已冻结;禁止重新生成或回改,只能新增更高版本迁移。

生成与静态验证

在发布包根目录执行:

python "database/tests/static_validate.py"

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

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

在 PostgreSQL 16 上验证

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

Flyway 示例:

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 依次执行:

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、并发、备份恢复、容量与故障注入验证。当前产物可进入数据库评审和测试环境迁移,不可据此宣称项目满足上线条件。

本包数据库脚本下载

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

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

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