说明文档

docs/36字花-数据库与实施计划.md

@@ -0,0 +1,244 @@
+# 「36字花」数据库与实施计划
+
+**文档版本**：V1.4  
+**依据**：《36字花 PRD》《业务流程说明书》《后端系统规格书》及现有表 `game_user`  
+**目标**：明确分阶段落地步骤、需新建表、两表适配方向与可执行验证清单。
+
+**DDL 脚本（可执行）**：[database/dfw_36zihua_schema_v1.sql](../database/dfw_36zihua_schema_v1.sql)  
+内含：新建 `channel` 表，及 `game_user` / `admin` / `admin_group` 的 `ALTER` 语句，以及新建表完整 `CREATE TABLE`（字段级 `COMMENT` 即字段清单）。
+
+---
+
+## 一、现状与表定位
+
+| 表名 | 当前角色 | 目标角色 |
+|------|----------|----------|
+| `channel` | 新渠道主表 | **顶级代理渠道分红配置表**：由超管创建，维护分红方式、分红金额、总利润等渠道参数 |
+| `game_user` | 用户（coin、channel_id 等） | **C 端玩家主表**：余额与精度、归属代理、流水与风控字段 |
+| `admin` | 后台管理员 | **子代理承载表**：顶级代理下级代理放在 `admin`，通过 `invite_code` 管理客户，统一无开奖控制权 |
+| `admin_group` | 角色组 | **按渠道隔离**：角色组归属 `channel`，渠道仅管理本渠道角色组 |
+
+---
+
+## 二、分阶段执行计划
+
+| 阶段 | 目标 | 主要内容 |
+|------|------|----------|
+| **P0** | 数据地基 | 新建 `channel` 并适配 `game_user`、`admin`、`admin_group`；建立账本类最小表集（金额精度统一） |
+| **P1** | 游戏核心 | 期号、注单、开奖、系统配置；Redis 状态机 + MQ 异步落库 |
+| **P2** | 资金与风控 | 充提订单、流水账、提现审核、Jackpot / 大额拦截 |
+| **P3** | 代理与结算 | 流水占比分桶、级差、联营占成与负结转（表结构 + 跑批骨架） |
+| **P4** | 运营与审计 | 公告（含 Pop-out）、站内信、后台 RBAC 与操作审计 |
+
+---
+
+## 三、`channel` 设计（替代 `game_channel`）
+
+### 3.1 建议保留字段
+
+`id`、`code`（可作渠道码）、`invite_code`、`name`、`status`、`remark`、`admin_id`、`admin_group_id`、`create_time`、`update_time`。
+
+### 3.2 建议新增或调整（按你确认口径）
+
+| 方向 | 说明 |
+|------|------|
+| 顶级代理归属 | `top_admin_id`：关联到顶级代理管理员 `admin.id` |
+| 代理模式参数 | `agent_mode`（`turnover` 普通刷水 / `affiliate` 联营）、`turnover_share_rate`、`affiliate_share_rate`、`affiliate_fee_rate`、`carryover_balance` |
+| 渠道经营指标 | `profit_amount`（精度升级）、`total_profit_amount`、`commission_pool_amount` |
+| 邀请码参数 | 渠道不生成邀请码，邀请码由管理员自动生成并用于注册归属 |
+| 代理钱包 | 余额可字段扩展或独立 `game_agent_wallet`（推荐独立表，便于对账） |
+
+### 3.3 注意
+
+`channel` 不承担子代理树结构；子代理层级与邀请码归属下沉到 `admin`。除超管外，渠道管理仅可查看当前管理员归属渠道。
+
+---
+
+## 四、`game_user` 适配（用户表）
+
+### 4.1 建议保留字段
+
+`id`、`username` / `phone`、`password`、`uuid`、`head_image`、`channel_id`（归属渠道）、`status`、`create_time`、`update_time`。
+
+### 4.2 建议新增或调整
+
+| 方向 | 说明 |
+|------|------|
+| 金额精度 | `coin` 调整为 **`decimal(18,4)`**（与规格书一致，禁止用浮点存币） |
+| 注册与归属 | `invite_code` 或注册时解析 URL 与 `channel.code` 绑定 |
+| 提现门槛 | `total_deposit_coin`、`total_valid_bet_coin` 或等价的「待完成流水」字段（全项目统一一种口径） |
+| 风控 | 禁止登录 / 禁止下注 / 禁止提现等，可用位标记或独立布尔字段 |
+| 连胜持久化 | 可选 `current_streak`、`last_bet_period_id`；高频仍以 **Redis** 为准，DB 作兜底同步 |
+| 邮箱 | PRD 支持手机或邮箱注册时，可增加可空字段 `email`（是否唯一索引按产品定） |
+
+---
+
+## 五、`admin` 适配（子代理承载）
+
+| 方向 | 说明 |
+|------|------|
+| 层级关系 | `parent_admin_id` 表示上级代理 |
+| 渠道归属 | `channel_id` 表示该子代理属于哪个顶级渠道 |
+| 邀请管理 | `invite_code` 自动生成且全局唯一，用于发展玩家并做归属绑定 |
+| 角色标识 | `agent_role`（如 `agent_admin` / `sub_agent` / `staff`） |
+| 分红设置 | `commission_rate`（百分比，0-100，最多两位小数）；管理员角色组改为单选，同一角色组下管理员分红比例总和不超过100% |
+| 开奖权限 | 不在数据层开放给渠道/子代理；开奖权限仅由超管 RBAC 控制 |
+
+### 5.1 角色组与管理员分红计算口径
+
+- 角色组分红：`当前角色分红 = 渠道设置获取分红 × (1 - 上级角色分红比例) × 当前角色分红比例`
+- 管理员分红：`当前管理员分红 = 当前角色分红 × 当前管理员分红比例`
+- 校验约束：
+  - 同一父级下角色组分红比例总和 `<= 100%`
+  - 同一角色组下管理员分红比例总和 `<= 100%`
+
+---
+
+## 六、`admin_group` 适配（角色组仅归属渠道）
+
+| 方向 | 说明 |
+|------|------|
+| 渠道归属 | 增加 `channel_id` 字段，角色组只属于一个渠道 |
+| 管理边界 | 渠道管理员只能增删改查本渠道 `admin_group` |
+| 系统角色组 | `channel_id` 可为空表示系统级（仅超管可见） |
+
+---
+## 七、需新建的核心表
+
+表名可按项目命名规范微调，须小写加下划线。
+
+### 7.1 游戏引擎
+
+| 表名 | 用途 |
+|------|------|
+| `game_period`（或 `game_issue`） | 期号、状态机阶段、开奖号码、自动/手动、作废标记 |
+| `game_bet_order` | 注单：期号、用户、选号、单注额、总额、状态（扣款 / 结算 / 退款） |
+| `game_bet_auto`（可选） | 自动托管：剩余局数、选号快照、启停状态 |
+
+### 7.2 系统配置
+
+| 表名 | 用途 |
+|------|------|
+| `game_config`（或统一 `system_config_kv`） | 局时长、下注时长、选号上限、赔率步长、Jackpot 参数、RTP 放水、提现倍数与手续费等（须 DB 可配，禁止写死） |
+
+### 7.3 资金与账本（强烈建议）
+
+| 表名 | 用途 |
+|------|------|
+| `user_wallet_ledger`（或 `game_user_balance_log`） | 充值、下注扣款、派彩、提现冻结、手续费、人工调账；金额 **`decimal(18,4)`** |
+| `deposit_order` | 第三方充值、法币金额、汇率、游戏币到账、回调状态 |
+| `withdraw_order` | 提现申请、手续费、审核状态、Jackpot / 大额标记 |
+
+### 7.4 代理与结算
+
+| 表名 | 用途 |
+|------|------|
+| `agent_settlement_period` | 结算周期、大盘盈亏快照 |
+| `agent_commission_record` | 流水占比分桶结果、级差拆分、发放状态 |
+| `affiliate_contract`（可选） | 联营契约、占成比例、阶梯条件 |
+| `affiliate_carryover`（或与佣金记录合并设计） | 联营负结转余额与流水 |
+
+### 7.5 运营
+
+| 表名 | 用途 |
+|------|------|
+| `operation_notice` | 公告类型（静默 / Pop-out）、内容 |
+| `user_notice_read` | 用户已读 / 强弹窗已确认 |
+
+### 7.6 审计（按需）
+
+若现有 `admin_log` 不足以覆盖财务与风控操作，可增补结构化审计表。
+
+### 7.7 冷热分离（中后期）
+
+历史注单与流水检索迁移至 **ElasticSearch 或 ClickHouse**，主库保留近期热数据与归档策略。
+
+---
+
+## 七、验证步骤
+
+### 7.1 数据库与模型
+
+1. DDL 执行后检查：金额字段均为 **`decimal(18,4)`**；`channel`、`game_user`、`admin`、`admin_group`、期号等关联字段有合理索引。  
+2. 创建测试渠道（顶级）→ 创建子代理 `admin`（设置 `parent_admin_id`、`channel_id`、`invite_code`）→ 创建用户并挂载 `channel_id`，链路与后台筛选正常。  
+3. 扣款更新采用「**条件更新**」语义（如 `WHERE balance >= 扣款额`），压测或单测验证**不出现负余额**。
+
+### 7.2 业务规则（对照 PRD / 业务流程）
+
+| 场景 | 验证要点 |
+|------|----------|
+| 注册与邀请 | 玩家使用子代理邀请码注册时，先命中 `admin.invite_code`，再落到对应 `channel_id` |
+| 子代理权限 | 渠道与子代理账号均无开奖权限；仅超管角色可访问开奖控制接口 |
+| 30 秒节奏 | 0–20s 可下注，20s 后拒绝；约 22s 后可查开奖结果 |
+| 连胜与跳局 | 连续期号未下注则连胜清零；连赢时本轮总下注不超过上轮总下注 |
+| Jackpot | 连胜达阈值且单局下注不低于配置最小额才触发额外大奖 |
+| 提现 | 有效投注 ≥ 总充值×配置倍数；最低提现与 0.5% 手续费；大额 / Jackpot 进审核 |
+| 灾难恢复 | 模拟期卡在「计算中」，启动退本流程：期作废、本金退回账本 |
+
+### 7.3 代理与结算（逻辑就绪后）
+
+1. 构造多代理树与多用户下注，跑一期结算脚本或单元测试纯算法。  
+2. **大盘亏损**：本期代理分佣为 0。  
+3. **大盘盈利**：流水占比分桶 + 级差，各级金额之和与线总包一致（可对照文档数值验算）。  
+4. **联营**：客损为负产生负结转；下期盈利先抵扣再分佣。
+
+### 7.4 非功能
+
+- Redis：当前期注单池、倒计时、近 30 期开奖缓存。  
+- MQ：派彩异步消费**幂等**（如 `period_id` + 用户 + 业务单号）。  
+- API：下注、提现等核心接口**限流**生效。
+
+---
+
+## 八、风险与依赖
+
+1. **子代理数据源**：子代理统一在 `admin`，避免在 `channel` 重复建树造成双主数据源。  
+2. **现有 `profit_amount`（decimal(5,2)）**：与游戏币 **18,4** 精度不一致，演进时改为 `decimal(18,4)` 或迁移至结算域，避免对账误差。  
+3. 文档要求 **AI 算票在 Redis 内完成**，主库避免结算期同步锁表；账本与注单以异步一致性与幂等为准。
+
+---
+
+## 九、相关文档索引
+
+| 文档 | 说明 |
+|------|------|
+| `docs/36字花prd.md` | 玩法、代理双轨、风控与性能要求 |
+| `docs/业务流程.md` | C 端、代理、联营、总控、灾难恢复流程 |
+| `docs/后端.md` | 状态机、API、后台模块、安全与精度 |
+| `docs/CRUD生成逻辑说明.md` | BuildAdmin CRUD 路径与表名规范 |
+| `database/dfw_36zihua_schema_v1.sql` | 具体 DDL：字段、索引、注释 |
+
+### 9.1 新建表一览（字段以 SQL 为准）
+
+| 序号 | 表名 | 说明 |
+|------|------|------|
+| 1 | `game_config` | 动态参数 KV |
+| 2 | `game_period` | 期号与状态机 |
+| 3 | `game_bet_order` | 注单 |
+| 4 | `game_bet_auto` | 自动托管 |
+| 5 | `user_wallet_ledger` | 用户游戏币账本 |
+| 6 | `deposit_order` | 充值订单 |
+| 7 | `withdraw_order` | 提现订单 |
+| 8 | `game_agent_wallet` | 代理钱包 |
+| 9 | `game_agent_wallet_ledger` | 代理钱包流水 |
+| 10 | `agent_settlement_period` | 结算周期与大盘快照 |
+| 11 | `agent_commission_record` | 代理佣金明细 |
+| 12 | `affiliate_contract` | 联营契约 |
+| 13 | `affiliate_carryover` | 联营负结转 |
+| 14 | `operation_notice` | 运营公告 |
+| 15 | `user_notice_read` | 公告已读/确认 |
+| 16 | `user_site_message` | 站内信 |
+
+**既有表变更**：新建 `channel` 替代 `game_channel`；`admin` 增加子代理字段（`parent_admin_id`、`channel_id`、`invite_code`、`agent_role`）用于代理邀请链路管理；`admin_group` 增加 `channel_id` 实现角色组按渠道隔离；`game_user` 调整 `coin` 精度并增加 `channel_id`、`email`、`register_invite_code`、累计流水与风控、连胜兜底等字段。
+
+---
+
+**变更记录**
+
+| 版本 | 日期 | 说明 |
+|------|------|------|
+| V1.0 | 2026-04-14 | 初稿：表适配、新建表清单、验证步骤 |
+| V1.1 | 2026-04-14 | 增加可执行 DDL 脚本路径与新建表一览 |
+| V1.2 | 2026-04-14 | 修正口径：`game_channel` 仅顶级分红参数，子代理迁移至 `admin` |
+| V1.3 | 2026-04-14 | 收敛权限：仅超管可开奖，渠道/子代理仅拉用户 |
+| V1.4 | 2026-04-14 | 新建 `channel` 替代 `game_channel`，`admin_group` 按渠道隔离 |

docs/36字花prd.md

@@ -0,0 +1,164 @@
+
+
+# 《"36字花" 数字竞猜游戏功能需求与详细流程规格说明书 (PRD)》
+
+**文档版本**：V 1.0 (最终定稿版)
+**项目定位**：高频（30秒/期）、高爆率、多国本地化数字竞猜平台
+
+## 一、 系统全局架构与底层规范
+
+### 1.1 多币种与游戏币体系（统一结算层）
+为支持多国市场无缝拓展，系统底层不直接使用法币（如 RM、IDR）进行业务流转：
+*   **充值兑换**：用户使用本地法币充值，资金到账后，系统根据实时/固定汇率自动转化为平台统一的**游戏币（Coins/Credits）**。
+*   **前端展示**：所有下注、余额、开奖金额均显示为统一的“游戏币图标 + 数值”（如 💎 100）。
+*   **提现结汇**：提现时，系统将游戏币按提现国的当前汇率反向换算为本地法币打款。
+*   **技术优势**：代理分佣、AI算票引擎完全剥离汇率波动，仅对游戏币进行纯数学计算，极大降低系统复杂度。
+
+### 1.2 分布式站点架构
+系统拆分为三个独立的前端与一个核心后端服务：
+1.  **用户前端 (User Portal)**：H5/Web响应式，面向玩家游玩。
+2.  **代理后台 (Agent Portal)**：面向总代理/子代理的数据与分佣端。
+3.  **总控后台 (Admin Portal)**：面向平台运营方的全局管控端。
+
+### 1.3 域名与防封安全架构
+*   采用 **方案A（反向代理 + CDN 隐藏源站） + 方案D（域名轮换池 Domain Pool）** 的组合方案。确保源站IP完全隐藏，入口域名被封时可秒级切换备用域名。
+
+---
+
+## 二、 核心玩法与游戏机制
+
+### 2.1 36字花字典对照表
+系统包含36个字号，分为生肖、猛兽、飞禽、虫蛇、神兽五大类。前端需展示“编号+名称+专属插画”。
+
+| 编号 | 名称 | 编号 | 名称 | 编号 | 名称 |
+| :---: | :---: | :---: | :---: | :---: | :---: |
+| 01 | 鼠 | 02 | 牛 | 03 | 虎 |
+| 04 | 兔 | 05 | 龙 | 06 | 蛇 |
+| 07 | 马 | 08 | 羊 | 09 | 猴 |
+| 10 | 鸡 | 11 | 狗 | 12 | 猪 |
+| 13 | 狮 | 14 | 象 | 15 | 鹿 |
+| 16 | 熊 | 17 | 狼 | 18 | 豹 |
+| 19 | 鹰 | 20 | 鹤 | 21 | 孔雀 |
+| 22 | 鸳鸯 | 23 | 鸵鸟 | 24 | 天鹅 |
+| 25 | 蟾蜍 | 26 | 蜘蛛 | 27 | 蝙蝠 |
+| 28 | 蜈蚣 | 29 | 蝎 | 30 | 蛇蜥 |
+| 31 | 麒麟 | 32 | 凤凰 | 33 | 青龙 |
+| 34 | 白虎 | 35 | 朱雀 | 36 | 玄武 |
+
+其中 01-12 为十二生肖，13-18 为猛兽类，19-24 为飞禽类，25-30 为虫蛇类，31-36 为神兽类。
+
+### 2.2 游戏节奏（30秒循环制）
+每局精确耗时30秒，分为两个绝对阶段：
+
+*   **【常态阶段 / 下注期】 (0-20秒)**
+    *   倒计时 20 秒启动，接收玩家下注。
+    *   **UI表现**：前端界面的 36 个格子上的高亮光圈，呈现**持续不断、不规则、快速的随机跳动**，营造强烈的赌场氛围。
+*   **【封盘开奖期】 (20-30秒)**
+    *   **第 20.0 秒**：准时锁盘。在此之后到达服务器的任何延迟请求（如因网络卡顿），直接**拒单退回（提示：已封盘，下注失败）**。
+    *   **第 20-22 秒（AI算票）**：AI 引擎瞬间完成全网盈亏计算并得出结果。
+    *   **第 22-25 秒（开奖动画与异步派彩）**：后端在第 22.0 秒得出结果后，立刻将派彩结算指令打入 MQ 异步执行。同时前端高亮光圈加速跳动，配合紧张心跳音效。在3秒内不规则快速跳动后，“啪”地一声**定格**在最终中奖号码上。
+    *   **第 25-30 秒（结算展示）**：前端通过轮询/推送接收到余额更新通知，开始播放中奖者全屏/半屏的**金币喷洒动画（伴随爆金音效）**，弹出醒目提示【恭喜获得 💎 XXX】。
+
+### 2.3 下注交互与限制
+*   **便捷筹码**：提供 💎1, 5, 10, 25, 50, 100 的快捷筹码按钮。
+*   **下注限制**：默认每场最多选 **5个数字**（后台可配）。单局内所选的每个数字，下注金额必须一致。
+*   **单注上限**：后台须配置“单号最高下注额（Max Bet Limit）”（如 💎500），以对冲超级连赢带来的数学风险。
+*   **快捷操作**：
+    *   **重复上一注 (Re-bet)**：一键复制上一局的选号和金额并提交。
+    *   **自动托管 (Auto-Spin)**：允许设定连续下注 N 局。采用**服务端执行、逐局扣款**机制。开启后，服务器将在每局的 **00:00 - 00:10 秒之间（引入随机抖动，防止并发风暴）**平滑地为所有托管玩家自动扣款下注，直至局数完成或余额不足。
+
+---
+
+## 三、 连续中奖 (Streak Bonus) & 大奖 (Jackpot) 规则
+
+### 3.1 赔率累加机制
+*   基础赔率为 **1:33**。
+*   玩家连续中奖时，赔率累加：第1场 1:33；连中2场 1:66；连中3场 1:99... 依此类推。
+*   只要某场未中奖（中断），连续记录清零，赔率重置为 1:33。
+*   **【跳局处理规则】**：出于提高活跃度和平台流水考虑，**连胜必须基于系统的“连续期号”判断**。若玩家在连胜期间，主动跳过了某一局（未下注），则连胜状态**直接强制清零**。
+
+### 3.2 连赢期间的“换注限制”
+为了防止玩家利用连赢的高赔率恶意“洗盘梭哈”：
+*   **下注金额锁定**：若第 N 轮中奖，则第 N+1 轮的**总下注金额上限**严格锁定为第 N 轮的实际总下注额。（如：上轮总共下了💎100，本轮最多只能下💎100；若本轮只下了💎10并中奖，下一轮上限将降为💎10）。
+*   **选号策略自由**：在总金额不超限的前提下，**允许玩家改变选字的数量**。例如：上一轮花💎100买了5个字，本轮可以花💎100全押在1个字上。
+
+### 3.3 Jackpot 百万大奖触发
+*   当玩家连续中奖达到 **10 场** 时触发。
+*   **触发门槛与限红**：为防止利用极小注额套取大奖，系统设定【Jackpot资格最小下注额】（如单注连续 ≥ 💎50）。若连胜中有任何一局未达大奖基准入场额，连胜仅享受常规多倍赔率，**不触发额外 Jackpot 大奖**。
+*   **派发逻辑（额外叠加）**：达标玩家正常获得第10场应得的常规连赢派彩，系统将在此基础上，**额外发放 Jackpot 大奖（如 💎100万）**。
+*   触发后，连续中奖场次重置为0。
+
+---
+
+## 四、 AI算票风控与开奖系统
+
+### 4.1 自动开奖引擎（利润最大化 + 随机放水）
+*   **第一优先级**：AI在封盘后遍历36个数字的全局赔付（包含当前所有人的连胜倍率计算），优先开出让平台**总赔付最少（利润最大）**的数字。
+*   **RTP 全局风控放水池**：
+    *   系统累积平台抽水利润的固定比例进入“放水池”。
+    *   当开出某个高赔付（如触发别人连胜或大奖）造成的亏损 **小于** 当前放水池余额时，AI 有一定概率（后台可配，如15%）主动开出该数字，制造真实大奖作为营销案例。
+
+### 4.2 手动开奖机制
+*   管理员在后台一键切换至“手动模式”。
+*   为了避免 10 秒开奖期的操作延误，管理员必须在**下注倒计时期间（前20秒内）**提前选定本局必开数字。20秒锁盘后，系统直接开出预设号码。
+
+### 4.3 灾难恢复 (Disaster Recovery)
+*   若系统在某局运行中途（如第25秒）遭遇断电或宕机崩溃。
+*   服务器重启后的首要动作是自动执行 **“作废退本 (Void & Refund)”** 脚本：该期残局作废，退回所有玩家本局投注的本金，杜绝暗箱操作嫌疑。
+
+---
+
+## 五、 代理体系：普通刷水代理与联营合营代理双轨制 (Agent & Affiliate System)
+
+为了适应不同渠道的推广需求，系统代理账号不开放前台自助注册（必须由后台人工创建或通过专属代理邀请码裂变），并支持**两条平行的代理分佣路线**：
+
+### 5.1 普通刷水代理（以流水分桶为导向）
+这是一种不承担玩家赢钱风险的基础代理模式。
+1.  **大盘盈亏判断**：周期结算时，优先计算全平台总盈亏。若全平台整体亏损或平局，则该周期内所有此类代理不分佣。
+2.  **计算流水占比**：若全平台盈利，则按某代理整条线下注流水占全平台总流水的百分比，分配资金池。（*应分红 = 平台总盈利 × 该线下注流水占比%*）。
+3.  **无负结转优势**：即便该代理名下的玩家赢了钱，只要全平台大盘是盈利的，其依然可按流水占比分佣。
+
+### 5.2 多级拨比机制
+在上述“分桶利润分配”算法中，系统支持无限线代理树的极差分账。例如：GM 给出的盘口总分红给到顶部总代的是 80%，当这个总代拿手上的分红比例拨给下级时，若他给 70%，则这位下级能拿单线利润基数的 70%，总代由于极差卡段，自己这条线只能拿到 10%（80%-70%）的差额利润。这个级差裂变能一直往下分直到没有 % 为止。
+
+### 5.3 联营代理模式 (Affiliate Agent / 客损占成分成)
+这是专为有强大客源且愿意与平台**“共担风险、共享高利润”**的高级代理设计的模式（即行业标准的**联营 / 占成代理**）。
+*   **角色定位**：联营代理脱离于普通流水池，直接对其名下所有会员的总客损（净输赢）负责。
+*   **净亏损分润**：结算时，系统统计该联营代理辖区内的【玩家总输赢】，扣除平台抽水与通道费后得出【净客损】。联营代理按配置的**占成比例**（如 50%）直接分走这笔客损。
+*   **负结转 (Negative Carryover)**：这是联营核心机制。如果该联营代理名下的玩家在当期大赢，导致结算时客损为负（代理亏钱），该亏损数字将“结转”至该代理的下期账单中。在后续周期里，必须先用玩家的输额填平该负结转账单后，代理才能恢复分红提现。
+
+---
+
+## 六、 用户与财务风控流程
+
+### 6.1 用户交互与注册
+*   只需手机号/邮箱+密码注册，**无需 KYC 实名认证**。
+*   **路子图 (走势图)**：前端界面底部提供类似百家乐大路/珠盘路的走势图。以数字区分：单数使用**红色图标**（Odd），双数使用**蓝色图标**（Even），仅保留最近30期。
+
+### 6.2 平台公告与运营触达流程
+为保证由于赔率调整、节日活动或临时维护等重要信息能 100% 触达玩家，前端具备两级触达机制：
+*   **静默收件箱 (Silent Mailbox)**：常规活动或系统通知直接派发至用户的【公告信箱/站内信】，UI 仅显示红点提示，不中断玩家游戏体验。
+*   **强阻断强制公告 (Pop-out Notification)**：具有最高优先级。运营在后台下发此级公告后，无论玩家在任何界面、或者新用户首次登录，系统立即在屏幕中央弹出该公告弹窗。玩家**必须手动勾选“已阅读并同意”**后才可关闭弹窗并继续游戏下注。
+
+### 6.3 财务风控与提现
+*   **提现门槛**：用户必须完成历史总充值额 **1倍流水** 的有效下注方可提现，防止恶意洗钱。
+*   **提现限制**：最低提现 💎100，系统自动扣除 0.5% 手续费。
+*   **人工审核强阻断**：任何触发 **100万 Jackpot** 或达到系统设定的超大额提现标准的资金，不会直接进入可用余额，而是进入“冻结/审核中”状态。必须由总后台管理员核查 IP 与下注流水，点击【通过】后方可打款。
+
+### 6.4 历史数据展示限制
+*   前端的下注记录、开奖记录仅展示**最近 1 个月**的数据。
+*   历史更久远的数据前端做隐藏处理，减少数据库连表查询压力。
+
+---
+
+## 七、 技术性能要求规范
+
+由于“30秒/期”属超高频高并发场景，系统架构必须满足以下规范：
+
+1.  **冷热数据分离架构**：
+    *   必须引入 **Redis** 内存数据库，用于存放最新30期开奖记录、当前进行中的下注队列、以及玩家当前的连赢（Streak）状态。确保 AI 引擎 2 秒内完成算票。
+    *   引入 **ElasticSearch 或 ClickHouse** 存储海量历史注单与资金流水，与交易主库隔离开来。
+2.  **异步派彩机制**：
+    *   开奖后的批量资金入账、连胜进度更新、以及站内信发送，必须采用 **消息队列 (Kafka / RabbitMQ)** 异步削峰处理。严禁在 10 秒结算期内使用数据库同步强锁表，防止并发雪崩。
+3.  **API 频控 (Rate Limiting)**：
+    *   用户端及代理端所有核心 API（如下注、提现申请）必须配置严格的频率限制，防止恶意脚本撞库或刷单。

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 秒倒计时，游戏继续运转。
+
+---

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;` 确保高并发下余额不会被扣成负数。
+