Initial commit: 投注游戏平台初始化
This commit is contained in:
li
Executable
+294
@@ -0,0 +1,294 @@
|
||||
# Xóc Đĩa API 快速参考表
|
||||
|
||||
> 这是简化版的 API 参考表，详细文档请查看 `XOCDIA_API_DOCUMENTATION.md`
|
||||
|
||||
---
|
||||
|
||||
## WebSocket 连接
|
||||
|
||||
```javascript
|
||||
const ws = new WebSocket('ws://yourdomain.com/ws/xocdia');
|
||||
|
||||
// 连接成功后订阅房间
|
||||
ws.send(JSON.stringify({
|
||||
action: 'SUBSCRIBE_ROOM',
|
||||
data: { room_id: 1 }
|
||||
}));
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 服务器推送事件（监听）
|
||||
|
||||
| 事件名 | 说明 | 数据示例 |
|
||||
|--------|------|---------|
|
||||
| `GAME_START` | 新期号开始 | `{ period_id, period_number, countdown, config }` |
|
||||
| `COUNTDOWN_UPDATE` | 倒计时更新（每秒） | `{ remaining: 25 }` |
|
||||
| `BET_SUCCESS` | 投注成功 | `{ bet_id, remaining_balance, potential_win }` |
|
||||
| `BETTING_CLOSED` | 封盘 | `{ state: "shaking" }` |
|
||||
| `GAME_RESULT` | 开奖结果 | `{ result: { coins, pattern }, settlement }` |
|
||||
| `ERROR` | 错误 | `{ code, message }` |
|
||||
|
||||
---
|
||||
|
||||
## 客户端发送动作
|
||||
|
||||
### 1. 下注（WebSocket）
|
||||
|
||||
```javascript
|
||||
ws.send(JSON.stringify({
|
||||
action: 'PLACE_BET',
|
||||
data: {
|
||||
room_id: 1,
|
||||
period_id: 12345,
|
||||
bet_type: 'odd', // even/odd/four_red/four_white/three_red/three_white
|
||||
bet_amount: 100
|
||||
}
|
||||
}));
|
||||
```
|
||||
|
||||
### 2. 获取当前状态
|
||||
|
||||
```javascript
|
||||
ws.send(JSON.stringify({
|
||||
action: 'GET_GAME_STATE',
|
||||
data: { room_id: 1 }
|
||||
}));
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## HTTP API 端点
|
||||
|
||||
### 获取房间列表
|
||||
```http
|
||||
GET /api/xocdia/rooms
|
||||
```
|
||||
|
||||
### 获取房间详情
|
||||
```http
|
||||
GET /api/xocdia/rooms/{room_id}
|
||||
```
|
||||
|
||||
### 获取当前期号
|
||||
```http
|
||||
GET /api/xocdia/periods/current?room_id=1
|
||||
```
|
||||
|
||||
### 下注（HTTP 备用）
|
||||
```http
|
||||
POST /api/xocdia/bet
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"room_id": 1,
|
||||
"period_id": 12345,
|
||||
"bet_type": "odd",
|
||||
"bet_amount": 100
|
||||
}
|
||||
```
|
||||
|
||||
### 获取开奖历史
|
||||
```http
|
||||
GET /api/xocdia/periods/history?room_id=1&limit=20
|
||||
```
|
||||
|
||||
### 获取我的投注记录
|
||||
```http
|
||||
GET /api/xocdia/my-bets?room_id=1&limit=20
|
||||
```
|
||||
|
||||
### 获取用户余额
|
||||
```http
|
||||
GET /api/user/balance
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 投注类型（bet_type）
|
||||
|
||||
| 类型值 | 中文 | 越南语 | 赔率 |
|
||||
|--------|------|--------|------|
|
||||
| `even` | 双 | Chẵn | 1:1 |
|
||||
| `odd` | 单 | Lẻ | 1:1 |
|
||||
| `four_red` | 4红 | 4 Đen | 10:1 |
|
||||
| `four_white` | 4白 | 4 Trắng | 10:1 |
|
||||
| `three_red` | 3红1白 | 3 Đen 1 Trắng | 3.5:1 |
|
||||
| `three_white` | 1红3白 | 1 Đen 3 Trắng | 3.5: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=红, 0=白
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 游戏状态（state）
|
||||
|
||||
| 状态值 | 说明 | 前端行为 |
|
||||
|--------|------|---------|
|
||||
| `waiting` | 等待中 | 显示上期结果 |
|
||||
| `betting` | 下注中 | 显示倒计时，开放投注 |
|
||||
| `shaking` | 摇碟中 | 禁用投注，显示动画 |
|
||||
| `settling` | 结算中 | 等待结算完成 |
|
||||
| `showing` | 展示结果 | 显示开奖结果和赔付 |
|
||||
|
||||
---
|
||||
|
||||
## 常见错误码
|
||||
|
||||
| 错误码 | 说明 | 处理方式 |
|
||||
|--------|------|---------|
|
||||
| `NOT_LOGGED_IN` | 未登录 | 跳转登录页 |
|
||||
| `INSUFFICIENT_BALANCE` | 余额不足 | 提示充值 |
|
||||
| `BET_AMOUNT_INVALID` | 投注金额无效 | 检查限红 |
|
||||
| `BETTING_CLOSED` | 已封盘 | 等待下期 |
|
||||
| `PERIOD_NOT_FOUND` | 期号不存在 | 刷新页面 |
|
||||
|
||||
---
|
||||
|
||||
## 前端完整示例
|
||||
|
||||
```javascript
|
||||
// 1. 连接 WebSocket
|
||||
const ws = new WebSocket('ws://yourdomain.com/ws/xocdia');
|
||||
|
||||
ws.onopen = () => {
|
||||
// 2. 订阅房间
|
||||
ws.send(JSON.stringify({
|
||||
action: 'SUBSCRIBE_ROOM',
|
||||
data: { room_id: 1 }
|
||||
}));
|
||||
};
|
||||
|
||||
ws.onmessage = (event) => {
|
||||
const msg = JSON.parse(event.data);
|
||||
|
||||
// 3. 处理服务器事件
|
||||
switch (msg.event) {
|
||||
case 'GAME_START':
|
||||
// 显示期号，启动倒计时，开放投注
|
||||
document.getElementById('period').textContent = msg.data.period_number;
|
||||
startCountdown(msg.data.countdown);
|
||||
break;
|
||||
|
||||
case 'COUNTDOWN_UPDATE':
|
||||
// 更新倒计时
|
||||
document.getElementById('countdown').textContent = msg.data.remaining;
|
||||
break;
|
||||
|
||||
case 'BET_SUCCESS':
|
||||
// 更新余额，显示投注成功
|
||||
document.getElementById('balance').textContent = msg.data.remaining_balance;
|
||||
alert('投注成功！');
|
||||
break;
|
||||
|
||||
case 'BETTING_CLOSED':
|
||||
// 禁用投注按钮
|
||||
disableBettingButtons();
|
||||
break;
|
||||
|
||||
case 'GAME_RESULT':
|
||||
// 显示开奖结果
|
||||
showResult(msg.data.result.coins);
|
||||
updateBalance(msg.data.settlement.new_balance);
|
||||
showProfit(msg.data.settlement.net_profit);
|
||||
break;
|
||||
|
||||
case 'ERROR':
|
||||
alert(msg.data.message);
|
||||
break;
|
||||
}
|
||||
};
|
||||
|
||||
// 4. 投注
|
||||
function placeBet(betType, amount) {
|
||||
ws.send(JSON.stringify({
|
||||
action: 'PLACE_BET',
|
||||
data: {
|
||||
room_id: 1,
|
||||
period_id: currentPeriodId,
|
||||
bet_type: betType,
|
||||
bet_amount: amount
|
||||
}
|
||||
}));
|
||||
}
|
||||
|
||||
// 5. 按钮事件
|
||||
document.getElementById('btn-bet-even').onclick = () => {
|
||||
placeBet('even', 100);
|
||||
};
|
||||
|
||||
document.getElementById('btn-bet-odd').onclick = () => {
|
||||
placeBet('odd', 100);
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **所有请求需携带 Cookie**：`credentials: 'include'`
|
||||
2. **WebSocket 断线重连**：监听 `onclose` 事件，延迟重连
|
||||
3. **金额精度**：使用浮点数，保留 2 位小数
|
||||
4. **时区处理**：服务器返回 UTC 时间，前端转换为本地时间
|
||||
5. **防抖处理**：投注按钮需防抖，避免重复提交
|
||||
6. **余额实时更新**：监听 `BET_SUCCESS` 和 `GAME_RESULT` 更新余额
|
||||
|
||||
---
|
||||
|
||||
## 测试数据
|
||||
|
||||
### 模拟开奖结果
|
||||
|
||||
```javascript
|
||||
// 测试用：手动触发开奖结果
|
||||
const mockResult = {
|
||||
event: 'GAME_RESULT',
|
||||
data: {
|
||||
result: {
|
||||
coins: [1, 1, 1, 0],
|
||||
pattern: '3_red_1_white',
|
||||
display_text: '3 Đen 1 Trắng'
|
||||
},
|
||||
settlement: {
|
||||
your_bets: [
|
||||
{
|
||||
bet_type: 'odd',
|
||||
bet_amount: 100,
|
||||
is_win: true,
|
||||
win_amount: 100,
|
||||
commission: 5,
|
||||
net_profit: 95
|
||||
}
|
||||
],
|
||||
new_balance: 10095
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
ws.onmessage({ data: JSON.stringify(mockResult) });
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 完整文档
|
||||
|
||||
详细说明、TypeScript 类型定义、高级功能请查看：
|
||||
|
||||
**`XOCDIA_API_DOCUMENTATION.md`**
|
||||
|
||||
---
|
||||
|
||||
**快速参考版本**: v1.0.0
|
||||
**最后更新**: 2026-01-08
|
||||
Reference in New Issue
Block a user