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

# 风暴扑克 PostgreSQL 数据字典

版本：V1.5-review（IB-1.1）  
生成日期：2026-10-21  
数据库：PostgreSQL 16+  
默认 Schema：`poker`  
状态：依据需求推导的技术评审稿；已纳入方案 A 的数据库强约束裁定、跨表约束责任矩阵及需求覆盖复审修订，不是已执行 DDL

## 1. 文档目的与依据

本文把产品需求、运营后台需求、设计字段契约和参考项目实现统一为可落地的 PostgreSQL 逻辑数据模型，供后端实现、DDL 编写、接口评审、测试造数和验收追踪使用。

推导优先级如下：

1. `docs/docs/product.html` 及其 `docs/config.html`。
2. `文档/运营后台需求文档-V2` 中的 PRD、模块、流程与权限矩阵。
3. `ui/player/docs/ui-contract.html`。
4. `texas-holdem` 的 `docs/schema.sql`、`docs/数据库字段.md` 与存储代码，仅作既有实现和迁移线索。

参考项目中的 `th_accounts`、`th_rooms`、`th_hands`、`th_login_logs` 等概念被保留，但以下实现不沿用：

- 金额使用 `double precision`；新模型统一使用整数最小单位 `bigint`。
- 用嵌套快照表直接表达业务账；新模型采用复式账本和不可变业务记录。
- 用昵称、数组位置或 JSON 路径充当业务关联；新模型使用稳定主键和显式外键。
- 每个玩家仅保留最近 3000 手；新模型改为按统一保留策略归档和游标分页查询，V1先使用普通表与时间索引，达到容量阈值后再按ADR-DB-001评审分区。
- `is_admin` 单布尔权限；新模型使用独立后台身份、角色、动作权限和资源范围。

## 2. 设计基线

### 2.1 命名和类型

| 项目 | 约定 |
| --- | --- |
| 表、字段 | `snake_case`；表名使用单数名词 |
| 内部主键 | `uuid`，默认 `gen_random_uuid()`；不向普通页面暴露顺序信息 |
| 外部业务号 | `varchar(32~64)`，带对象前缀，例如 `USR_`、`ROM_`、`HND_` |
| 金额 | `bigint`，单位为对应资产的最小单位；当前精度 2 时 `100` 表示 `1.00` |
| 账本分录 | `delta_amount bigint`；正数增加账户余额、负数减少账户余额，同一事务合计必须为 0 |
| 比例 | `numeric(9,6)`，范围 `0 <= value <= 1` |
| 高精度计提 | `numeric(30,12)`，日汇总后才向下取到资产精度 |
| 时间 | `timestamptz`，数据库存 UTC；展示统一转 `Asia/Shanghai` |
| 业务日 | `date`，明确按 `Asia/Shanghai` 计算 |
| IP | `inet` |
| 可扩展属性 | 仅低频、非核心查询字段允许 `jsonb`；账务、权限、状态和关联不得藏入 JSON |
| 状态枚举 | 首期用 `varchar + CHECK`，避免 PostgreSQL 原生 ENUM 阻碍灰度演进 |

### 2.2 标记

| 标记 | 含义 |
| --- | --- |
| PK | 主键 |
| FK | 外键 |
| UQ | 唯一约束 |
| CK | 检查约束 |
| IDX | 普通索引 |
| PII | 个人或敏感信息，接口必须按权裁剪 |
| SECRET | 密钥、令牌或私牌数据，不得写普通日志或导出 |

### 2.3 通用字段

除不可变明细表和明确使用共享主键的一对一表另有说明外，业务实体默认包含以下字段。后续各表不重复列出时，仍视为包含这些字段。`user_preference`、`user_timebank` 使用 `user_id` 作为共享主键，不再额外包含 `id`。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `id` | `uuid` | PK | 内部主键 |
| `created_at` | `timestamptz` | NOT NULL, default `now()` | 服务端创建时间 |
| `updated_at` | `timestamptz` | NOT NULL, default `now()` | 最近一次持久化更新时间；不得冒充业务发生时间 |
| `row_version` | `bigint` | NOT NULL, default `0` | 乐观锁版本；更新时递增 |

不可变流水表只保留 `id`、业务发生时间和 `created_at`，禁止更新或软删。历史对象原则上不物理删除；状态终止、归档或法定清理应保留独立审计记录。

### 2.4 已接受的 P0 架构决策

| ADR | 决策 | V1 处理 | 放弃/延后 |
| --- | --- | --- | --- |
| ADR-DB-001 | 全局唯一约束优先于提前分区 | 账本、手牌事件、审计、聊天和分析事件均先使用普通表及时间索引 | 达到容量阈值后再引入全局 ID 注册表和时间分区，不在 V1 承担复合主键传播成本 |
| ADR-DB-002 | 私牌授权目标关系化 | 申请目标和实际访问目标使用子表；私牌只允许通过受限函数读取 | 不使用 `uuid[]` 承载授权边界，不允许应用角色直接查询私牌密文 |
| ADR-DB-003 | 座位竞争使用统一占用行 | 每个物理座位一条 `room_seat_occupancy`，预约、买入和离座均锁同一行 | 不依赖两张业务表各自的唯一索引解决跨表竞争，不以约定式 advisory lock 作为主方案 |
| ADR-DB-004 | 账本采用有符号零和分录 | 正数增加、负数减少；POSTED 事务分录合计为 0；冲正新建交易 | 不使用未冻结会计口径的 `D/C` 字段，不修改已 POSTED 原交易表达冲正 |
| ADR-DB-005 | 动作请求与动作事实分离 | `hand_action_request` 保存接受和拒绝结果，`hand_action` 只保存已接受事实 | 不让失败请求随事务异常回滚，不依赖内存缓存实现 action_id 幂等 |
| ADR-DB-006 | 资金授权和代理归因由数据库防重 | 调款授权与操作复合绑定且只能消费一次；原始归因和冲正分别使用部分唯一索引 | 不使用包含可空列的普通唯一约束表达原始归因唯一性，不只依赖服务层判重 |
| ADR-DB-007 | 消息发送者显式建模 | 玩家、后台和系统发送者分别约束幂等；用户屏蔽独立关系化 | 不把系统消息冒充后台人员消息，不把屏蔽列表藏入偏好 JSON/数组 |
| ADR-DB-008 | 存储状态与展示状态分离 | 账本存储状态保持 `PENDING/POSTED/FAILED`；`REVERSED` 由有效冲正交易派生 | 不更新原 POSTED 交易来迎合前端状态枚举 |
| ADR-DB-009 | 相同规则允许创建多个独立房间快照 | `room_rule_snapshot.content_digest` 仅作校验与普通索引，每个房间持有独立不可变快照 | 不以全局摘要唯一约束误阻止相同模板重复开房，也不在V1共享房间快照 |
| ADR-DB-010 | 请求幂等与领域状态轨迹分离 | `business_operation` 保存请求结果；一对一领域结果唯一绑定操作；邀请申请的多次状态迁移写追加事件 | 不用一个 `operation_id` 同时冒充申请、审核、撤销等多次操作 |
| ADR-DB-011 | 权限、代理与禁言关系使用数据库排斥约束 | 活动记录防重、有效区间不得重叠，当前字段和历史在受限函数内原子同步 | 不仅依赖应用查询后再写入，不允许重复活动授权掩盖撤权 |
| ADR-DB-012 | 高风险授权必须参数绑定并由受限函数消费 | 权限变更、私牌审批/读取和资金调整均复合绑定 `sensitive_authorization` 与 `business_operation` | 不允许应用角色直接更新高风险终态，不接受只在接口层检查TOTP |
| ADR-DB-013 | 恢复资金按明细关系化 | `recovery_case_item` 记录玩家、资产、账户、原交易和最终处置，案件总额由明细汇总 | 不用单个无资产的 `frozen_amount` 充当资金事实 |
| ADR-DB-014 | 恢复快照采用检查点加事件重放 | `room_state_snapshot` 只保存周期检查点；恢复时选择不超过 `room.state_version` 的最新完整快照并重放后续事件 | 不要求每个动作版本写完整快照，不把 `room.state_version` 冒充快照外键 |
| ADR-DB-015 | 玩家账号与认证身份分离 | `app_user` 只承载稳定玩家身份；`player_identity` 统一 LOCAL/TELEGRAM 来源；本地口令单独存入 `local_credential` | 不把 Telegram 字段写入玩家主表，不让绑定外部身份新建钱包、归属或战绩，不让玩家凭据进入后台认证域 |

上述决策是数据模型与 Flyway DDL 的强制边界。替代方案只有在新 ADR 说明容量证据、迁移路径和回滚方式后才能采用。

## 3. 领域关系总览

```mermaid
flowchart LR
  U[app_user 玩家] --> M[club_membership 归属历史]
  U --> PI[player_identity 认证身份]
  PI --> LC[local_credential 本地口令]
  U --> PS[player_session 操控会话]
  M --> C[club 俱乐部]
  C --> R[room 房间]
  R --> SO[room_seat_occupancy 座位占用]
  SO --> SS[seat_session 入座资金会话]
  R --> SS[seat_session 入座资金会话]
  SS --> H[hand 手牌]
  H --> HAR[hand_action_request 动作请求]
  HAR --> HA[hand_action 已接受动作]
  H --> P[hand_pot 底池]
  H --> LS[ledger_transaction 账务事务]
  U --> LA[ledger_account 账务账户]
  LS --> LE[ledger_entry 复式分录]
  H --> CA[commission_attribution 分成归因]
  CA --> DS[commission_daily_statement 代理日账]
  AU[admin_user 后台人员] --> BO[business_operation 操作结果]
  BO --> AL[audit_log 审计]
  T[support_ticket 工单] --> PA[private_card_access_request 私牌专项]
  PA --> PT[private_card_access_request_player 批准目标]
  PA --> PL[private_card_access_log 逐次访问]
  PL --> PRT[private_card_access_log_player 实际目标]
  PL --> AL
  U --> UCB[user_chat_block 用户屏蔽]
```

文字说明：玩家核心业务只引用稳定 `app_user.id`；本地登录和未来 Telegram 绑定均通过 `player_identity` 解析到同一玩家，本地口令与外部资料不进入钱包、俱乐部或牌局主键。玩家在一个时点只有一个当前俱乐部归属；房间引用不可变规则快照；每个座位通过统一占用行仲裁预约和入座，一次入座对应一个资金会话；每手先持久化动作请求结果，再由已接受动作、牌、底池、派奖和零和账务共同构成；私牌目标关系化并逐次授权审计；聊天屏蔽是接收侧关系，不删除消息或屏蔽系统提示；后台人员只通过业务操作请求权威服务，不能直接改余额、筹码、牌序或结算终态。

## 4. 身份与玩家域

### 4.1 `app_user` — 玩家主账号

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `game_id` | `varchar(32)` | NOT NULL, UQ | 对外稳定玩家 ID，不因登录名、昵称或外部身份变化而改变 |
| `display_name` | `varchar(20)` | NOT NULL | 玩家展示昵称；去首尾空格后 2–20 个可见 Unicode 字符，允许重复；控制字符和纯空白由服务端拒绝 |
| `avatar_url` | `text` | NULL | 头像地址；失效时客户端用默认头像 |
| `status` | `varchar(24)` | NOT NULL, CK `ACTIVE/DISABLED` | 禁用只阻止新准入，不没收资产 |
| `disabled_reason` | `varchar(500)` | NULL | 禁用原因；仅后台按权可见 |
| `disabled_at` | `timestamptz` | NULL | 禁用生效时间 |
| `registered_at` | `timestamptz` | NOT NULL | 新环境真实注册时间；旧数据未知时不得写入主表或用 `updated_at` 补造，只能留在可空的只读迁移暂存表 |
| `session_generation` | `bigint` | NOT NULL, default 0, CK >=0 | 玩家操控会话代际，只增不减；不是设备编号 |
| `last_login_at` | `timestamptz` | NULL | 最近一次任一合法身份完整登录成功时间 |

索引：`(status, registered_at desc, id)`、`lower(display_name)` 的 `pg_trgm` GIN 索引；昵称不唯一。注册只创建普通玩家；`app_user` 不包含后台角色、初始余额或 Telegram 专用字段。

### 4.2 `player_identity` — 玩家认证身份

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 统一玩家；绑定身份不得创建第二套玩家、钱包、归属或战绩 |
| `provider` | `varchar(24)` | NOT NULL, CK `LOCAL/TELEGRAM` | 认证提供者；首期只开放 LOCAL，TELEGRAM 为后续接入预留 |
| `provider_subject` | `varchar(128)` | NOT NULL, PII | 提供者内稳定键；LOCAL 为小写规范化登录名，TELEGRAM 为十进制 `user.id` 字符串 |
| `provider_username` | `varchar(64)` | NULL, PII | 外部 username 快照，可变且不作账号键；LOCAL 为空 |
| `provider_display_name` | `varchar(128)` | NULL, PII | 外部展示名快照；仅在玩家显式选择时同步到主账号资料 |
| `provider_avatar_url` | `text` | NULL, PII | 外部头像快照；不自动覆盖主账号资料 |
| `verified_at` | `timestamptz` | NOT NULL | 本次身份完成服务端验证时间；TG 接入后须先校验 `initData` 和时效 |
| `bound_at` | `timestamptz` | NOT NULL | 绑定到统一玩家的时间 |
| `unbound_at` | `timestamptz` | NULL | 外部身份解绑时间；LOCAL 登录停用使用凭据状态而非解绑 |
| `last_authenticated_at` | `timestamptz` | NULL | 该身份最近一次成功认证时间 |

约束：`UNIQUE(provider, provider_subject)` 防止同一身份属于两个玩家；部分唯一索引 `UNIQUE(user_id, provider) WHERE unbound_at IS NULL` 防止同一玩家同时存在两个活动同源身份。LOCAL subject 必须匹配 `^[a-z0-9_]{4,32}$`；TELEGRAM subject 必须是非零开头十进制数字。用户名展示、TG username 和 TG display name 永远不作业务关联键。

### 4.3 `local_credential` — 本地登录凭据

使用 `identity_id` 作为与 `player_identity` 的共享主键；除该主键外仍包含 `created_at/updated_at/row_version`。登录名只存于对应 LOCAL 身份的 `provider_subject`，不在凭据表重复保存。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `identity_id` | `uuid` | PK, FK → `player_identity.id` | 一条 LOCAL 身份最多一条本地凭据 |
| `provider` | `varchar(24)` | NOT NULL, default `'LOCAL'`, CK `LOCAL` | 用于复合外键保证凭据只能挂到 LOCAL 身份 |
| `password_hash` | `varchar(255)` | NOT NULL, SECRET | Argon2id 或经评审的现代口令哈希；禁止明文、可逆密文、空值及写普通日志 |
| `failed_login_count` | `smallint` | NOT NULL, default 0, CK 0–5 | 连续失败次数；成功后清零，第 5 次失败进入锁定 |
| `locked_until` | `timestamptz` | NULL | 连续 5 次失败后至少锁定 15 分钟；到期收口和失败计数更新须原子执行 |
| `password_changed_at` | `timestamptz` | NOT NULL | 最近一次设置或重置口令时间 |
| `status` | `varchar(24)` | NOT NULL, CK `ACTIVE/RESET_REQUIRED/DISABLED` | 本地凭据状态，不等同于玩家资产状态 |
| `last_failed_at` | `timestamptz` | NULL | 最近一次口令失败时间，供安全审计和锁定计算 |

约束：`(identity_id, provider)` 复合外键必须命中 `player_identity(id, provider)` 且 provider 固定为 LOCAL；`password_hash` 至少 20 个字符且不得为空白。输入密码 8–72 个字符、IP 每分钟最多 30 次属于认证服务与限流存储的入口规则，不保存原始密码。首个注册玩家不得由数据库种子或服务逻辑自动获得 `admin_user`、后台角色或初始余额。

### 4.4 `player_session` — 玩家操控会话

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `session_generation` | `bigint` | NOT NULL, CK >0 | 本次会话创建时复制的玩家代际；UNIQUE(user_id,session_generation) |
| `identity_id` | `uuid` | FK → `player_identity.id`, NOT NULL | 建立本次会话所使用的认证身份；业务授权仍以 `user_id` 为准 |
| `session_token_hash` | `bytea` | NOT NULL, UQ, SECRET | 仅存会话令牌摘要 |
| `device_id_hash` | `bytea` | NULL, PII | 设备稳定摘要，不存可逆设备指纹 |
| `user_agent` | `varchar(1024)` | NULL, PII | 设备摘要来源 |
| `ip_address` | `inet` | NULL, PII | 建立会话时 IP |
| `authenticated_at` | `timestamptz` | NOT NULL | 本次身份认证完成时间 |
| `expires_at` | `timestamptz` | NOT NULL | 最长 24 小时 |
| `revoked_at` | `timestamptz` | NULL | 新设备接管、退出或安全事件撤销时间 |
| `revoke_reason` | `varchar(64)` | NULL | `DEVICE_TAKEOVER/LOGOUT/EXPIRED/ADMIN_DISABLED/GENERATION_MIGRATION` 等 |
| `active_room_id` | `uuid` | FK → `room.id`, NULL | 当前真人桌恢复入口；同一玩家最多一个活动值 |

约束：`identity_id` 必须属于同一 `user_id`；部分唯一索引 `UNIQUE(user_id) WHERE revoked_at IS NULL`，确保一个未撤销操控会话。建立新会话必须调用受限函数：先锁定 `app_user`，把 `expires_at <= now()` 但尚未撤销的旧会话写为 `revoked_at=now(), revoke_reason='EXPIRED'`，再撤销其他接管会话并插入新会话；所有鉴权同时要求 `revoked_at IS NULL AND expires_at > now()`。不得把依赖 `now()` 的条件写入部分索引，客户端也不得仅凭 `user_id` 恢复会话。

代际写入协议：认证成功后 create_player_session 先锁 app_user，撤销旧会话、将 app_user.session_generation 加1，再以该值创建 player_session，同事务写审计和接管通知。普通 WSS 重连沿用原会话/代际，不递增；退出、禁用、密码重置撤销会话并推进代际。迁移 V015 将历史会话全部撤销，历史会话按(created_at,id)编号，玩家计数置为其历史最大代际（无历史置0）；上线后重新登录取得更大的正数代际，禁止给仍活动的旧会话猜测代际。

每个动作必须在事务内锁同一 app_user，要求 token 命中会话、会话未撤销且未过期、信封代际=player_session.session_generation=app_user.session_generation，才可持锁提交。登录接管也争同一锁，因此接管提交后旧连接不能提交新动作；此前已持锁的动作按提交先后线性化。旧连接关闭只是通知优化，不能代替每次鉴权。代际不一致返回 SESSION_REPLACED。受限会话/动作函数未实现前保持关闭。

### 4.5 `player_login_event` — 玩家登录审计

不可变。V1 使用普通表并按 `occurred_at` 建索引，以保留单列 UUID 主键和跨时间全局约束；达到容量阈值后再按 ADR-DB-001 演进。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `occurred_at` | `timestamptz` | NOT NULL | 服务端收到请求时间 |
| `method` | `varchar(24)` | NOT NULL | `LOCAL_REGISTER/LOCAL_PASSWORD/SESSION_RESUME/DEVICE_TAKEOVER/TG_AUTH/TG_BIND` |
| `user_id` | `uuid` | FK → `app_user.id`, NULL | 未识别账号时为空，审计记录仍保留 |
| `identity_id` | `uuid` | FK → `player_identity.id`, NULL | 已识别身份；失败或会话恢复事件可为空 |
| `auth_provider` | `varchar(24)` | NULL, CK `LOCAL/TELEGRAM` | 本次认证来源；与未识别账号的失败事件一起保留 |
| `login_identifier_hash` | `bytea` | NULL, PII | 登录名或外部 subject 的带密钥不可逆摘要；不存密码、原始 initData 或会话令牌 |
| `success` | `boolean` | NOT NULL | 是否成功 |
| `failure_code` | `varchar(64)` | NULL | 安全可记录的失败码，不存凭据 |
| `ip_address` | `inet` | NULL, PII | 经可信代理解析后的来源 IP |
| `user_agent` | `varchar(1024)` | NULL, PII | 客户端摘要 |
| `request_id` | `uuid` | NULL | 链路请求号 |

索引：`(user_id, occurred_at desc)`、`(occurred_at desc)`；IP 查询另验 `BP-05`。

### 4.6 `user_preference` — 玩家偏好

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `user_id` | `uuid` | PK, FK → `app_user.id` | 一人一行 |
| `card_theme` | `varchar(24)` | NOT NULL | `CLASSIC/FOUR_COLOR/FULL_COLOR/RANK_ONLY` |
| `table_theme` | `varchar(24)` | NOT NULL | `EMERALD/GRAPHITE/MIDNIGHT_BLUE` |
| `card_back_theme` | `varchar(24)` | NOT NULL | `CLASSIC_RED/DEEP_BLUE/INK_GREEN` |
| `sound_enabled` | `boolean` | NOT NULL, default false | 账号偏好；设备授权另行处理 |
| `vibration_enabled` | `boolean` | NOT NULL, default false | 同上 |
| `hide_balance` | `boolean` | NOT NULL, default false | 仅显示偏好，不改变权限 |
| `quick_bets` | `varchar(16)[]` | NOT NULL | 3–5 个去重选项；服务端校验候选集 |
| `preference_version` | `integer` | NOT NULL | 主题下架或规则变更时迁移版本 |

### 4.7 `user_timebank` — 账号级时间银行

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `user_id` | `uuid` | PK, FK → `app_user.id` | 跨房间、换座、重买不重置 |
| `remaining_ms` | `integer` | NOT NULL, CK 0–60000 | 当前剩余时间；初始 30000 |
| `valid_hand_count` | `bigint` | NOT NULL, default 0 | 累计有效手数 |
| `last_bonus_hand_count` | `bigint` | NOT NULL, default 0 | 防止每 10 手奖励重复发放 |

### 4.8 `protocol_acceptance` — 协议接受记录

不可变。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `protocol_type` | `varchar(32)` | NOT NULL | `TERMS/PRIVACY/RULE_DISCLOSURE` |
| `protocol_version` | `varchar(32)` | NOT NULL | 正式发布版本 |
| `content_digest` | `bytea` | NOT NULL | 接受内容摘要 |
| `accepted_at` | `timestamptz` | NOT NULL | 服务端确认时间 |
| `room_id` | `uuid` | FK → `room.id`, NULL | 房间规则披露接受时关联 |
| `rule_snapshot_id` | `uuid` | FK → `room_rule_snapshot.id`, NULL | 对应冻结规则 |
| `source` | `varchar(24)` | NOT NULL | `WEB_CLIENT/TG_CLIENT/ROOM_BUYIN`；首期注册协议来自 WEB_CLIENT |

唯一约束：`(user_id, protocol_type, protocol_version, coalesce(room_id, zero_uuid))`。

## 5. 组织、代理与邀请域

### 5.1 `agent` — 代理实体

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `agent_code` | `varchar(32)` | NOT NULL, UQ | 稳定代理业务 ID |
| `name` | `varchar(80)` | NOT NULL | 当前名称；历史显示使用快照 |
| `status` | `varchar(24)` | NOT NULL, CK `ACTIVE/DISABLED` | 停用不删除历史计提 |
| `manager_agent_id` | `uuid` | FK → `agent.id`, NULL | 仅管理关系，不自动产生多层佣金 |
| `created_by_admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 创建人 |
| `registered_at` | `timestamptz` | NOT NULL | 代理建立时间 |

### 5.2 `agent_agreement_version` — 代理协议/等级版本

发布后不可覆盖。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `agreement_code` | `varchar(32)` | NOT NULL | 协议族 ID |
| `version_no` | `integer` | NOT NULL | 递增版本 |
| `agent_id` | `uuid` | FK → `agent.id`, NOT NULL | 代理 |
| `level_code` | `varchar(32)` | NOT NULL | 默认 `GENERAL` |
| `rate` | `numeric(9,6)` | NOT NULL, CK 0–1 | GENERAL 默认 0；不得超操作者上限 |
| `status` | `varchar(24)` | NOT NULL | `DRAFT/PUBLISHED/RETIRED/CONFIG_ERROR` |
| `effective_from` | `timestamptz` | NULL | 发布后的生效时间；新手引用 |
| `effective_to` | `timestamptz` | NULL | 版本结束时间，左闭右开 |
| `published_by_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 发布人 |
| `content_digest` | `bytea` | NOT NULL | 防止版本内容被静默修改 |

唯一约束：`(agreement_code, version_no)`；同代理有效区间不得重叠（建议 `tstzrange` 排斥约束）。

### 5.3 `club` — 俱乐部

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `club_code` | `varchar(32)` | NOT NULL, UQ | 对外俱乐部 ID |
| `name` | `varchar(80)` | NOT NULL | 名称 |
| `avatar_url` | `text` | NULL | 头像 |
| `description` | `varchar(500)` | NULL | 简介 |
| `status` | `varchar(24)` | NOT NULL | `ACTIVE/FROZEN/ARCHIVED` |
| `is_default` | `boolean` | NOT NULL, default false | 系统保底俱乐部；禁止冻结和归档 |
| `direct_agent_id` | `uuid` | FK → `agent.id`, NULL | 首期最多一个直接代理；空表示平台 |
| `allow_player_create` | `boolean` | NOT NULL, default false | 玩家开房总开关 |
| `frozen_at` | `timestamptz` | NULL | 冻结时间 |
| `archived_at` | `timestamptz` | NULL | 归档时间 |
| `status_reason` | `varchar(500)` | NULL | 冻结/归档原因 |

约束：全库最多一条 `is_default=true`；默认俱乐部状态必须为 `ACTIVE`。

### 5.4 `club_agent_history` — 俱乐部直接代理历史

历史记录除关闭当前有效区间时首次写入 `effective_to` 外不可修改；已关闭区间完全不可变。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `club_id` | `uuid` | FK → `club.id`, NOT NULL | 俱乐部 |
| `agent_id` | `uuid` | FK → `agent.id`, NULL | 空表示平台归因 |
| `effective_from` | `timestamptz` | NOT NULL | 生效起点 |
| `effective_to` | `timestamptz` | NULL | 结束时点 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL | 变更操作 |
| `agent_code_snapshot` | `varchar(32)` | NULL | 历史展示快照 |
| `agent_name_snapshot` | `varchar(80)` | NULL | 历史展示快照 |

约束：`effective_to IS NULL OR effective_to > effective_from`；`UNIQUE(club_id) WHERE effective_to IS NULL`；使用 `btree_gist` 建立同俱乐部 `tstzrange(effective_from, coalesce(effective_to, 'infinity'), '[)')` 不重叠的排斥约束；`operation_id` 唯一。应用角色不得直接写入本表或 `club.direct_agent_id`，只能调用 `change_club_agent`，在同一事务内锁定俱乐部、关闭旧区间、创建新区间、更新当前代理并写审计。

### 5.5 `club_membership` — 玩家归属与迁移历史

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `club_id` | `uuid` | FK → `club.id`, NOT NULL | 目标俱乐部 |
| `agent_id_snapshot` | `uuid` | FK → `agent.id`, NULL | 生效时直接代理快照 |
| `status` | `varchar(24)` | NOT NULL | `PENDING/CURRENT/ENDED/CANCELLED` |
| `source_club_id` | `uuid` | FK → `club.id`, NULL | 迁移来源；首次归属为空 |
| `requested_at` | `timestamptz` | NOT NULL | 提交时间 |
| `effective_at` | `timestamptz` | NULL | 实际生效时间 |
| `ended_at` | `timestamptz` | NULL | 归属终止时间 |
| `wait_hand_id` | `uuid` | FK → `hand.id`, NULL | 有在手时等待完成的手 |
| `cancel_code` | `varchar(64)` | NULL | 撤权、目标冻结等取消原因 |
| `reason` | `varchar(500)` | NOT NULL | 迁移原因 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL, UQ | 幂等业务操作；一次迁移只创建一条目标归属记录 |

约束：每个玩家最多一条 `CURRENT`、最多一条 `PENDING` 的部分唯一索引。生效前再次校验双侧权限和目标 `ACTIVE`。

### 5.6 `club_template_allowlist` — 玩家开房模板白名单

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `club_id` | `uuid` | FK → `club.id`, NOT NULL | 俱乐部 |
| `rule_template_version_id` | `uuid` | FK → `rule_template_version.id`, NOT NULL | 仅已发布版本 |
| `enabled` | `boolean` | NOT NULL | 是否允许 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL | 授权操作 |

唯一约束：`(club_id, rule_template_version_id)`。

### 5.7 `invite` — ROOM/CLUB 业务邀请

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `invite_code` | `char(6)` | NULL, UQ | 大写短码，排除 `0/O/1/I`；可与深链并存 |
| `token_hash` | `bytea` | NOT NULL, UQ, SECRET | 深链不透明 token 的摘要；原 token 不落日志/导出 |
| `target_type` | `varchar(16)` | NOT NULL, CK `ROOM/CLUB` | 邀请目标类型 |
| `target_id` | `uuid` | NOT NULL | 目标 ID；由服务层按类型校验 |
| `policy` | `varchar(32)` | NOT NULL | `EXPIRING_24H/PERMANENT_REVIEW` |
| `issuer_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 后台签发者 |
| `issuer_user_id` | `uuid` | FK → `app_user.id`, NULL | 获授权的玩家签发者 |
| `expires_at` | `timestamptz` | NULL | 永久审核策略可为空；ROOM 仍受关闭约束 |
| `revoked_at` | `timestamptz` | NULL | 撤销时间 |
| `revoked_by_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 撤销人 |
| `revoke_reason` | `varchar(500)` | NULL | 撤销原因 |
| `status_hint` | `varchar(24)` | NOT NULL | `ACTIVE/REVOKED`；`EXPIRED/TARGET_UNAVAILABLE` 查询时派生 |

约束：`issuer_admin_id` 与 `issuer_user_id` 恰有一个非空。

### 5.8 `invite_application` — 邀请申请与审核

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `application_code` | `varchar(32)` | NOT NULL, UQ | 对外申请号 |
| `invite_id` | `uuid` | FK → `invite.id`, NOT NULL | 来源邀请 |
| `applicant_user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 申请人 |
| `status` | `varchar(24)` | NOT NULL | `PENDING/APPROVED/REJECTED/WITHDRAWN/EXPIRED/FROZEN/CANCELLED` |
| `reviewer_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 审核人 |
| `reviewed_at` | `timestamptz` | NULL | 审核时间 |
| `review_reason` | `varchar(500)` | NULL | 审核理由；与玩家公开结论分离 |
| `membership_id` | `uuid` | FK → `club_membership.id`, NULL | CLUB 审批后产生的即时或待生效归属 |
| `room_access_status` | `varchar(24)` | NULL | ROOM 访问 `PENDING/GRANTED/REVOKED/EXPIRED` |
| `submit_operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL, UQ | 创建申请的幂等操作 |
| `review_operation_id` | `uuid` | FK → `business_operation.id`, NULL, UQ | 批准或拒绝操作；PENDING 时为空，与提交操作分离 |

唯一约束：同一邀请、同一申请人最多一个未决申请；并发审核锁定申请行并以唯一 `review_operation_id` 保证一个审核终态。审核操作通过 `business_operation.parent_operation_id` 引用提交操作；撤销、冻结、失效和生效轨迹写入追加事件，不覆盖原操作号。

### 5.9 `invite_application_event` — 邀请申请状态轨迹

不可变；申请、审核、撤回、邀请撤销联动、目标冻结、失效和归属生效均追加事件。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `application_id` | `uuid` | FK → `invite_application.id`, NOT NULL | 邀请申请 |
| `seq_no` | `integer` | NOT NULL | 申请内递增序号 |
| `from_status` | `varchar(24)` | NULL | 创建事件为空 |
| `to_status` | `varchar(24)` | NOT NULL | 新状态 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL | 触发该次迁移的幂等操作；批量冻结/撤销可影响多个申请 |
| `operator_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 后台审核或处置人；玩家/系统事件为空 |
| `reason_code` | `varchar(64)` | NOT NULL | 稳定原因码 |
| `reason_text` | `varchar(500)` | NULL | 安全可展示或内部原因，按接口裁剪 |
| `occurred_at` | `timestamptz` | NOT NULL | 权威发生时间 |

唯一约束：`(application_id, seq_no)`、`(operation_id, application_id)`。状态更新与事件插入必须在同一受限函数事务内完成；事件不可更新或删除。

### 5.10 `invite_redemption` — 邀请校验和使用事实

不可变。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `invite_id` | `uuid` | FK → `invite.id`, NOT NULL | 邀请 |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 使用人 |
| `application_id` | `uuid` | FK → `invite_application.id`, NULL | 审核型邀请关联申请 |
| `result` | `varchar(32)` | NOT NULL | `VALIDATED/ACCESS_GRANTED/REJECTED` |
| `failure_code` | `varchar(64)` | NULL | 过期、撤销、房间关闭等 |
| `occurred_at` | `timestamptz` | NOT NULL | 发生时间 |
| `request_id` | `uuid` | NOT NULL, UQ | 幂等及旅程归因 |
| `parameter_digest` | `bytea` | NOT NULL | 规范化邀请、用户、申请和校验用途；同号异参数拒绝 |

重复 `request_id` 且摘要相同返回首次保存的 `result/failure_code`，摘要不同返回 `IDEMPOTENCY_CONFLICT`，不得在邀请状态变化后重新解释原请求。

## 6. 规则、费用与系统配置域

### 6.1 `fee_template_version` — 抽水模板版本

发布后不可变。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `fee_code` | `varchar(32)` | NOT NULL | 例如 `CSV_STANDARD_V2` |
| `version_no` | `integer` | NOT NULL | 递增版本 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 费率模板资产 |
| `rake_rate` | `numeric(9,6)` | NOT NULL, CK 0–1 | 默认 5% 或 3% |
| `rake_cap_amount` | `bigint` | NOT NULL, CK >=0 | 明确金额封顶；房间快照同时保存对应 BB |
| `postflop_only` | `boolean` | NOT NULL, default true | 未发翻牌费为 0 |
| `whole_hand_cap` | `boolean` | NOT NULL, default true | 全手只封顶一次 |
| `rounding_mode` | `varchar(24)` | NOT NULL | 当前 `FLOOR_TO_PRECISION` |
| `status` | `varchar(24)` | NOT NULL | `DRAFT/PUBLISHED/RETIRED` |
| `effective_from` | `timestamptz` | NULL | 发布生效时间 |
| `published_by_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 发布人 |
| `content_digest` | `bytea` | NOT NULL | 内容摘要 |

唯一约束：`(fee_code, version_no)`。

### 6.2 `exit_fee_template_version` — 提前盈利离座费版本

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `exit_fee_code` | `varchar(32)` | NOT NULL | 默认 `EARLY_EXIT_PROFIT_V2` |
| `version_no` | `integer` | NOT NULL | 版本 |
| `profit_rate` | `numeric(9,6)` | NOT NULL, CK 0–1 | 默认 30% |
| `exempt_natural_end` | `boolean` | NOT NULL, default true | 自然到期豁免 |
| `exempt_operator_close` | `boolean` | NOT NULL, default true | 运营关闭/禁用/移除豁免 |
| `exempt_service_failure` | `boolean` | NOT NULL, default true | 服务故障豁免 |
| `exempt_no_valid_hand` | `boolean` | NOT NULL, default true | 无有效手豁免 |
| `status` | `varchar(24)` | NOT NULL | `DRAFT/PUBLISHED/RETIRED` |
| `effective_from` | `timestamptz` | NULL | 生效时间 |
| `published_by_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 发布人 |
| `content_digest` | `bytea` | NOT NULL | 摘要 |

### 6.3 `rule_template` — 规则模板族

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `template_code` | `varchar(32)` | NOT NULL, UQ | 模板稳定 ID |
| `name` | `varchar(80)` | NOT NULL | 模板名称 |
| `owner_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 运营草稿所属人；超管模板可为空 |
| `description` | `varchar(500)` | NULL | 用途说明 |

### 6.4 `rule_template_version` — 可发布规则版本

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `template_id` | `uuid` | FK → `rule_template.id`, NOT NULL | 模板族 |
| `version_no` | `integer` | NOT NULL | 版本号 |
| `status` | `varchar(24)` | NOT NULL | `DRAFT/PUBLISHED/RETIRED` |
| `deck_mode` | `varchar(16)` | NOT NULL | `LONG/SHORT` |
| `betting` | `varchar(8)` | NOT NULL, CK `NLH` | 本期不支持 Limit |
| `seat_count` | `smallint` | NOT NULL | 长牌 8、短牌 6 |
| `room_seconds` | `integer` | NOT NULL | 长牌 7200/10800，短牌 3600 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 币种 |
| `sb_amount` | `bigint` | NOT NULL, CK >0 | 小盲 |
| `bb_amount` | `bigint` | NOT NULL, CK >0 | 大盲；应为最小单位 2 的倍数，且 `sb*2=bb` |
| `buyin_min_amount` | `bigint` | NOT NULL, CK >0 | 最小买入 |
| `buyin_max_amount` | `bigint` | NOT NULL, CK >= min | 最大买入 |
| `ante_mode` | `varchar(16)` | NOT NULL | `OFF/EACH/BB_PAYS` |
| `ante_amount` | `bigint` | NOT NULL, CK >=0 | OFF 时为 0 |
| `straddle_mode` | `varchar(24)` | NOT NULL | `OFF/FORCED_UTG_2BB` |
| `start_players` | `smallint` | NOT NULL | 2 到座位上限 |
| `allow_spectate` | `boolean` | NOT NULL | 默认允许 |
| `delay_mode` | `varchar(24)` | NOT NULL | `OFF/BOARD_EACH_STREET/HOLE_PREFLOP` |
| `vpip_threshold` | `smallint` | NULL, CK 1–100 | 空表示关闭 |
| `absence_mode` | `varchar(32)` | NOT NULL | `EXIT_AFTER_HAND/AUTO_PLAY_UNTIL_DEADLINE` |
| `absence_deadline_mode` | `varchar(24)` | NOT NULL | `FIXED_SECONDS/ROOM_END` |
| `absence_seconds` | `integer` | NULL, CK 30–1800 | 固定时限模式必填 |
| `action_seconds` | `smallint` | NOT NULL, CK 10–60 | 默认 20 |
| `reconnect_grace_seconds` | `smallint` | NOT NULL, default 15 | 每手共享离线宽限 |
| `fee_template_version_id` | `uuid` | FK → `fee_template_version.id`, NOT NULL | 抽水版本 |
| `exit_fee_template_version_id` | `uuid` | FK → `exit_fee_template_version.id`, NOT NULL | 离座费版本 |
| `player_editable_fields` | `varchar(32)[]` | NOT NULL | 玩家可调字段白名单 |
| `editable_limits` | `jsonb` | NOT NULL, default `{}` | 仅保存白名单字段的允许范围 |
| `published_at` | `timestamptz` | NULL | 发布时间 |
| `published_by_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 发布人 |
| `content_digest` | `bytea` | NOT NULL | 规范化内容摘要 |

唯一约束：`(template_id, version_no)`。短牌必须 `seat_count=6` 且 Ante/抓头关闭；长牌必须 8 席和 2/3 小时。

### 6.5 `system_policy_version` — 固定系统策略版本

该表不是“万能参数后台”；只允许代码内白名单键，发布须走部署或受控配置流程。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `policy_key` | `varchar(64)` | NOT NULL | 如 `seat_reserve_seconds`、`zero_stack_reserve_seconds` |
| `version_no` | `integer` | NOT NULL | 版本 |
| `value_json` | `jsonb` | NOT NULL | 经过该键专属 schema 校验的值 |
| `status` | `varchar(24)` | NOT NULL | `DRAFT/PUBLISHED/RETIRED` |
| `effective_from` | `timestamptz` | NULL | 生效时间；PUBLISHED 必填 |
| `effective_to` | `timestamptz` | NULL | 结束时间；左闭右开，当前版本为空 |
| `published_by_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 发布人或部署主体映射 |
| `reason` | `varchar(500)` | NOT NULL | 变更原因 |
| `content_digest` | `bytea` | NOT NULL | 摘要 |

唯一约束：`(policy_key, version_no)`；`effective_to IS NULL OR effective_to > effective_from`；同键 PUBLISHED 有效区间使用 `btree_gist` 与 `tstzrange(effective_from, coalesce(effective_to, 'infinity'), '[)')` 排斥重叠。发布新版本必须在同一受限函数事务内锁定策略键、关闭旧区间并打开新区间。

## 7. 资产与复式账本域

### 7.1 `asset` — 资产定义

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `asset_code` | `varchar(16)` | NOT NULL, UQ | 如 `TEST`；不可用展示名关联 |
| `display_name` | `varchar(64)` | NOT NULL | 展示名称 |
| `precision` | `smallint` | NOT NULL, CK 0–8 | 当前桌面资产为 2 |
| `transferability` | `varchar(24)` | NOT NULL | `NON_TRANSFERABLE/FUTURE_REAL`；TEST 不可兑换 |
| `status` | `varchar(24)` | NOT NULL | `ACTIVE/INACTIVE` |
| `withdrawable_default` | `boolean` | NOT NULL, default false | 手工额度默认不可提 |

### 7.2 `ledger_account` — 账务账户

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `account_code` | `varchar(64)` | NOT NULL, UQ | 稳定账户号 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 资产 |
| `owner_type` | `varchar(16)` | NOT NULL | `USER/PLATFORM/AGENT/SYSTEM` |
| `owner_id` | `uuid` | NULL | USER/AGENT 时分别引用业务实体；由服务层和触发器校验 |
| `account_type` | `varchar(32)` | NOT NULL | `AVAILABLE/TOPUP_FROZEN/TABLE_ESCROW/RAKE_INCOME/EXIT_FEE_INCOME/COMMISSION_PAYABLE/ADJUSTMENT_CLEARING` |
| `balance` | `bigint` | NOT NULL, default 0 | 分录余额的同步缓存；只由受限过账函数按 `balance + delta_amount` 更新，可从完整账本校验 |
| `allow_negative` | `boolean` | NOT NULL, default false | 玩家可用/冻结/托管为 false；清算类系统账户按种子显式设为 true |
| `status` | `varchar(16)` | NOT NULL | `ACTIVE/FROZEN/CLOSED` |
| `withdrawable` | `boolean` | NOT NULL, default false | 账户余额是否具备提款资格；不等于资产可提款 |

唯一约束：`(asset_id, owner_type, owner_id, account_type)`，平台/系统空 owner 使用规范化生成列或 `NULLS NOT DISTINCT` 唯一约束。

### 7.3 `ledger_transaction` — 账务事务头

事务头仅允许一次受控状态变化：`PENDING → POSTED/FAILED`；到达终态后不可修改。冲正另建 `REVERSAL` 事务，原交易始终保持 `POSTED`。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `transaction_code` | `varchar(40)` | NOT NULL, UQ | 玩家账单可见交易号 |
| `business_id` | `varchar(64)` | NOT NULL | 买入、补码、结算、离座、调整等业务号 |
| `business_type` | `varchar(32)` | NOT NULL | `MANUAL_ADJUSTMENT/BUYIN/TOPUP_HOLD/TOPUP_APPLY/TOPUP_RELEASE/HAND_SETTLEMENT/EXIT/COMMISSION/REVERSAL` 等 |
| `idempotency_key` | `varchar(128)` | NOT NULL, UQ | 业务级幂等键；与网络 request 分离 |
| `parameter_digest` | `bytea` | NOT NULL | 规范化资产、账户、金额和业务引用摘要；同幂等键异参数拒绝 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 单事务只允许一种资产 |
| `status` | `varchar(16)` | NOT NULL | `PENDING/POSTED/FAILED`；冲正不修改原交易状态 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NULL | 后台或客户端操作结果 |
| `user_id` | `uuid` | FK → `app_user.id`, NULL | 主要玩家；多玩家结算可为空，明细在分录 |
| `user_game_id_snapshot` | `varchar(32)` | NULL | 发生时玩家公开 ID 快照 |
| `user_name_snapshot` | `varchar(80)` | NULL | 发生时玩家名称快照 |
| `club_id_snapshot` | `uuid` | FK → `club.id`, NULL | 发生时归属俱乐部 |
| `agent_id_snapshot` | `uuid` | FK → `agent.id`, NULL | 发生时直接代理 |
| `agent_name_snapshot` | `varchar(80)` | NULL | 发生时代理名，当前改名不覆盖 |
| `room_id` | `uuid` | FK → `room.id`, NULL | 房间 |
| `hand_id` | `uuid` | FK → `hand.id`, NULL | 手牌 |
| `seat_session_id` | `uuid` | FK → `seat_session.id`, NULL | 入座资金会话 |
| `rule_snapshot_id` | `uuid` | FK → `room_rule_snapshot.id`, NULL | 使用的规则快照 |
| `agreement_version_id` | `uuid` | FK → `agent_agreement_version.id`, NULL | 代理协议快照 |
| `reason_code` | `varchar(64)` | NOT NULL | 稳定原因码 |
| `reason_text` | `varchar(500)` | NULL | 可审计补充原因 |
| `original_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL | `REVERSAL` 必填；其他纠错可选引用原单 |
| `posted_at` | `timestamptz` | NULL | 成功过账时间 |
| `failed_at` | `timestamptz` | NULL | 明确失败时间 |
| `failure_code` | `varchar(64)` | NULL | 失败原因；UNKNOWN 属于操作状态，不写成账本失败 |

索引：`(user_id, created_at desc, id)`、`(room_id, created_at desc)`、`(hand_id)`、`(original_transaction_id)`、`(business_type, status, created_at)`。完整冲正采用 `UNIQUE(original_transaction_id) WHERE business_type='REVERSAL'`，防止同一原交易被重复完整冲正。

对外账单使用派生 `display_status`：底层 `PENDING/FAILED` 原样返回；POSTED 原交易不存在有效冲正时显示 `POSTED`，存在引用它的 POSTED `REVERSAL` 交易时显示 `REVERSED`，并同时返回 `reversal_transaction_id`、`reversed_at`。`REVERSED` 不是 `ledger_transaction.status` 的可写值。V1仅支持完整冲正；未来如增加部分冲正，须新增 `PARTIALLY_REVERSED` 口径而不能复用 `REVERSED`。

### 7.4 `ledger_entry` — 复式账本分录

不可变，V1 使用普通表并按 `posted_at` 建索引。每个 `POSTED` 事务至少两条分录，全部 `delta_amount` 合计必须为 0。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `transaction_id` | `uuid` | FK → `ledger_transaction.id`, NOT NULL | 事务头 |
| `line_no` | `smallint` | NOT NULL | 事务内顺序 |
| `account_id` | `uuid` | FK → `ledger_account.id`, NOT NULL | 账户 |
| `delta_amount` | `bigint` | NOT NULL, CK <>0 | 有符号最小单位；正数增加账户余额、负数减少账户余额 |
| `balance_before` | `bigint` | NOT NULL | 过账前账户余额 |
| `balance_after` | `bigint` | NOT NULL | 必须等于 `balance_before + delta_amount` |
| `posted_at` | `timestamptz` | NOT NULL | 过账时间；V1时间索引列，未来分区候选键 |
| `memo` | `varchar(255)` | NULL | 安全摘要，不写私牌或秘密 |

唯一约束：`(transaction_id, line_no)`；同一事务同一账户默认只允许一条净分录，建立 `UNIQUE(transaction_id, account_id)`。账户更新须按 `account_id` 稳定顺序加锁，防止死锁。

#### 7.4.1 统一过账契约

应用角色不得直接写 `ledger_transaction`、`ledger_entry` 或 `ledger_account.balance`，所有账务写入必须调用受限函数 `post_ledger_transaction`。函数与买入、补码、结算、离座或调款的业务终态在同一数据库事务内执行：

1. 按 `idempotency_key` 锁定或创建 PENDING 事务；同键同 `parameter_digest` 返回原结果，同键异摘要拒绝。
2. 校验至少两条分录、所有账户资产等于事务 `asset_id`、`sum(delta_amount)=0`。
3. 按 `account_id` 排序加行锁，计算 `balance_after`；`allow_negative=false` 的账户不得小于 0。
4. 插入不可变分录并同步更新账户余额，随后把事务改为 POSTED；任一步失败则整个业务事务回滚或明确记为 FAILED。
5. 冲正复制原交易的相反 `delta_amount` 生成新的 POSTED `REVERSAL` 事务；不得修改或删除原交易和原分录。

`wallet_balance_projection` 是可延迟重建的查询模型；`ledger_account.balance` 是由同一过账函数维护的当前余额缓存；`ledger_entry` 是最终资金事实。三者不一致时以完整分录重算并报警，不以页面投影反向覆盖账本。

### 7.5 `wallet_balance_projection` — 玩家资产读模型

该表用于列表和客户端展示，不是账务真相来源；必须可由账本重建。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 资产 |
| `available_amount` | `bigint` | NOT NULL | 可用 |
| `topup_frozen_amount` | `bigint` | NOT NULL | 未生效补码冻结 |
| `table_escrow_amount` | `bigint` | NOT NULL | 桌内托管；底池已包含在内，不重复相加 |
| `total_amount` | `bigint` | GENERATED/投影 | 三者之和 |
| `last_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NOT NULL | 投影水位 |
| `projected_at` | `timestamptz` | NOT NULL | 数据截止时间 |

唯一约束：`(user_id, asset_id)`。

### 7.6 `manual_adjustment` — 超管调款/补偿业务记录

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `adjustment_code` | `varchar(40)` | NOT NULL, UQ | 业务号 |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 资产 |
| `adjustment_type` | `varchar(32)` | NOT NULL | `TEST_GRANT/MANUAL_ADJUSTMENT/COMPENSATION/CORRECTION` |
| `delta_amount` | `bigint` | NOT NULL, CK <>0 | 调整账户的有符号最小单位；正数增加、负数减少，过账时生成对应零和清算分录 |
| `withdrawable` | `boolean` | NOT NULL, default false | 默认不可提 |
| `reason` | `varchar(500)` | NOT NULL | 必填原因 |
| `original_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL | 纠错时必填 |
| `operator_admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 仅超管 |
| `sensitive_authorization_id` | `uuid` | FK → `sensitive_authorization.id`, NOT NULL, UQ | 120 秒单次授权，只能绑定一条调款记录 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL, UQ | 一次业务操作只产生一条调款记录 |
| `ledger_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL, UQ | 成功后关联唯一账务事务 |

`sensitive_authorization` 建立 `UNIQUE(id, operation_id)`，本表建立复合外键 `(sensitive_authorization_id, operation_id) → sensitive_authorization(id, operation_id)`，禁止把其他操作的授权挪用于调款。应用角色不得直接写本表，只能调用 `execute_manual_adjustment`：函数锁定授权和相关账户，重验超管身份、会话、权限版本、参数摘要、120秒期限及未消费状态，在同一事务内消费授权、创建调款记录并调用统一过账函数；同操作号同参数返回原结果，同号异参数拒绝。

### 7.7 `revenue_note` — 收入明细追加备注

备注只追加，不修改历史费用、归因或金额。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `revenue_type` | `varchar(16)` | NOT NULL | `HAND_RAKE/EXIT_FEE` |
| `hand_fee_id` | `uuid` | FK → `hand_fee.id`, NULL | 抽水备注目标 |
| `seat_session_id` | `uuid` | FK → `seat_session.id`, NULL | 离座费备注目标 |
| `content` | `varchar(1000)` | NOT NULL | 备注正文 |
| `operator_admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 追加人 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL | 权限与审计操作 |
| `noted_at` | `timestamptz` | NOT NULL | 追加时间 |

约束：`hand_fee_id` 与 `seat_session_id` 恰有一个非空，并与 `revenue_type` 一致。

## 8. 房间、座位与资金会话域

### 8.1 `room` — 房间

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `room_code` | `varchar(32)` | NOT NULL, UQ | 对外房间 ID，不应可猜测 |
| `club_id` | `uuid` | FK → `club.id`, NOT NULL | 所属俱乐部 |
| `creator_user_id` | `uuid` | FK → `app_user.id`, NULL | 授权玩家创建时填写 |
| `creator_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 运营创建时填写 |
| `rule_template_version_id` | `uuid` | FK → `rule_template_version.id`, NOT NULL | 来源模板版本 |
| `rule_snapshot_id` | `uuid` | FK → `room_rule_snapshot.id`, NOT NULL, UQ | 房间冻结快照 |
| `status` | `varchar(24)` | NOT NULL | `SCHEDULED/WAITING/RUNNING/DRAINING/PAUSED_RECOVERY/CLOSED` |
| `scheduled_open_at` | `timestamptz` | NULL | 最远未来 7 天 |
| `opened_at` | `timestamptz` | NULL | 进入 WAITING 时间 |
| `first_hand_at` | `timestamptz` | NULL | 房间计时起点 |
| `ends_at` | `timestamptz` | NULL | 第一手开始后按时长确定 |
| `draining_at` | `timestamptz` | NULL | 停新业务时间 |
| `closed_at` | `timestamptz` | NULL | 完成清算时间 |
| `close_intent` | `boolean` | NOT NULL, default false | 恢复中仍要保留关桌意图 |
| `close_reason` | `varchar(64)` | NULL | `NATURAL_END/OPERATOR/CLUB_FROZEN/EMPTY_TIMEOUT/RECOVERY` 等 |
| `current_hand_id` | `uuid` | FK → `hand.id`, NULL | 当前手恢复入口 |
| `hand_count` | `integer` | NOT NULL, default 0 | 已创建手数；有效手统计另算 |
| `state_version` | `bigint` | NOT NULL, default 0 | 房间状态并发版本 |

约束：创建者玩家/后台二选一；SCHEDULED 必须有 `scheduled_open_at`。索引：`(club_id, status, created_at desc)`、`(status, scheduled_open_at)`、`(ends_at) WHERE status IN ('WAITING','RUNNING')`。

### 8.2 `room_rule_snapshot` — 房间不可变规则快照

从模板复制并应用允许修改项后写入；开房成功后禁止更新。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `template_version_id` | `uuid` | FK → `rule_template_version.id`, NOT NULL | 来源 |
| `template_version_label` | `varchar(32)` | NOT NULL | 玩家披露版本 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 资产 |
| `deck_mode` | `varchar(16)` | NOT NULL | `LONG/SHORT` |
| `betting` | `varchar(8)` | NOT NULL | `NLH` |
| `seat_count` | `smallint` | NOT NULL | 8/6 |
| `room_seconds` | `integer` | NOT NULL | 时长 |
| `sb_amount` | `bigint` | NOT NULL | SB |
| `bb_amount` | `bigint` | NOT NULL | BB |
| `buyin_min_amount` | `bigint` | NOT NULL | 买入下限 |
| `buyin_max_amount` | `bigint` | NOT NULL | 买入上限 |
| `ante_mode` | `varchar(16)` | NOT NULL | Ante 模式 |
| `ante_amount` | `bigint` | NOT NULL | Ante 金额 |
| `straddle_mode` | `varchar(24)` | NOT NULL | 抓头模式 |
| `start_players` | `smallint` | NOT NULL | 自动开局人数 |
| `allow_spectate` | `boolean` | NOT NULL | 是否允许观战 |
| `delay_mode` | `varchar(24)` | NOT NULL | 延迟模式 |
| `vpip_threshold` | `smallint` | NULL | 准入阈值 |
| `absence_mode` | `varchar(32)` | NOT NULL | 缺席策略 |
| `absence_deadline_mode` | `varchar(24)` | NOT NULL | 缺席截止模式 |
| `absence_seconds` | `integer` | NULL | 缺席秒数 |
| `action_seconds` | `smallint` | NOT NULL | 基础行动时间 |
| `reconnect_grace_seconds` | `smallint` | NOT NULL | 每手离线宽限 |
| `rake_rate` | `numeric(9,6)` | NOT NULL | 抽水比例快照 |
| `rake_cap_amount` | `bigint` | NOT NULL | 封顶金额快照 |
| `fee_version_label` | `varchar(32)` | NOT NULL | 费用披露版本 |
| `exit_profit_rate` | `numeric(9,6)` | NOT NULL | 离座盈利费率 |
| `exit_fee_version_label` | `varchar(32)` | NOT NULL | 离座费版本 |
| `editable_values` | `jsonb` | NOT NULL, default `{}` | 创建者实际修改且在白名单内的字段及来源值 |
| `content_digest` | `bytea` | NOT NULL, IDX | 完整规则摘要；相同模板和参数可以创建多个独立房间快照 |

`content_digest` 仅用于完整性校验和普通索引，不得建立全局唯一约束。每次开房仍创建独立不可变快照，并由 `room.rule_snapshot_id` 一对一引用，避免共享对象的生命周期和审计耦合。

同源约束：`room_rule_snapshot` 建立 `UNIQUE(id, template_version_id)`，`room` 建立复合外键 `(rule_snapshot_id, rule_template_version_id) → room_rule_snapshot(id, template_version_id)`；`room` 再建立 `UNIQUE(id, rule_snapshot_id)`，`hand` 以 `(room_id, rule_snapshot_id) → room(id, rule_snapshot_id)` 保证手牌只能使用所属房间的冻结快照。上述复合外键在循环依赖收口迁移中后置创建。

### 8.3 `room_state_snapshot` — 游戏引擎恢复快照

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间 |
| `state_version` | `bigint` | NOT NULL | 与动作事件版本连续 |
| `hand_id` | `uuid` | FK → `hand.id`, NULL | 当前手 |
| `snapshot_json` | `jsonb` | NOT NULL | 可恢复的非账务引擎状态；不得作为余额或结算唯一事实 |
| `snapshot_digest` | `bytea` | NOT NULL | 完整性摘要 |
| `last_event_id` | `uuid` | FK → `hand_event.id`, NULL | 投影水位 |
| `captured_at` | `timestamptz` | NOT NULL | 快照时间 |

唯一约束：`(room_id, state_version)`；该表是周期检查点，不要求每个房间版本都有完整快照。恢复时读取同一房间中 `state_version <= room.state_version` 的最大版本，验证摘要和 `last_event_id` 后重放后续事件至当前版本；不得把 `room.state_version` 建成要求精确命中快照的外键。清理旧快照时每个活动房间至少保留一个已验证检查点。

### 8.4 `room_seat_occupancy` — 统一座位占用仲裁

每个房间的每个物理座位预创建一行。预约、买入、取消、过期和离座都必须先 `SELECT ... FOR UPDATE` 锁定该行；应用角色不得绕过受限座位函数直接改变占用状态。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间 |
| `seat_no` | `smallint` | NOT NULL, CK >=0 | 物理座位号，必须小于规则快照席数 |
| `status` | `varchar(16)` | NOT NULL | `VACANT/RESERVED/OCCUPIED` |
| `user_id` | `uuid` | FK → `app_user.id`, NULL | RESERVED/OCCUPIED 时必填 |
| `reservation_id` | `uuid` | FK → `seat_reservation.id`, NULL | RESERVED 时唯一非空业务引用 |
| `seat_session_id` | `uuid` | FK → `seat_session.id`, NULL | OCCUPIED 时唯一非空业务引用 |
| `expires_at` | `timestamptz` | NULL | RESERVED 的服务端期限，其他状态为空 |
| `changed_at` | `timestamptz` | NOT NULL | 最近一次合法状态变化时间 |

唯一约束：`(room_id, seat_no)`。检查约束要求：VACANT 时三个引用及 `expires_at` 均为空；RESERVED 时只有 `reservation_id/user_id/expires_at` 非空；OCCUPIED 时只有 `seat_session_id/user_id` 非空。由于占用表和业务表互相引用，先创建表结构，再在 Flyway 的跨域约束阶段增加可延迟外键。

### 8.5 `seat_reservation` — 15 秒座位预约

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `reservation_code` | `varchar(40)` | NOT NULL, UQ | 客户端恢复用业务号 |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间 |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `seat_no` | `smallint` | NOT NULL, CK >=0 | 物理座位号，范围由快照席数决定 |
| `occupancy_id` | `uuid` | FK → `room_seat_occupancy.id`, NOT NULL | 竞争的统一座位行 |
| `status` | `varchar(24)` | NOT NULL | `ACTIVE/CONSUMED/EXPIRED/CANCELLED` |
| `expires_at` | `timestamptz` | NOT NULL | 服务端截止时间 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL, UQ | 预约请求；一次操作只生成一条预约 |

约束：每房间座位最多一个 ACTIVE、每用户每房间最多一个 ACTIVE 的部分唯一索引；预约不冻结资金。上述索引用于查询和历史防重，真正的预约/入座互斥由 `room_seat_occupancy` 主键行锁保证。

### 8.6 `seat_session` — 入座资金会话

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `session_code` | `varchar(40)` | NOT NULL, UQ | 客户端/账单关联 `seat_session_id` |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间 |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `seat_no` | `smallint` | NOT NULL | 当前物理座位 |
| `occupancy_id` | `uuid` | FK → `room_seat_occupancy.id`, NOT NULL | 当前统一座位行 |
| `status` | `varchar(24)` | NOT NULL | `WAIT_NEXT_HAND/PLAYING/AUTO_PLAY/LEAVE_PENDING/ZERO_STACK_HOLD/SETTLING/CLOSED` |
| `membership_id_at_join` | `uuid` | FK → `club_membership.id`, NOT NULL | 入座时归属 |
| `agent_id_snapshot` | `uuid` | FK → `agent.id`, NULL | 会话展示快照；每手仍单独冻结协议 |
| `buyin_amount` | `bigint` | NOT NULL, CK >0 | 初始买入本金 |
| `applied_topup_amount` | `bigint` | NOT NULL, default 0 | 已生效补码本金累计 |
| `stack_amount` | `bigint` | NOT NULL, CK >=0 | 当前桌内可行动筹码投影；账本托管仍为资金真相 |
| `started_at` | `timestamptz` | NOT NULL | 买入明确成功时间 |
| `first_hand_at` | `timestamptz` | NULL | 第一手参与时间 |
| `last_hand_id` | `uuid` | FK → `hand.id`, NULL | 最近参与手 |
| `leave_requested_at` | `timestamptz` | NULL | 主动/超时离座申请 |
| `leave_reason` | `varchar(64)` | NULL | 主动、超时、自然到期、运营、故障等 |
| `zero_stack_deadline` | `timestamptz` | NULL | 零筹码 60 秒截止 |
| `ended_at` | `timestamptz` | NULL | 清算完成时间 |
| `returned_amount` | `bigint` | NULL | 返回可用余额 |
| `exit_fee_amount` | `bigint` | NULL | 离座费 |
| `net_result_amount` | `bigint` | NULL | 会话净收益，含离座费 |
| `exit_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL, UQ | 退出幂等账 |

约束：一个玩家最多一条活动真人 `seat_session`；同一房间座位最多一条活动会话。旧俱乐部临时访问权由此活动会话表达，关闭后失效。活动会话必须与占用行的 `seat_session_id/user_id/room_id/seat_no` 一致。

#### 8.6.1 预约、买入与离座事务

预约函数锁定 `(room_id, seat_no)` 占用行，仅允许 `VACANT → RESERVED`；过期或取消仅在占用行仍指向同一预约时执行 `RESERVED → VACANT`。买入在一个事务内完成：

1. 锁定玩家活动会话约束、座位占用行和相关账本账户；占用行必须仍指向请求 reservation_id、属于该玩家且为 RESERVED，并在获得锁后以 clock_timestamp() 判断 expires_at > 当前时刻；等于截止即过期。禁止从 VACANT 直接买入。
2. 调用 `post_ledger_transaction` 完成可用余额到桌内托管的零和转移。
3. 创建 `seat_session`，把预约改为 CONSUMED，并将占用行原子改为 OCCUPIED。
4. 任一步失败全部回滚，不允许出现已扣款无座位或有座位无托管资金。

买入请求必须带 reservation_id 和 request_id。先查询同键已提交结果再判断预约：成功响应丢失即使预约后来过期也返回原成功。首次提交预约已过期则同事务把仍指向原预约的占用行释放、预约标 EXPIRED、business_operation 保存 RESERVATION_EXPIRED，提交该拒绝结果；不得先抛异常导致清理与拒绝记录回滚。拒绝不建 seat_session、不扣款、不隐式续期。客户端重新预约并用新 request_id 提交；新键同座但已 OCCUPIED 返回 SEAT_TAKEN。锁后验有效并开始本次原子消费，即使事务提交越过预约截止仍可成功，因为座位锁已仲裁；另一玩家不得同时抢得该座。

离座先停止新手准入并完成资金清算，再在同一事务中关闭 `seat_session`、把占用行改回 VACANT。换座按 `(room_id, seat_no)` 排序锁定两行，避免双向换座死锁。

### 8.7 `seat_move_request` — 换座请求

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `seat_session_id` | `uuid` | FK → `seat_session.id`, NOT NULL | 不新开资金会话 |
| `from_seat_no` | `smallint` | NOT NULL | 原座位 |
| `to_seat_no` | `smallint` | NOT NULL | 目标座位 |
| `status` | `varchar(24)` | NOT NULL | `PENDING/APPLIED/CANCELLED/FAILED` |
| `wait_until_bb_paid` | `boolean` | NOT NULL | 防止逃避下一次 BB |
| `requested_at` | `timestamptz` | NOT NULL | 请求时间 |
| `applied_at` | `timestamptz` | NULL | 手间实际生效时间 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL, UQ | 幂等操作；一次操作只生成一条换座请求 |

每会话最多一条 PENDING；应用时按固定顺序同时锁定源、目标 `room_seat_occupancy` 行，两个状态在同一事务内切换。

### 8.8 `topup_order` — 补码冻结、应用与退款

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `topup_code` | `varchar(40)` | NOT NULL, UQ | 补码业务号 |
| `seat_session_id` | `uuid` | FK → `seat_session.id`, NOT NULL | 入座会话 |
| `request_id` | `uuid` | NOT NULL, UQ | 客户端幂等请求号 |
| `requested_amount` | `bigint` | NOT NULL, CK >0 | 申请并冻结金额 |
| `stack_at_request` | `bigint` | NOT NULL, CK >=0 | 申请时剩余可行动筹码 C |
| `status` | `varchar(24)` | NOT NULL | `PENDING/APPLIED/CANCELLED/REFUNDED/FAILED` |
| `hold_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NOT NULL, UQ | 可用→冻结 |
| `applied_amount` | `bigint` | NULL | 手间实际进入托管的 X |
| `refunded_amount` | `bigint` | NULL | 退回 A-X 或全额退款 |
| `resolution_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL, UQ | 应用/取消竞争的唯一终态账 |
| `resolved_at` | `timestamptz` | NULL | 终态时间 |
| `failure_code` | `varchar(64)` | NULL | `TOPUP_MIN_REQUIRED` 等 |

约束：每 `seat_session` 最多一条 `PENDING` 的部分唯一索引；取消和应用必须在同一数据库事务内竞争。

### 8.9 `room_state_event` — 房间状态轨迹

不可变。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间 |
| `seq_no` | `bigint` | NOT NULL | 房间内连续序号 |
| `from_status` | `varchar(24)` | NULL | 初始创建为空 |
| `to_status` | `varchar(24)` | NOT NULL | 新状态 |
| `reason_code` | `varchar(64)` | NOT NULL | 状态原因 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NULL | 操作来源 |
| `occurred_at` | `timestamptz` | NOT NULL | 生效时间 |
| `details` | `jsonb` | NOT NULL, default `{}` | 只存非敏感补充信息 |

唯一约束：`(room_id, seq_no)`。

## 9. 手牌、动作、底池与结算域

### 9.1 `hand` — 手牌主记录

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `hand_code` | `varchar(40)` | NOT NULL, UQ | 全局唯一 hand_id |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间 |
| `hand_no` | `integer` | NOT NULL | 房间内递增手号 |
| `rule_snapshot_id` | `uuid` | FK → `room_rule_snapshot.id`, NOT NULL | 冻结规则 |
| `status` | `varchar(24)` | NOT NULL | `PREPARING/STARTED/SETTLING/SETTLED/VOID/RECOVERY_REQUIRED` |
| `street` | `varchar(16)` | NOT NULL | `PREFLOP/FLOP/TURN/RIVER/SHOWDOWN/COMPLETE` |
| `state_version` | `bigint` | NOT NULL, default 0 | 动作并发版本 |
| `button_seat_no` | `smallint` | NOT NULL | 庄位 |
| `sb_seat_no` | `smallint` | NOT NULL | 小盲位 |
| `bb_seat_no` | `smallint` | NOT NULL | 大盲位 |
| `straddle_seat_no` | `smallint` | NULL | 有效抓头位 |
| `current_actor_seat_no` | `smallint` | NULL | 当前行动座位 |
| `current_bet_amount` | `bigint` | NOT NULL, default 0 | 本街最高有效下注 H |
| `last_full_raise_delta` | `bigint` | NOT NULL | 最近完整差额 L |
| `action_deadline` | `timestamptz` | NULL | 当前阶段截止 |
| `deal_source` | `varchar(24)` | NOT NULL | `RANDOM/SCRIPTED_TEST` |
| `test_deal_run_id` | `uuid` | FK → `test_deal_run.id`, NULL | 预设测试手关联 |
| `deck_commitment` | `bytea` | NULL, SECRET | 恢复完整性摘要；未接入公平证明时不对外宣称验证 |
| `started_at` | `timestamptz` | NULL | 强制款与开手原子提交时间 |
| `settled_at` | `timestamptz` | NULL | 首次成功结算时间；代理业务日依据 |
| `voided_at` | `timestamptz` | NULL | 作废时间 |
| `settlement_id` | `uuid` | FK → `hand_settlement.id`, NULL, UQ | 结算记录 |

唯一约束：`(room_id, hand_no)`。索引：`(status, started_at)`、`(room_id, started_at desc)`、`(settled_at)`。

### 9.2 `hand_player` — 每手玩家状态与统计事实

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL | 手牌 |
| `seat_session_id` | `uuid` | FK → `seat_session.id`, NOT NULL | 资金会话 |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `seat_no` | `smallint` | NOT NULL | 本手固定物理座位 |
| `display_name_snapshot` | `varchar(80)` | NOT NULL | 回放历史昵称 |
| `club_id_snapshot` | `uuid` | FK → `club.id`, NOT NULL | 开手归属快照 |
| `agent_id_snapshot` | `uuid` | FK → `agent.id`, NULL | 开手代理快照 |
| `agreement_version_id` | `uuid` | FK → `agent_agreement_version.id`, NULL | 开手协议快照；缺失时归因标 CONFIG_ERROR |
| `starting_stack_amount` | `bigint` | NOT NULL | 开手筹码 |
| `ending_stack_amount` | `bigint` | NULL | 正常结算/作废后筹码 |
| `total_contribution_amount` | `bigint` | NOT NULL, default 0 | 本手全部实际投入 |
| `current_street_contribution` | `bigint` | NOT NULL, default 0 | 当前街有效投入 |
| `unmatched_return_amount` | `bigint` | NOT NULL, default 0 | 无人匹配返还，不抽水 |
| `award_amount` | `bigint` | NOT NULL, default 0 | 各池派奖合计 |
| `net_amount` | `bigint` | NULL | 派奖+返还−投入 |
| `folded` | `boolean` | NOT NULL, default false | 是否弃牌 |
| `all_in` | `boolean` | NOT NULL, default false | 是否全下 |
| `reached_showdown` | `boolean` | NOT NULL, default false | 是否进入摊牌 |
| `cards_revealed` | `boolean` | NOT NULL, default false | 是否依规则公开底牌 |
| `mucked` | `boolean` | NOT NULL, default false | 是否 Muck |
| `remaining_stack_amount` | `bigint` | NOT NULL, CK >=0 | 当前可行动桌内筹码，不含已投入底池 |
| `has_acted_this_street` | `boolean` | NOT NULL, default false | 本街是否已主动响应 |
| `last_response_price` | `bigint` | NOT NULL, default 0 | 该玩家上次响应的最高有效下注 |
| `reopen_threshold` | `bigint` | NOT NULL, default 0 | 再次获得加注权所需的完整累计增量 |
| `connection_state` | `varchar(16)` | NOT NULL | `ONLINE/OFFLINE/AUTO` |
| `timer_phase` | `varchar(16)` | NOT NULL | `BASE/BANK/GRACE/AUTO` |
| `base_deadline` | `timestamptz` | NULL | 本轮基础时间截止 |
| `absence_deadline` | `timestamptz` | NULL | B 模式缺席截止；A 模式为空 |
| `vpip_flag` | `boolean` | NOT NULL, default false | 严格口径主动入池 |
| `pfr_flag` | `boolean` | NOT NULL, default false | 翻前提高最高下注 |
| `won_competed_pot` | `boolean` | NOT NULL, default false | 获得至少一个有竞争池份额 |
| `timebank_before_ms` | `integer` | NOT NULL | 行动前账号时间银行快照 |
| `timebank_after_ms` | `integer` | NULL | 本手结束后值 |
| `disconnect_grace_remaining_ms` | `integer` | NOT NULL | 本手共享离线预算 |

唯一约束：`(hand_id, user_id)`、`(hand_id, seat_no)`。

### 9.3 `hand_card` — 牌序、底牌、公共牌与烧牌

该表为 SECRET。HOLE/DECK/BURN 使用应用层信封加密，密钥由 KMS/Vault 管理；普通查询视图只暴露合法公开字段。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL | 手牌 |
| `deck_position` | `smallint` | NOT NULL | 固定完整牌序位置 |
| `card_role` | `varchar(16)` | NOT NULL | `HOLE/BOARD/BURN/REMAINDER` |
| `street` | `varchar(16)` | NULL | 公共牌/烧牌所属街 |
| `owner_user_id` | `uuid` | FK → `app_user.id`, NULL | 底牌持有人 |
| `owner_card_no` | `smallint` | NULL | 玩家第 1/2 张底牌 |
| `public_code` | `char(2)` | NULL, CK 标准牌码 | 已公开公共牌或依法公开底牌；否则为空 |
| `card_ciphertext` | `bytea` | NOT NULL, SECRET | 牌码密文 |
| `key_version` | `varchar(32)` | NOT NULL, SECRET | 加密密钥版本，不存密钥 |
| `revealed_at` | `timestamptz` | NULL | 实际公开时间 |
| `visibility` | `varchar(24)` | NOT NULL | `SERVER_ONLY/OWNER_ONLY/PUBLIC/MUCKED` |

唯一约束：`(hand_id, deck_position)`、`(hand_id, owner_user_id, owner_card_no) WHERE owner_user_id IS NOT NULL`。长牌牌码 52 张唯一，短牌只允许 6–A。

### 9.4 `hand_action_request` — 动作请求与幂等结果

每个玩家、超时或系统动作请求无论接受或拒绝都保存终态结果，防止旧版本、非法加注等拒绝请求在状态变化后被重新解释。应用角色不得直接写入，只能调用 `submit_hand_action`。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `action_code` | `varchar(48)` | NOT NULL, UQ | 全局动作请求幂等键；PLAYER 使用客户端 action_id，TIMEOUT/SYSTEM 由服务端确定性生成 |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL | 请求所针对的手牌 |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 请求玩家 |
| `seat_session_id` | `uuid` | FK → `seat_session.id`, NOT NULL | 请求时的入座会话 |
| `requested_state_version` | `bigint` | NOT NULL | 请求所依据的权威状态版本 |
| `action_type` | `varchar(16)` | NOT NULL | 请求动作 |
| `source` | `varchar(16)` | NOT NULL | `PLAYER/TIMEOUT/SYSTEM`；服务端动作也必须先形成请求事实 |
| `target_amount` | `bigint` | NOT NULL | 请求的本街目标总额 |
| `parameter_digest` | `bytea` | NOT NULL | 规范化手牌、玩家、版本、动作和金额摘要 |
| `result` | `varchar(16)` | NOT NULL | `PENDING/ACCEPTED/REJECTED` |
| `error_category` | `varchar(32)` | NULL | 前端稳定错误分类；接受时为空 |
| `error_code` | `varchar(64)` | NULL | `STALE_ACTION/ILLEGAL_RAISE/...`；接受时为空 |
| `result_state_version` | `bigint` | NULL | 接受后的版本或拒绝时服务端当前版本 |
| `response_summary` | `jsonb` | NULL | 裁剪后的合法动作、跟注成本、目标范围和截止时间；不得含未公开牌 |
| `requested_at` | `timestamptz` | NOT NULL | 首次收到时间 |
| `resolved_at` | `timestamptz` | NULL | 明确接受或拒绝时间 |

`submit_hand_action` 先按 `action_code` 锁定或创建 PENDING 行；同 ID 同 `parameter_digest` 返回已存结果，同 ID 异摘要返回 `IDEMPOTENCY_CONFLICT`。超时和系统动作以 `hand_id + state_version + user_id + source` 规范化后生成稳定服务端请求号，同样经过本函数。可预期的业务拒绝必须写成 REJECTED 并提交，不能通过抛异常回滚幂等证据；接受时创建 `hand_action`、`hand_event`、更新手牌状态和请求终态必须同一事务提交。

### 9.5 `hand_action` — 已接受的结构化动作

不可变。V1 使用普通表并按 `accepted_at` 建索引；请求幂等键保存在 `hand_action_request`，本表保证 `(hand_id, seq_no)` 和一个请求至多一个动作事实。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `action_request_id` | `uuid` | FK → `hand_action_request.id`, NOT NULL, UQ | 已接受的原请求；拒绝请求没有动作事实 |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL | 手牌 |
| `seq_no` | `integer` | NOT NULL | 手牌内全局动作序号 |
| `state_version_before` | `bigint` | NOT NULL | 校验旧版本 |
| `state_version_after` | `bigint` | NOT NULL | 接受后的新版本 |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 行动玩家 |
| `seat_no` | `smallint` | NOT NULL | 座位快照 |
| `street` | `varchar(16)` | NOT NULL | 街道 |
| `action_type` | `varchar(16)` | NOT NULL | `FOLD/CHECK/CALL/BET/RAISE/ALL_IN/AUTO_CHECK/AUTO_FOLD` |
| `target_amount` | `bigint` | NOT NULL | 本街目标总额 T；弃牌/过牌为 0 |
| `delta_amount` | `bigint` | NOT NULL | 本次实际扣除 T-c |
| `to_call_before` | `bigint` | NOT NULL | 动作前跟注成本 C |
| `pot_before` | `bigint` | NOT NULL | 动作前总池 |
| `full_raise_delta_before` | `bigint` | NOT NULL | 动作前 L |
| `reopened_betting` | `boolean` | NOT NULL | 此动作是否构成完整增量并重开 |
| `is_short_all_in` | `boolean` | NOT NULL | 是否短全下 |
| `source` | `varchar(16)` | NOT NULL | `PLAYER/TIMEOUT/SYSTEM` |
| `accepted_at` | `timestamptz` | NOT NULL | 服务端接收且提交时间 |

唯一约束：`(hand_id, seq_no)`；`action_request_id` 唯一保证一个接受请求只产生一个动作事实。重复 action_id 由 `hand_action_request` 返回原结果，不再次执行。

### 9.6 `hand_event` — 可重放领域事件

不可变。V1 使用普通表并按 `occurred_at` 建索引；与 `hand_action` 的区别是它还记录发牌、换街、强制款、退款、摊牌和结算阶段。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL | 手牌 |
| `seq_no` | `bigint` | NOT NULL | 严格递增 |
| `event_type` | `varchar(48)` | NOT NULL | `HAND_STARTED/CARD_DEALT/FORCED_BET_POSTED/ACTION_ACCEPTED/STREET_CHANGED/POT_BUILT/SETTLED/VOIDED` 等 |
| `state_version` | `bigint` | NOT NULL | 事件后版本 |
| `payload` | `jsonb` | NOT NULL | 结构化事件；不得包含明文未公开牌、凭据或密钥 |
| `occurred_at` | `timestamptz` | NOT NULL | 权威时间 |
| `request_id` | `uuid` | NULL | 来源请求 |
| `payload_digest` | `bytea` | NOT NULL | 防篡改与重放校验 |

唯一约束：`(hand_id, seq_no)`。

### 9.7 `hand_pot` — 主池、边池和公共 Ante 池

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL | 手牌 |
| `pot_no` | `smallint` | NOT NULL | 从 0 递增，决定同余分配顺序 |
| `pot_type` | `varchar(16)` | NOT NULL | `MAIN/SIDE/BB_ANTE_COMMON` |
| `layer_from_amount` | `bigint` | NOT NULL | 分层下界 |
| `layer_to_amount` | `bigint` | NOT NULL | 分层上界 |
| `gross_amount` | `bigint` | NOT NULL, CK >=0 | 抽水前池额 G 的组成 |
| `rake_amount` | `bigint` | NOT NULL, CK >=0 | 分摊到该池的费用 |
| `net_amount` | `bigint` | NOT NULL, CK >=0 | 可派奖净额 |
| `is_competed` | `boolean` | NOT NULL | 是否存在竞争；无人匹配部分不建池而走返还 |

唯一约束：`(hand_id, pot_no)`；`gross_amount = rake_amount + net_amount`。

### 9.8 `hand_pot_contribution` — 池贡献与获池资格

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `pot_id` | `uuid` | FK → `hand_pot.id`, NOT NULL | 底池 |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `contribution_amount` | `bigint` | NOT NULL, CK >0 | 该池实际贡献；含弃牌者 |
| `eligible_to_win` | `boolean` | NOT NULL | 未弃牌且达到该层才可获池 |
| `folded` | `boolean` | NOT NULL | 快照 |
| `attribution_base_exact` | `numeric(30,12)` | NOT NULL | 抽水逐池贡献归因基数 |

唯一约束：`(pot_id, user_id)`。

### 9.9 `hand_pot_award` — 每池派奖与尾分

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `pot_id` | `uuid` | FK → `hand_pot.id`, NOT NULL | 底池 |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 获奖玩家 |
| `base_share_amount` | `bigint` | NOT NULL | 平分基础额 |
| `odd_chip_amount` | `bigint` | NOT NULL, CK 0 或最小单位 | 从庄左顺时针产生的尾分 |
| `award_amount` | `bigint` | NOT NULL | 合计派奖 |
| `hand_category` | `varchar(24)` | NULL | `HIGH_CARD/.../STRAIGHT_FLUSH`；弃牌获胜可空 |
| `rank_vector` | `smallint[]` | NULL | 同牌型比较向量，不使用花色破平 |

唯一约束：`(pot_id, user_id)`；每池 award 合计必须等于 `hand_pot.net_amount`。

### 9.10 `hand_fee` — 单手抽水事实

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL, UQ | 一手一条抽水总额 |
| `fee_template_version_id` | `uuid` | FK → `fee_template_version.id`, NOT NULL | 来源版本 |
| `gross_competed_pot_amount` | `bigint` | NOT NULL | 全部有竞争池之和 G |
| `rate_snapshot` | `numeric(9,6)` | NOT NULL | 费率 |
| `cap_snapshot_amount` | `bigint` | NOT NULL | 全手 cap |
| `rake_amount` | `bigint` | NOT NULL | `floor(min(G*rate, cap))` |
| `flop_dealt` | `boolean` | NOT NULL | false 时当前模板费用 0 |
| `ledger_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL, UQ | 结算账务事务 |
| `reversed_by_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL | VOID 冲正 |

### 9.11 `hand_settlement` — 原子结算结果

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `settlement_code` | `varchar(40)` | NOT NULL, UQ | 重试返回同一 settlement_id |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL, UQ | 一手一个结算 |
| `status` | `varchar(24)` | NOT NULL | `PENDING/POSTED/REVERSED/FAILED` |
| `total_contribution_amount` | `bigint` | NOT NULL | 全部投入 |
| `total_unmatched_return_amount` | `bigint` | NOT NULL | 无人匹配返还 |
| `total_rake_amount` | `bigint` | NOT NULL | 抽水 |
| `total_award_amount` | `bigint` | NOT NULL | 派奖 |
| `ledger_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL, UQ | 结算账和终态同事务提交 |
| `posted_at` | `timestamptz` | NULL | 首次成功时间，等于 `hand.settled_at` |
| `result_digest` | `bytea` | NOT NULL | 规则、池、赢家和金额摘要 |
| `failure_code` | `varchar(64)` | NULL | 守恒失败等明确错误 |

守恒：`total_contribution = total_unmatched_return + total_rake + total_award`。广播失败不得重做结算。

### 9.12 `player_hand_stat` — 玩家单手统计读模型

由结算事件生成，可重建。V1 使用普通表并按 `settled_at` 建索引。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL | 手牌 |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间 |
| `seat_session_id` | `uuid` | FK → `seat_session.id`, NOT NULL | 会话 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 资产 |
| `deck_mode` | `varchar(16)` | NOT NULL | 长/短牌分开统计 |
| `settled_at` | `timestamptz` | NOT NULL | 时间筛选依据 |
| `valid_hand` | `boolean` | NOT NULL | 已发底牌且正常 SETTLED |
| `vpip_flag` | `boolean` | NOT NULL | VPIP 分子 |
| `pfr_flag` | `boolean` | NOT NULL | PFR 分子 |
| `showdown_flag` | `boolean` | NOT NULL | W$SD 分母 |
| `showdown_won_flag` | `boolean` | NOT NULL | 获任一池份额 |
| `won_pot_flag` | `boolean` | NOT NULL | 获池率分子 |
| `net_amount` | `bigint` | NOT NULL | 单手净收益，不再减一次归因抽水 |
| `bb_amount` | `bigint` | NOT NULL | bb/100 分母换算快照 |
| `deal_source` | `varchar(24)` | NOT NULL | SCRIPTED_TEST 不混入正式指标 |

唯一约束：`(user_id, hand_id)`。

## 10. 代理归因与日账域

### 10.1 `commission_attribution` — 逐手逐池代理归因

不可变；玩家结算不得因计提异常而回滚。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `event_code` | `varchar(48)` | NOT NULL, UQ | 计提事件唯一号 |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL | 手牌 |
| `pot_id` | `uuid` | FK → `hand_pot.id`, NOT NULL | 底池 |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 贡献玩家 |
| `agent_id` | `uuid` | FK → `agent.id`, NULL | 空表示平台 |
| `agreement_version_id` | `uuid` | FK → `agent_agreement_version.id`, NULL | 开手协议快照 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 资产 |
| `business_date` | `date` | NOT NULL | 首次 settled_at 转 Asia/Shanghai |
| `pot_rake_amount` | `bigint` | NOT NULL | 该池实收抽水 |
| `player_contribution_amount` | `bigint` | NOT NULL | 玩家该池贡献 |
| `pot_contribution_amount` | `bigint` | NOT NULL | 全池贡献 |
| `attribution_base_exact` | `numeric(30,12)` | NOT NULL | `pot_rake * player/pot` |
| `rate_snapshot` | `numeric(9,6)` | NULL | 协议费率 |
| `commission_exact` | `numeric(30,12)` | NULL | 未取分的佣金 |
| `status` | `varchar(24)` | NOT NULL | `VALID/CONFIG_ERROR/REVERSED` |
| `original_event_id` | `uuid` | FK → `commission_attribution.id`, NULL | 冲正事件引用 |
| `occurred_at` | `timestamptz` | NOT NULL | 投影写入时间；不改变业务日 |

唯一约束拆分为：`UNIQUE(hand_id, pot_id, user_id) WHERE original_event_id IS NULL`，防止可空列使原始归因重复；`UNIQUE(original_event_id) WHERE original_event_id IS NOT NULL`，保证一个原事件最多冲正一次。检查约束要求 `VALID/CONFIG_ERROR` 的 `original_event_id` 为空，`REVERSED` 必须非空。

应用角色不得直接写入，统一调用 `post_commission_attribution`。函数按业务键或原事件加锁，校验手牌、池、玩家、资产和金额一致；冲正必须引用尚未冲正的原始事件并写入相反的归因/佣金数值。重复同一原始事件或重复冲正返回原结果，不新增第二条记录。

### 10.2 `commission_daily_statement` — 代理业务日日账

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `statement_code` | `varchar(40)` | NOT NULL, UQ | 日账号 |
| `agent_id` | `uuid` | FK → `agent.id`, NOT NULL | 代理 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 资产 |
| `business_date` | `date` | NOT NULL | 业务日 |
| `version_no` | `integer` | NOT NULL | 重算版本 |
| `status` | `varchar(24)` | NOT NULL | `FINAL/PENDING_RECALC/CONFIG_ERROR` |
| `attribution_base_exact` | `numeric(30,12)` | NOT NULL | 高精度归因基数净额 |
| `commission_target_exact` | `numeric(30,12)` | NOT NULL | 高精度目标应计 |
| `target_accrued_amount` | `bigint` | NOT NULL | 向下取资产精度后的目标 |
| `booked_net_amount` | `bigint` | NOT NULL | 截至该版本已记净应计 |
| `test_marked_paid_amount` | `bigint` | NOT NULL, default 0 | 仅 TEST 标记，不代表真实付款 |
| `pending_difference_amount` | `bigint` | NOT NULL | 目标应计−测试标记等待核对差额 |
| `data_cutoff_at` | `timestamptz` | NOT NULL | 数据截止时间 |
| `calculated_at` | `timestamptz` | NOT NULL | 计算时间 |

唯一约束：`(agent_id, asset_id, business_date, version_no)`。不保存 `is_current`，也不建立无法稳定表达“最高版本”的部分索引；`v_commission_current_statement` 按每个代理、资产、业务日的最高 `version_no` 返回当前版本。生成新版本时锁定已存在的最高版本行并依赖唯一约束串行化；首次版本并发冲突时读取胜出记录后按幂等规则返回或重算。

### 10.3 `commission_statement_adjustment` — 日账版本调整轨迹

不可变。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `statement_id` | `uuid` | FK → `commission_daily_statement.id`, NOT NULL | 日账版本 |
| `adjustment_code` | `varchar(48)` | NOT NULL, UQ | 调整业务号 |
| `adjustment_amount` | `bigint` | NOT NULL | 可正可负；新目标−已记净额 |
| `reason` | `varchar(32)` | NOT NULL | `INITIAL/LATE_EVENT/REVERSAL/CORRECTION` |
| `source_event_id` | `uuid` | FK → `commission_attribution.id`, NULL | 导致重算的事件 |
| `ledger_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL, UQ | 平台收入内划分账 |
| `booked_at` | `timestamptz` | NOT NULL | 实际记账时间，与业务日分列 |

### 10.4 `commission_test_payment_mark` — TEST 支付标记

不可变，不调用真实支付。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `statement_id` | `uuid` | FK → `commission_daily_statement.id`, NOT NULL | TEST 日账 |
| `amount` | `bigint` | NOT NULL, CK >0 | 标记金额 |
| `operator_admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 仅超管 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL, UQ | 幂等操作；一次操作只产生一条TEST标记 |
| `marked_at` | `timestamptz` | NOT NULL | 标记时间 |
| `reason` | `varchar(500)` | NOT NULL | 原因 |

## 11. 聊天、举报与客服域

### 11.1 `chat_message` — 牌桌消息

V1 使用普通表并按 `sent_at` 建索引，默认保留 30 天；保留全局消息号和客户端幂等约束。未来分区须先引入非分区消息 ID 注册表。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `message_code` | `varchar(48)` | NOT NULL, UQ | 服务端 message_id |
| `client_message_id` | `varchar(64)` | NULL | USER/ADMIN 必填的发送端幂等 ID；SYSTEM 可空 |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间 |
| `sender_type` | `varchar(16)` | NOT NULL | `USER/ADMIN/SYSTEM` |
| `sender_user_id` | `uuid` | FK → `app_user.id`, NULL | 玩家消息 |
| `sender_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 客服巡检消息 |
| `system_event_code` | `varchar(64)` | NULL | SYSTEM 必填的来源事件幂等键 |
| `sender_public_id_snapshot` | `varchar(32)` | NOT NULL | 对外身份快照 |
| `message_type` | `varchar(16)` | NOT NULL | `TEXT/QUICK/EMOJI/SYSTEM` |
| `content` | `varchar(500)` | NOT NULL | 文字 1–200 可见字符；系统消息可更长，渲染必须转义 |
| `status` | `varchar(16)` | NOT NULL | `SENT/REJECTED/REDACTED` |
| `sent_at` | `timestamptz` | NOT NULL | 服务端时间 |
| `moderation_flags` | `varchar(32)[]` | NOT NULL, default `{}` | 风控标记，不等于处罚事实 |

检查约束要求：USER 只有 `sender_user_id/client_message_id` 非空；ADMIN 只有 `sender_admin_id/client_message_id` 非空；SYSTEM 的两个发送者外键和 `client_message_id` 均为空且 `system_event_code` 非空；`message_type='SYSTEM'` 当且仅当 `sender_type='SYSTEM'`。分别建立 `UNIQUE(room_id, sender_user_id, client_message_id) WHERE sender_type='USER'`、`UNIQUE(room_id, sender_admin_id, client_message_id) WHERE sender_type='ADMIN'` 和 `UNIQUE(room_id, system_event_code) WHERE sender_type='SYSTEM'`，使玩家、客服和系统重试都只生成一条消息。

### 11.2 `asr_job` — 语音转文字任务

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 录音用户 |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间上下文 |
| `status` | `varchar(24)` | NOT NULL | `UPLOADED/TRANSCRIBING/SUCCEEDED/FAILED/DELETED` |
| `audio_object_key` | `text` | NULL, SECRET | 临时对象键；不存公开 URL |
| `audio_size_bytes` | `integer` | NOT NULL, CK <=2097152 | 最大 2 MiB |
| `duration_ms` | `integer` | NOT NULL, CK <=15000 | 最大 15 秒 |
| `transcript_draft` | `varchar(500)` | NULL, PII | 草稿，用户确认前不发送 |
| `failure_code` | `varchar(64)` | NULL | 失败原因 |
| `delete_after` | `timestamptz` | NOT NULL | 成功后立即删除；失败最长 24h |
| `deleted_at` | `timestamptz` | NULL | 实际删除时间 |

### 11.3 `mute_record` — 禁言记录

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 被禁言玩家 |
| `room_id` | `uuid` | FK → `room.id`, NULL | 房间级；空可表示授权范围级 |
| `duration_type` | `varchar(16)` | NOT NULL | `MIN_10/HOUR_24/PERMANENT` |
| `starts_at` | `timestamptz` | NOT NULL | 起始 |
| `ends_at` | `timestamptz` | NULL | 永久为空 |
| `status` | `varchar(16)` | NOT NULL | `ACTIVE/EXPIRED/REVOKED` |
| `reason` | `varchar(500)` | NOT NULL | 原因 |
| `operator_admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 永久禁言仅运营/超管 |
| `issued_operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL, UQ | 创建禁言的幂等操作 |
| `revoked_operation_id` | `uuid` | FK → `business_operation.id`, NULL, UQ | 主动撤销禁言的幂等操作；自然到期为空 |

约束：`ends_at IS NULL OR ends_at > starts_at`；ACTIVE 时 `revoked_operation_id` 为空，REVOKED 时必须非空，EXPIRED 时为空；同一用户和同一作用域最多一条 `ACTIVE` 记录，房间为空的范围级禁言使用规范化零UUID表达唯一键。禁言、撤销和到期收口只能调用受限函数；创建新禁言前先锁定该用户与作用域并把已自然到期但仍为ACTIVE的旧记录转为EXPIRED。

### 11.4 `user_chat_block` — 玩家主动屏蔽关系

屏蔽是接收侧过滤关系，不删除消息、不改变举报和禁言事实。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `blocker_user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 发起屏蔽的玩家 |
| `blocked_user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 被屏蔽的玩家 |
| `status` | `varchar(16)` | NOT NULL | `ACTIVE/REVOKED` |
| `blocked_at` | `timestamptz` | NOT NULL | 生效时间 |
| `revoked_at` | `timestamptz` | NULL | 解除时间 |
| `blocked_operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL, UQ | 屏蔽幂等操作 |
| `revoked_operation_id` | `uuid` | FK → `business_operation.id`, NULL, UQ | 解除幂等操作 |

检查约束：不得屏蔽自己；ACTIVE 时 `revoked_at/revoked_operation_id` 为空，REVOKED 时二者均非空。建立 `UNIQUE(blocker_user_id, blocked_user_id) WHERE status='ACTIVE'`。服务端仅在普通玩家 `TEXT/QUICK/EMOJI` 的订阅和历史查询中应用过滤；SYSTEM、安全提示和客服巡检消息不可被屏蔽，原消息、举报证据和审计记录不删除。

### 11.5 `report_submission` — 玩家私有举报记录

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `public_report_code` | `varchar(32)` | NOT NULL, UQ | 举报人可见编号，不可枚举他人记录 |
| `reporter_user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 举报人 |
| `target_type` | `varchar(16)` | NOT NULL | `MESSAGE/HAND/PLAYER/OTHER` |
| `target_id` | `uuid` | NULL | 对象 ID；文本对象另存安全摘要 |
| `reason_code` | `varchar(32)` | NOT NULL | `ABUSE/HARASSMENT/COLLUSION/OTHER` |
| `description` | `varchar(500)` | NULL | 补充说明 |
| `status` | `varchar(24)` | NOT NULL | `SUBMITTED/IN_REVIEW/RESOLVED/REJECTED` |
| `ticket_id` | `uuid` | FK → `support_ticket.id`, NOT NULL | 内部案件；不同举报人可关联同一案件 |
| `submitted_at` | `timestamptz` | NOT NULL | 首次提交时间 |
| `last_submitted_at` | `timestamptz` | NOT NULL | 24h 合并判断 |
| `public_conclusion` | `varchar(500)` | NULL | 结案 1–500 字，禁止私牌/IP/他人身份 |
| `conclusion_read_at` | `timestamptz` | NULL | 玩家已读时间 |

唯一合并规则：同举报人、同对象 24h 内追加原记录；不同举报人不得合并其私有前台记录。

### 11.6 `report_appendix` — 举报补充说明

不可变。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `report_id` | `uuid` | FK → `report_submission.id`, NOT NULL | 举报 |
| `content` | `varchar(500)` | NOT NULL | 补充说明 |
| `submitted_at` | `timestamptz` | NOT NULL | 提交时间 |
| `reopened_ticket` | `boolean` | NOT NULL | 已结案追加会重回 IN_REVIEW |

### 11.7 `support_ticket` — 内部客服/风控案件

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `ticket_code` | `varchar(32)` | NOT NULL, UQ | 内部案件号 |
| `ticket_type` | `varchar(24)` | NOT NULL | `REPORT/RECOVERY/RISK/OTHER` |
| `club_id` | `uuid` | FK → `club.id`, NULL | 范围 |
| `room_id` | `uuid` | FK → `room.id`, NULL | 房间 |
| `hand_id` | `uuid` | FK → `hand.id`, NULL | 手牌 |
| `status` | `varchar(24)` | NOT NULL | `OPEN/IN_REVIEW/RESOLVED/REJECTED` |
| `assignee_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 负责人 |
| `priority` | `varchar(8)` | NOT NULL | `P0/P1/P2/P3` |
| `internal_summary` | `text` | NULL, PII | 内部摘要，不返回玩家 |
| `resolution_code` | `varchar(64)` | NULL | 处置类型 |
| `resolved_at` | `timestamptz` | NULL | 结案时间 |
| `retention_until` | `timestamptz` | NOT NULL | 证据至少保留至结案并按策略延长 |

### 11.8 `ticket_event` — 工单处理轨迹

不可变。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `ticket_id` | `uuid` | FK → `support_ticket.id`, NOT NULL | 工单 |
| `seq_no` | `integer` | NOT NULL | 轨迹顺序 |
| `event_type` | `varchar(32)` | NOT NULL | `ASSIGNED/NOTE_ADDED/MUTED/STATUS_CHANGED/ACCESS_REQUESTED` 等 |
| `operator_admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 操作者 |
| `internal_note` | `text` | NULL, PII | 内部备注 |
| `public_note` | `varchar(500)` | NULL | 可公开内容；必须显式填写，不从内部备注复制 |
| `occurred_at` | `timestamptz` | NOT NULL | 时间 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NULL | 实际业务操作 |

唯一约束：`(ticket_id, seq_no)`。

### 11.9 `ticket_evidence` — 工单证据元数据

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `ticket_id` | `uuid` | FK → `support_ticket.id`, NOT NULL | 工单 |
| `evidence_type` | `varchar(24)` | NOT NULL | `MESSAGE/HAND_EVENT/LOGIN_LINK/FILE` |
| `object_type` | `varchar(32)` | NOT NULL | 对象类型 |
| `object_id` | `uuid` | NULL | 对象主键 |
| `object_key` | `text` | NULL, SECRET | 独立证据存储键，不存永久公开 URL |
| `content_digest` | `bytea` | NOT NULL | 完整性摘要 |
| `retention_until` | `timestamptz` | NOT NULL | 保留截止 |
| `added_by_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 添加人；系统保全可为空 |

### 11.10 `private_card_access_request` — 私牌专项申请与审批

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `request_code` | `varchar(40)` | NOT NULL, UQ | 专项申请号 |
| `ticket_id` | `uuid` | FK → `support_ticket.id`, NOT NULL | 有效工单 |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL | 必须已结束手 |
| `purpose` | `varchar(500)` | NOT NULL | 指定用途 |
| `requester_admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 申请人 |
| `authorized_admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 获准访问人；V1必须等于申请人 |
| `approver_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 审批人，不得与申请人相同 |
| `status` | `varchar(24)` | NOT NULL | `PENDING/APPROVED/REJECTED/EXPIRED/REVOKED` |
| `approved_at` | `timestamptz` | NULL | 审批时间 |
| `valid_until` | `timestamptz` | NULL | APPROVED 时等于 `approved_at + 30 minutes`；工单关闭时即使未到期也拒绝 |
| `decision_reason` | `varchar(500)` | NULL | 审批理由 |
| `decision_authorization_id` | `uuid` | FK → `sensitive_authorization.id`, NULL, UQ | 审批或拒绝动作自身的单次敏感授权；不得替代每次访问授权 |
| `decision_operation_id` | `uuid` | FK → `business_operation.id`, NULL, UQ | 审批/拒绝业务操作；PENDING 时为空 |
| `revoked_at` | `timestamptz` | NULL | 主动撤销时间 |
| `revoke_reason` | `varchar(500)` | NULL | 撤销原因 |

约束：`authorized_admin_id=requester_admin_id`；审批人不得等于申请人；APPROVED/REJECTED 必须同时具备审批人、决定授权和决定操作，APPROVED 还必须具备审批时间和到期时间，REJECTED 必须有理由。目标玩家由子表保存，不得恢复为数组。`sensitive_authorization` 建立 `UNIQUE(id, operation_id)`，本表建立复合外键 `(decision_authorization_id, decision_operation_id) → sensitive_authorization(id, operation_id)`。

应用角色不得直接更新审批终态，只能调用 `decide_private_card_access_request`。函数锁定申请和授权，复核专项审批权限、非自审、工单、手牌、参数摘要、会话、权限版本和120秒期限，在同一事务内消费授权、写审批终态、业务操作结果和不可变审计；同操作号同参数返回原结果，同号异参数拒绝。

### 11.11 `private_card_access_request_player` — 私牌申请目标玩家

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `request_id` | `uuid` | FK → `private_card_access_request.id`, NOT NULL | 专项申请 |
| `hand_id` | `uuid` | NOT NULL | 冗余绑定申请手牌，用于复合外键 |
| `user_id` | `uuid` | NOT NULL | 获准读取的玩家 |

主键/唯一约束：`(request_id, user_id)`；申请表建立 `UNIQUE(id, hand_id)`，本表以 `(request_id, hand_id) → private_card_access_request(id, hand_id)` 锁定申请手牌，并以 `(hand_id, user_id) → hand_player(hand_id, user_id)` 保证目标确为该手参与者。每个申请至少一条目标记录；应用角色不得直接写入本表。

### 11.12 `private_card_access_log` — 私牌实际访问轨迹

不可变。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `access_attempt_code` | `varchar(48)` | NOT NULL, UQ | 每次实际读取或拒绝尝试的稳定编号 |
| `access_request_id` | `uuid` | FK → `private_card_access_request.id`, NOT NULL | 已批准申请 |
| `admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 实际访问者 |
| `session_id` | `uuid` | FK → `admin_session.id`, NOT NULL | 原会话 |
| `sensitive_authorization_id` | `uuid` | FK → `sensitive_authorization.id`, NOT NULL, UQ | 本次访问对应的120秒参数绑定TOTP单次授权，不得复用 |
| `hand_id` | `uuid` | FK → `hand.id`, NOT NULL | 手牌 |
| `accessed_at` | `timestamptz` | NOT NULL | 时间 |
| `purpose_snapshot` | `varchar(500)` | NOT NULL | 用途快照 |
| `result` | `varchar(16)` | NOT NULL | `ALLOWED/DENIED` |
| `failure_code` | `varchar(64)` | NULL | 过期、撤权、越范围等 |

约束：申请表的 `UNIQUE(id, hand_id)` 同时作为复合引用目标，`(access_request_id, hand_id) → private_card_access_request(id, hand_id)`，防止访问日志替换为另一手牌；`admin_id` 必须等于申请的 `authorized_admin_id`，由受限读取函数和约束触发器双重保证。

### 11.13 `private_card_access_log_player` — 私牌实际访问目标

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `access_log_id` | `uuid` | FK → `private_card_access_log.id`, NOT NULL | 一次实际访问 |
| `hand_id` | `uuid` | NOT NULL | 冗余绑定访问手牌，用于复合外键 |
| `user_id` | `uuid` | NOT NULL | 实际请求读取的玩家；拒绝尝试也记录 |

主键/唯一约束：`(access_log_id, user_id)`；访问日志表建立 `UNIQUE(id, hand_id)`，本表以 `(access_log_id, hand_id) → private_card_access_log(id, hand_id)` 锁定访问手牌，并以 `(hand_id, user_id) → hand_player(hand_id, user_id)` 保证目标确为该手参与者。`ALLOWED` 时目标集合必须是申请目标集合的子集，由唯一受限读取函数校验；`DENIED` 仍可记录越范围目标。

应用运行角色没有 `hand_card.card_ciphertext` 的直接 SELECT 权限，只能调用 `read_private_cards(request_id, sensitive_authorization_id, hand_id, player_ids)` 安全定义函数。函数在同一事务中锁定申请和单次授权，验证结束手、工单处于 `OPEN/IN_REVIEW`、获准访问人、独立审批、30分钟期限、会话、权限版本、参数摘要及目标子集；随后原子消费授权并写访问日志。拒绝路径返回安全错误码并提交 DENIED 日志，不通过抛异常回滚掉审计证据。

## 12. 后台身份、权限与安全域

### 12.1 `admin_user` — 独立后台人员账号

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `admin_code` | `varchar(32)` | NOT NULL, UQ | 后台稳定 ID |
| `login_name` | `citext` | NOT NULL, UQ, PII | 登录名；与 TG 玩家身份分离 |
| `display_name` | `varchar(80)` | NOT NULL | 展示名 |
| `password_hash` | `text` | NULL, SECRET | Argon2id 等现代口令哈希；INVITED 可为空 |
| `status` | `varchar(24)` | NOT NULL | `INVITED/ACTIVE/DISABLED/RESET_PENDING` |
| `linked_user_id` | `uuid` | FK → `app_user.id`, NULL | 同一自然人的可选关联，不继承玩家权限 |
| `linked_agent_id` | `uuid` | FK → `agent.id`, NULL | 代理只读工作台关联，不自动获得管理权 |
| `authorization_version` | `bigint` | NOT NULL, default 1 | 角色/范围变更递增，撤销旧会话和授权 |
| `failed_login_count` | `smallint` | NOT NULL, default 0 | 登录失败计数 |
| `login_locked_until` | `timestamptz` | NULL | 5 次失败锁 15 分钟 |
| `failed_password_change_count` | `smallint` | NOT NULL, default 0 | 与登录计数分离 |
| `password_change_locked_until` | `timestamptz` | NULL | 改密锁定 |
| `failed_sensitive_auth_count` | `smallint` | NOT NULL, default 0 | 敏感操作验证失败计数，与登录/改密分离 |
| `sensitive_auth_locked_until` | `timestamptz` | NULL | 5 次失败锁敏感验证 15 分钟，不影响只读会话 |
| `last_full_auth_at` | `timestamptz` | NULL | 最近密码+TOTP 完整认证 |
| `activated_at` | `timestamptz` | NULL | 激活时间 |
| `disabled_at` | `timestamptz` | NULL | 停用时间 |

### 12.2 `admin_totp_authenticator` — 后台认证器

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 后台账号 |
| `secret_ciphertext` | `bytea` | NOT NULL, SECRET | TOTP 密钥信封加密 |
| `key_version` | `varchar(32)` | NOT NULL, SECRET | KMS 密钥版本 |
| `status` | `varchar(16)` | NOT NULL | `PENDING/ACTIVE/REVOKED` |
| `verified_at` | `timestamptz` | NULL | 首个 TOTP 验证时间 |
| `last_used_step` | `bigint` | NULL, CK >=0 | 已消费最大时间步；成功必须严格递增 |
| `revoked_at` | `timestamptz` | NULL | 重绑时撤销 |

约束：每账号最多一个 ACTIVE 认证器。TOTP 校验服务器当前步 N 的 [N−1,N+1]；密码和码验证成功后锁定认证器，以 `UPDATE ... SET last_used_step=:matched_step WHERE status='ACTIVE' AND (last_used_step IS NULL OR last_used_step < :matched_step) RETURNING id` 原子消费，必须恰一行。与登录会话或单次 sensitive_authorization 创建同事务提交，失败回滚不能签发任何会话/授权。并发同一步仅一次成功；先消费 N+1 后，N 和 N+1 均拒绝（即使 N 从未用过），N+2 在进入容差窗口后才可用。服务器时钟回拨不降低高水位，等待时钟恢复或受审计重绑新认证器，不清零旧认证器。V015 触发器禁止减小/清空高水位；仅字段不变并不代表验证成功，认证入口必须用上述条件更新。单值方案足够，不能只判断 step != last_used_step。同一码在窗口内匹配多个时间步时确定性选择大于高水位的最大匹配步，再原子消费，不进行多次签发尝试。

### 12.3 `admin_activation_token` — 激活/人工重置凭据

只存摘要，24 小时单次使用。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 目标账号 |
| `token_hash` | `bytea` | NOT NULL, UQ, SECRET | 凭据摘要 |
| `purpose` | `varchar(16)` | NOT NULL | `ACTIVATE/RESET` |
| `expires_at` | `timestamptz` | NOT NULL | 24h |
| `used_at` | `timestamptz` | NULL | 使用时间 |
| `revoked_at` | `timestamptz` | NULL | 重发作废旧凭据 |
| `created_by_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 超管创建；本地初始化可空并写审计主体 |
| `identity_verification_channel` | `varchar(128)` | NULL, PII | 人工重置核验渠道摘要，不存多余隐私 |
| `reason` | `varchar(500)` | NOT NULL | 创建原因 |

约束：同一账号、同一用途最多一个未使用且未撤销凭据，建立 `UNIQUE(admin_id, purpose) WHERE used_at IS NULL AND revoked_at IS NULL`。重发必须在同一受限函数事务内锁定账号、撤销旧凭据并创建新凭据；已过期但未收口的记录先写 `revoked_at`。人工 RESET 的 `created_by_admin_id` 不得等于 `admin_id`；受控本地恢复允许创建者为空，但必须绑定工单号并写系统审计。

### 12.4 `admin_recovery_code` — 单次恢复码

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 账号 |
| `code_hash` | `bytea` | NOT NULL, UQ, SECRET | 仅存强哈希 |
| `batch_no` | `uuid` | NOT NULL | 每次生成 10 个为一批 |
| `used_at` | `timestamptz` | NULL | 单次使用 |
| `revoked_at` | `timestamptz` | NULL | 重绑后整批撤销 |

### 12.5 `admin_session` — 后台会话

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 账号 |
| `session_token_hash` | `bytea` | NOT NULL, UQ, SECRET | 令牌摘要 |
| `session_type` | `varchar(16)` | NOT NULL | `BUSINESS/RECOVERY` |
| `authorization_version` | `bigint` | NOT NULL | 建立时权限版本；不匹配即拒绝 |
| `created_ip` | `inet` | NULL, PII | 来源 IP |
| `user_agent` | `varchar(1024)` | NULL, PII | 设备摘要 |
| `authenticated_at` | `timestamptz` | NOT NULL | 完整认证时间 |
| `last_active_at` | `timestamptz` | NOT NULL | 仅主动查询/操作更新；轮询不续期 |
| `idle_expires_at` | `timestamptz` | NOT NULL | 15 分钟 |
| `absolute_expires_at` | `timestamptz` | NOT NULL | 8 小时；恢复会话 15 分钟 |
| `revoked_at` | `timestamptz` | NULL | 撤销时间 |
| `revoke_reason` | `varchar(64)` | NULL | 改密、停用、改权、重置等 |

### 12.6 `admin_role` — 后台角色

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `role_code` | `varchar(32)` | NOT NULL, UQ | `SUPER_ADMIN/OPERATOR/SUPPORT/AGENT_READONLY` |
| `name` | `varchar(64)` | NOT NULL | 展示名 |
| `is_system` | `boolean` | NOT NULL | 系统角色不可任意删除 |
| `status` | `varchar(16)` | NOT NULL | `ACTIVE/INACTIVE` |

### 12.7 `admin_permission` — 原子动作权限

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `permission_code` | `varchar(32)` | NOT NULL, UQ | 对应权限矩阵 `BP-01`～`BP-31` 或更细动作码 |
| `action_code` | `varchar(64)` | NOT NULL, UQ | 如 `CLUB.CREATE`、`LEDGER.ADJUST` |
| `resource_type` | `varchar(32)` | NOT NULL | 资源类型 |
| `sensitive` | `boolean` | NOT NULL | 是否要求单次 TOTP 授权 |
| `description` | `varchar(255)` | NOT NULL | 权限说明 |

### 12.8 `admin_role_permission` — 角色动作映射

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `role_id` | `uuid` | FK → `admin_role.id`, NOT NULL | 角色 |
| `permission_id` | `uuid` | FK → `admin_permission.id`, NOT NULL | 权限 |
| `effect` | `varchar(8)` | NOT NULL, CK `ALLOW/DENY` | 明确拒绝优先 |

唯一约束：`(role_id, permission_id)`。

### 12.9 `admin_user_role` — 人员角色授予

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 人员 |
| `role_id` | `uuid` | FK → `admin_role.id`, NOT NULL | 角色 |
| `valid_from` | `timestamptz` | NOT NULL | 起始 |
| `valid_until` | `timestamptz` | NULL | 可选截止 |
| `granted_by_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 授权人；初始化可空 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL | 授权操作 |
| `sensitive_authorization_id` | `uuid` | FK → `sensitive_authorization.id`, NULL | ADMIN来源必填；受控初始化为空 |
| `grant_source` | `varchar(16)` | NOT NULL | `ADMIN/BOOTSTRAP`；BOOTSTRAP只允许版本化种子迁移 |
| `revoked_at` | `timestamptz` | NULL | 撤权时间 |

约束：`valid_until IS NULL OR valid_until > valid_from`；同一 `admin_id + role_id` 的未撤销有效区间不得重叠。ADMIN来源必须同时具备授权人和敏感授权，BOOTSTRAP来源二者均为空并由Flyway种子迁移专用角色写入。建立复合外键 `(sensitive_authorization_id, operation_id) → sensitive_authorization(id, operation_id)`；同一授权可在一次原子操作内授予多个角色/范围，不能在操作外复用。

### 12.10 `admin_scope_grant` — 资源范围与业务上限

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 人员 |
| `scope_type` | `varchar(24)` | NOT NULL | `GLOBAL/CLUB/AGENT/TICKET/ROOM` |
| `scope_id` | `uuid` | NULL | GLOBAL 为空，其余对应资源 |
| `permission_id` | `uuid` | FK → `admin_permission.id`, NULL | 空表示角色内所有可范围化动作 |
| `commission_rate_ceiling` | `numeric(9,6)` | NULL, CK 0–1 | 运营比例授权上限 |
| `valid_from` | `timestamptz` | NOT NULL | 起始 |
| `valid_until` | `timestamptz` | NULL | 截止 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL | 授权操作 |
| `granted_by_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 授权人；受控初始化可空 |
| `sensitive_authorization_id` | `uuid` | FK → `sensitive_authorization.id`, NULL | ADMIN来源必填；受控初始化为空 |
| `grant_source` | `varchar(16)` | NOT NULL | `ADMIN/BOOTSTRAP` |
| `revoked_at` | `timestamptz` | NULL | 撤权时间 |

约束：`scope_type='GLOBAL'` 当且仅当 `scope_id IS NULL`；`valid_until IS NULL OR valid_until > valid_from`。使用规范化 `scope_id/permission_id` 和 `tstzrange` 排斥同一管理员、作用域、权限的未撤销重叠区间；`permission_id IS NULL` 的全动作范围与同一作用域下任一具体权限区间也不得重叠，由受限函数和约束触发器保证，避免撤销宽授权后仍残留重复窄授权。ADMIN来源必须具备授权人和敏感授权，BOOTSTRAP仅允许种子迁移。建立复合外键 `(sensitive_authorization_id, operation_id) → sensitive_authorization(id, operation_id)`。索引：`(admin_id, scope_type, scope_id) WHERE revoked_at IS NULL`。源/目标迁移需分别命中授权范围。

应用角色不得直接写 `admin_user_role` 或 `admin_scope_grant`，统一调用 `apply_admin_grant`。函数锁定目标管理员和单次授权，校验不可自提权、操作者当前范围与上限、参数摘要及未消费状态，在同一事务内写入/撤销授权、递增目标 `authorization_version`、撤销目标全部旧会话和未消费授权并写审计。撤权时把 `valid_until` 收口到撤权时间，保证历史区间与实际生效时点一致。

#### 权限组合判定（ADR-012）

在数据库事务时刻 t，仅使用 ACTIVE 账号/角色、未撤销且 valid_from<=t<valid_until（空截止为无穷）的授权。先校验原会话、authorization_version、资源实时归属，再判下表；所有 SUPER_ADMIN 也适用显式 DENY 与单次敏感授权，独立字段无隐式超管绕过。

| 条件 | 结果 |
| --- | --- |
| 任一有效角色对该 permission 显式 DENY | DENY，其他角色 ALLOW、GLOBAL/窄范围均不能覆盖 |
| 无 DENY，至少一有效角色 ALLOW | 取得动作候选能力；还须命中 scope |
| 只有 scope（即使 permission_id 明确）但角色无 ALLOW | DENY；scope 仅限缩能力，不创造动作权限 |
| scope.permission_id 为空 | 匹配已有角色 ALLOW 的可范围化动作，不授 IP/私牌/导出等独立动作 |
| 动作 ALLOW 且至少一个有效范围覆盖当前资源 | 按该动作继续验证业务条件；无匹配默认 DENY |
| 多个匹配范围带上限 | 采用所有匹配非空 commission_rate_ceiling 的最小值，空值不增权；若动作要求上限且全为空则拒绝 |
| 源/目标迁移或批量请求 | 每一个资源分别命中同一动作权限和范围；禁止只用源范围授权目标 |
| 敏感动作 | 前述通过后仍须参数、操作号、会话及权限版本绑定的未过期单次授权 |

GLOBAL 覆盖所有对象；CLUB/ROOM/AGENT/TICKET 仅按当前权威关系覆盖相应对象，不从名称或前端过滤条件推断。不同范围可以重叠，组合采用上述最小上限。相同规范化 scope 的同动作重叠，以及同 scope 的空 permission 与具体 permission 重叠仍按现有触发器拒绝；不新增“窄范围覆盖宽范围”优先级。所有列表/详情/汇总/回放/导出共用判定器和行过滤，字段独立权限逐项裁剪。异步执行与下载重新判定当前权限；撤权、版本推进和旧授权失效原子提交。若依菜单只展示判定结果。

### 12.11 `admin_auth_event` — 后台认证与安全事件

不可变。V1 使用普通表并按 `occurred_at` 建索引，以保留全局事件追踪和单列 UUID 主键。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `admin_id` | `uuid` | FK → `admin_user.id`, NULL | 未识别账号时为空 |
| `login_name_hash` | `bytea` | NULL, PII | 失败登录关联，不保存多余明文 |
| `event_type` | `varchar(32)` | NOT NULL | `LOGIN/ACTIVATE/RECOVERY/PASSWORD_CHANGE/TOTP_RESET/SENSITIVE_AUTH` |
| `success` | `boolean` | NOT NULL | 结果 |
| `failure_code` | `varchar(64)` | NULL | 统一文案背后的安全码 |
| `ip_address` | `inet` | NULL, PII | 来源 |
| `user_agent` | `varchar(1024)` | NULL, PII | 客户端 |
| `occurred_at` | `timestamptz` | NOT NULL | 时间 |
| `request_id` | `uuid` | NULL | 链路号 |

### 12.12 `sensitive_authorization` — 参数绑定单次授权

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 操作者 |
| `session_id` | `uuid` | FK → `admin_session.id`, NOT NULL | 原会话 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL, UQ | 绑定操作 |
| `action_code` | `varchar(64)` | NOT NULL | 敏感动作 |
| `parameter_digest` | `bytea` | NOT NULL | 对象、金额、币种、范围等规范化摘要 |
| `authorization_version` | `bigint` | NOT NULL | 生成时权限版本 |
| `verified_totp_step` | `bigint` | NOT NULL | 不可与登录或其他授权复用 |
| `status` | `varchar(16)` | NOT NULL | `ISSUED/CONSUMED/EXPIRED/REVOKED` |
| `expires_at` | `timestamptz` | NOT NULL | 默认 120 秒 |
| `consumed_at` | `timestamptz` | NULL | 仅一次 |

执行时必须同时校验会话、权限版本、参数摘要、时效和未消费状态。

唯一约束：`(id, operation_id)`，供资金调整等敏感业务建立复合外键，确保授权对象、参数和业务操作不可被重新组合。消费授权的受限函数必须对本行执行 `SELECT ... FOR UPDATE`；应用角色不得直接修改授权状态。

## 13. 业务操作、审计、恢复与导出域

### 13.1 `business_operation` — 统一请求与实际生效状态

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `operation_code` | `varchar(40)` | NOT NULL, UQ | 后台/客户端可查询操作号 |
| `request_id` | `uuid` | NOT NULL, UQ | 调用方生成幂等号 |
| `actor_type` | `varchar(16)` | NOT NULL | `USER/ADMIN/SYSTEM` |
| `actor_id` | `uuid` | NOT NULL | 对应主体；系统主体使用固定服务 ID |
| `operation_type` | `varchar(64)` | NOT NULL | 开房、买入、迁移、调款、关桌等 |
| `target_type` | `varchar(32)` | NOT NULL | 对象类型 |
| `target_id` | `uuid` | NULL | 对象可能在成功后才生成 |
| `parameter_digest` | `bytea` | NOT NULL | 同 ID 异参数检测 |
| `parameter_summary` | `jsonb` | NOT NULL | 脱敏参数摘要，不存 token/TOTP/私牌 |
| `request_status` | `varchar(24)` | NOT NULL | `SUBMITTING/UNKNOWN/FAILED/SUCCEEDED` |
| `domain_status` | `varchar(32)` | NULL | `ACCEPTED/PENDING_EFFECT/APPLIED/CANCELLED/SETTLING/SETTLED` 等 |
| `submitted_at` | `timestamptz` | NOT NULL | 提交时间 |
| `accepted_at` | `timestamptz` | NULL | 业务方受理时间 |
| `effective_at` | `timestamptz` | NULL | 实际生效时间 |
| `completed_at` | `timestamptz` | NULL | 终态时间 |
| `reason` | `varchar(500)` | NULL | 写操作原因 |
| `error_category` | `varchar(32)` | NULL | 前端稳定错误分类 |
| `error_code` | `varchar(64)` | NULL | 精确错误码 |
| `error_message` | `varchar(500)` | NULL | 安全可展示信息 |
| `result_summary` | `jsonb` | NULL | 脱敏结果；查询原号直接返回 |
| `parent_operation_id` | `uuid` | FK → `business_operation.id`, NULL | 审核、纠错、撤销等关系 |

索引：`(actor_type, actor_id, submitted_at desc)`、`(request_status, submitted_at)`、`(target_type, target_id, submitted_at desc)`。UNKNOWN 不能自动转失败或产生退款。

### 13.2 `audit_log` — 不可删除审计日志

不可变。V1 使用普通表并按 `occurred_at` 建索引，默认保留 365 天；未来分区须先处理全局 `audit_code` 与外键策略。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `audit_code` | `varchar(48)` | NOT NULL, UQ | 审计事件号 |
| `operator_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 后台操作者；系统事件可空 |
| `operator_user_id` | `uuid` | FK → `app_user.id`, NULL | 玩家写操作 |
| `role_snapshot` | `varchar(32)[]` | NOT NULL | 当时角色 |
| `scope_snapshot` | `jsonb` | NOT NULL | 当时范围的脱敏摘要 |
| `action_code` | `varchar(64)` | NOT NULL | 动作 |
| `object_type` | `varchar(32)` | NOT NULL | 对象类型 |
| `object_id` | `uuid` | NULL | 对象 |
| `before_value` | `jsonb` | NULL | 脱敏前值 |
| `after_value` | `jsonb` | NULL | 脱敏后值 |
| `reason` | `varchar(500)` | NULL | 原因 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NULL | 操作号 |
| `request_id` | `uuid` | NULL | 请求号 |
| `original_business_id` | `varchar(64)` | NULL | 原业务号 |
| `result` | `varchar(16)` | NOT NULL | `ALLOWED/DENIED/SUCCEEDED/FAILED` |
| `error_code` | `varchar(64)` | NULL | 错误 |
| `occurred_at` | `timestamptz` | NOT NULL | 提交/访问时间 |
| `effective_at` | `timestamptz` | NULL | 延迟动作实际生效时间 |

禁止记录密码、TOTP、完整 token、完整牌序和无关 PII。应用角色仅 INSERT/SELECT，无 UPDATE/DELETE。

### 13.3 `recovery_case` — 游戏/资金故障恢复事件

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `case_code` | `varchar(40)` | NOT NULL, UQ | 恢复事件号 |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间 |
| `hand_id` | `uuid` | FK → `hand.id`, NULL | 原手 |
| `settlement_id` | `uuid` | FK → `hand_settlement.id`, NULL | 可证结算 |
| `status` | `varchar(24)` | NOT NULL | `OPEN/RECOVERING/RECOVERED/VOIDED/RECOVERY_REQUIRED/CLOSED` |
| `evidence_state` | `varchar(32)` | NOT NULL | `SETTLEMENT_COMMITTED/LOG_REPLAYABLE/PREFLOP_SNAPSHOT_ONLY/UNKNOWN` |
| `selected_path` | `varchar(32)` | NULL | `RENOTIFY/RESUME_SAME_HAND/VOID_AND_REVERSE/HOLD_FOR_REVIEW` |
| `last_committed_event_id` | `uuid` | FK → `hand_event.id`, NULL | 最后可信事件 |
| `owner_admin_id` | `uuid` | FK → `admin_user.id`, NULL | 负责人 |
| `decision_reason` | `varchar(1000)` | NULL | 恢复依据 |
| `opened_at` | `timestamptz` | NOT NULL | 发现时间 |
| `updated_business_at` | `timestamptz` | NOT NULL | 最近处置更新时间 |
| `closed_at` | `timestamptz` | NULL | 完成时间 |
| `operation_id` | `uuid` | FK → `business_operation.id`, NULL | 受控恢复请求 |

案件冻结资金总额按 `recovery_case_item` 分资产汇总，不在案件头保存无资产的可写总额。恢复处置只能追加或更新明细终态，不能覆盖原账本和原交易。

### 13.4 `recovery_case_item` — 恢复资金与对象明细

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `case_id` | `uuid` | FK → `recovery_case.id`, NOT NULL | 恢复案件 |
| `item_no` | `integer` | NOT NULL | 案件内顺序 |
| `user_id` | `uuid` | FK → `app_user.id`, NULL | 受影响玩家；纯平台项目可空 |
| `asset_id` | `uuid` | FK → `asset.id`, NOT NULL | 资产，禁止跨资产汇总金额 |
| `ledger_account_id` | `uuid` | FK → `ledger_account.id`, NULL | 受影响账户 |
| `original_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL | 原买入、补码、结算或退出交易 |
| `seat_session_id` | `uuid` | FK → `seat_session.id`, NULL | 受影响资金会话 |
| `amount` | `bigint` | NOT NULL, CK >0 | 等待核查或处置金额 |
| `status` | `varchar(24)` | NOT NULL | `FROZEN/CONFIRMED/REVERSED/RELEASED/HELD_FOR_REVIEW` |
| `disposition_transaction_id` | `uuid` | FK → `ledger_transaction.id`, NULL | 最终冲正或释放交易；一个多方零和交易可处置多个明细 |
| `decision_reason` | `varchar(500)` | NULL | 明细处置依据 |
| `resolved_at` | `timestamptz` | NULL | 明细终态时间 |

唯一约束：`(case_id, item_no)`。至少关联账户、原交易或资金会话之一；终态 `REVERSED/RELEASED` 必须关联处置交易。案件、明细处置、账本交易和审计在同一受限恢复函数事务内提交。

### 13.5 `export_task` — 异步导出任务

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `task_code` | `varchar(40)` | NOT NULL, UQ | 任务号 |
| `admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 发起人 |
| `session_id` | `uuid` | FK → `admin_session.id`, NOT NULL | 绑定原会话 |
| `export_type` | `varchar(32)` | NOT NULL | 账本、审计、房间、分成等 |
| `filter_json` | `jsonb` | NOT NULL | 原筛选，时间区间不得超过 31 天 |
| `column_codes` | `varchar(64)[]` | NOT NULL | 申请列；不含无权隐藏列 |
| `scope_digest` | `bytea` | NOT NULL | 生成时权限范围摘要 |
| `status` | `varchar(24)` | NOT NULL | `QUEUED/GENERATING/READY/FAILED/EXPIRED/REVOKED` |
| `object_key` | `text` | NULL, SECRET | 私有存储键，不是公开 URL |
| `row_count` | `bigint` | NULL | 导出行数 |
| `data_cutoff_at` | `timestamptz` | NULL | 数据时点 |
| `ready_at` | `timestamptz` | NULL | 生成完成 |
| `expires_at` | `timestamptz` | NULL | 生成起 15 分钟 |
| `failure_code` | `varchar(64)` | NULL | 撤权、服务失败等 |

生成中和每次下载都重验账号、原会话、当前权限与范围；CSV 文本防公式注入，ID 保持文本格式。

### 13.6 `export_download_log` — 导出下载审计

不可变。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `export_task_id` | `uuid` | FK → `export_task.id`, NOT NULL | 任务 |
| `admin_id` | `uuid` | FK → `admin_user.id`, NOT NULL | 下载人，必须等于任务发起人 |
| `session_id` | `uuid` | FK → `admin_session.id`, NOT NULL | 原会话 |
| `downloaded_at` | `timestamptz` | NOT NULL | 时间 |
| `result` | `varchar(16)` | NOT NULL | `ALLOWED/DENIED` |
| `failure_code` | `varchar(64)` | NULL | 过期、撤权、会话失效等 |
| `ip_address` | `inet` | NULL, PII | 下载来源 |

### 13.7 `projection_checkpoint` — 报表投影水位与完整性

用于向运营页面明确数据截止时间和完整性；不得用“最后更新时间”冒充源业务时间。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `projection_name` | `varchar(64)` | NOT NULL, UQ | 如 `OPS_DAILY_METRICS/COMMISSION_DAILY/WALLET_BALANCE` |
| `status` | `varchar(24)` | NOT NULL | `CURRENT/PARTIAL/REBUILDING/FAILED` |
| `last_event_id` | `uuid` | NULL | 已处理的最后事件；不同源可改用业务游标 |
| `last_business_at` | `timestamptz` | NULL | 已覆盖的最晚业务时间 |
| `data_cutoff_at` | `timestamptz` | NOT NULL | 页面展示的数据截止时间 |
| `completeness_note` | `varchar(500)` | NULL | 缺失范围、旧摘要或重建说明 |
| `last_success_at` | `timestamptz` | NULL | 最近完整成功时间 |
| `failure_code` | `varchar(64)` | NULL | 失败原因 |

### 13.8 `outbox_event` — 不可变业务事件

不可变，包含 id/created_at，不含 updated_at/row_version；id 即全局 event_id。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `operation_id` | `uuid` | FK → `business_operation.id`, NOT NULL | 同事务业务操作；系统事件也须有幂等操作 |
| `aggregate_type` | `varchar(32)` | NOT NULL | 聚合类型 |
| `aggregate_id` | `uuid` | NOT NULL | 聚合主键；类型由生产者白名单约束 |
| `aggregate_version` | `bigint` | NOT NULL, CK >=0 | 已提交版本 |
| `event_type` | `varchar(64)` | NOT NULL | 版本化事件名 |
| `schema_version` | `smallint` | NOT NULL, default 1, CK >0 | payload 契约版本 |
| `payload` | `jsonb` | NOT NULL | 对象类型 JSON；最小必要字段，不含凭据或未公开私牌 |
| `occurred_at` | `timestamptz` | NOT NULL | 业务发生时刻 |

id PK；UNIQUE(operation_id,aggregate_type,aggregate_id,aggregate_version,event_type) 防同操作重复事件；索引(aggregate_type,aggregate_id,aggregate_version)、(created_at,id)。应用不能直接 INSERT/UPDATE/DELETE；事件与预期消费者 delivery 行由未来受限业务函数在同事务写入，不开放孤立 append API。

### 13.9 `outbox_delivery` — 每消费者投递与租约

包含通用 id/created_at/updated_at/row_version。UNIQUE(event_id,consumer_name)，一个事件可以投递到多个消费者，ACK 相互独立。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `event_id` | `uuid` | FK → `outbox_event.id`, NOT NULL | 不可变源事件 |
| `consumer_name` | `varchar(64)` | NOT NULL | 部署白名单消费者，不接受客户端任意目标 |
| `status` | `varchar(16)` | NOT NULL, default 'READY' | `READY/LEASED/DELIVERED/DEAD` |
| `attempt_count` | `integer` | NOT NULL, default 0, CK >=0 | 领取次数 |
| `available_at` | `timestamptz` | NOT NULL, default now() | 下次可领时间 |
| `lease_token` | `uuid` | NULL | 每次领取随机防栅令牌 |
| `lease_expires_at` | `timestamptz` | NULL | 租约截止 |
| `delivered_at` | `timestamptz` | NULL | 消费者确认成功时间 |
| `last_error_code` | `varchar(64)` | NULL | 无敏感信息的错误码 |

LEASED 当且仅当 lease_token/lease_expires_at 同时非空；DELIVERED 当且仅当 delivered_at 非空。READY/DEAD 不得残留租约。领取、ACK 与失败重试协议见架构 §8.4；索引(status,available_at)、(lease_expires_at) WHERE status='LEASED'。V015 仅落地结构与保护，不声称业务生产者、worker 和消费者已实现。投递入口未完成前保持 fail-closed。

## 14. 测试预设与分析事件域

### 14.1 `test_deal_run` — 隔离环境预设发牌运行

无运营后台写入口，仅受控部署工具写入；保留 365 天。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `scenario_id` | `varchar(64)` | NOT NULL | 场景 ID |
| `run_id` | `varchar(64)` | NOT NULL, UQ | 整个测试部署唯一；清理后也不支持复用 |
| `schema_version` | `smallint` | NOT NULL, CK =1 | 文件结构版本 |
| `content_digest` | `bytea` | NOT NULL | 规范化完整内容摘要；同 run_id 异内容冲突 |
| `target_type` | `varchar(16)` | NOT NULL | `ROOM/USER_SET` |
| `target_room_code` | `varchar(32)` | NULL | ROOM 定位 |
| `target_user_ids` | `uuid[]` | NULL | USER_SET 定位，必须同桌且全参局 |
| `deck_mode` | `varchar(16)` | NOT NULL | 与目标房间一致 |
| `payload_ciphertext` | `bytea` | NOT NULL, SECRET | 公共牌、指定底牌和规范化预设的密文 |
| `key_version` | `varchar(32)` | NOT NULL, SECRET | 加密密钥版本 |
| `status` | `varchar(24)` | NOT NULL | `REGISTERED/NOT_MATCHED/BOUND/CONSUMED/FAILED/VOIDED` |
| `bound_hand_id` | `uuid` | FK → `hand.id`, NULL, UQ | 与开手提交一致 |
| `registered_at` | `timestamptz` | NOT NULL | 登记时间 |
| `consumed_at` | `timestamptz` | NULL | 成功开手消费时间 |
| `failure_code` | `varchar(64)` | NULL | 文件错误、冲突、账号缺席等 |

约束：目标房间与用户集合恰有一个；正式环境或非 TEST 资产拒绝绑定。普通客户端只看到 `deal_source=SCRIPTED_TEST`。

### 14.2 `conversion_journey` — 加入转化旅程

业务读模型，可由服务端业务事件重建。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `journey_code` | `varchar(40)` | NOT NULL, UQ | journey_id |
| `user_id` | `uuid` | FK → `app_user.id`, NOT NULL | 玩家 |
| `room_id` | `uuid` | FK → `room.id`, NOT NULL | 房间 |
| `entry_source` | `varchar(16)` | NOT NULL | `INVITE/CLUB_LIST`，首次合格入口归因 |
| `first_eligible_at` | `timestamptz` | NOT NULL | 服务端确认合格时间 |
| `window_ends_at` | `timestamptz` | NOT NULL | 30 分钟后 |
| `status` | `varchar(24)` | NOT NULL | `OPEN/BUYIN_POSTED/EXPIRED` |
| `buyin_operation_id` | `uuid` | FK → `business_operation.id`, NULL | 首次成功买入 |
| `buyin_posted_at` | `timestamptz` | NULL | 成功时间 |
| `initial_rejection_code` | `varchar(64)` | NULL | 非合格入口拒绝另行统计时使用 |
| `later_failure_code` | `varchar(64)` | NULL | 窗口内满桌、余额变化等，不删除分母 |
| `business_date` | `date` | NOT NULL | 按首次合格进入的 Asia/Shanghai 日期 |
| `is_test` | `boolean` | NOT NULL | 隔离测试不混正式指标 |

唯一规则：同 `user_id + room_id` 的未结束 30 分钟窗口只保留一条。

### 14.3 `analytics_event` — 非权威分析事件

V1 使用普通表并按 `occurred_at` 建索引；不得作为账务或业务终态来源。未来分区须先引入非分区事件 ID 注册表。

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `event_code` | `varchar(48)` | NOT NULL, UQ | 事件 ID |
| `event_name` | `varchar(64)` | NOT NULL | 设计契约事件名 |
| `user_id` | `uuid` | FK → `app_user.id`, NULL | 玩家 |
| `room_id` | `uuid` | FK → `room.id`, NULL | 房间 |
| `journey_id` | `uuid` | FK → `conversion_journey.id`, NULL | 旅程 |
| `request_id` | `uuid` | NULL | 提交事件关联 |
| `business_id` | `varchar(64)` | NULL | 业务号 |
| `properties` | `jsonb` | NOT NULL | 按事件 schema 校验；禁止邀请码 token、TG 原始身份、IP、私牌、完整聊天正文 |
| `occurred_at` | `timestamptz` | NOT NULL | 服务端接收时间 |
| `is_test` | `boolean` | NOT NULL | 测试隔离 |

## 15. 建议视图与物化读模型

| 名称 | 类型 | 用途 | 关键口径 |
| --- | --- | --- | --- |
| `v_current_club_membership` | 视图 | 当前归属 | 仅 `club_membership.status='CURRENT'` |
| `v_user_wallet_balance` | 视图/投影 | 玩家资产与后台列表 | 可用+补码冻结+桌内托管；底池不重复 |
| `v_ledger_transaction_display` | 安全视图 | 账单/API展示状态 | 存储状态保持 `PENDING/POSTED/FAILED`；存在有效完整冲正时派生 `REVERSED` 并返回冲正交易与时间 |
| `v_room_public_summary` | 视图 | 俱乐部房间列表 | 只含公开人数、规则与状态，无私牌/钱包 |
| `v_player_session_result` | 物化读模型 | 战绩会话列表 | 单手净收益合计−离座费；结束时间归属 |
| `v_player_stat_period` | 参数化查询/汇总表 | VPIP/PFR/W$SD/bb100 | 玩法、资产分开；分母 0 返回 NULL |
| `v_hand_replay_public` | 安全视图 | 普通回放 | 本人底牌+当时公开牌，Muck/他人未公开牌不返回 |
| `v_ops_daily_metrics` | 物化视图 | 运营总览 | 去重 user_id/hand_id；按资产分组；显示 data_cutoff_at |
| `v_revenue_detail` | 视图 | 抽水与离座费 | 两类收入分列，代理应计不重复算收入 |
| `v_commission_current_statement` | 视图 | 当前代理日账 | 每代理/资产/业务日取最高版本 |
| `v_operation_pending_review` | 视图 | 待确认操作 | UNKNOWN、待生效、未清算、待重算分别分类 |
| `v_recovery_case_funds` | 视图 | 恢复案件资金明细与分资产合计 | 从 `recovery_case_item` 汇总，不跨资产合并，不以案件头缓存覆盖账本 |

所有后台视图必须在服务层叠加动作权限和资源范围；不能只靠前端筛选 `club_id`。如采用 PostgreSQL RLS，应把 RLS 作为纵深防御，仍保留服务层鉴权和审计。

## 16. 核心约束与索引清单

### 16.1 必须由数据库保证

1. 玩家最多一个活动操控会话、一个活动真人入座会话。
2. 玩家最多一个当前归属、一个待生效归属迁移。
3. 每个物理座位只有一条 `room_seat_occupancy`；预约、正式入座和空闲状态互斥，所有流转锁定同一行。
4. 每个 `seat_session` 最多一个 PENDING 补码。
5. `request_id`、`action_id`、`settlement_id`、账务幂等键均唯一；动作接受和拒绝结果都持久化，同号同参数返回原结果，同号异参数拒绝。
6. 每手房间号+手号唯一；动作、事件、底池在手内顺序唯一。
7. 结算守恒；复式账本每个 POSTED 事务至少两条分录、同一资产且 `sum(delta_amount)=0`，每行满足 `balance_after=balance_before+delta_amount`。
8. 金额为正整数最小单位；账户和玩家可用余额不得在不允许时为负。
9. 发布后的规则、费用、协议版本和房间快照不可更新。
10. 审计、账本分录、动作、事件、派奖、计提调整只追加，不更新不删除；账本原交易不得因冲正改状态。
11. 私牌申请目标和实际访问目标必须引用同手 `hand_player`；每次访问只消费一个唯一120秒授权，访问者必须等于获准人。
12. 调款的敏感授权、业务操作、调款记录和账本交易一一绑定；同一授权不得被第二次消费。
13. 原始代理归因按手牌、池和玩家唯一；每条原始归因最多一个冲正事件，不使用可空列普通唯一约束替代部分唯一索引。
14. 玩家、后台和系统消息分别满足幂等；发送者字段组合与 `sender_type` 一致。
15. 用户屏蔽不得指向自己；同一对用户最多一条ACTIVE关系，屏蔽不作用于SYSTEM或客服巡检消息。
16. 相同规则摘要允许创建多个独立房间快照；摘要只校验内容，不承担业务唯一性。
17. 邀请提交、审核和后续状态迁移分别绑定业务操作；邀请校验请求同号同参只保存一个结果。
18. 同俱乐部直接代理历史、同管理员角色/范围授权的有效区间不得重叠；撤权与权限版本、会话失效同事务提交。
19. 私牌审批决定和实际读取分别消费参数绑定的敏感授权，授权与操作号复合绑定。
20. 恢复冻结金额必须按玩家、资产、账户或原交易落到 `recovery_case_item`，不得只保存无资产汇总值。

跨行守恒、发布不可变和状态迁移使用受限数据库函数与约束触发器兜底；业务逻辑只在 Node 权威服务执行；数据库只保不可绕过的不变量、持久化与并发安全，见架构 ADR-009。账本、调款、动作、代理归因、座位占用、邀请状态、代理变更、权限授予、恢复处置和私牌审批/读取函数为强制写/读入口，不只是实现建议。

### 16.2 跨表约束实现矩阵

本矩阵是新增 Flyway 迁移的强制输入；V001～V014 已冻结，不重新生成。标记为受限函数的规则必须同时撤销应用角色对底层表的直接写权限；不能仅在 Java 服务中实现同名校验。

| 规则 | 主要对象 | 数据库实现 | 最低验证 |
| --- | --- | --- | --- |
| 模板、快照、房间、手牌同源 | `room_rule_snapshot`、`room`、`hand` | 复合唯一键与复合外键；循环引用后置创建 | 交叉替换模板或快照必须触发 FK 失败 |
| 当前会话、归属和活动关系唯一 | `player_session`、`seat_session`、`club_membership`、`mute_record` | 不依赖 `now()` 的部分唯一索引；受限函数先收口自然过期记录 | 100 并发只允许一个活动结果 |
| 座位预约、会话和占用行一致 | `room_seat_occupancy`、`seat_reservation`、`seat_session` | 可延迟循环外键、字段组合 CHECK、统一座位受限函数和行锁；预约为必选前置，过期拒绝 | 抢座、过期、买入、离座无悬空引用 |
| 动作请求和动作事实一致 | `hand_action_request`、`hand_action`、`hand_player` | 受限函数锁定请求；约束触发器校验手牌、玩家、会话和来源一致；请求到事实一对零或一 | 拒绝请求无动作；接受请求最多一条且上下文相同 |
| 手牌玩家、底牌、底池和派奖一致 | `hand_player`、`hand_card`、`hand_pot*` | 同手复合外键或 DEFERRABLE 约束触发器；发牌/结算函数一次提交 | 非参与者不得持牌、贡献或获池；牌组不得重复 |
| 账本同资产、零和及余额不越界 | `ledger_transaction`、`ledger_entry`、`ledger_account` | 撤销直接写权限；`post_ledger_transaction` 排序锁账户并校验跨行合计 | POSTED 至少两行、同资产、合计零；受限账户不为负 |
| 敏感授权与业务操作绑定 | `sensitive_authorization` 及调款、权限、私牌对象 | `(id, operation_id)` 复合引用、授权行锁和单次消费函数 | 错配、过期、重复消费、撤权和旧会话全部拒绝 |
| 权限和代理有效区间不重叠 | `admin_user_role`、`admin_scope_grant`、`club_agent_history`、`system_policy_version` | `btree_gist`、规范化空值和 `tstzrange` 排斥约束；同一 scope 的宽/窄授权重叠另用约束触发器；跨 scope 按 ADR-012 组合 | 并发重叠写入最多一个成功 |
| 多态目标真实存在且类型匹配 | `invite.target_id`、`admin_scope_grant.scope_id`、`ledger_account.owner_id`、审计对象 | 受限函数加约束触发器；按类型查询对应目标，核心对象不得只由前端或 ORM 校验 | 不存在目标或类型错配写入失败 |
| 恢复明细与资产、来源、处置一致 | `recovery_case_item`、账户、原交易、处置交易、资金会话 | `num_nonnulls` CHECK；复合资产外键或约束触发器；案件内规范化来源防重；受限恢复函数校验处置分录 | 跨资产、空来源、重复来源、错误处置交易均拒绝 |
| 发布对象和事实表不可改写 | 版本表、快照、账本分录、动作、事件、审计、访问日志 | 表级权限加拒绝 UPDATE/DELETE 触发器；允许的状态收口只通过专用函数 | 应用角色直接更新或删除失败 |
| 状态枚举和字段组合合法 | 所有 `status/type/mode/source/result` 字段 | `varchar + CHECK`；终态时间、原因、引用采用组合 CHECK | 非法枚举和不完整终态写入失败 |

### 16.3 高价值索引

| 表 | 索引 |
| --- | --- |
| `app_user` | `(game_id)`、`(status, registered_at desc)`、昵称 trigram |
| `player_identity` | `(provider, provider_subject)`唯一、`(user_id, provider) WHERE unbound_at IS NULL`唯一、`(id, user_id)`和`(id, provider)`复合引用键 |
| `local_credential` | `(identity_id)`共享主键；通过复合外键限定 LOCAL 身份 |
| `player_session` | `(user_id) WHERE revoked_at IS NULL`唯一、`(expires_at) WHERE revoked_at IS NULL`、`(session_token_hash)`唯一；身份与玩家复合同源 |
| `club_agent_history` | `(club_id) WHERE effective_to IS NULL`唯一、同俱乐部有效时间范围排斥、`(operation_id)`唯一 |
| `club_membership` | `(user_id) WHERE status='CURRENT'` 唯一、`(user_id) WHERE status='PENDING'` 唯一、`(club_id, status, user_id)` |
| `invite` | `(invite_code)`、`(token_hash)`、`(target_type, target_id, created_at desc)` |
| `invite_application` | `(status, created_at)`、`(applicant_user_id, created_at desc)`、`(submit_operation_id)`唯一、`(review_operation_id) WHERE review_operation_id IS NOT NULL`唯一 |
| `invite_application_event` | `(application_id, seq_no)`唯一、`(operation_id, application_id)`唯一、`(application_id, occurred_at desc)` |
| `invite_redemption` | `(request_id)`唯一、`(invite_id, user_id, occurred_at desc)` |
| `system_policy_version` | `(policy_key, version_no)`唯一、同策略 PUBLISHED 有效区间排斥 |
| `room` | `(club_id, status, created_at desc)`、`(status, scheduled_open_at)`、`(status, ends_at)` |
| `room_rule_snapshot` | `(content_digest)`普通索引，不唯一 |
| `room_seat_occupancy` | `(room_id, seat_no)` 唯一、`(user_id) WHERE status IN ('RESERVED','OCCUPIED')`、`(status, expires_at) WHERE status='RESERVED'` |
| `seat_session` | `(user_id) WHERE status NOT IN ('CLOSED')` 唯一、`(room_id, seat_no) WHERE status NOT IN ('CLOSED')` 唯一 |
| `hand` | `(room_id, hand_no)` 唯一、`(settled_at desc)`、`(status, updated_at)` |
| `hand_action_request` | `(action_code)` 唯一、`(hand_id, requested_at desc)`、`(result, requested_at)` |
| `hand_action` | `(hand_id, seq_no)`唯一、`(action_request_id)`唯一 |
| `ledger_transaction` | `(idempotency_key)`、`(user_id, created_at desc, id)`、`(hand_id)`、`(status, created_at)` |
| `ledger_entry` | `(account_id, posted_at desc, id)`、`(transaction_id, line_no)`、`(transaction_id, account_id)` 唯一 |
| `manual_adjustment` | `(sensitive_authorization_id)`唯一、`(operation_id)`唯一、`(ledger_transaction_id) WHERE ledger_transaction_id IS NOT NULL`唯一 |
| `commission_attribution` | `(hand_id, pot_id, user_id) WHERE original_event_id IS NULL`唯一、`(original_event_id) WHERE original_event_id IS NOT NULL`唯一、`(agent_id, asset_id, business_date)`、`(status, business_date)` |
| `commission_daily_statement` | `(agent_id, asset_id, business_date, version_no desc)` |
| `chat_message` | 玩家/后台/系统三组部分唯一幂等索引、`(room_id, sent_at desc, id)` |
| `mute_record` | 规范化`(user_id, room_id) WHERE status='ACTIVE'`唯一、`(issued_operation_id)`唯一、`(revoked_operation_id) WHERE revoked_operation_id IS NOT NULL`唯一、`(status, ends_at)` |
| `user_chat_block` | `(blocker_user_id, blocked_user_id) WHERE status='ACTIVE'`唯一、`(blocked_user_id, status)` |
| `support_ticket` | `(assignee_admin_id, status, updated_at desc)`、`(club_id, status)` |
| `admin_activation_token` | `(token_hash)`唯一、`(admin_id, purpose) WHERE used_at IS NULL AND revoked_at IS NULL`唯一、`(expires_at) WHERE used_at IS NULL AND revoked_at IS NULL` |
| `admin_user_role` | 同管理员角色有效时间范围排斥、`(admin_id, revoked_at, valid_until)` |
| `admin_scope_grant` | 规范化作用域与权限有效时间范围排斥、`(admin_id, scope_type, scope_id) WHERE revoked_at IS NULL` |
| `business_operation` | `(request_id)`、`(request_status, submitted_at)`、`(target_type, target_id)` |
| `audit_log` | `(operator_admin_id, occurred_at desc)`、`(object_type, object_id, occurred_at desc)`、`(operation_id)` |
| `recovery_case_item` | `(case_id, item_no)`唯一、`(original_transaction_id)`、`(user_id, asset_id, status)` |

### 16.4 分区与保留

| 数据 | V1物理结构 | 未来分区前置条件 | V1统一保留基线 |
| --- | --- | --- | --- |
| `hand_event`、`hand_action_request`、`hand_action`、`player_hand_stat` | 普通表+时间索引 | 表规模或维护窗口达到已记录阈值；建立全局 ID 注册表并完成复合外键迁移 | 牌谱及动作请求结果 180 天 |
| `ledger_entry` | 普通表+时间索引 | 不以删除权威账本换取分区便利；先完成可验证冷归档和期初余额方案 | 在线查询 365 天，权威分录按归档策略可恢复 |
| `audit_log`、玩家/后台认证事件 | 普通表+时间索引 | 建立全局审计事件注册表并处理工单/安全引用 | 365 天 |
| `chat_message` | 普通表+时间索引 | 建立非分区消息 ID/客户端幂等注册表 | 30 天；工单证据单独保全 |
| `report_*`、`ticket_*` | 普通表 | 若未来按年分区，先迁移证据和私牌访问外键 | 365 天，证据至少至结案 |
| `analytics_event` | 普通表+时间索引 | 建立非分区事件 ID 注册表后可按月 RANGE | 由指标策略确认 |
| `test_deal_run` | 普通表 | 若清理主体记录，须另存永久 `run_id` 墓碑以禁止复用 | 365 天 |
| `asr_job` 临时音频对象 | 不以主表分区代替对象生命周期 | 不适用 | 成功即删；失败最长 24 小时 |

以上是产品与技术共同采用的V1基线，不宣称满足任何特定法域的法律要求。到期清理不能删除仍被工单、纠错、审计或法定保全引用的记录；工单证据至少保留至结案。“账本365天”表示在线查询基线，不得直接销毁无法恢复的权威分录。未来启用分区必须先通过真实 PostgreSQL 16 DDL、外键、全局幂等和分区删除测试，不得为删除分区而取消核心引用完整性。

## 17. 关键枚举字典

| 枚举 | 值 |
| --- | --- |
| 玩家状态 | `ACTIVE, DISABLED` |
| 俱乐部状态 | `ACTIVE, FROZEN, ARCHIVED` |
| 房间状态 | `SCHEDULED, WAITING, RUNNING, DRAINING, PAUSED_RECOVERY, CLOSED` |
| 座位会话状态 | `WAIT_NEXT_HAND, PLAYING, AUTO_PLAY, LEAVE_PENDING, ZERO_STACK_HOLD, SETTLING, CLOSED` |
| 手牌状态 | `PREPARING, STARTED, SETTLING, SETTLED, VOID, RECOVERY_REQUIRED` |
| 街道 | `PREFLOP, FLOP, TURN, RIVER, SHOWDOWN, COMPLETE` |
| 操作请求状态 | `SUBMITTING, UNKNOWN, FAILED, SUCCEEDED` |
| 动作请求结果 | `PENDING, ACCEPTED, REJECTED` |
| 账本存储状态 | `PENDING, POSTED, FAILED`；冲正使用新的 POSTED `REVERSAL` 交易 |
| 账本展示状态 | `PENDING, POSTED, REVERSED, FAILED`；`REVERSED` 由有效完整冲正派生，不回写原交易 |
| 消息发送者 | `USER, ADMIN, SYSTEM` |
| 用户屏蔽状态 | `ACTIVE, REVOKED` |
| 邀请目标 | `ROOM, CLUB` |
| 邀请策略 | `EXPIRING_24H, PERMANENT_REVIEW` |
| 邀请申请 | `PENDING, APPROVED, REJECTED, WITHDRAWN, EXPIRED, FROZEN, CANCELLED` |
| 规则版本 | `DRAFT, PUBLISHED, RETIRED` |
| 后台账号 | `INVITED, ACTIVE, DISABLED, RESET_PENDING` |
| 工单 | `OPEN, IN_REVIEW, RESOLVED, REJECTED` |
| 预设发牌来源 | `RANDOM, SCRIPTED_TEST` |
| 前端错误分类 | `AUTH_REQUIRED, FORBIDDEN, INVALID_CODE, INVITE_EXPIRED, INVITE_REVOKED, RATE_LIMITED, ROOM_CLOSED, SEAT_TAKEN, RESERVATION_EXPIRED, INSUFFICIENT_BALANCE, INELIGIBLE, RESULT_UNKNOWN, SERVICE_UNAVAILABLE` |

精确错误码继续细分，客户端只稳定依赖错误分类。空值表示未知/不适用，零值表示真实的 0，两者不得混用。

## 18. 参考项目迁移映射

| 参考对象 | 新模型 | 处理 |
| --- | --- | --- |
| `th_accounts` | `app_user` + `player_identity` + `local_credential` + `ledger_account` + `wallet_balance_projection` + 后台身份表 | 旧登录名/密码默认不迁；`chips` 不直接迁为可信余额；需逐币种对账。若未来迁移资金，仅允许以平衡的有符号零和分录过账，禁止直接写账户余额。`is_admin` 不迁为授权 |
| `th_invites` | `invite` / `invite_application` | 旧表是注册邀请码，语义不足；只读留存，不能冒充 ROOM/CLUB 邀请 |
| `th_rooms` / `th_room_games` | `room` + `room_rule_snapshot` + `room_state_snapshot` | 将元数据、冻结规则和引擎快照分离 |
| `th_room_seats` | `room_seat_occupancy` + `seat_session` + `hand_player` | 当前座位占用、资金会话与单手状态分离；同座位并发由唯一占用行仲裁，金额转整数最小单位 |
| `th_room_actions` / seat actions | `hand_action_request` + `hand_action` + `hand_event` | 接受和拒绝请求均保存幂等结果；已接受事实统一 state_version、目标额与增量 |
| `th_room_deck_cards` / board/cards | `hand_card` | 补足牌序位置、角色、可见性和加密 |
| `th_room_results` / awards | `hand_pot` + contribution + award + settlement | 明确主边池、资格、尾分、抽水与守恒 |
| `th_room_summaries` | `seat_session` 终态 + `v_player_session_result` | 不覆盖历史快照，可由手牌事实聚合 |
| `th_hands` | `hand` + `player_hand_stat` + 安全回放视图 | 删除 3000 手硬截断；修正 VPIP 历史口径 |
| `th_login_logs` | `player_login_event` | 保留追加审计，统一 LOCAL/TELEGRAM 来源并增强 request_id、方法和脱敏；不导入旧密码、令牌或原始身份载荷 |
| JSON `accounts/rooms/hands` | 只读迁移源 | 新环境默认不导入；未来迁移须映射、对账、幂等和异常清单 |

参考项目没有可安全继承的私牌审批/访问授权模型。`private_card_access_request_player`、`private_card_access_log_player` 及其受限读取函数属于新建安全域，不从旧库迁移授权、会话或历史访问资格。

## 19. 默认方案裁定

以下裁定于2026-10-20形成，并于2026-10-21补充首期 Web 身份入口，是V1建模与实施基线；“已裁定”不表示DDL、代码、部署或验收已经完成。

| # | 主题 | 默认方案 | 状态 |
| --- | --- | --- | --- |
| 1 | 私牌专项 | 仅已结束手、有效工单、限定手牌/玩家/用途；申请人与审批人不同，由具备专项审批权的超管审批；批准后30分钟；每次访问另需120秒参数绑定TOTP；会话、撤权或工单失效立即失效；逐次审计 | 已裁定 |
| 2 | 权限种子 | 最小授权；运营仅俱乐部范围，客服仅分配/授权工单及公开桌面，代理仅本人协议/汇总/佣金只读；IP、私牌、全局审计/导出独立权限且角色默认不继承；资金调整仅超管；导出不超页面查询字段权 | 已裁定 |
| 3 | 七组买入 | V1仅发布TEST资产、`SB/BB=1/2`、买入`100–300`、长牌8席2小时、Ante/抓头关闭；其余六组DRAFT，不推导盲注、资产或授权范围，也不阻塞V1 | 已裁定 |
| 4 | 数据保留 | 牌谱180天；账本、审计、举报/工单365天；聊天30天；工单证据至少至结案；ASR成功即删、失败最长24小时；不作特定法域合规声明 | 已裁定 |
| 5 | 真实充提 | 正式列为P2独立专项；本期仅TEST资产，不创建虚假充值订单、地址或到账状态 | 明确后置 |
| 6 | 人工动作 | 不提供人工佣金补结，继续自动扫描脏日；拒绝后须使用新邀请重新申请，不提供解除拒绝；超管可撤销任意业务邀请，运营仅撤本人签发且仍在范围的邀请 | 已裁定 |
| 7 | 旧数据 | 使用新环境；旧库只读留存；不迁移余额、管理员、密码、令牌、认证身份或权限 | 已裁定 |
| 18 | 玩家认证身份 | 首期 LOCAL 注册登录；`app_user` 与身份/凭据分离；未来 TELEGRAM 只绑定既有玩家且冲突拒绝，不新建第二套钱包、归属或战绩 | 已裁定 |
| 8 | PostgreSQL工程 | PostgreSQL 16、Flyway、HikariCP；生产托管主备或同等高可用；每日全量备份+WAL连续归档；初期不分库分表 | 已裁定 |
| 9 | 动作请求幂等 | 接受与拒绝结果均写 `hand_action_request`；已接受动作另写不可变 `hand_action`，同ID同参返回原结果、异参拒绝 | 已裁定 |
| 10 | 资金与归因防重 | 调款授权和operation复合绑定且单次消费；代理原始归因与冲正采用两组部分唯一索引及受限函数 | 已裁定 |
| 11 | 账本展示状态 | 数据库存储 `PENDING/POSTED/FAILED`；客户端 `REVERSED` 由有效完整冲正派生并返回冲正交易ID/时间 | 已裁定 |
| 12 | 消息与屏蔽 | USER/ADMIN/SYSTEM分别幂等；用户屏蔽关系化且仅过滤普通玩家消息，系统和客服巡检不可屏蔽 | 已裁定 |
| 13 | 房间快照摘要 | 同一模板和参数允许创建多个独立不可变快照；摘要仅作完整性校验和普通索引，不作全局唯一键 | 已裁定 |
| 14 | 邀请与领域幂等 | 提交、审核和状态事件分别绑定业务操作；一对一领域结果数据库防重；同请求号异参数拒绝 | 已裁定 |
| 15 | 权限及代理历史 | 活动授权和当前代理唯一、有效区间排斥；变更通过受限函数与权限版本、会话撤销原子提交 | 已裁定 |
| 16 | 高风险授权边界 | 权限变更和私牌审批/读取均复合绑定敏感授权与业务操作，由受限函数单次消费 | 已裁定 |
| 17 | 恢复资金明细 | 恢复案件按玩家、资产、账户/原交易保存明细，案件总额按资产汇总，不保存无资产权威总额 | 已裁定 |

## 20. DDL 落地顺序

工程基线：使用Flyway管理版本化迁移且禁止修改已发布迁移；Java服务使用HikariCP并按数据库容量设置连接池上限。生产采用托管主备或同等高可用拓扑，每日全量备份并连续归档WAL，恢复演练须验证备份可用性；V1不分库分表、核心事实表暂不分区，优先通过索引、读模型和容量监控演进，达到容量阈值后再按ADR-DB-001的前置条件引入分区。具体RPO/RTO、托管服务、密钥与归档介质仍由部署评审在不降低本基线的前提下确定。

建议按以下依赖顺序生成迁移脚本：

1. 扩展与 Schema：`pgcrypto`、`citext`、`btree_gist`、可选 `pg_trgm`，创建 `poker` Schema。
2. 基础身份、资产与控制面：`app_user`、`asset`、后台身份、角色、权限和 `business_operation`；后续所有敏感写操作均可先引用业务操作记录。
3. 组织与版本：代理、俱乐部、互斥代理历史、归属、邀请申请事件、规则/费用/协议版本。
4. 房间与座位：规则快照、房间、`room_seat_occupancy`、预约、资金会话和补码；先创建可独立成立的列与约束。
5. 账本：账户、事务、有符号分录、余额投影和调款，并创建仅对服务角色开放的 `post_ledger_transaction`、`execute_manual_adjustment` 受限函数及账本展示视图。
6. 手牌：手牌、玩家、牌、动作请求、已接受动作、事件、底池、结算和统计，并创建 `submit_hand_action` 受限函数。
7. 代理日账、关系化代理归因、三类发送者消息、用户屏蔽、工单、恢复资金明细和关系化私牌授权目标/访问目标，以及 `post_commission_attribution`、`change_club_agent`、`apply_admin_grant`、`decide_private_card_access_request`、受限私牌读取/恢复处置函数、审计、导出和分析事件。
8. 跨域与循环依赖收口：追加 `room_seat_occupancy` 与 `seat_reservation`/`seat_session`、`ledger_transaction` 与 `seat_session`/`hand`、权限授予与敏感授权等后置外键，以及其他循环外键、部分唯一索引、`btree_gist` 排斥约束、安全视图和只追加权限；V1不创建核心事实表分区。
9. 种子数据：TEST 资产、GENERAL 0% 协议、默认俱乐部、系统角色/权限、费用与规则测试种子。
10. 使用真实 PostgreSQL 16 执行全量 Flyway 迁移、回滚替代演练、约束与事务集成测试；不得仅用H2或SQL语法静态检查代替。

### 20.1 P0及需求覆盖验收门禁

以下测试是进入联调环境前的最低架构适应度门禁，任何一项失败都不得以应用层补偿或人工操作替代数据库约束。

| 门禁 | 必测场景 | 通过标准 |
| --- | --- | --- |
| 分区与全局唯一 | 在全新 PostgreSQL 16 实例顺序执行全部 Flyway 脚本，并验证外键、全局业务号/幂等键和保留清理脚本 | V1普通表模型可一次建成；核心外键和全局唯一约束真实生效；清理任务不删除仍被引用或保全的数据 |
| 房间快照 | 使用同一模板及完全相同参数并发创建100个不同房间；同request_id重复创建 | 不同请求可各自创建独立快照和房间；同一请求只返回同一房间；摘要相同不触发唯一冲突 |
| 私牌授权 | 自审、审批授权与operation错配、审批授权重复消费、请求非本手玩家、30分钟审批过期、120秒访问授权过期、同一访问授权重复使用、撤权、会话失效、权限版本变化 | 仅合法首次审批/读取成功；其余均拒绝且留下不可回滚的 `DENIED` 审计；成功访问留下唯一 `ALLOWED` 审计并精确记录玩家范围 |
| 权限与代理区间 | 并发授予相同角色/范围、重叠有效区间、自提权、撤权后旧会话继续调用、并发切换同俱乐部代理 | 不存在重叠活动授权或代理历史；自提权拒绝；撤权、版本递增及会话/授权失效原子生效；当前代理与历史一致 |
| 邀请幂等 | 同一提交、审核、撤销和校验请求各100并发，同号异参数，并发审核与撤销竞争 | 每个操作只形成一个领域结果和一条状态事件；申请与审核操作可分别追溯；失败重试不重新解释原结果 |
| 座位并发 | 100个并发事务抢同一房间同一座位，并覆盖预约转买入、预约过期与离座重入 | 同一时点最多一个事务成功占用；`room_seat_occupancy`、预约、会话和账本要么全部提交，要么全部回滚；无超卖、悬空预约或孤立托管资金 |
| 复式账本 | POSTED零和、同键同参重试、同键异参重试、完整冲正、受限账户余额不足，并对并发账户过账做死锁测试 | 每笔POSTED交易至少两条同资产分录且 `sum(delta_amount)=0`；同参返回原结果、异参拒绝；冲正后原交易与冲正交易净额为0；受限账户不为负且锁顺序稳定 |
| 动作幂等 | 已接受和已拒绝 action_id 重试、同ID异参数、旧state_version和100并发同ID | 同参始终返回首次结果；异参拒绝；拒绝结果不随异常回滚；最多生成一条 `hand_action` 和对应事件 |
| 调款授权 | 同一120秒授权100并发执行、授权与operation错配、过期/撤权/会话失效、同操作异参数 | 只有合法首次调用成功；授权、调款、操作和账本一一绑定；其余拒绝且不产生资金分录 |
| 代理归因 | 100并发写同一手/池/玩家归因、并发重复冲正、包含NULL的原始事件唯一性 | 原始归因仅一条；每条原始事件最多一条冲正；不存在因PostgreSQL NULL唯一语义产生的重复计提 |
| 账本展示状态 | 查询未冲正、已完整冲正及冲正失败交易 | 原交易数据库状态始终POSTED；仅存在有效POSTED冲正时API派生REVERSED并返回冲正ID和时间 |
| 聊天与屏蔽 | 玩家/客服/系统消息分别100次重试；玩家屏蔽、解除、屏蔽自己；读取普通、系统和客服消息 | 每类消息仅一条；普通被屏蔽玩家消息过滤；SYSTEM和客服巡检仍可见；原消息及举报证据不删除 |
| 恢复资金明细 | 多玩家、多资产测试数据进入同一恢复流程，分别冲正、释放或保持核查 | 每笔金额均关联资产及账户/原交易/会话之一；不同资产不合并；处置交易与明细、案件和审计一致 |

除上述门禁外，还应覆盖权限越权、结算守恒、恢复演练、保留清理、只追加审计和脱敏导出。未来若引入分区，必须新增跨分区外键、全局幂等、分区裁剪和安全删除的专项验收，不得复用V1普通表测试结论。

本字典刻意不提供可直接执行的 DDL：评审通过后应从本模型生成独立版本化迁移，并用 Testcontainers/PostgreSQL 16 验证约束、事务和查询计划。




