实施基线 / PostgreSQL数据字典
STORM POKER / IB-1.1

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

风暴扑克 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. 领域关系总览

关系图文本定义
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 验证约束、事务和查询计划。

风暴扑克 · 统一实施基线 IB-1.1文档已发布 · 软件开发与验收按门禁推进

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