From fb16321b7e527fd818ab5fc78044ea9a1b504ae8 Mon Sep 17 00:00:00 2001 From: zhenhui <1276357500@qq.com> Date: Wed, 15 Apr 2026 18:06:15 +0800 Subject: [PATCH] =?UTF-8?q?=E6=89=A7=E8=A1=8C=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/36字花-数据库与实施计划.md | 233 ++++++++++++++++++++++++++++---- 1 file changed, 209 insertions(+), 24 deletions(-) diff --git a/docs/36字花-数据库与实施计划.md b/docs/36字花-数据库与实施计划.md index 0553cdd..58d4ee8 100644 --- a/docs/36字花-数据库与实施计划.md +++ b/docs/36字花-数据库与实施计划.md @@ -1,11 +1,11 @@ # 「36字花」数据库与实施计划 -**文档版本**：V1.4 -**依据**：《36字花 PRD》《业务流程说明书》《后端系统规格书》及现有表 `game_user` +**文档版本**：V1.10 +**依据**：《36字花 PRD》《业务流程说明书》《后端系统规格书》及现有表 `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` 表，及 `user` / `admin` / `admin_group` 的 `ALTER` 语句，以及新建表完整 `CREATE TABLE`（字段级 `COMMENT` 即字段清单）。 --- @@ -14,22 +14,93 @@ | 表名 | 当前角色 | 目标角色 | |------|----------|----------| | `channel` | 新渠道主表 | **顶级代理渠道分红配置表**：由超管创建，维护分红方式、分红金额、总利润等渠道参数 | -| `game_user` | 用户（coin、channel_id 等） | **C 端玩家主表**：余额与精度、归属代理、流水与风控字段 | +| `user` | 用户（coin、channel_id 等） | **C 端玩家主表**：余额与精度、归属代理、流水与风控字段 | | `admin` | 后台管理员 | **子代理承载表**：顶级代理下级代理放在 `admin`，通过 `invite_code` 管理客户，统一无开奖控制权 | | `admin_group` | 角色组 | **按渠道隔离**：角色组归属 `channel`，渠道仅管理本渠道角色组 | +### 1.1 全局对局与渠道职责（重要） + +与「多渠道」并存的一条硬规则：**对局与开奖全局唯一**，渠道**不**切分牌桌、**不**各自开奖。 + +| 维度 | 口径 | +|------|------| +| **期号 / 对局** | **全平台共用一套** `game_period`（及全网唯一的当前 `period_no`、同一套状态机）。不存在「每个渠道一局」或「每渠道独立期号表」。 | +| **开奖结果** | **全渠道玩家共享同一期、同一 `result_number`**。所有玩家（无论来自哪个 `channel_id`）压的是**同一场**；避免用户感知「不同入口有不同局、可被渠道操纵」。 | +| **渠道的用途** | `channel`、`user.channel_id`、注单上的 **`channel_id` 快照**（若有）仅用于 **代理归属、分润、风控与后台数据范围**，**不**用于生成多套并行对局或独立开奖。 | +| **Redis / 接口** | 当前期倒计时、封盘、算票、开奖号码等 **热状态全局一份**；不得在业务上按渠道维护多套「当前期」或多套开奖结果。 | + +> **与 DDL 的对应**：`game_period` **不设** `channel_id`；`bet_order.channel_id` 为下单时用户归属快照，不改变「全场一局」语义。详见 §11.5。 + --- -## 二、分阶段执行计划 +## 二、分阶段执行计划与「先核心、后细节」顺序 + +**原则**：先打通 **账号 / 渠道 / 余额与流水 / 最小可演示闭环**，再叠 **玩法细则、自动开奖调度、公告与站内信等展示类能力**。避免一上来就做全量 DDL 与全部后台菜单，导致联调面过大。 + +### 2.1 总览（与下文 P0～P4 对应） | 阶段 | 目标 | 主要内容 | |------|------|----------| -| **P0** | 数据地基 | 新建 `channel` 并适配 `game_user`、`admin`、`admin_group`；建立账本类最小表集（金额精度统一） | +| **P0** | 数据地基 | 新建 `channel` 并适配 `user`、`admin`、`admin_group`；建立账本类最小表集（金额精度统一） | | **P1** | 游戏核心 | 期号、注单、开奖、系统配置；Redis 状态机 + MQ 异步落库 | | **P2** | 资金与风控 | 充提订单、流水账、提现审核、Jackpot / 大额拦截 | | **P3** | 代理与结算 | 流水占比分桶、级差、联营占成与负结转（表结构 + 跑批骨架） | | **P4** | 运营与审计 | 公告（含 Pop-out）、站内信、后台 RBAC 与操作审计 | +### 2.2 建议先做的：第一批建表（核心路径） + +按依赖顺序执行 DDL（或 Phinx），**优先保证下列表/变更已落地**，其余表可分期补建： + +| 顺序 | 类型 | 对象 | 说明 | +|------|------|------|------| +| 1 | 新建 | **`channel`** | 渠道与顶级代理参数；替代历史 `game_channel` 方向 | +| 2 | 适配 | **`user`、`admin`、`admin_group`** | `coin` 精度、`channel_id`、邀请码与风控等（见 §四～§六） | +| 3 | 新建 | **`game_config`** | 全局可调参数（局时长、下注窗口等），避免写死 | +| 4 | 新建 | **`user_wallet_record`** | 玩家钱包流水，与余额变更同事务、可审计 | +| 5 | 新建 | **`game_period`**、**`bet_order`** | 最小「一期号 + 注单」闭环；先有表再写状态机与接口 | + +**第一批可暂缓的表（归入后续迭代）**：`game_bet_auto`（自动托管）、`operation_notice` / `user_notice_read` / `user_site_message`（纯展示与触达）、`game_agent_wallet` 及结算域各表（代理分佣与联营跑批）。 + +### 2.3 建议先做的：第一批后台菜单（与核心能力对齐） + +在 BuildAdmin **`admin_rule`** 中，**优先保证**与下列能力相关的菜单与按钮权限可配置（具体 `component` 路径以仓库为准）： + +| 优先级 | 菜单能力 | 目的 | +|--------|----------|------| +| 高 | **渠道**、**游戏用户**、**角色组 / 管理员**（含渠道与邀请码相关字段） | 搭好「谁管哪条线、玩家归谁」 | +| 高 | **用户管理 / 用户钱包流水** | 覆盖玩家主数据与账务对账 | +| 高 | **游戏对局 / 压注订单** | 核心玩法与对账入口 | +| 中 | **游戏配置 / 36字花字典** | 运营参数与字典维护 | +| 中 | **充值订单 / 提现订单** | 充提流程管理与审核 | +| 低 | **公告 / 站内信**、**代理结算** 等 | 属 **P3～P4**，核心跑通后再接 | + +### 2.4 明确放到「细节阶段」的能力（勿阻塞第一期） + +下列项依赖 **P1 状态机、定时任务、前端 C 端页面** 较完整后再做，避免与「账号 + 余额 + 最小下注」抢工期： + +- **玩法细则**：选号上限、连胜倍率、Jackpot 条件等在 `game_config` 与代码中逐步细化即可。 +- **自动开奖 / 调度**：依赖期号服务、Redis 与（可选）MQ；表结构可先建，**调度与算票逻辑后迭代**。 +- **游戏公告、强弹窗、站内信展示**：表可后建；**后台编辑 + C 端展示** 属于运营体验增强，放在核心闭环之后。 + +### 2.5 最小可验收里程碑（建议） + +1. **P0 完成**：能创建渠道与子代理管理员，玩家归属正确，`coin` 与 `user_wallet_record` 手工或脚本入账可对上。 +2. **P1 骨架完成**：能创建期号、写入注单、产生钱包流水（即使开奖仍为**手动或脚本模拟**）。 +3. 再推进 **自动流程、充提、公告展示** 与 **P3 结算**。 + +### 2.6 本次重构迁移顺序（已执行口径） + +1. 新建订单表：`deposit_order`、`withdraw_order`（带 `order_no` 唯一索引、`user_id/status/create_time` 常用索引）。 +2. 硬重命名：`game_user -> user`、`game_bet_order -> bet_order`。 +3. 重建菜单与权限目录：`user`、`order`、`game`、`config`、`record`。 +4. 新增菜单节点： + - `user/user` + - `order/betOrder`、`order/depositOrder`、`order/withdrawOrder` + - `game/period` + - `config/gameConfig`、`config/ziHuaDictionary` + - `record/userWalletRecord` +5. 清理收口：删除迁移过程中的冗余权限别名规则，仅保留最终模块节点（`user/order/game/config/record`）。 + --- ## 三、`channel` 设计（替代 `game_channel`） @@ -54,7 +125,7 @@ --- -## 四、`game_user` 适配（用户表） +## 四、`user` 适配（用户表） ### 4.1 建议保留字段 @@ -109,11 +180,13 @@ ### 7.1 游戏引擎 +**对局范围**：与 §1.1 一致——**全平台一套期号**，不按渠道分桌；详见 `game_period` 无 `channel_id` 的 DDL。 + | 表名 | 用途 | |------|------| -| `game_period`（或 `game_issue`） | 期号、状态机阶段、开奖号码、自动/手动、作废标记 | -| `game_bet_order` | 注单：期号、用户、选号、单注额、总额、状态（扣款 / 结算 / 退款） | -| `game_bet_auto`（可选） | 自动托管：剩余局数、选号快照、启停状态 | +| `game_period`（或 `game_issue`） | **全局**期号、状态机阶段、开奖号码、自动/手动、作废标记（**非**每渠道一局） | +| `bet_order` | 注单：关联全局 `period_id`；可选 `channel_id` 为用户归属快照（分润/查询），**非**独立牌桌 | +| `game_bet_auto`（可选） | 自动托管：剩余局数、选号快照、启停状态（仍挂在全局期号下） | ### 7.2 系统配置 @@ -125,7 +198,7 @@ | 表名 | 用途 | |------|------| -| `user_wallet_ledger`（或 `game_user_balance_log`） | 充值、下注扣款、派彩、提现冻结、手续费、人工调账；金额 **`decimal(18,4)`** | +| **`user_wallet_record`**（原草案名 `user_wallet_ledger`，以 DDL 为准） | **玩家游戏币钱包流水**：充值、提现（含冻结/解冻）、平台划入划出、管理员加扣币、下注、派彩、手续费、作废退款、调账等；金额 **`decimal(18,4)`**，**只增不改**；与 `user.coin` 变更须同事务 + 条件更新 | | `deposit_order` | 第三方充值、法币金额、汇率、游戏币到账、回调状态 | | `withdraw_order` | 提现申请、手续费、审核状态、Jackpot / 大额标记 | @@ -155,15 +228,27 @@ --- -## 七、验证步骤 +## 八、验证步骤 -### 7.1 数据库与模型 +### 8.1 数据库与模型 -1. DDL 执行后检查：金额字段均为 **`decimal(18,4)`**；`channel`、`game_user`、`admin`、`admin_group`、期号等关联字段有合理索引。 +1. DDL 执行后检查：金额字段均为 **`decimal(18,4)`**；`channel`、`user`、`admin`、`admin_group`、期号等关联字段有合理索引。 2. 创建测试渠道（顶级）→ 创建子代理 `admin`（设置 `parent_admin_id`、`channel_id`、`invite_code`）→ 创建用户并挂载 `channel_id`，链路与后台筛选正常。 3. 扣款更新采用「**条件更新**」语义（如 `WHERE balance >= 扣款额`），压测或单测验证**不出现负余额**。 -### 7.2 业务规则（对照 PRD / 业务流程） +### 8.1.1 菜单与权限回归（本次新增） + +1. 使用超管登录，确认五大目录 `user/order/game/config/record` 可见。 +2. 使用普通角色登录，逐项验证按钮权限（`index/add/edit/del/save`）是否与授权一致。 +3. 抽查重点页面： + - `user/user` + - `order/depositOrder`、`order/withdrawOrder`、`order/betOrder` + - `game/period` + - `config/gameConfig`、`config/ziHuaDictionary` + - `record/userWalletRecord` +4. 验证 `config/ziHuaDictionary` 的读取与保存权限均命中，且仅授权角色可操作。 + +### 8.2 业务规则（对照 PRD / 业务流程） | 场景 | 验证要点 | |------|----------| @@ -175,14 +260,14 @@ | 提现 | 有效投注 ≥ 总充值×配置倍数；最低提现与 0.5% 手续费；大额 / Jackpot 进审核 | | 灾难恢复 | 模拟期卡在「计算中」，启动退本流程：期作废、本金退回账本 | -### 7.3 代理与结算（逻辑就绪后） +### 8.3 代理与结算（逻辑就绪后） 1. 构造多代理树与多用户下注，跑一期结算脚本或单元测试纯算法。 2. **大盘亏损**：本期代理分佣为 0。 3. **大盘盈利**：流水占比分桶 + 级差，各级金额之和与线总包一致（可对照文档数值验算）。 4. **联营**：客损为负产生负结转；下期盈利先抵扣再分佣。 -### 7.4 非功能 +### 8.4 非功能 - Redis：当前期注单池、倒计时、近 30 期开奖缓存。 - MQ：派彩异步消费**幂等**（如 `period_id` + 用户 + 业务单号）。 @@ -190,15 +275,16 @@ --- -## 八、风险与依赖 +## 九、风险与依赖 1. **子代理数据源**：子代理统一在 `admin`，避免在 `channel` 重复建树造成双主数据源。 2. **现有 `profit_amount`（decimal(5,2)）**：与游戏币 **18,4** 精度不一致，演进时改为 `decimal(18,4)` 或迁移至结算域，避免对账误差。 -3. 文档要求 **AI 算票在 Redis 内完成**，主库避免结算期同步锁表；账本与注单以异步一致性与幂等为准。 +3. 文档要求 **AI 算票在 Redis 内完成**，主库避免结算期同步锁表；账本与注单以异步一致性与幂等为准。 +4. **全局对局一致性**：任何需求（多租户展示、渠道后台）均不得引入「按渠道独立期号/独立开奖」；若出现产品歧义，以 **§1.1** 为准，避免公平性质疑与客诉。 --- -## 九、相关文档索引 +## 十、相关文档索引 | 文档 | 说明 | |------|------| @@ -208,15 +294,15 @@ | `docs/CRUD生成逻辑说明.md` | BuildAdmin CRUD 路径与表名规范 | | `database/dfw_36zihua_schema_v1.sql` | 具体 DDL：字段、索引、注释 | -### 9.1 新建表一览（字段以 SQL 为准） +### 10.1 新建表一览（字段以 SQL 为准） | 序号 | 表名 | 说明 | |------|------|------| | 1 | `game_config` | 动态参数 KV | | 2 | `game_period` | 期号与状态机 | -| 3 | `game_bet_order` | 注单 | +| 3 | `bet_order` | 注单 | | 4 | `game_bet_auto` | 自动托管 | -| 5 | `user_wallet_ledger` | 用户游戏币账本 | +| 5 | `user_wallet_record` | 玩家游戏币钱包流水（替代旧名 `user_wallet_ledger`） | | 6 | `deposit_order` | 充值订单 | | 7 | `withdraw_order` | 提现订单 | | 8 | `game_agent_wallet` | 代理钱包 | @@ -229,7 +315,7 @@ | 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`、累计流水与风控、连胜兜底等字段。 +**既有表变更**：新建 `channel` 替代 `game_channel`；`admin` 增加子代理字段（`parent_admin_id`、`channel_id`、`invite_code`、`agent_role`）用于代理邀请链路管理；`admin_group` 增加 `channel_id` 实现角色组按渠道隔离；`game_user` 已硬重命名为 `user`，`game_bet_order` 已硬重命名为 `bet_order`；`user_wallet_record`、`game_config` 保持现名。 --- @@ -242,3 +328,102 @@ | V1.2 | 2026-04-14 | 修正口径：`game_channel` 仅顶级分红参数，子代理迁移至 `admin` | | V1.3 | 2026-04-14 | 收敛权限：仅超管可开奖，渠道/子代理仅拉用户 | | V1.4 | 2026-04-14 | 新建 `channel` 替代 `game_channel`，`admin_group` 按渠道隔离 | +| V1.5 | 2026-04-15 | 落地 `game_user_wallet_record` 玩家钱包流水表；文档增补字段说明附录；与 DDL 统一命名 | +| V1.6 | 2026-04-15 | 增加「先核心后细节」实施顺序：先建表/菜单清单、可暂缓表与细节阶段能力；修正章节编号（验证步骤改为第八章） | +| V1.7 | 2026-04-15 | 明确「多渠道、单场对局」：全平台共用 `game_period` 与同一开奖；渠道仅归属/分润；附录 `game_period`/`bet_order` 注释对齐 | +| V1.8 | 2026-04-15 | §7.1 游戏引擎表与 §1.1 对齐：显式说明全局期号、`bet_order.channel_id` 仅为归属快照 | +| V1.9 | 2026-04-15 | 落地模块化重构：`game_user->user`、`game_bet_order->bet_order`；新增 `deposit_order`/`withdraw_order`；后台菜单重组为 `user/order/game/config/record` 五大目录 | +| V1.10 | 2026-04-15 | 完成表名与权限规则收口：`user_wallet_record`、`game_config` 保持不变；移除冗余 snake alias 菜单规则，文档口径与线上结构一致 | + +--- + +## 十一、附录：主要表字段说明（与 `database/dfw_36zihua_schema_v1.sql` 同步） + +以下为各表**字段含义与使用要点**，便于评审与联调；**以仓库内 DDL 为最终口径**。 + +### 11.1 `channel`（渠道 / 顶级代理分红参数） + +| 字段 | 作用 | +|------|------| +| `id` | 主键 | +| `code` | 渠道标识，业务唯一 | +| `invite_code` | 渠道侧邀请码（与 PRD「邀请码由管理员生成」并存时，以产品定义为准） | +| `name` | 渠道名称 | +| `agent_mode` | `turnover` 普通刷水 / `affiliate` 联营，决定分红与契约字段使用方式 | +| `profit_amount` / `total_profit_amount` / `commission_pool_amount` | 经营与分红池快照类金额，**decimal(18,4)** | +| `turnover_share_rate` / `affiliate_share_rate` / `affiliate_fee_rate` | 分红与联营费率类参数 | +| `carryover_balance` | 联营负结转余额（可负） | +| `top_admin_id` | 顶级代理管理员，关联 `admin.id` | +| `admin_id` / `admin_group_id` | 创建人、渠道绑定的角色组 | +| `status` / `remark` / `create_time` / `update_time` | 状态、备注、时间戳 | + +### 11.2 `user`（C 端玩家） + +| 字段 | 作用 | +|------|------| +| `coin` | 当前游戏币余额，**decimal(18,4)**，更新须条件更新防负余额 | +| `channel_id` | 归属渠道；历史 `game_channel_id` 若仍存在，迁移期注意双写/对照 | +| `register_invite_code` | 注册时邀请码快照，用于审计与归属 | +| `total_deposit_coin` / `total_valid_bet_coin` | 累计充值入账、累计有效投注；提现流水倍数校验用 | +| `risk_flags` | 风控位（如禁止登录/下注/提现，按位定义） | +| `current_streak` / `last_bet_period_no` | 连胜与期号兜底；高频仍以 Redis 为准 | +| `admin_id` | 归属子代理管理员 | +| 其余 | 账号、头像、状态、时间戳等见 DDL | + +### 11.3 `admin` / `admin_group`（子代理与角色组） + +| 表/字段 | 作用 | +|---------|------| +| `admin.parent_admin_id` | 子代理上下级 | +| `admin.channel_id` | 所属渠道 | +| `admin.invite_code` | 子代理邀请码，注册归属 | +| `admin.agent_role` | 角色类型（均无开奖权） | +| `admin_group.channel_id` | 角色组归属渠道；`NULL` 可为系统级（仅超管） | +| `admin_group.commission_rate` | 角色组分红比例（百分比） | + +### 11.4 `game_config`（动态参数） + +| 字段 | 作用 | +|------|------| +| `config_key` | 全局唯一键 | +| `config_value` / `value_type` | 参数值及类型（含 JSON） | +| `remark` | 说明，禁止业务写死应读此表 | + +### 11.5 `game_period` / `bet_order` / `game_bet_auto` + +| 表 | 要点 | +|----|------| +| `game_period` | **全平台唯一**期号：`period_no` 全局唯一；`status` 状态机；开奖结果与作废原因。**无 `channel_id` 字段**：对局不按渠道拆分。 | +| `bet_order` | 注单关联**全局** `period_id`；`channel_id`（若有）为**用户/归属快照**，便于分润与查询，**不表示**独立牌桌或独立开奖。`idempotency_key` 幂等；金额 **18,4**；`win_amount` / `jackpot_extra_amount` | +| `game_bet_auto` | 托管剩余局数、选号快照、抖动时间等；仍挂在**全局**期号下 | + +### 11.6 `user_wallet_record`（玩家钱包流水） + +| 字段 | 作用 | +|------|------| +| `user_id` | 玩家 `user.id` | +| `channel_id` | **账务发生时**渠道快照，便于按渠道查询与对账；入账逻辑应写入 | +| `biz_type` | 业务类型：`deposit`、`withdraw`、`platform_in`、`platform_out`、`admin_credit`、`admin_deduct`、`bet`、`payout`、`fee`、`void_refund`、`adjust` 等（字符串枚举，与代码常量一致） | +| `direction` | `1` 入金 / `2` 出金；与 `amount` 恒正配合使用 | +| `amount` | 变动额，**恒正** | +| `balance_before` / `balance_after` | 变动前后余额，对账与审计 | +| `ref_type` / `ref_id` | 关联订单或业务主键（如 `deposit_order`、`bet_order`） | +| `idempotency_key` | 幂等键，防重复记账（唯一索引，允许多 `NULL`） | +| `operator_admin_id` | 人工加扣币时的操作者 `admin.id` | +| `remark` | 说明 | +| `create_time` | 流水时间；**本表不设 `update_time`，禁止 UPDATE** | + +### 11.7 `deposit_order` / `withdraw_order` + +| 表 | 要点 | +|----|------| +| `deposit_order` | 法币、`fx_rate`、`coin_amount`、网关单号、回调存档 | +| `withdraw_order` | 申请额、手续费、审核与 Jackpot 标记、驳回原因 | + +### 11.8 代理钱包与结算域（`game_agent_wallet`、`game_agent_wallet_ledger`、`agent_settlement_period`、`agent_commission_record`、`affiliate_*`） + +见 DDL 注释：代理余额与流水、结算周期大盘快照、佣金行、联营契约与负结转；金额均为 **decimal(18,4)**，与玩家账本区分职责。 + +### 11.9 运营与消息（`operation_notice`、`user_notice_read`、`user_site_message`） + +公告类型（含强弹）、已读确认；站内信与公告分离存储，详见各表 `COMMENT`。