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

# 字段与事件契约

版本：D2.2  
状态：产品与 UI 交付契约；正式接口路径、传输协议和数据库结构由技术评审确定。

## 1. 通用原则

- 客户端只展示服务端确认的业务事实。
- 金额使用整数最小单位传输，并同时返回 `asset_id` 与展示精度；不得使用浮点数记账。
- 时间使用服务端时间和带时区的 ISO 8601 值；倒计时以服务端截止时间计算。
- 每次产生业务结果的提交携带唯一 `request_id`；同号同参数返回第一次结果，同号异参数返回 `IDEMPOTENCY_CONFLICT`，不得因当前状态变化重新解释旧请求。
- 空值、未知值和零值必须区分；无分母统计显示“—”，不显示 0%。
- 所有敏感字段由服务端按权限裁剪，不能先下发再由前端隐藏。

## 2. 通用响应字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `request_id` | string | 提交型必填 | 客户端生成的幂等请求号 |
| `business_id` | string | 成功或已受理时 | 买入、开房、申请、清算等业务记录号 |
| `status` | enum | 是 | `IDLE/SUBMITTING/UNKNOWN/FAILED/SUCCEEDED` 或领域只读状态 |
| `server_time` | datetime | 是 | 服务端当前时间 |
| `updated_at` | datetime | 是 | 当前数据版本更新时间 |
| `error.category` | enum | 失败时 | 前端稳定依赖的错误分类 |
| `error.code` | string | 失败时 | 后端精确错误码，便于追踪 |
| `error.message` | string | 否 | 安全、可面向用户的补充说明 |
| `retry_after_seconds` | integer | 限流时 | 允许再次校验的等待秒数 |

## 3. 关键对象

### 3.1 俱乐部与成员

| 字段 | 类型 | UI 用途 | 约束 |
| --- | --- | --- | --- |
| `club_id` | string | 定位当前俱乐部 | 不以名称作为唯一键 |
| `club_name` | string | 标题与邀请说明 | 服务端过滤不安全字符 |
| `membership_status` | enum | 当前归属/审核状态 | 归属改变只由服务端终态确认 |
| `member_count` | integer | 俱乐部摘要 | 不等于在线人数 |
| `display_name` | string | 成员目录 | 普通成员不可见 TG ID、IP、余额、佣金 |
| `game_id` | string | 精确搜索与公开身份 | 不等于登录凭据 |

### 3.2 房间

| 字段 | 类型 | UI 用途 | 约束 |
| --- | --- | --- | --- |
| `room_id` | string | 房间详情、邀请、恢复 | 唯一且不可由前端猜测 |
| `room_status` | enum | 等待、进行中、暂停、关闭 | 决定是否允许预约和买入 |
| `game_variant` | enum | 长牌/短牌 | 长牌 8 席；短牌 6 席 |
| `seat_count` | integer | 座位布局 | 与玩法模板一致 |
| `occupied_seats` | integer | 列表与详情 | 由服务端快照提供 |
| `sb_amount` / `bb_amount` | money | 盲注展示 | 同一资产单位 |
| `buyin_min` / `buyin_max` | money | 滑杆范围 | 客户端不得扩大范围 |
| `rule_version` | string | 入桌披露 | 开房成功后冻结 |
| `fee_version` | string | 服务费披露 | 与房间规则快照关联 |
| `ends_at` | datetime | 剩余时间 | 以服务端时间计算 |

### 3.3 座位预约与买入

| 字段 | 类型 | UI 用途 | 约束 |
| --- | --- | --- | --- |
| `seat_no` | integer | 座位按钮 | 范围由 `seat_count` 决定 |
| `seat_status` | enum | 可选/已占/已选/锁定 | 已占与锁定均不可提交 |
| `reservation_id` | string | 当前预约 | 不作为资金记录号 |
| `reservation_expires_at` | datetime | 15 秒倒计时 | 到期后必须重新预约 |
| `buyin_amount` | money | 买入金额 | 必须在冻结范围内 |
| `available_balance` | money | 可用额度 | 与桌内托管分开 |
| `effective_timing` | enum | 当前手后生效 | 进行中牌桌不得立即获得底牌 |
| `seat_session_id` | string | 买入成功后的座位会话 | 账单和战绩关联键 |

### 3.4 开房与邀请

| 字段 | 类型 | UI 用途 | 约束 |
| --- | --- | --- | --- |
| `template_id` | string | 已授权模板 | 只允许选择服务端返回的已发布模板 |
| `template_version` | string | 确认页与房间快照 | 创建时冻结 |
| `create_permission` | boolean | 显示开房入口 | 前端隐藏不替代服务端校验 |
| `invite_type` | enum | `ROOM/CLUB` | 两类邀请不得串流程 |
| `invite_status` | enum | 有效、过期、撤销、冻结 | 每次进入和批准时重新校验 |
| `application_id` | string | 加入申请状态 | 重开小程序后可恢复 |
| `application_status` | enum | 审核中、通过、拒绝、撤销、失效、冻结 | 审核中保留原归属 |
| `submit_request_id` | string | 申请提交结果查询 | 与审核请求分离；重复提交不新增待审申请 |
| `review_request_id` | string/null | 审核结果查询 | 批准或拒绝时生成；不得复用提交请求号 |
| `application_event_id` | string | 状态轨迹与刷新定位 | 审核、撤销、冻结、失效、生效按服务端追加事件返回 |

### 3.5 牌局与账本

| 字段 | 类型 | UI 用途 | 约束 |
| --- | --- | --- | --- |
| `hand_id` | string | 当前手、回放、账单关联 | 每手唯一 |
| `street` | enum | 翻前/翻牌/转牌/河牌/摊牌 | 服务端事件推进 |
| `action_deadline` | datetime | 行动倒计时 | 客户端不自行判定最终超时结果 |
| `action_source` | enum | `PLAYER/TIMEOUT/SYSTEM` | 超时和系统动作由服务端生成稳定幂等号，仍返回动作事实 |
| `legal_actions` | array | 动作按钮 | 未列出的动作必须禁用 |
| `to_call` | money | 跟注金额 | 与“加到”目标额分开 |
| `raise_to_min` / `raise_to_max` | money | 加注目标范围 | 表示本街目标总额 |
| `pot_total` | money | 总底池 | 不与本街投入混用 |
| `ledger_transaction_id` | string | 账单记录 | 查询不重新执行业务 |
| `ledger_status` | enum | `PENDING/POSTED/REVERSED/FAILED` | 展示状态；`REVERSED` 仅由有效完整冲正交易派生，原交易存储状态仍为 `POSTED` |
| `reversal_transaction_id` | string/null | 冲正关联 | `ledger_status=REVERSED` 时必填，指向新的 POSTED REVERSAL 交易 |
| `reversed_at` | datetime/null | 冲正时间 | `ledger_status=REVERSED` 时必填，取冲正交易过账时间 |

## 4. 前端错误分类

前端只依赖稳定的 `error.category`，后端精确错误码可继续细分。

| 分类 | 用户含义 | 前端动作 |
| --- | --- | --- |
| `AUTH_REQUIRED` | TG 身份无效或过期 | 重新完成身份确认 |
| `FORBIDDEN` | 当前角色无权操作 | 隐藏非法入口并展示无权限结果 |
| `INVALID_CODE` | 邀请码格式正确但不可识别 | 保留输入，允许修改 |
| `INVITE_EXPIRED` | 邀请已过期 | 不进入目标页面 |
| `INVITE_REVOKED` | 邀请已撤销 | 不允许申请或加入 |
| `RATE_LIMITED` | 校验过于频繁 | 展示 `retry_after_seconds` |
| `ROOM_CLOSED` | 房间已关闭 | 返回房间列表 |
| `SEAT_TAKEN` | 座位被其他玩家抢先 | 清除当前预约，不冻结金额 |
| `RESERVATION_EXPIRED` | 预约超时 | 重新选座 |
| `INSUFFICIENT_BALANCE` | 可用额度不足 | 不提交买入 |
| `INELIGIBLE` | 不满足入桌资格 | 说明可公开原因 |
| `RESULT_UNKNOWN` | 原请求结果未知 | 只查询原请求 |
| `SERVICE_UNAVAILABLE` | 服务暂不可用 | 保留合法输入并重试查询 |

## 5. 分析事件契约

分析事件不作为业务事实来源，不得携带邀请码 token、TG 原始身份、IP、未公开底牌或完整聊天正文。

| 事件 | 触发条件 | 必填属性 |
| --- | --- | --- |
| `CLIENT_SCREEN_VIEW` | 页面可交互后一次 | `screen_id, source, journey_id?` |
| `INVITE_VALIDATION_RESULT` | 邀请校验得到服务端结果 | `invite_type, result, failure_reason?` |
| `CLUB_APPLICATION_SUBMITTED` | 申请明确受理 | `application_id, target_club_id` |
| `ELIGIBLE_ROOM_ENTRY` | 服务端确认具备房间访问资格 | `journey_id, room_id, entry_source` |
| `SEAT_RESERVED` | 座位预约成功 | `journey_id, room_id, seat_no` |
| `BUYIN_SUBMITTED` | 买入请求首次发送 | `journey_id, request_id, room_id` |
| `BUYIN_POSTED` | 买入明确成功入账 | `journey_id, business_id, room_id` |
| `ROOM_CREATE_SUBMITTED` | 开房请求首次发送 | `request_id, template_id, template_version` |
| `ROOM_CREATED` | 开房明确成功 | `business_id, room_id, template_version` |
| `TABLE_ACTION_CONFIRMED` | 服务端确认合法动作 | `room_id, hand_id, street, action_type` |
| `EXIT_SETTLEMENT_CONFIRMED` | 离桌清算明确完成 | `business_id, room_id, seat_session_id` |

`ELIGIBLE_ROOM_ENTRY` 和 `BUYIN_POSTED` 的旅程窗口及去重规则以综合 PRD 20.3 节为准。
