Add quiz invitation system with individual student codes

- Add QuizInvitation model for per-student unique codes
- Add roster import endpoint (CSV or JSON)
- Add Resend email service for sending quiz invitations
- Update quiz access/start views to handle invitation codes
- 8-char invitation codes vs 6-char shared access codes
- Invitation tracks: email sent, used, linked submission
- Add RESEND_API_KEY, FROM_EMAIL, BASE_URL settings

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: jsb2092

questionbank/config/settings.py

@@ -148,6 +148,11 @@
 ANTHROPIC_API_KEY = os.getenv('ANTHROPIC_API_KEY', '')
 OPENAI_API_KEY = os.getenv('OPENAI_API_KEY', '')
 
+# Email (Resend)
+RESEND_API_KEY = os.getenv('RESEND_API_KEY', '')
+FROM_EMAIL = os.getenv('FROM_EMAIL', 'quizzes@yourdomain.com')
+BASE_URL = os.getenv('BASE_URL', 'https://mkt-production.up.railway.app')
+
 # Production security settings
 if not DEBUG:
     SECURE_SSL_REDIRECT = True

questionbank/quizzes/migrations/0003_add_quiz_invitation.py

@@ -0,0 +1,36 @@
+# Generated by Django 4.2.27 on 2025-12-12 00:15
+
+from django.db import migrations, models
+import django.db.models.deletion
+import quizzes.models
+import uuid
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('quizzes', '0002_make_template_optional'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='QuizInvitation',
+            fields=[
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('student_name', models.CharField(max_length=200)),
+                ('student_email', models.EmailField(db_index=True, max_length=254)),
+                ('student_id', models.CharField(blank=True, max_length=50)),
+                ('code', models.CharField(db_index=True, default=quizzes.models.generate_invitation_code, max_length=12, unique=True)),
+                ('email_sent_at', models.DateTimeField(blank=True, null=True)),
+                ('email_error', models.TextField(blank=True)),
+                ('used_at', models.DateTimeField(blank=True, null=True)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('quiz_session', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='invitations', to='quizzes.quizsession')),
+                ('submission', models.OneToOneField(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='invitation', to='quizzes.studentsubmission')),
+            ],
+            options={
+                'ordering': ['student_name'],
+                'unique_together': {('quiz_session', 'student_email')},
+            },
+        ),
+    ]

questionbank/quizzes/models.py

@@ -229,6 +229,55 @@ def get_final_score(self):
         return self.points_earned
 
 
+def generate_invitation_code():
+    """Generate a unique 8-character invitation code."""
+    return ''.join(secrets.choice(string.ascii_uppercase + string.digits) for _ in range(8))
+
+
+class QuizInvitation(models.Model):
+    """Individual invitation for a student to take a quiz."""
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    quiz_session = models.ForeignKey(QuizSession, on_delete=models.CASCADE, related_name='invitations')
+
+    # Student info (from roster import)
+    student_name = models.CharField(max_length=200)
+    student_email = models.EmailField(db_index=True)
+    student_id = models.CharField(max_length=50, blank=True)
+
+    # Unique code for this student
+    code = models.CharField(max_length=12, unique=True, default=generate_invitation_code, db_index=True)
+
+    # Email tracking
+    email_sent_at = models.DateTimeField(null=True, blank=True)
+    email_error = models.TextField(blank=True)
+
+    # Usage tracking
+    used_at = models.DateTimeField(null=True, blank=True)
+    submission = models.OneToOneField(
+        'StudentSubmission', on_delete=models.SET_NULL, null=True, blank=True,
+        related_name='invitation'
+    )
+
+    # Audit
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        ordering = ['student_name']
+        unique_together = ['quiz_session', 'student_email']
+
+    def __str__(self):
+        return f"{self.student_name} - {self.quiz_session.name} ({self.code})"
+
+    @property
+    def is_used(self):
+        return self.used_at is not None
+
+    @property
+    def quiz_url(self):
+        return f"/quiz/{self.code}/"
+
+
 class ScannedExam(models.Model):
     """A scanned paper exam uploaded for OCR processing."""
 

questionbank/quizzes/serializers.py

@@ -2,7 +2,7 @@
 Serializers for quiz models.
 """
 from rest_framework import serializers
-from .models import QuizSession, StudentSubmission, QuestionResponse, ScannedExam
+from .models import QuizSession, StudentSubmission, QuestionResponse, ScannedExam, QuizInvitation
 from questions.serializers import QuestionListSerializer
 from exams.serializers import ExamTemplateSerializer
 
@@ -303,3 +303,26 @@ class Meta:
             'ocr_text', 'ocr_confidence', 'extracted_answers',
             'submission', 'uploaded_at', 'processed_at'
         ]
+
+
+class QuizInvitationSerializer(serializers.ModelSerializer):
+    """Serializer for quiz invitations."""
+    quiz_name = serializers.CharField(source='quiz_session.name', read_only=True)
+    quiz_url = serializers.CharField(read_only=True)
+    is_used = serializers.BooleanField(read_only=True)
+
+    class Meta:
+        model = QuizInvitation
+        fields = [
+            'id', 'quiz_session', 'quiz_name',
+            'student_name', 'student_email', 'student_id',
+            'code', 'quiz_url',
+            'email_sent_at', 'email_error',
+            'used_at', 'is_used', 'submission',
+            'created_at'
+        ]
+        read_only_fields = [
+            'id', 'code', 'quiz_url', 'is_used',
+            'email_sent_at', 'email_error',
+            'used_at', 'submission', 'created_at'
+        ]

questionbank/quizzes/services/email.py

@@ -0,0 +1,116 @@
+"""
+Email service for sending quiz invitations via Resend.
+"""
+import resend
+from django.conf import settings
+from django.utils import timezone
+
+
+def send_quiz_invitations(quiz, invitations, request=None):
+    """
+    Send quiz invitation emails to students.
+
+    Args:
+        quiz: QuizSession instance
+        invitations: List of QuizInvitation instances
+        request: Optional HTTP request for building URLs
+
+    Returns:
+        dict with sent, failed counts and errors list
+    """
+    resend.api_key = settings.RESEND_API_KEY
+
+    # Build base URL
+    if request:
+        base_url = f"{request.scheme}://{request.get_host()}"
+    else:
+        base_url = getattr(settings, 'BASE_URL', 'https://mkt-production.up.railway.app')
+
+    from_email = getattr(settings, 'FROM_EMAIL', 'quizzes@updates.yourdomain.com')
+
+    sent = 0
+    failed = 0
+    errors = []
+
+    for invitation in invitations:
+        quiz_url = f"{base_url}/quiz/{invitation.code}/"
+
+        try:
+            # Build email content
+            subject = f"Quiz Invitation: {quiz.name}"
+
+            html_content = f"""
+            <div style="font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto;">
+                <h2 style="color: #0284c7;">Quiz Invitation</h2>
+
+                <p>Hello {invitation.student_name or 'Student'},</p>
+
+                <p>You have been invited to take the following quiz:</p>
+
+                <div style="background: #f0f9ff; padding: 20px; border-radius: 8px; margin: 20px 0;">
+                    <h3 style="margin: 0 0 10px 0; color: #0369a1;">{quiz.name}</h3>
+                    {f'<p style="margin: 0; color: #64748b;">{quiz.description}</p>' if quiz.description else ''}
+                    <p style="margin: 10px 0 0 0; color: #64748b;">
+                        Time limit: {quiz.time_limit_minutes} minutes
+                    </p>
+                </div>
+
+                <p>Click the button below to start your quiz:</p>
+
+                <a href="{quiz_url}"
+                   style="display: inline-block; background: #0284c7; color: white;
+                          padding: 12px 24px; text-decoration: none; border-radius: 6px;
+                          font-weight: bold; margin: 10px 0;">
+                    Start Quiz
+                </a>
+
+                <p style="color: #64748b; font-size: 14px; margin-top: 20px;">
+                    Or copy this link: <a href="{quiz_url}">{quiz_url}</a>
+                </p>
+
+                <p style="color: #94a3b8; font-size: 12px; margin-top: 30px;">
+                    This is your personal quiz link. Do not share it with others.
+                </p>
+            </div>
+            """
+
+            text_content = f"""
+Quiz Invitation: {quiz.name}
+
+Hello {invitation.student_name or 'Student'},
+
+You have been invited to take the quiz: {quiz.name}
+
+Time limit: {quiz.time_limit_minutes} minutes
+
+Click here to start: {quiz_url}
+
+This is your personal quiz link. Do not share it with others.
+            """
+
+            # Send via Resend
+            response = resend.Emails.send({
+                "from": from_email,
+                "to": [invitation.student_email],
+                "subject": subject,
+                "html": html_content,
+                "text": text_content
+            })
+
+            # Update invitation
+            invitation.email_sent_at = timezone.now()
+            invitation.email_error = ''
+            invitation.save(update_fields=['email_sent_at', 'email_error'])
+            sent += 1
+
+        except Exception as e:
+            invitation.email_error = str(e)
+            invitation.save(update_fields=['email_error'])
+            errors.append(f"{invitation.student_email}: {str(e)}")
+            failed += 1
+
+    return {
+        'sent': sent,
+        'failed': failed,
+        'errors': errors
+    }

questionbank/quizzes/urls.py

@@ -10,6 +10,7 @@
 router.register(r'submissions', views.StudentSubmissionViewSet, basename='submissions')
 router.register(r'responses', views.QuestionResponseViewSet, basename='responses')
 router.register(r'scanned', views.ScannedExamViewSet, basename='scanned-exams')
+router.register(r'invitations', views.QuizInvitationViewSet, basename='invitations')
 
 urlpatterns = [
     # Instructor API endpoints (auth required)
@@ -21,6 +22,10 @@
     # Scanned exam upload
     path('scan/upload/', views.ScannedExamUploadView.as_view(), name='scan-upload'),
 
+    # Roster and invitations
+    path('sessions/<uuid:quiz_id>/roster/import/', views.RosterImportView.as_view(), name='roster-import'),
+    path('sessions/<uuid:quiz_id>/invitations/send/', views.SendInvitationsView.as_view(), name='send-invitations'),
+
     # Public student API endpoints (no auth required)
     path('take/<str:code>/', views.QuizAccessView.as_view(), name='quiz-access'),
     path('take/<str:code>/start/', views.QuizStartView.as_view(), name='quiz-start'),