pk10/XOCDIA_README.md

# Xóc Đĩa 游戏 - 后台管理系统

## 📋 项目概述

这是为 TM68 在线娱乐平台开发的 **Xóc Đĩa（色碟）** 游戏后台管理系统。

Xóc Đĩa 是越南传统赌博游戏，使用 4 枚双色硬币（红/白），玩家根据硬币颜色组合进行投注。

---

## 🎮 游戏规则

### 基本玩法

1. 荷官摇动碗盘，展示 4 枚硬币的结果
2. 每枚硬币有两面：**红色 (Đen)** 或 **白色 (Trắng)**
3. 玩家提前押注结果组合

### 投注类型与赔率

| 投注类型 | 说明 | 默认赔率 |
|---------|------|---------|
| **Chẵn (双)** | 4红 / 4白 / 2红2白 | 1:1 |
| **Lẻ (单)** | 3红1白 / 1红3白 | 1:1 |
| **4 Đen (4红)** | 4枚全红 | 10:1 |
| **4 Trắng (4白)** | 4枚全白 | 10:1 |
| **3 Đen (3红1白)** | 3红1白 | 3.5:1 |
| **3 Trắng (3白1红)** | 1红3白 | 3.5:1 |

### 房间类型

#### 1. Bàn Thu Phế (抽水台)
- 庄家对赢家抽取佣金（默认 5%）
- 标准玩法

#### 2. Bàn Xâu 3 Đen (免水台)
- 免抽水（1赔1）
- **特殊规则**：出现"3红1白"时，押"单"的玩家退款（可配置）
- 庄家通过特殊规则保持优势

---

## 🗂️ 系统架构

### 目录结构

```
touzi/
├── App/
│   ├── Controllers/
│   │   └── Admin/
│   │       ├── XocdiaRoomController.php      # 房间配置管理
│   │       └── XocdiaPeriodController.php    # 期号管理
│   └── Views/
│       └── Admin/
│           ├── xocdia_rooms.php              # 房间管理界面
│           └── xocdia_periods.php            # 期号管理界面
├── Db/
│   └── xocdia_schema.sql                     # 数据库表结构
├── Docs/
│   └── XOCDIA_ADMIN_GUIDE.md                 # 详细使用指南
└── routes.php                                 # 路由配置
```

### 数据库表

| 表名 | 用途 |
|-----|------|
| `xd_room_config` | 房间配置（赔率、限红、规则） |
| `xd_periods` | 期号记录（状态、结果、配置快照） |
| `xd_bets` | 投注记录 |
| `xd_settlements` | 结算汇总 |
| `xd_bet_stats` | 实时投注统计 |

---

## 🚀 快速开始

### 步骤1：初始化数据库

```bash
# 登录 MySQL
mysql -u your_username -p

# 使用现有数据库
USE touzi_database;

# 导入表结构
SOURCE /path/to/touzi/Db/xocdia_schema.sql;
```

**验证**：
```sql
SHOW TABLES LIKE 'xd_%';
-- 应该看到 5 个表

SELECT * FROM xd_room_config;
-- 应该看到 2 个默认房间
```

### 步骤2：访问后台

1. 登录后台：`http://yourdomain.com/admin/login`
2. 访问房间管理：`http://yourdomain.com/admin/xocdia/rooms`
3. 访问期号管理：`http://yourdomain.com/admin/xocdia/periods`

### 步骤3：配置房间

1. 在房间列表点击"编辑"
2. 修改赔率、限红、抽水比例等
3. 保存配置

### 步骤4：开始第一期游戏

1. 访问期号管理页面
2. 选择房间
3. 点击"开始新期号"
4. 等待用户下注（或手动点击"封盘"）
5. 点击"开奖"，选择 4 枚硬币的结果
6. 系统自动结算并更新用户余额

---

## 🎯 管理流程

### 完整流程图

```
┌────────────┐
│ 开始新期号  │ → 自动生成期号、快照配置
└──────┬─────┘
       ↓
┌────────────┐
│  下注阶段   │ → 用户可以投注（30-60秒）
└──────┬─────┘
       ↓
┌────────────┐
│    封盘     │ → 停止接受新投注
└──────┬─────┘
       ↓
┌────────────┐
│    开奖     │ → 管理员选择 4 枚硬币结果
└──────┬─────┘
       ↓
┌────────────┐
│  自动结算   │ → 判断输赢、计算赔付、更新余额
└──────┬─────┘
       ↓
┌────────────┐
│  展示结果   │ → 显示开奖结果和赔付明细
└────────────┘
```

### 关键操作

#### 1. 配置赔率

**方式 A：通过界面**
- 访问 `/admin/xocdia/rooms`
- 点击"编辑"按钮
- 修改赔率配置
- 保存

**方式 B：直接修改数据库**
```sql
UPDATE xd_room_config
SET odds = JSON_OBJECT(
    'even', 1.0,
    'odd', 1.0,
    'four_red', 15.0,  -- 修改为 15 倍
    'four_white', 15.0,
    'three_red', 5.0,
    'three_white', 5.0
),
version = version + 1
WHERE room_id = 1;
```

#### 2. 开始期号

**API 调用**：
```javascript
fetch('/admin/xocdia/periods/start', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ room_id: 1 })
})
```

#### 3. 开奖

**API 调用**：
```javascript
fetch('/admin/xocdia/periods/draw', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        period_id: 123,
        coins: [1, 1, 1, 0]  // 3红1白
    })
})
```

**开奖结果映射**：
```
[1, 1, 1, 1] → 4_red         (4红)
[1, 1, 1, 0] → 3_red_1_white (3红1白)
[1, 1, 0, 0] → 2_red_2_white (2红2白)
[1, 0, 0, 0] → 1_red_3_white (1红3白)
[0, 0, 0, 0] → 4_white       (4白)
```

---

## 💰 结算逻辑

### 基础结算（抽水台）

```
1. 判断输赢
   - 投注"双"，结果是 4红 → 赢
   - 投注"单"，结果是 3红1白 → 赢

2. 计算赔付
   - 赢得金额 = 投注金额 × 赔率
   - 佣金 = 赢得金额 × 佣金率 (5%)
   - 净盈亏 = 赢得金额 - 佣金

3. 更新余额
   - 用户余额 += 净盈亏

示例：
  投注 100 元押"单"，赔率 1.0，结果 3红1白
  → 赢得金额 = 100 × 1.0 = 100
  → 佣金 = 100 × 0.05 = 5
  → 净盈亏 = 100 - 5 = 95
  → 用户实际获得 95 元利润
```

### 特殊规则结算（免水台）

```
配置示例：
{
    "trigger_result": "3_red_1_white",    // 触发条件
    "affected_bet_types": ["odd"],         // 影响的投注类型
    "action": "refund",                    // 动作：退款
    "refund_percentage": 1.0               // 100% 退款
}

结算流程：
1. 检查结果是否为 "3_red_1_white"
2. 如果是，检查投注类型是否为 "odd"
3. 如果匹配，执行退款动作：
   - 赢得金额 = 投注金额 × 100% = 投注金额
   - 净盈亏 = 0（不赚不赔）
   - 状态 = 'refund'

示例：
  投注 100 元押"单"，结果 3红1白
  → 触发特殊规则
  → 退款 100 元
  → 净盈亏 = 0
```

---

## 📊 数据查询

### 查看房间盈亏

```sql
-- 今日盈亏
SELECT
    room_id,
    SUM(house_profit) as total_profit,
    SUM(total_bets_amount) as total_bets,
    COUNT(*) as period_count
FROM xd_settlements
WHERE settled_at >= CURDATE()
GROUP BY room_id;

-- 历史盈亏（按日）
SELECT
    DATE(settled_at) as date,
    room_id,
    SUM(house_profit) as daily_profit,
    COUNT(*) as period_count
FROM xd_settlements
WHERE room_id = 1
GROUP BY DATE(settled_at), room_id
ORDER BY date DESC
LIMIT 30;
```

### 查看用户投注记录

```sql
SELECT
    u.username,
    b.period_number,
    b.bet_type,
    b.bet_amount,
    b.status,
    b.net_profit,
    b.created_at
FROM xd_bets b
JOIN users u ON b.user_id = u.id
WHERE u.id = 123
ORDER BY b.created_at DESC
LIMIT 50;
```

### 统计热门玩法

```sql
SELECT
    bet_type,
    COUNT(*) as bet_count,
    SUM(bet_amount) as total_amount,
    AVG(bet_amount) as avg_amount
FROM xd_bets
WHERE created_at >= DATE_SUB(NOW(), INTERVAL 7 DAY)
GROUP BY bet_type
ORDER BY bet_count DESC;
```

---

## 🔧 配置说明

### 房间配置字段详解

```json
{
    "room_id": 1,
    "room_name": "Bàn Thu Phế",
    "room_type": "commission",  // commission=抽水台, special_rule=免水台

    // 赔率配置（倍数）
    "odds": {
        "even": 1.0,         // 双
        "odd": 1.0,          // 单
        "four_red": 10.0,    // 4红
        "four_white": 10.0,  // 4白
        "three_red": 3.5,    // 3红1白
        "three_white": 3.5   // 1红3白
    },

    // 抽水配置
    "commission_rate": 0.05,      // 5%
    "commission_enabled": true,   // 是否启用

    // 限红配置
    "limits": {
        "min_bet": 10,           // 最小投注
        "max_bet": 50000,        // 最大投注
        "max_payout": 500000     // 最大赔付
    },

    // 时间配置
    "timing": {
        "betting_duration": 30,         // 下注时长（秒）
        "result_display_duration": 8,   // 结果展示时长（秒）
        "auto_start_next": true         // 自动开始下一期
    },

    // 特殊规则（仅免水台）
    "special_rule": {
        "enabled": true,
        "trigger_result": "3_red_1_white",
        "affected_bet_types": ["odd"],
        "action": "refund",            // refund/half_win/lose
        "refund_percentage": 1.0       // 1.0=100%, 0.5=50%
    }
}
```

---

## ⚠️ 注意事项

### 配置修改

1. **配置修改后不会立即生效**
   - 当前期号使用配置快照
   - 新期号开始时才会读取最新配置

2. **版本控制**
   - 每次修改配置，`version` 字段自动 +1
   - 用于乐观锁，防止并发修改冲突

### 开奖操作

1. **开奖不可撤销**
   - 开奖后立即结算并更新余额
   - 如果误操作，需手动回滚数据库

2. **结算原子性**
   - 结算过程使用事务保证
   - 失败会自动回滚

### 安全建议

1. **限制管理员权限**
   - 开奖权限应严格控制
   - 建议启用操作日志

2. **数据备份**
   - 定期备份 `xd_*` 表
   - 重要操作前手动备份

3. **并发控制**
   - 避免多个管理员同时操作同一期号
   - 配置更新使用乐观锁

---

## 📚 相关文档

- **详细使用指南**: `Docs/XOCDIA_ADMIN_GUIDE.md`
- **后端逻辑架构**: 参见开发文档
- **数据库表结构**: `Db/xocdia_schema.sql`
- **API 接口文档**: 待补充

---

## 🛠️ 后续开发计划

### 第一阶段（核心功能完善）

- [ ] WebSocket 实时通信
- [ ] 自动化定时任务（自动开奖、封盘）
- [ ] 风险监控预警
- [ ] 操作日志记录

### 第二阶段（数据分析）

- [ ] 房间盈亏报表
- [ ] 用户行为分析
- [ ] 开奖历史走势图
- [ ] 实时数据可视化

### 第三阶段（体验优化）

- [ ] 移动端适配
- [ ] 多语言支持（越南语/中文）
- [ ] 游戏历史回放
- [ ] API 开放接口

---

## 📞 技术支持

如有问题，请查阅：
1. 详细使用指南：`Docs/XOCDIA_ADMIN_GUIDE.md`
2. 数据库表结构：`Db/xocdia_schema.sql`
3. 源代码文档：控制器代码注释

---

**开发完成日期**: 2026-01-08
**版本**: 1.0.0
**开发者**: Claude (AI Assistant)