pk10/XOCDIA_INTEGRATION_GUIDE.md

Xóc Đĩa 游戏集成指南

概述

Xóc Đĩa 游戏已成功集成到现有的游戏管理系统中，复用了骰子游戏的核心架构（games, periods, bets, game_odds, transactions 表），无需创建独立的数据库表和后台管理界面。

---

数据库变更

1. 扩展 periods 表（方案 A）

在原有骰子字段（dice1, dice2, dice3）的基础上，新增了硬币字段：

ALTER TABLE `periods`
ADD COLUMN `coin1` TINYINT DEFAULT NULL COMMENT '硬币1（1=红，0=白）',
ADD COLUMN `coin2` TINYINT DEFAULT NULL COMMENT '硬币2（1=红，0=白）',
ADD COLUMN `coin3` TINYINT DEFAULT NULL COMMENT '硬币3（1=红，0=白）',
ADD COLUMN `coin4` TINYINT DEFAULT NULL COMMENT '硬币4（1=红，0=白）',
ADD COLUMN `red_count` TINYINT DEFAULT NULL COMMENT '红色硬币数量（0-4）';

设计说明：

• 骰子游戏使用：dice1, dice2, dice3, total, result
• Xóc Đĩa 使用：coin1, coin2, coin3, coin4, red_count, result
• 两种游戏可共存，不会相互干扰

2. 在 games 表中添加 Xóc Đĩa 游戏

INSERT INTO `games` (
    `name`, `code`, `type`, `tags`, `sort_order`, `status`, `featured`
) VALUES (
    'Xóc Đĩa',
    'xocdia',
    'xocdia',
    '越南传统,硬币游戏',
    10,
    1,
    1
);

3. 配置赔率（game_odds 表）

-- Xóc Đĩa 投注类型及赔率：
INSERT INTO `game_odds` (`game_id`, `type`, `target`, `odds`) VALUES
(@xocdia_game_id, 'even', 'all', 0.97),      -- 双（偶数个红色）
(@xocdia_game_id, 'odd', 'all', 0.97),       -- 单（奇数个红色）
(@xocdia_game_id, 'four_red', 'all', 8.00),  -- 4 红
(@xocdia_game_id, 'four_white', 'all', 8.00),-- 4 白
(@xocdia_game_id, 'three_red', 'all', 1.90), -- 3 红 1 白
(@xocdia_game_id, 'three_white', 'all', 1.90);-- 1 红 3 白

---

代码变更

1. PeriodController 扩展

文件: App/Controllers/Admin/PeriodController.php

新增方法：

• drawXocdia($db, $id, $data) - 处理 Xóc Đĩa 开奖（4 个硬币）
• checkWinXocdia($bet, $period, $oddsConfig) - 判断 Xóc Đĩa 中奖

修改方法：

• draw() - 根据游戏类型（games.type）分发到 drawDice() 或 drawXocdia()
• checkWin() - 根据游戏类型分发到 checkWinDice() 或 checkWinXocdia()

开奖逻辑：

if ($gameType === 'xocdia') {
    // 生成 4 个硬币结果（0=白，1=红）
    $coin1 = rand(0, 1);
    $coin2 = rand(0, 1);
    $coin3 = rand(0, 1);
    $coin4 = rand(0, 1);
    $redCount = $coin1 + $coin2 + $coin3 + $coin4;
    $result = ($redCount % 2 == 0) ? 'even' : 'odd';
}

中奖判断：

switch ($betType) {
    case 'even':       // 双
        if ($redCount % 2 == 0) $isWin = true;
        break;
    case 'four_red':   // 4 红
        if ($redCount == 4) $isWin = true;
        break;
    case 'three_red':  // 3 红 1 白
        if ($redCount == 3) $isWin = true;
        break;
    // ...
}

2. 前台控制器

文件: App/Controllers/Web/XocdiaController.php

功能：

• index() - 显示所有 Xóc Đĩa 类型的游戏列表
• room() - 游戏房间界面
• placeBet() - 下注（使用 bets 表）
• getCurrentPeriod() - 获取当前期号
• getHistory() - 获取开奖历史
• getMyBets() - 获取用户投注记录

数据访问：

• 从 games 表读取游戏配置（type='xocdia'）
• 从 game_odds 表读取赔率
• 从 periods 表读取期号
• 从 bets 表记录投注

3. 路由配置

文件: routes.php

保留前台路由：

// Xóc Đĩa 前台路由
['GET', '/xocdia', '\App\Controllers\Web\XocdiaController@index'],
['GET', '/xocdia/room', '\App\Controllers\Web\XocdiaController@room'],
['GET', '/api/xocdia/periods/current', '\App\Controllers\Web\XocdiaController@getCurrentPeriod'],
['POST', '/api/xocdia/bet', '\App\Controllers\Web\XocdiaController@placeBet'],
['GET', '/api/xocdia/periods/history', '\App\Controllers\Web\XocdiaController@getHistory'],
['GET', '/api/xocdia/my-bets', '\App\Controllers\Web\XocdiaController@getMyBets'],

删除后台路由：

• 不再需要独立的 /admin/xocdia/* 路由
• 使用现有的 /admin/games, /admin/periods 管理

---

管理流程

1. 创建 Xóc Đĩa 游戏

后台路径: /admin/games

1. 点击"添加游戏"
2. 填写信息：
   • 游戏名称：Xóc Đĩa
   • 游戏标识：xocdia（自动生成）
   • 游戏类型：xocdia
   • 直播流地址：（可选）
3. 点击"保存"

2. 配置赔率

后台路径: /admin/games → 点击游戏 → "配置赔率"

配置以下投注类型：

• even: 双（0.97）
• odd: 单（0.97）
• four_red: 4 红（8.00）
• four_white: 4 白（8.00）
• three_red: 3 红 1 白（1.90）
• three_white: 1 红 3 白（1.90）

3. 期号管理

后台路径: /admin/periods

启动新期号

1. 选择游戏：Xóc Đĩa
2. 点击"开始下注"
3. 系统自动生成期号（格式：G{GameID}{YYYYMMDD}{NNNN}）

开奖

1. 在期号列表中找到"待开奖"的期号
2. 点击"开奖"
3. 选择 4 个硬币的结果：
   • 手动选择：每个硬币选择"红"或"白"
   • 自动开奖：系统随机生成 4 个硬币结果
4. 系统自动计算红色硬币数量和单双结果

结算

1. 确认开奖结果无误
2. 点击"结算"
3. 系统自动：
   • 查询该期所有投注
   • 判断输赢
   • 更新用户余额（赢的情况）
   • 记录交易流水
   • 更新投注状态（win/lose）

---

前台访问

用户访问流程

1. 游戏大厅：访问 /xocdia

   • 显示所有可用的 Xóc Đĩa 游戏
   • 显示当前期号、赔率、限红

2. 进入房间：点击"进入房间"

   • URL：/xocdia/room?room_id={game_id}
   • 实时显示：当前期号、倒计时、开奖结果
   • 投注区域：6 种投注类型

3. 下注：

   • 选择投注类型（双/单/4红/4白/3红1白/1红3白）
   • 输入金额（10 - 10000）
   • 点击"投注"

4. 查看结果：

   • 开奖历史：最近 5 期结果
   • 我的投注：当前期号的投注记录

---

数据库安装

执行 SQL 脚本

mysql -u 用户名 -p 数据库名 < Db/xocdia_integration.sql

脚本内容：

1. 扩展 periods 表（添加硬币字段）
2. 插入 Xóc Đĩa 游戏记录
3. 配置赔率

验证安装：

-- 检查 periods 表字段
SHOW COLUMNS FROM periods LIKE 'coin%';

-- 检查游戏是否创建
SELECT * FROM games WHERE type = 'xocdia';

-- 检查赔率配置
SELECT g.name, go.type, go.odds
FROM game_odds go
JOIN games g ON go.game_id = g.id
WHERE g.code = 'xocdia';

---

投注类型说明

投注类型	bet_type	条件	赔率
双（Chẵn）	even	红色硬币数量为 0, 2, 4	1:0.97
单（Lẻ）	odd	红色硬币数量为 1, 3	1:0.97
4 红	four_red	4 个红色硬币	1:8.00
4 白	four_white	0 个红色硬币（即 4 白）	1:8.00
3 红 1 白	three_red	3 个红色硬币	1:1.90
1 红 3 白	three_white	1 个红色硬币	1:1.90

---

常见问题

Q1: 骰子游戏和 Xóc Đĩa 会冲突吗？

答：不会。两种游戏使用不同的字段：

• 骰子：dice1, dice2, dice3, total
• Xóc Đĩa：coin1, coin2, coin3, coin4, red_count

系统根据 games.type 字段区分游戏类型。

Q2: 如何在后台区分两种游戏的期号？

答：在期号列表中，通过"游戏名称"列区分：

• 骰子游戏：games.type = 'dice'
• Xóc Đĩa：games.type = 'xocdia'

开奖时，系统自动根据游戏类型调用不同的逻辑。

Q3: 如何修改赔率？

答：

1. 访问 /admin/games
2. 找到 Xóc Đĩa 游戏，点击"配置赔率"
3. 修改对应投注类型的赔率值
4. 点击"保存"

注意：修改赔率只影响新的投注，已下注的订单使用下注时的赔率。

Q4: 如何添加新的 Xóc Đĩa 游戏（不同房间）？

答：

1. 在 /admin/games 创建新游戏
2. 游戏类型选择 xocdia
3. 配置该游戏的赔率（可以与现有游戏不同）
4. 前台 /xocdia 会自动显示所有 Xóc Đĩa 游戏

---

技术细节

数据流

用户下注
  ↓
验证（余额、期号状态、赔率）
  ↓
开启事务
  ↓
扣除余额（users.balance）
  ↓
记录投注（bets 表）
  ↓
记录流水（transactions 表）
  ↓
提交事务

管理员开奖
  ↓
根据 game.type 判断游戏类型
  ↓
生成结果（4 个硬币或 3 个骰子）
  ↓
更新 periods 表（coin1-4 或 dice1-3）
  ↓
管理员结算
  ↓
查询该期所有投注
  ↓
遍历判断输赢（checkWinXocdia 或 checkWinDice）
  ↓
更新用户余额（赢的情况）
  ↓
记录交易流水
  ↓
更新投注状态

安全措施

1. 并发控制：使用数据库事务防止并发扣款
2. 权限检查：所有后台操作需要管理员权限
3. 参数化查询：使用 Medoo ORM 防止 SQL 注入
4. 余额验证：下注前检查用户余额
5. 期号状态验证：只能在"待开奖"期号下注

---

后续优化建议

1. 配置限红：当前限红（10 - 10000）硬编码在代码中，建议存储到 games 表或单独的配置表
2. 抽水功能：当前未实现抽水逻辑，建议添加抽水率配置
3. 倒计时功能：前台倒计时当前通过轮询实现，建议使用 WebSocket 推送
4. 实时监控：建议添加实时投注统计和风控监控页面
5. 历史查询：添加更丰富的历史查询筛选条件（日期、投注类型等）

---

相关文件清单

数据库

• Db/xocdia_integration.sql - 数据库集成脚本

控制器

• App/Controllers/Admin/PeriodController.php - 期号管理（已扩展支持 Xóc Đĩa）
• App/Controllers/Admin/GameController.php - 游戏管理（复用）
• App/Controllers/Web/XocdiaController.php - 前台控制器

视图

• App/Views/Web/xocdia_rooms.php - 游戏大厅
• App/Views/Web/xocdia_room.php - 游戏房间
• App/Views/Admin/games.php - 游戏管理（复用）
• App/Views/Admin/periods.php - 期号管理（复用）

路由

• routes.php - 路由配置（包含 Xóc Đĩa 前台路由）

---

最后更新: 2026-01-08 集成方式: 方案 A（扩展 periods 表字段） 状态: 已完成集成，待测试