说明文档

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` 按渠道隔离 |