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_V25% / cap 1.5BB(300 最小单位)及EARLY_EXIT_PROFIT_V230% 和四类豁免。 - 创建默认俱乐部,但默认关闭玩家开房;未伪造管理员、玩家、代理、钱包或演示业务记录。
GENERAL0% 先作为固定策略发布。代理协议表要求真实agent_id,因此创建真实代理时必须物化不可变的 0%agent_agreement_version,基线不创建虚假代理。- 创建四个系统角色和 BP-01~BP-31 权限目录。IP、私牌、全局审计/导出及后台禁止项不由任何系统角色默认继承;非超管只继承最小只读集合,仍必须另有对象范围。
已实现与阻断项
已实现:结构、声明外键、LOCAL/TELEGRAM 身份分离、本地凭据及锁定形状约束、身份与会话同源约束、关键复合外键、部分唯一、时间排斥、不可变/发布保护、多态目标校验、恢复资产校验、安全视图、账本函数、最小种子和直接写封锁。
以下函数尚未实现,因此相关写流程仍被数据库权限阻断:
- 本地注册、口令验证、5 次失败锁定、IP 限流及
create_player_session受限入口 - 座位预约、买入、补码、换座和离桌清算
submit_hand_action及结算提交post_commission_attributionchange_club_agent及成员迁移apply_admin_grant与敏感授权消费decide_private_card_access_request、受限私牌读取- 恢复处置与冲正编排
不能用 ORM 直写、临时授予表写权限或空函数绕过这些缺口。实现每个函数时需同步新增 Flyway 迁移、并发/越权测试和追踪矩阵证据。
与 RuoYi / Spring Boot 集成
- 应用连接使用能
SET ROLE poker_app的独立登录角色,禁止拥有poker_owner或迁移角色成员资格。 - Flyway 使用独立迁移数据源,生产启动账号不应具有
CREATEROLE、CREATE EXTENSION或对象所有权。 - Hibernate/MyBatis 只查询表或安全视图;领域写入调用经评审的函数。
- API 金额使用整数最小单位,幂等键和规范化参数摘要由服务端生成并持久化。
- 新迁移创建的
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。