pk10/Docs/XOCDIA_API_QUICK_REFERENCE.md

Xóc Đĩa API 快速参考表

这是简化版的 API 参考表，详细文档请查看 XOCDIA_API_DOCUMENTATION.md

---

WebSocket 连接

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）

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. 获取当前状态

ws.send(JSON.stringify({
    action: 'GET_GAME_STATE',
    data: { room_id: 1 }
}));

---

HTTP API 端点

获取房间列表

GET /api/xocdia/rooms

获取房间详情

GET /api/xocdia/rooms/{room_id}

获取当前期号

GET /api/xocdia/periods/current?room_id=1

下注（HTTP 备用）

POST /api/xocdia/bet
Content-Type: application/json

{
    "room_id": 1,
    "period_id": 12345,
    "bet_type": "odd",
    "bet_amount": 100
}

获取开奖历史

GET /api/xocdia/periods/history?room_id=1&limit=20

获取我的投注记录

GET /api/xocdia/my-bets?room_id=1&limit=20

获取用户余额

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	期号不存在	刷新页面

---

前端完整示例

// 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 更新余额

---

测试数据

模拟开奖结果

// 测试用：手动触发开奖结果
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