Initial commit - clean project structure

notifications/admin.py

@@ -0,0 +1,10 @@
+from django.contrib import admin
+
+from .models import Notification
+
+
+@admin.register(Notification)
+class NotificationAdmin(admin.ModelAdmin):
+    list_display = ('id', 'user_id', 'type', 'title', 'is_read', 'created_at')
+    list_filter = ('type', 'is_read')
+    search_fields = ('title', 'body')

notifications/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class NotificationsConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    name = 'notifications'

notifications/migrations/0001_initial.py

@@ -0,0 +1,37 @@
+# Generated by Django 5.2.17 on 2026-08-10 12:00
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Notification',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('user_id', models.IntegerField(db_index=True)),
+                ('type', models.CharField(choices=[
+                    ('xp_earned', 'امتیاز گرفتی'),
+                    ('lesson_completed', 'درس تکمیل شد'),
+                    ('order_paid', 'پرداخت موفق'),
+                    ('ticket_replied', 'پاسخ تیکت'),
+                    ('family_link_accepted', 'اتصال خانواده تأیید شد'),
+                    ('weekly_report_ready', 'گزارش هفتگی آماده شد'),
+                ], max_length=30)),
+                ('title', models.CharField(max_length=150)),
+                ('body', models.CharField(blank=True, max_length=300)),
+                ('related_id', models.IntegerField(blank=True, null=True)),
+                ('is_read', models.BooleanField(default=False)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+            ],
+            options={
+                'ordering': ['-created_at'],
+            },
+        ),
+    ]

notifications/models.py

@@ -0,0 +1,30 @@
+from django.db import models
+
+
+class Notification(models.Model):
+    # انواع رویدادهایی که این اپ فقط بهشون گوش می‌ده (event-listener)؛
+    # خودش تولیدکننده‌ی رویداد نیست. طبق سند معماری:
+    # LessonCompleted/XPEarned (Progress), OrderPaid (Payment),
+    # TicketReplied (Support), FamilyLinkAccepted/WeeklyReportReady (Family)
+    TYPE_CHOICES = [
+        ('xp_earned', 'امتیاز گرفتی'),
+        ('lesson_completed', 'درس تکمیل شد'),
+        ('order_paid', 'پرداخت موفق'),
+        ('ticket_replied', 'پاسخ تیکت'),
+        ('family_link_accepted', 'اتصال خانواده تأیید شد'),
+        ('weekly_report_ready', 'گزارش هفتگی آماده شد'),
+    ]
+
+    user_id = models.IntegerField(db_index=True)  # ارجاع سبک به accounts.User
+    type = models.CharField(max_length=30, choices=TYPE_CHOICES)
+    title = models.CharField(max_length=150)
+    body = models.CharField(max_length=300, blank=True)
+    related_id = models.IntegerField(null=True, blank=True)  # id رکورد رویداد منبع، بدون FK واقعی
+    is_read = models.BooleanField(default=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        ordering = ['-created_at']
+
+    def __str__(self):
+        return f"notif-{self.id}-{self.type}-user{self.user_id}"

notifications/serializers.py

@@ -0,0 +1,21 @@
+from rest_framework import serializers
+
+from .models import Notification
+
+
+class NotificationItemSerializer(serializers.ModelSerializer):
+    id = serializers.IntegerField()
+    isRead = serializers.BooleanField(source='is_read')
+
+    class Meta:
+        model = Notification
+        fields = ['id', 'type', 'title', 'isRead']
+
+
+class NotificationListResponseSerializer(serializers.Serializer):
+    items = NotificationItemSerializer(many=True)
+    unreadCount = serializers.IntegerField()
+
+
+class MarkReadResponseSerializer(serializers.Serializer):
+    success = serializers.BooleanField()

notifications/services.py

@@ -0,0 +1,27 @@
+"""
+اپ 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,
+    )

notifications/tests.py

@@ -0,0 +1,3 @@
+from django.test import TestCase
+
+# Create your tests here.

notifications/urls.py

@@ -0,0 +1,8 @@
+from django.urls import path
+
+from .views import NotificationListView, NotificationMarkReadView
+
+urlpatterns = [
+    path('notifications', NotificationListView.as_view(), name='notifications-list'),
+    path('notifications/<int:id>/read', NotificationMarkReadView.as_view(), name='notifications-mark-read'),
+]

notifications/views.py

@@ -0,0 +1,37 @@
+from django.shortcuts import get_object_or_404
+from drf_spectacular.utils import extend_schema
+from rest_framework.permissions import IsAuthenticated
+from rest_framework.response import Response
+from rest_framework.views import APIView
+
+from .models import Notification
+from .serializers import MarkReadResponseSerializer, NotificationListResponseSerializer
+
+
+class NotificationListView(APIView):
+    """GET /api/notifications — فهرست اعلان‌های کاربر (جدیدترین اول)"""
+
+    permission_classes = [IsAuthenticated]
+
+    @extend_schema(responses=NotificationListResponseSerializer, tags=['Notifications (notifications)'])
+    def get(self, request):
+        qs = Notification.objects.filter(user_id=request.user.id)
+        unread_count = qs.filter(is_read=False).count()
+
+        data = {'items': list(qs), 'unreadCount': unread_count}
+        return Response(NotificationListResponseSerializer(data).data)
+
+
+class NotificationMarkReadView(APIView):
+    """PATCH /api/notifications/{id}/read — علامت‌گذاری یک اعلان به‌عنوان خوانده‌شده"""
+
+    permission_classes = [IsAuthenticated]
+
+    @extend_schema(responses=MarkReadResponseSerializer, tags=['Notifications (notifications)'])
+    def patch(self, request, id):
+        notification = get_object_or_404(Notification, pk=id, user_id=request.user.id)
+        if not notification.is_read:
+            notification.is_read = True
+            notification.save(update_fields=['is_read'])
+
+        return Response(MarkReadResponseSerializer({'success': True}).data)