JiaJun/36-character-flower

Fork 0

Files

JiaJun bd92f10b83 feat: 项目初始化

2026-04-23 16:41:39 +08:00

12 KiB

Raw Blame History

《36字花》前端开发基线需求文档

1. 文档目的

本文件基于以下两份前期文档整理：

docs/《_36字花_ 前端开发对接与交互逻辑说明书》.docx
docs/《36字花》用户前端 (User Portal) UI_UX .docx

目标是移除营销型表述和非关键修辞，只保留后续 UI 设计、前端开发、联调和验收所需的核心设计要求、交互逻辑和技术栈建议。

2. 核心结论

2.1 产品形态

产品为实时开奖类游戏前端，主场景是移动端 H5，同时要求兼容桌面端响应式布局。
页面核心是围绕单局倒计时循环运行的 36 宫格下注界面。
前端必须以服务器状态为准，不能依赖客户端本地时间做开奖判断。

2.2 设计方向

视觉风格保留为深色背景、高对比强调色的娱乐场风格。
颜色建议以深海蓝/黑为底，青色和金色作为强调色。
视觉参考中的“神鼎、宝箱、卷轴、巨龙、赛博朋克”等描述，只作为美术方向参考，不作为开发阻塞项。
所有文案容器必须支持多语言伸缩，禁止固定宽度写死。

2.3 交付优先级

后续设计与开发应按以下优先级执行：

玩法状态正确
倒计时与服务端同步正确
下单、封盘、开奖、派彩状态切换正确
移动端可用性与性能达标
动效和视觉强化

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 断开后重连