Study Bot Maker — Python

هذه نسخة Python كاملة من بوت Study Bot Maker. البوت يعمل على Telegram عبر polling سريع مع إعادة اتصال تلقائية، ويدعم معالجة متوازية للمحادثات المختلفة مع الحفاظ على ترتيب الحالة داخل كل محادثة. يتيح اختيار قالب مذاكرة، تحديد وقت ومدة الجلسة، إضافة المهام، إرسال بطاقة منسقة، متابعة الإحصائيات، وإرسال تذكير عند انتهاء الجلسة. يحتوي الآن على 90 قالبًا في 10 أقسام، وجميع البطاقات تستخدم تسلسلًا بصريًا موحدًا بخط italic، Quote عربي قصير، ودعاء مذاكرة أسفل البطاقة، بالإضافة إلى عداد حي للوقت المتبقي.

التشغيل على Railway أو محليًا

أنشئ خدمة Railway من مستودع GitHub أو شغّل محتويات هذا المجلد محليًا. اجعل الملف الرئيسي:

main.py

عند النشر باستخدام Dockerfile اترك حقل Start Command فارغًا حتى يستخدم Railway ENTRYPOINT الموجود في الصورة ويهيئ Volume ثم يشغّل البوت بالمستخدم غير الجذري. للتشغيل المحلي استخدم:

python main.py

أضف متغيرات البيئة التالية من Settings:

المتغير	القيمة
TELEGRAM_BOT_TOKEN	توكن البوت من BotFather
PORT	المنفذ الذي توفره المنصة، أو 3000 محليًا
DATABASE_PATH	اختياري، والقيمة الافتراضية study_bot.sqlite3
MAX_TASKS	اختياري، الحد الأقصى للمهام، الافتراضي 20
MAX_TASK_CHARS	اختياري، طول المهمة، الافتراضي 180
MAX_SESSION_MINUTES	اختياري، أقصى مدة جلسة بالدقائق، الافتراضي 720
CLOCK_OFFSET_MINUTES	اختياري، تصحيح يدوي بالدقائق لو ساعة السيرفر الفعلية متأخرة أو متقدمة عن الوقت الحقيقي (مش مشكلة توقيت زمني/DST، دي مشكلة ساعة النظام نفسها). مثال: لو البوت بيطلع الوقت متأخر 7 دقايق عن الواقع، ضع 7. لو متقدم، ضع رقم سالب مثل -7. الافتراضي 0
UPDATE_CONCURRENCY	اختياري، عدد التحديثات المختلفة التي يمكن معالجتها بالتوازي، من 1 إلى 32، الافتراضي 8
CONNECTION_POOL_SIZE	اختياري، عدد اتصالات Telegram المتاحة، من 1 إلى 64، الافتراضي 16
POOL_TIMEOUT_SECONDS	اختياري، أقصى انتظار لاتصال Telegram، من 1 إلى 30 ثانية، الافتراضي 5
TIMER_UPDATE_SECONDS	اختياري، فترة تحديث العداد الحي، من 0.5 إلى 60 ثانية، الافتراضي 1
MOTIVATION_VIDEOS_ENABLED	اختياري، تفعيل إرسال فيديو تحفيزي بعد انتهاء الجلسة، الافتراضي true

يستخدم المشروع SQLite محليًا للحفظ الدائم على القرص، مع WAL وذاكرة مؤقتة سريعة وترحيل تلقائي لقاعدة البيانات القديمة. تم تفعيل SQLite statement cache وذاكرة temporary داخلية وفهرسة مناسبة، كما تُحفظ Telegram file_id في جدول media_cache حتى لا يعاد رفع الصور بعد إعادة تشغيل البوت. يسجل آخر الجلسات بدون حفظ نص المهام في سجل التاريخ، ويحتفظ بحد أقصى 200 جلسة لكل مستخدم. إذا كانت بيئة الاستضافة مؤقتة أو لا تحفظ الملفات بين عمليات النشر، سيستمر البوت في العمل لكن ستحتاج إلى Volume دائم أو قاعدة بيانات خارجية حتى لا تفقد البيانات.

لوحة المالك والإدارة

يفتح المالك لوحة الإدارة باستخدام الأمر /admin بعد وضع رقم حساب Telegram في OWNER_IDS. جميع أزرار الإدارة والتحكم محمية برقم المستخدم، وليست برقم الرسالة أو اسم المستخدم فقط. تعرض اللوحة حالة التشغيل وارتباط SQLite ومدة التشغيل وعدد الجلسات النشطة وعدد الأصول وأخطاء التخزين، كما تعرض إجمالي المستخدمين، الأعضاء الجدد خلال آخر 24 ساعة، النشطين، المحظورين، الجلسات والدقائق. يستطيع المالك فتح قائمة الأعضاء، مراجعة الأعضاء الجدد فورًا، البحث عن أي عضو بواسطة chat_id وعرض ملفه وإحصائياته وسجل نشاطه، حظر عضو أو فك حظره، بدء إذاعة في الخلفية مع تقرير نجاح وفشل، إيقاف الإذاعة الجارية، عرض سجلات آخر 10 دقائق، وإدارة الاشتراك الإجباري.

يمكن تفعيل الاشتراك الإجباري مبدئيًا من خلال FORCE_SUBSCRIPTION_CHANNELS=@channel_one,@channel_two. ويجب أن يكون البوت قادرًا على فحص عضوية المستخدمين في هذه القنوات، ويفضل أن يكون مشرفًا فيها. كما يستطيع المالك تغيير القنوات أو إيقاف الاشتراك الإجباري من زر الإدارة، وتُحفظ الإعدادات في SQLite حتى تستمر بعد إعادة التشغيل.

Telegram لا يسمح للبوت بفرض لون مخصص للأزرار من جهة Bot API؛ لون الزر يتبع ثيم تطبيق المستخدم. لذلك صُممت الواجهة بتقسيمات واضحة، رموز ملونة، عناوين عربية، وأزرار Inline منظمة لتقترب من الشكل المرجعي دون الاعتماد على لون غير مدعوم تقنيًا.

الجلسة والتقييم

يعرض كل كرت جلسة رقمًا يوميًا بصيغة English مثل Session #1 ثم Session #2 وSession #3. يحسب البوت الرقم من سجل الجلسات المكتملة في اليوم الحالي حسب توقيت القاهرة، لذلك يبدأ العد من 1 كل يوم جديد ويستمر مع كل جلسة مكتملة للمستخدم. يظهر عدد الجلسات اليومية أيضًا في شاشة البداية والإحصائيات.

بعد انتهاء مدة الجلسة يرسل البوت رسالة ودودة مثل «خلصت الجلسة يا سكر!» ويعرض أزرارًا لاختيار عدد المهام المنجزة من إجمالي المهام. بعد ذلك يطلب تقييم الجلسة من 1 إلى 10، ويرسل رسالة تشجيعية تختلف حسب نسبة الإنجاز والتقييم. لا يستطيع المستخدم بدء جلسة جديدة أثناء جلسة جارية أو أثناء تجهيز جلسة لم تكتمل؛ يتلقى بدلًا من ذلك رسالة لطيفة توضّح الوقت المتبقي أو الخطوة المطلوبة. يظل /cancel متاحًا لإلغاء التجهيز أو الجلسة بإرادة المستخدم. يظهر الدعاء في قسم مستقل بعنوان دعاء للمذاكرة أسفل كل بطاقة، والأدعية مخصصة للفهم والحفظ والتركيز وتنظيم الوقت والمراجعة والاختبارات، وليست أدعية عامة غير مرتبطة بالدراسة.

مشاركة المؤقت

المؤقت الحي في الرسالة الأصلية يستمر في التحديث داخل المحادثة الأصلية. عند مشاركة الرسالة خارج البوت، لا تسمح Telegram للبوت بتعديل النسخة المُعاد توجيهها؛ لذلك تحتوي البطاقة على زر 🔗 مشاركة المؤقت يفتح رابطًا للبوت ويحسب الوقت المتبقي من reminder_ends_at المحفوظ في SQLite. بهذه الطريقة يظل وقت النهاية قابلًا للاسترجاع حتى لو تم نشر البطاقة في محادثة أو مجموعة أخرى.

تصميمات البطاقات

تمت إزالة أسماء التصميمات من الرسائل والبطاقات والسجل حتى تظل الواجهة بسيطة. أصبحت البطاقات تعتمد على أربعة أساليب عرض متناوبة: بطاقة Study Timer كيوت، إطار Pomodoro، بطاقة Deep Focus، وبطاقة Focus Mode. في جميع الأساليب يأتي الـQuote قبل بيانات الوقت والمهام، ويظهر Session #N بالإنجليزية، ثم قسم مستقل بعنوان دعاء للمذاكرة.

صور القوالب

تحتوي مجلدات assets/templates/ وassets/user_images/ على مكتبة الصور. أضيفت 106 صور user مرفقة من المستخدم، وحُولت صور JFIF إلى JPG محسّن بأسماء ثابتة من user_001.jpg إلى user_106.jpg مع الحفاظ على محتوى الصور وتقليل حجمها المناسب للإرسال. يختار البوت صورة عشوائيًا من مكتبة الصور المتاحة في المعاينة وعند إرسال بطاقة الجلسة، ويمنع تكرار نفس الصورة مباشرةً للمحادثة نفسها. يتم رفع الصورة محليًا أول مرة فقط، ثم يحتفظ البوت بـTelegram file_id لكل صورة ويعيد استخدامه لتقليل زمن الإرسال واستهلاك الشبكة. ملف assets/user_images_manifest.json يحتفظ بربط كل صورة جديدة باسمها الأصلي.

يضم الكتالوج الحالي 90 قالبًا داخل 10 أقسام فقط، بحيث تم تجميع القوالب السابقة في مجموعات أكبر بدل تشتيت المستخدم بين أقسام كثيرة.

التشغيل المحلي

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export TELEGRAM_BOT_TOKEN="توكن_البوت"
export PORT=3000
python main.py

يمكن اختبار خادم الصحة من خلال:

/api/healthz

وسيُرجع استجابة JSON مضغوطة تتضمن الحالة ووقت التشغيل وعدد القوالب والأقسام، مثل:

{"status":"ok","service":"study-bot-python","uptime_seconds":12.4,"templates":90,"categories":10}

وظائف البوت

يدعم البوت الأوامر /start و/study و/menu و/templates لإنشاء جلسة، /done لإنهاء إدخال المهام، /stats لعرض الإحصائيات والشارات، /history لعرض آخر الجلسات، /cancel للإلغاء، و/help لعرض التعليمات. يحتوي على 90 قالبًا في 10 أقسام، منها «هادئ وأنيق» و«باستيل» و«ورقي» و«مساحة هادئة»، ويقدم زر قالب عشوائي وصورة عشوائية لكل معاينة وجلسة، مع أكثر من 40 دعاءً للمذاكرة يتم اختيار أحدها عشوائيًا عند التسليم. يفهم الأوقات بالأرقام العربية والإنجليزية مثل ٣ العصر و9:30 ص والآن، والمدد مثل ربع ساعة وساعتين و90 دقيقة و2h. بعد تسليم البطاقة يبدأ عداد حي بصيغة دقائق:ثوانٍ ويتجدد كل ثانية، ثم يتحول إلى «انتهت الجلسة» عند الوصول للصفر.

بعد انتهاء الجلسة يرسل البوت فيديو تحفيزيًا عشوائيًا من assets/motivation_videos/. المكتبة الحالية تحتوي على 19 فيديو MP4: 14 فيديو مرفقًا من المستخدم و5 مقاطع Stock Video موثّقة من Mixkit، مع حفظ صفحة المصدر والترخيص للمقاطع الخارجية داخل assets/motivation_videos_manifest.json. لا يتكرر الفيديو نفسه مباشرةً للمحادثة نفسها، ويُحفظ Telegram file_id في SQLite لتقليل إعادة الرفع. يمكن تعطيل الميزة عبر MOTIVATION_VIDEOS_ENABLED=false. لإضافة ملفات جديدة محليًا استخدم دليل إضافة الوسائط.

عند وصول مستخدم لأول مرة، يسجل البوت اسمه وusername وchat_id ووقت أول دخول، ويرسل تنبيهًا فوريًا إلى المالكين المسجلين في OWNER_IDS. لا يكرر التنبيه عند كل رسالة لاحقة من العضو نفسه.

العداد الحي يعتمد على تعديل Caption الرسالة عبر Telegram كل ثانية؛ لذلك هو مناسب للاستخدام الفردي أو عدد الجلسات المحدود. تم حفظ العداد في مهمة مستقلة لكل محادثة حتى لا يوقف polling أو يعطل التذكير، ويتم إلغاؤه تلقائيًا عند بدء جلسة جديدة أو إلغاء الجلسة.

الملفات

الملف	الوظيفة
main.py	تشغيل البوت، المعالجات، القوائم، التقييم، Session numbering، التذكيرات، والعداد الحي
templates.py	90 قالبًا و10 أقسام، مع Quotes عربية و50 دعاءً مخصصًا للمذاكرة وقسم دعاء واضح وتنسيق italic موحد
storage.py	SQLite مع WAL، جلسات وأعضاء وسجلات وإعدادات إدارية وفهارس محسنة وعداد يومي للجلسات
utils.py	تحليل الأوقات والمدد والتوقيت المصري
config.py	قراءة والتحقق من متغيرات البيئة، ومنها OWNER_IDS وFORCE_SUBSCRIPTION_CHANNELS
assets/templates/ وassets/user_images/	59 صورة قالب و106 صور user مدمجة، يتم اختيارها عشوائيًا مع منع التكرار الفوري
assets/motivation_videos/	19 فيديو تحفيزيًا بصيغة MP4، مع اختيار عشوائي ومنع التكرار وحفظ Telegram file_id
test_updated_bot.py وtest_admin_features.py	اختبارات syntax والقوالب والتخزين والعداد ومكتبة الصور وخصائص الإدارة
requirements.txt	اعتماديات Python
Procfile	أمر التشغيل المتوافق مع خدمات الاستضافة
.env.example	نموذج متغيرات البيئة

النشر على Railway

هذا المشروع مجهز بملف Dockerfile وملف railway.json. اربط المستودع بخدمة Railway واترك Railway يستخدم Dockerfile الموجود في جذر المشروع. أضف Volume للخدمة بمسار تركيب /app/data، ثم اضبط:

DATA_DIR=/app/data
DATABASE_PATH=/app/data/study_bot.sqlite3

أضف TELEGRAM_BOT_TOKEN وOWNER_IDS من إعدادات Variables في Railway. لا تضع التوكن داخل Git أو هذا الملف. Railway يحقن PORT تلقائيًا، ويستمع التطبيق عليه من خلال خادم الصحة. استخدم /api/healthz للتحقق من أن الخدمة بدأت وأن SQLite متصل.

تم التحقق من وجود 59 صورة قالب حقيقية من template_001.jpg إلى template_059.jpg، و106 صور user من user_001.jpg إلى user_106.jpg. كما توجد 19 فيديوهات تحفيزية في assets/motivation_videos/، وتوجد تعليمات إضافة الملفات الجديدة في docs/ADDING_MEDIA.md.

استخدم replica واحدة عند تشغيل Telegram polling بالتوكن نفسه. لا ترسل ملفات study_bot.sqlite3-wal أو study_bot.sqlite3-shm منفردة؛ إذا كانت البيانات القديمة مهمة، استعد ملف study_bot.sqlite3 الرئيسي المطابق لها أو أنشئ Backup صحيحًا عبر SQLite.

راجع دليل نشر Railway وسياسة الأمان قبل فتح البوت للمستخدمين.