# 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 脚本初始化游戏和赔率配置：

```bash
# 方式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）：
```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` |

### 投注数据结构

```json
{
  "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调用示例

```javascript
// 手动开奖
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            // 自动随机
  })
});
```

### 结算逻辑

```php
// 中奖判断示例（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（不在大厅显示）

**解决**：
```sql
UPDATE games SET status=1, featured=1 WHERE code='xocdia';
```

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

**原因**：
- `game_odds` 表缺少赔率配置

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

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

**原因**：
- `result` 字段不是有效的 JSON 数组

**解决**：
```sql
-- 检查 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. 检查期号状态：
   ```sql
   SELECT id, period_number, status FROM periods WHERE id=XXX;
   ```
3. 手动修复状态：
   ```sql
   UPDATE periods SET status='drawn' WHERE id=XXX;
   ```

---

## 📊 性能优化建议

### 1. 赔率缓存

当前实现已使用静态缓存，避免重复查询：
```php
static $oddsCache = [];
```

### 2. 期号索引

确保数据库有以下索引：
```sql
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. 定时清理

建议每月清理已结算的旧期号和投注记录：
```sql
-- 保留最近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