pk10/Docs/XOCDIA_INTEGRATION_GUIDE.md

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

📋 概述

本文档描述如何在 TM68 平台上使用新集成的 Xóc Đĩa（色碟）游戏功能。

🎯 游戏规则

基本机制

• 使用 4 枚双色硬币（红色/白色）
• 荷官摇动后开盖展示结果
• 玩家根据硬币颜色组合进行投注

投注类型

投注类型	说明	中奖条件	默认赔率
CHẴN (双/偶)	双数组合	4红 或 4白 或 2红2白	1:0.96
LẺ (单/奇)	单数组合	3红1白 或 3白1红	1:0.96
4 ĐỎ	4个红色	全部红色	1:10
4 TRẮNG	4个白色	全部白色	1:10
3 ĐỎ 1 TRẮNG	3红1白	3个红色1个白色	1:3.5
3 TRẮNG 1 ĐỎ	3白1红	3个白色1个红色	1:3.5

---

🚀 部署步骤

1. 初始化数据库

执行 SQL 脚本初始化游戏和赔率配置：

# 方式1：通过 phpMyAdmin 导入
# 导入文件：Db/xocdia_setup.sql

# 方式2：通过命令行执行
mysql -u用户名 -p数据库名 < Db/xocdia_setup.sql

脚本内容：

• 在 games 表添加 Xóc Đĩa 游戏记录（code='xocdia', type='xocdia'）
• 在 game_odds 表配置6种投注类型的赔率

2. 配置游戏信息

登录后台管理 → 游戏管理 → 编辑 Xóc Đĩa 游戏：

1. 基本信息

   • 游戏名称：Xóc Đĩa
   • 游戏标识：xocdia（自动生成）
   • 游戏类型：xocdia（重要！）
   • 状态：启用

2. 直播配置

   • 直播流地址：填写 HLS/FLV 流地址
   • 示例：https://your-cdn.com/live/xocdia.m3u8

3. 展示设置

   • 游戏图片：上传缩略图（推荐尺寸 400x300）
   • 在游戏大厅显示：是
   • 排序权重：100（数字越大越靠前）

3. 配置赔率（可选）

如需调整赔率，登录后台管理 → 游戏管理 → 赔率配置：

类型 (type)	目标 (target)	赔率 (odds)	说明
chan	all	0.96	双(偶)的赔率
le	all	0.96	单(奇)的赔率
exact	4red	10.0	4红的赔率
exact	4white	10.0	4白的赔率
exact	3red1white	3.5	3红1白的赔率
exact	3white1red	3.5	3白1红的赔率

---

🎮 游戏流程

前台用户流程

1. 进入游戏

   • 访问首页 → 点击 Xóc Đĩa 游戏卡片
   • 或直接访问：http://yourdomain.com/live?game_id=X（X为游戏ID）

2. 观看直播

   • 页面左侧自动播放直播视频
   • 显示当前期号和倒计时

3. 下注

   • 选择筹码金额（100K ~ 5M）
   • 点击投注区域（双/单 或 精确组合）
   • 可多次点击累加投注额
   • 点击"ĐẶT CƯỢC"确认，或"HỦY"取消

4. 等待开奖

   • 倒计时结束后封盘
   • 荷官开奖
   • 自动结算并更新余额

后台管理流程

开始新一轮

1. 登录后台管理 → 期号管理
2. 点击"开始下注"按钮
3. 系统自动创建新期号（格式：G{GameID}{YYYYMMDD}{NNNN}）
4. 前台用户可以开始投注（60秒倒计时）

开奖

1. 倒计时结束或手动封盘
2. 点击"开奖"按钮
3. 选择开奖方式：
   • 手动输入：逐个选择4个硬币的颜色（red/white）
   • 自动随机：系统随机生成结果
4. 确认开奖

开奖结果存储格式（JSON）：

["red", "white", "red", "red"]  // 3红1白

结算

1. 点击"结算"按钮
2. 系统自动：
   • 遍历所有待结算投注
   • 根据开奖结果判断输赢
   • 中奖用户：返还本金 + 盈利
   • 未中奖：不退还本金
   • 记录资金流水
3. 期号状态变更为"已结算"
4. 点击"开始下注"启动下一轮

---

🔧 技术实现细节

数据库字段复用

为避免修改数据库结构，Xóc Đĩa 游戏复用了 periods 表的骰子游戏字段：

字段名	骰子游戏	Xóc Đĩa 游戏
result	"Xỉu/Tài"	JSON数组：["red","white",...]
dice1	骰子1点数	红色硬币数量
dice2	骰子2点数	白色硬币数量
dice3	骰子3点数	null
total	三骰总和	null

投注数据结构

{
  "bets": [
    {
      "type": "chan",           // 投注类型
      "value": "all",           // 投注目标
      "amount": 100000,         // 投注金额
      "odds": 0.96              // 赔率（从服务器获取）
    },
    {
      "type": "exact",
      "value": "4red",
      "amount": 500000,
      "odds": 10.0
    }
  ],
  "period_number": "G2202601080001",
  "game_id": 2
}

开奖API调用示例

// 手动开奖
fetch('/admin/periods/draw', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: 123,              // 期号ID
    auto: false,          // 手动模式
    coins: ['red', 'red', 'white', 'red']  // 4个硬币颜色
  })
});

// 自动开奖
fetch('/admin/periods/draw', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: 123,
    auto: true            // 自动随机
  })
});

结算逻辑

// 中奖判断示例（checkWin 方法）
$coins = json_decode($period['result'], true);  // ["red", "red", "white", "red"]
$redCount = count(array_filter($coins, fn($c) => $c === 'red'));  // 3

// 判断 chan（双）
if (in_array($redCount, [0, 2, 4])) {
    // 中奖：0红4白, 2红2白, 4红0白
    $winAmount = $betAmount * $odds;
}

// 判断 exact（精确组合）
if ($betValue === '3red1white' && $redCount === 3) {
    // 中奖：3红1白
    $winAmount = $betAmount * $odds;
}

---

🐛 故障排查

问题1：前台看不到 Xóc Đĩa 游戏

原因：

• 游戏未启用（status=0）
• featured=0（不在大厅显示）

解决：

UPDATE games SET status=1, featured=1 WHERE code='xocdia';

问题2：投注时提示"赔率无效"

原因：

• game_odds 表缺少赔率配置

解决：

# 重新执行初始化脚本
mysql -u用户名 -p数据库名 < Db/xocdia_setup.sql

问题3：开奖后前台显示错误

原因：

• result 字段不是有效的 JSON 数组

解决：

-- 检查 result 字段格式
SELECT id, result FROM periods WHERE game_id=2 LIMIT 5;

-- 应该是：["red","white","red","red"] 格式
-- 如果不是，手动修正
UPDATE periods SET result='["red","red","white","white"]' WHERE id=XXX;

问题4：结算失败

原因：

• 期号状态不是 'drawn'
• 事务回滚

解决：

1. 检查日志：Storage/log/error.log
2. 检查期号状态：

   SELECT id, period_number, status FROM periods WHERE id=XXX;
   

3. 手动修复状态：

   UPDATE periods SET status='drawn' WHERE id=XXX;
   

---

📊 性能优化建议

1. 赔率缓存

当前实现已使用静态缓存，避免重复查询：

static $oddsCache = [];

2. 期号索引

确保数据库有以下索引：

CREATE INDEX idx_period_status ON periods(status);
CREATE INDEX idx_period_game ON periods(game_id, status);
CREATE INDEX idx_bet_period ON bets(period_id, status);

3. 定时清理

建议每月清理已结算的旧期号和投注记录：

-- 保留最近30天的记录
DELETE FROM periods WHERE status='settled' AND created_at < DATE_SUB(NOW(), INTERVAL 30 DAY);
DELETE FROM bets WHERE status IN ('win','lose') AND created_at < DATE_SUB(NOW(), INTERVAL 30 DAY);

---

📝 未来扩展

可能的功能增强

1. 统计数据

   • 历史开奖记录（路单）
   • 热门投注统计
   • 玩家胜率分析

2. 游戏变体

   • 支持自定义硬币图案
   • 支持更多投注类型（如：颜色顺序）

3. 自动化

   • 自动开奖（对接硬件或视频识别）
   • 自动封盘（基于倒计时）

---

✅ 集成检查清单

部署前请确认：

• SQL 脚本已执行，游戏和赔率已创建
• 后台游戏管理中 Xóc Đĩa 状态为"启用"
• 已配置直播流地址（或留空测试）
• 前台可以正常访问游戏页面
• 测试完整流程：创建期号 → 投注 → 开奖 → 结算
• 数据库备份已创建

---

📞 技术支持

如遇到问题，请检查：

1. Storage/log/error.log - PHP 错误日志
2. 浏览器开发者工具 Console - 前端错误
3. 数据库查询日志 - SQL 错误

相关文件：

• 数据库脚本：Db/xocdia_setup.sql
• 前端组件：App/Views/Web/components/xocdia-bet-panel.php
• 后端控制器：
  • App/Controllers/Web/HomeController.php (live方法)
  • App/Controllers/Web/BetController.php (placeBet方法)
  • App/Controllers/Admin/PeriodController.php (draw/settle方法)

---

最后更新: 2026-01-08 版本: 1.0.0