دليل مستخدم Cat-Scan¶

المشكلة في صورة واحدة¶

قمع QPS

يرسل Google لمزايدك سيلاً من طلبات المزايدة. في كل ثانية، تتدفق عشرات الآلاف من الاستعلامات من بورصة Authorized Buyers نحو نقطة الاتصال الخاصة بك. يقيّم مزايدك كل طلب، ويقرر ما إذا كان سيزايد عليه، ثم يستجيب — كل ذلك في غضون بضعة أجزاء من الألف من الثانية.

هنا ما يغفل عنه معظم الناس: الغالبية العظمى من هذه الإشارات هي مجرد ضوضاء. مقعد نموذجي يستقبل 50,000 QPS قد يجد أن 30,000 من تلك الاستعلامات تخص مخزوناً لم يكن المشتري الإعلامي لينفق عليه أبداً: مواقع جغرافية خاطئة، نطاقات ناشرين غير ذات صلة، أحجام إعلانية لا تتطابق مع أي تصميم إبداعي. ومع ذلك، يتعين على مزايدك استقبال كل طلب وتحليله ورفضه. وهذا يكلف نطاقاً ترددياً وحوسبة وأموالاً.

يُظهر الرسم البياني أعلاه ذلك كهطول المطر. QPS من Google هو الفوهة في الأعلى؛ والقطرات تنتشر على مساحة واسعة. مزايدك هو الدلو الصغير في الأسفل. كل ما يخطئ الدلو (القطرات التي تسقط يميناً ويساراً) هو هدر. لقد دفعت ثمنه ولم تحصل على شيء في المقابل.

Cat-Scan موجود ليجعل الدلو أوسع والمطر أضيق.

يحقق ذلك من خلال منحك رؤية واضحة لأماكن حدوث الهدر (أي المناطق الجغرافية، أي الناشرين، أي أحجام الإعلانات، أي التصاميم الإبداعية) والأدوات اللازمة لإيقافه من المصدر، باستخدام إعدادات الاستهداف المسبق التي يوفرها Google.

لماذا هذا أصعب مما يبدو¶

يمنحك Google Authorized Buyers 10 إعدادات استهداف مسبق فقط لكل مقعد، بالإضافة إلى تقسيمات جغرافية تقريبية (شرق الولايات المتحدة، غرب الولايات المتحدة، أوروبا، آسيا). لا توجد API للتقارير. جميع بيانات الأداء تأتي من تصديرات CSV تصل عبر البريد الإلكتروني. واجهة الاستهداف المسبق في AB نفسها عملية لكنها تجعل من الصعب رؤية الصورة الكاملة عبر الإعدادات، أو التراجع عن تغيير لم يسر كما هو مطلوب.

Cat-Scan يسد هذه الثغرات:

يقوم بإعادة بناء التقارير من تصديرات CSV (رفع يدوي أو استيراد تلقائي من Gmail)، مع إزالة التكرارات عند الاستيراد بحيث لا تحدث عملية إعادة المعالجة عدّاً مزدوجاً أبداً.
يعرض قمع RTB الكامل، من QPS الخام مروراً بالمزايدات والفوز ومرات الظهور والنقرات والإنفاق، مقسّماً حسب أي بُعد: المنطقة الجغرافية، الناشر، حجم الإعلان، التصميم الإبداعي، الإعداد.
يوفر إدارة آمنة للاستهداف المسبق مع سجل التغييرات والتعديلات المرحلية ومعاينة التشغيل التجريبي والتراجع بنقرة واحدة.
يشغّل محسّناً يقيّم الشرائح ويقترح تغييرات على الإعدادات، مع حواجز حماية لسير العمل (آمن / متوازن / جريء) بحيث لا يُنفَّذ أي تغيير دون مراجعة.

لمن هذا الدليل¶

هذا الدليل له مساران لأن Cat-Scan يخدم دورين مختلفين تماماً:

مشترو الوسائط ومديرو الحملات يستخدمون Cat-Scan لفهم أين تذهب ميزانيتهم، وإيجاد الهدر، وإدارة التصاميم الإبداعية، وضبط الاستهداف المسبق، والموافقة على مقترحات التحسين. يفكرون بمصطلحات CPM ومعدلات الفوز وROAS. تركز فصولهم على ما تعرضه واجهة المستخدم، وماذا تعني الأرقام، وما الإجراءات التي يجب اتخاذها.

مهندسو DevOps ومهندسو المنصات يستخدمون Cat-Scan للنشر والمراقبة واستكشاف الأخطاء وإصلاحها. يفكرون بمصطلحات الحاويات ونقاط الفحص الصحي وخطط الاستعلامات. تركز فصولهم على البنية التحتية وخطوط أنابيب النشر وعمليات قواعد البيانات وأدلة التعامل مع الحوادث.

يتشارك المساران أساساً مشتركاً (البدء، المسرد) وتتقاطع الفصول مع بعضها البعض حيث تتداخل مسارات العمل. مشتري وسائط يبلغ عن "تحديث البيانات معطّل" ومهندس DevOps يحقق في الاستعلام الذي يقف وراءه يجب أن يتمكنا من الإشارة إلى نفس مدخلة المسرد وفهم بعضهما البعض.

كيف تقرأ هذا الدليل¶

الجزء 0 للجميع. ابدأ من هنا.
الجزء الأول هو مسار مشتري الوسائط. إذا كنت تعمل في الحملات أو التحسين أو الشراء، فهذا هو مسارك.
الجزء الثاني هو مسار DevOps. إذا كنت تنشر أو تراقب أو تدير Cat-Scan، فهذا هو مسارك.
الجزء الثالث هو مرجع مشترك: المسرد والأسئلة الشائعة وفهرس API.

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

جدول المحتويات¶

الجزء 0: البدء¶

الجميع يقرأ هذا.

الفصل 0: ما هو Cat-Scan؟ ماذا تفعل المنصة، ولمن هي، والمفاهيم الأساسية التي تحتاجها قبل أي شيء آخر: المقاعد، QPS، الاستهداف المسبق، قمع RTB.
الفصل 1: تسجيل الدخول طرق المصادقة (Google OAuth، الحسابات المحلية)، صفحة تسجيل الدخول، ماذا تفعل عند فشل تسجيل الدخول، وكيف يعمل محدد المقعد.
الفصل 2: التنقل في لوحة التحكم الشريط الجانبي، تبديل المقعد، محدد اللغة، قائمة الإعداد للحسابات الجديدة، وكيف يتم تنظيم الصفحات.

الجزء الأول: مسار مشتري الوسائط¶

لمشتري الوسائط ومديري الحملات ومهندسي التحسين.

الفصل 3: فهم قمع QPS الخاص بك الصفحة الرئيسية. كيف تقرأ تحليل القمع: مرات الظهور، المزايدات، الفوز، الإنفاق، معدل الفوز، CTR، CPM. ماذا يعني "الهدر" بمصطلحات ملموسة. بطاقات الإعداد وما تتحكم به حقولها.
الفصل 4: تحليل الهدر حسب البُعد عروض تحليل الهدر الثلاثة ومتى تستخدم كلاً منها:
الجغرافي (/qps/geo): أي البلدان والمدن تستهلك QPS دون تحويل.
الناشر (/qps/publisher): أي النطاقات والتطبيقات ذات الأداء الضعيف.
الحجم (/qps/size): أي أحجام الإعلانات تستقبل حركة مرور لكن ليس لديها تصاميم إبداعية مطابقة. يرسل Google حوالي 400 حجم مختلف؛ معظمها غير ذي صلة بالإعلانات المصورة ذات الحجم الثابت.
الفصل 5: إدارة التصاميم الإبداعية معرض التصاميم الإبداعية (/creatives): التصفح حسب التنسيق، التصفية حسب مستوى الأداء، البحث بالمعرّف. الصور المصغرة، شارات التنسيق، تشخيصات الوجهة. تجميع الحملات (/campaigns): السحب والإفلات، التجميع التلقائي بالذكاء الاصطناعي، مجموعة غير المعيّنين.
الفصل 6: إعداد الاستهداف المسبق ما يتحكم به إعداد الاستهداف المسبق (المناطق الجغرافية، الأحجام، التنسيقات، المنصات، الحد الأقصى لـ QPS). كيف تقرأ بطاقة الإعداد. تطبيق التغييرات مع معاينة التشغيل التجريبي. الجدول الزمني لسجل التغييرات (/history). التراجع: كيف يعمل، لماذا موجود، ومتى تستخدمه.
الفصل 7: المحسّن (BYOM) أحضر نموذجك الخاص: تسجيل نقطة تقييم خارجية، التحقق منها، تفعيلها. دورة حياة التقييم-الاقتراح-الموافقة-التطبيق. إعدادات سير العمل المسبقة: آمن، متوازن، جريء. الاقتصاديات: CPM الفعلي، خط أساس تكلفة الاستضافة، ملخص الكفاءة. كيف يبدو المقترح وكيف تقيّمه.
الفصل 8: التحويلات والإسناد ربط مصدر تحويل. تكامل البكسل. إعداد Webhook: توقيعات HMAC، المفاتيح المشتركة، تحديد المعدل. فحوصات الجاهزية. إحصائيات الاستيعاب. ماذا تعني "صحة التحويل" وكيف تقرأ صفحة حالة الأمان.
الفصل 9: استيراد البيانات كيف تدخل البيانات إلى Cat-Scan، ولماذا هذا مهم. رفع CSV يدوي (/import): السحب والإفلات، تعيين الأعمدة، التحقق، الرفع المجزّأ للملفات الكبيرة. الاستيراد التلقائي من Gmail: كيف يعمل، كيف تتحقق من الحالة، ماذا يحدث عند فشله. شبكة تحديث البيانات: ماذا تعني "مستورد" مقابل "مفقود" لكل تاريخ ونوع تقرير. ضمانات إزالة التكرارات.
الفصل 10: قراءة تقاريرك إحصائيات الإنفاق، لوحات أداء الإعدادات، مقاييس كفاءة نقطة الاتصال. كيف تفسر الاتجاهات. ماذا يظهر التحليل اليومي. مقارنات اللقطات: قبل وبعد تغيير الاستهداف المسبق.

الجزء الثاني: مسار DevOps¶

لمهندسي المنصات ومهندسي موثوقية المواقع ومديري الأنظمة.

الفصل 11: نظرة عامة على البنية التحتية طبولوجيا النظام: واجهة خلفية FastAPI، واجهة أمامية Next.js 14، Postgres (Cloud SQL)، BigQuery. لماذا توجد قاعدتا بيانات (التكلفة، زمن الاستجابة، التجميع المسبق، إدارة الاتصالات). تخطيط الحاويات: api، dashboard، oauth2-proxy، cloudsql-proxy، nginx. سلسلة ثقة المصادقة: OAuth2 Proxy يضبط X-Email، nginx يمرره، API يثق به.
الفصل 12: النشر خط أنابيب CI/CD: GitHub Actions build-and-push.yml يبني الصور عند الدفع؛ deploy.yml يعمل بتفعيل يدوي فقط (مع تأكيد DEPLOY). علامات صور Artifact Registry (sha-XXXXXXX). تسلسل النشر: git pull على الخادم، docker compose pull، إعادة إنشاء، تنظيف. التحقق بعد النشر: فحص صحي، فحص العقد. لماذا النشر التلقائي معطّل (حادثة يناير 2026). كيف تتحقق من نشر: curl /api/health | jq .git_sha.
الفصل 13: مراقبة الصحة والتشخيص نقاط الفحص الصحي: /api/health (فحص الحياة)، /system/data-health (اكتمال البيانات). صفحة حالة النظام (/settings/system): Python، Node، FFmpeg، قاعدة البيانات، القرص، الصور المصغرة. سكريبتات الصحة أثناء التشغيل: diagnose_v1_buyer_report_coverage.sh، run_v1_runtime_health_strict_dispatch.sh. مصادقة الكناري: CATSCAN_CANARY_EMAIL، CATSCAN_BEARER_TOKEN. سير عمل CI: v1-runtime-health-strict.yml وماذا تعني PASS/FAIL/BLOCKED.
الفصل 14: عمليات قاعدة البيانات Postgres فقط في الإنتاج. Cloud SQL عبر حاوية proxy. الجداول الرئيسية وحجمها: rtb_daily (~84 مليون صف)، rtb_bidstream (~21 مليون صف)، rtb_quality، rtb_bid_filtering. الفهارس الحرجة: (buyer_account_id, metric_date DESC). نموذج الاتصال: لكل طلب (بدون مجمّع)، run_in_executor للعمليات غير المتزامنة. مهلات الجمل (SET LOCAL statement_timeout). إعدادات الاحتفاظ بالبيانات. دور BigQuery: مستودع دفعي للبيانات الخام؛ Postgres يقدم البيانات المجمّعة مسبقاً للتطبيق.
الفصل 15: دليل استكشاف الأخطاء وإصلاحها أنماط الفشل المعروفة وكيفية حلها:
حلقة تسجيل الدخول: Cloud SQL Proxy متوقف، _get_or_create_oauth2_user يفشل بصمت، /auth/check يعيد {authenticated:false}، حلقة إعادة توجيه الواجهة الأمامية. الإصلاح ثلاثي الطبقات. كيفية الكشف: عداد إعادة التوجيه في المتصفح، 503 من /auth/check.
مهلة تحديث البيانات: الجداول الكبيرة تقوم بمسح تسلسلي بدلاً من استخدام الفهارس. الأعراض: /uploads/data-freshness تنتهي مهلته أو يعيد
1. التشخيص: pg_stat_activity، EXPLAIN ANALYZE. نمط الإصلاح: generate_series + EXISTS.
فشل استيراد Gmail: /gmail/status يعرض خطأ. تحقق من حاوية Cloud SQL Proxy. تحقق من عدد الرسائل غير المقروءة.
ترتيب إعادة تشغيل الحاويات: cloudsql-proxy يجب أن يكون سليماً قبل أن يبدأ api. علامات الترتيب الخاطئ: رفض الاتصال في سجلات API.
الفصل 16: إدارة المستخدمين والصلاحيات لوحة الإدارة (/admin): إنشاء المستخدمين (محلي وإنشاء مسبق لـ OAuth)، إدارة الأدوار، الصلاحيات لكل مقعد. حسابات الخدمة: رفع ملف اعتماد GCP بصيغة JSON، ما يفتحه (اكتشاف المقاعد، مزامنة الاستهداف المسبق). المستخدمون المقيّدون: ما يرونه وما هو مخفي. سجل التدقيق: ما الإجراءات التي يتم تتبعها، كيفية التصفية، فترة الاحتفاظ.
الفصل 17: التكاملات حسابات خدمة GCP واتصال المشروع. Google Authorized Buyers API: اكتشاف المقاعد، مزامنة إعدادات الاستهداف المسبق، مزامنة نقاط اتصال RTB. تكامل Gmail: OAuth2 لاستيراد التقارير تلقائياً. مزودو الذكاء الاصطناعي اللغوي: Gemini، Claude، Grok (لاكتشاف لغة التصميم الإبداعي وتنبيهات عدم التطابق). خطافات التحويل: تسجيل نقطة الاتصال، التحقق من HMAC، تحديد المعدل، مراقبة التحديث.

الجزء الثالث: المرجع¶

مشترك بين المسارين.

المسرد كل مصطلح بمنظورين. عمود مشتري الوسائط: "الاستهداف المسبق" هو "القواعد التي تتحكم في أي طلبات مزايدة تصل إلى مزايدك." عمود DevOps: "الاستهداف المسبق" هو "كيان قابل للتعديل يتم مزامنته من AB API، مخزّن في pretargeting_configs، متاح عبر /settings/pretargeting." كلاهما يحتاج نفس الكلمة؛ ولا أحد منهما يستخدم تعريف الآخر.
الأسئلة الشائعة مصنّفة حسب الجمهور. أسئلة يطرحها مشتري الوسائط ("لماذا تغطيتي 74%؟") بجانب أسئلة يطرحها مهندس DevOps ("لماذا فشلت بوابة فحص الصحة الصارم أثناء التشغيل؟"). الإجابات تربط بالفصل ذي الصلة.
مرجع API السريع جميع نقاط الاتصال الـ 118+ مجمّعة حسب المجال: الأساسي، المقاعد، التصاميم الإبداعية، الحملات، التحليلات، الإعدادات، الإدارة، المحسّن، التحويلات، التكاملات، الرفع، اللقطات، المصادقة. الطريقة، المسار، المعاملات الرئيسية، وما يعيده. ليس بديلاً عن مواصفات OpenAPI على /api/docs، لكنه فهرس قابل للتصفح.