「36字花」数据库与实施计划
文档版本：V1.4
依据：《36字花 PRD》《业务流程说明书》《后端系统规格书》及现有表 game_user
目标：明确分阶段落地步骤、需新建表、两表适配方向与可执行验证清单。
DDL 脚本（可执行）：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 数据库与模型
- DDL 执行后检查：金额字段均为
decimal(18,4)；channel、game_user、admin、admin_group、期号等关联字段有合理索引。
- 创建测试渠道（顶级）→ 创建子代理
admin（设置 parent_admin_id、channel_id、invite_code）→ 创建用户并挂载 channel_id，链路与后台筛选正常。
- 扣款更新采用「条件更新」语义（如
WHERE balance >= 扣款额），压测或单测验证不出现负余额。
7.2 业务规则（对照 PRD / 业务流程）
| 场景 |
验证要点 |
| 注册与邀请 |
玩家使用子代理邀请码注册时，先命中 admin.invite_code，再落到对应 channel_id |
| 子代理权限 |
渠道与子代理账号均无开奖权限；仅超管角色可访问开奖控制接口 |
| 30 秒节奏 |
0–20s 可下注，20s 后拒绝；约 22s 后可查开奖结果 |
| 连胜与跳局 |
连续期号未下注则连胜清零；连赢时本轮总下注不超过上轮总下注 |
| Jackpot |
连胜达阈值且单局下注不低于配置最小额才触发额外大奖 |
| 提现 |
有效投注 ≥ 总充值×配置倍数；最低提现与 0.5% 手续费；大额 / Jackpot 进审核 |
| 灾难恢复 |
模拟期卡在「计算中」，启动退本流程：期作废、本金退回账本 |
7.3 代理与结算（逻辑就绪后）
- 构造多代理树与多用户下注，跑一期结算脚本或单元测试纯算法。
- 大盘亏损：本期代理分佣为 0。
- 大盘盈利：流水占比分桶 + 级差，各级金额之和与线总包一致（可对照文档数值验算）。
- 联营：客损为负产生负结转；下期盈利先抵扣再分佣。
7.4 非功能
- Redis：当前期注单池、倒计时、近 30 期开奖缓存。
- MQ：派彩异步消费幂等（如
period_id + 用户 + 业务单号）。
- API：下注、提现等核心接口限流生效。
八、风险与依赖
- 子代理数据源：子代理统一在
admin，避免在 channel 重复建树造成双主数据源。
- 现有
profit_amount（decimal(5,2)）：与游戏币 18,4 精度不一致，演进时改为 decimal(18,4) 或迁移至结算域，避免对账误差。
- 文档要求 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 按渠道隔离 |
