Initial commit: 投注游戏平台初始化

2026-02-25 01:26:58 +08:00
commit 77ca2cc8b3
275 changed files with 237479 additions and 0 deletions
@@ -0,0 +1,480 @@
+# 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