# Xóc Đĩa 游戏后台管理使用指南

## 目录
1. [快速开始](#快速开始)
2. [数据库初始化](#数据库初始化)
3. [房间配置管理](#房间配置管理)
4. [期号管理流程](#期号管理流程)
5. [实时监控](#实时监控)
6. [常见问题](#常见问题)

---

## 快速开始

### 访问地址

- **房间配置管理**: `http://yourdomain.com/admin/xocdia/rooms`
- **期号管理**: `http://yourdomain.com/admin/xocdia/periods`
- **实时监控**: `http://yourdomain.com/admin/xocdia/monitor?room_id=1`

### 前置条件

1. 已完成系统安装（`/install`）
2. 已创建管理员账号并登录后台
3. 已执行数据库初始化脚本

---

## 数据库初始化

### 步骤1：导入数据库表结构

连接到 MySQL 数据库，执行以下命令：

```bash
mysql -u your_username -p your_database < Db/xocdia_schema.sql
```

或者通过 phpMyAdmin 导入 `Db/xocdia_schema.sql` 文件。

### 步骤2：验证表是否创建成功

```sql
SHOW TABLES LIKE 'xd_%';
```

应该看到以下表：
- `xd_room_config` - 房间配置表
- `xd_periods` - 期号表
- `xd_bets` - 投注记录表
- `xd_settlements` - 结算汇总表
- `xd_bet_stats` - 实时投注统计表

### 步骤3：查看默认房间

数据库初始化时已自动创建两个默认房间：

```sql
SELECT room_id, room_name, room_type FROM xd_room_config;
```

- **Room 1**: Bàn Thu Phế (抽水台) - 标准抽水 5%
- **Room 2**: Bàn Xâu 3 Đen (免水台) - 特殊规则，3红1白时退款

---

## 房间配置管理

### 访问房间列表

1. 登录后台后，访问 `/admin/xocdia/rooms`
2. 可以看到所有房间的列表

### 创建新房间

**注意**：当前版本暂不支持通过界面创建房间，请直接修改数据库或复制以下 SQL：

```sql
INSERT INTO xd_room_config (room_id, room_name, room_type, odds, limits, timing)
VALUES (
    3,  -- 新房间ID
    '高级房',  -- 房间名称
    'commission',  -- 房间类型
    JSON_OBJECT(
        'even', 1.0,
        'odd', 1.0,
        'four_red', 12.0,  -- 可自定义赔率
        'four_white', 12.0,
        'three_red', 4.0,
        'three_white', 4.0
    ),
    JSON_OBJECT(
        'min_bet', 100,  -- 最小投注
        'max_bet', 100000,  -- 最大投注
        'max_payout', 1000000
    ),
    JSON_OBJECT(
        'betting_duration', 60,  -- 下注时长60秒
        'result_display_duration', 10,
        'auto_start_next', true
    )
);
```

### 编辑房间配置

#### 方式1：通过后台界面

1. 在房间列表点击"编辑"按钮
2. 修改以下配置项：

**基本设置**
- 房间名称
- 房间类型（抽水台/免水台）
- 抽水比例（仅抽水台）

**赔率配置**
- 双 (Chẵn) - 默认 1.0
- 单 (Lẻ) - 默认 1.0
- 4红 - 默认 10.0
- 4白 - 默认 10.0
- 3红1白 - 默认 3.5
- 3白1红 - 默认 3.5

**限红配置**
- 最小投注：建议 10-100
- 最大投注：建议 50000-100000
- 最大赔付：建议 500000-1000000

**时间配置**
- 下注时长：建议 30-60 秒

3. 点击"保存配置"

#### 方式2：直接修改数据库

```sql
-- 修改赔率
UPDATE xd_room_config
SET odds = JSON_OBJECT(
    'even', 1.0,
    'odd', 1.0,
    'four_red', 15.0,  -- 修改赔率
    'four_white', 15.0,
    'three_red', 5.0,
    'three_white', 5.0
),
version = version + 1  -- 版本号加1
WHERE room_id = 1;
```

### 配置生效时机

⚠️ **重要**：配置修改后，**下一期号开始时**才会生效。

- 当前正在进行的期号使用"配置快照"，不受影响
- 新开始的期号会读取最新配置

### 开放/关闭房间

1. 在房间列表点击"开放"或"关闭"按钮
2. 关闭的房间无法开始新期号

---

## 期号管理流程

### 完整流程图

```
开始新期号 → 下注阶段 (30-60s) → 封盘 → 开奖 → 自动结算 → 展示结果 → 完成
```

### 步骤1：开始新期号

1. 访问 `/admin/xocdia/periods`
2. 选择房间
3. 点击"开始新期号"按钮

**自动执行的操作**：
- 生成期号（格式：`YYYYMMDD-001`）
- 快照当前房间配置
- 初始化投注统计表
- 设置状态为 `betting`

### 步骤2：下注阶段

此时前台用户可以下注。

**管理员可以**：
- 实时查看投注统计（访问监控页面）
- 手动封盘（提前结束下注）

**自动封盘**：
- 如果配置了倒计时，到时间后自动封盘（需 WebSocket 支持）

### 步骤3：封盘

1. 在期号列表找到状态为"下注中"的期号
2. 点击"封盘"按钮

**自动执行的操作**：
- 设置状态为 `shaking`
- 记录封盘时间
- 拒绝新的投注请求

### 步骤4：开奖

1. 在期号列表找到状态为"摇碟中"的期号
2. 点击"开奖"按钮
3. 在弹窗中选择 4 枚硬币的结果：
   - **1 = 红色 (Đen)**
   - **0 = 白色 (Trắng)**

**示例结果**：
- `[1, 1, 1, 0]` = 3红1白 = `3_red_1_white`
- `[1, 1, 1, 1]` = 4红 = `4_red`
- `[0, 0, 0, 0]` = 4白 = `4_white`

4. 点击"确认开奖并结算"

### 步骤5：自动结算

开奖后，系统自动执行以下操作：

1. **判断输赢**
   - 遍历所有投注记录
   - 根据开奖结果判断是否赢

2. **计算赔付**
   - 赢的投注：`赢得金额 = 投注金额 × 赔率`
   - 输的投注：`净盈亏 = -投注金额`

3. **应用佣金**（仅抽水台）
   - `佣金 = 赢得金额 × 佣金率`
   - `净盈亏 = 赢得金额 - 佣金`

4. **应用特殊规则**（仅免水台）
   - 检查是否触发特殊规则（如 3红1白）
   - 如果触发：
     - `action=refund`: 退款，净盈亏 = 0
     - `action=half_win`: 只赢一半
     - `action=lose`: 强制输

5. **更新余额**
   - 更新所有玩家的余额
   - 记录交易流水

6. **生成结算汇总**
   - 总投注笔数
   - 总投注金额
   - 总赢得金额
   - 总佣金
   - **庄家盈利** = 总投注额 - (总赢得金额 - 总佣金)

7. **完成**
   - 设置状态为 `showing`

### 步骤6：查看结算详情

1. 点击期号的"详情"按钮
2. 查看：
   - 开奖结果
   - 投注统计
   - 结算数据
   - 庄家盈亏

---

## 实时监控

### 访问监控页面

```
/admin/xocdia/monitor?room_id=1
```

### 监控内容

1. **当前期号信息**
   - 期号
   - 状态
   - 倒计时（如果在下注阶段）

2. **实时投注统计**（需要数据库触发器或定时刷新）
   - 各投注项的金额
   - 各投注项的笔数
   - 单边倾斜预警

3. **赔付预测**
   - 如果结果是 X，庄家盈亏多少
   - 最差情况/最佳情况分析

---

## 常见问题

### Q1: 配置修改后为什么还是旧的赔率？

**答**：当前期号使用的是"配置快照"，修改不会影响正在进行的期号。新期号开始后才会使用新配置。

---

### Q2: 如何验证结算是否正确？

**答**：可以手动计算验证：

```sql
-- 查看某期号的结算汇总
SELECT * FROM xd_settlements WHERE period_id = 123;

-- 查看详细投注记录
SELECT
    bet_type,
    COUNT(*) as count,
    SUM(bet_amount) as total_bet,
    SUM(win_amount) as total_win,
    SUM(commission) as total_commission,
    SUM(net_profit) as total_profit
FROM xd_bets
WHERE period_id = 123
GROUP BY bet_type;
```

验证公式：
```
庄家盈利 = 总投注额 - (总赢得金额 - 总佣金)
        = 总投注额 - 玩家净盈亏总和
```

---

### Q3: 如何处理误操作开奖？

**答**：当前版本不支持撤销开奖。如果误操作：

1. **紧急方案**：直接修改数据库
   ```sql
   -- 回滚期号状态（谨慎操作！）
   UPDATE xd_periods SET state = 'shaking', result = NULL WHERE id = 123;

   -- 删除结算记录
   DELETE FROM xd_settlements WHERE period_id = 123;

   -- 回滚投注记录
   UPDATE xd_bets SET status = 'pending', is_win = 0, win_amount = 0, commission = 0, net_profit = 0 WHERE period_id = 123;

   -- 手动调整受影响用户的余额（需逐个计算）
   ```

2. **推荐方案**：联系技术团队处理

---

### Q4: 特殊规则如何配置？

**答**：修改 `special_rule` 字段（JSON 格式）：

```sql
UPDATE xd_room_config
SET special_rule = JSON_OBJECT(
    'enabled', true,
    'trigger_result', '3_red_1_white',  -- 触发条件：3红1白
    'affected_bet_types', JSON_ARRAY('odd'),  -- 影响的投注类型
    'action', 'refund',  -- 动作：refund/half_win/lose
    'refund_percentage', 1.0  -- 退款比例（1.0=100%）
),
version = version + 1
WHERE room_id = 2;
```

**常见配置示例**：

| 规则名称 | trigger_result | affected_bet_types | action | refund_percentage |
|---------|----------------|-------------------|--------|------------------|
| Xâu 3 Đen 全退款 | 3_red_1_white | ['odd'] | refund | 1.0 |
| Xâu 3 Đen 半退款 | 3_red_1_white | ['odd'] | refund | 0.5 |
| Xâu 3 Đen 只赢一半 | 3_red_1_white | ['odd'] | half_win | - |
| Xâu 3 Đen 强制输 | 3_red_1_white | ['odd'] | lose | - |

---

### Q5: 如何查看房间盈亏统计？

**答**：执行以下 SQL：

```sql
-- 查看某房间今日盈亏
SELECT
    SUM(house_profit) as total_profit,
    SUM(total_bets_amount) as total_bets,
    SUM(total_commission) as total_commission,
    COUNT(*) as period_count
FROM xd_settlements
WHERE room_id = 1
  AND settled_at >= CURDATE();

-- 查看某房间历史盈亏（按日统计）
SELECT
    DATE(settled_at) as date,
    COUNT(*) as period_count,
    SUM(total_bets_amount) as total_bets,
    SUM(house_profit) as total_profit
FROM xd_settlements
WHERE room_id = 1
GROUP BY DATE(settled_at)
ORDER BY date DESC
LIMIT 30;
```

---

### Q6: 如何备份游戏数据？

**答**：定期备份以下表：

```bash
# 备份所有 Xóc Đĩa 相关表
mysqldump -u username -p database_name \
  xd_room_config \
  xd_periods \
  xd_bets \
  xd_settlements \
  xd_bet_stats \
  > xocdia_backup_$(date +%Y%m%d).sql
```

---

## 后续开发建议

### 高优先级

1. **WebSocket 集成**
   - 实时推送游戏状态变化
   - 自动倒计时
   - 实时投注更新

2. **自动化流程**
   - 定时自动开始新期号
   - 定时自动封盘
   - 定时自动开奖（如接入硬件设备）

3. **风险控制**
   - 单边预警（投注严重倾斜时提醒）
   - 异常投注检测
   - 最大赔付限制

### 中优先级

4. **数据分析**
   - 房间盈亏报表
   - 用户投注习惯分析
   - 热门玩法统计

5. **用户体验优化**
   - 投注历史查询
   - 开奖历史走势图
   - 房间排行榜

### 低优先级

6. **高级功能**
   - 多语言支持（越南语/中文/英文）
   - 移动端适配
   - API 接口文档

---

## 技术支持

如有问题，请参考：
- 后端逻辑设计：`/path/to/architecture_design.md`
- 数据库表结构：`Db/xocdia_schema.sql`
- 控制器代码：`App/Controllers/Admin/Xocdia*.php`

---

**最后更新**: 2026-01-08
**文档版本**: 1.0.0