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

# 展示字段契约

版本V2.1-review。本清单把[模块与页面规格](../../docs/ops-modules.html)中的字段摘要，结合《数据库实施/PostgreSQL数据字典》V1.4-review与已落地安全读视图，展开为设计、API、研发和测试可共同评审的页面字段契约。完整字段矩阵见[fields.csv](../../docs/ops-field-matrix.html)。它描述“应该展示什么、从哪里来、如何裁剪”，不证明接口、查询、UI或导出已经实现。

## 1. 使用方式

- `页面/功能 + 区域`是界面字段集边界；“展示字段（按顺序）”是默认桌面端顺序，设计可以调整布局但不得静默删改业务口径。
- 中括号内为建议API字段名或权威数据库字段名；中文为运营界面标签。聚合/派生字段必须由服务端或受控读模型计算，不能由前端拼接后作为资金或状态事实。
- `主要来源`写“已建安全视图”时，指V013迁移已有对象；写“建议读模型”时，仅代表数据字典建议，仍需新增迁移/API实现与测试。
- 每个字段集关联至少一个BKR需求；构建脚本校验16模块和全部59项BKR均被字段清单覆盖。

## 2. 全局展示规则

| 主题 | 统一规则 |
| --- | --- |
| 稳定标识 | 玩家、房间、手牌、会话、操作、流水均显示业务稳定ID；数据库UUID只在排错权限下显示，不以昵称或展示手号替代主键。 |
| 时间 | 默认以Asia/Shanghai显示到秒，并保留原始时区语义；业务日期、提交时间、生效时间、完成时间分列，不把`updated_at`冒充业务时间。 |
| 金额 | 显示“金额 + 资产代码”，按`asset.precision`格式化；API传整数最小单位。跨币种禁止求和，零值显示0。 |
| 比例 | 费率、佣金率按百分比展示并保留足够精度；实际入账金额仍以整数最小单位和权威结算为准。 |
| 状态 | 同时展示业务状态、请求状态和实际生效状态；UNKNOWN、PENDING_EFFECT、SETTLING不得折叠成失败或成功。 |
| 空值 | 数据确实为空显示“—”；历史缺失或不可证明显示“未知”；无权字段不下发、不占位，不用“***”暗示对象存在。 |
| 快照 | 历史昵称、代理、协议、规则和费率优先显示交易/手牌发生时快照，并可在有权限时另链当前对象。 |
| 数据新鲜度 | 汇总、投影、列表详情统一显示`data_cutoff_at`/`projected_at`与完整性状态；服务失败不得伪装成真实空集。 |
| 分页与合计 | 默认近7天、20条/页、最大100；总数、合计、详情和导出复用同一筛选、范围和数据时点。 |
| 敏感信息 | LOCAL/TELEGRAM认证身份、IP、设备、私牌、内部工单、全局审计分别按动作权限裁剪；登录名、provider subject、密码/哈希、令牌、TOTP密钥、恢复码、原始initData和摘要密文永不展示或导出。 |
| 导出 | 仅导出当前字段权限内列；最大31天、默认7天；文本防CSV公式注入，ID按文本，金额不丢精度，下载时再次校验会话和范围。 |

## 3. 数据来源状态

数据库实施基线已建立`v_current_club_membership`、`v_user_wallet_balance`、`v_ledger_transaction_display`、`v_commission_current_statement`、`v_operation_pending_review`、`v_recovery_case_funds`和`v_player_session_result`七个安全读视图。

数据字典中提出但V013尚未建立的`v_ops_daily_metrics`、`v_room_public_summary`、`v_player_stat_period`、`v_hand_replay_public`、`v_revenue_detail`等，在fields.csv中标为“建议读模型”。实现时有两种可接受路径：新增受权限约束的数据库视图/物化视图，或由服务层查询并以同等口径、范围和审计返回。产品要求的是口径一致与最小披露，不预先锁死查询技术。

## 4. 评审与验收门槛

1. 产品确认标签、顺序、空值与状态含义；UI确认列表密度、详情分组和危险动作确认层级。
2. 后端为每个字段给出API类型、来源、查询计划和权限策略；对“建议读模型”明确新增迁移或服务查询方案。
3. 安全评审验证无权字段在响应层被裁剪，而不是只在前端隐藏；导出、详情、下钻和合计使用同一范围。
4. 测试至少覆盖真实零值、历史未知、跨币种、投影延迟、撤权、越权ID、CSV公式注入和导出下载复核。
5. 字段清单中的“可导出”仅代表产品允许进入导出设计，实际开放仍依赖BKR-049、权限种子、查询性能和验收证据。
