دفتر التشغيل المركزي لخدمة API¶

1. المهمة والنطاق¶

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

هي تطبيق Laravel قوي مصمم ليكون النواة المستقرة للمنصة. يفرض سلامة البيانات، وينسق تدفقات العمل المعقدة من خلال نظام قائم على قوائم الانتظار، ويوفر واجهة GraphQL API غنية للعملاء الأماميين. تعطي بنيته الهندسية الأولوية للاستقرار، سلامة البيانات، والعقود الواضحة والمُدارة بالإصدارات للخدمات المتفاعلة.

2. مسؤوليات الخدمة وتفاعلاتها¶

يحدد هذا الجدول الدور المركزي لخدمة API واعتمادياتها الحيوية داخل منظومة منصة لبيب.

3. المبادئ التوجيهية¶

تستند البنية الهندسية والفلسفة التشغيلية لخدمة API بشكل عميق على مبادئ SRE الأساسية التالية:

• مصدر الحقيقة ():

  • ماذا: قاعدة بيانات PostgreSQL هي مصدر الحقيقة النهائي لجميع البيانات العلائقية. خدمة API هي المالك الحصري لمخططها وصلاحيات الكتابة.
  • لماذا: يمنع هذا تلف البيانات وسيناريوهات "انقسام الدماغ" من خلال ضمان وجود مخزن بيانات واحد ومعتمد.

• غير متزامن افتراضيًا ():

  • ماذا: جميع المهام الثقيلة أو التي تستغرق وقتًا طويلاً (مثل تحليل الذكاء الاصطناعي، فهرسة البحث) يتم تفريغها إلى نظام قوائم انتظار قوي (Laravel Horizon & Redis).
  • لماذا: يحافظ هذا على استجابة ومرونة API. يمكن تأكيد طلب الجلب في أجزاء من الثانية، بينما تتم المعالجة المعقدة بموثوقية في الخلفية.

• عقود صارمة ومُدارة بالإصدارات ():

  • ماذا: جميع الاتصالات بين الخدمات، وخاصة الجلب، تخضع لعقد صارم ومُدار بالإصدارات.
  • لماذا: يسمح هذا للخدمات الأخرى (مثل Scraper) بالتطور بشكل مستقل دون كسر API الأساسية، مما يضمن استقرار المنصة.

• منطق مدفوع بقاعدة البيانات ():

  • ماذا: يتم تغليف منطق العمل الأساسي داخل إطار عمل Laravel، بشكل أساسي في نماذج Eloquent والخدمات والمهام.
  • لماذا: يستفيد هذا من إطار عمل ناضج ومُختبَر جيدًا، مما يقلل من الشيفرة البرمجية المتكررة ويعزز منطق العمل القابل للصيانة والاختبار.

4. نظرة سريعة على البنية الهندسية¶

تقع خدمة API في قلب المنصة، حيث تتلقى البيانات من Scraper، وتنسق العمل مع AI-Box، وتخدم الاستعلامات للعملاء.

    flowchart TD
        subgraph "الخدمات المصدرية"
            SCR[(Scraper)]:::svc
            FE[(الواجهة الأمامية)]:::svc
        end

    subgraph "خدمة API"
    direction LR
    C(طبقة المتحكمات)
    S(طبقة الخدمات والمنطق)
    Q(قائمة الانتظار Horizon)
    end

    subgraph "الاعتماديات التابعة"
    AIB[(AI-Box)]:::svc
    OS[(OpenSearch)]:::store
    PG[(PostgreSQL)]:::store
    end

    SCR -- "POST /v1/ingest/articles" --> C
    FE -- "استعلامات GraphQL" --> C
    C --> S
    S -- "كتابة البيانات" --> PG
    S -- "فهرسة البيانات" --> OS
    S -- "إرسال مهمة" --> Q
    Q -- "معالجة المهمة" --> AIB

5. عملية النشر القياسية¶

توضح قائمة التحقق هذه الإجراء القياسي لنشر خدمة API. تضمن هذه العملية الاتساق وتقليل وقت التوقف.

1. الدخول في وضع الصيانة (في بيئة الإنتاج): منع المستخدمين من الوصول إلى الخدمة أثناء النشر.

   docker compose exec api php artisan down
   

2. سحب آخر تحديثات الشيفرة البرمجية:

   git pull origin main
   

3. تثبيت الاعتماديات: تثبيت اعتماديات PHP باستخدام Composer.

   docker compose exec api composer install --no-dev --optimize-autoloader
   

4. تشغيل ترحيلات قاعدة البيانات: تطبيق أي تغييرات جديدة على مخطط قاعدة البيانات.

   docker compose exec api php artisan migrate --force
   

5. مسح وتخزين التكوين مؤقتًا: ضمان تحميل التطبيق للتكوين والمسارات الجديدة.

   docker compose exec api php artisan config:cache
   docker compose exec api php artisan route:cache
   

6. إعادة تشغيل عمال قائمة الانتظار: يضمن هذا أن العمال في الخلفية يقومون بتشغيل الشيفرة البرمجية الجديدة.

   docker compose exec api php artisan horizon:terminate
   

7. الخروج من وضع الصيانة: إتاحة التطبيق للمستخدمين مرة أخرى.

   docker compose exec api php artisan up
   

6. العمليات الروتينية والصيانة¶

• التحقق من حالة Horizon: docker compose exec api php artisan horizon:status
• مسح المهام الفاشلة: docker compose exec api php artisan horizon:forget-failed
• تشغيل الاختبارات: docker compose exec api php artisan test
• فتح طرفية Tinker: docker compose exec api php artisan tinker

7. أدلة تشغيل منظمة للحوادث¶

يوفر هذا القسم روابط مباشرة إلى دفاتر تشغيل مفصلة للحوادث التشغيلية الشائعة التي تؤثر على خدمة API.