> 本文为IB-1.1完整摘录/规范化收录。与本包[统一基线](../../docs/baseline.html)和[冲突裁定](../../docs/decisions.html)配套执行；旧来源状态不代表软件完成。

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

## 目录

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

## 生成与静态验证

在发布包根目录执行：

```powershell
python "database/tests/static_validate.py"
```

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

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

## 在 PostgreSQL 16 上验证

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

Flyway 示例：

```powershell
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` 依次执行：

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


## 本包数据库脚本下载

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

- [V001__extensions_schema_and_roles.sql](../../database/flyway/sql/V001__extensions_schema_and_roles.sql)
- [V002__identity.sql](../../database/flyway/sql/V002__identity.sql)
- [V003__organization_and_rules.sql](../../database/flyway/sql/V003__organization_and_rules.sql)
- [V004__ledger.sql](../../database/flyway/sql/V004__ledger.sql)
- [V005__room_and_seat.sql](../../database/flyway/sql/V005__room_and_seat.sql)
- [V006__hand_and_settlement.sql](../../database/flyway/sql/V006__hand_and_settlement.sql)
- [V007__commission_and_support.sql](../../database/flyway/sql/V007__commission_and_support.sql)
- [V008__admin_and_operations.sql](../../database/flyway/sql/V008__admin_and_operations.sql)
- [V009__test_and_analytics.sql](../../database/flyway/sql/V009__test_and_analytics.sql)
- [V010__declared_foreign_keys.sql](../../database/flyway/sql/V010__declared_foreign_keys.sql)
- [V011__strong_constraints_and_indexes.sql](../../database/flyway/sql/V011__strong_constraints_and_indexes.sql)
- [V012__guards_and_ledger_function.sql](../../database/flyway/sql/V012__guards_and_ledger_function.sql)
- [V013__safe_views.sql](../../database/flyway/sql/V013__safe_views.sql)
- [V014__review_baseline_seed.sql](../../database/flyway/sql/V014__review_baseline_seed.sql)
- [V015__outbox_session_generation_and_totp.sql](../../database/flyway/sql/V015__outbox_session_generation_and_totp.sql)
- [001_smoke.sql](../../database/tests/sql/001_smoke.sql)
- [002_constraints.sql](../../database/tests/sql/002_constraints.sql)
- [003_ledger.sql](../../database/tests/sql/003_ledger.sql)
- [004_security.sql](../../database/tests/sql/004_security.sql)

- [005_ib11_security_outbox.sql](../../database/tests/sql/005_ib11_security_outbox.sql)

- [静态校验工具](../../database/tests/static_validate.py)
- [冻结DDL解析工具（禁止回写）](../../database/tools/generate_flyway.py)

## 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。
