Initial commit

content/admin.py

@@ -0,0 +1,50 @@
+from django.contrib import admin
+
+from .models import Choice, Grade, Lesson, Node, Question, Unit, UserAnswer, UserLessonCompletion
+
+
+class ChoiceInline(admin.TabularInline):
+    model = Choice
+    extra = 1
+
+
+@admin.register(Grade)
+class GradeAdmin(admin.ModelAdmin):
+    list_display = ('id', 'title', 'icon', 'color')
+
+
+@admin.register(Unit)
+class UnitAdmin(admin.ModelAdmin):
+    list_display = ('id', 'title', 'grade', 'order')
+    list_filter = ('grade',)
+
+
+@admin.register(Node)
+class NodeAdmin(admin.ModelAdmin):
+    list_display = ('id', 'title', 'unit', 'order')
+    list_filter = ('unit',)
+
+
+@admin.register(Lesson)
+class LessonAdmin(admin.ModelAdmin):
+    list_display = ('id', 'title', 'node')
+    list_filter = ('node',)
+
+
+@admin.register(Question)
+class QuestionAdmin(admin.ModelAdmin):
+    list_display = ('id', 'prompt', 'lesson', 'type')
+    list_filter = ('type', 'lesson')
+    inlines = [ChoiceInline]
+
+
+@admin.register(UserLessonCompletion)
+class UserLessonCompletionAdmin(admin.ModelAdmin):
+    list_display = ('id', 'user_id', 'lesson', 'correct_count', 'stars', 'xp_earned', 'coins_earned')
+    list_filter = ('lesson',)
+
+
+@admin.register(UserAnswer)
+class UserAnswerAdmin(admin.ModelAdmin):
+    list_display = ('id', 'user_id', 'question', 'choice', 'correct', 'xp_earned')
+    list_filter = ('correct',)

content/apps.py

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

content/migrations/0001_initial.py

@@ -0,0 +1,106 @@
+# Generated by Django 5.2.17 on 2026-08-10 11:37
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Grade',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('title', models.CharField(max_length=50)),
+                ('icon', models.CharField(max_length=100)),
+                ('color', models.CharField(max_length=10)),
+            ],
+        ),
+        migrations.CreateModel(
+            name='Node',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('title', models.CharField(max_length=150)),
+                ('order', models.PositiveIntegerField(default=0)),
+            ],
+            options={
+                'ordering': ['order'],
+            },
+        ),
+        migrations.CreateModel(
+            name='Lesson',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('title', models.CharField(max_length=150)),
+                ('intro_text', models.TextField()),
+                ('mascot_animation', models.CharField(default='explain', max_length=50)),
+                ('node', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='lessons', to='content.node')),
+            ],
+        ),
+        migrations.CreateModel(
+            name='Question',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('type', models.CharField(choices=[('multiple_choice', 'چهارگزینه\u200cای'), ('count_objects', 'شمارش اشیاء')], max_length=30)),
+                ('prompt', models.TextField()),
+                ('asset_group', models.CharField(blank=True, max_length=100)),
+                ('lesson', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='questions', to='content.lesson')),
+            ],
+        ),
+        migrations.CreateModel(
+            name='Choice',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('value', models.CharField(max_length=100)),
+                ('is_correct', models.BooleanField(default=False)),
+                ('question', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='choices', to='content.question')),
+            ],
+        ),
+        migrations.CreateModel(
+            name='Unit',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('title', models.CharField(max_length=100)),
+                ('order', models.PositiveIntegerField(default=0)),
+                ('grade', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='units', to='content.grade')),
+            ],
+            options={
+                'ordering': ['order'],
+            },
+        ),
+        migrations.AddField(
+            model_name='node',
+            name='unit',
+            field=models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='nodes', to='content.unit'),
+        ),
+        migrations.CreateModel(
+            name='UserAnswer',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('user_id', models.IntegerField(db_index=True)),
+                ('correct', models.BooleanField()),
+                ('xp_earned', models.PositiveIntegerField(default=0)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('choice', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='answers', to='content.choice')),
+                ('question', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='answers', to='content.question')),
+            ],
+        ),
+        migrations.CreateModel(
+            name='UserLessonCompletion',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('user_id', models.IntegerField(db_index=True)),
+                ('correct_count', models.PositiveIntegerField()),
+                ('stars', models.PositiveSmallIntegerField()),
+                ('xp_earned', models.PositiveIntegerField(default=0)),
+                ('coins_earned', models.PositiveIntegerField(default=0)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('lesson', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='completions', to='content.lesson')),
+            ],
+        ),
+    ]

content/models.py

@@ -0,0 +1,100 @@
+from django.db import models
+
+
+class Grade(models.Model):
+    title = models.CharField(max_length=50)
+    icon = models.CharField(max_length=100)
+    color = models.CharField(max_length=10)
+
+    def __str__(self):
+        return self.title
+
+
+class Unit(models.Model):
+    grade = models.ForeignKey(Grade, on_delete=models.CASCADE, related_name='units')
+    title = models.CharField(max_length=100)
+    order = models.PositiveIntegerField(default=0)
+
+    class Meta:
+        ordering = ['order']
+
+    def __str__(self):
+        return self.title
+
+
+class Node(models.Model):
+    unit = models.ForeignKey(Unit, on_delete=models.CASCADE, related_name='nodes')
+    title = models.CharField(max_length=150)
+    order = models.PositiveIntegerField(default=0)
+
+    class Meta:
+        ordering = ['order']
+
+    def __str__(self):
+        return self.title
+
+
+class Lesson(models.Model):
+    node = models.ForeignKey(Node, on_delete=models.CASCADE, related_name='lessons')
+    title = models.CharField(max_length=150)
+    intro_text = models.TextField()
+    mascot_animation = models.CharField(max_length=50, default='explain')
+
+    def __str__(self):
+        return self.title
+
+
+class Question(models.Model):
+    TYPE_CHOICES = [('multiple_choice', 'چهارگزینه‌ای'), ('count_objects', 'شمارش اشیاء')]
+
+    lesson = models.ForeignKey(Lesson, on_delete=models.CASCADE, related_name='questions')
+    type = models.CharField(max_length=30, choices=TYPE_CHOICES)
+    prompt = models.TextField()
+    asset_group = models.CharField(max_length=100, blank=True)
+
+    def __str__(self):
+        return self.prompt[:50]
+
+
+class Choice(models.Model):
+    """
+    ⚠️ اصلاح نسبت به سند اولیه: دیاگرام معماری فقط فیلد `value` رو برای
+    Choice مشخص کرده بود و فیلد تشخیص گزینه‌ی درست (is_correct) رو نداشت
+    (این نکته توی سند models هم صراحتاً به‌عنوان یک ایراد/نقص علامت‌گذاری
+    شده بود: "یا این فیلد سهواً جا افتاده یا تشخیص جای دیگه‌ای انجام می‌شه").
+    چون بدون این فیلد امکان پیاده‌سازی POST /api/questions/{id}/answer
+    (که باید correct را برگردونه) وجود نداره، این فیلد اینجا اضافه شده.
+    اگه منطق تشخیص پاسخ درست قراره جای دیگه‌ای (سرویس content-authoring)
+    انجام بشه، این فیلد رو می‌شه بعداً حذف/جابه‌جا کرد.
+    """
+    question = models.ForeignKey(Question, on_delete=models.CASCADE, related_name='choices')
+    value = models.CharField(max_length=100)
+    is_correct = models.BooleanField(default=False)  # <-- اصلاح/افزوده شده
+
+    def __str__(self):
+        return self.value
+
+
+class UserLessonCompletion(models.Model):
+    user_id = models.IntegerField(db_index=True)  # ارجاع سبک به accounts.User
+    lesson = models.ForeignKey(Lesson, on_delete=models.CASCADE, related_name='completions')
+    correct_count = models.PositiveIntegerField()
+    stars = models.PositiveSmallIntegerField()
+    xp_earned = models.PositiveIntegerField(default=0)
+    coins_earned = models.PositiveIntegerField(default=0)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    def __str__(self):
+        return f"completion-user{self.user_id}-lesson{self.lesson_id}"
+
+
+class UserAnswer(models.Model):
+    user_id = models.IntegerField(db_index=True)  # ارجاع سبک به accounts.User
+    question = models.ForeignKey(Question, on_delete=models.CASCADE, related_name='answers')
+    choice = models.ForeignKey(Choice, on_delete=models.CASCADE, related_name='answers')
+    correct = models.BooleanField()
+    xp_earned = models.PositiveIntegerField(default=0)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    def __str__(self):
+        return f"answer-user{self.user_id}-q{self.question_id}"

content/serializers.py

@@ -0,0 +1,94 @@
+from rest_framework import serializers
+
+from .models import Choice, Grade, Lesson, Question
+
+
+# ---- Grades ----
+
+class GradeSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Grade
+        fields = ['id', 'title', 'icon', 'color']
+
+
+class GradesListResponseSerializer(serializers.Serializer):
+    grades = GradeSerializer(many=True)
+
+
+# ---- Home (skill map + stats) ----
+
+class NodeStatusSerializer(serializers.Serializer):
+    id = serializers.CharField()
+    title = serializers.CharField()
+    status = serializers.ChoiceField(choices=['locked', 'unlocked', 'completed'])
+
+
+class UnitWithNodesSerializer(serializers.Serializer):
+    id = serializers.CharField()
+    title = serializers.CharField()
+    nodes = NodeStatusSerializer(many=True)
+
+
+class StatsSerializer(serializers.Serializer):
+    progressPercent = serializers.FloatField()
+    xp = serializers.IntegerField()
+    coins = serializers.IntegerField()
+
+
+class HomeResponseSerializer(serializers.Serializer):
+    units = UnitWithNodesSerializer(many=True)
+    stats = StatsSerializer()
+
+
+# ---- Lesson intro ----
+
+class LessonIntroResponseSerializer(serializers.Serializer):
+    lessonId = serializers.CharField()
+    title = serializers.CharField()
+    introText = serializers.CharField()
+    mascotAnimation = serializers.CharField()
+
+
+# ---- Lesson questions ----
+
+class ChoiceOptionSerializer(serializers.Serializer):
+    id = serializers.CharField()
+    value = serializers.CharField()
+
+
+class QuestionSerializer(serializers.Serializer):
+    id = serializers.CharField()
+    type = serializers.CharField()
+    prompt = serializers.CharField()
+    options = ChoiceOptionSerializer(many=True)
+
+
+class LessonQuestionsResponseSerializer(serializers.Serializer):
+    questions = QuestionSerializer(many=True)
+
+
+# ---- Answer submission ----
+
+class AnswerRequestSerializer(serializers.Serializer):
+    selectedOptionId = serializers.IntegerField()
+
+
+class AnswerResponseSerializer(serializers.Serializer):
+    correct = serializers.BooleanField()
+    correctOptionId = serializers.CharField()
+    xpEarned = serializers.IntegerField()
+    heartsRemaining = serializers.IntegerField()
+
+
+# ---- Lesson completion ----
+
+class LessonCompleteRequestSerializer(serializers.Serializer):
+    correctCount = serializers.IntegerField()
+    totalQuestions = serializers.IntegerField()
+
+
+class LessonCompleteResponseSerializer(serializers.Serializer):
+    stars = serializers.IntegerField()
+    xpEarned = serializers.IntegerField()
+    coinsEarned = serializers.IntegerField()
+    stats = StatsSerializer()

content/tests.py

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

content/urls.py

@@ -0,0 +1,19 @@
+from django.urls import path
+
+from .views import (
+    GradesListView,
+    HomeView,
+    LessonCompleteView,
+    LessonIntroView,
+    LessonQuestionsView,
+    QuestionAnswerView,
+)
+
+urlpatterns = [
+    path('grades', GradesListView.as_view(), name='grades-list'),
+    path('home', HomeView.as_view(), name='home'),
+    path('lessons/<int:lesson_id>/intro', LessonIntroView.as_view(), name='lesson-intro'),
+    path('lessons/<int:lesson_id>/questions', LessonQuestionsView.as_view(), name='lesson-questions'),
+    path('lessons/<int:lesson_id>/complete', LessonCompleteView.as_view(), name='lesson-complete'),
+    path('questions/<int:question_id>/answer', QuestionAnswerView.as_view(), name='question-answer'),
+]

content/views.py

@@ -0,0 +1,247 @@
+from django.db.models import Sum
+from django.shortcuts import get_object_or_404
+from drf_spectacular.types import OpenApiTypes
+from drf_spectacular.utils import OpenApiParameter, extend_schema
+from rest_framework import status
+from rest_framework.permissions import IsAuthenticated
+from rest_framework.response import Response
+from rest_framework.views import APIView
+
+from progress.models import UserHearts, UserStats
+
+from .models import Choice, Grade, Lesson, Question, UserAnswer, UserLessonCompletion
+from .serializers import (
+    AnswerRequestSerializer,
+    AnswerResponseSerializer,
+    GradesListResponseSerializer,
+    HomeResponseSerializer,
+    LessonCompleteRequestSerializer,
+    LessonCompleteResponseSerializer,
+    LessonIntroResponseSerializer,
+    LessonQuestionsResponseSerializer,
+)
+
+
+class GradesListView(APIView):
+    """GET /api/grades — لیست پایه‌ها"""
+
+    @extend_schema(responses=GradesListResponseSerializer, tags=['Curriculum (content)'])
+    def get(self, request):
+        grades = Grade.objects.all().order_by('id')
+        data = {'grades': [
+            {'id': g.id, 'title': g.title, 'icon': g.icon, 'color': g.color} for g in grades
+        ]}
+        return Response(GradesListResponseSerializer(data).data)
+
+
+def _node_status(node, user_id, is_first_unlocked_candidate):
+    lesson_ids = list(node.lessons.values_list('id', flat=True))
+    if not lesson_ids:
+        return 'locked'
+    completed_count = UserLessonCompletion.objects.filter(
+        user_id=user_id, lesson_id__in=lesson_ids
+    ).values('lesson_id').distinct().count()
+    if completed_count >= len(lesson_ids):
+        return 'completed'
+    if completed_count > 0 or is_first_unlocked_candidate:
+        return 'unlocked'
+    return 'locked'
+
+
+class HomeView(APIView):
+    """GET /api/home?userId&grade — نقشه‌ی مهارت‌ها + آمار (ادغام‌شده)"""
+
+    @extend_schema(
+        parameters=[
+            OpenApiParameter('userId', OpenApiTypes.INT, required=True),
+            OpenApiParameter('grade', OpenApiTypes.INT, required=False),
+        ],
+        responses=HomeResponseSerializer,
+        tags=['Curriculum (content)'],
+    )
+    def get(self, request):
+        user_id = request.query_params.get('userId')
+        grade_id = request.query_params.get('grade')
+        if not user_id:
+            return Response({'detail': 'پارامتر userId الزامی است.'}, status=status.HTTP_400_BAD_REQUEST)
+        user_id = int(user_id)
+
+        units_qs = Grade.objects.get(pk=grade_id).units.all() if grade_id else []
+
+        units_payload = []
+        for unit in units_qs:
+            nodes = list(unit.nodes.all())
+            node_payload = []
+            unlock_next = True  # اولین نودِ قفل‌نشده در هر واحد، باز می‌مونه
+            for node in nodes:
+                node_status = _node_status(node, user_id, unlock_next)
+                if node_status != 'completed':
+                    unlock_next = False
+                node_payload.append({'id': str(node.id), 'title': node.title, 'status': node_status})
+            units_payload.append({'id': str(unit.id), 'title': unit.title, 'nodes': node_payload})
+
+        stats = UserStats.objects.filter(user_id=user_id).first()
+        stats_payload = {
+            'progressPercent': stats.progress_percent if stats else 0,
+            'xp': stats.xp if stats else 0,
+            'coins': stats.coins if stats else 0,
+        }
+
+        data = {'units': units_payload, 'stats': stats_payload}
+        return Response(HomeResponseSerializer(data).data)
+
+
+class LessonIntroView(APIView):
+    """GET /api/lessons/{id}/intro"""
+
+    @extend_schema(responses=LessonIntroResponseSerializer, tags=['Curriculum (content)'])
+    def get(self, request, lesson_id):
+        lesson = get_object_or_404(Lesson, pk=lesson_id)
+        data = {
+            'lessonId': str(lesson.id),
+            'title': lesson.title,
+            'introText': lesson.intro_text,
+            'mascotAnimation': lesson.mascot_animation,
+        }
+        return Response(LessonIntroResponseSerializer(data).data)
+
+
+class LessonQuestionsView(APIView):
+    """GET /api/lessons/{id}/questions"""
+
+    @extend_schema(responses=LessonQuestionsResponseSerializer, tags=['Curriculum (content)'])
+    def get(self, request, lesson_id):
+        lesson = get_object_or_404(Lesson, pk=lesson_id)
+        questions = lesson.questions.prefetch_related('choices').all()
+        data = {'questions': [
+            {
+                'id': str(q.id),
+                'type': q.type,
+                'prompt': q.prompt,
+                'options': [{'id': str(c.id), 'value': c.value} for c in q.choices.all()],
+            }
+            for q in questions
+        ]}
+        return Response(LessonQuestionsResponseSerializer(data).data)
+
+
+class QuestionAnswerView(APIView):
+    """POST /api/questions/{id}/answer — ثبت پاسخ"""
+
+    # ⚠️ اصلاح امنیتی: قبلاً userId از query/body کلاینت خونده می‌شد که به
+    # کلاینت اجازه می‌داد به‌جای هر کاربر دیگری پاسخ ثبت کنه (heart/xp کاربر
+    # دلخواه رو تغییر بده). حالا auth اجباریه و همیشه از request.user.id
+    # (که از توکن معتبر استخراج شده) استفاده می‌شه.
+    permission_classes = [IsAuthenticated]
+
+    @extend_schema(
+        request=AnswerRequestSerializer,
+        responses=AnswerResponseSerializer,
+        tags=['Curriculum (content)'],
+    )
+    def post(self, request, question_id):
+        question = get_object_or_404(Question, pk=question_id)
+        serializer = AnswerRequestSerializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+        selected_option_id = serializer.validated_data['selectedOptionId']
+
+        choice = get_object_or_404(Choice, pk=selected_option_id, question=question)
+        correct_choice = question.choices.filter(is_correct=True).first()
+
+        user_id = request.user.id
+        xp_earned = 10 if choice.is_correct else 0
+
+        UserAnswer.objects.create(
+            user_id=user_id,
+            question=question,
+            choice=choice,
+            correct=choice.is_correct,
+            xp_earned=xp_earned,
+        )
+        if not choice.is_correct:
+            hearts, _ = UserHearts.objects.get_or_create(user_id=user_id)
+            if hearts.current_hearts > 0:
+                hearts.current_hearts -= 1
+                hearts.save(update_fields=['current_hearts'])
+            hearts_remaining = hearts.current_hearts
+        else:
+            hearts = UserHearts.objects.filter(user_id=user_id).first()
+            hearts_remaining = hearts.current_hearts if hearts else 5
+
+        data = {
+            'correct': choice.is_correct,
+            'correctOptionId': str(correct_choice.id) if correct_choice else '',
+            'xpEarned': xp_earned,
+            'heartsRemaining': hearts_remaining if hearts_remaining is not None else 5,
+        }
+        return Response(AnswerResponseSerializer(data).data)
+
+
+class LessonCompleteView(APIView):
+    """POST /api/lessons/{id}/complete — اتمام درس + آمار جدید"""
+
+    # ⚠️ اصلاح امنیتی: قبلاً userId از query/body کلاینت خونده می‌شد که به
+    # کلاینت اجازه می‌داد به‌جای هر کاربر دیگری xp/coins ثبت کنه. حالا auth
+    # اجباریه و همیشه از request.user.id استفاده می‌شه.
+    permission_classes = [IsAuthenticated]
+
+    @extend_schema(
+        request=LessonCompleteRequestSerializer,
+        responses=LessonCompleteResponseSerializer,
+        tags=['Curriculum (content)'],
+    )
+    def post(self, request, lesson_id):
+        lesson = get_object_or_404(Lesson, pk=lesson_id)
+        serializer = LessonCompleteRequestSerializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+        correct_count = serializer.validated_data['correctCount']
+        total_questions = serializer.validated_data['totalQuestions'] or 1
+
+        ratio = correct_count / total_questions
+        stars = 3 if ratio >= 0.9 else 2 if ratio >= 0.6 else 1 if ratio > 0 else 0
+        potential_xp = correct_count * 10
+        potential_coins = stars * 5
+
+        user_id = request.user.id
+
+        # ⚠️ اصلاح: تکمیل هر درس یک‌بارمصرفه — دفعات بعدیِ تکمیل همون درس
+        # نباید دوباره xp/coins به آمار کاربر اضافه کنه (قبلاً هر بار
+        # تکمیل، xp_earned/coins_earned رو بدون قید به stats اضافه می‌کرد).
+        is_first_completion = not UserLessonCompletion.objects.filter(
+            user_id=user_id, lesson=lesson
+        ).exists()
+        xp_earned = potential_xp if is_first_completion else 0
+        coins_earned = potential_coins if is_first_completion else 0
+
+        UserLessonCompletion.objects.create(
+            user_id=user_id,
+            lesson=lesson,
+            correct_count=correct_count,
+            stars=stars,
+            xp_earned=xp_earned,
+            coins_earned=coins_earned,
+        )
+        stats, _ = UserStats.objects.get_or_create(user_id=user_id)
+        stats.xp += xp_earned
+        stats.coins += coins_earned
+
+        total_lessons = Lesson.objects.count() or 1
+        completed_lessons = UserLessonCompletion.objects.filter(
+            user_id=user_id
+        ).values('lesson_id').distinct().count()
+        stats.progress_percent = round(min(completed_lessons / total_lessons, 1.0) * 100, 2)
+        stats.save(update_fields=['xp', 'coins', 'progress_percent'])
+
+        stats_payload = {
+            'progressPercent': stats.progress_percent,
+            'xp': stats.xp,
+            'coins': stats.coins,
+        }
+
+        data = {
+            'stars': stars,
+            'xpEarned': xp_earned,
+            'coinsEarned': coins_earned,
+            'stats': stats_payload,
+        }
+        return Response(LessonCompleteResponseSerializer(data).data)