مزامنة حالة قطع المرحلة 11 — دليل التشغيل

هذا المجلد فيه كل حاجة محتاجها عشان موقعك يعرض حالة "متاح / تم التخصيص" تلقائيًا، ويبعتلك تنبيه تليجرام كل ما قطعة تتحجز.

الفكرة باختصار

كل 5 دقايق (GitHub Actions):
  scraper.py يفحص موقع الهيئة العلني  →  status.json يتحدث
       →  telegram_notify.py يبعت تنبيه لو فيه حجز جديد
       →  status.json يترفع تلقائي على GitHub
       →  موقعك (المستضاف على Vercel/GitHub Pages) يقرا الملف الجديد
          في أول تحميل صفحة — من غير أي تدخل منك

الملفات اللي هنا

الملف	وظيفته
scraper.py	يكتشف كل مناطق المرحلة 11 ويجيب حالة كل قطعة
telegram_notify.py	يبعت تنبيه تليجرام للحجوزات الجديدة بس
requirements.txt	المكتبات اللي السكريبت محتاجها
.github/workflows/sync-status.yml	الجدولة التلقائية على GitHub

خطوات التشغيل

1. جهّز المستودع (Repo) على GitHub

1. اعمل مستودع جديد — مثلاً phase11-sync — واخليه Public. دقايق تشغيل GitHub Actions بتبقى بلا حد لو المستودع عام، بدل 2000 دقيقة/الشهر بس لو خاص، وده ضروري عشان الجدولة كل 5 دقايق (فيه أكتر من 8,000 تشغيلة في الشهر). الأسرار (Telegram token) بتفضل مخفية تمامًا حتى لو المستودع عام.
2. ارفع فيه:
   • محتويات المجلد ده (scraper.py, telegram_notify.py, requirements.txt, ومجلد .github/)
   • ملف الموقع (مستشارك_العقاري_أحمد_جاب_الله.html) وlogo.png
   • ملف status.json الفاضي اللي بعتهولك قبل كده (نقطة البداية)

كل الملفات دي في نفس المستودع، في نفس المجلد الرئيسي (Root) — الموقع محتاج يقرا status.json وlogo.png من نفس المسار اللي هو فيه.

2. سجّل الـ Secrets بتاعة تليجرام

في المستودع على GitHub: Settings → Secrets and variables → Actions → New repository secret

أضف اتنين:

• TELEGRAM_BOT_TOKEN — التوكن اللي أخدته من BotFather
• TELEGRAM_CHAT_ID — يوزر نيم القناة بتاعتك (مثلاً @my_channel) أو الـ ID الرقمي لو القناة خاصة

تأكد إن البوت نفسه مضاف كـ Admin في القناة، وإلا مش هيقدر يبعت رسائل فيها.

3. شغّل تجربة يدوية الأول (مهم جدًا)

قبل ما تسيب الجدولة تشتغل لوحدها:

1. روح لتبويب Actions في المستودع

2. اختار "Sync Phase 11 plot status"

3. دوس Run workflow (تشغيل يدوي)

4. تابع الـ logs وشوف:

   • كام Zone اتلقى ([discover] found N zone(s))
   • كام قطعة اتقرت (X plot rows read)
   • كام قطعة طلعت محجوزة

5. افتح status.json اللي اتحدث وقارن 3-4 قطع منه يدويًا مع موقع الهيئة نفسه — ده أهم خطوة، عشان تتأكد إن القراءة صحيحة قبل ما تثق في التنبيهات الأوتوماتيك.

لو النتايج غريبة (صفر قطع محجوزة في مدينة كبيرة، أو أرقام مش منطقية)، ابعتلي الـ log وهنصلح المشكلة قبل ما نفعّل الجدولة.

4. فعّل الجدولة

لو التجربة اليدوية طلعت صح، مفيش حاجة تانية تعملها — الملف sync-status.yml هيشتغل لوحده كل 5 دقايق تلقائيًا. السكريبت بقى يفحص 6 مناطق في نفس الوقت (بدل واحدة ورا التانية) عشان الفحصة الكاملة تخلص في 2-4 دقايق تقريبًا، وتلحق تبدأ تاني قبل الموعد التالي.

ده وتيرة سريعة نسبيًا على سيرفر حكومي، فراقب أول يوم أو اتنين بانتباه:

• لو شفت في الـ logs أخطاء زي timeout أو connection error أو رقم 429 بيتكرر، ده الموقع بيقولك "قللوا الضغط". في الحالة دي:
  • افتح .github/workflows/sync-status.yml وغيّر */5 * * * * لـ */15 * * * * (كل 15 دقيقة) كخطوة أولى
  • أو قلل --workers من 6 لـ 3 في خطوة "Run scraper" بملف الـ workflow
• لو كل حاجة شغالة نضيف من غير أخطاء لمدة أسبوع، تقدر تسيبها زي ما هي بضمير مرتاح

لو عايز تقلّل الوتيرة بعدين، عدّل نفس السطر:

cron: "*/5 * * * *"

لأي حاجة تانية، زي */15 * * * * (كل 15 دقيقة) أو */30 * * * * (كل نص ساعة) — الأرقام اللي بعد */ هي عدد الدقايق.

5. اربط الموقع بـ Vercel (لو لسه مش مربوط)

1. سجّل دخول على vercel.com بحساب GitHub بتاعك
2. Add New → Project واختار المستودع
3. Vercel هيكتشف إنه مجلد ملفات ثابتة (Static) ويرفعه على طول
4. كل مرة GitHub Action يحدّث status.json ويعمله push، Vercel هيعيد النشر تلقائيًا خلال ثواني

نقطة أمانة مهمة

السكريبت ده بيقرا من موقع عام لكنه مش API رسمي من الهيئة. لو غيّروا شكل الموقع في يوم من الأيام، السكريبت ممكن يوقف عن الشغل أو يديك بيانات غلط. راقب أول أسبوعين بانتظام، ولو حصل أي تغيير غير متوقع في الأرقام (زيادة أو نقصان مفاجئ كبير في عدد المحجوزين) وقف الجدولة وراجع الموقع يدويًا الأول.

استكشاف الأخطاء

• الجدولة مش بتشتغل: تأكد إن permissions: contents: write موجودة في أول الملف (موجودة بالفعل هنا)، وإن الـ repo مش Fork (الـ Forks بتلاقي صلاحيات الكتابة مقفولة افتراضيًا على GitHub)
• تليجرام مش بيبعت: تأكد إن البوت Admin في القناة، وإن TELEGRAM_CHAT_ID مكتوب صح (لازم يبدأ بـ @ لو يوزر نيم قناة عامة)
• status.json مش بيتحدث في الموقع: امسح الكاش (Ctrl+Shift+R) — المتصفح أحيانًا بيكاش الملف القديم