"""
اپ Notifications برخلاف بقیه‌ی اپ‌ها به هیچ اپی رفرنس سبک نمی‌ده و خودش
تولیدکننده‌ی رویداد نیست؛ فقط event-listener‌ه (طبق سند معماری داده).
چون این پروژه یک مونولیت جنگویی‌ه، «گوش دادن به رویداد» با یک تابع کمکی
پیاده‌سازی شده که سایر اپ‌ها (Progress، Payment، Support، Family) مستقیماً
از این ماژول import و صدا می‌زنن — دقیقاً همون الگوی call_payment_gateway
در payment/services.py و create_order که سرور-به-سرور از subscription
صدا زده می‌شه.
"""
from .models import Notification


def notify(*, user_id: int, type: str, title: str, body: str = '', related_id: int | None = None) -> Notification:
    """
    ثبت یک اعلان جدید برای کاربر. نمونه‌ی استفاده از اپ‌های دیگه:

        from notifications.services import notify
        notify(user_id=order.user_id, type='order_paid',
               title='پرداخت با موفقیت انجام شد', related_id=order.id)
    """
    return Notification.objects.create(
        user_id=user_id,
        type=type,
        title=title,
        body=body,
        related_id=related_id,
    )