说明文档

docs/业务流程.md

@@ -0,0 +1,168 @@
+# 🚀《"36字花" 全链路业务流程说明书 (Business Flow Document)》
+
+**文档版本**：V 1.0 (最终定稿版)
+**适用对象**：后端开发工程师、前端开发工程师、QA 测试工程师、系统运营人员
+
+---
+
+## 模块一：C端用户生命周期与游戏流程 (User Flow)
+
+### 1.1 新用户注册与登入流程 (Onboarding Flow)
+1. **获取链接**：用户通过点击代理的专属推广链接（URL携带代理专属 Invite Code）进入注册页。
+2. **极简注册**：用户输入 手机号/邮箱 + 密码 进行注册（**系统不要求上传身份证进行 KYC 实名认证**）。
+3. **绑定归属**：系统自动将该新用户挂载到对应代理的下线树状图中。
+4. **强阻断公告触达**：
+   * 用户首次登录成功，进入主界面前。
+   * 系统弹出【强制公告信箱】（展示平台规则、近期活动）。
+   * 必须勾选 `[ √ ] 我已阅读并同意`，否则进入游戏的按钮为灰色不可点击状态。
+   * 勾选并点击后，正式进入游戏主大厅。
+
+### 1.2 资金充值转换流程 (Deposit & Exchange Flow)
+1. **发起充值**：用户点击顶部 `[+] 充值`，选择本地法币（如 RM）和金额（例如充值 RM 100）。
+2. **网关支付**：跳转至第三方 Payment Gateway 完成支付。
+3. **回调与转换**：
+   * 第三方网关向系统发送成功回调。
+   * 系统底层执行**汇率转换**（如 RM 1 = 💎 1），将法币转化为平台统一的【游戏币】。
+4. **资金入账**：用户界面余额更新为 💎 100，并产生一条充值流水记录。系统记录该用户的“需完成流水额度”（即 💎 100，1倍提现门槛）。
+
+### 1.3 🌟 核心游戏交互流程（单局30秒标准生命周期）
+这是系统最高频运转的流程，每30秒循环一次：
+
+* **阶段 A：下注期 (00:00 - 00:20)**
+  1. 用户在 36宫格 挑选心仪的数字（上限 5 个）。
+  2. 用户在下方选择筹码面额（如 💎 10）。**系统强校验**：所有已选数字将被统一设置为 💎 10。
+  3. **确认防呆**：用户点击右下角发光的 `[ ✅ 确定下注 ]` 按钮。
+  4. **资金扣除**：系统校验余额是否充足，若充足则实时扣除余额，并在选中的格子上打上“锁定”印章。此时注单正式生效写入数据库。
+* **阶段 B：封盘与算票期 (00:20 - 00:22)**
+  1. 第 20.0 秒准时封盘。界面变灰，提示 `[停止下注]`。
+  2. 系统拒收任何晚于此时间的下注请求。
+  3. **AI 算票执行**：AI 瞬间遍历 36 个数字的全局赔付表，结合 RTP 放水池概率，选定本期开奖数字（详见 3.1 节）。
+* **阶段 C：开奖与结算期 (00:22 - 00:30)**
+  1. **异步派彩 (00:22)**：后端得出结果立刻扔进消息队列更新数据、派发奖金、计算连胜次数（主动跳局未下注的玩家也会被清零连胜）。
+  2. **前端动画 (00:22 - 00:25)**：前端同步收到倒计时状态与定格数字，播放 3 秒紧张的快速跳动转盘动画。
+  3. **结算展示 (00:25 - 00:30)**：弹出定格的开奖结果。前端轮询接收最新的资金状态更新，播放金币爆破与余额暴增动画。
+
+### 1.4 特殊托管流程：自动下注 (Auto-Spin Flow)
+1. 用户在前端设定：托管 50 局，每局选 【08羊，16熊】，每注 💎 10。点击启动。
+2. 前端界面进入暗色“锁定态”。
+3. **服务端接管**：用户的请求下发给后端。此后每一局的前段（**引入 00:00 - 00:10 秒的平滑随机分布，防服务器高并发崩溃**），服务器自动在后台帮用户扣款并生成注单。
+4. **中断条件**：当达到 50 局、或用户中途点击 `[ 🛑 停止 ]`、或用户余额不足以支付单局总注时，托管脚本自动终止。
+
+### 1.5 资金提现与风控流程 (Withdrawal Flow)
+1. **发起提现**：用户点击提现，输入金额（最低限制 💎 100）。
+2. **前置系统校验**：
+   * 余额是否充足？
+   * **流水校验**：该用户的历史总有效投注额，是否达到了历史总充值额的 1 倍？（未达标则驳回并提示）。
+3. **扣除手续费**：系统自动扣除 0.5% 的手续费（例如提现 100，实际申请出金金额为 99.5）。
+4. **大额/安全拦截**：
+   * 若提现金额超过后台设定的免审阈值，或该资金来源于 Jackpot 百万大奖。系统自动将提现单挂起，状态为 `[待人工审核]`。
+5. **财务打款**：后台管理员审核通过后，调用网关接口，按实时汇率将游戏币转换回当地法币（RM），打入用户银行卡。
+6. **成功入账**：流转完成，前端发送提现成功站内信。
+
+---
+
+## 模块二：代理端业务与分佣流程 (Agent Flow)
+
+由于采用防刷机制，系统**不支持** C端用户自助升级为代理。
+
+### 2.1 代理开户与层级搭建流程
+1. **创设总代**：平台最高管理员在 Admin 后台，创建一个【总代 Master Agent】账号，并设定 GM 抽成比例（如平台截留 20%，总代享有 80% 的分红权）。
+2. **总代拓客**：总代登录 Agent Portal，生成自己的推广链接发给散户；或者生成【子代专属邀请码】发展下级代理。
+3. **分配比例**：总代在给子代开户时，将自己手中 80% 的分红权，划拨一部分（如 70%）给子代，自己赚取 10% 的级差。
+
+### 2.2 🌟 核心分佣结算流程（流水占比分桶模式）
+系统设定为每周一凌晨（或每日）自动执行结算脚本：
+
+1. **大盘盈亏判断**：系统计算在此周期内的平台实际盈利（总下注扣除总派彩）。
+   * *分支 A*：假如是亏损，**终结流程**，所有代理本期没有分佣。
+   * *分支 B*：假如实际盈利为 RM 2,000（系统内记为 💎 2,000），进入下一步。
+2. **计算单线流水占比 (分桶)**：
+   * 统计所有单线的流水占全网总下注金额的百分比。例如总下注金额为 RM 10,000。
+   * 【Line B】本期下注 RM 2,000，计算得占比为 **20%**。
+3. **拨出单线应得红利基数**：
+   * Line B 的路线应分红基数 = 2,000 (实际盈利) × 20% (该线占比) = 💎 400。
+4. **结合 GM 盘口计算实际到手金额**：
+   * 假设我们 GM 开发者给出的盘口分红比例是 **80%**。
+   * Line B 整线实际到手金额 = 400 × 80% = 💎 320。
+5. **层层级差分配 (无限下延)**：
+   * 当 Line B 总代拿手上的分红拨给旗下的子代（譬如给 70%）。
+   * 该子代拿到的佣金 = 400 (基数) × 70% = 💎 280。
+   * Line B 总代自己这条线只能吃到级差倒扣 (80% - 70% = 10%)，即：400 × 10% = 💎 40。
+   * *(注：280 + 40 = 320，刚好核对总线实际到手金额，多级代理一直按此“抽水级差”相减，最后分到无差价为止。)*
+6. **发放佣金**：计算完毕后，佣金分别直接发放到各级代理的 Agent 钱包，代理可随时提现。
+
+---
+
+## 模块三：联营代理佣金结算大流 (Affiliate Commission Flow)
+
+系统支持高级的“联营代理（占成代理）”独立结算。联营代理不按流水比例切蛋糕，而是直接就其辖区玩家的**客损净利**与平台进行按比例分成结算。
+
+### 3.1 🌟 客损占成与负结转计算逻辑
+系统每月（或单周）触发联营账单结算脚本：
+
+1. **计算总客损 (GGR)**：
+   * 统计【联营代理 A】整条线下所有散户和子代的总输赢额。
+   * 例如：玩家总输款 150,000，玩家总赢款 50,000。该代理辖区 GGR (总客损) = 100,000。
+2. **扣除平台双降费 (Admin Fees)**：
+   * 平台需扣除运营杂费，包括充提通道手续费、API算票系统服务费等（假设固定扣除 GGR 的 15%）。
+   * 真实净利润 = 100,000 - 15,000 = 💎 85,000。
+3. **正盈利分成拨付**：
+   * 根据总后台签署的“联营契约”，代理 A 满足阶梯条件，享有 **55% 的客损占成**。
+   * 联营代理 A 本期佣金 = 85,000 × 55% = 💎 46,750。系统将其下发至代理钱包卡。
+4. **负结转机制 (Negative Carryover)**：
+   * *异常分支*：若周期内玩家鸿运当头，该代理辖区 GGR = **负 50,000**（代理大亏）。
+   * 系统不会直接要求代理补款，而是将这 -50,000 计入代理的**负结转账单 (Carryover Balance)**。
+   * **下期抵扣**：下个结算周期，若该区重新盈利 80,000，必须先刨去上期的 -50,000 亏空窟窿，只能用剩下的 30,000 作为基数来进行分成。以此保证平台与联营代理的绝对风险共担。
+
+---
+
+## 模块四：总控后台运营与管理流程 (Admin Flow)
+
+### 4.1 🌟 开奖管控流程（自动 vs 手动）
+管理员在后台【开奖控制台】进行全局调控：
+
+* **【自动开奖模式】 (默认运转流)**
+  1. 系统在封盘后（第20秒），AI 引擎接管。
+  2. AI 遍历 36 个格子的平台赔付金额（PnL）。
+  3. **风控池判定**：检查 RTP 放水池余额。如果开出最高连赢赔付大奖的亏损 ＜ 放水池余额，AI 以 15%（参数可调）的概率主动把开奖结果设定为该大奖号码；否则，强制开出平台赔付最少的安全号码。
+* **【手动开奖模式】 (特殊干预流)**
+  1. 管理员开启手动模式。
+  2. **强制前置选择**：管理员必须在**下注倒计时的 20 秒内**，在后台面板点击选中一个必开的动物并保存。
+  3. 20秒一到，系统直接抓取管理员预设的号码作为本期开奖结果。
+  4. *异常兜底与强制重置*：若管理员开启了手动模式，但 20 秒内忘了点选号码。系统为防宕机，该期自动由 AI 引擎接管兜底出号。**（重要）同时系统会自动将全局模式强制切回并锁定至【自动模式】**，直至管理员再次手动开启，防范持续缺位引发的事故。
+
+### 4.2 大额提现与异常账号审计流程
+1. **触发警报**：某玩家触发了 10连胜获得 100万 Jackpot，或单笔提现超过 💎 50,000。
+2. **资金冻结**：该笔提现进入后台 `[Risk Audit / 风控审核]` 列表。
+3. **人工溯源**：风控专员点击该玩家详情，查看：
+   * **IP 与设备指纹**：是否与其他多账号重合（防对刷）。
+   * **投注路径**：是否每局固定在最后 0.1 秒压秒下注（防接口脚本外挂）。
+4. **处理决策**：
+    * 若无异常：点击 `[通过 Pass]`，财务打款。
+    * 若实锤作弊：点击 `[驳回并冻结 Reject & Freeze]`，账号封禁，资金不予出款。
+
+### 4.3 平台公告与运营触达流程
+1. 运营在后台新建一条公告内容（如“本周末狂欢，基础赔率提升至 1:35”）。
+2. **选择触达方式**：
+   * *静默发布*：仅收纳进用户的 `[公告信箱]`。
+   * *强弹窗发布*：设定为 `[Pop-out]`。
+3. **用户端生效**：前端检测到有新的 Pop-out 级别的公告未读，立即在用户当前界面弹出。用户必须勾选同意后才可继续游戏，保证 100% 触达率。
+
+---
+
+## 模块五：极端异常与灾难恢复流程 (Disaster Recovery Flow)
+
+### 5.1 开奖期服务器宕机补偿流 (Void & Refund)
+这是对平台信誉极其重要的保护流程：
+1. **灾难发生**：某局倒计时走到 00:22（玩家已全额扣款，系统正在算票），机房突然断电或遭遇极端 DDoS 攻击，服务器彻底宕机。
+2. **工程师重启**：30 分钟后，服务器恢复上线。
+3. **自检与重置机制**：
+   * 后端主程序启动时的**第一件事**，是去数据库自检上一局的状态。
+   * 发现状态为 `[计算中/未结算]`，触发**熔断补偿脚本**。
+4. **执行退本与安抚**：
+   * 系统将该期直接标记为 **`[已作废 VOID]`**。
+   * 将该局所有已被扣除下注资金的用户本金，**100% 原路退回**其可用余额。
+   * 系统通过站内信群发：*“尊敬的用户，因极端的网络波动，期号 20260413-1240 发生数据异常，该期已作废，您的下注本金已全额退回，给您带来的不便敬请谅解。”*
+5. **恢复循环**：处理完残局后，系统开启全新的 30 秒倒计时，游戏继续运转。
+
+---