الخطوة 1 في الواجهة الخلفية: إعداد المشروع

في هذه الخطوة، ستقوم بإعداد بيئة تطوير Python وتثبيت الأدوات التي تحتاجها الواجهة الخلفية.

ما ستتعلمه

إنشاء بيئة افتراضية بلغة Python
تثبيت الحزم باستخدام pip
فهم بنية المشروع
تصميم API قبل كتابة الكود

صمّم أولًا

قبل أن تكتب سطرًا واحدًا من الكود، ارسم مخطط API على ورقة أو في ملف نصي. يُسمّى هذا التطوير بالتصميم أولًا — حيث تخطّط لما سيفعله API قبل أن تبنيه.

في تطبيق الدردشة هذا، سيحتاج API إلى ما يلي:

نقطة النهاية (endpoint)	طريقة HTTP	ما تفعله
`GET /api/status`	GET	فحص الصحة — يعيد `{"status":"ok"}`
`GET /api/messages`	GET	جلب كل رسائل الدردشة
`POST /api/chat`	POST	إرسال رسالة والحصول على رد من الذكاء الاصطناعي
`DELETE /api/messages/<id>`	DELETE	حذف رسالة محددة
`GET /api/health`	GET	معلومات مفصلة عن الصحة (قاعدة البيانات، الإصدار، المقاييس)
`GET /api/metrics`	GET	عدد الطلبات وبيانات الأداء

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

الخطوة 1: إنشاء بنية المشروع

أنشئ بنية المجلدات التالية:

aiproject/
├── backend/
│   ├── app/
│   │   ├── __init__.py
│   │   ├── models.py
│   │   ├── routes.py
│   │   ├── config.py
│   │   ├── errors.py
│   │   ├── logging_config.py
│   │   ├── metrics.py
│   │   ├── requirements.txt
│   │   └── .env.example
│   ├── tests/
│   │   ├── __init__.py
│   │   ├── conftest.py
│   │   ├── test_status.py
│   │   ├── test_chat.py
│   │   ├── test_messages.py
│   │   └── test_health.py
│   ├── Dockerfile
│   ├── Dockerfile.prod
│   ├── docker-compose.yml
│   └── wsgi.py
├── advanced/
├── concepts/
├── deployment/
├── ...

شغّل:

mkdir -p aiproject/backend/app aiproject/backend/tests
cd aiproject/backend

الخطوة 2: اختر طريقة الإعداد

أمامك طريقتان لتشغيل الواجهة الخلفية: بيئة افتراضية (Python القياسية) أو Docker (داخل حاوية). وكلتاهما تعطيان النتيجة نفسها — اختر الطريقة التي تشعر معها براحة أكبر.

الخيار أ: بيئة افتراضية (الطريقة القياسية)

هذا هو الأسلوب التقليدي في Python. تحتاج إلى تثبيت Python 3.10 أو أحدث على جهازك.

الخطوة 2أ: إنشاء بيئة افتراضية

python3 -m venv venv

فعّلها:

# macOS / Linux
source venv/bin/activate

# ويندوز (موجه الأوامر)
venv\Scripts\activate

# ويندوز (PowerShell)
venv\Scripts\Activate.ps1

ينبغي أن يظهر الآن (venv) في بداية موجه الطرفية.

الخطوة 3أ: إنشاء ملف requirements.txt

أنشئ ملف backend/app/requirements.txt:

flask
flask-sqlalchemy
flask-cors
python-dotenv
openai

الخطوة 4أ: تثبيت التبعيات

pip install -r app/requirements.txt

تحقّق من نجاح التثبيت:

pip list

ينبغي أن ترى flask وflask-sqlalchemy وflask-cors وpython-dotenv وopenai في القائمة.

الخيار ب: Docker (داخل حاوية)

يشغّل Docker تطبيقك في حاوية معزولة — فلا حاجة إلى تثبيت Python أو إدارة بيئات افتراضية.

الخطوة 2ب: تثبيت Docker

macOS: نزّل Docker Desktop for Mac
Windows: نزّل Docker Desktop for Windows
Linux: استخدم مدير الحزم لديك — مثلًا sudo apt install docker.io docker-compose-v2

تحقّق من أن Docker يعمل:

docker --version
docker compose version

الخطوة 3ب: البناء والتشغيل باستخدام Docker

cd aiproject/backend
docker compose build
docker compose up

يُنزّل البناء الأول صورة Python ويثبّت التبعيات — ويستغرق ذلك دقيقة واحدة. أما التشغيلات التالية فتكون فورية.

سترى:

app-1  |  * Running on http://127.0.0.1:5000

تستخدم الحاوية ملف .env من backend/app/.env تلقائيًا (ستنشئه في الخطوة 5 أدناه). وأي تغييرات تُجريها على الكود تنعكس فورًا بفضل ربط المجلد (volume mount) الذي يتيح إعادة التحميل المباشر.

للإيقاف: اضغط Ctrl+C.

نصيحة: تبقى بيانات SQLite محفوظة في مجلد تخزين Docker (volume). لإعادة ضبط قاعدة البيانات: docker compose down -v

تابع بأي من الخيارين

تعمل الخطوات المتبقية بالطريقة نفسها مع كل من venv وDocker. الفرق الوحيد هو طريقة تشغيل الخادم:

الإجراء	venv	Docker
تثبيت التبعيات	`pip install -r app/requirements.txt`	`docker compose build`
تشغيل الخادم	`source venv/bin/activate && python app/__init__.py`	`docker compose up`
إيقاف الخادم	`Ctrl+C`	`Ctrl+C`

الخطوة 5: إنشاء .env.example

أنشئ ملف backend/app/.env.example:

OPENAI_API_KEY=sk-your-key-here

هذا قالب. عندما تحصل على مفتاح API الفعلي، ستنسخ هذا الملف إلى .env وتستبدل القيمة.

الخطوة 6: إنشاء init.py (فارغ في الوقت الحالي)

touch app/__init__.py
touch app/models.py
touch app/routes.py

ما الذي حدث للتو؟

البيئة الافتراضية تعزل حزم مشروعك عن بقية نظامك
requirements.txt يسرد تبعياتك حتى يستطيع أي شخص تثبيتها بأمر واحد
.env.example قالب لمتغيرات البيئة المطلوبة (لا تعمل commit لملف .env الحقيقي أبدًا)

ما هو Ruff؟

Ruff هو أداة فحص (linter) — أداة تفحص كودك بحثًا عن الأخطاء والاستيرادات غير المستخدمة ومشكلات الأسلوب قبل تشغيله.

فبدلًا من اكتشاف الأخطاء البرمجية وقت التشغيل (عندما يتعطّل تطبيقك)، يكتشفها ruff وقت تحرير الكود:

ruff check app/
# → app/routes.py:5:1: F401 `os` imported but unused

أمر واحد يكتشف أخطاء شائعة كثيرة. وستستخدمه بدءًا من الخطوة 2.

ثبّته الآن:

pip install ruff

التحقق

شغّل هذا للتأكد من أن كل شيء مثبّت:

python3 -c "import flask; import flask_sqlalchemy; import flask_cors; print('All imports work!')"

المخرجات المتوقعة: All imports work!

الخيار ب (Docker)

يُعدّ البناء ناجحًا إذا اكتمل docker compose build دون أخطاء. نفّذ فحصًا سريعًا:

docker compose run app python -c "import flask; import flask_sqlalchemy; import flask_cors; print('All imports work!')"

المخرجات المتوقعة: All imports work!