🎡 توثيق نظام لعبة الروليت (Roulette Game)

يوفر هذا المستند دليلاً شاملاً لنظام لعبة الروليت، ويغطي نقاط نهاية API، وأحداث WebSocket، ومنطق الربط الداخلي.

محرك API:

PHP-FPM (Standard Laravel)

محرك WebSocket:

Swoole (Laravel Swoole)

جسر التواصل:

HTTP Bridge on 127.0.0.1:1215

المصادقة (Authentication):

تتطلب جميع طلبات الـ API إرسال Bearer Token في العناوين:

Authorization: Bearer {token}
Accept: application/json

1. تكامل الغرف (Room Integration)

يتم حقن بيانات لعبة الروليت النشطة داخل مورد الغرفة (Room Resource) القياسي.

GET /v1/rooms/{uid}

GET /v1/rooms/{uid}/join

الحقل المضاف:

active_roulette_game: يحتوي على كائن اللعبة أو null في حال عدم وجود لعبة نشطة.

2. التحكم في اللعبة (API Endpoints)

المسار الأساسي: /v1/rooms/{room_uid}/games/roulette

الإجراء	الطريقة	النقطة (Endpoint)	الوصف
جلب اللعبة النشطة	`GET`	`/`	إرجاع اللعبة الحالية في الغرفة.
إنشاء لعبة	`POST`	`/create`	إنشاء لعبة جديدة (دعم `join_admin=1` للانضمام التلقائي).
الانضمام للعبة	`POST`	`/join/{id}`	انضمام لاعب للعبة موجودة.
مغادرة اللعبة	`POST`	`/leave/{id}`	مغادرة اللاعب (استرداد الكوينز إذا كان ذلك ممكناً).
إنهاء اللعبة	`POST`	`/finish/{id}`	تشغيل عجلة الحظ واختيار الفائز.
إلغاء اللعبة	`DELETE`	`/{id}`	إلغاء اللعبة من قبل المنشئ.

💡 ملاحظة: جميع النقاط تدعم استخدام معرف الـ ID (الرقمي) أو الـ UID (النصي) بشكل تبادلي في البارامترات.

3. أحداث الويب سوكيت (One-To-Room)

يتم بث جميع الأحداث إلى قناة الغرفة: one-to-room:{room_uid}.

أ. إنشاء اللعبة (roulette-wheel-created)

{
  "id": 15,
  "game_price": 100,
  "prize": 200,
  "max_players": 2,
  "from": { "id": 58, "name": "...", "avatar": "...", "uid": "58" },
  "created_at": "2026-04-22 18:30:00"
}

ب. الانضمام (roulette-wheel-joined)

{
  "game_id": 15,
  "user": { "id": 123, "name": "...", "avatar": "..." }
}

ج. إنهاء اللعبة (roulette-wheel-finished)

يتم إرساله عند اختيار الفائز وتوزيع الجوائز.

{
  "game_id": 15,
  "winner": { "id": 58, "name": "...", "avatar": "..." },
  "prize": 200,
  "losers": [ { "id": 123, "name": "...", "avatar": "..." } ]
}

د. إلغاء اللعبة (roulette-wheel-destroyed)

{ "game_id": 15 }

4. أكواد الخطأ والرسائل (Error Codes)

Only game creator can destroy game: خطأ في الصلاحية عند محاولة الإلغاء.
Game is finished: محاولة الانضمام أو المغادرة من لعبة مكتملة.
You already joined this game: تكرار محاولة الانضمام.
Game is full: تم الوصول للحد الأقصى من اللاعبين.

5. أوامر الصيانة (Maintenance Commands)

لمسح الألعاب العالقة (التي لم تنتهِ) من خلال التيرمينال:

php artisan tinker --execute="App\Models\GameRouletteWheel::whereNull('finished_at')->delete()"