展示字段契约
版本V2.1-review。本清单把模块与页面规格中的字段摘要,结合《数据库实施/PostgreSQL数据字典》V1.4-review与已落地安全读视图,展开为设计、API、研发和测试可共同评审的页面字段契约。完整字段矩阵见fields.csv。它描述“应该展示什么、从哪里来、如何裁剪”,不证明接口、查询、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. 评审与验收门槛
- 产品确认标签、顺序、空值与状态含义;UI确认列表密度、详情分组和危险动作确认层级。
- 后端为每个字段给出API类型、来源、查询计划和权限策略;对“建议读模型”明确新增迁移或服务查询方案。
- 安全评审验证无权字段在响应层被裁剪,而不是只在前端隐藏;导出、详情、下钻和合计使用同一范围。
- 测试至少覆盖真实零值、历史未知、跨币种、投影延迟、撤权、越权ID、CSV公式注入和导出下载复核。
- 字段清单中的“可导出”仅代表产品允许进入导出设计,实际开放仍依赖BKR-049、权限种子、查询性能和验收证据。