feat: apply OEP-66 queryset-scoping pattern to Enrollments v2 API

openedx/core/djangoapps/enrollments/v2/tests/test_views.py

@@ -10,15 +10,16 @@
   - ADR 0032: list action returns the 7-field DefaultPagination envelope
   - ADR 0033: ordering whitelist + Deprecation header on the admin list
 """
-from unittest.mock import patch
+from unittest.mock import Mock, patch
 
 from django.test import override_settings
 from django.urls import reverse
+from opaque_keys.edx.keys import CourseKey
 from rest_framework import status
 from rest_framework.test import APITestCase
 
-from common.djangoapps.student.tests.factories import AdminFactory, UserFactory
-from openedx.core.djangoapps.enrollments.v2.views import EnrollmentViewSet
+from common.djangoapps.student.tests.factories import AdminFactory, CourseEnrollmentFactory, UserFactory
+from openedx.core.djangoapps.enrollments.v2.views import AdminEnrollmentScopingPolicy, EnrollmentViewSet
 from openedx.core.djangolib.testing.utils import skip_unless_lms
 
 API_KEY = "test-enrollment-v2-api-key"
@@ -287,3 +288,79 @@ def test_minimal_view_collapses_course_details_to_course_id(self, mock_list, moc
         assert {r["course_id"] for r in response.data["results"]} == {
             "course-v1:org+a+r", "course-v1:org+b+r",
         }
+
+
+# ---------------------------------------------------------------------------
+# OEP-66 — EnrollmentsAdminListView (GET /enrollments/)
+# ---------------------------------------------------------------------------
+@skip_unless_lms
+class TestEnrollmentsAdminListView(APITestCase):
+    """
+    OEP-66 + ADR 0026/0033 — regression tests for the admin enrollment list.
+
+    This endpoint adopted ``ScopedQuerysetMixin`` (from edx-drf-extensions) and
+    moved its filtering from ``get_queryset()`` into ``filter_queryset()``. These
+    tests guard that split: endpoint access, the record-visibility pass-through
+    policy, the user-driven filters, the 400-on-invalid-params path (validation
+    now runs in ``filter_queryset``), and the ADR 0033 ``Deprecation`` header.
+    Uses real ``CourseEnrollment`` rows (SQL, MongoDB-free).
+    """
+
+    def setUp(self):
+        super().setUp()
+        self.admin = AdminFactory.create(password="test")
+        self.user = UserFactory.create(password="test")
+        self.url = reverse("v2:enrollment-v2-admin-list")
+        self.course_a = CourseKey.from_string("course-v1:edX+A+run")
+        self.course_b = CourseKey.from_string("course-v1:edX+B+run")
+        self.learner_a = UserFactory.create()
+        self.learner_b = UserFactory.create()
+        CourseEnrollmentFactory.create(user=self.learner_a, course_id=self.course_a)
+        CourseEnrollmentFactory.create(user=self.learner_b, course_id=self.course_b)
+
+    def test_unauthenticated_gets_401(self):
+        assert self.client.get(self.url).status_code == status.HTTP_401_UNAUTHORIZED
+
+    def test_non_admin_gets_403(self):
+        """Endpoint-access layer: IsAdminUser rejects a regular user."""
+        self.client.force_authenticate(user=self.user)
+        assert self.client.get(self.url).status_code == status.HTTP_403_FORBIDDEN
+
+    def test_admin_sees_all_rows(self):
+        """Record-visibility layer is a pass-through: admin sees every enrollment."""
+        self.client.force_authenticate(user=self.admin)
+        response = self.client.get(self.url)
+        assert response.status_code == status.HTTP_200_OK
+        assert response.data["count"] == 2
+
+    def test_filter_by_course_key_narrows(self):
+        """User-driven filter (filter_queryset) still narrows by course_key."""
+        self.client.force_authenticate(user=self.admin)
+        response = self.client.get(self.url, {"course_key": str(self.course_a)})
+        assert response.status_code == status.HTTP_200_OK
+        assert response.data["count"] == 1
+
+    def test_filter_by_username_narrows(self):
+        """User-driven filter (filter_queryset) still narrows by username."""
+        self.client.force_authenticate(user=self.admin)
+        response = self.client.get(self.url, {"username": self.learner_b.username})
+        assert response.status_code == status.HTTP_200_OK
+        assert response.data["count"] == 1
+
+    def test_invalid_course_key_gets_400(self):
+        """Form validation moved to filter_queryset must still surface as a 400."""
+        self.client.force_authenticate(user=self.admin)
+        response = self.client.get(self.url, {"course_key": "not-a-course-key"})
+        assert response.status_code == status.HTTP_400_BAD_REQUEST
+
+    def test_legacy_course_id_emits_deprecation_header(self):
+        """ADR 0033: the legacy ``course_id`` alias still emits the Deprecation header."""
+        self.client.force_authenticate(user=self.admin)
+        response = self.client.get(self.url, {"course_id": str(self.course_a)})
+        assert response.status_code == status.HTTP_200_OK
+        assert "Deprecation" in response.headers
+
+    def test_scoping_policy_is_passthrough(self):
+        """AdminEnrollmentScopingPolicy returns the queryset unchanged (no narrowing today)."""
+        sentinel = Mock()
+        assert AdminEnrollmentScopingPolicy().scope(sentinel, self.admin) is sentinel

openedx/core/djangoapps/enrollments/v2/views.py

@@ -46,6 +46,7 @@
 )
 from edx_rest_framework_extensions.auth.jwt.authentication import JwtAuthentication
 from edx_rest_framework_extensions.paginators import DefaultPagination
+from edx_rest_framework_extensions.scoping import ScopedQuerysetMixin
 from opaque_keys import InvalidKeyError
 from opaque_keys.edx.keys import CourseKey
 from rest_framework import permissions, status, viewsets
@@ -627,6 +628,34 @@ def get(self, request, course_id=None):
 # ===========================================================================
 # EnrollmentsAdminListView — GET /enrollments/  (admin paginated list)
 # ===========================================================================
+class AdminEnrollmentScopingPolicy:
+    """
+    OEP-66 record-visibility policy for the admin enrollment list.
+
+    Implements the ``ScopingPolicy`` protocol from
+    ``edx_rest_framework_extensions.scoping`` by duck typing (a ``scope``
+    method); it does not need to inherit from it.
+
+    This endpoint is a *platform-administration* tool gated by ``IsAdminUser``
+    (see the view's ``permission_classes``). A platform admin's accessible scope
+    is every enrollment, so this policy returns the queryset unchanged.
+
+    **This pass-through is intentional and load-bearing — please do not remove
+    it.** It is the single seam at which a *narrower* visibility rule will be
+    introduced once openedx-authz can resolve enrollment scopes: for example,
+    restricting a delegated (org-scoped) admin to enrollments in their
+    organization's courses by translating a
+    ``get_scopes_for_subject_and_permission`` scope set into a
+    ``course_id__in=...`` / ``course__org__in=...`` filter. Keeping the policy
+    wired now means that change is confined to this one method. No narrowing is
+    applied today, so behavior is unchanged.
+    """
+
+    def scope(self, queryset, subject):
+        # Platform admins (IsAdminUser) see all enrollments; nothing to narrow yet.
+        return queryset
+
+
 @extend_schema(
     tags=["openedx-platform-sdk"],
     summary="List all course enrollments (admin-only, paginated)",
@@ -661,8 +690,24 @@ def get(self, request, course_id=None):
         403: _RESP_FORBIDDEN,
     },
 )
-class EnrollmentsAdminListView(StandardizedErrorMixin, ListAPIView):
-    """Admin-only paginated enrollment list with OEP-68 filter aliases."""
+class EnrollmentsAdminListView(ScopedQuerysetMixin, StandardizedErrorMixin, ListAPIView):
+    """
+    Admin-only paginated enrollment list with OEP-68 filter aliases.
+
+    OEP-66 — this ORM-backed list endpoint wires the three authorization layers
+    separately (see ``edx_rest_framework_extensions.scoping``):
+
+    * **Endpoint access** — ``permission_classes = (IsAdminUser,)``.
+    * **Record visibility (queryset scoping)** — ``ScopedQuerysetMixin`` applies
+      :class:`AdminEnrollmentScopingPolicy` to the base ``queryset`` in
+      ``get_queryset()``. (A pass-through for platform admins today; see the
+      policy docstring for the seam where an openedx-authz scope-set filter
+      plugs in.)
+    * **User-driven filtering** — ``filter_queryset`` applies the caller-supplied
+      ``course_key`` / ``course_keys`` / ``username`` / ``email`` / ``ordering``
+      params (validated by ``EnrollmentsAdminListForm``). It runs *after* the
+      scoping layer and only narrows the already-authorized queryset.
+    """
 
     # ADR 0034 — JWT + cross-domain session (BearerAuthenticationAllowInactiveUser
     # removed per OEP-0042). EnrollmentCrossDomainSessionAuth retained because the
@@ -677,6 +722,11 @@ class EnrollmentsAdminListView(StandardizedErrorMixin, ListAPIView):
     serializer_class = CourseEnrollmentsApiListSerializer
     pagination_class = EnrollmentsAdminListPagination
 
+    # OEP-66 — base (unscoped) queryset and the record-visibility policy that
+    # ScopedQuerysetMixin.get_queryset() applies on top of it.
+    queryset = CourseEnrollment.objects.all().select_related("user", "course")
+    scoping_policy = AdminEnrollmentScopingPolicy()
+
     # ADR 0033 §3 — whitelist of allowed values for the ``ordering`` param.
     ALLOWED_ORDERING_FIELDS = frozenset({"created", "-created", "id", "-id"})
 
@@ -686,12 +736,16 @@ class EnrollmentsAdminListView(StandardizedErrorMixin, ListAPIView):
         ("course_ids", "course_keys"),
     )
 
-    def get_queryset(self):
+    def filter_queryset(self, queryset):
+        """
+        OEP-66 user-driven filtering layer. Narrows the already-scoped
+        ``queryset`` (from ``ScopedQuerysetMixin.get_queryset()``) by the
+        caller-supplied query parameters; never widens it.
+        """
         form = EnrollmentsAdminListForm(self.request.query_params)
         if not form.is_valid():
             raise ValidationError(form.errors)
 
-        queryset = CourseEnrollment.objects.all().select_related("user", "course")
         course_id = form.cleaned_data.get("course_id")
         course_ids = form.cleaned_data.get("course_ids")
         usernames = form.cleaned_data.get("username")

requirements/edx/base.txt

@@ -471,7 +471,7 @@ edx-django-utils==8.0.1
     #   ora2
     #   super-csv
     #   xblocks-contrib
-edx-drf-extensions==10.6.0
+edx-drf-extensions==10.7.0
     # via
     #   -r requirements/edx/kernel.in
     #   edx-completion

requirements/edx/development.txt

@@ -743,7 +743,7 @@ edx-django-utils==8.0.1
     #   ora2
     #   super-csv
     #   xblocks-contrib
-edx-drf-extensions==10.6.0
+edx-drf-extensions==10.7.0
     # via
     #   -r requirements/edx/doc.txt
     #   -r requirements/edx/testing.txt

requirements/edx/doc.txt

@@ -561,7 +561,7 @@ edx-django-utils==8.0.1
     #   ora2
     #   super-csv
     #   xblocks-contrib
-edx-drf-extensions==10.6.0
+edx-drf-extensions==10.7.0
     # via
     #   -r requirements/edx/base.txt
     #   edx-completion

requirements/edx/testing.txt

@@ -577,7 +577,7 @@ edx-django-utils==8.0.1
     #   ora2
     #   super-csv
     #   xblocks-contrib
-edx-drf-extensions==10.6.0
+edx-drf-extensions==10.7.0
     # via
     #   -r requirements/edx/base.txt
     #   edx-completion