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

## 概述

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

---

## 数据库变更

### 1. 扩展 `periods` 表（方案 A）

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

```sql
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 游戏

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

### 3. 配置赔率（`game_odds` 表）

```sql
-- 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()`

**开奖逻辑**：
```php
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';
}
```

**中奖判断**：
```php
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`

**保留前台路由**：
```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 脚本

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

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

**验证安装**：
```sql
-- 检查 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 表字段）
**状态**: 已完成集成，待测试