# 前端需求

版本：IB-1.1。适用玩家 Web 与若依运营 Web；完整业务正文见[产品需求](../../docs/product.html)，每项需求及验收编号见[需求追踪](../../docs/traceability.html)。

## 客户端职责

玩家端采用 Vue 3 + TypeScript + Vite + Pinia。渲染服务器确认的状态、合法动作、金额和权限，维护输入草稿、提交中、未知结果、明确失败、成功及重连过程。客户端不裁定余额、结算或业务权限。工作台原型控件不进入正式产品。

## 玩家页面与验收

| 模块 | 必须实现 | 关键状态/验收 |
| --- | --- | --- |
| Web认证 | 登录、注册、退出、会话恢复、设备接管、协议接受 | 登录名与昵称分离；密码不可空；重复昵称合法；锁定、限流、会话过期、旧设备失权明确 |
| 主导航 | 游戏、俱乐部、我的 | 登录后默认俱乐部；不增加一级分享导航 |
| 邀请 | 短码或普通HTTPS链接输入，ROOM/CLUB解析 | 无效、过期、撤销、限流、目标冻结；业务邀请不充当注册邀请码 |
| 俱乐部 | 资料、房间列表、成员目录、本人申请及迁移状态 | 普通成员不出现签发、审核、自退或创建俱乐部入口；在手迁移显示待生效 |
| 房间与开房 | 模板选择、规则费用披露、受权开房、排期展示 | 只选服务端返回已发布且已授权的模板；未授权路由与提交均拒绝 |
| 买入 | 选座、15秒预约、金额与费用确认 | 抢座、到期、余额不足、准入失败、关闭、提交中、未知结果及确认成功 |
| 牌桌 | 长牌8席、短牌6席，公共牌、本人牌、底池、动作、位置与截止时间 | 仅按legal_actions展示操作；加注目标额与增量分开；不可收到他人未公开私牌 |
| 补码与退出 | 冻结、手间生效、费用预估、离桌清算、返还 | 不向当前手直接加筹码；未知结果按原操作号查询；豁免与收费原因清楚 |
| 记录与资产 | 可用/冻结/在桌托管、账单、会话战绩、单手记录、回放 | 不跨币求和；只汇总已完成会话，进行中暂计分列；无分母显示“—” |
| 社交与客服 | 文字、快捷语、免费表情、语音转草稿、举报、本人举报结果 | 旁观只读；禁言不阻止举报；ASR失败可重试或转文字，不伪造已发送 |
| 恢复 | 重连、版本缺口、权威快照、会话接管与结果查询 | 保留座位及资产；展示服务器恢复状态；不可由超时推断退款 |
| 偏好 | 主题、快捷下注、头像昵称与复制Game ID | 稳定玩家ID不变；剪贴板失败可手动复制；声音/振动处理设备授权 |

## 认证字段

注册输入 `login_name`、`password`、`display_name`。登录名4～32位ASCII字母数字下划线、小写唯一；昵称2～20个可见Unicode字符，可重复；密码8～72字符。失败文案不能泄露账号是否存在。5次失败锁15分钟、IP每分钟30次限流由服务端执行，客户端展示安全错误和重试时间。

不提供公开“忘记密码”绕过页。若未来开放受审计重置，独立处理一次性凭据，不以后台代设密码。演示原型的登录跳转不代表认证接口已实现。

## 请求与实时契约

- 业务提交使用唯一请求号；同号同参返回原结果，同号异参拒绝。HTTP、WSS共用业务用例。
- 超时进入UNKNOWN，只查询原号；确认失败后才允许修正并创建新请求。页面刷新、重新登录后仍可恢复原操作结果。
- 金额传整数最小单位并携带资产和精度；未知、缺失和零值区分。
- 时间携带时区及server_time，倒计时根据服务端deadline计算；页面可见性切换后校准。
- WSS按事件版本检测重复、乱序及缺口；缺口拉取权威状态，旧会话不能继续发动作。
- 完整字段见[字段与事件契约](../../docs/ui-contract.html)。正式端点、消息类型及错误码由M0接口任务形成可校验契约；本包不把视觉原型事件名冒充已实现API。

## 运营前端

采用若依 Vue 3 目录。包含16个模块：总览待办、玩家、俱乐部、邀请申请、规则费用、房间恢复、代理、资金账本、牌谱、统计、聊天举报、客服、导出、配置、认证授权和审计。逐项表格/详情/筛选/确认字段以[后台模块](../../docs/ops-modules.html)、[展示字段](../../docs/ops-fields.html)、[权限矩阵](../../docs/ops-permissions.html)为准。

默认列表近7天、20条/页、最大100；时间区间[start,end)。筛选、合计、详情和导出保持同资产与同授权范围。详情显示来源、数据截止与完整性、更新时间、对象状态和关联操作。无权字段不由服务端下发；前端隐藏不能代替权限检查。

危险操作先确认对象、影响、原因与范围，敏感动作调用参数绑定TOTP。提交成功、受理、手后生效与清算完成分别显示。资金调整跳专用流程，不允许行内编辑余额。BP-32渠道门禁未关闭前，玩家密码重置入口关闭。

## UI和适配要求

[玩家原型](../../ui/player/index.html)、[Web认证原型](../../ui/player/auth.html)、[后台交互样稿](../../ui/admin/index.html)均只使用演示数据。实现规范包含[Design Token](../../docs/ui-tokens.html)、[页面状态](../../docs/ui-states.html)、[角色权限](../../docs/ui-permissions.html)和[设计验收矩阵](../../docs/ui-acceptance.html)。

验证Chrome、Edge、Safari和目标移动浏览器；覆盖320、360、390、430及桌面宽度、安全区、键盘遮挡、弱网和切后台。操作可键盘完成，焦点可见；弹窗限制焦点并关闭后返回；状态不能只靠颜色区分；尊重减少动画设置。

## 前端完成标准

逐项提供需求ID、页面与状态、字段来源、权限拒绝、失败/未知/恢复截图或自动化证据。页面能打开、原型能点击或Mock返回成功，均不能代替连接真实服务后的产品验收。

## IB-1.1接缝约束

后台唯一认证与权限事实为 Node/poker.admin_*，若依原生 sys_* 登录在生产禁用；采用架构6.6及数据字典12.10的统一判定。买入必须携带有效reservation_id，过期返回RESERVATION_EXPIRED；重试先返回同request_id原结果，不从VACANT直接买入。WSS代际来自player_session及app_user持久字段，每次动作在事务中复查。TOTP使用严格递增高水位的条件更新，与授权签发同事务。手间处理按架构9.3.1，不凭SETTLED直接启动下一手。
