mojiahui/webman-buildadmin
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

执行文档

Browse Source
This commit is contained in:
zhenhui
2026-04-15 18:06:15 +08:00
parent 7e695d32cf
commit fb16321b7e
1 changed files with 209 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -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`。