440 lines
12 KiB
Markdown
440 lines
12 KiB
Markdown
# 《36字花》前端开发基线需求文档
|
||
|
||
## 1. 文档目的
|
||
|
||
本文件基于以下两份前期文档整理：
|
||
|
||
- `docs/《_36字花_ 前端开发对接与交互逻辑说明书》.docx`
|
||
- `docs/《36字花》用户前端 (User Portal) UI_UX .docx`
|
||
|
||
目标是移除营销型表述和非关键修辞，只保留后续 UI 设计、前端开发、联调和验收所需的核心设计要求、交互逻辑和技术栈建议。
|
||
|
||
## 2. 核心结论
|
||
|
||
### 2.1 产品形态
|
||
|
||
- 产品为实时开奖类游戏前端，主场景是移动端 H5，同时要求兼容桌面端响应式布局。
|
||
- 页面核心是围绕单局倒计时循环运行的 36 宫格下注界面。
|
||
- 前端必须以服务器状态为准，不能依赖客户端本地时间做开奖判断。
|
||
|
||
### 2.2 设计方向
|
||
|
||
- 视觉风格保留为深色背景、高对比强调色的娱乐场风格。
|
||
- 颜色建议以深海蓝/黑为底，青色和金色作为强调色。
|
||
- 视觉参考中的“神鼎、宝箱、卷轴、巨龙、赛博朋克”等描述，只作为美术方向参考，不作为开发阻塞项。
|
||
- 所有文案容器必须支持多语言伸缩，禁止固定宽度写死。
|
||
|
||
### 2.3 交付优先级
|
||
|
||
后续设计与开发应按以下优先级执行：
|
||
|
||
1. 玩法状态正确
|
||
2. 倒计时与服务端同步正确
|
||
3. 下单、封盘、开奖、派彩状态切换正确
|
||
4. 移动端可用性与性能达标
|
||
5. 动效和视觉强化
|
||
|
||
## 3. 推荐技术栈
|
||
|
||
## 3.1 前端框架
|
||
|
||
- `React + TypeScript + Vite`
|
||
- 原因：移动 H5 交互复杂、状态密集、联调频繁，Vite 启动快，React 生态成熟，TypeScript 适合管理复杂状态和接口约束。
|
||
|
||
## 3.2 路由与页面组织
|
||
|
||
- `React Router`
|
||
- 页面结构建议按大厅主界面、公告弹窗、规则面板、用户侧滑面板拆分。
|
||
|
||
## 3.3 状态管理
|
||
|
||
- `Zustand` 作为全局业务状态容器
|
||
- `XState` 或等价状态机方案用于维护单局生命周期状态
|
||
- 原因：本项目存在明确的 4 段式回合状态机、局内局外状态切换、自动托管覆盖态、网络重连恢复，单纯依赖局部状态容易错乱。
|
||
|
||
建议状态拆分：
|
||
|
||
- `roundStore`：期号、阶段、倒计时、开奖数据
|
||
- `betStore`：选中格子、锁定格子、筹码、总注额、按钮状态
|
||
- `userStore`：余额、连赢状态、下注上限、公告状态
|
||
- `uiStore`：弹窗、抽屉、Toast、动画开关、自动托管蒙层
|
||
|
||
## 3.4 数据请求与实时通信
|
||
|
||
- `TanStack Query`：管理普通 HTTP 请求、缓存与重拉
|
||
- `WebSocket`：接收当前局状态、开奖、余额变动、派彩、自动托管进度
|
||
- 如果后端使用 Socket.IO，则前端改用 `socket.io-client`
|
||
|
||
## 3.5 样式与动画
|
||
|
||
- 页面布局：`Tailwind CSS`
|
||
- 复杂状态样式：`CSS Modules` 或同级方案
|
||
- 盘面高频动画：优先 `CSS Animation / Transition / SVG`
|
||
- 全屏粒子特效：`PixiJS` 或 `tsParticles`
|
||
|
||
约束：
|
||
|
||
- 禁止用 JS 逐帧操作 DOM 做 36 宫格边框动画
|
||
- 动效必须优先使用合成层友好的属性，如 `transform`、`opacity`、`filter`
|
||
|
||
## 3.6 国际化与时间处理
|
||
|
||
- `react-i18next`
|
||
- `dayjs`
|
||
|
||
说明：
|
||
|
||
- `dayjs` 只用于显示格式化，不用于决定回合状态。
|
||
- 回合倒计时必须基于服务端时间戳推导。
|
||
|
||
## 3.7 测试与质量保障
|
||
|
||
- 单元测试：按项目需要自行接入
|
||
- 组件测试：按项目需要自行接入
|
||
- 端到端测试：`Playwright`
|
||
- 线上监控：建议接入 `Sentry`
|
||
|
||
## 4. 页面与模块范围
|
||
|
||
## 4.1 主游戏界面
|
||
|
||
必须包含以下区域：
|
||
|
||
- 顶部导航栏
|
||
- 开奖展示区
|
||
- 中控信息区
|
||
- 36 宫格下注区
|
||
- 筹码与操作栏
|
||
- 右侧历史区
|
||
- 底部单双走势区
|
||
|
||
## 4.2 次级界面
|
||
|
||
必须包含以下弹层或侧栏：
|
||
|
||
- 强制公告弹窗
|
||
- 自动托管运行浮层
|
||
- 玩法与规则面板
|
||
- 用户 Dashboard 侧滑面板
|
||
|
||
## 5. 单局生命周期状态机
|
||
|
||
后台可配置单局时长，前端默认按 30 秒一局建模，并支持服务端参数覆盖。
|
||
|
||
### 5.1 游戏阶段枚举
|
||
|
||
- `BETTING`：下注期
|
||
- `LOCKED`：封盘锁定
|
||
- `DRAWING`：算票与开奖
|
||
- `PAYOUT`：派彩与收尾
|
||
|
||
### 5.2 各阶段规则
|
||
|
||
`BETTING`
|
||
|
||
- 允许选格子、换筹码、清除未确认、重复上一注、确认下注、开启自动托管。
|
||
- 显示倒计时。
|
||
- 跑马灯处于常规速度。
|
||
|
||
`LOCKED`
|
||
|
||
- 到达封盘时间点后，前端必须立即锁盘，不等待后端响应。
|
||
- 所有点击事件、按钮、输入行为全部禁用。
|
||
- 所有 `PRE_SELECTED` 未确认格子必须清空。
|
||
- 显示“停止下注”提示。
|
||
|
||
`DRAWING`
|
||
|
||
- 等待 WebSocket 推送开奖结果。
|
||
- 收到开奖后，盘面跑马灯加速。
|
||
- 最终定格中奖格子，进入中奖态。
|
||
|
||
`PAYOUT`
|
||
|
||
- 接收余额和连赢状态更新。
|
||
- 播放中奖特效。
|
||
- 更新历史和走势。
|
||
- 为下一局做状态重置。
|
||
|
||
## 6. 36 宫格下注区需求
|
||
|
||
## 6.1 网格结构
|
||
|
||
- 固定为 `6 x 6`
|
||
- 每个格子包含：编号、动物名、动物图
|
||
- 格子需要支持轻量分组提示，用于区分业务分类，但不影响下注逻辑
|
||
|
||
## 6.2 单格状态枚举
|
||
|
||
建议统一实现 `CellStatus`：
|
||
|
||
- `IDLE`：默认闲置
|
||
- `MARQUEE`：跑马灯焦点
|
||
- `HOVER`：PC 悬浮
|
||
- `PRE_SELECTED`：已选未确认
|
||
- `LOCKED`：已确认下注
|
||
- `DISABLED`：不可操作
|
||
- `ERROR`：错误反馈
|
||
- `WINNING`：中奖高亮
|
||
- `LOSER`：未中奖弱化
|
||
- `AUTO_ACTIVE`：自动托管执行态
|
||
|
||
## 6.3 单格交互规则
|
||
|
||
- 玩家单局最多选择 5 个格子。
|
||
- `PRE_SELECTED + LOCKED` 的总数不得超过 5。
|
||
- 达到 5 个后，其余可选格子全部置为 `DISABLED`。
|
||
- 点击第 6 个格子时，不得选中，必须触发错误反馈。
|
||
- 余额不足或超限点击时，必须触发错误反馈。
|
||
- 已确认格子在本局内不可取消。
|
||
- 若本局尚未封盘且未满 5 个，允许继续追加下注并再次确认。
|
||
|
||
## 7. 筹码与下注逻辑
|
||
|
||
## 7.1 筹码区
|
||
|
||
标准筹码档位：
|
||
|
||
- `1`
|
||
- `5`
|
||
- `10`
|
||
- `25`
|
||
- `50`
|
||
- `100`
|
||
|
||
## 7.2 统一下注金额同步
|
||
|
||
- 全局维护 `currentChipValue`
|
||
- 已处于 `PRE_SELECTED` 的所有格子，其显示筹码必须跟随 `currentChipValue` 实时同步
|
||
- 筹码切换后，总下注金额必须同步刷新
|
||
|
||
## 7.3 连赢上限与余额限制
|
||
|
||
需要实时校验：
|
||
|
||
- `selectedCount * currentChipValue <= streakMaxBetLimit`
|
||
- `totalBetAmount <= balance`
|
||
|
||
当不满足时：
|
||
|
||
- 对应不可选的大额筹码必须禁用
|
||
- 确认下注按钮进入错误态或禁用态
|
||
- 格子点击需给出明确错误反馈
|
||
|
||
## 8. 确认下注主按钮状态机
|
||
|
||
按钮需要独立维护以下 4 个状态：
|
||
|
||
- `DISABLED`：未选任何格子
|
||
- `READY`：已选格子且余额足够，可点击提交
|
||
- `ERROR`：总下注金额大于余额，文案显示“余额不足”
|
||
- `SUCCESS`：下注成功后维持成功态直到本局结束
|
||
|
||
约束：
|
||
|
||
- 禁止自动提交
|
||
- 必须由用户手动点击确认
|
||
- 成功后已确认格子不可撤销
|
||
|
||
## 9. 自动托管需求
|
||
|
||
## 9.1 功能行为
|
||
|
||
- 调用自动托管接口提交：下注格子、金额、局数
|
||
- 前端进入 `AUTO_MODE`
|
||
- 主键盘和筹码区整体进入不可编辑状态
|
||
- 自动托管中的目标格子显示 `AUTO_ACTIVE`
|
||
- 前端展示当前进度，例如 `12 / 50`
|
||
- 必须提供显式“停止托管”操作
|
||
|
||
## 9.2 视觉与交互约束
|
||
|
||
- 使用全局玻璃遮罩阻断手动操作
|
||
- 自动托管目标格子需要穿透遮罩高亮显示
|
||
- 自动托管态必须与手动锁定态有视觉区分
|
||
|
||
## 10. 中控信息区需求
|
||
|
||
必须展示以下信息：
|
||
|
||
- 当前余额
|
||
- 当前赔率
|
||
- 当前连赢次数
|
||
- 连赢限额提示
|
||
- 当前倒计时
|
||
- 当前期号
|
||
- 当前阶段状态，如 `OPEN` / `CLOSED`
|
||
|
||
倒计时要求：
|
||
|
||
- 最后 5 秒需要强化提示
|
||
- 倒计时只展示服务器推导结果
|
||
|
||
## 11. 历史与走势需求
|
||
|
||
## 11.1 右侧历史区
|
||
|
||
- 显示最近开奖记录
|
||
- 每条至少包含时间、号码、动物名
|
||
- 最新一条高亮
|
||
- 需要支持滚动
|
||
|
||
## 11.2 底部单双走势
|
||
|
||
- 保留最近 30 局
|
||
- 奇数显示红色圆点
|
||
- 偶数显示蓝色圆点
|
||
- 新增一条数据时，最后一个点需要入场动画
|
||
|
||
## 12. 弹窗与侧栏需求
|
||
|
||
## 12.1 强制公告弹窗
|
||
|
||
功能要求：
|
||
|
||
- 首屏进入时请求公告接口
|
||
- 若存在未读公告，必须强制弹出
|
||
- 不允许点击遮罩关闭
|
||
- 不允许提供右上角关闭按钮
|
||
- 勾选“已阅读并同意”前，进入游戏按钮必须禁用
|
||
- 关闭后要记录已读状态
|
||
- 无新公告时，不重复弹出
|
||
|
||
布局要求：
|
||
|
||
- 支持图文内容
|
||
- 内容超长时支持滚动
|
||
- 移动端建议复选框和主按钮上下排列，避免多语言挤压
|
||
|
||
## 12.2 规则面板
|
||
|
||
- 提供玩法规则、赔率说明、连胜机制、大奖说明
|
||
- 允许分页或滚动
|
||
- 结构化展示，不得纯长文堆叠
|
||
|
||
## 12.3 用户 Dashboard 侧滑面板
|
||
|
||
至少包含：
|
||
|
||
- 资产信息
|
||
- 充值入口
|
||
- 提现入口与手续费说明
|
||
- 最近 1 个月投注历史
|
||
- 站内信列表
|
||
- 公告信箱入口
|
||
|
||
## 13. 异常与容错要求
|
||
|
||
## 13.1 本地锁盘优先
|
||
|
||
- 到达封盘时间点时，前端必须立刻锁盘
|
||
- 即使网络延迟，也不能继续允许下注交互
|
||
|
||
## 13.2 压秒点击失败处理
|
||
|
||
场景：
|
||
|
||
- 用户在接近封盘时点击确认
|
||
- 请求发出，但服务器实际已封盘
|
||
|
||
前端处理：
|
||
|
||
- 先进入锁盘和加载态
|
||
- 若稍后收到失败响应，必须撤销未成功下注的本地状态
|
||
- 明确提示“网络延迟，下注失败，未扣款”
|
||
- 严禁误显示为下注成功
|
||
|
||
## 13.3 断线重连恢复
|
||
|
||
触发条件：
|
||
|
||
- 页面重新可见
|
||
- WebSocket 断开后重连
|
||
|
||
前端处理：
|
||
|
||
- 立即调用全量状态接口重新同步
|
||
- 重置倒计时、期号、余额、连赢、走势、当前盘面状态
|
||
- 禁止依赖本地累计时间继续运行
|
||
|
||
## 13.4 余额不足场景
|
||
|
||
- 确认按钮进入错误态
|
||
- 充值入口需要有明显引导
|
||
- 相关格子或筹码点击时给出即时反馈
|
||
|
||
## 14. 接口与事件依赖
|
||
|
||
以下为前端开发所需的最小接口能力，命名可与后端协商，但能力不可缺失。
|
||
|
||
## 14.1 HTTP 接口
|
||
|
||
- `GET /api/user/announcement`
|
||
- `GET /api/game/current_status`
|
||
- `POST /api/bet/place`
|
||
- `POST /api/auto_spin`
|
||
- `POST /api/announcement/read`
|
||
|
||
## 14.2 WebSocket 事件
|
||
|
||
- `round_status`：当前阶段、期号、服务器时间、剩余时间
|
||
- `draw_result`：开奖结果、中奖格子
|
||
- `balance_changed`：余额变化
|
||
- `streak_changed`：连赢状态与限额变化
|
||
- `trend_updated`：最新走势数据
|
||
- `auto_spin_progress`：自动托管局数进度
|
||
|
||
## 15. 性能与实现约束
|
||
|
||
- 移动端目标帧率：`60 FPS`
|
||
- 36 宫格状态切换不得出现明显掉帧
|
||
- 高亮、缩放、呼吸、闪烁等动画优先使用 GPU 友好属性
|
||
- 避免大面积重排和重绘
|
||
- 长列表区域应考虑虚拟化或分段渲染
|
||
- 全局状态更新必须避免引起整盘 36 格不必要重渲染
|
||
|
||
## 16. 多语言与响应式要求
|
||
|
||
- 所有按钮、标签、提示文案必须支持长度扩展
|
||
- 不允许固定像素宽度导致文案截断
|
||
- 文本区域需预留至少 40% 的横向伸缩空间
|
||
- 设计需优先保证移动端单手操作
|
||
- PC 端可补充 Hover 态，移动端不依赖 Hover 完成交互
|
||
|
||
## 17. 开发验收基线
|
||
|
||
满足以下条件才可进入测试或交付：
|
||
|
||
- 单局状态机完整跑通
|
||
- 封盘时前端能本地立即锁盘
|
||
- 服务端时间同步准确
|
||
- 下注数量限制与统一筹码机制无误
|
||
- 余额与连赢上限限制生效
|
||
- 自动托管可启动、运行、停止
|
||
- 公告弹窗强阻断逻辑正确
|
||
- 断线重连后状态可恢复
|
||
- 走势与历史区数据更新正确
|
||
- 移动端核心流程可稳定使用
|
||
|
||
## 18. 建议的开发顺序
|
||
|
||
1. 搭建项目骨架、路由、状态层、接口层
|
||
2. 先实现 30 秒回合状态机和服务端时间同步
|
||
3. 完成 36 宫格、筹码区、确认按钮的核心下注流程
|
||
4. 接入开奖、派彩、历史、走势
|
||
5. 实现公告弹窗、规则面板、用户侧栏
|
||
6. 实现自动托管
|
||
7. 最后补齐粒子特效、强化动画和视觉细节
|
||
|
||
## 19. 明确降级为“视觉参考”的内容
|
||
|
||
以下内容不应阻塞前端逻辑开发，可在视觉设计阶段再细化：
|
||
|
||
- 神坛主体到底是神鼎、宝箱还是法槌
|
||
- 是否采用卷轴、金属边框或全息科技框
|
||
- Jackpot 动画具体表现形式
|
||
- 动物头像是否 3D、半写实或插画风
|
||
- 特效音、粒子素材、品牌化图标样式
|
||
|
||
以上内容只影响视觉表现，不影响本文件定义的交互和功能边界。
|