دليل دمج نظام هدية الدونت (Donut Gift Stages)

هذا المستند يشرح لمطوري الموبايل كيفية ربط وبرمجة نظام هدية الدونت اليومية وتفاصيل واجهات برمجة التطبيقات (APIs) الخاصة بها وتتبع أوقات بقاء الأعضاء داخل غرف الدردشة الصوتية.

1. جلب حالة الاستلام وإعدادات المراحل (Get Donut Status)

يستخدم هذا الرابط لمعرفة المراحل المتاحة، الوقت المطلوب لكل مرحلة، تفاصيل الهدايا، وما إذا كان المستخدم قد استلمها بالفعل اليوم أم لا.

GET /api/v1/donut-gift/status

التوثيق (Headers)

Authorization: Bearer {token}
Accept: application/json

نموذج استجابة السيرفر الناجحة (JSON Response Example)

{
    "success": true,
    "active_minutes": 12,
    "data": [
        {
            "stage": 1,
            "minutes_required": 5,
            "gift": {
                "id": 12,
                "name": "إطار التاج الفضي",
                "image_path": "https://co-ko.app/uploads/decorations/frame_tag.png"
            },
            "quantity": 1,
            "valid_days": 7,
            "claimed": false
        },
        {
            "stage": 2,
            "minutes_required": 5,
            "gift": {
                "id": 45,
                "name": "أثر دخول التنين المضيء",
                "image_path": "https://co-ko.app/uploads/decorations/effect_dragon.png"
            },
            "quantity": 1,
            "valid_days": 3,
            "claimed": false
        },
        {
            "stage": 3,
            "minutes_required": 5,
            "gift": {
                "id": 99,
                "name": "هدية دونت ذهبية",
                "image_path": "https://co-ko.app/uploads/decorations/gift_donut.png"
            },
            "quantity": 5,
            "valid_days": null,
            "claimed": false
        }
    ]
}

شرح حقول الاستجابة:

الحقل	النوع	الوصف
`active_minutes`	`integer`	عدد الدقائق التراكمية التي قضاها المستخدم فعلياً داخل الغرف اليوم (يتم حسابها تلقائياً على السيرفر عبر نظام الـ WebSocket). يمكن للمطور استخدامها لعرض الوقت الحالي الذي قضاه العضو اليوم بدقة.
`stage`	`integer`	رقم المرحلة (1 أو 2 أو 3).
`minutes_required`	`integer`	عدد الدقائق المطلوبة لهذه المرحلة المحددة فقط (وليس تراكمياً). يقوم السيرفر بطرح وقت المراحل السابقة تلقائياً لتسهيل عرض العداد التنازلي محلياً على الموبايل.
`gift`	`object \| null`	تفاصيل التصميم/الهدية الممنوحة (معرّف التصميم، الاسم، ورابط الصورة). يكون `null` في حال لم يتم تحديد هدية في لوحة الإدارة بعد.
`quantity`	`integer`	الكمية الممنوحة من الهدية.
`valid_days`	`integer \| null`	أيام صلاحية الهدية (إذا كان `null` يعني أن صلاحية الهدية دائمة).
`claimed`	`boolean`	حالة الاستلام اليوم (`true` تعني تم الاستلام، `false` تعني لم يتم الاستلام بعد).

2. استلام مكافأة مرحلة معينة (Claim Donut Reward)

يستخدم هذا الرابط لإرسال طلب استلام هدية مرحلة محددة بعد إكمال وقت البقاء المطلوب في الغرفة.

POST /api/v1/donut-gift/claim

المعاملات المرسلة (Request Body)

الحقل	النوع	الوصف	إجباري
`stage`	`integer`	رقم المرحلة المراد استلامها، يجب أن يكون `1` أو `2` أو `3`.	نعم

نموذج الطلب (JSON Example)

{
    "stage": 2
}

حالات الاستجابة:

أ. نجاح الاستلام (200 OK)

{
    "success": true,
    "meta": {
        "message": "تم استلام الهدية بنجاح"
    },
    "data": {
        "stage": 2,
        "gift_name": "أثر دخول التنين المضيء",
        "quantity": 1
    }
}

ب. محاولة استلام مكرر (422 Unprocessable Entity)

{
    "success": false,
    "error": "لقد قمت باستلام هذه المرحلة بالفعل اليوم"
}

جـ. محاولة استلام مرحلة قبل السابقة (422 Unprocessable Entity)

{
    "success": false,
    "error": "يجب عليك استلام المرحلة 1 أولاً اليوم"
}

3. آلية تتبع الوقت في تطبيق الموبايل (Client-Side Logic)

لتأمين تجربة مستخدم سلسة وخالية من المشاكل، ينصح المطور بتطبيق الخطوات التالية:

1. عداد الوقت المحلي (Session Timer)

بمجرد دخول المستخدم أي غرفة صوتية نشطة، ابدأ في تشغيل عداد الوقت وتراكمه محلياً طوال اليوم لتمثيل مدة نشاط العضو.

2. تحديث الحالة بانتظام

عند فتح واجهة هدية الدونت، أرسل طلب GET لتحديث حالة التفعيل والوقت المطلوب من الخادم، وقم بحساب الوقت المتبقي لكل مرحلة لعرض عداد تنازلي دقيق.

3. تفعيل زر الاستلام

عند إكمال الوقت المطلوب للمرحلة الحالية، قم بتفعيل زر الاستلام. بعد نقر المستخدم وإرسال طلب POST بنجاح، اعرض شاشة تهنئة بالهدية المكتسبة وحدث زر المرحلة إلى "تم الاستلام".

4. أكواد الحالة (Status Codes)

200 OK: تمت عملية الاستلام بنجاح وإضافة المكافأة.

422: خطأ في المنطق (استلام مكرر، مرحلة غير مرتبة، لم تحدد هدية).

401: التوكن الخاص بالمستخدم مفقود أو غير صالح.