✨(backend) add "tree" action on document API endpoint

We want to display the tree structure to which a document belongs
on the left side panel of its detail view. For this, we need an
endpoint to retrieve the list view of the document's ancestors
opened.

By opened, we mean that when display the document, we also need to
display its siblings. When displaying the parent of the current
document, we also need to display the siblings of the parent...

src/backend/core/models.py

@@ -29,7 +29,7 @@ from django.utils.translation import gettext_lazy as _
 from botocore.exceptions import ClientError
 from rest_framework.exceptions import ValidationError
 from timezone_field import TimeZoneField
-from treebeard.mp_tree import MP_Node
+from treebeard.mp_tree import MP_Node, MP_NodeManager, MP_NodeQuerySet
 
 logger = getLogger(__name__)
 
@@ -369,6 +369,51 @@ class BaseAccess(BaseModel):
         }
 
 
+class DocumentQuerySet(MP_NodeQuerySet):
+    """
+    Custom queryset for the Document model, providing additional methods
+    to filter documents based on user permissions.
+    """
+
+    def readable_per_se(self, user):
+        """
+        Filters the queryset to return documents that the given user has
+        permission to read.
+        :param user: The user for whom readable documents are to be fetched.
+        :return: A queryset of documents readable by the user.
+        """
+        if user.is_authenticated:
+            return self.filter(
+                models.Q(accesses__user=user)
+                | models.Q(accesses__team__in=user.teams)
+                | ~models.Q(link_reach=LinkReachChoices.RESTRICTED)
+            )
+
+        return self.filter(link_reach=LinkReachChoices.PUBLIC)
+
+
+class DocumentManager(MP_NodeManager):
+    """
+    Custom manager for the Document model, enabling the use of the custom
+    queryset methods directly from the model manager.
+    """
+
+    def get_queryset(self):
+        """
+        Overrides the default get_queryset method to return a custom queryset.
+        :return: An instance of DocumentQuerySet.
+        """
+        return DocumentQuerySet(self.model, using=self._db)
+
+    def readable_per_se(self, user):
+        """
+        Filters documents based on user permissions using the custom queryset.
+        :param user: The user for whom readable documents are to be fetched.
+        :return: A queryset of documents readable by the user.
+        """
+        return self.get_queryset().readable_per_se(user)
+
+
 class Document(MP_Node, BaseModel):
     """Pad document carrying the content."""
 
@@ -401,6 +446,8 @@ class Document(MP_Node, BaseModel):
 
     path = models.CharField(max_length=7 * 36, unique=True, db_collation="C")
 
+    objects = DocumentManager()
+
     class Meta:
         db_table = "impress_document"
         ordering = ("path",)
@@ -574,7 +621,11 @@ class Document(MP_Node, BaseModel):
     def invalidate_nb_accesses_cache(self):
         """
         Invalidate the cache for number of accesses, including on affected descendants.
+        Args:
+            path: can optionally be passed as argument (useful when invalidating cache for a
+                document we just deleted)
         """
+
         for document in Document.objects.filter(path__startswith=self.path).only("id"):
             cache_key = document.get_nb_accesses_cache_key()
             cache.delete(cache_key)
@@ -682,6 +733,7 @@ class Document(MP_Node, BaseModel):
             "restore": is_owner,
             "retrieve": can_get,
             "media_auth": can_get,
+            "tree": can_get,
             "update": can_update,
             "versions_destroy": is_owner_or_admin,
             "versions_list": has_access_role,