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-23 17:50:25 +08:00
parent de3b9ab6bf
commit f7d0ee81f8
2 changed files with 133 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,6 +1,6 @@
# 「36字花」数据库与实施计划
**文档版本**：V1.14
**文档版本**：V1.16
**依据**：《36字花 PRD》《业务流程说明书》《后端系统规格书》及现有表 `user`
**目标**：明确分阶段落地步骤、需新建表、两表适配方向与可执行验证清单。
@@ -145,7 +145,7 @@
| 方向 | 说明 |
|------|------|
| 金额精度 | `coin` 调整为 **`decimal(18,4)`**（与规格书一致，禁止用浮点存币） |
| 金额精度 | `coin` 调整为 **`decimal(18,2)`**（与规格书一致，禁止用浮点存币） |
| 注册与归属 | `invite_code` 或注册时解析 URL 与 `channel.code` 绑定 |
| 提现门槛 | `user.total_deposit_coin` / `user.total_withdraw_coin` / `user.bet_flow_coin` + `game_config.withdraw_bet_flow_ratio`（净充值打码口径，全项目统一） |
| 风控 | 禁止登录 / 禁止下注 / 禁止提现等，可用位标记或独立布尔字段 |
@@ -206,7 +206,7 @@
| 表名 | 用途 |
|------|------|
| **`user_wallet_record`**（原草案名 `user_wallet_ledger`，以 DDL 为准） | **玩家游戏币钱包流水**：充值、提现（含冻结/解冻）、平台划入划出、管理员加扣币、下注、派彩、手续费、作废退款、调账等；金额 **`decimal(18,4)`**，**只增不改**；与 `user.coin` 变更须同事务 + 条件更新 |
| **`user_wallet_record`**（原草案名 `user_wallet_ledger`，以 DDL 为准） | **玩家游戏币钱包流水**：充值、提现（含冻结/解冻）、平台划入划出、管理员加扣币、下注、派彩、手续费、作废退款、调账等；金额 **`decimal(18,2)`**，**只增不改**；与 `user.coin` 变更须同事务 + 条件更新 |
| `deposit_order` | 第三方充值、法币金额、汇率、游戏币到账、回调状态 |
| `withdraw_order` | 提现申请、手续费、审核状态、Jackpot / 大额标记 |
@@ -240,7 +240,7 @@
### 8.1 数据库与模型
1. DDL 执行后检查：金额字段均为 **`decimal(18,4)`**；`channel`、`user`、`admin`、`admin_group`、期号等关联字段有合理索引。
1. DDL 执行后检查：金额字段均为 **`decimal(18,2)`**；`channel`、`user`、`admin`、`admin_group`、期号等关联字段有合理索引。
2. 创建测试渠道（顶级）→ 创建子代理 `admin`（设置 `parent_admin_id`、`channel_id`、`invite_code`）→ 创建用户并挂载 `channel_id`，链路与后台筛选正常。
3. 扣款更新采用「**条件更新**」语义（如 `WHERE balance >= 扣款额`），压测或单测验证**不出现负余额**。
@@ -286,6 +286,21 @@
3. **大盘盈利**：流水占比分桶 + 级差，各级金额之和与线总包一致（可对照文档数值验算）。
4. **联营**：客损为负产生负结转；下期盈利先抵扣再分佣。
### 8.3.1 渠道结算新流程（2026-04-23）
1. **仅超管可结算**：按渠道结算周期（支持自动任务与手动提前结算）执行渠道结算。
2. **结算即发放**：结算时按 `channel_admin_share` 比例，直接发放到管理员钱包并写入 `admin_wallet_record`（`commission_income`），同时写 `agent_settlement_period` / `agent_commission_record`。
3. **提前结算规则**：手动提前结算后，新的周期起点从本次结算结束时间开始，后续自动周期归入下个结算段。
4. **停用渠道限制**：`channel.status != 1` 时，该渠道不再允许玩家注册与登录。
### 8.3.2 后台管理员资金与提现流程（2026-04-23）
1. **管理员钱包隔离**：新增 `admin_wallet`、`admin_wallet_record`，与玩家钱包完全隔离。
2. **分红入账**：渠道分红结算后，写管理员钱包入账流水（`commission_income`）。
3. **提现申请**：管理员在个人中心发起提现，金额先冻结（`withdraw_freeze`），生成 `admin_withdraw_order`（`status=0`）。
4. **渠道超管审核**：仅该渠道顶级角色组（`admin_group.pid=0`）中的管理员可审核本渠道提现单。
5. **审核通过/拒绝**：通过则扣减冻结并累计提现（`withdraw_success`）；拒绝则退回可用余额（`withdraw_refund`）。
### 8.4 非功能
- **Redis（已落地）**
@@ -300,7 +315,7 @@
## 九、风险与依赖
1. **子代理数据源**：子代理统一在 `admin`，避免在 `channel` 重复建树造成双主数据源。
2. **现有 `profit_amount`（decimal(5,2)）**：与游戏币 **18,4** 精度不一致，演进时改为 `decimal(18,4)` 或迁移至结算域，避免对账误差。
2. **现有 `profit_amount`（decimal(5,2)）**：与游戏币 **18,4** 精度不一致，演进时改为 `decimal(18,2)` 或迁移至结算域，避免对账误差。
3. 文档要求 **AI 算票在 Redis 内完成**（演进目标），当前实现以 **MySQL `game_record` + 服务层缓存** 为主；主库仍应避免结算期大范围锁表；账本与注单以事务与幂等为准。
4. **全局对局一致性**：任何需求（多租户展示、渠道后台）均不得引入「按渠道独立期号/独立开奖」；若出现产品歧义，以 **§1.1** 为准，避免公平性质疑与客诉。
@@ -360,6 +375,7 @@
| V1.12 | 2026-04-18 | 下注口径：`bet_order` 仅保留 `total_amount`（整笔压注），删除 `unit_amount`、`pick_count`；DDL 与 Phinx 迁移 `20260418270000_bet_order_drop_unit_amount_pick_count` 对齐 |
| V1.14 | 2026-04-20 | 服务端 Redis 热点缓存：`GameHotDataRedis`（`user` / `game_config` / `game_record`），`config/game_hot_cache.php` 与 `.env-example` 中 `GAME_HOT_CACHE_*`；更新 §1.1、§2.1、§8.4、第九章风险与依赖、附录 `user`；与 `CACHE_DRIVER`（系统 `config` 表文件缓存）区分说明 |
| V1.15 | 2026-04-20 | 热点写路径收口：`GameHotDataCoordinator` + `GameHotDataLock` + `GameHotDataWriteQueue` / `GameHotDataQueueConsumer`；文档与实现对齐（替代仅 `*Forget` 描述）；移动端 `betPlace` 与后台钱包共用用户互斥锁及 `coin` 乐观更新 |
| V1.16 | 2026-04-23 | 渠道结算改为单阶段口径（仅超管结算，结算即按比例发放管理员钱包并记录操作人）与管理员钱包提现流程（`admin_wallet` / `admin_wallet_record` / `admin_withdraw_order`，渠道顶级组审核） |
---
@@ -376,7 +392,7 @@
| `invite_code` | 渠道侧邀请码（与 PRD「邀请码由管理员生成」并存时，以产品定义为准） |
| `name` | 渠道名称 |
| `agent_mode` | `turnover` 普通刷水 / `affiliate` 联营，决定分红与契约字段使用方式 |
| `profit_amount` / `total_profit_amount` / `commission_pool_amount` | 经营与分红池快照类金额，**decimal(18,4)** |
| `profit_amount` / `total_profit_amount` / `commission_pool_amount` | 经营与分红池快照类金额，**decimal(18,2)** |
| `turnover_share_rate` / `affiliate_share_rate` / `affiliate_fee_rate` | 分红与联营费率类参数 |
| `carryover_balance` | 联营负结转余额（可负） |
| `admin_id` / `admin_group_id` | 渠道负责人（管理员）、渠道绑定的角色组 |
@@ -386,7 +402,7 @@
| 字段 | 作用 |
|------|------|
| `coin` | 当前游戏币余额，**decimal(18,4)**，更新须条件更新防负余额 |
| `coin` | 当前游戏币余额，**decimal(18,2)**，更新须条件更新防负余额 |
| `channel_id` | 归属渠道；历史 `game_channel_id` 若仍存在，迁移期注意双写/对照 |
| `register_invite_code` | 注册时邀请码快照，用于审计与归属 |
| `total_deposit_coin` / `total_withdraw_coin` | 累计充值入账、累计提现出账（提现受理时累加）；与「净充值」口径配合校验提现门槛 |
@@ -420,7 +436,7 @@
| 表 | 要点 |
|----|------|
| `game_period` | **全平台唯一**期号：`period_no` 全局唯一；`status` 状态机；开奖结果与作废原因。**无 `channel_id` 字段**：对局不按渠道拆分。 |
| `bet_order` | 注单关联**全局** `period_id`；`channel_id`（若有）为**用户/归属快照**，便于分润与查询，**不表示**独立牌桌或独立开奖。`pick_numbers` 为所选号码集合；**`total_amount` 为整笔压注金额**（命中集合内任一开奖号码即按该金额参与派彩倍率计算）。已移除历史字段 `unit_amount` / `pick_count`。`idempotency_key` 幂等；金额 **18,4**；`win_amount` / `jackpot_extra_amount` |
| `game_play_record`（兼容视图 `bet_order`） | 游玩记录关联**全局** `period_id`；`channel_id` 为**用户/归属快照**，便于分润与查询，**不表示**独立牌桌或独立开奖。`pick_numbers` 为所选号码集合；**`total_amount` 为整笔游玩金额**（命中集合内任一开奖号码即按该金额参与派彩倍率计算）。已移除历史字段 `unit_amount` / `pick_count`。`idempotency_key` 幂等；金额 **18,4**；`win_amount` / `jackpot_extra_amount` |
| `game_bet_auto` | 托管剩余局数、选号快照、抖动时间等；仍挂在**全局**期号下 |
### 11.6 `user_wallet_record`（玩家钱包流水）
@@ -448,7 +464,7 @@
### 11.8 代理钱包与结算域（`game_agent_wallet`、`game_agent_wallet_ledger`、`agent_settlement_period`、`agent_commission_record`、`affiliate_*`）
见 DDL 注释：代理余额与流水、结算周期大盘快照、佣金行、联营契约与负结转；金额均为 **decimal(18,4)**，与玩家账本区分职责。
见 DDL 注释：代理余额与流水、结算周期大盘快照、佣金行、联营契约与负结转；金额均为 **decimal(18,2)**，与玩家账本区分职责。
### 11.9 运营与消息（`operation_notice`、`user_notice_read`、`user_site_message`）