Initial commit: 投注游戏平台初始化

2026-02-25 01:26:58 +08:00
commit 77ca2cc8b3
275 changed files with 237479 additions and 0 deletions
@@ -0,0 +1,385 @@
+# Xóc Đĩa 游戏集成完成报告
+
+**日期**: 2026-01-08
+**集成方式**: 方案 A（扩展 periods 表字段）
+**状态**: ✅ 代码集成已完成，待数据库初始化
+
+---
+
+## 一、集成完成清单
+
+### ✅ 数据库层
+- [x] 创建数据库迁移脚本 `Db/xocdia_integration.sql`
+  - 扩展 periods 表（添加 coin1-4, red_count 字段）
+  - 插入 Xóc Đĩa 游戏记录
+  - 配置 6 种投注类型赔率
+
+### ✅ 控制器层
+- [x] `App/Controllers/Admin/PeriodController.php` - 扩展支持 Xóc Đĩa
+  - 新增 `drawXocdia()` 方法（开奖）
+  - 新增 `checkWinXocdia()` 方法（中奖判断）
+  - 修改 `draw()` 方法（游戏类型分发）
+  - 修改 `checkWin()` 方法（游戏类型分发）
+
+- [x] `App/Controllers/Web/XocdiaController.php` - 适配使用现有表
+  - 修改 `index()` - 查询 games 表
+  - 修改 `room()` - 使用 periods 表
+  - 修改 `placeBet()` - 使用 bets 和 transactions 表
+  - 修改 API 方法 - 使用 periods 表字段
+
+### ✅ 路由层
+- [x] 清理 `routes.php`
+  - 删除独立后台路由 (`/admin/xocdia/*`)
+  - 保留前台路由 (`/xocdia/*`)
+
+### ✅ 视图层
+- [x] 删除独立后台视图
+  - 删除 `App/Views/Admin/xocdia_rooms.php`
+  - 删除 `App/Views/Admin/xocdia_periods.php`
+  - 删除后台菜单中的独立菜单项
+
+- [x] 保留前台视图
+  - `App/Views/Web/xocdia_rooms.php` - 游戏大厅
+  - `App/Views/Web/xocdia_room.php` - 游戏房间
+
+### ✅ 文档层
+- [x] 创建 `XOCDIA_INTEGRATION_GUIDE.md`
+  - 数据库变更说明
+  - 代码变更说明
+  - 管理流程文档
+  - 前台访问流程
+  - 常见问题 FAQ
+
+### ✅ 清理工作
+- [x] 删除 `App/Controllers/Admin/XocdiaRoomController.php`
+- [x] 删除 `App/Controllers/Admin/XocdiaPeriodController.php`
+- [x] 删除 `Db/xocdia_schema.sql`（旧版独立 schema）
+
+---
+
+## 二、验证结果
+
+### 文件存在性检查
+
+```bash
+✅ Db/xocdia_integration.sql (2292 字节)
+✅ App/Controllers/Admin/PeriodController.php (973 行，包含 drawXocdia 和 checkWinXocdia 方法)
+✅ App/Controllers/Web/XocdiaController.php (462 行)
+✅ XOCDIA_INTEGRATION_GUIDE.md (388 行)
+```
+
+### 独立后台组件清理检查
+
+```bash
+✅ 无独立后台控制器 (App/Controllers/Admin/Xocdia*.php)
+✅ 无独立后台视图 (App/Views/Admin/xocdia_*.php)
+✅ 无旧版 schema (Db/xocdia_schema.sql)
+```
+
+### 代码集成检查
+
+```bash
+✅ PeriodController.php 包含 drawXocdia 方法 (第 304 行)
+✅ PeriodController.php 包含 checkWinXocdia 方法 (第 900 行)
+✅ PeriodController.php draw() 方法调用 drawXocdia (第 226 行)
+✅ PeriodController.php checkWin() 方法调用 checkWinXocdia (第 752 行)
+```
+
+---
+
+## 三、下一步操作指引
+
+### 步骤 1：执行数据库迁移 ⚠️ 必须执行
+
+```bash
+# 备份数据库（重要！）
+mysqldump -u tm68 -p tm68 > backup_$(date +%Y%m%d_%H%M%S).sql
+
+# 执行迁移脚本
+mysql -u tm68 -p tm68 < Db/xocdia_integration.sql
+```
+
+**预期输出**：
+```
+✅ Xóc Đĩa 游戏集成完成！
+game_id: [新游戏 ID]
+game_code: xocdia
+```
+
+### 步骤 2：验证数据库变更
+
+```sql
+-- 检查 periods 表新字段
+SHOW COLUMNS FROM periods LIKE 'coin%';
+
+-- 预期返回 5 行：coin1, coin2, coin3, coin4, red_count
+
+-- 检查 Xóc Đĩa 游戏
+SELECT * FROM games WHERE type = 'xocdia';
+
+-- 预期返回 1 行游戏记录
+
+-- 检查赔率配置
+SELECT g.name, go.type, go.odds
+FROM game_odds go
+JOIN games g ON go.game_id = g.id
+WHERE g.code = 'xocdia';
+
+-- 预期返回 6 行赔率记录
+```
+
+### 步骤 3：后台管理测试
+
+#### 3.1 创建 Xóc Đĩa 期号
+
+1. 访问 `/admin/periods`
+2. 选择游戏："Xóc Đĩa"
+3. 点击"开始新期号"
+4. 验证期号格式：`G{GameID}{YYYYMMDD}{NNNN}`
+
+#### 3.2 开奖测试
+
+1. 在期号列表找到"待开奖"的 Xóc Đĩa 期号
+2. 点击"开奖"
+3. 选择开奖方式：
+   - **手动开奖**：选择 4 个硬币的颜色（红/白）
+   - **自动开奖**：系统随机生成
+4. 验证结果字段：
+   - `coin1`, `coin2`, `coin3`, `coin4` = 0 或 1
+   - `red_count` = 0-4
+   - `result` = "even" 或 "odd"
+
+#### 3.3 结算测试
+
+1. 确认开奖结果无误
+2. 点击"结算"
+3. 验证：
+   - 投注记录状态更新（win/lose）
+   - 赢家余额增加
+   - 交易流水记录正确
+   - 期号状态变为 "settled"
+
+### 步骤 4：前台用户测试
+
+#### 4.1 游戏大厅
+
+1. 访问 `/xocdia`
+2. 验证：
+   - 显示 Xóc Đĩa 游戏卡片
+   - 显示当前期号
+   - 显示赔率信息
+
+#### 4.2 游戏房间
+
+1. 点击"进入房间"
+2. 验证：
+   - 直播流播放（如已配置）
+   - 当前期号显示
+   - 6 种投注类型可选
+   - 赔率显示正确
+
+#### 4.3 投注流程
+
+1. 选择投注类型（双/单/4红/4白/3红1白/1红3白）
+2. 输入金额（10 - 10000）
+3. 点击"投注"
+4. 验证：
+   - 余额实时扣除
+   - 投注记录显示
+   - 返回成功消息
+
+#### 4.4 开奖结果
+
+1. 等待开奖
+2. 验证：
+   - 显示 4 个硬币结果（红色/白色）
+   - 显示红色硬币数量
+   - 显示单双结果
+   - 中奖投注显示奖金
+
+### 步骤 5：边界情况测试
+
+#### 测试用例
+- [ ] 期号关闭后投注（应拒绝）
+- [ ] 余额不足投注（应拒绝）
+- [ ] 赔率配置缺失（应报错）
+- [ ] 并发投注（同一用户多次下注）
+- [ ] 骰子游戏和 Xóc Đĩa 共存（互不干扰）
+
+---
+
+## 四、集成架构说明
+
+### 数据库表共享策略
+
+| 表名 | 骰子游戏使用字段 | Xóc Đĩa 使用字段 | 共享字段 |
+|------|---------------|---------------|---------|
+| `games` | - | - | id, name, code, type, status |
+| `periods` | dice1, dice2, dice3, total | coin1, coin2, coin3, coin4, red_count | id, game_id, period_number, status, result |
+| `bets` | - | - | 全部字段（通用） |
+| `game_odds` | - | - | 全部字段（通用） |
+| `transactions` | - | - | 全部字段（通用） |
+
+### 游戏类型识别
+
+```php
+// 通过 games.type 字段区分
+$game = $db->get('games', ['type'], ['id' => $gameId]);
+
+if ($game['type'] === 'xocdia') {
+    // 使用 coin1-4 字段
+    $this->drawXocdia($db, $id, $data);
+} else {
+    // 使用 dice1-3 字段
+    $this->drawDice($db, $id, $data);
+}
+```
+
+### 中奖判断逻辑
+
+#### 骰子游戏
+```php
+private function checkWinDice($bet, $period, $oddsConfig) {
+    $total = $period['total']; // dice1 + dice2 + dice3
+    // 根据 bet_type 判断...
+}
+```
+
+#### Xóc Đĩa
+```php
+private function checkWinXocdia($bet, $period, $oddsConfig) {
+    $redCount = $period['red_count']; // coin1 + coin2 + coin3 + coin4
+
+    switch ($bet['bet_type']) {
+        case 'even':  // 双
+            return ($redCount % 2 == 0);
+        case 'four_red':  // 4 红
+            return ($redCount == 4);
+        case 'three_red':  // 3 红 1 白
+            return ($redCount == 3);
+        // ...
+    }
+}
+```
+
+---
+
+## 五、Xóc Đĩa 投注类型说明
+
+| 投注类型 | bet_type | 中奖条件 | 赔率 | 示例 |
+|---------|---------|---------|------|------|
+| 双（Chẵn） | even | 红色硬币数量为 0, 2, 4 | 1:0.97 | 投 100，赢 97 |
+| 单（Lẻ） | odd | 红色硬币数量为 1, 3 | 1:0.97 | 投 100，赢 97 |
+| 4 红 | four_red | 4 个红色硬币 | 1:8.00 | 投 100，赢 800 |
+| 4 白 | four_white | 0 个红色硬币（即 4 白） | 1:8.00 | 投 100，赢 800 |
+| 3 红 1 白 | three_red | 3 个红色硬币 | 1:1.90 | 投 100，赢 190 |
+| 1 红 3 白 | three_white | 1 个红色硬币 | 1:1.90 | 投 100，赢 190 |
+
+---
+
+## 六、常见问题解答
+
+### Q1: 骰子游戏会受影响吗？
+**答**：不会。两种游戏使用不同的字段，通过 `games.type` 区分，互不干扰。
+
+### Q2: 如何修改赔率？
+**答**：
+1. 访问 `/admin/games`
+2. 找到 Xóc Đĩa 游戏，点击"配置赔率"
+3. 修改对应投注类型的赔率值
+4. 保存
+
+**注意**：修改赔率只影响新投注，已下注订单使用下注时的赔率（快照机制）。
+
+### Q3: 如何添加新的 Xóc Đĩa 游戏房间？
+**答**：
+1. 在 `/admin/games` 创建新游戏
+2. 游戏类型选择 `xocdia`
+3. 配置该游戏的赔率（可以与现有游戏不同）
+4. 前台 `/xocdia` 会自动显示所有 Xóc Đĩa 游戏
+
+### Q4: 如何配置直播流？
+**答**：
+1. 在 `/admin/games` 编辑 Xóc Đĩa 游戏
+2. 填写 `stream_url` 字段（支持 HLS/FLV/MPEGTS）
+3. 保存后，前台游戏房间会自动播放
+
+---
+
+## 七、技术支持
+
+### 日志位置
+- 错误日志：`Storage/log/error.log`
+- 数据库查询日志：Medoo 不记录日志，可通过 `$db->medoo->last()` 查看最后执行的 SQL
+
+### 调试模式
+在 `index.php` 开启调试：
+```php
+error_reporting(E_ALL);
+ini_set('display_errors', 1);
+```
+
+### 数据库工具
+```bash
+# 查看最后执行的 SQL
+$sql = $db->medoo->last();
+echo $sql;
+
+# 查看错误信息
+$error = $db->medoo->error();
+print_r($error);
+```
+
+---
+
+## 八、回滚方案
+
+如果需要回滚集成：
+
+```sql
+-- 删除 Xóc Đĩa 游戏记录
+DELETE FROM games WHERE code = 'xocdia';
+
+-- 删除赔率配置
+DELETE FROM game_odds WHERE game_id = (SELECT id FROM games WHERE code = 'xocdia');
+
+-- 删除扩展字段（可选，不影响骰子游戏）
+ALTER TABLE periods
+DROP COLUMN coin1,
+DROP COLUMN coin2,
+DROP COLUMN coin3,
+DROP COLUMN coin4,
+DROP COLUMN red_count;
+```
+
+---
+
+## 九、性能优化建议
+
+### 数据库索引
+```sql
+-- 为常用查询添加索引
+CREATE INDEX idx_periods_game_status ON periods(game_id, status);
+CREATE INDEX idx_bets_period_user ON bets(period_id, user_id);
+```
+
+### 缓存策略
+- 游戏列表缓存（Redis）
+- 赔率配置缓存（Redis）
+- 当前期号缓存（Redis，60秒过期）
+
+### 前台优化
+- 使用 WebSocket 推送开奖结果（避免轮询）
+- 投注记录分页加载
+- 开奖历史延迟加载
+
+---
+
+**集成完成日期**: 2026-01-08
+**文档版本**: 1.0.0
+**负责人**: Claude AI
+**状态**: ✅ 代码集成完成，待数据库初始化和测试
+
+---
+
+**下一步**: 执行数据库迁移脚本，按照"步骤 1"开始验证