245 lines
12 KiB
Markdown
245 lines
12 KiB
Markdown
# 「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` 按渠道隔离 |
|