说明文档

docs/后端.md

@@ -0,0 +1,145 @@
+
+
+# 💻《"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;` 确保高并发下余额不会被扣成负数。
+