apps/integrations/README.md

اپلیکیشن Integrations

اپلیکیشن مدیریت یکپارچه‌سازی‌های خارجی برای پروژه هلسا

معرفی

این اپلیکیشن مسئول مدیریت تمام یکپارچه‌سازی‌ها با سرویس‌های خارجی شامل:

• سرویس پیامک (Kavenegar)
• سرویس‌های AI (OpenAI, TalkBot)
• مدیریت Webhook ها
• سیستم Rate Limiting
• ذخیره‌سازی فایل

ساختار

integrations/
├── __init__.py
├── apps.py              # تنظیمات اپلیکیشن
├── models.py            # مدل‌های دیتابیس
├── serializers.py       # سریالایزرها
├── views.py             # API Views
├── urls.py              # URL patterns
├── admin.py             # رابط ادمین
├── settings.py          # تنظیمات اپ
├── services/            # سرویس‌های یکپارچه‌سازی
│   ├── __init__.py
│   ├── base_service.py  # کلاس پایه
│   ├── kavenegar_service.py
│   ├── ai_service.py
│   └── webhook_service.py
└── tests/               # تست‌ها
    ├── __init__.py
    ├── test_models.py
    ├── test_services.py
    └── test_views.py

مدل‌ها

IntegrationProvider

ارائه‌دهندگان خدمات یکپارچه‌سازی (مثل Kavenegar, OpenAI)

IntegrationCredential

ذخیره اطلاعات احراز هویت برای هر ارائه‌دهنده

IntegrationLog

ثبت تمام فعالیت‌های یکپارچه‌سازی

WebhookEndpoint

تعریف endpoint های webhook

WebhookEvent

ثبت رویدادهای دریافتی از webhook ها

RateLimitRule

قوانین محدودیت نرخ درخواست

API Endpoints

مدیریت ارائه‌دهندگان

• GET /api/integrations/providers/ - لیست ارائه‌دهندگان
• GET /api/integrations/providers/{slug}/ - جزئیات ارائه‌دهنده
• GET /api/integrations/providers/{slug}/health-check/ - بررسی سلامت
• GET /api/integrations/providers/{slug}/statistics/ - آمار استفاده

ارسال پیامک

• POST /api/integrations/sms/send/ - ارسال پیامک

نمونه درخواست:

{
    "receptor": "09123456789",
    "message_type": "otp",
    "token": "12345",
    "template": "verify"
}

تولید متن با AI

• POST /api/integrations/ai/generate/ - تولید متن

نمونه درخواست:

{
    "prompt": "متن ورودی",
    "max_tokens": 1000,
    "temperature": 0.7,
    "analysis_type": "symptoms"
}

Webhook

• POST /api/integrations/webhook/{endpoint_url}/ - دریافت webhook

سرویس‌ها

KavenegarService

• send_otp() - ارسال کد OTP
• send_pattern() - ارسال با قالب
• send_bulk() - ارسال گروهی
• get_status() - بررسی وضعیت پیامک

AIIntegrationService

• generate_text() - تولید متن
• analyze_medical_text() - تحلیل متن پزشکی
• transcribe_audio() - تبدیل صوت به متن

WebhookService

• register_webhook() - ثبت webhook جدید
• process_webhook() - پردازش درخواست webhook
• verify_signature() - تأیید امضا

تنظیمات

در فایل settings.py پروژه اصلی:

# Kavenegar
KAVENEGAR_API_KEY = 'your-api-key'
KAVENEGAR_SENDER = '10004346'

# OpenAI
OPENAI_API_KEY = 'your-openai-key'
OPENAI_DEFAULT_MODEL = 'gpt-4'

# Webhook
WEBHOOK_SECRET = 'your-webhook-secret'

# Security
CREDENTIAL_ENCRYPTION_KEY = 'your-encryption-key'

نحوه استفاده

ارسال پیامک OTP

from integrations.services import KavenegarService

service = KavenegarService()
result = service.send_otp(
    receptor='09123456789',
    token='12345'
)

تحلیل متن پزشکی

from integrations.services import AIIntegrationService

service = AIIntegrationService('openai')
result = service.analyze_medical_text(
    text='بیمار از سردرد و تب شکایت دارد',
    analysis_type='symptoms',
    patient_context={'age': 35, 'gender': 'male'}
)

ثبت Webhook

from integrations.services import WebhookService

service = WebhookService()
result = service.register_webhook(
    provider_slug='payment-gateway',
    name='Payment Status',
    endpoint_url='payment-status',
    events=['payment.success', 'payment.failed']
)

تست‌ها

برای اجرای تست‌ها:

python manage.py test integrations

نکات امنیتی

1. رمزنگاری Credentials: تمام اطلاعات حساس باید رمزنگاری شوند
2. تأیید امضای Webhook: همیشه امضای webhook ها را تأیید کنید
3. Rate Limiting: برای جلوگیری از سوءاستفاده، rate limit اعمال کنید
4. Logging: تمام فعالیت‌ها را لاگ کنید

مستندات API

مستندات کامل API در آدرس زیر:

• Swagger: /api/docs/
• ReDoc: /api/redoc/