✨(backend) add agreement batch order viewset and serializer

We want authenticated organization user who have access to be able to
list, retrieve information on the contracts related to batch orders. This
will allow certain user who have the rights to retrieve the list of contracts
and if they are eligible to sign them.

We needed to create a new viewset and serializer because the existing
viewset for organization nested contract viewset was built around the
relation `contract.order`, it did not correspond to the relation
`batch_order.contract`. This is the reason why we created a new viewset
for that matter.

Author: jonathanreveille

src/backend/joanie/client_urls.py

@@ -103,6 +103,11 @@
     api_client.NestedOrganizationContractViewSet,
     basename="organization_contracts",
 )
+organization_related_router.register(
+    "agreements",
+    api_client.NestedOrganizationAgreementViewSet,
+    basename="organization_agreements",
+)
 organization_related_router.register(
     "offerings",
     api_client.OfferingViewSet,

src/backend/joanie/core/api/client/__init__.py

@@ -1644,6 +1644,96 @@ def get_me(self, request):
         return Response(self.serializer_class(request.user, context=context).data)
 
 
+class GenericAgreementViewSet(
+    mixins.ListModelMixin, mixins.RetrieveModelMixin, viewsets.GenericViewSet
+):
+    """
+    Agreement ViewSet that returns information on Contracts related to Batch Orders.
+    Only authenticated users that have access to organization can get information.
+
+    GET /.*/agreements/
+    GET /.*/agreements/<uuid:contract_id>
+    """
+
+    lookup_field = "pk"
+    permission_classes = [permissions.IsAuthenticated]
+    serializer_class = serializers.AgreementBatchOrderSerializer
+    filterset_class = filters.AgreementFilter
+    ordering = ["-organization_signed_on", "-created_on"]
+    queryset = (
+        models.Contract.objects.exclude(
+            batch_order__state=enums.BATCH_ORDER_STATE_CANCELED
+        )
+        .select_related(
+            "definition",
+            "organization_signatory",
+        )
+        .prefetch_related(
+            "batch_order__organization",
+            "batch_order__offering__course",
+            "batch_order__owner",
+            "batch_order__offering__product",
+        )
+    )
+
+
+class NestedOrganizationAgreementViewSet(NestedGenericViewSet, GenericAgreementViewSet):
+    """
+    Nested Organization and Agreements (contracts) related to batch orders inside organization
+    route.
+
+    It allows to list & retrieve organization's agreements (contracts) if the user is
+    an administrator or an owner of the organization.
+
+    GET /api/organizations/<organization_id|organization_code>/agreements/
+        Return list of all organization's contracts
+
+    GET /api/organizations/<organization_id|organization_code>/agreements/<contract_id>/
+        Return an organization's contract if one matches the provided id
+
+    You can use query params to filter by signature state when retrieving the list, or by
+    offering id.
+    """
+
+    lookup_fields = ["batch_order__organization__pk", "pk"]
+    lookup_url_kwargs = ["organization_id", "pk"]
+
+    def _lookup_by_organization_code_or_pk(self):
+        """
+        Override `lookup_fields` to lookup by organization code or pk according to
+        the `organization_id` kwarg is a valid UUID or not.
+        """
+        try:
+            uuid.UUID(self.kwargs["organization_id"])
+        except ValueError:
+            self.lookup_fields[0] = "batch_order__organization__code__iexact"
+
+    def initial(self, request, *args, **kwargs):
+        """
+        Runs anything that needs to occur prior to calling method handler.
+        """
+        super().initial(request, *args, **kwargs)
+        self._lookup_by_organization_code_or_pk()
+
+    def get_queryset(self):
+        """
+        Customize the queryset to get only user's agreements.
+        """
+        queryset = super().get_queryset()
+
+        username = (
+            self.request.auth["username"]
+            if self.request.auth
+            else self.request.user.username
+        )
+
+        additional_filter = {
+            "batch_order__organization__accesses__user__username": username,
+        }
+
+        return queryset.filter(**additional_filter)
+
+
 class GenericContractViewSet(
     mixins.ListModelMixin, mixins.RetrieveModelMixin, viewsets.GenericViewSet
 ):

src/backend/joanie/core/filters/client/__init__.py

@@ -173,6 +173,60 @@ def filter_offering_id(self, queryset, _name, value):
         )
 
 
+class AgreementFilter(filters.FilterSet):
+    """
+    AgreementFilter allows to filter this resource with signature state, organization id,
+    or offering id.
+    """
+
+    id = filters.AllValuesMultipleFilter()
+    signature_state = filters.ChoiceFilter(
+        method="filter_signature_state",
+        choices=enums.CONTRACT_SIGNATURE_STATE_FILTER_CHOICES,
+    )
+    organization_id = filters.UUIDFilter(field_name="batch_order__organization__id")
+    offering_id = filters.UUIDFilter(method="filter_offering_id")
+
+    class Meta:
+        model = models.Contract
+        fields: List[str] = ["id", "signature_state", "offering_id"]
+
+    def filter_signature_state(self, queryset, _name, value):
+        """
+        Filter Contracts by signature state
+        """
+        is_unsigned = value == enums.CONTRACT_SIGNATURE_STATE_UNSIGNED
+        is_half_signed = value == enums.CONTRACT_SIGNATURE_STATE_HALF_SIGNED
+
+        return queryset.filter(
+            student_signed_on__isnull=is_unsigned,
+            organization_signed_on__isnull=is_unsigned | is_half_signed,
+        )
+
+    def filter_offering_id(self, queryset, _name, value):
+        """
+        Try to retrieve an offering from the given id and filter contracts accordingly.
+        """
+        url_kwargs = self.request.parser_context.get("kwargs", {})
+        queryset_filters = {"id": value}
+
+        if organization_id := url_kwargs.get("organization_id"):
+            queryset_filters["organizations__in"] = [organization_id]
+
+        try:
+            offering = models.CourseProductRelation.objects.get(**queryset_filters)
+        except models.CourseProductRelation.DoesNotExist:
+            return queryset.none()
+
+        return queryset.filter(
+            batch_order__relation__course_id=offering.course_id,
+            batch_order__relation__product_id=offering.product_id,
+            batch_order__organization__in=offering.organizations.only("pk").values_list(
+                "pk", flat=True
+            ),
+        )
+
+
 class NestedOrderCourseViewSetFilter(filters.FilterSet):
     """
     OrderCourseFilter that allows to filter this resource with a product's 'id', an

src/backend/joanie/core/serializers/client.py

@@ -546,6 +546,20 @@ def get_total_currency(self, *args, **kwargs) -> str:
         return settings.DEFAULT_CURRENCY
 
 
+class AgreementBatchOrderSerializer(AbilitiesModelSerializer):
+    """Small serializer for Contracts models related to Batch Orders (agreements)"""
+
+    batch_order = BatchOrderLightSerializer(read_only=True)
+
+    class Meta:
+        model = models.Contract
+        fields = [
+            "id",
+            "batch_order",
+        ]
+        read_only_fields = fields
+
+
 class QuoteDefinitionSerializer(serializers.ModelSerializer):
     """Read only serializer for QuoteDefinition model."""