📱 توثيق دمج هدايا Lucky & Returnable

يحدد هذا المستند المتطلبات التقنية لدمج ميزات هدايا Lucky و Returnable الجديدة في التطبيق، مع التركيز على الأداء العالي والنتائج اللحظية.

1. API إرسال الهدايا (Sending Gifts)

يوصى باستخدام الـ Endpoint السريع للألعاب التي تتطلب استجابة فورية.

POST /api/v1/instant-send

البديل (المخزن): /api/v1/users/{user_id}/decorations/send

المעاملات (Request Parameters - Instant Send):

Parameter	Type	Required	Description
`u_id`	Integer	Yes	ID of the sender (Authenticated User).
`decoration_id`	Integer	Yes	ID of the gift being sent.
`user_id`	Array	Yes	Array of receiver IDs, e.g., `[123]`.
`quantity`	Integer	Yes	Number of gifts to send.
`room_id`	Integer	Yes	Current room ID/UID.
`is_bag`	Boolean	Optional	Set to `1` if sending from user inventory.
`with_encryption`	Boolean	Optional	Set to `1` for encrypted socket response.

2. معالجة رد الـ API (Response Handling)

عند إرسال Lucky Gift عبر instant-send، يقوم الـ API بإرجاع نتيجة "اللعبة السحرية" فوراً في استجابة الـ HTTP.

مثال للاستجابة الناجحة (Success Response):

{
    "data": {
        "diamonds": 100250,
        "lucky_result": {
            "code": 200,
            "data": {
                "gift_id": 576,
                "gift_price": 100,
                "OrderList": [
                    {
                        "order_id": "9df3b0e5-...",
                        "is_win": 1,
                        "reward_num": 390
                    }
                ]
            }
        }
    }
}

حقول هامة لواجهة الموبايل:

diamonds: رصيد الماس المحدث للمستخدم. يجب تحديث العداد في الواجهة فوراً.
lucky_result.data.OrderList: إذا كانت is_win == 1، قم بإظهار أنيميشن الفوز مع عدد المكافأة reward_num.

3. التنبيهات اللحظية (System Socket)

يجب على التطبيق الاستماع لأحداث Socket محددة (خارج Pusher) لإظهار الإعلانات الفائزة.

Event: lucky-big-win

النطاق: خاص بالغرفة (Room Context).

الشرط: المكافأة >= 5,000 ماسة.

Event: lucky-big-win-all

النطاق: عام على مستوى التطبيق (Global).

الشرط: المكافأة >= 10,000 ماسة.

Event: one-to-room:lucky-gift-sent

النطاق: خاص بالغرفة (Room Context).

الوصف: أنيميشن الإرسال المتتالي (يتصفر بعد توقف 6 ثوانٍ).

هيكل البيانات (Payload Structure):

{
    "user": {
        "id": 1,
        "name": "User Name",
        "uid": "12345",
        "current_profile_image_url": "..."
    },
    "reward": 15000,
    "decoration": {
        "id": 576,
        "name": "Fire Eagle",
        "image_path": "..."
    }
}

هيكل بيانات متتالي الحظ (lucky-gift-sent Payload):

{
  "id": "7607b9cb7d82e18a71d0346f915d3bf8",
  "totalcost": 100,
  "gift": {
    "id": 576,
    "name": "Fire Eagle",
    "image_path": "..."
  },
  "times": 5,
  "senderid": 297,
  "receiversids": ["300"],
  "currencycount": 20,
  "quantity": 1,
  "roomuid": "1134370",
  "win": 150,
  "last_update": "2026-04-16 18:40:00"
}

4. ملخص قواعد العمل (Business Rules)

🎁 هدايا Lucky

عمولة أدمن الغرفة: 0%.
نقاط الكأس (Trophy): 0.
دخل المستلم (ذهب/هدف): 10% من القيمة.

♻️ هدايا Returnable

تُعامل تماماً مثل هدايا Lucky (دخل المستلم 10%، لا توجد حصة للغرفة أو نقاط).

✨ الهدايا القياسية

تظل القواعد كما هي دون تغيير (دخل المستلم 100%، حصة الغرفة 3%).

5. توصيات تجربة المستخدم (UI/UX Recommendations)

السرعة هي الأهم: استخدم instant-send لضمان عودة نتيجة الفوز قبل وصول رسالة الـ Socket، مما يمنع حدوث لاغ (UI Lag).
التبعية البصرية: يجب أن يظهر lucky-big-win أنيميشن داخل الغرفة، بينما lucky-big-win-all يفعل بنر علوي يراه الجميع.
فك تشفير الأصول: في حال استخدام with_encryption، يجب على التطبيق فك تشفير مسارات الصور والفيديو باستخدام منطق rot41 المعتمد.