feat: #129 Add enrollment API

Author: payamnj

django_email_learning/migrations/0001_initial.py

@@ -1,4 +1,4 @@
-# Generated by Django 6.0.1 on 2026-01-09 11:59
+# Generated by Django 6.0.1 on 2026-01-17 05:42
 
 import django.core.validators
 import django.db.models.deletion
@@ -286,7 +286,7 @@ class Migration(migrations.Migration):
                         db_index=True, default=django.utils.timezone.now
                     ),
                 ),
-                ("link", models.URLField(blank=True, null=True)),
+                ("link", models.URLField(blank=True, max_length=500, null=True)),
                 (
                     "status",
                     models.CharField(
@@ -309,6 +309,14 @@ class Migration(migrations.Migration):
                                 ],
                                 "Delivered",
                             ),
+                            (
+                                django_email_learning.models.DeliveryStatus["CANCELED"],
+                                "Canceled",
+                            ),
+                            (
+                                django_email_learning.models.DeliveryStatus["BLOCKED"],
+                                "Blocked",
+                            ),
                         ],
                         db_index=True,
                         default=django_email_learning.models.DeliveryStatus[
@@ -317,6 +325,7 @@ class Migration(migrations.Migration):
                         max_length=50,
                     ),
                 ),
+                ("failed_attempts", models.IntegerField(default=0)),
                 (
                     "delivery",
                     models.ForeignKey(
@@ -340,6 +349,8 @@ class Migration(migrations.Migration):
                     ),
                 ),
                 ("enrolled_at", models.DateTimeField(auto_now_add=True)),
+                ("activated_at", models.DateTimeField(blank=True, null=True)),
+                ("final_state_at", models.DateTimeField(blank=True, null=True)),
                 (
                     "status",
                     models.CharField(
@@ -432,6 +443,7 @@ class Migration(migrations.Migration):
             name="enrollment",
             field=models.ForeignKey(
                 on_delete=django.db.models.deletion.CASCADE,
+                related_name="content_deliveries",
                 to="django_email_learning.enrollment",
             ),
         ),
@@ -445,6 +457,14 @@ class Migration(migrations.Migration):
                 to="django_email_learning.imapconnection",
             ),
         ),
+        migrations.AddField(
+            model_name="learner",
+            name="organization",
+            field=models.ForeignKey(
+                on_delete=django.db.models.deletion.CASCADE,
+                to="django_email_learning.organization",
+            ),
+        ),
         migrations.AddField(
             model_name="imapconnection",
             name="organization",
@@ -554,6 +574,7 @@ class Migration(migrations.Migration):
                     "delivery",
                     models.ForeignKey(
                         on_delete=django.db.models.deletion.CASCADE,
+                        related_name="quiz_submissions",
                         to="django_email_learning.contentdelivery",
                     ),
                 ),

django_email_learning/migrations/0002_learner_organization_alter_deliveryschedule_link.py

@@ -356,6 +356,8 @@ class Enrollment(models.Model):
     learner = models.ForeignKey(Learner, on_delete=models.CASCADE)
     course = models.ForeignKey(Course, on_delete=models.CASCADE)
     enrolled_at = models.DateTimeField(auto_now_add=True)
+    activated_at = models.DateTimeField(null=True, blank=True)
+    final_state_at = models.DateTimeField(null=True, blank=True)
     status = models.CharField(
         max_length=50,
         choices=[
@@ -400,6 +402,12 @@ def save(self, *args, **kwargs) -> None:  # type: ignore[no-untyped-def]
                 "Deactivation reason must be provided when status is 'deactivated'."
             )
         self.full_clean()
+        if self.status == EnrollmentStatus.ACTIVE and self.activated_at is None:
+            self.activated_at = timezone.now()
+        if self.status in [EnrollmentStatus.COMPLETED, EnrollmentStatus.DEACTIVATED]:
+            if self.final_state_at is None:
+                self.final_state_at = timezone.now()
+
         super().save(*args, **kwargs)
 
     def __str__(self) -> str:
@@ -418,6 +426,7 @@ def graduate(self) -> None:
         if self.status != EnrollmentStatus.ACTIVE:
             raise ValidationError("Only active enrollments can be marked as completed.")
         self.status = EnrollmentStatus.COMPLETED
+        self.final_state_at = timezone.now()
         logger.info(
             f"Learner ID {self.learner.id} has completed the course {self.course.title}."
         )
@@ -430,6 +439,7 @@ def fail(self) -> None:
             raise ValidationError("Only active enrollments can be marked as failed.")
         self.status = EnrollmentStatus.DEACTIVATED
         self.deactivation_reason = DeactivationReason.FAILED
+        self.final_state_at = timezone.now()
         logger.info(
             f"Learner ID {self.learner.id} has failed the course {self.course.title}."
         )
@@ -457,7 +467,9 @@ def schedule_first_content_delivery(self) -> None:
 
 
 class ContentDelivery(models.Model):
-    enrollment = models.ForeignKey(Enrollment, on_delete=models.CASCADE)
+    enrollment = models.ForeignKey(
+        Enrollment, on_delete=models.CASCADE, related_name="content_deliveries"
+    )
     course_content = models.ForeignKey(CourseContent, on_delete=models.CASCADE)
     hash_value = models.CharField(max_length=64, null=True, blank=True)
     valid_until = models.DateTimeField(null=True, blank=True)
@@ -586,7 +598,9 @@ def __str__(self) -> str:
 
 
 class QuizSubmission(models.Model):
-    delivery = models.ForeignKey(ContentDelivery, on_delete=models.CASCADE)
+    delivery = models.ForeignKey(
+        ContentDelivery, on_delete=models.CASCADE, related_name="quiz_submissions"
+    )
     score = models.IntegerField()
     is_passed = models.BooleanField()
     submitted_at = models.DateTimeField(auto_now_add=True)

django_email_learning/migrations/0003_deliveryschedule_failed_attempts_and_more.py

@@ -6,8 +6,10 @@
     field_validator,
     model_validator,
 )
+from datetime import datetime
 from typing import Optional, Literal, Any
 from django_email_learning.models import (
+    DeliveryStatus,
     Organization,
     ImapConnection,
     Lesson,
@@ -17,6 +19,7 @@
     CourseContent,
     Course,
     QuizSelectionStrategy,
+    Enrollment,
     EnrollmentStatus,
 )
 import enum
@@ -112,6 +115,14 @@ class CourseResponse(BaseModel):
     model_config = ConfigDict(from_attributes=True)
 
 
+class CourseSummaryResponse(BaseModel):
+    id: int
+    title: str
+    slug: str
+
+    model_config = ConfigDict(from_attributes=True)
+
+
 class CreateImapConnectionRequest(BaseModel):
     email: str = Field(min_length=1, examples=["user@example.com"])
     password: str = Field(min_length=1, examples=["aSafePassword123!"])
@@ -328,6 +339,145 @@ class LearnerResponse(BaseModel):
     email: str
 
 
+class EventType(enum.StrEnum):
+    REGISTERED = "registered"
+    VERIFIED = "verified"
+    DEACTIVATED = "deactivated"
+    QUIZ_SUBMITED = "quiz_submitted"
+    CONTENT_SENT = "content_sent"
+    COURSE_COMPLETED = "course_completed"
+
+
+class DeactivatedEvent(BaseModel):
+    type: Literal[EventType.DEACTIVATED] = Field(
+        default=EventType.DEACTIVATED, exclude=True
+    )
+    reason: str
+
+
+class QuizSubmitedEvent(BaseModel):
+    type: Literal[EventType.QUIZ_SUBMITED] = Field(
+        default=EventType.QUIZ_SUBMITED, exclude=True
+    )
+    quiz_id: int
+    quiz_title: str
+    score: int
+    is_passed: bool
+    attempt_number: int
+
+
+class ContentSentEvent(BaseModel):
+    type: Literal[EventType.CONTENT_SENT] = Field(
+        default=EventType.CONTENT_SENT, exclude=True
+    )
+    course_content_id: int
+    course_content_title: str
+    course_content_type: str
+
+
+class Event(BaseModel):
+    type: EventType
+    timestamp: datetime
+    event_data: DeactivatedEvent | QuizSubmitedEvent | ContentSentEvent | None = Field(
+        discriminator="type"
+    )  # REGISTERED, VERIFIED, COURSE_COMPLETED have no additional data
+
+
+class EnrollmentResponse(BaseModel):
+    id: int
+    learner: LearnerResponse
+    course: CourseSummaryResponse
+    status: EnrollmentStatus
+    events: list[Event]
+
+    @staticmethod
+    def from_django_model(enrollment: Enrollment) -> "EnrollmentResponse":
+        events = [
+            Event(
+                type=EventType.REGISTERED,
+                timestamp=enrollment.enrolled_at,
+                event_data=None,
+            )
+        ]
+        if enrollment.activated_at:
+            events.append(
+                Event(
+                    type=EventType.VERIFIED,
+                    timestamp=enrollment.activated_at,
+                    event_data=None,
+                )
+            )
+        for delivery in enrollment.content_deliveries.all():  # type: ignore[attr-defined]
+            for schedule in delivery.delivery_schedules.filter(
+                status=DeliveryStatus.DELIVERED
+            ):
+                events.append(
+                    Event(
+                        type=EventType.CONTENT_SENT,
+                        timestamp=schedule.time,
+                        event_data=ContentSentEvent(
+                            course_content_id=delivery.course_content.id,
+                            course_content_title=delivery.course_content.lesson.title
+                            if delivery.course_content.lesson
+                            else delivery.course_content.quiz.title,
+                            course_content_type=delivery.course_content.type,
+                        ),
+                    )
+                )
+                if delivery.course_content.type == "quiz":
+                    attempt_number = 0
+                    quiz_attempts = delivery.quiz_submissions.all().order_by(
+                        "submitted_at"
+                    )
+                    for attempt in quiz_attempts:
+                        attempt_number += 1
+                        events.append(
+                            Event(
+                                type=EventType.QUIZ_SUBMITED,
+                                timestamp=attempt.submitted_at,
+                                event_data=QuizSubmitedEvent(
+                                    quiz_id=delivery.course_content.quiz.id,
+                                    quiz_title=delivery.course_content.quiz.title,
+                                    score=attempt.score,
+                                    is_passed=attempt.is_passed,
+                                    attempt_number=attempt_number,
+                                ),
+                            )
+                        )
+        if (
+            enrollment.status == EnrollmentStatus.COMPLETED
+            and enrollment.final_state_at
+        ):
+            events.append(
+                Event(
+                    type=EventType.COURSE_COMPLETED,
+                    timestamp=enrollment.final_state_at,
+                    event_data=None,
+                )
+            )
+        elif (
+            enrollment.status == EnrollmentStatus.DEACTIVATED
+            and enrollment.final_state_at
+        ):
+            events.append(
+                Event(
+                    type=EventType.DEACTIVATED,
+                    timestamp=enrollment.final_state_at,
+                    event_data=DeactivatedEvent(reason=enrollment.deactivation_reason),  # type: ignore[arg-type]
+                )
+            )
+
+        return EnrollmentResponse.model_validate(
+            {
+                "id": enrollment.id,
+                "learner": enrollment.learner,
+                "course": enrollment.course,
+                "status": enrollment.status,
+                "events": events,
+            }
+        )
+
+
 class LearnerDetailResponse(BaseModel):
     id: int
     email: str