pk10/XOCDIA_集成完成报告.md

# 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"开始验证