# 《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、半写实或插画风 - 特效音、粒子素材、品牌化图标样式 以上内容只影响视觉表现，不影响本文件定义的交互和功能边界。