295 lines
6.6 KiB
Markdown
Executable File
295 lines
6.6 KiB
Markdown
Executable File
# 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
|