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：初始化数据库

# 登录 MySQL
mysql -u your_username -p

# 使用现有数据库
USE touzi_database;

# 导入表结构
SOURCE /path/to/touzi/Db/xocdia_schema.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：直接修改数据库

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 调用：

fetch('/admin/xocdia/periods/start', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ room_id: 1 })
})

3. 开奖

API 调用：

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

---

📊 数据查询

查看房间盈亏

-- 今日盈亏
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;

查看用户投注记录

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;

统计热门玩法

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;

---

🔧 配置说明

房间配置字段详解

{
    "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)