# 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