Allow organizing documents in a tree structure

src/backend/core/admin.py

@@ -4,12 +4,15 @@
 from django.contrib.auth import admin as auth_admin
 from django.utils.translation import gettext_lazy as _
 
+from treebeard.admin import TreeAdmin
+
 from . import models
 
 
 class TemplateAccessInline(admin.TabularInline):
     """Inline admin class for template accesses."""
 
+    autocomplete_fields = ["user"]
     model = models.TemplateAccess
     extra = 0
 
@@ -111,14 +114,46 @@ class TemplateAdmin(admin.ModelAdmin):
 class DocumentAccessInline(admin.TabularInline):
     """Inline admin class for template accesses."""
 
+    autocomplete_fields = ["user"]
     model = models.DocumentAccess
     extra = 0
 
 
 @admin.register(models.Document)
-class DocumentAdmin(admin.ModelAdmin):
+class DocumentAdmin(TreeAdmin):
     """Document admin interface declaration."""
 
+    fieldsets = (
+        (
+            None,
+            {
+                "fields": (
+                    "id",
+                    "title",
+                )
+            },
+        ),
+        (
+            _("Permissions"),
+            {
+                "fields": (
+                    "creator",
+                    "link_reach",
+                    "link_role",
+                )
+            },
+        ),
+        (
+            _("Tree structure"),
+            {
+                "fields": (
+                    "path",
+                    "depth",
+                    "numchild",
+                )
+            },
+        ),
+    )
     inlines = (DocumentAccessInline,)
     list_display = (
         "id",
@@ -128,6 +163,14 @@ class DocumentAdmin(admin.ModelAdmin):
         "created_at",
         "updated_at",
     )
+    readonly_fields = (
+        "creator",
+        "depth",
+        "id",
+        "numchild",
+        "path",
+    )
+    search_fields = ("id", "title")
 
 
 @admin.register(models.Invitation)

src/backend/core/api/permissions.py

@@ -8,7 +8,8 @@
 from core.models import DocumentAccess, RoleChoices
 
 ACTION_FOR_METHOD_TO_PERMISSION = {
-    "versions_detail": {"DELETE": "versions_destroy", "GET": "versions_retrieve"}
+    "versions_detail": {"DELETE": "versions_destroy", "GET": "versions_retrieve"},
+    "children": {"GET": "children_list", "POST": "children_create"},
 }
 
 

src/backend/core/api/serializers.py

@@ -147,34 +147,54 @@ class ListDocumentSerializer(BaseResourceSerializer):
 
     is_favorite = serializers.BooleanField(read_only=True)
     nb_accesses = serializers.IntegerField(read_only=True)
+    user_roles = serializers.SerializerMethodField(read_only=True)
 
     class Meta:
         model = models.Document
         fields = [
             "id",
             "abilities",
-            "content",
             "created_at",
             "creator",
+            "depth",
+            "excerpt",
             "is_favorite",
             "link_role",
             "link_reach",
             "nb_accesses",
+            "numchild",
+            "path",
             "title",
             "updated_at",
+            "user_roles",
         ]
         read_only_fields = [
             "id",
             "abilities",
             "created_at",
             "creator",
+            "depth",
+            "excerpt",
             "is_favorite",
             "link_role",
             "link_reach",
             "nb_accesses",
+            "numchild",
+            "path",
             "updated_at",
+            "user_roles",
         ]
 
+    def get_user_roles(self, document):
+        """
+        Return roles of the logged-in user for the current document,
+        taking into account ancestors.
+        """
+        request = self.context.get("request")
+        if request:
+            return document.get_roles(request.user)
+        return []
+
 
 class DocumentSerializer(ListDocumentSerializer):
     """Serialize documents with all fields for display in detail views."""
@@ -189,23 +209,32 @@ class Meta:
             "content",
             "created_at",
             "creator",
+            "depth",
+            "excerpt",
             "is_favorite",
             "link_role",
             "link_reach",
             "nb_accesses",
+            "numchild",
+            "path",
             "title",
             "updated_at",
+            "user_roles",
         ]
         read_only_fields = [
             "id",
             "abilities",
             "created_at",
             "creator",
-            "is_avorite",
+            "depth",
+            "is_favorite",
             "link_role",
             "link_reach",
             "nb_accesses",
+            "numchild",
+            "path",
             "updated_at",
+            "user_roles",
         ]
 
     def get_fields(self):
@@ -281,7 +310,7 @@ def create(self, validated_data):
         except ConversionError as err:
             raise exceptions.APIException(detail="could not convert content") from err
 
-        document = models.Document.objects.create(
+        document = models.Document.add_root(
             title=validated_data["title"],
             content=document_content,
             creator=user,
@@ -529,3 +558,44 @@ def validate_text(self, value):
         if len(value.strip()) == 0:
             raise serializers.ValidationError("Text field cannot be empty.")
         return value
+
+
+class MoveDocumentSerializer(serializers.Serializer):
+    """
+    Serializer for validating input data to move a document within the tree structure.
+
+    Fields:
+        - target_document_id (UUIDField): The ID of the target parent document where the
+            document should be moved. This field is required and must be a valid UUID.
+        - position (ChoiceField): Specifies the position of the document in relation to
+            the target parent's children.
+          Choices:
+            - "first-child": Place the document as the first child of the target parent.
+            - "last-child": Place the document as the last child of the target parent (default).
+            - "left": Place the document as the left sibling of the target parent.
+            - "right": Place the document as the right sibling of the target parent.
+
+    Example:
+        Input payload for moving a document:
+        {
+            "target_document_id": "123e4567-e89b-12d3-a456-426614174000",
+            "position": "first-child"
+        }
+
+    Notes:
+        - The `target_document_id` is mandatory.
+        - The `position` defaults to "last-child" if not provided.
+    """
+
+    target_document_id = serializers.UUIDField(required=True)
+    position = serializers.ChoiceField(
+        choices=[
+            "first-child",
+            "last-child",
+            "first-sibling",
+            "last-sibling",
+            "left",
+            "right",
+        ],
+        default="last-child",
+    )