webman-buildadmin/docs/后端.md

💻《"36字花" 后端系统开发与后台模块详细规格书》

适用对象：后端开发工程师、数据库架构师、系统管理员

一、 系统架构与技术栈规范 (Architecture & Tech Stack)

1. 核心开发语言/框架：由于极高的并发读写，推荐使用并发性能优越的语言。
2. 数据冷热分离架构：
   • 热数据 (Redis)：存放当前局的倒计时状态、当前局全网注单池、玩家连胜状态 (Streak)、30期开奖历史。AI算票必须全程在 Redis 内存中计算，确保 2 秒内出结果。
   • 业务主库 (MySQL / PostgreSQL)：存放用户资产、核心账本、代理树状图、系统配置。注单状态确认后异步落库。
   • 冷数据查询 (ElasticSearch / ClickHouse)：超海量注单流水（每月上亿条）的存储与分页查询，减轻主库压力。
3. 异步消息队列 (MQ)：引入 RabbitMQ 或 Kafka。开奖结果一出，立刻将派彩结算、连胜状态更新、站内信发放等操作扔进 MQ 异步执行，绝对禁止在结算期同步锁库写数据。
4. 事务安全性：下注扣款动作必须是强原子性操作 (Atomic)，结合 Redis 分布式锁，杜绝并发下注导致的余额超扣（Negative Balance）。

---

二、 核心驱动引擎：30秒状态机与AI算票 (Core Engine)

后端必须启动一个绝对精准的守护进程（Daemon）来维持 30 秒一局的生命周期。

2.1 状态机切换逻辑 (State Machine)

• STATUS_OPEN (0-20s)：接收 Bet_API 请求。若有自动托管任务，在 0-10s 内通过 Jitter 平滑随机执行注单，防并发风暴。
• STATUS_LOCKED (20.0s)：严格切断请求接入，开始计算。
• STATUS_CALCULATING (20-22s)：调用 AI 算票引擎。
• STATUS_PAYOUT (22-25s)：第 22.0 秒立刻将派彩和站内信任务扔入 MQ 异步执行。同时下发结果给前端开始播放倒计时定格动画。
• STATUS_FINISHED (25-30s)：本期收尾，创建下一期期号，循环。
• 灾难兜底器：系统启动时自检，若发现有卡在 CALCULATING 的历史期号，立即执行 VOID_AND_REFUND（全额退本）脚本。

2.2 AI 算票引擎算法 (后台执行逻辑)

1. 汇集注单：抓取本期 Redis 池中所有有效注单。
2. 提取连赢系数：关联下注玩家当前的连赢次数（0次=33倍，1次=66倍，2次=99倍...）。
3. 遍历计算 (PnL Loop)：
   • For i = 1 to 36:
   • 计算如果开出 i，平台需赔付的总金额（含触发Jackpot的额外100万）。
4. RTP 风控池判定：
   • 拉取当前“全局放水池”余额。
   • 如果有某个结果导致平台亏损，但亏损额 < 放水池余额，AI通过 Math.random() 以配置概率（如15%）选择该结果。
5. 最终决断：若未触发放水，则 Return Min(PnL_Array)（返回让平台赔付最少的数字）。若有多个最小值，随机取其一。

---

三、 🌟 核心重点：总控后台 (Admin Portal) 功能模块清单

为了让运营团队能够全方位掌控平台，后端需要为前端/后台管理系统提供以下极为详尽的 API 和模块支持：

3.1 📊 数据看板台 (Dashboard)

运营人员登录后台第一眼看到的数据宏观监控：

• 实时在线：当前 WebSocket 在线连接数。
• 宏观财务 (今日/本周/本月)：全网总充值额、总提现额、全网总下注额 (Turnover)、平台实际客损盈亏 (GGR / PnL)。
• 风控预警屏：滚动显示大额中奖提示（单笔赢取超过X万）、异常频繁提现提示。

3.2 🎲 游戏与开奖控制台 (Game & Draw Control)

• 模式切换开关：[自动 AI 模式] 与 [手动控制模式] 实时切换。
• 实时注单监控：在下注的 0-20 秒内，实时展示当前 36 个格子的注金分布热力图，并实时预估每个格子的 PnL。
• 手动开奖干预框：当开启手动模式时，提供一个允许在前 20 秒内指定开奖号码的输入框。
• 历史开奖纠错与作废：允许超管针对历史某期执行“撤回作废 (Void)”指令，系统自动扣除已派彩金额（慎用功能）。

3.3 👥 用户 CRM 与风控管理 (User & Risk Management)

• 玩家列表与画像：包含玩家ID、归属代理、注册时间、当前余额、总充提差、历史总输赢。
• 玩家详情穿透 (Deep Trace)：
  • 查看该玩家详细下注流水、充提流水。
  • 查看登录设备指纹、登录 IP 历史（支持同一 IP 多账号关联查询）。
• 风控操作箱：
  • 冻结/解冻账户（禁止登录 / 禁止下注 / 禁止提现）。
  • 人工加减币 (Manual Adjustment)：用于处理客诉补偿或线下充值，必须记录操作理由和操作人。
  • 清零连胜进度（异常账号干预）。

3.4 💰 财务与出入金审核中枢 (Finance Center)

• 充值明细表：所有充值订单状态（成功/失败/掉单补单）。
• 提现审核队列 (Withdrawal Audit)：
  • 列出待审核单据。后端必须在此处提供“有效流水达标检测”标签（如：该玩家充值1000，当前已打流水1500，流水完成率 150%，亮绿灯）。
  • 支持 [一键通过并打款] 和 [驳回请求并退回余额] 操作。
• Jackpot 提现专项通道：针对大额中奖资金的专属审核队列，必须由超管权限放行。
• 提现手续费收益报表：单独统计系统抽取的 0.5% 手续费总收入。

3.5 🏢 代理中枢与佣金结算系统 (Agent System)

• 创建总代账号：由于前端不支持散户变代理，只能由管理员在此处点击 [新增总代 Master Agent]，生成专属邀请链接。
• 代理树状图 (Tree View)：可视化查看整个多级代理层级及人数。
• 佣金结算看板 (Commission Settlement)：
  • 后端按周/月跑批处理脚本（Cron Job）。
  • 展示全平台周期总盈利（大盘盈亏）。
  • 列出各代理线的流水占比%、应得分红、GM盘口扣除利润、实际下放分红。
  • 提供 [一键发佣] 按钮，将佣金批量转入各代理的 Agent 钱包。

3.6 🤝 联营契约与合营代理管控大厅 (Affiliate Management)

设计为与普通流水分佣系统并行的客损占成代理模块方案：

• 联营契约（合营契约）线上配置：平台超管可与高级代理在线签署“联营契约”。支持动态阶梯的占成比（例如：当月新增活跃≥10人且总客损>1万美元时，该代客损占成提高至45%）。
• 独立负结转账单明细 (Agent Statement)：
  • 后端按月或周生成带有“负盈利结转”规则的专业级合营账单。
  • 账表包含项目：辖区总输赢、当期大促红利扣除、当期通道成本扣除、历史负结转累计抵扣、当期应结佣金。
• 佣金与负盈利全自动跑批：结算周期末由 Cron Job 自动判断，若是正佣金则划入代理钱包；若是负佣金（玩家赢），则记入该代理名下的 Carryover Balance（累计负结转账本）供下期抵扣。
• 独立的财务出金通道：联营代理大额提取高额占成分红时，有专门供高级财务总监审批的安全通道，与普通玩家或刷水代理区分开。

3.7 ⚙️ 系统超级参数引擎 (System Configuration)

这是系统最核心的动态配置中心，后端必须将以下参数做成 DB 可配置，严禁在代码里写死：

• 时间参数：单局时长（默认30）、下注时长（默认20）。
• 下注参数：最高选字数（默认5，可调为6或7）、最低下注额（默认1）、单注最高限额（如500，风控核心）、前端快捷筹码面额配置。
• 赔率参数：基础赔率（默认33）、连续中奖递增步长（默认33）。
• 大奖参数：Jackpot 触发连胜阈值（默认10）、Jackpot 奖励固定金额（默认1,000,000）、Jackpot资格最小下注额（默认50）。
• 风控参数：提现流水倍数要求（默认1.0倍）、提现手续费比例（默认0.005）、AI RTP 放水抽水比例。
• 代理参数：全局 GM 盘口截留比例（默认20%）、联营（合营）基础成本双降费比例（默认15%）。

3.8 📢 运营中心 (Operations)

• 公告信箱管理：富文本编辑器。支持设置公告类型为 [普通静默] 或 [强阻断 Pop-out]，其中 Pop-out 要求客户端弹出并强制确认。
• 前端走马灯/跑马灯：管理首页顶部滚动的文字通知。

3.9 🔒 权限与操作日志 (Admin RBAC & Logs)

• 角色控制 (Role-Based Access Control)：设置超级管理员、财务审核员、普通客服。
• 管理员操作审计 (Audit Trail)：记录所有后台操作的日志（谁、在什么时间、把赔率从33改成了35，或给谁手动加了钱），防范内部作恶。

---

四、 C端前端核心 API 接口要求 (User API Requirements)

除了基础的登录注册，后端需要重点保证以下几个接口的性能与安全：

1. POST /api/user/register (用户注册)：
   • 接受手机/邮箱、密码、以及 invite_code（选传）。如果带有 invite_code，自动挂载到对应代理名下；否则为直客。
2. GET /api/game/roadmap_history (历史路子图拉取)：
   • 前端初始化首屏时调用，返回最近 30 期的开奖记录数组（含期号、中奖数字、赔率），用于渲染屏幕底部大路/红蓝球走势图。
3. GET /api/game/current_status (轮询/长连接)：
   • 前端每秒请求或通过 WebSocket 接收。返回当前期号、倒计时剩余秒数、当前开奖状态。
4. POST /api/game/place_bet (核心下注接口)：
   • 入参：期号、选中的动物编号数组 [01, 02, 15]、单注金额 10。
   • 后端强校验逻辑：
     1. 验证时间：是否超过第 20 秒？是则返回 403 封盘报错。
     2. 验证数量：数组长度是否 ≤ 系统配置的【最高选字数】？
     3. 验证连赢上限：该玩家若处于连赢态，本次下注总额（如 30）是否 ≤ 上局总下注额？
     4. 验证余额：余额是否 ≥ 30？
   • 校验全过，开启 DB 事务，扣钱，写注单，提交。
5. POST /api/game/auto_spin (启动/停止自动托管)：
   • 后端接收托管指令后，写入守护进程列队。由服务器在后台引入 Jitter(0-10s随机制打散) 帮玩家调用 place_bet。
6. GET /api/user/pnl_history (历史记录过滤)：
   • 后端仅返回最近 1 个月的数据（通过 SQL 时间戳硬性过滤），防止扫库查询。

---

五、 后端安全与反黑客建议 (Security & Anti-Fraud)

1. 接口限流 (Rate Limiting)：place_bet 接口必须限制单个用户的请求频率（如 1秒内最多2次），防止外挂脚本通过并发漏洞击穿余额。
2. 汇率与金额精度：底层数据库所有金钱字段（游戏币）必须使用 DECIMAL(18,4) 或将其放大 10000 倍用整型 (INT64) 存储。绝不允许使用浮点数（Float/Double），防止精度丢失导致对账不平。
3. 负资产阻断：扣款 SQL 必须带上条件判断：UPDATE user SET balance = balance - 100 WHERE id = 1 AND balance >= 100; 确保高并发下余额不会被扣成负数。