Mission Project - Motrjim Academy S
دليل تطبيقي كامل — من الصفر إلى النشر

🚀 مشروع Misson

منصّة تعليمية ذكية تحوّل الدروس إلى ألعاب تفاعلية للأطفال

📑 محتويات الدليل

  1. فكرة المشروع وما الذي يحققه
  2. مكوّنات المشروع (كيف تعمل الأجزاء معًا)
  3. تجهيز جهازك للمبتدئين + تحميل Flutter
  4. ما هو GitHub وكيف نربط المشروع للرفع التلقائي
  5. ما هو ملف .env ولماذا هو مهم
  6. Render: تسجيل الحساب ونشر الخدمة
  7. PostgreSQL: إنشاء قاعدة البيانات وربطها وأهميتها
  8. الأخطاء الشائعة وكيف نحلّلها ونحلّها
  9. قائمة تحقّق نهائية

1 فكرة المشروع وما الذي يحققه

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

🎯 ما المتوقّع أن يحقّقه

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

الفئة المستهدفة: أولياء الأمور والمعلّمون لأطفال في مراحل التعليم الأساسي، مع دعم كامل للّغة العربية والإنجليزية.

2 مكوّنات المشروع (كيف تعمل الأجزاء معًا)

المشروع يتكوّن من ثلاثة أجزاء رئيسية تتحدّث مع بعضها عبر الإنترنت:

📱

التطبيق (Flutter)

الواجهة التي يراها المستخدم على الهاتف — مبني بلغة Dart وإطار Flutter.

⚙️

الخادم (FastAPI)

العقل الخلفي بلغة Python — يعالج الطلبات ويولّد الألعاب ويحفظ البيانات.

🗄️

قاعدة البيانات (PostgreSQL)

تخزّن الحسابات والأطفال والألعاب والتقدّم بشكل دائم.

ويعتمد على خدمتين خارجيتين:

🤖

Claude AI

يحلّل الدروس ويصمّم الألعاب.

🐙

GitHub

يخزّن الكود ويشغّل النشر التلقائي.

☁️

Render

يستضيف الخادم وقاعدة البيانات على الإنترنت.

📱 التطبيق ⟵ ⚙️ الخادم على Render ⟵ 🗄️ PostgreSQL
💻 كودك ⟶ 🐙 GitHub ⟶ ☁️ Render ينشر تلقائيًا

3 تجهيز جهازك للمبتدئين + تحميل Flutter

هذه الأدوات تُثبَّت مرّة واحدة على جهازك (Windows):

أ) محرّر الأكواد — VS Code

  1. افتح code.visualstudio.com وحمّل النسخة لويندوز ثم ثبّتها.
  2. من داخل VS Code افتح تبويب Extensions وثبّت إضافتَي Flutter وDart.

ب) Git (لرفع الكود على GitHub)

  1. حمّل Git من git-scm.com/download/win وثبّته بالخيارات الافتراضية.
  2. تأكّد من التثبيت بفتح موجّه الأوامر وكتابة الأمر التالي:
git --version

ج) تحميل Flutter SDK

  1. ادخل الموقع الرسمي docs.flutter.dev/get-started/install واختر Windows.
  2. حمّل ملف flutter_windows_x.x.x-stable.zip وفك ضغطه في مسار بسيط مثل C:\src\flutter (تجنّب مسارات فيها مسافات أو رموز عربية).
  3. أضف مسار C:\src\flutter\bin إلى متغيّر النظام Path (ابحث في ويندوز عن "Edit environment variables").
  4. افتح موجّه أوامر جديد وشغّل فحص البيئة:
flutter doctor

سيخبرك flutter doctor بما ينقص (مثل Android Studio لبناء تطبيقات أندرويد). اتبع تعليماته حتى تصبح كل البنود ✓.

نصيحة: لتشغيل التطبيق على هاتفك أثناء التطوير، فعّل "خيارات المطوّر" و"تصحيح USB" في الهاتف، أو استخدم محاكي Android من Android Studio. ثم من داخل مجلد المشروع شغّل:

# جلب الحزم ثم تشغيل التطبيق flutter pub get flutter run

4 ما هو GitHub وكيف نربط المشروع للرفع التلقائي

GitHub هو "خزانة سحابية للأكواد". يحفظ كل نسخة من مشروعك، ويسمح بالرجوع لأي تعديل سابق، والأهم: خدمات الاستضافة مثل Render تسحب الكود منه وتنشره تلقائيًا.

فرق مهم: GitHub لا ينشر موقعك — هو فقط يخزّن الكود. الذي ينشر ويشغّل الخادم هو Render، وهو يقرأ الكود من GitHub.

أ) إنشاء حساب GitHub

  1. ادخل github.com/signup وسجّل ببريدك الإلكتروني وكلمة مرور قوية.
  2. فعّل الحساب من رسالة التأكيد في بريدك.

ب) إنشاء مستودع (Repository) جديد

  1. اضغط زر + أعلى اليمين ثم New repository.
  2. اكتب اسمًا مثل mission، واتركه Public أو Private، ثم Create repository.

ج) رفع مشروعك من جهازك إلى GitHub

من داخل مجلد المشروع، افتح موجّه الأوامر ونفّذ هذه الأوامر مرّة واحدة:

# تهيئة Git داخل المشروع git init git add . git commit -m "أول نسخة من المشروع" # ربط المستودع البعيد (انسخ الرابط من صفحة مستودعك) git remote add origin https://github.com/USERNAME/mission.git git branch -M main git push -u origin main

د) الرفع التلقائي بعد ذلك

بعد أول ربط، كل ما تحتاجه لرفع أي تعديل جديد هو ثلاثة أوامر:

git add . git commit -m "وصف التعديل" git push

السحر هنا: عند تفعيل خاصية Auto-Deploy في Render، بمجرّد تنفيذ git push سيلتقط Render التعديل وينشر النسخة الجديدة تلقائيًا خلال دقائق — دون أي خطوة يدوية.

5 ما هو ملف .env ولماذا هو مهم

ملف .env (اختصار Environment = البيئة) هو ملف نصّي يحتوي الإعدادات السرّية والمتغيّرة للمشروع، مثل: رابط قاعدة البيانات، المفتاح السرّي للتوكن، ومفاتيح الخدمات الخارجية.

لماذا نستخدمه؟

  • الأمان: لا نكتب كلمات المرور والمفاتيح داخل الكود مباشرة (لأن الكود يُرفع على GitHub ويراه الجميع).
  • المرونة: نغيّر الإعدادات بين جهازك (تطوير) والخادم (إنتاج) دون تعديل الكود.

مثال على محتوى ملف .env:

# قاعدة البيانات DATABASE_URL=postgresql://user:pass@host:5432/dbname # مفتاح سرّي لإنشاء توكنات الدخول JWT_SECRET_KEY=قيمة-عشوائية-طويلة-وقوية # مفتاح خدمة الذكاء الاصطناعي CLAUDE_API_KEY=sk-xxxxxxxx # الوضع التجريبي DEMO_MODE=true

تحذير أمني مهم جدًا: ملف .env يجب ألّا يُرفع أبدًا على GitHub. أضِف اسمه إلى ملف .gitignore ليتجاهله Git. على الخادم (Render) تُوضَع هذه القيم في قسم Environment Variables بدلًا من الملف.

لهذا يوجد عادةً ملف .env.example يُرفع على GitHub — يحتوي أسماء المتغيّرات بدون قيمها الحقيقية، ليعرف أي مطوّر ما الذي يحتاج ضبطه.

6 Render: تسجيل الحساب ونشر الخدمة

Render منصّة استضافة سحابية تشغّل خادمك على الإنترنت وتربطه بـ GitHub للنشر التلقائي، ولها خطة مجانية مناسبة للبداية.

أ) إنشاء الحساب

  1. ادخل render.com واضغط Get Started.
  2. سجّل الدخول بحساب GitHub مباشرة (الأسهل) — سيؤدي هذا لربط حسابيك تلقائيًا.
  3. وافق على منح Render صلاحية قراءة مستودعاتك.

ب) نشر الخادم (Web Service)

  1. من لوحة Render اضغط New + ثم Web Service.
  2. اختر مستودع mission من قائمة مستودعات GitHub.
  3. اضبط الإعدادات:
    • Environment: Python
    • Build Command: pip install -r backend/requirements.txt
    • Start Command: uvicorn app.main:app --host 0.0.0.0 --port $PORT
    • Root Directory: backend
  4. اختر الخطة Free ثم Create Web Service.

انتبه: متغيّر $PORT يوفّره Render تلقائيًا — يجب استخدامه في أمر التشغيل، وإلا لن يكتشف Render المنفذ وستفشل الخدمة برسالة "No open ports detected".

ج) إضافة متغيّرات البيئة

من تبويب Environment أضِف نفس مفاتيح ملف .env (DATABASE_URL و JWT_SECRET_KEY ...). حفظها يُطلق إعادة نشر تلقائية.

ملاحظة عن الخطة المجانية: الخدمة "تنام" بعد ~15 دقيقة خمول، وأول طلب بعدها يتأخّر ~50 ثانية للإيقاظ. هذا طبيعي ولا يعني وجود خطأ.

7 PostgreSQL: إنشاء قاعدة البيانات وربطها وأهميتها

ما هي ولماذا نحتاجها؟

PostgreSQL نظام قواعد بيانات قوي ومجاني ومفتوح المصدر. أهميتها أنها الذاكرة الدائمة للمشروع: بدونها تختفي كل الحسابات والبيانات عند إعادة تشغيل الخادم. تحفظ: المستخدمين، ملفات الأطفال، الدروس، الألعاب، ونقاط التقدّم.

لماذا PostgreSQL على Render وليس استضافة عادية؟ لأن الاستضافات المشتركة (مثل بعض خطط الاستضافة التقليدية) غالبًا تمنع الاتصال الخارجي بقاعدة البيانات، بينما قاعدة Render تعمل بجوار خادمك مباشرة وبلا تعقيد.

أ) إنشاء القاعدة

  1. على Render اضغط New + ثم PostgreSQL.
  2. اختر اسمًا مثل misson-db، ونفس منطقة خدمتك، والخطة Free.
  3. اضغط Create Database وانتظر حتى تصبح الحالة Available.

ب) ربطها بالخادم

  1. افتح صفحة قاعدة البيانات وانسخ Internal Database URL (الداخلي أسرع ومجاني).
  2. اذهب لخدمة الخادم ← تبويب Environment ← أضِف متغيّرًا باسم DATABASE_URL والصق فيه الرابط.
  3. احفظ — سيعيد Render النشر، وسينشئ الخادم الجداول تلقائيًا عند الإقلاع.

نصيحة: لا حاجة لإنشاء الجداول يدويًا — الكود ينشئها تلقائيًا أول مرّة يتصل فيها بالقاعدة.

8 الأخطاء الشائعة وكيف نحلّلها ونحلّها

هذه أخطاء حقيقية واجهناها فعليًا أثناء نشر Misson — وكيف حلّلناها وحللناها. القاعدة الذهبية: اقرأ آخر سطر في رسالة الخطأ (Traceback) — هو الذي يخبرك بالسبب الحقيقي.

رسالة الخطأالسببالحل
No open ports detected أمر التشغيل لا يستخدم $PORT اجعله --port $PORT
email-validator is not installed حزمة ناقصة في requirements أضِف email-validator إلى الملف
ModuleNotFoundError: No module named 'pypdf' مكتبة مستوردة لكن غير مثبّتة أضِف اسم المكتبة إلى requirements.txt
Invalid args for response field خطأ برمجي في تعريف الاستجابة استخدم نموذج Pydantic صحيحًا
Can't connect to database (بعد ~30 ثانية) رابط القاعدة خاطئ أو غير مسموح تحقّق من DATABASE_URL والصلاحيات

منهجية تحليل أي خطأ (3 خطوات)

  1. افتح اللوق (Logs): في Render من تبويب Logs، أو في الطرفية على جهازك.
  2. اقرأ آخر سطر: عادةً يبدأ الخطأ الفعلي بكلمة مثل Error أو Exception في نهاية الـ Traceback.
  3. حدّد النوع: هل هو حزمة ناقصة؟ خطأ كود؟ إعداد بيئة؟ ثم طبّق الحل المناسب وأعد النشر بـ git push.

حيلة عملية: بدل معالجة الأخطاء واحدًا تلو الآخر، افحص كل الاستيرادات (imports) في مشروعك مرّة واحدة وتأكّد أن كل مكتبة خارجية مذكورة في requirements.txt — هذا يوفّر عليك دورات نشر فاشلة متكرّرة.

9 قائمة تحقّق نهائية (من الصفر إلى النشر)

  1. ثبّت الأدوات: VS Code + Git + Flutter (وتأكّد بـ flutter doctor).
  2. جهّز الكود محليًا وجرّبه (flutter run للتطبيق، وتشغيل الخادم محليًا).
  3. أنشئ حساب GitHub وارفع المشروع (git push).
  4. أنشئ حساب Render واربطه بـ GitHub.
  5. أنشئ خدمة Web Service واضبط أوامر البناء والتشغيل.
  6. أنشئ قاعدة PostgreSQL واربطها عبر DATABASE_URL.
  7. أضِف متغيّرات البيئة (JWT_SECRET_KEY وغيرها).
  8. راقب اللوق حتى تظهر "Your service is live 🎉".
  9. حدّث رابط الخادم داخل التطبيق ثم ابنِ نسخة التطبيق النهائية.

بعد كل تعديل مستقبلي: git add . ثم git commit -m "..." ثم git push — وسيتكفّل Render بالباقي تلقائيًا. 🚀

دليل مشروع Misson — أُعدّ للشرح التعليمي · تعلّم من خلال البناء

أكاديمية مُترجم الترجمة في عصر الذكاء الاصطناعي

© 2026 جميع الحقوق محفوظة

Scroll to Top