1.重构实时消息WebSocket连接
2.MySQL备份
This commit is contained in:
252
docs/_36字花_前端开发对接与交互逻辑说明书.txt
Normal file
252
docs/_36字花_前端开发对接与交互逻辑说明书.txt
Normal file
@@ -0,0 +1,252 @@
|
||||
《"36字花" 前端开发对接与交互逻辑说明书》
|
||||
适用对象
|
||||
：前端开发工程师 (React / Vue / 移动端 H5 开发者)
|
||||
核心要求
|
||||
：极高的渲染性能（移动端务必保持 60FPS，禁止重绘卡顿），极致的状态同步（30秒循环状态机绝对不可发生状态错乱）。
|
||||
一、 全局架构与技术栈建议 (Architecture Guidelines)
|
||||
状态管理 (State Management)
|
||||
：由于游戏状态极其复杂（连赢限额、统一下注金额、倒计时同步），强烈推荐使用全局状态管理库（如 React的
|
||||
Redux/Zustand
|
||||
或 Vue的
|
||||
Pinia
|
||||
），将
|
||||
“业务逻辑数据层”
|
||||
与
|
||||
“UI渲染层”
|
||||
完全解耦。
|
||||
动画性能 (Animation Performance)
|
||||
：
|
||||
盘面的 10 种状态切换和高频边框动画，
|
||||
严禁使用 JS 帧动画操作 DOM
|
||||
。
|
||||
必须全部采用
|
||||
CSS3
|
||||
transition
|
||||
、
|
||||
animation
|
||||
、
|
||||
box-shadow
|
||||
或
|
||||
SVG (
|
||||
stroke-dasharray
|
||||
)
|
||||
。
|
||||
涉及到全屏爆金币的粒子特效 (Particle Effects)，建议直接调用轻量级 Canvas 动画库（如
|
||||
tsparticles
|
||||
或
|
||||
PixiJS
|
||||
）。
|
||||
时间同步 (Time Sync)
|
||||
：绝对不要信任客户端（手机/浏览器）的本地时间！游戏倒计时必须以 WebSocket/API 下发的服务器时间戳为基准进行倒推补偿。
|
||||
二、 核心状态机：30秒生命周期 (The 30s Lifecycle) 注意⚠️这个时间后台可配置
|
||||
前端的整个游戏循环被严格划分为 4 个生命周期，请在代码中建立全局的
|
||||
GameState
|
||||
枚举，并根据状态驱动 UI 渲染：
|
||||
GameState.BETTING
|
||||
|
||||
(0 - 20秒：下注期)
|
||||
行为
|
||||
：允许用户点击格子、选筹码、点确认。
|
||||
UI
|
||||
：倒计时递减。背景跑马灯常态运转。
|
||||
GameState.LOCKED
|
||||
|
||||
(20.0秒：封盘锁定)
|
||||
行为
|
||||
：
|
||||
前端立即进行物理锁盘
|
||||
。无论网络是否有延迟，只要本地计算到达20.0秒，立即禁用所有输入框、点击事件和按钮。
|
||||
UI
|
||||
：弹出
|
||||
[停止下注]
|
||||
提示，未点击确认的预选状态 (
|
||||
PRE_SELECTED
|
||||
) 格子全部强制清除。
|
||||
GameState.DRAWING
|
||||
|
||||
(20 - 25秒：算票与开奖)
|
||||
行为
|
||||
：等待后端 WebSocket 推送开奖结果。
|
||||
UI
|
||||
：收到结果后，前端触发 3 秒的高频加速跑马灯，最后 0.5 秒光圈定格在中奖格子上，触发
|
||||
WINNING
|
||||
状态大爆动画。
|
||||
GameState.PAYOUT
|
||||
|
||||
(25 - 30秒：结算派彩)
|
||||
行为
|
||||
：监听余额变更推送，更新连赢 (Streak) 状态。
|
||||
UI
|
||||
：播放中奖特效，更新底部走势图 (红蓝圆点)，准备进入下一局。
|
||||
三、 组件级交互逻辑：36字花主键盘 (The 36-Grid System)
|
||||
前端需要封装一个
|
||||
<Cell />
|
||||
组件，该组件接收一个
|
||||
status
|
||||
属性（范围 0-9），并根据该枚举值切换对应的 CSS Class。
|
||||
📌 10 种状态枚举 (CellStatus Enum) 映射逻辑
|
||||
IDLE
|
||||
(闲置)：默认状态，深色，偶发微光 CSS 动画。
|
||||
MARQUEE
|
||||
(跑马灯焦点)：全局维护一个
|
||||
activeCellIndex
|
||||
每 0.1秒随机变更，命中的组件亮起青色霓虹边框。
|
||||
HOVER
|
||||
(悬浮)：
|
||||
:hover
|
||||
伪类触发（仅 PC）。
|
||||
PRE_SELECTED
|
||||
(预选中)：前端本地状态数组。显示筹码图标，金边流光。
|
||||
LOCKED
|
||||
(已确认)：调用
|
||||
place_bet
|
||||
API 成功后切换至此状态。显示锁定印章，绿色边框。
|
||||
DISABLED
|
||||
(禁用)：封盘时，或已选中数量达标（5个）时，其余格子强制渲染黑色 60% 遮罩。
|
||||
ERROR
|
||||
(错误抖动)：触发 CSS
|
||||
shake
|
||||
动画，维持 0.5s 后回退到上一个状态。
|
||||
WINNING
|
||||
(中奖大爆)：开奖目标，Z-index 置顶，放大 1.25 倍，播放强脉冲 CSS。
|
||||
LOSER
|
||||
(落选陪跑)：透明度设为
|
||||
opacity: 0.2
|
||||
。
|
||||
AUTO_ACTIVE
|
||||
(自动托管中)：全局遮罩下，该格子穿透遮罩，显示紫色虚线动画与
|
||||
AUTO
|
||||
印章。
|
||||
📌 核心防呆交互逻辑 (必须用代码写死限制)
|
||||
统一下注金额联动 (Chip Sync)
|
||||
：
|
||||
全局维护一个
|
||||
currentChipValue
|
||||
（当前选中的筹码）。
|
||||
如果用户修改了
|
||||
currentChipValue
|
||||
，前端必须
|
||||
遍历所有状态为
|
||||
PRE_SELECTED
|
||||
的格子，将它们显示的筹码瞬间同步为新金额
|
||||
。
|
||||
数量限制校验 (Max 5 Limit)
|
||||
：
|
||||
实时计算：
|
||||
count(PRE_SELECTED) + count(LOCKED)
|
||||
必须
|
||||
<= 5
|
||||
。
|
||||
等于 5 时，其余 31 个
|
||||
IDLE
|
||||
状态的格子必须变成
|
||||
DISABLED
|
||||
状态。如果强行点击，触发
|
||||
ERROR
|
||||
动画。
|
||||
连赢上限校验 (Streak Bet Limit)
|
||||
：
|
||||
如果玩家上一局赢了，API 会下发一个
|
||||
streakMaxBetLimit
|
||||
（连赢最高下注总额，如 💎 100）。
|
||||
前端需要写一个
|
||||
useEffect
|
||||
/
|
||||
watch
|
||||
：实时计算
|
||||
当前选中数字数量 * currentChipValue
|
||||
。如果这个乘积
|
||||
> streakMaxBetLimit
|
||||
，或者当前账户余额不足，左下角的那个筹码图标必须添加
|
||||
disabled
|
||||
属性（变灰不可点）。
|
||||
四、 核心中控台交互 (Control Panel & Actions)
|
||||
1.
|
||||
[✅ 确定下注 Confirm]
|
||||
主按钮的状态机
|
||||
这是全场最重要的按钮，前端必须维护它独立的四态机：
|
||||
Disabled
|
||||
：未选中任何格子时。
|
||||
Ready (高亮呼吸)
|
||||
：选中格子 > 0，且总注金 <= 余额。绑定
|
||||
onClick -> handleSubmit
|
||||
。
|
||||
Error (红色)
|
||||
：总注金 > 余额。文字变成“余额不足”。
|
||||
Success (绿色)
|
||||
：收到 API 200 成功响应后，维持绿色直到本局结束。
|
||||
1.
|
||||
Auto-Spin（自动托管）逻辑流
|
||||
数据层
|
||||
：调用
|
||||
/api/auto_spin
|
||||
告知后端要买哪些数字、金额和局数。
|
||||
UI 层
|
||||
：前端进入
|
||||
AUTO_MODE
|
||||
全局变量。
|
||||
整个盘面外层盖一个
|
||||
<div className="glass-overlay" />
|
||||
，
|
||||
pointer-events: none
|
||||
（阻断一切鼠标点击）。
|
||||
只有目标格子的状态被设为
|
||||
AUTO_ACTIVE
|
||||
，并使用 CSS
|
||||
z-index
|
||||
穿透遮罩。
|
||||
监听后端 WebSocket 下发的每一局扣款成功事件，更新底部控制台的进度条（如
|
||||
3/50 局
|
||||
）。
|
||||
3.
|
||||
Red/Blue 路子图渲染逻辑 (Trend Chart)
|
||||
接收一个含有最近 30 期开奖数字的 Array
|
||||
[08, 15, 36, ...]
|
||||
。
|
||||
渲染判断
|
||||
：
|
||||
item % 2 === 0
|
||||
(偶数) 渲染蓝色圆圈；
|
||||
item % 2 !== 0
|
||||
(奇数) 渲染红色圆圈。
|
||||
入场动画
|
||||
：当有新数字加入 Array 时，最后一个圆圈必须带有
|
||||
slide-in
|
||||
或
|
||||
pop-in
|
||||
动画。
|
||||
五、 网络延迟与极端异常处理 (Edge Cases & Fallbacks)
|
||||
博彩游戏的前端，对异常处理的要求极高，请前端必须实现以下机制：
|
||||
首屏强制公告 (Welcome Pop-out)
|
||||
进页面时调用
|
||||
/api/user/announcement
|
||||
。如果有未读公告，弹出
|
||||
<Modal />
|
||||
。
|
||||
“进入游戏”的
|
||||
Button
|
||||
绑定
|
||||
disabled={!isChecked}
|
||||
。不勾选绝对不给进。
|
||||
压秒网络卡顿防错 (The 19.9s Click)
|
||||
场景
|
||||
：倒计时剩 0.1 秒，玩家点击了【确定下注】，前端发起了 HTTP/Socket 请求，但因为网络差，请求还没到服务器，本地倒计时先归零了。
|
||||
处理方案
|
||||
：前端立即锁盘进入
|
||||
LOCKED
|
||||
状态，并显示 Loading (spinner)。当 2 秒后收到后端的 400 Bad Request（提示已封盘）时，前端必须
|
||||
清除这个格子的状态，并弹窗提示
|
||||
[网络延迟，下注失败，未扣款]
|
||||
。千万不能强行把它变成
|
||||
LOCKED
|
||||
绿勾。
|
||||
断线重连恢复 (Reconnection Recovery)
|
||||
场景
|
||||
：玩家切出微信看消息，5分钟后切回浏览器。
|
||||
处理方案
|
||||
：前端检测到
|
||||
visibilitychange
|
||||
或者 Socket 断开，必须立刻重新发起
|
||||
/api/game/current_status
|
||||
全量拉取请求。根据服务器返回的数据，瞬间重置本地的倒计时、当前连胜数、走势图数据。
|
||||
绝对不要依赖本地时间的积累运算。
|
||||
Reference in New Issue
Block a user