项目文档

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

@@ -1,6 +1,6 @@
 # 「36字花」数据库与实施计划
 
-**文档版本**：V1.10  
+**文档版本**：V1.14  
 **依据**：《36字花 PRD》《业务流程说明书》《后端系统规格书》及现有表 `user`  
 **目标**：明确分阶段落地步骤、需新建表、两表适配方向与可执行验证清单。
 
@@ -27,7 +27,7 @@
 | **期号 / 对局** | **全平台共用一套** `game_period`（及全网唯一的当前 `period_no`、同一套状态机）。不存在「每个渠道一局」或「每渠道独立期号表」。 |
 | **开奖结果** | **全渠道玩家共享同一期、同一 `result_number`**。所有玩家（无论来自哪个 `channel_id`）压的是**同一场**；避免用户感知「不同入口有不同局、可被渠道操纵」。 |
 | **渠道的用途** | `channel`、`user.channel_id`、注单上的 **`channel_id` 快照**（若有）仅用于 **代理归属、分润、风控与后台数据范围**，**不**用于生成多套并行对局或独立开奖。 |
-| **Redis / 接口** | 当前期倒计时、封盘、算票、开奖号码等 **热状态全局一份**；不得在业务上按渠道维护多套「当前期」或多套开奖结果。 |
+| **Redis / 接口** | 当前期倒计时、封盘、算票、开奖号码等 **热状态全局一份**；不得在业务上按渠道维护多套「当前期」或多套开奖结果。**已实现（2026-04）**：`GameHotDataRedis` 将 **`user` 全行、`game_config` 按 key、`game_record`（活跃局 / 按 id / 最新一行）** 以 JSON 缓存在 Redis（键前缀 `dfw:v1:`），配置见 `config/game_hot_cache.php` 与 `.env-example` 中 `GAME_HOT_CACHE_*`；与 `config/cache.php` 的 `CACHE_DRIVER`（系统表 `config` 文件缓存）**相互独立**。 |
 
 > **与 DDL 的对应**：`game_period` **不设** `channel_id`；`bet_order.channel_id` 为下单时用户归属快照，不改变「全场一局」语义。详见 §11.5。
 
@@ -42,7 +42,7 @@
 | 阶段 | 目标 | 主要内容 |
 |------|------|----------|
 | **P0** | 数据地基 | 新建 `channel` 并适配 `user`、`admin`、`admin_group`；建立账本类最小表集（金额精度统一） |
-| **P1** | 游戏核心 | 期号、注单、开奖、系统配置；Redis 状态机 + MQ 异步落库 |
+| **P1** | 游戏核心 | 期号、注单、开奖、系统配置；**Redis 热点读缓存（user / game_config / game_record）已落地**；可选 MQ 异步落库等后续增强 |
 | **P2** | 资金与风控 | 充提订单、流水账、提现审核、Jackpot / 大额拦截 |
 | **P3** | 代理与结算 | 流水占比分桶、级差、联营占成与负结转（表结构 + 跑批骨架） |
 | **P4** | 运营与审计 | 公告（含 Pop-out）、站内信、后台 RBAC 与操作审计 |
@@ -70,7 +70,7 @@
 | 高 | **渠道**、**游戏用户**、**角色组 / 管理员**（含渠道与邀请码相关字段） | 搭好「谁管哪条线、玩家归谁」 |
 | 高 | **用户管理 / 用户钱包流水** | 覆盖玩家主数据与账务对账 |
 | 高 | **游戏对局 / 压注订单** | 核心玩法与对账入口 |
-| 中 | **游戏配置 / 36字花字典** | 运营参数与字典维护 |
+| 中 | **游戏配置**（侧栏目录名）：**常规配置**（`game_config` 通用 KV，列表默认每页 50 条，不含 `deposit_tier` / `streak_win_reward` / `zi_hua_36_dictionary`）、**连胜奖励**、**充值档位**、**36字花字典** | 运营参数与字典维护 |
 | 中 | **充值订单 / 提现订单** | 充提流程管理与审核 |
 | 低 | **公告 / 站内信**、**代理结算** 等 | 属 **P3～P4**，核心跑通后再接 |
 
@@ -98,8 +98,18 @@
    - `order/betOrder`、`order/depositOrder`、`order/withdrawOrder`
    - `game/period`
    - `config/gameConfig`、`config/ziHuaDictionary`
-   - `record/userWalletRecord`
+   - `user/userWalletRecord`
 5. 清理收口：删除迁移过程中的冗余权限别名规则，仅保留最终模块节点（`user/order/game/config/record`）。
+6. 运营模块：`operation_notice`、`user_notice_read` 表与后台目录 **`operation`**（子菜单 `operation/operationNotice`、`operation/userNoticeRead`）。
+
+### 2.7 `game_config` 连胜与派彩（2026-04 起）
+
+| `config_key` | 说明 |
+|--------------|------|
+| `streak_win_reward` | JSON：`rows[]` 每项含 `streak`（1～10）、`odds_factor`（与 33 相乘为整段赔率）、`is_jackpot`（是否大奖）。派彩公式：`total_amount × odds_factor × 33`。默认第 10 档 `is_jackpot=true`。 |
+| `deposit_tier` | 仍由「充值档位」独立菜单维护，**不出现在**「常规配置」列表。 |
+
+开奖结算后更新 **`user.current_streak`**：本期有中奖注单则 `min(streak_at_bet+1, 10)`，否则 **连胜归 0**（无档位配置）。若命中大奖档，向玩家 **私有频道** `private-user-{uuid}` 与 **公共频道** `public-game-period` 推送事件 **`jackpot.hit`**（负载含 `period_no`、`user_id`、`total_win_amount`、`result_number` 等）。
 
 ---
 
@@ -113,7 +123,7 @@
 
 | 方向 | 说明 |
 |------|------|
-| 顶级代理归属 | `top_admin_id`：关联到顶级代理管理员 `admin.id` |
+| 渠道负责人 | `admin_id`：渠道对应一名管理员（`admin.id`），权限与数据范围以该账号为准；不再单独维护 `top_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` |
 | 邀请码参数 | 渠道不生成邀请码，邀请码由管理员自动生成并用于注册归属 |
@@ -137,7 +147,7 @@
 |------|------|
 | 金额精度 | `coin` 调整为 **`decimal(18,4)`**（与规格书一致，禁止用浮点存币） |
 | 注册与归属 | `invite_code` 或注册时解析 URL 与 `channel.code` 绑定 |
-| 提现门槛 | `total_deposit_coin`、`total_valid_bet_coin` 或等价的「待完成流水」字段（全项目统一一种口径） |
+| 提现门槛 | `user.total_deposit_coin` / `user.total_withdraw_coin` / `user.bet_flow_coin` + `game_config.withdraw_bet_flow_ratio`（净充值打码口径，全项目统一） |
 | 风控 | 禁止登录 / 禁止下注 / 禁止提现等，可用位标记或独立布尔字段 |
 | 连胜持久化 | 可选 `current_streak`、`last_bet_period_id`；高频仍以 **Redis** 为准，DB 作兜底同步 |
 | 邮箱 | PRD 支持手机或邮箱注册时，可增加可空字段 `email`（是否唯一索引按产品定） |
@@ -152,16 +162,14 @@
 | 渠道归属 | `channel_id` 表示该子代理属于哪个顶级渠道 |
 | 邀请管理 | `invite_code` 自动生成且全局唯一，用于发展玩家并做归属绑定 |
 | 角色标识 | `agent_role`（如 `agent_admin` / `sub_agent` / `staff`） |
-| 分红设置 | `commission_rate`（百分比，0-100，最多两位小数）；管理员角色组改为单选，同一角色组下管理员分红比例总和不超过100% |
+| 分红设置 | 不再使用 `admin` / `admin_group` 分红字段；统一改为渠道维度结算后按 `channel_admin_share` 二次分配 |
 | 开奖权限 | 不在数据层开放给渠道/子代理；开奖权限仅由超管 RBAC 控制 |
 
-### 5.1 角色组与管理员分红计算口径
+### 5.1 分红计算口径（现行）
 
-- 角色组分红：`当前角色分红 = 渠道设置获取分红 × (1 - 上级角色分红比例) × 当前角色分红比例`
-- 管理员分红：`当前管理员分红 = 当前角色分红 × 当前管理员分红比例`
-- 校验约束：
-  - 同一父级下角色组分红比例总和 `<= 100%`
-  - 同一角色组下管理员分红比例总和 `<= 100%`
+- 渠道分红：先按 `channel.agent_mode` 计算渠道总佣金
+- 管理员分红：再按 `channel_admin_share.share_rate` 对渠道总佣金进行二次分配
+- 角色组仅用于权限与数据范围，不再参与金额拆分
 
 ---
 
@@ -245,7 +253,8 @@
    - `order/depositOrder`、`order/withdrawOrder`、`order/betOrder`
    - `game/period`
    - `config/gameConfig`、`config/ziHuaDictionary`
-   - `record/userWalletRecord`
+   - `user/userWalletRecord`
+   - `operation/operationNotice`、`operation/userNoticeRead`
 4. 验证 `config/ziHuaDictionary` 的读取与保存权限均命中，且仅授权角色可操作。
 
 ### 8.2 业务规则（对照 PRD / 业务流程）
@@ -269,7 +278,10 @@
 
 ### 8.4 非功能
 
-- Redis：当前期注单池、倒计时、近 30 期开奖缓存。  
+- **Redis（已落地）**  
+  - **热点数据缓存**：`app/common/service/GameHotDataRedis.php`，依赖 `webman/redis` 与 `config/redis.php`。缓存对象：`user` 行（鉴权与余额类读路径）、`game_config` 行（按 `config_key`）、`game_record`（活跃局、按 id、最新一条）。写库后通过模型事件或服务内 **`gameRecordForget` / `gameConfigForget` / `userForget`** 失效；环境变量 `GAME_HOT_CACHE_*` 控制开关与 TTL（见 `.env-example`）。  
+  - **规划/增强**（未替代上述）：当前期注单池、近 30 期开奖列表缓存、纯 Redis 状态机等，可按压测需求迭代。  
+- **与 `CACHE_DRIVER`**：`config/cache.php` 默认 `file` 仅影响 **系统配置表 `config`**（如 `get_sys_config`），**不**控制 `GameHotDataRedis`。  
 - MQ：派彩异步消费**幂等**（如 `period_id` + 用户 + 业务单号）。  
 - API：下注、提现等核心接口**限流**生效。
 
@@ -279,7 +291,7 @@
 
 1. **子代理数据源**：子代理统一在 `admin`，避免在 `channel` 重复建树造成双主数据源。  
 2. **现有 `profit_amount`（decimal(5,2)）**：与游戏币 **18,4** 精度不一致，演进时改为 `decimal(18,4)` 或迁移至结算域，避免对账误差。  
-3. 文档要求 **AI 算票在 Redis 内完成**，主库避免结算期同步锁表；账本与注单以异步一致性与幂等为准。  
+3. 文档要求 **AI 算票在 Redis 内完成**（演进目标），当前实现以 **MySQL `game_record` + 服务层缓存** 为主；主库仍应避免结算期大范围锁表；账本与注单以事务与幂等为准。  
 4. **全局对局一致性**：任何需求（多租户展示、渠道后台）均不得引入「按渠道独立期号/独立开奖」；若出现产品歧义，以 **§1.1** 为准，避免公平性质疑与客诉。
 
 ---
@@ -334,6 +346,9 @@
 | 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 菜单规则，文档口径与线上结构一致 |
+| V1.11 | 2026-04-16 | 落地运营公告：`operation_notice`、`user_notice_read` 表与菜单目录 `operation`（运营公告、用户阅读记录） |
+| 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` 表文件缓存）区分说明 |
 
 ---
 
@@ -353,8 +368,7 @@
 | `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` | 创建人、渠道绑定的角色组 |
+| `admin_id` / `admin_group_id` | 渠道负责人（管理员）、渠道绑定的角色组 |
 | `status` / `remark` / `create_time` / `update_time` | 状态、备注、时间戳 |
 
 ### 11.2 `user`（C 端玩家）
@@ -364,9 +378,10 @@
 | `coin` | 当前游戏币余额，**decimal(18,4)**，更新须条件更新防负余额 |
 | `channel_id` | 归属渠道；历史 `game_channel_id` 若仍存在，迁移期注意双写/对照 |
 | `register_invite_code` | 注册时邀请码快照，用于审计与归属 |
-| `total_deposit_coin` / `total_valid_bet_coin` | 累计充值入账、累计有效投注；提现流水倍数校验用 |
+| `total_deposit_coin` / `total_withdraw_coin` | 累计充值入账、累计提现出账（提现受理时累加）；与「净充值」口径配合校验提现门槛 |
+| `bet_flow_coin` | 打码量/流水（历史名 `total_valid_bet_coin`，2026-04-18 迁移重命名）；开奖结算成功时按注单 `total_amount` 1:1 累加，提现门槛 `bet_flow_coin >= (total_deposit_coin - total_withdraw_coin) × withdraw_bet_flow_ratio` |
 | `risk_flags` | 风控位（如禁止登录/下注/提现，按位定义） |
-| `current_streak` / `last_bet_period_no` | 连胜与期号兜底；高频仍以 Redis 为准 |
+| `current_streak` / `last_bet_period_no` | 连胜与期号兜底；**读路径**可通过 **`GameHotDataRedis` 缓存 `user` 行** 降低压力，**写路径**仍以下注/结算后落库为准并主动失效缓存 |
 | `admin_id` | 归属子代理管理员 |
 | 其余 | 账号、头像、状态、时间戳等见 DDL |
 
@@ -379,7 +394,7 @@
 | `admin.invite_code` | 子代理邀请码，注册归属 |
 | `admin.agent_role` | 角色类型（均无开奖权） |
 | `admin_group.channel_id` | 角色组归属渠道；`NULL` 可为系统级（仅超管） |
-| `admin_group.commission_rate` | 角色组分红比例（百分比） |
+| `channel_admin_share.share_rate` | 渠道内管理员分配比例（百分比，启用项合计=100） |
 
 ### 11.4 `game_config`（动态参数）
 
@@ -394,7 +409,7 @@
 | 表 | 要点 |
 |----|------|
 | `game_period` | **全平台唯一**期号：`period_no` 全局唯一；`status` 状态机；开奖结果与作废原因。**无 `channel_id` 字段**：对局不按渠道拆分。 |
-| `bet_order` | 注单关联**全局** `period_id`；`channel_id`（若有）为**用户/归属快照**，便于分润与查询，**不表示**独立牌桌或独立开奖。`idempotency_key` 幂等；金额 **18,4**；`win_amount` / `jackpot_extra_amount` |
+| `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`（玩家钱包流水）