✨(backend) annotate number of accesses on documents

The new UI will display the number of accesses on each document.

/!\ Once team accesses will be used, this will not represent the number
    of people with access anymore and will have to be improved by
    computing the number of people in each team.

CHANGELOG.md

@@ -11,12 +11,15 @@ and this project adheres to
 
 ## Added
 
+- ✨(backend) annotate number of accesses on documents in list view #411
+- ✨(backend) allow users to mark/unmark documents as favorite #411
 - 🌐(frontend) Add German translation #255
 - ✨(frontend) Add a broadcast store #387
 
 
 ## Changed
 
+- ⚡️(backend) optimize number of queries on document list view #411
 - 🚸(backend) improve users similarity search and sort results #391
 - 🌐(backend) add german translation #259
 - ♻️(frontend) simplify stores #402

src/backend/core/api/serializers.py

@@ -137,32 +137,65 @@ class BaseResourceSerializer(serializers.ModelSerializer):
         return {}
 
 
-class DocumentSerializer(BaseResourceSerializer):
-    """Serialize documents."""
+class ListDocumentSerializer(BaseResourceSerializer):
+    """Serialize documents with limited fields for display in lists."""
 
-    content = serializers.CharField(required=False)
-    accesses = DocumentAccessSerializer(many=True, read_only=True)
+    is_favorite = serializers.BooleanField(read_only=True)
+    nb_accesses = serializers.IntegerField(read_only=True)
 
     class Meta:
         model = models.Document
         fields = [
             "id",
-            "content",
-            "title",
-            "accesses",
             "abilities",
+            "content",
+            "created_at",
+            "is_favorite",
             "link_role",
             "link_reach",
-            "created_at",
+            "nb_accesses",
+            "title",
             "updated_at",
         ]
         read_only_fields = [
             "id",
-            "accesses",
             "abilities",
+            "created_at",
+            "is_favorite",
             "link_role",
             "link_reach",
+            "nb_accesses",
+            "updated_at",
+        ]
+
+
+class DocumentSerializer(ListDocumentSerializer):
+    """Serialize documents with all fields for display in detail views."""
+
+    content = serializers.CharField(required=False)
+
+    class Meta:
+        model = models.Document
+        fields = [
+            "id",
+            "abilities",
+            "content",
             "created_at",
+            "is_favorite",
+            "link_role",
+            "link_reach",
+            "nb_accesses",
+            "title",
+            "updated_at",
+        ]
+        read_only_fields = [
+            "id",
+            "abilities",
+            "created_at",
+            "is_avorite",
+            "link_role",
+            "link_reach",
+            "nb_accesses",
             "updated_at",
         ]
 

src/backend/core/api/viewsets.py

@@ -10,10 +10,13 @@ from django.contrib.postgres.search import TrigramSimilarity
 from django.core.exceptions import ValidationError
 from django.core.files.storage import default_storage
 from django.db.models import (
+    Count,
+    Exists,
     Min,
     OuterRef,
     Q,
     Subquery,
+    Value,
 )
 from django.http import Http404
 
@@ -191,42 +194,6 @@ class UserViewSet(
         )
 
 
-class ResourceViewsetMixin:
-    """Mixin with methods common to all resource viewsets that are managed with accesses."""
-
-    filter_backends = [filters.OrderingFilter]
-    ordering_fields = ["created_at", "updated_at", "title"]
-    ordering = ["-created_at"]
-
-    def get_queryset(self):
-        """Custom queryset to get user related resources."""
-        queryset = super().get_queryset()
-        user = self.request.user
-
-        if not user.is_authenticated:
-            return queryset
-
-        user_roles_query = (
-            self.access_model_class.objects.filter(
-                Q(user=user) | Q(team__in=user.teams),
-                **{self.resource_field_name: OuterRef("pk")},
-            )
-            .values(self.resource_field_name)
-            .annotate(roles_array=ArrayAgg("role"))
-            .values("roles_array")
-        )
-        return queryset.annotate(user_roles=Subquery(user_roles_query)).distinct()
-
-    def perform_create(self, serializer):
-        """Set the current user as owner of the newly created object."""
-        obj = serializer.save()
-        self.access_model_class.objects.create(
-            user=self.request.user,
-            role=models.RoleChoices.OWNER,
-            **{self.resource_field_name: obj},
-        )
-
-
 class ResourceAccessViewsetMixin:
     """Mixin with methods common to all access viewsets."""
 
@@ -336,7 +303,6 @@ class DocumentMetadata(metadata.SimpleMetadata):
 
 
 class DocumentViewSet(
-    ResourceViewsetMixin,
     mixins.CreateModelMixin,
     mixins.DestroyModelMixin,
     mixins.UpdateModelMixin,
@@ -344,20 +310,59 @@ class DocumentViewSet(
 ):
     """Document ViewSet"""
 
+    filter_backends = [filters.OrderingFilter]
+    metadata_class = DocumentMetadata
+    ordering = ["-updated_at"]
+    ordering_fields = ["created_at", "is_favorite", "updated_at", "title"]
     permission_classes = [
         permissions.AccessPermission,
     ]
-    serializer_class = serializers.DocumentSerializer
-    access_model_class = models.DocumentAccess
-    resource_field_name = "document"
     queryset = models.Document.objects.all()
-    ordering = ["-updated_at"]
-    metadata_class = DocumentMetadata
+    serializer_class = serializers.DocumentSerializer
+
+    def get_serializer_class(self):
+        """
+        Use ListDocumentSerializer for list actions, otherwise use DocumentSerializer.
+        """
+        if self.action == "list":
+            return serializers.ListDocumentSerializer
+        return self.serializer_class
+
+    def get_queryset(self):
+        """Optimize queryset to include favorite status for the current user."""
+        queryset = super().get_queryset()
+        user = self.request.user
+
+        # Annotate the number of accesses associated with each document
+        queryset = queryset.annotate(nb_accesses=Count("accesses"))
+
+        if not user.is_authenticated:
+            # If the user is not authenticated, annotate `is_favorite` as False
+            return queryset.annotate(is_favorite=Value(False))
+
+        # Annotate the queryset to indicate if the document is favorited by the current user
+        favorite_exists = models.DocumentFavorite.objects.filter(
+            document_id=OuterRef("pk"), user=user
+        )
+        queryset = queryset.annotate(is_favorite=Exists(favorite_exists))
+
+        # Annotate the queryset with the logged-in user roles
+        user_roles_query = (
+            models.DocumentAccess.objects.filter(
+                Q(user=user) | Q(team__in=user.teams),
+                document_id=OuterRef("pk"),
+            )
+            .values("document")
+            .annotate(roles_array=ArrayAgg("role"))
+            .values("roles_array")
+        )
+        return queryset.annotate(user_roles=Subquery(user_roles_query)).distinct()
 
     def list(self, request, *args, **kwargs):
         """Restrict resources returned by the list endpoint"""
         queryset = self.filter_queryset(self.get_queryset())
         user = self.request.user
+
         if user.is_authenticated:
             queryset = queryset.filter(
                 Q(accesses__user=user)
@@ -401,6 +406,15 @@ class DocumentViewSet(
 
         return drf_response.Response(serializer.data)
 
+    def perform_create(self, serializer):
+        """Set the current user as owner of the newly created object."""
+        obj = serializer.save()
+        models.DocumentAccess.objects.create(
+            document=obj,
+            user=self.request.user,
+            role=models.RoleChoices.OWNER,
+        )
+
     @decorators.action(detail=True, methods=["get"], url_path="versions")
     def versions_list(self, request, *args, **kwargs):
         """
@@ -494,6 +508,43 @@ class DocumentViewSet(
         serializer.save()
         return drf_response.Response(serializer.data, status=status.HTTP_200_OK)
 
+    @decorators.action(detail=True, methods=["post", "delete"], url_path="favorite")
+    def favorite(self, request, *args, **kwargs):
+        """
+        Mark or unmark the document as a favorite for the logged-in user based on the HTTP method.
+        """
+        # Check permissions first
+        document = self.get_object()
+        user = request.user
+
+        if request.method == "POST":
+            # Try to mark as favorite
+            try:
+                models.DocumentFavorite.objects.create(document=document, user=user)
+            except ValidationError:
+                return drf_response.Response(
+                    {"detail": "Document already marked as favorite"},
+                    status=status.HTTP_200_OK,
+                )
+            return drf_response.Response(
+                {"detail": "Document marked as favorite"},
+                status=status.HTTP_201_CREATED,
+            )
+
+        # Handle DELETE method to unmark as favorite
+        deleted, _ = models.DocumentFavorite.objects.filter(
+            document=document, user=user
+        ).delete()
+        if deleted:
+            return drf_response.Response(
+                {"detail": "Document unmarked as favorite"},
+                status=status.HTTP_204_NO_CONTENT,
+            )
+        return drf_response.Response(
+            {"detail": "Document was already not marked as favorite"},
+            status=status.HTTP_200_OK,
+        )
+
     @decorators.action(detail=True, methods=["post"], url_path="attachment-upload")
     def attachment_upload(self, request, *args, **kwargs):
         """Upload a file related to a given document"""
@@ -677,7 +728,6 @@ class DocumentAccessViewSet(
 
 
 class TemplateViewSet(
-    ResourceViewsetMixin,
     mixins.CreateModelMixin,
     mixins.DestroyModelMixin,
     mixins.RetrieveModelMixin,
@@ -686,15 +736,35 @@ class TemplateViewSet(
 ):
     """Template ViewSet"""
 
+    filter_backends = [filters.OrderingFilter]
     permission_classes = [
         permissions.IsAuthenticatedOrSafe,
         permissions.AccessPermission,
     ]
+    ordering = ["-created_at"]
+    ordering_fields = ["created_at", "updated_at", "title"]
     serializer_class = serializers.TemplateSerializer
-    access_model_class = models.TemplateAccess
-    resource_field_name = "template"
     queryset = models.Template.objects.all()
 
+    def get_queryset(self):
+        """Custom queryset to get user related templates."""
+        queryset = super().get_queryset()
+        user = self.request.user
+
+        if not user.is_authenticated:
+            return queryset
+
+        user_roles_query = (
+            models.TemplateAccess.objects.filter(
+                Q(user=user) | Q(team__in=user.teams),
+                template_id=OuterRef("pk"),
+            )
+            .values("template")
+            .annotate(roles_array=ArrayAgg("role"))
+            .values("roles_array")
+        )
+        return queryset.annotate(user_roles=Subquery(user_roles_query)).distinct()
+
     def list(self, request, *args, **kwargs):
         """Restrict templates returned by the list endpoint"""
         queryset = self.filter_queryset(self.get_queryset())
@@ -716,6 +786,15 @@ class TemplateViewSet(
         serializer = self.get_serializer(queryset, many=True)
         return drf_response.Response(serializer.data)
 
+    def perform_create(self, serializer):
+        """Set the current user as owner of the newly created object."""
+        obj = serializer.save()
+        models.TemplateAccess.objects.create(
+            template=obj,
+            user=self.request.user,
+            role=models.RoleChoices.OWNER,
+        )
+
     @decorators.action(
         detail=True,
         methods=["post"],

src/backend/core/factories.py

@@ -80,6 +80,13 @@ class DocumentFactory(factory.django.DjangoModelFactory):
             for item in extracted:
                 models.LinkTrace.objects.create(document=self, user=item)
 
+    @factory.post_generation
+    def favorited_by(self, create, extracted, **kwargs):
+        """Mark document as favorited by a list of users."""
+        if create and extracted:
+            for item in extracted:
+                models.DocumentFavorite.objects.create(document=self, user=item)
+
 
 class UserDocumentAccessFactory(factory.django.DjangoModelFactory):
     """Create fake document user accesses for testing."""

src/backend/core/migrations/0009_add_document_favorite.py

@@ -0,0 +1,37 @@
+# Generated by Django 5.1.2 on 2024-11-08 07:59
+
+import django.db.models.deletion
+import uuid
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('core', '0008_alter_document_link_reach'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='user',
+            name='language',
+            field=models.CharField(choices="(('en-us', 'English'), ('fr-fr', 'French'), ('de-de', 'German'))", default='en-us', help_text='The language in which the user wants to see the interface.', max_length=10, verbose_name='language'),
+        ),
+        migrations.CreateModel(
+            name='DocumentFavorite',
+            fields=[
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, help_text='primary key for the record as UUID', primary_key=True, serialize=False, verbose_name='id')),
+                ('created_at', models.DateTimeField(auto_now_add=True, help_text='date and time at which a record was created', verbose_name='created on')),
+                ('updated_at', models.DateTimeField(auto_now=True, help_text='date and time at which a record was last updated', verbose_name='updated on')),
+                ('document', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='favorited_by_users', to='core.document')),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='favorite_documents', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'verbose_name': 'Document favorite',
+                'verbose_name_plural': 'Document favorites',
+                'db_table': 'impress_document_favorite',
+                'constraints': [models.UniqueConstraint(fields=('user', 'document'), name='unique_document_favorite_user', violation_error_message='This document is already targeted by a favorite relation instance for the same user.')],
+            },
+        ),
+    ]

src/backend/core/models.py

@@ -518,6 +518,7 @@ class Document(BaseModel):
             "ai_translate": is_owner_or_admin or is_editor,
             "attachment_upload": is_owner_or_admin or is_editor,
             "destroy": RoleChoices.OWNER in roles,
+            "favorite": can_get and user.is_authenticated,
             "link_configuration": is_owner_or_admin,
             "invite_owner": RoleChoices.OWNER in roles,
             "partial_update": is_owner_or_admin or is_editor,
@@ -600,6 +601,37 @@ class LinkTrace(BaseModel):
         return f"{self.user!s} trace on document {self.document!s}"
 
 
+class DocumentFavorite(BaseModel):
+    """Relation model to store a user's favorite documents."""
+
+    document = models.ForeignKey(
+        Document,
+        on_delete=models.CASCADE,
+        related_name="favorited_by_users",
+    )
+    user = models.ForeignKey(
+        User, on_delete=models.CASCADE, related_name="favorite_documents"
+    )
+
+    class Meta:
+        db_table = "impress_document_favorite"
+        verbose_name = _("Document favorite")
+        verbose_name_plural = _("Document favorites")
+        constraints = [
+            models.UniqueConstraint(
+                fields=["user", "document"],
+                name="unique_document_favorite_user",
+                violation_error_message=_(
+                    "This document is already targeted by a favorite relation instance "
+                    "for the same user."
+                ),
+            ),
+        ]
+
+    def __str__(self):
+        return f"{self.user!s} favorite on document {self.document!s}"
+
+
 class DocumentAccess(BaseAccess):
     """Relation model to give access to a document for a user or a team with a role."""
 

src/backend/core/tests/documents/test_api_documents_favorite.py

@@ -0,0 +1,308 @@
+"""Test favorite document API endpoint for users in impress's core app."""
+
+import pytest
+from rest_framework.test import APIClient
+
+from core import factories, models
+
+pytestmark = pytest.mark.django_db
+
+
+@pytest.mark.parametrize(
+    "reach",
+    [
+        "restricted",
+        "authenticated",
+        "public",
+    ],
+)
+@pytest.mark.parametrize("method", ["post", "delete"])
+def test_api_document_favorite_anonymous_user(method, reach):
+    """Anonymous users should not be able to mark/unmark documents as favorites."""
+    document = factories.DocumentFactory(link_reach=reach)
+
+    response = getattr(APIClient(), method)(
+        f"/api/v1.0/documents/{document.id!s}/favorite/"
+    )
+
+    assert response.status_code == 401
+    assert response.json() == {
+        "detail": "Authentication credentials were not provided."
+    }
+
+    # Verify in database
+    assert models.DocumentFavorite.objects.exists() is False
+
+
+@pytest.mark.parametrize(
+    "reach, has_role",
+    [
+        ["restricted", True],
+        ["authenticated", False],
+        ["authenticated", True],
+        ["public", False],
+        ["public", True],
+    ],
+)
+def test_api_document_favorite_authenticated_post_allowed(reach, has_role):
+    """Authenticated users should be able to mark a document as favorite using POST."""
+    user = factories.UserFactory()
+    document = factories.DocumentFactory(link_reach=reach)
+    client = APIClient()
+    client.force_login(user)
+
+    if has_role:
+        models.DocumentAccess.objects.create(document=document, user=user)
+
+    # Mark as favorite
+    response = client.post(f"/api/v1.0/documents/{document.id!s}/favorite/")
+
+    assert response.status_code == 201
+    assert response.json() == {"detail": "Document marked as favorite"}
+
+    # Verify in database
+    assert models.DocumentFavorite.objects.filter(document=document, user=user).exists()
+
+    # Verify document format
+    response = client.get(f"/api/v1.0/documents/{document.id!s}/")
+    assert response.json()["is_favorite"] is True
+
+
+def test_api_document_favorite_authenticated_post_forbidden():
+    """Authenticated users should be able to mark a document as favorite using POST."""
+    user = factories.UserFactory()
+    document = factories.DocumentFactory(link_reach="restricted")
+    client = APIClient()
+    client.force_login(user)
+
+    # Try marking as favorite
+    response = client.post(f"/api/v1.0/documents/{document.id!s}/favorite/")
+
+    assert response.status_code == 403
+    assert response.json() == {
+        "detail": "You do not have permission to perform this action."
+    }
+
+    # Verify in database
+    assert (
+        models.DocumentFavorite.objects.filter(document=document, user=user).exists()
+        is False
+    )
+
+
+@pytest.mark.parametrize(
+    "reach, has_role",
+    [
+        ["restricted", True],
+        ["authenticated", False],
+        ["authenticated", True],
+        ["public", False],
+        ["public", True],
+    ],
+)
+def test_api_document_favorite_authenticated_post_already_favorited_allowed(
+    reach, has_role
+):
+    """POST should not create duplicate favorites if already marked."""
+    user = factories.UserFactory()
+    document = factories.DocumentFactory(link_reach=reach, favorited_by=[user])
+    client = APIClient()
+    client.force_login(user)
+
+    if has_role:
+        models.DocumentAccess.objects.create(document=document, user=user)
+
+    # Try to mark as favorite again
+    response = client.post(f"/api/v1.0/documents/{document.id!s}/favorite/")
+
+    assert response.status_code == 200
+    assert response.json() == {"detail": "Document already marked as favorite"}
+
+    # Verify in database
+    assert models.DocumentFavorite.objects.filter(document=document, user=user).exists()
+
+    # Verify document format
+    response = client.get(f"/api/v1.0/documents/{document.id!s}/")
+    assert response.json()["is_favorite"] is True
+
+
+def test_api_document_favorite_authenticated_post_already_favorited_forbidden():
+    """POST should not create duplicate favorites if already marked."""
+    user = factories.UserFactory()
+    document = factories.DocumentFactory(link_reach="restricted", favorited_by=[user])
+    client = APIClient()
+    client.force_login(user)
+
+    # Try to mark as favorite again
+    response = client.post(f"/api/v1.0/documents/{document.id!s}/favorite/")
+
+    assert response.status_code == 403
+    assert response.json() == {
+        "detail": "You do not have permission to perform this action."
+    }
+
+    # Verify in database
+    assert models.DocumentFavorite.objects.filter(document=document, user=user).exists()
+
+
+@pytest.mark.parametrize(
+    "reach, has_role",
+    [
+        ["restricted", True],
+        ["authenticated", False],
+        ["authenticated", True],
+        ["public", False],
+        ["public", True],
+    ],
+)
+def test_api_document_favorite_authenticated_delete_allowed(reach, has_role):
+    """Authenticated users should be able to unmark a document as favorite using DELETE."""
+    user = factories.UserFactory()
+    document = factories.DocumentFactory(link_reach=reach, favorited_by=[user])
+    client = APIClient()
+    client.force_login(user)
+
+    if has_role:
+        models.DocumentAccess.objects.create(document=document, user=user)
+
+    # Unmark as favorite
+    response = client.delete(f"/api/v1.0/documents/{document.id!s}/favorite/")
+    assert response.status_code == 204
+
+    # Verify in database
+    assert (
+        models.DocumentFavorite.objects.filter(document=document, user=user).exists()
+        is False
+    )
+
+    # Verify document format
+    response = client.get(f"/api/v1.0/documents/{document.id!s}/")
+    assert response.json()["is_favorite"] is False
+
+
+def test_api_document_favorite_authenticated_delete_forbidden():
+    """Authenticated users should be able to unmark a document as favorite using DELETE."""
+    user = factories.UserFactory()
+    document = factories.DocumentFactory(link_reach="restricted", favorited_by=[user])
+    client = APIClient()
+    client.force_login(user)
+
+    # Unmark as favorite
+    response = client.delete(f"/api/v1.0/documents/{document.id!s}/favorite/")
+
+    assert response.status_code == 403
+    assert response.json() == {
+        "detail": "You do not have permission to perform this action."
+    }
+
+    # Verify in database
+    assert (
+        models.DocumentFavorite.objects.filter(document=document, user=user).exists()
+        is True
+    )
+
+
+@pytest.mark.parametrize(
+    "reach, has_role",
+    [
+        ["restricted", True],
+        ["authenticated", False],
+        ["authenticated", True],
+        ["public", False],
+        ["public", True],
+    ],
+)
+def test_api_document_favorite_authenticated_delete_not_favorited_allowed(
+    reach, has_role
+):
+    """DELETE should be idempotent if the document is not marked as favorite."""
+    user = factories.UserFactory()
+    document = factories.DocumentFactory(link_reach=reach)
+    client = APIClient()
+    client.force_login(user)
+
+    if has_role:
+        models.DocumentAccess.objects.create(document=document, user=user)
+
+    # Try to unmark as favorite when no favorite entry exists
+    response = client.delete(f"/api/v1.0/documents/{document.id!s}/favorite/")
+
+    assert response.status_code == 200
+    assert response.json() == {"detail": "Document was already not marked as favorite"}
+
+    # Verify in database
+    assert (
+        models.DocumentFavorite.objects.filter(document=document, user=user).exists()
+        is False
+    )
+
+    # Verify document format
+    response = client.get(f"/api/v1.0/documents/{document.id!s}/")
+    assert response.json()["is_favorite"] is False
+
+
+def test_api_document_favorite_authenticated_delete_not_favorited_forbidden():
+    """DELETE should be idempotent if the document is not marked as favorite."""
+    user = factories.UserFactory()
+    document = factories.DocumentFactory(link_reach="restricted")
+    client = APIClient()
+    client.force_login(user)
+
+    # Try to unmark as favorite when no favorite entry exists
+    response = client.delete(f"/api/v1.0/documents/{document.id!s}/favorite/")
+
+    assert response.status_code == 403
+    assert response.json() == {
+        "detail": "You do not have permission to perform this action."
+    }
+
+    # Verify in database
+    assert (
+        models.DocumentFavorite.objects.filter(document=document, user=user).exists()
+        is False
+    )
+
+
+@pytest.mark.parametrize(
+    "reach, has_role",
+    [
+        ["restricted", True],
+        ["authenticated", False],
+        ["authenticated", True],
+        ["public", False],
+        ["public", True],
+    ],
+)
+def test_api_document_favorite_authenticated_post_unmark_then_mark_again_allowed(
+    reach, has_role
+):
+    """A user should be able to mark, unmark, and mark a document again as favorite."""
+    user = factories.UserFactory()
+    document = factories.DocumentFactory(link_reach=reach)
+    client = APIClient()
+    client.force_login(user)
+
+    if has_role:
+        models.DocumentAccess.objects.create(document=document, user=user)
+
+    url = f"/api/v1.0/documents/{document.id!s}/favorite/"
+
+    # Mark as favorite
+    response = client.post(url)
+    assert response.status_code == 201
+
+    # Unmark as favorite
+    response = client.delete(url)
+    assert response.status_code == 204
+
+    # Mark as favorite again
+    response = client.post(url)
+    assert response.status_code == 201
+    assert response.json() == {"detail": "Document marked as favorite"}
+
+    # Verify in database
+    assert models.DocumentFavorite.objects.filter(document=document, user=user).exists()
+
+    # Verify document format
+    response = client.get(f"/api/v1.0/documents/{document.id!s}/")
+    assert response.json()["is_favorite"] is True

src/backend/core/tests/documents/test_api_documents_list.py

@@ -32,7 +32,44 @@ def test_api_documents_list_anonymous(reach, role):
     assert len(results) == 0
 
 
-def test_api_documents_list_authenticated_direct():
+def test_api_documents_list_format():
+    """Validate the format of documents as returned by the list view."""
+    user = factories.UserFactory()
+
+    client = APIClient()
+    client.force_login(user)
+
+    document = factories.DocumentFactory(
+        users=[user, *factories.UserFactory.create_batch(2)],
+        favorited_by=[user, *factories.UserFactory.create_batch(2)],
+    )
+
+    response = client.get("/api/v1.0/documents/")
+
+    assert response.status_code == 200
+    content = response.json()
+    results = content.pop("results")
+    assert content == {
+        "count": 1,
+        "next": None,
+        "previous": None,
+    }
+    assert len(results) == 1
+    assert results[0] == {
+        "id": str(document.id),
+        "abilities": document.get_abilities(user),
+        "content": document.content,
+        "created_at": document.created_at.isoformat().replace("+00:00", "Z"),
+        "is_favorite": True,
+        "link_reach": document.link_reach,
+        "link_role": document.link_role,
+        "nb_accesses": 3,
+        "title": document.title,
+        "updated_at": document.updated_at.isoformat().replace("+00:00", "Z"),
+    }
+
+
+def test_api_documents_list_authenticated_direct(django_assert_num_queries):
     """
     Authenticated users should be able to list documents they are a direct
     owner/administrator/member of or documents that have a link reach other
@@ -55,9 +92,8 @@ def test_api_documents_list_authenticated_direct():
 
     expected_ids = {str(document.id) for document in documents}
 
-    response = client.get(
-        "/api/v1.0/documents/",
-    )
+    with django_assert_num_queries(3):
+        response = client.get("/api/v1.0/documents/")
 
     assert response.status_code == 200
     results = response.json()["results"]
@@ -66,7 +102,9 @@ def test_api_documents_list_authenticated_direct():
     assert expected_ids == results_id
 
 
-def test_api_documents_list_authenticated_via_team(mock_user_teams):
+def test_api_documents_list_authenticated_via_team(
+    django_assert_num_queries, mock_user_teams
+):
     """
     Authenticated users should be able to list documents they are a
     owner/administrator/member of via a team.
@@ -89,7 +127,8 @@ def test_api_documents_list_authenticated_via_team(mock_user_teams):
 
     expected_ids = {str(document.id) for document in documents_team1 + documents_team2}
 
-    response = client.get("/api/v1.0/documents/")
+    with django_assert_num_queries(3):
+        response = client.get("/api/v1.0/documents/")
 
     assert response.status_code == 200
     results = response.json()["results"]
@@ -98,7 +137,9 @@ def test_api_documents_list_authenticated_via_team(mock_user_teams):
     assert expected_ids == results_id
 
 
-def test_api_documents_list_authenticated_link_reach_restricted():
+def test_api_documents_list_authenticated_link_reach_restricted(
+    django_assert_num_queries,
+):
     """
     An authenticated user who has link traces to a document that is restricted should not
     see it on the list view
@@ -115,9 +156,10 @@ def test_api_documents_list_authenticated_link_reach_restricted():
     other_document = factories.DocumentFactory(link_reach="public")
     models.LinkTrace.objects.create(document=other_document, user=user)
 
-    response = client.get(
-        "/api/v1.0/documents/",
-    )
+    with django_assert_num_queries(3):
+        response = client.get(
+            "/api/v1.0/documents/",
+        )
 
     assert response.status_code == 200
     results = response.json()["results"]
@@ -127,7 +169,9 @@ def test_api_documents_list_authenticated_link_reach_restricted():
     assert results[0]["id"] == str(other_document.id)
 
 
-def test_api_documents_list_authenticated_link_reach_public_or_authenticated():
+def test_api_documents_list_authenticated_link_reach_public_or_authenticated(
+    django_assert_num_queries,
+):
     """
     An authenticated user who has link traces to a document with public or authenticated
     link reach should see it on the list view.
@@ -144,9 +188,10 @@ def test_api_documents_list_authenticated_link_reach_public_or_authenticated():
     ]
     expected_ids = {str(document.id) for document in documents}
 
-    response = client.get(
-        "/api/v1.0/documents/",
-    )
+    with django_assert_num_queries(3):
+        response = client.get(
+            "/api/v1.0/documents/",
+        )
 
     assert response.status_code == 200
     results = response.json()["results"]
@@ -254,6 +299,8 @@ def test_api_documents_list_ordering_by_fields():
     for parameter in [
         "created_at",
         "-created_at",
+        "is_favorite",
+        "-is_favorite",
         "updated_at",
         "-updated_at",
         "title",
@@ -272,3 +319,45 @@ def test_api_documents_list_ordering_by_fields():
         compare = operator.ge if is_descending else operator.le
         for i in range(4):
             assert compare(results[i][field], results[i + 1][field])
+
+
+def test_api_documents_list_favorites_no_extra_queries(django_assert_num_queries):
+    """
+    Ensure that marking documents as favorite does not generate additional queries
+    when fetching the document list.
+    """
+    user = factories.UserFactory()
+    client = APIClient()
+    client.force_login(user)
+
+    special_documents = factories.DocumentFactory.create_batch(3, users=[user])
+    factories.DocumentFactory.create_batch(2, users=[user])
+
+    url = "/api/v1.0/documents/"
+    with django_assert_num_queries(3):
+        response = client.get(url)
+
+    assert response.status_code == 200
+    results = response.json()["results"]
+    assert len(results) == 5
+
+    assert all(result["is_favorite"] is False for result in results)
+
+    # Mark documents as favorite and check results again
+    for document in special_documents:
+        models.DocumentFavorite.objects.create(document=document, user=user)
+
+    with django_assert_num_queries(3):
+        response = client.get(url)
+
+    assert response.status_code == 200
+    results = response.json()["results"]
+    assert len(results) == 5
+
+    # Check if the "is_favorite" annotation is correctly set for the favorited documents
+    favorited_ids = {str(doc.id) for doc in special_documents}
+    for result in results:
+        if result["id"] in favorited_ids:
+            assert result["is_favorite"] is True
+        else:
+            assert result["is_favorite"] is False

src/backend/core/tests/documents/test_api_documents_retrieve.py

@@ -27,6 +27,8 @@ def test_api_documents_retrieve_anonymous_public():
             "ai_translate": document.link_role == "editor",
             "attachment_upload": document.link_role == "editor",
             "destroy": False,
+            # Anonymous user can't favorite a document even with read access
+            "favorite": False,
             "invite_owner": False,
             "link_configuration": False,
             "partial_update": document.link_role == "editor",
@@ -36,12 +38,13 @@ def test_api_documents_retrieve_anonymous_public():
             "versions_list": False,
             "versions_retrieve": False,
         },
-        "accesses": [],
+        "nb_accesses": 0,
+        "content": document.content,
+        "created_at": document.created_at.isoformat().replace("+00:00", "Z"),
+        "is_favorite": False,
         "link_reach": "public",
         "link_role": document.link_role,
         "title": document.title,
-        "content": document.content,
-        "created_at": document.created_at.isoformat().replace("+00:00", "Z"),
         "updated_at": document.updated_at.isoformat().replace("+00:00", "Z"),
     }
 
@@ -84,9 +87,10 @@ def test_api_documents_retrieve_authenticated_unrelated_public_or_authenticated(
             "ai_transform": document.link_role == "editor",
             "ai_translate": document.link_role == "editor",
             "attachment_upload": document.link_role == "editor",
-            "link_configuration": False,
             "destroy": False,
+            "favorite": True,
             "invite_owner": False,
+            "link_configuration": False,
             "partial_update": document.link_role == "editor",
             "retrieve": True,
             "update": document.link_role == "editor",
@@ -94,12 +98,13 @@ def test_api_documents_retrieve_authenticated_unrelated_public_or_authenticated(
             "versions_list": False,
             "versions_retrieve": False,
         },
-        "accesses": [],
-        "link_reach": reach,
-        "link_role": document.link_role,
-        "title": document.title,
         "content": document.content,
         "created_at": document.created_at.isoformat().replace("+00:00", "Z"),
+        "is_favorite": False,
+        "link_reach": reach,
+        "link_role": document.link_role,
+        "nb_accesses": 0,
+        "title": document.title,
         "updated_at": document.updated_at.isoformat().replace("+00:00", "Z"),
     }
     assert (
@@ -168,43 +173,25 @@ def test_api_documents_retrieve_authenticated_related_direct():
     client.force_login(user)
 
     document = factories.DocumentFactory()
-    access1 = factories.UserDocumentAccessFactory(document=document, user=user)
+    factories.UserDocumentAccessFactory(document=document, user=user)
     access2 = factories.UserDocumentAccessFactory(document=document)
-    access1_user = serializers.UserSerializer(instance=user).data
-    access2_user = serializers.UserSerializer(instance=access2.user).data
+    serializers.UserSerializer(instance=user)
+    serializers.UserSerializer(instance=access2.user)
 
     response = client.get(
         f"/api/v1.0/documents/{document.id!s}/",
     )
     assert response.status_code == 200
-    content = response.json()
-    assert sorted(content.pop("accesses"), key=lambda x: x["id"]) == sorted(
-        [
-            {
-                "id": str(access1.id),
-                "user": access1_user,
-                "team": "",
-                "role": access1.role,
-                "abilities": access1.get_abilities(user),
-            },
-            {
-                "id": str(access2.id),
-                "user": access2_user,
-                "team": "",
-                "role": access2.role,
-                "abilities": access2.get_abilities(user),
-            },
-        ],
-        key=lambda x: x["id"],
-    )
     assert response.json() == {
         "id": str(document.id),
-        "title": document.title,
-        "content": document.content,
         "abilities": document.get_abilities(user),
+        "content": document.content,
+        "created_at": document.created_at.isoformat().replace("+00:00", "Z"),
+        "is_favorite": False,
         "link_reach": document.link_reach,
         "link_role": document.link_role,
-        "created_at": document.created_at.isoformat().replace("+00:00", "Z"),
+        "nb_accesses": 2,
+        "title": document.title,
         "updated_at": document.updated_at.isoformat().replace("+00:00", "Z"),
     }
 
@@ -257,7 +244,7 @@ def test_api_documents_retrieve_authenticated_related_team_members(
 ):
     """
     Authenticated users should be allowed to retrieve a document to which they
-    are related via a team whatever the role and see all its accesses.
+    are related via a team whatever the role.
     """
     mock_user_teams.return_value = teams
 
@@ -268,81 +255,33 @@ def test_api_documents_retrieve_authenticated_related_team_members(
 
     document = factories.DocumentFactory(link_reach="restricted")
 
-    access_reader = factories.TeamDocumentAccessFactory(
+    factories.TeamDocumentAccessFactory(
         document=document, team="readers", role="reader"
     )
-    access_editor = factories.TeamDocumentAccessFactory(
+    factories.TeamDocumentAccessFactory(
         document=document, team="editors", role="editor"
     )
-    access_administrator = factories.TeamDocumentAccessFactory(
+    factories.TeamDocumentAccessFactory(
         document=document, team="administrators", role="administrator"
     )
-    access_owner = factories.TeamDocumentAccessFactory(
-        document=document, team="owners", role="owner"
-    )
-    other_access = factories.TeamDocumentAccessFactory(document=document)
+    factories.TeamDocumentAccessFactory(document=document, team="owners", role="owner")
+    factories.TeamDocumentAccessFactory(document=document)
     factories.TeamDocumentAccessFactory()
 
     response = client.get(f"/api/v1.0/documents/{document.id!s}/")
 
     # pylint: disable=R0801
     assert response.status_code == 200
-    content = response.json()
-    expected_abilities = {
-        "destroy": False,
-        "retrieve": True,
-        "set_role_to": [],
-        "update": False,
-        "partial_update": False,
-    }
-    assert sorted(content.pop("accesses"), key=lambda x: x["id"]) == sorted(
-        [
-            {
-                "id": str(access_reader.id),
-                "user": None,
-                "team": "readers",
-                "role": access_reader.role,
-                "abilities": expected_abilities,
-            },
-            {
-                "id": str(access_editor.id),
-                "user": None,
-                "team": "editors",
-                "role": access_editor.role,
-                "abilities": expected_abilities,
-            },
-            {
-                "id": str(access_administrator.id),
-                "user": None,
-                "team": "administrators",
-                "role": access_administrator.role,
-                "abilities": expected_abilities,
-            },
-            {
-                "id": str(access_owner.id),
-                "user": None,
-                "team": "owners",
-                "role": access_owner.role,
-                "abilities": expected_abilities,
-            },
-            {
-                "id": str(other_access.id),
-                "user": None,
-                "team": other_access.team,
-                "role": other_access.role,
-                "abilities": expected_abilities,
-            },
-        ],
-        key=lambda x: x["id"],
-    )
     assert response.json() == {
         "id": str(document.id),
-        "title": document.title,
-        "content": document.content,
         "abilities": document.get_abilities(user),
+        "nb_accesses": 5,
+        "content": document.content,
+        "created_at": document.created_at.isoformat().replace("+00:00", "Z"),
+        "is_favorite": False,
         "link_reach": "restricted",
         "link_role": document.link_role,
-        "created_at": document.created_at.isoformat().replace("+00:00", "Z"),
+        "title": document.title,
         "updated_at": document.updated_at.isoformat().replace("+00:00", "Z"),
     }
 
@@ -360,7 +299,7 @@ def test_api_documents_retrieve_authenticated_related_team_administrators(
 ):
     """
     Authenticated users should be allowed to retrieve a document to which they
-    are related via a team whatever the role and see all its accesses.
+    are related via a team whatever the role.
     """
     mock_user_teams.return_value = teams
 
@@ -371,98 +310,33 @@ def test_api_documents_retrieve_authenticated_related_team_administrators(
 
     document = factories.DocumentFactory(link_reach="restricted")
 
-    access_reader = factories.TeamDocumentAccessFactory(
+    factories.TeamDocumentAccessFactory(
         document=document, team="readers", role="reader"
     )
-    access_editor = factories.TeamDocumentAccessFactory(
+    factories.TeamDocumentAccessFactory(
         document=document, team="editors", role="editor"
     )
-    access_administrator = factories.TeamDocumentAccessFactory(
+    factories.TeamDocumentAccessFactory(
         document=document, team="administrators", role="administrator"
     )
-    access_owner = factories.TeamDocumentAccessFactory(
-        document=document, team="owners", role="owner"
-    )
-    other_access = factories.TeamDocumentAccessFactory(document=document)
+    factories.TeamDocumentAccessFactory(document=document, team="owners", role="owner")
+    factories.TeamDocumentAccessFactory(document=document)
     factories.TeamDocumentAccessFactory()
 
     response = client.get(f"/api/v1.0/documents/{document.id!s}/")
 
     # pylint: disable=R0801
     assert response.status_code == 200
-    content = response.json()
-    assert sorted(content.pop("accesses"), key=lambda x: x["id"]) == sorted(
-        [
-            {
-                "id": str(access_reader.id),
-                "user": None,
-                "team": "readers",
-                "role": "reader",
-                "abilities": {
-                    "destroy": True,
-                    "retrieve": True,
-                    "set_role_to": ["administrator", "editor"],
-                    "update": True,
-                    "partial_update": True,
-                },
-            },
-            {
-                "id": str(access_editor.id),
-                "user": None,
-                "team": "editors",
-                "role": "editor",
-                "abilities": {
-                    "destroy": True,
-                    "retrieve": True,
-                    "set_role_to": ["administrator", "reader"],
-                    "update": True,
-                    "partial_update": True,
-                },
-            },
-            {
-                "id": str(access_administrator.id),
-                "user": None,
-                "team": "administrators",
-                "role": "administrator",
-                "abilities": {
-                    "destroy": True,
-                    "retrieve": True,
-                    "set_role_to": ["editor", "reader"],
-                    "update": True,
-                    "partial_update": True,
-                },
-            },
-            {
-                "id": str(access_owner.id),
-                "user": None,
-                "team": "owners",
-                "role": "owner",
-                "abilities": {
-                    "destroy": False,
-                    "retrieve": True,
-                    "set_role_to": [],
-                    "update": False,
-                    "partial_update": False,
-                },
-            },
-            {
-                "id": str(other_access.id),
-                "user": None,
-                "team": other_access.team,
-                "role": other_access.role,
-                "abilities": other_access.get_abilities(user),
-            },
-        ],
-        key=lambda x: x["id"],
-    )
     assert response.json() == {
         "id": str(document.id),
-        "title": document.title,
-        "content": document.content,
         "abilities": document.get_abilities(user),
+        "nb_accesses": 5,
+        "content": document.content,
+        "created_at": document.created_at.isoformat().replace("+00:00", "Z"),
+        "is_favorite": False,
         "link_reach": "restricted",
         "link_role": document.link_role,
-        "created_at": document.created_at.isoformat().replace("+00:00", "Z"),
+        "title": document.title,
         "updated_at": document.updated_at.isoformat().replace("+00:00", "Z"),
     }
 
@@ -481,7 +355,7 @@ def test_api_documents_retrieve_authenticated_related_team_owners(
 ):
     """
     Authenticated users should be allowed to retrieve a restricted document to which
-    they are related via a team whatever the role and see all its accesses.
+    they are related via a team whatever the role.
     """
     mock_user_teams.return_value = teams
 
@@ -492,100 +366,32 @@ def test_api_documents_retrieve_authenticated_related_team_owners(
 
     document = factories.DocumentFactory(link_reach="restricted")
 
-    access_reader = factories.TeamDocumentAccessFactory(
+    factories.TeamDocumentAccessFactory(
         document=document, team="readers", role="reader"
     )
-    access_editor = factories.TeamDocumentAccessFactory(
+    factories.TeamDocumentAccessFactory(
         document=document, team="editors", role="editor"
     )
-    access_administrator = factories.TeamDocumentAccessFactory(
+    factories.TeamDocumentAccessFactory(
         document=document, team="administrators", role="administrator"
     )
-    access_owner = factories.TeamDocumentAccessFactory(
-        document=document, team="owners", role="owner"
-    )
-    other_access = factories.TeamDocumentAccessFactory(document=document)
+    factories.TeamDocumentAccessFactory(document=document, team="owners", role="owner")
+    factories.TeamDocumentAccessFactory(document=document)
     factories.TeamDocumentAccessFactory()
 
     response = client.get(f"/api/v1.0/documents/{document.id!s}/")
 
     # pylint: disable=R0801
     assert response.status_code == 200
-    content = response.json()
-    assert sorted(content.pop("accesses"), key=lambda x: x["id"]) == sorted(
-        [
-            {
-                "id": str(access_reader.id),
-                "user": None,
-                "team": "readers",
-                "role": "reader",
-                "abilities": {
-                    "destroy": True,
-                    "retrieve": True,
-                    "set_role_to": ["owner", "administrator", "editor"],
-                    "update": True,
-                    "partial_update": True,
-                },
-            },
-            {
-                "id": str(access_editor.id),
-                "user": None,
-                "team": "editors",
-                "role": "editor",
-                "abilities": {
-                    "destroy": True,
-                    "retrieve": True,
-                    "set_role_to": ["owner", "administrator", "reader"],
-                    "update": True,
-                    "partial_update": True,
-                },
-            },
-            {
-                "id": str(access_administrator.id),
-                "user": None,
-                "team": "administrators",
-                "role": "administrator",
-                "abilities": {
-                    "destroy": True,
-                    "retrieve": True,
-                    "set_role_to": ["owner", "editor", "reader"],
-                    "update": True,
-                    "partial_update": True,
-                },
-            },
-            {
-                "id": str(access_owner.id),
-                "user": None,
-                "team": "owners",
-                "role": "owner",
-                "abilities": {
-                    # editable only if there is another owner role than the user's team...
-                    "destroy": other_access.role == "owner",
-                    "retrieve": True,
-                    "set_role_to": ["administrator", "editor", "reader"]
-                    if other_access.role == "owner"
-                    else [],
-                    "update": other_access.role == "owner",
-                    "partial_update": other_access.role == "owner",
-                },
-            },
-            {
-                "id": str(other_access.id),
-                "user": None,
-                "team": other_access.team,
-                "role": other_access.role,
-                "abilities": other_access.get_abilities(user),
-            },
-        ],
-        key=lambda x: x["id"],
-    )
     assert response.json() == {
         "id": str(document.id),
-        "title": document.title,
-        "content": document.content,
         "abilities": document.get_abilities(user),
+        "nb_accesses": 5,
+        "content": document.content,
+        "created_at": document.created_at.isoformat().replace("+00:00", "Z"),
+        "is_favorite": False,
         "link_reach": "restricted",
         "link_role": document.link_role,
-        "created_at": document.created_at.isoformat().replace("+00:00", "Z"),
+        "title": document.title,
         "updated_at": document.updated_at.isoformat().replace("+00:00", "Z"),
     }

src/backend/core/tests/documents/test_api_documents_update.py

@@ -216,7 +216,7 @@ def test_api_documents_update_authenticated_editor_administrator_or_owner(
     document = models.Document.objects.get(pk=document.pk)
     document_values = serializers.DocumentSerializer(instance=document).data
     for key, value in document_values.items():
-        if key in ["id", "accesses", "created_at", "link_reach", "link_role"]:
+        if key in ["id", "created_at", "link_reach", "link_role", "nb_accesses"]:
             assert value == old_document_values[key]
         elif key == "updated_at":
             assert value > old_document_values[key]
@@ -255,7 +255,7 @@ def test_api_documents_update_authenticated_owners(via, mock_user_teams):
     document = models.Document.objects.get(pk=document.pk)
     document_values = serializers.DocumentSerializer(instance=document).data
     for key, value in document_values.items():
-        if key in ["id", "accesses", "created_at", "link_reach", "link_role"]:
+        if key in ["id", "created_at", "link_reach", "link_role", "nb_accesses"]:
             assert value == old_document_values[key]
         elif key == "updated_at":
             assert value > old_document_values[key]

src/backend/core/tests/test_models_documents.py

@@ -88,9 +88,10 @@ def test_models_documents_get_abilities_forbidden(is_authenticated, reach, role)
         "ai_transform": False,
         "ai_translate": False,
         "attachment_upload": False,
-        "link_configuration": False,
         "destroy": False,
+        "favorite": False,
         "invite_owner": False,
+        "link_configuration": False,
         "partial_update": False,
         "retrieve": False,
         "update": False,
@@ -123,8 +124,9 @@ def test_models_documents_get_abilities_reader(is_authenticated, reach):
         "ai_translate": False,
         "attachment_upload": False,
         "destroy": False,
-        "link_configuration": False,
+        "favorite": is_authenticated,
         "invite_owner": False,
+        "link_configuration": False,
         "partial_update": False,
         "retrieve": True,
         "update": False,
@@ -157,8 +159,9 @@ def test_models_documents_get_abilities_editor(is_authenticated, reach):
         "ai_translate": True,
         "attachment_upload": True,
         "destroy": False,
-        "link_configuration": False,
+        "favorite": is_authenticated,
         "invite_owner": False,
+        "link_configuration": False,
         "partial_update": True,
         "retrieve": True,
         "update": True,
@@ -180,8 +183,9 @@ def test_models_documents_get_abilities_owner():
         "ai_translate": True,
         "attachment_upload": True,
         "destroy": True,
-        "link_configuration": True,
+        "favorite": True,
         "invite_owner": True,
+        "link_configuration": True,
         "partial_update": True,
         "retrieve": True,
         "update": True,
@@ -202,8 +206,9 @@ def test_models_documents_get_abilities_administrator():
         "ai_translate": True,
         "attachment_upload": True,
         "destroy": False,
-        "link_configuration": True,
+        "favorite": True,
         "invite_owner": False,
+        "link_configuration": True,
         "partial_update": True,
         "retrieve": True,
         "update": True,
@@ -227,8 +232,9 @@ def test_models_documents_get_abilities_editor_user(django_assert_num_queries):
         "ai_translate": True,
         "attachment_upload": True,
         "destroy": False,
-        "link_configuration": False,
+        "favorite": True,
         "invite_owner": False,
+        "link_configuration": False,
         "partial_update": True,
         "retrieve": True,
         "update": True,
@@ -254,8 +260,9 @@ def test_models_documents_get_abilities_reader_user(django_assert_num_queries):
         "ai_translate": False,
         "attachment_upload": False,
         "destroy": False,
-        "link_configuration": False,
+        "favorite": True,
         "invite_owner": False,
+        "link_configuration": False,
         "partial_update": False,
         "retrieve": True,
         "update": False,
@@ -282,8 +289,9 @@ def test_models_documents_get_abilities_preset_role(django_assert_num_queries):
         "ai_translate": False,
         "attachment_upload": False,
         "destroy": False,
-        "link_configuration": False,
+        "favorite": True,
         "invite_owner": False,
+        "link_configuration": False,
         "partial_update": False,
         "retrieve": True,
         "update": False,