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.

openedx/core/djangoapps/agreements/api.py

@@ -3,17 +3,15 @@
 """
 
 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 LTIPIISignature
-
-from .data import LTIToolsReceivingPIIData
-from .data import LTIPIISignatureData
+from .data import LTIPIISignatureData, LTIToolsReceivingPIIData, UserAgreementRecordData
+from .models import IntegritySignature, LTIPIISignature, LTIPIITool, UserAgreementRecord
 
 log = logging.getLogger(__name__)
 User = get_user_model()
@@ -240,3 +238,50 @@ 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]:
+    """
+    Retrieves all the agreements that the specified user has acknowledged.
+    """
+    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]:
+    """
+    Retrieve the user agreement record for the specified user and agreement type.
+
+    An agreement update timestamp can be provided to return a record only if it
+    was signed after that timestamp.
+    """
+    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:
+    """
+    Creates a user agreement record if one doesn't already exist, or updates existing
+    record to current timestamp.
+    """
+    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,8 +1,13 @@
 """
 Public data structures for this app.
 """
+from dataclasses import dataclass
+from datetime import datetime
+
 import attr
 
+from .models import UserAgreementRecord
+
 
 @attr.s(frozen=True, auto_attribs=True)
 class LTIToolsReceivingPIIData:
@@ -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,22 @@ 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'
+        # A user can only have a single record for a single agreement type.
+        unique_together = [['user', 'agreement_type']]

openedx/core/djangoapps/agreements/serializers.py

@@ -3,9 +3,10 @@
 """
 from rest_framework import serializers
 
-from openedx.core.djangoapps.agreements.models import IntegritySignature, LTIPIISignature
 from openedx.core.lib.api.serializers import CourseKeyField
 
+from .models import IntegritySignature, LTIPIISignature
+
 
 class IntegritySignatureSerializer(serializers.ModelSerializer):
     """
@@ -31,3 +32,12 @@ class LTIPIISignatureSerializer(serializers.ModelSerializer):
     class Meta:
         model = LTIPIISignature
         fields = ('username', 'course_id', 'lti_tools', 'created_at')
+
+
+class UserAgreementsSerializer(serializers.Serializer):
+    """
+    Serializer for UserAgreementRecord model
+    """
+    accepted_at = serializers.DateTimeField()
+    agreement_type = serializers.CharField(read_only=True)
+    username = serializers.CharField(read_only=True)

openedx/core/djangoapps/agreements/tests/test_api.py

@@ -2,25 +2,29 @@
 Tests for the Agreements API
 """
 import logging
+from datetime import datetime, timedelta
 
+from django.test import TestCase
+from opaque_keys.edx.keys import CourseKey
 from testfixtures import LogCapture
 
 from common.djangoapps.student.tests.factories import UserFactory
-from openedx.core.djangoapps.agreements.api import (
+from openedx.core.djangolib.testing.utils import skip_unless_lms
+from xmodule.modulestore.tests.django_utils import SharedModuleStoreTestCase
+from xmodule.modulestore.tests.factories import CourseFactory
+
+from ..api import (
     create_integrity_signature,
+    create_lti_pii_signature,
+    create_user_agreement_record,
     get_integrity_signature,
     get_integrity_signatures_for_course,
+    get_lti_pii_signature,
     get_pii_receiving_lti_tools,
-    create_lti_pii_signature,
-    get_lti_pii_signature
+    get_user_agreement_record,
+    get_user_agreements
 )
-from openedx.core.djangolib.testing.utils import skip_unless_lms
-from xmodule.modulestore.tests.django_utils import SharedModuleStoreTestCase  # lint-amnesty, pylint: disable=wrong-import-order
-from xmodule.modulestore.tests.factories import CourseFactory  # lint-amnesty, pylint: disable=wrong-import-order
-from ..models import (
-    LTIPIITool,
-)
-from opaque_keys.edx.keys import CourseKey
+from ..models import LTIPIITool
 
 LOGGER_NAME = "openedx.core.djangoapps.agreements.api"
 
@@ -186,3 +190,37 @@ def _assert_ltitools(self, lti_list):
         Helper function to assert the returned list has the correct tools
         """
         self.assertEqual(self.lti_tools, lti_list)
+
+
+@skip_unless_lms
+class UserAgreementsTests(TestCase):
+    """
+    Tests for the python APIs related to user agreements.
+    """
+    def setUp(self):
+        self.user = UserFactory()
+
+    def test_get_user_agreements(self, ):
+        result = list(get_user_agreements(self.user))
+        assert len(result) == 0
+
+        record = create_user_agreement_record(self.user, 'test_type')
+        result = list(get_user_agreements(self.user))
+
+        assert len(result) == 1
+        assert result[0].agreement_type == 'test_type'
+        assert result[0].username == self.user.username
+        assert result[0].accepted_at == record.accepted_at
+
+    def test_get_user_agreement_record(self):
+        record = create_user_agreement_record(self.user, 'test_type')
+        result = get_user_agreement_record(self.user, 'test_type')
+
+        assert result == record
+
+        result = get_user_agreement_record(self.user, 'test_type', datetime.now() + timedelta(days=1))
+
+        assert result is None
+
+    def tearDown(self):
+        self.user.delete()

openedx/core/djangoapps/agreements/tests/test_views.py

@@ -2,26 +2,28 @@
 Tests for agreements views
 """
 
+import json
 from datetime import datetime, timedelta
 from unittest.mock import patch
 
 from django.conf import settings
 from django.urls import reverse
-from rest_framework.test import APITestCase
-from rest_framework import status
 from freezegun import freeze_time
-import json
+from rest_framework import status
+from rest_framework.test import APITestCase
 
-from common.djangoapps.student.tests.factories import UserFactory, AdminFactory
 from common.djangoapps.student.roles import CourseStaffRole
-from openedx.core.djangoapps.agreements.api import (
+from common.djangoapps.student.tests.factories import AdminFactory, UserFactory
+from openedx.core.djangolib.testing.utils import skip_unless_lms
+from xmodule.modulestore.tests.django_utils import ModuleStoreTestCase
+from xmodule.modulestore.tests.factories import CourseFactory
+
+from ..api import (
     create_integrity_signature,
+    create_user_agreement_record,
     get_integrity_signatures_for_course,
     get_lti_pii_signature
 )
-from openedx.core.djangolib.testing.utils import skip_unless_lms
-from xmodule.modulestore.tests.django_utils import ModuleStoreTestCase  # lint-amnesty, pylint: disable=wrong-import-order
-from xmodule.modulestore.tests.factories import CourseFactory  # lint-amnesty, pylint: disable=wrong-import-order
 
 
 @skip_unless_lms
@@ -289,3 +291,49 @@ def test_post_lti_pii_signature(self):
         signature = get_lti_pii_signature(self.user.username, self.course_id)
         self.assertEqual(signature.user.username, self.user.username)
         self.assertEqual(signature.lti_tools, self.lti_tools)
+
+
+@skip_unless_lms
+class UserAgreementsViewTests(APITestCase):
+    """
+    Tests for the UserAgreementsView
+    """
+
+    def setUp(self):
+        self.user = UserFactory(username="testuser", password="password")
+        self.client.login(username="testuser", password="password")
+        self.url = reverse('user_agreements', kwargs={'agreement_type': 'sample_agreement'})
+
+    def test_get_user_agreement_record_no_data(self):
+        response = self.client.get(self.url)
+        assert response.status_code == status.HTTP_404_NOT_FOUND
+
+    def test_get_user_agreement_record_invalid_date(self):
+        response = self.client.get(self.url, {'after': 'invalid_date'})
+        assert response.status_code == status.HTTP_400_BAD_REQUEST
+
+    def test_get_user_agreement_record(self):
+        create_user_agreement_record(self.user, 'sample_agreement')
+        response = self.client.get(self.url)
+        assert response.status_code == status.HTTP_200_OK
+        assert 'accepted_at' in response.data
+
+        response = self.client.get(self.url, {"after": str(datetime.now() + timedelta(days=1))})
+        assert response.status_code == status.HTTP_404_NOT_FOUND
+
+    def test_post_user_agreement(self):
+        with freeze_time("2024-11-21 12:00:00"):
+            response = self.client.post(self.url)
+        assert response.status_code == status.HTTP_201_CREATED
+
+        response = self.client.get(self.url)
+        assert response.status_code == status.HTTP_200_OK
+
+        response = self.client.get(self.url, {"after": "2024-11-21T13:00:00Z"})
+        assert response.status_code == status.HTTP_404_NOT_FOUND
+
+        response = self.client.post(self.url)
+        assert response.status_code == status.HTTP_201_CREATED
+
+        response = self.client.get(self.url, {"after": "2024-11-21T13:00:00Z"})
+        assert response.status_code == status.HTTP_200_OK

openedx/core/djangoapps/agreements/urls.py

@@ -3,9 +3,9 @@
 """
 
 from django.conf import settings
-from django.urls import re_path
+from django.urls import path, re_path
 
-from .views import IntegritySignatureView, LTIPIISignatureView
+from .views import IntegritySignatureView, LTIPIISignatureView, UserAgreementsView
 
 urlpatterns = [
     re_path(r'^integrity_signature/{course_id}$'.format(
@@ -14,4 +14,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"),
 ]