عن المشروع

مشروع Matcha Restock Alert هو مشروع أتمتة صغير يراقب كل منتجات الماتشا في متجر Marukyu-Koyamaen الدولي ويرسل بريدًا إلكترونيًا عندما ينتقل منتج من حالة نفاد المخزون إلى حالة التوفر. وبما أن المتجر يعيد التخزين عشوائيًا دون الإعلان عن جدول زمني، يعمل المشروع في السحابة على مدار الساعة بحيث يمكن إيقاف تشغيل حاسوبك الخاص. طريقة العمل: تستدعي خدمة pinger خارجية مجانية (cron-job.org) سير عمل GitHub Actions كل خمس دقائق عبر واجهة workflow_dispatch API. يشغّل سير العمل الملف matcha_monitor.py، الذي يزور كل صفحة منتج ويبحث عن رسالة المتجر نفسها التي تفيد بأنه "غير متوفر حاليًا وغير متاح"؛ ويعني عدم وجود الرسالة أن المنتج قابل للشراء. يخزّن السكربت آخر حالة لكل منتج في state.json، ويُعاد commit به إلى المستودع بعد كل تشغيل، ولا يرسل بريدًا إلكترونيًا إلا عند إعادة تخزين شيء حديثًا، مما يتجنب الرسائل المتكررة المزعجة. إذا فشل إرسال بريد إلكتروني، تتم إعادة محاولة التنبيه في التشغيل التالي. حرصًا على عدم إرهاق المتجر، يقتصر كل تشغيل كل خمس دقائق على إعادة فحص العناصر النافدة حاليًا، مع مسح شامل مرة واحدة كل ساعة لاكتشاف حالات النفاد الجديدة. تُفصل الطلبات بفاصل زمني مدته ثانيتان وتستخدم هوية متصفح عادية. يفحص السكربت أيضًا الكتالوج بحثًا عن منتجات ماتشا جديدة تمامًا، ويراقبها تلقائيًا، ويرسل بريدًا إلكترونيًا عند ظهورها. ويُحتفظ بجدولة cron */30 الخاصة بسير العمل كنسخة احتياطية فقط لأن cron من GitHub يتعرض لاختناق شديد عمليًا. يتطلب الإعداد كلمة مرور تطبيق Gmail، وأسرار مستودع لاسم مستخدم SMTP وكلمة المرور والمستلم، ورمز GitHub token دقيق الصلاحيات مقصورًا على المستودع مع إذن قراءة/كتابة Actions، ويتم ضبطه على cron-job.org كمهمة POST مع نص JSON. وتشغيل اختباري يُرجع 204 يؤكد أنه يعمل، كما يتحقق تشغيل test-email عبر workflow dispatch من التسليم. توجد قائمة المراقبة في products.json وتضم حوالي 50 منتج ماتشا؛ ويمكن إضافة عناصر أو إزالتها أو إيقافها مؤقتًا باستخدام "watch": false. تُخزَّن المنتجات المكتشفة تلقائيًا في state.json ويمكن إيقافها مؤقتًا بالطريقة نفسها. الملفات الأساسية هي matcha_monitor.py (أداة الفحص والمرسِل البريدي، ويمكن تشغيله محليًا أيضًا باستخدام --force) وproducts.json وstate.json وملف سير عمل GitHub Actions. ملاحظات: يثني المتجر عن الجمع العدواني للبيانات، وقد تمنع حماية الروبوتات لديه الطلبات. يكشف السكربت صفحات الحظر أو التحقق ولا يعتبرها أبدًا حالة توفر في المخزون؛ وتُعاد الفحوصات المحظورة ببساطة في التشغيل التالي. يقتصر شراء الماتشا على خمسة عناصر لكل طلب، ويرفض المتجر الطلبات التي يعتقد أنها بغرض إعادة البيع.