arc/hesabixAPI/docs/PHASE4_BACKGROUND_JOBS.md

فاز 4: Background Job Queue

خلاصه

این فاز سیستم Background Job Queue را با استفاده از RQ (Redis Queue) پیاده‌سازی می‌کند. این سیستم امکان اجرای کارهای زمان‌بر را در پس‌زمینه فراهم می‌کند و از blocking شدن API جلوگیری می‌کند.

قابلیت‌های پیاده‌سازی شده

1. Queue Service (app/core/queue.py)

• مدیریت queues با RQ
• پشتیبانی از چندین queue با اولویت‌های مختلف:
  • high: کارهای با اولویت بالا
  • default: کارهای عادی
  • email: ارسال ایمیل
  • reports: تولید گزارش
  • exports: export داده‌ها
  • low: کارهای با اولویت پایین
• مدیریت job ها: enqueue, get, cancel, delete
• آمارگیری از queues

2. Job Manager به‌روزرسانی شده (app/services/job_manager.py)

• سازگاری با QueueService
• پشتیبانی از memory-based jobs (fallback)
• تبدیل وضعیت RQ jobs به JobStatus

3. Background Jobs

• Email Job (app/services/jobs/email_job.py): ارسال ایمیل
• Report Job (app/services/jobs/report_job.py): تولید گزارش
• Export Job (app/services/jobs/export_job.py): export داده‌ها

4. RQ Worker (rq_worker.py)

• Worker script برای اجرای jobs
• پشتیبانی از تمام queues با اولویت‌بندی

5. API Endpoints (adapters/api/v1/jobs.py)

• GET /api/v1/jobs/{job_id}: دریافت وضعیت job
• DELETE /api/v1/jobs/{job_id}: لغو یا حذف job
• GET /api/v1/jobs/queue/stats: آمار queues
• GET /api/v1/jobs/failed: لیست jobs ناموفق

نصب و راه‌اندازی

1. نصب Dependencies

cd hesabixAPI
source .venv/bin/activate
pip install -e .

2. راه‌اندازی Redis

Redis باید نصب و راه‌اندازی شده باشد. برای راهنمای نصب Redis، به docs/REDIS_SETUP.md مراجعه کنید.

3. راه‌اندازی RQ Worker

دستی:

cd hesabixAPI
source .venv/bin/activate
python rq_worker.py

با systemd (از طریق deploy.sh):

sudo systemctl start hesabix-rq-worker
sudo systemctl enable hesabix-rq-worker

4. بررسی وضعیت Worker

# بررسی وضعیت service
sudo systemctl status hesabix-rq-worker

# مشاهده لاگ‌ها
sudo journalctl -u hesabix-rq-worker -f

برای مشاهدهٔ همان لاگ از پنل ادمین (تنظیمات سیستم → لاگ‌های سرویس‌ها) و محدودیت‌های میزبان/Docker، به SERVICE_LOGS_ADMIN_API.md مراجعه کنید.

استفاده

Enqueue کردن Job

from app.core.queue import get_queue_service, QUEUE_EMAIL
from app.services.jobs import send_email_job

queue_service = get_queue_service()

# Enqueue کردن job
job = queue_service.enqueue(
    send_email_job,
    to_email="user@example.com",
    subject="Test Email",
    body="This is a test email",
    queue_name=QUEUE_EMAIL,
    timeout=300,
    result_ttl=3600
)

if job:
    print(f"Job ID: {job.id}")

بررسی وضعیت Job

from app.services.job_manager import JobManager

job_manager = JobManager.instance()
status = job_manager.get(job_id)

if status:
    print(f"State: {status.state}")
    print(f"Progress: {status.progress}%")
    print(f"Message: {status.message}")

استفاده در API Endpoints

from app.core.queue import get_queue_service, QUEUE_REPORTS
from app.services.jobs import generate_report_job

@router.post("/reports/generate")
async def create_report(...):
    queue_service = get_queue_service()
    
    if not queue_service.enabled:
        raise ApiError("QUEUE_DISABLED", "Queue service is disabled")
    
    job = queue_service.enqueue(
        generate_report_job,
        report_type="sales",
        business_id=business_id,
        user_id=user_id,
        queue_name=QUEUE_REPORTS
    )
    
    return {"job_id": job.id}

Queues و اولویت‌ها

Worker به ترتیب اولویت از queues استفاده می‌کند:

1. high - کارهای با اولویت بالا
2. default - کارهای عادی
3. email - ارسال ایمیل
4. reports - تولید گزارش
5. exports - export داده‌ها
6. low - کارهای با اولویت پایین

Monitoring

آمار Queues

curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8000/api/v1/jobs/queue/stats

Jobs ناموفق

curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8000/api/v1/jobs/failed?limit=10

Troubleshooting

Worker شروع نمی‌شود

1. بررسی کنید Redis در حال اجرا است:

   sudo systemctl status redis
   

2. بررسی تنظیمات Redis در پنل مدیریت سیستم

3. بررسی لاگ‌های worker:

   sudo journalctl -u hesabix-rq-worker -n 50
   

Jobs اجرا نمی‌شوند

1. بررسی کنید worker در حال اجرا است:

   sudo systemctl status hesabix-rq-worker
   

2. بررسی کنید Redis در دسترس است:

   redis-cli ping
   

3. بررسی آمار queues:

   curl -H "Authorization: Bearer YOUR_TOKEN" \
     http://localhost:8000/api/v1/jobs/queue/stats
   

Jobs در queue می‌مانند

1. بررسی کنید worker در حال اجرا است
2. بررسی لاگ‌های worker برای خطاها
3. بررسی failed jobs:

   curl -H "Authorization: Bearer YOUR_TOKEN" \
     http://localhost:8000/api/v1/jobs/failed
   

Best Practices

1. Timeout مناسب: برای هر job یک timeout مناسب تنظیم کنید
2. Result TTL: برای jobs با نتیجه بزرگ، TTL کوتاه‌تری تنظیم کنید
3. Queue مناسب: از queue مناسب برای هر نوع job استفاده کنید
4. Error Handling: در job functions خطاها را به درستی handle کنید
5. Monitoring: به طور منظم آمار queues و failed jobs را بررسی کنید

مقیاس‌پذیری

برای مقیاس‌پذیری بیشتر:

• می‌توانید چندین worker اجرا کنید
• می‌توانید worker های جداگانه برای هر queue ایجاد کنید
• می‌توانید از Redis Cluster برای مقیاس‌پذیری بیشتر استفاده کنید

Migration از BackgroundTasks

اگر از FastAPI BackgroundTasks استفاده می‌کردید، می‌توانید به تدریج به RQ migrate کنید:

1. Job های زمان‌بر را به RQ منتقل کنید
2. Job های سریع را می‌توانید در BackgroundTasks نگه دارید
3. از QueueService برای enqueue کردن استفاده کنید

منابع

• RQ Documentation
• Redis Documentation