feat: 项目初始化

2026-04-23 16:41:39 +08:00
parent be4669a9f1
commit bd92f10b83
42 changed files with 6047 additions and 2 deletions
--- a/docs/frontend-baseline-requirements.md
+++ b/docs/frontend-baseline-requirements.md
@@ -0,0 +1,439 @@
+# 《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、半写实或插画风
+- 特效音、粒子素材、品牌化图标样式
+
+以上内容只影响视觉表现，不影响本文件定义的交互和功能边界。