feat: User agreements API for generic agreement records

This change adds a new kind of generic user agreement that allows plugins or
even the core platform to record a user's acknowledgement of an agreement.

Author: xitij2000

openedx/core/djangoapps/agreements/api.py

@@ -3,17 +3,18 @@
 """
 
 import logging
+from datetime import datetime
+from typing import Iterable, Optional
 
 from django.contrib.auth import get_user_model
 from django.core.exceptions import ObjectDoesNotExist
 from opaque_keys.edx.keys import CourseKey
 
-from openedx.core.djangoapps.agreements.models import IntegritySignature
-from openedx.core.djangoapps.agreements.models import LTIPIITool
+from openedx.core.djangoapps.agreements.models import IntegritySignature, UserAgreementRecord
 from openedx.core.djangoapps.agreements.models import LTIPIISignature
-
-from .data import LTIToolsReceivingPIIData
+from openedx.core.djangoapps.agreements.models import LTIPIITool
 from .data import LTIPIISignatureData
+from .data import LTIToolsReceivingPIIData, UserAgreementRecordData
 
 log = logging.getLogger(__name__)
 User = get_user_model()
@@ -240,3 +241,38 @@ def _user_signature_out_of_date(username, course_id):
         return False
     else:
         return user_lti_pii_signature_hash != course_lti_pii_tools_hash
+
+
+def get_user_agreements(user: User) -> Iterable[UserAgreementRecordData]:
+    for agreement_record in UserAgreementRecord.objects.filter(user=user):
+        yield UserAgreementRecordData.from_model(agreement_record)
+
+
+def get_user_agreement_record(
+    user: User,
+    agreement_type: str,
+    agreement_update_timestamp: datetime = None,
+) -> Optional[UserAgreementRecordData]:
+    try:
+        record_query = UserAgreementRecord.objects.filter(
+            user=user,
+            agreement_type=agreement_type,
+        )
+        if agreement_update_timestamp:
+            record_query = record_query.filter(timestamp__gte=agreement_update_timestamp)
+        record = record_query.get()
+        return UserAgreementRecordData.from_model(record)
+    except UserAgreementRecord.DoesNotExist:
+        return None
+
+
+def create_user_agreement_record(user: User, agreement_type: str) -> UserAgreementRecordData:
+    record, _ = UserAgreementRecord.objects.update_or_create(
+        user=user,
+        agreement_type=agreement_type,
+        defaults={
+            "timestamp": datetime.now(),
+        },
+    )
+    return UserAgreementRecordData.from_model(record)
+

openedx/core/djangoapps/agreements/data.py

@@ -1,7 +1,12 @@
 """
 Public data structures for this app.
 """
+from datetime import datetime
+
 import attr
+from dataclasses import dataclass
+
+from openedx.core.djangoapps.agreements.models import UserAgreementRecord
 
 
 @attr.s(frozen=True, auto_attribs=True)
@@ -21,3 +26,21 @@ class LTIPIISignatureData:
     course_id: str
     lti_tools: str
     lti_tools_hash: str
+
+
+@dataclass
+class UserAgreementRecordData:
+    """
+    Data for a single user agreement record.
+    """
+    username: str
+    agreement_type: str
+    accepted_at: datetime
+
+    @classmethod
+    def from_model(cls, model: UserAgreementRecord):
+        return UserAgreementRecordData(
+            username=model.user.username,
+            agreement_type=model.agreement_type,
+            accepted_at=model.timestamp,
+        )

openedx/core/djangoapps/agreements/migrations/0006_useragreementrecord.py

@@ -0,0 +1,28 @@
+# Generated by Django 4.2.16 on 2024-11-14 11:47
+
+from django.conf import settings
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+        ('agreements', '0005_timestampedmodels'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='UserAgreementRecord',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('agreement_type', models.CharField(max_length=255)),
+                ('timestamp', models.DateTimeField(auto_now_add=True)),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'unique_together': {('user', 'agreement_type')},
+            },
+        ),
+    ]

openedx/core/djangoapps/agreements/models.py

@@ -70,3 +70,20 @@ class ProctoringPIISignature(TimeStampedModel):
 
     class Meta:
         app_label = 'agreements'
+
+class UserAgreementRecord(models.Model):
+    """
+    This model stores the agreements a user has accepted or acknowledged.
+
+    Each record here represents a user agreeing to the agreement type represented
+    by `agreement_type`.
+
+    .. no_pii:
+    """
+    user = models.ForeignKey(User, db_index=True, on_delete=models.CASCADE)
+    agreement_type = models.CharField(max_length=255)
+    timestamp = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        app_label = 'agreements'
+        unique_together = [['user', 'agreement_type']]

openedx/core/djangoapps/agreements/serializers.py

@@ -3,7 +3,7 @@
 """
 from rest_framework import serializers
 
-from openedx.core.djangoapps.agreements.models import IntegritySignature, LTIPIISignature
+from openedx.core.djangoapps.agreements.models import IntegritySignature, LTIPIISignature, UserAgreementRecord
 from openedx.core.lib.api.serializers import CourseKeyField
 
 
@@ -31,3 +31,6 @@ class LTIPIISignatureSerializer(serializers.ModelSerializer):
     class Meta:
         model = LTIPIISignature
         fields = ('username', 'course_id', 'lti_tools', 'created_at')
+
+class UserAgreementsSerializer(serializers.Serializer):
+    accepted_at = serializers.DateTimeField()

openedx/core/djangoapps/agreements/urls.py

@@ -3,9 +3,10 @@
 """
 
 from django.conf import settings
-from django.urls import re_path
+from django.urls import re_path, path
+from django.urls.conf import include
 
-from .views import IntegritySignatureView, LTIPIISignatureView
+from .views import IntegritySignatureView, LTIPIISignatureView, UserAgreementsView
 
 urlpatterns = [
     re_path(r'^integrity_signature/{course_id}$'.format(
@@ -14,4 +15,5 @@
     re_path(r'^lti_pii_signature/{course_id}$'.format(
         course_id=settings.COURSE_ID_PATTERN
     ), LTIPIISignatureView.as_view(), name='lti_pii_signature'),
+    path("agreement/<slug:agreement_type>", UserAgreementsView.as_view(), name="user_agreements"),
 ]

openedx/core/djangoapps/agreements/views.py

@@ -1,8 +1,10 @@
 """
 Views served by the Agreements app
 """
+from os import times
 
 from django.conf import settings
+from django import forms
 from rest_framework import status
 from rest_framework.views import APIView
 from rest_framework.response import Response
@@ -14,9 +16,10 @@
 from openedx.core.djangoapps.agreements.api import (
     create_integrity_signature,
     create_lti_pii_signature,
-    get_integrity_signature,
+    get_integrity_signature, get_user_agreement_record, create_user_agreement_record,
 )
-from openedx.core.djangoapps.agreements.serializers import IntegritySignatureSerializer, LTIPIISignatureSerializer
+from openedx.core.djangoapps.agreements.serializers import IntegritySignatureSerializer, LTIPIISignatureSerializer, \
+    UserAgreementsSerializer
 
 
 def is_user_course_or_global_staff(user, course_id):
@@ -159,3 +162,24 @@ def post(self, request, course_id):
         else:
             statusStr = status.HTTP_500_INTERNAL_SERVER_ERROR
         return Response(data=serializer.data, status=statusStr)
+
+
+class UserAgreementsView(AuthenticatedAPIView):
+
+    class QueryFilterForm(forms.Form):
+        after = forms.DateTimeField(required=False)
+
+    def get(self, request, agreement_type):
+        params = UserAgreementsView.QueryFilterForm(request.query_params)
+        if not params.is_valid():
+            return Response(status=status.HTTP_400_BAD_REQUEST)
+        record = get_user_agreement_record(request.user, agreement_type, params.cleaned_data.get('after'))
+        if record is None:
+            return Response(status=status.HTTP_404_NOT_FOUND)
+        serializer = UserAgreementsSerializer(record)
+        return Response(serializer.data)
+
+    def post(self, request, agreement_type):
+        record = create_user_agreement_record(request.user, agreement_type)
+        serializer = UserAgreementsSerializer(record)
+        return Response(serializer.data, status=status.HTTP_201_CREATED)