تهيئة مشروع TaskFlow

في هذا المعمل، ستقوم بإعداد الأساس الكامل لواجهة TaskFlow البرمجية. بنهاية التمرين، سيكون لديك حزمة Docker Compose عاملة مع FastAPI وPostgreSQL 18 وRedis — جميعها متصلة ومتحقق منها عبر نقطة نهاية فحص الصحة.

الخطوة 1: إنشاء هيكل مجلدات المشروع

أنشئ هيكل المجلدات التالي لمشروع TaskFlow:

mkdir -p taskflow/app/{api/v1,models,schemas,core,tests}
cd taskflow

أنشئ ملفات __init__.py في كل مجلد حزمة Python:

touch app/__init__.py
touch app/api/__init__.py
touch app/api/v1/__init__.py
touch app/models/__init__.py
touch app/schemas/__init__.py
touch app/core/__init__.py
touch app/tests/__init__.py

الخطوة 2: إنشاء ملف المتطلبات

أنشئ requirements.txt مع تبعيات مثبتة الإصدارات:

# إطار العمل الويب
fastapi>=0.128.0,<0.129.0
uvicorn[standard]>=0.34.0,<0.35.0

# قاعدة البيانات
sqlalchemy>=2.0.46,<2.1.0
psycopg2-binary>=2.9.10,<3.0.0
alembic>=1.18.4,<1.19.0

# التحقق والإعدادات
pydantic>=2.12.0,<3.0.0
pydantic-settings>=2.8.0,<3.0.0

# المصادقة
python-jose[cryptography]>=3.3.0,<4.0.0
passlib[bcrypt]>=1.7.4,<2.0.0

# التخزين المؤقت
redis>=7.1.1,<8.0.0

# الاختبار
pytest>=9.0.2,<10.0.0
pytest-asyncio>=0.25.0,<1.0.0
httpx>=0.28.0,<1.0.0

# الأدوات المساعدة
python-dotenv>=1.0.1,<2.0.0
python-multipart>=0.0.20,<1.0.0

الخطوة 3: إنشاء إعدادات البيئة

أنشئ ملف .env في جذر المشروع:

# التطبيق
APP_NAME=TaskFlow
APP_VERSION=0.1.0
DEBUG=true

# قاعدة البيانات
POSTGRES_USER=taskflow
POSTGRES_PASSWORD=taskflow_secret_2026
POSTGRES_DB=taskflow
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
DATABASE_URL=postgresql://taskflow:taskflow_secret_2026@postgres:5432/taskflow

# Redis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_URL=redis://redis:6379/0

# JWT (أنشئ مفتاحك السري الخاص في بيئة الإنتاج!)
JWT_SECRET_KEY=dev-secret-key-change-in-production
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30

الخطوة 4: إنشاء وحدة الإعدادات

أنشئ app/core/config.py:

from pydantic_settings import BaseSettings


class Settings(BaseSettings):
    app_name: str = "TaskFlow"
    app_version: str = "0.1.0"
    debug: bool = False

    # قاعدة البيانات
    database_url: str = "postgresql://taskflow:taskflow_secret_2026@postgres:5432/taskflow"

    # Redis
    redis_url: str = "redis://redis:6379/0"

    # JWT
    jwt_secret_key: str = "dev-secret-key-change-in-production"
    jwt_algorithm: str = "HS256"
    jwt_access_token_expire_minutes: int = 30

    class Config:
        env_file = ".env"
        env_file_encoding = "utf-8"


settings = Settings()

الخطوة 5: إنشاء تطبيق FastAPI

أنشئ app/main.py:

from fastapi import FastAPI
from app.core.config import settings

app = FastAPI(
    title=settings.app_name,
    version=settings.app_version,
    docs_url="/docs",
    redoc_url="/redoc",
)


@app.get("/health")
async def health_check():
    return {
        "status": "healthy",
        "app": settings.app_name,
        "version": settings.app_version,
    }

الخطوة 6: إنشاء ملف Dockerfile

أنشئ Dockerfile مع بناء متعدد المراحل:

# ---- المرحلة 1: البناء ----
FROM python:3.12-slim AS builder

WORKDIR /build

COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

# ---- المرحلة 2: التشغيل ----
FROM python:3.12-slim AS runtime

WORKDIR /app

# نسخ الحزم المثبتة من مرحلة البناء
COPY --from=builder /install /usr/local

# نسخ كود التطبيق
COPY . .

EXPOSE 8000

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

الخطوة 7: إنشاء إعدادات Docker Compose

أنشئ docker-compose.yml:

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8000:8000"
    volumes:
      - .:/app
    env_file:
      - .env
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:18
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-taskflow}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-taskflow_secret_2026}
      POSTGRES_DB: ${POSTGRES_DB:-taskflow}
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U taskflow -d taskflow"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:

الخطوة 8: البناء والتشغيل

شغّل الحزمة الكاملة:

docker compose up --build -d

تحقق من نقطة نهاية فحص الصحة:

curl http://localhost:8000/health

يجب أن ترى:

{
  "status": "healthy",
  "app": "TaskFlow",
  "version": "0.1.0"
}

تحقق من توثيق الواجهة البرمجية المُنشأ تلقائيا بزيارة http://localhost:8000/docs في متصفحك.

الخطوة 9: التحقق من جميع الخدمات

تحقق أن جميع الحاويات تعمل:

docker compose ps

يجب أن تظهر جميع الخدمات الثلاث (app، postgres، redis) بحالة Up (healthy).

ماذا تقدّم

المحرر يحتوي مسبقاً على 6 أقسام ملفات مع تعليقات TODO. استبدل كل TODO بالكود الفعلي. سيقوم المقيّم الذكي بتقييم كل قسم وفقاً لمعايير التقييم.