M13 F2.3 · Playground Crawler

Playground Crawler

حين يقصر crawl من جهة العميل — Chromium من جهة الخادم لفحص DOM واكتشاف patterns ومراجعة لقطات الشاشة.

متى تحتاجه

Client-side crawl لا يكفي

SPA ثقيل بـ JS، late mount، محتوى ديناميكي، shadow DOM — هنا يتدخل Chromium من جهة الخادم.

  • SPA ثقيل بـ JS

    تطبيقات React/Vue/Angular أحادية الصفحة — عندما يُعرَض الـ DOM بالكامل عبر JS.

  • Late mount

    HTML الأولي فارغ؛ المحتوى الحقيقي يُحمَّل بعد 2-5 ثوانٍ — Chromium يستطيع الانتظار.

  • DOM يُحمَّل ديناميكياً

    Scroll + click + lazy load — عناصر تحتاج تفاعلاً برمجياً لتظهر.

  • Shadow DOM

    الوصول من جهة العميل إلى shadow root لـ web component محدود؛ Chromium من جهة الخادم يستطيع اختراقه.

3 أوضاع crawl

Single · Multi · لقطة شاشة فقط

ثلاثة أوضاع بحسب الحاجة. Multi-page يسحب قوائم URL ديناميكية من CH events_canonical.

single_page

single_page

أعطِ URL واحداً → فحص DOM + اكتشاف pattern + لقطة شاشة. أسرع وضع — مثالي لمعاينة playground.

multi_page

multi_page

CH events_canonical آخر 7 أيام distinct source_context['context_url'] → crawl متعدد الصفحات. يبحث عن نفس الـ pattern عبر الصفحات (إجمالي العدد).

screenshot_only

screenshot_only

لقطة كاملة + viewport بلا فحص DOM. للـ UX review / regression.

مولّد selector بـ 6 استراتيجيات

Selectors متعددة الطبقات للـ auto-healing fail-safe

كل event يحصل على 6 أنواع selector — إذا انكسرت واحدة، تحلّ التالية محلها (5 طبقات fallback healing).

لماذا 6 طبقات؟

إعادة تصميم الواجهة قد تكسر CSS classes أو ARIA labels أو النصوص. ما لم تنكسر الـ 6 دفعة واحدة، يستمر تتبّع الأحداث.

  • dataAttrخاصية data-* — الأكثر استقراراً (تُضاف يدوياً، يتحكم بها المطور)
  • textالنص الظاهر — قد ينكسر مع تغييرات i18n
  • cssCSS class / id — مخاطرة أثناء refactor الـ classes
  • xpathتعبير XPath — يعتمد على هرمية DOM
  • regexمطابقة regex على السمات — مبنية على patterns
  • ariaARIA role + label — بدرجة accessibility، مستقر نسبياً
// 6 strateji, en spesifikten en gevşeğe doğru
{
  "selectors": [
    { "type": "data_attr", "value": "[data-testid='cart-add']" },
    { "type": "aria",      "value": "[role='button'][aria-label='Sepete ekle']" },
    { "type": "text",      "value": "button:has-text('Sepete ekle')" },
    { "type": "css",       "value": ".product-card .add-to-cart" },
    { "type": "xpath",     "value": "//button[contains(., 'Sepete ekle')]" },
    { "type": "regex",     "value": "button[name=~'add.cart']" }
  ]
}

اكتشاف Patterns

1,248 زر سلة → event واحد

تجميع تلقائي للعناصر المتكررة بنفس التصميم — تعريف event واحد يغطي كل الصفحات.

كيف يجمّع؟

تجميع بـ selector + بنية DOM المجاورة + تشابه accessible label. كل العناصر في cluster واحد تُربط بـ event واحد.

# Multi-page crawl → 1.248 add-to-cart noktası bulundu
gurulu playground crawl \
  --mode multi_page \
  --base https://shop.example.com \
  --discover ch_events_last_7d \
  --max-pages 200

# Sonuç: pattern grouping (eşleşen selector → tek event'e bağla)
# event:add_to_cart  →  matched 1.248 instances across 47 pages

مراجعة لقطات الشاشة

MinIO presigned + thumbnail

بعد crawl، تُكتَب لقطة كل صفحة إلى MinIO؛ يُعيد الـ API redirect 302 إلى URL presigned.

GET /v1/playground/crawl/{crawl_id}/screenshot
  → 302 redirect → MinIO presigned URL (15 dk TTL)

# Thumbnail (JPEG, dashboard list için)
GET /v1/playground/crawl/{crawl_id}/screenshot?variant=thumb

التحكم بالوصول

تُعاد URLs presigned بـ TTL مدته 15 دقيقة — يُفحَص إذن workspace أولاً، ثم إعادة توجيه إلى bucket في MinIO. صور dashboard المصغّرة بصيغة JPEG.

تهيئة الأداء

Browser pool 2، timeout 30s، shm 1gb

قطاع SHM لـ Chromium 1 GB — قيمة Docker الافتراضية لـ shm_size 64 MB لن تعمل، يجب تجاوزها.

الإعداد
الافتراضي
ملاحظة
حجم Browser pool
2
نُسخ Chromium المتزامنة — 2 مستقر؛ أكثر يستهلك RAM.
Page timeout
30 s
يفشل بعد 30s إن لم يكن DOM جاهزاً. كافٍ لـ SPAs.
shm_size
1 GB
Docker SHM 1 GB — يمنع انهيار Chromium. الافتراضي 64 MB لن يعمل.
تزامن Jobs
1 job / worker
Job واحد لكل worker — يحد من مخاطر تسرب ذاكرة Chromium.

حالات الاستخدام

Onboarding + اكتشاف

سيناريوهان نموذجيان — إعداد workspace جديد، واكتشاف patterns جديدة في workspace قائم.

Playground الـ onboarding

إعداد workspace جديد: استخدم زر 'scan multi-page' من قائمة sessions لاكتشاف patterns عبر كل الصفحات وإنشاء events دفعة واحدة.

اكتشاف Patterns

في workspace قائم بعد الإطلاق — شغّل multi-page crawl من الـ playground لإيجاد عناصر جديدة وإضافتها إلى event registry.

وثائق ذات صلة

اقرأ بعد ذلك

ابنِ جماهير من patterns، شاهد patterns تظهر في ملخص الـ AI، تعلّم المعمارية.

الجماهير — cohort + audience من patternالملخص الصباحي — تفسيرات الـ anomalyHow it works — معمارية Truth Layerفهرس الوثائق
Playground Crawler — وثائق Gurulu