✨(backend) implement thread and reactions API

In order to use comment we also have to implement a thread and reactions
API. A thread has multiple comments and comments can have multiple
reactions.

Author: AntoLC

src/backend/core/api/serializers.py

@@ -879,45 +879,122 @@ class MoveDocumentSerializer(serializers.Serializer):
     )
 
 
+class ReactionSerializer(serializers.ModelSerializer):
+    """Serialize reactions."""
+
+    users = UserLightSerializer(many=True, read_only=True)
+
+    class Meta:
+        model = models.Reaction
+        fields = [
+            "id",
+            "emoji",
+            "created_at",
+            "users",
+        ]
+        read_only_fields = ["id", "created_at", "users"]
+
+
 class CommentSerializer(serializers.ModelSerializer):
-    """Serialize comments."""
+    """Serialize comments (nested under a thread) with reactions and abilities."""
 
     user = UserLightSerializer(read_only=True)
-    abilities = serializers.SerializerMethodField(read_only=True)
+    abilities = serializers.SerializerMethodField()
+    reactions = ReactionSerializer(many=True, read_only=True)
 
     class Meta:
         model = models.Comment
         fields = [
             "id",
-            "content",
+            "user",
+            "body",
             "created_at",
             "updated_at",
-            "user",
-            "document",
+            "reactions",
             "abilities",
         ]
         read_only_fields = [
             "id",
+            "user",
             "created_at",
             "updated_at",
-            "user",
-            "document",
+            "reactions",
             "abilities",
         ]
 
-    def get_abilities(self, comment) -> dict:
-        """Return abilities of the logged-in user on the instance."""
+    def validate(self, attrs):
+        """Validate comment data."""
+
+        request = self.context.get("request")
+        user = getattr(request, "user", None)
+
+        attrs["thread_id"] = self.context["thread_id"]
+        attrs["user_id"] = user.id if user else None
+        return attrs
+
+    def get_abilities(self, obj):
+        """Return comment's abilities."""
         request = self.context.get("request")
         if request:
-            return comment.get_abilities(request.user)
+            return obj.get_abilities(request.user)
         return {}
 
+
+class ThreadSerializer(serializers.ModelSerializer):
+    """Serialize threads in a backward compatible shape for current frontend.
+
+    We expose a flatten representation where ``content`` maps to the first
+    comment's body. Creating a thread requires a ``content`` field which is
+    stored as the first comment.
+    """
+
+    creator = UserLightSerializer(read_only=True)
+    abilities = serializers.SerializerMethodField(read_only=True)
+    body = serializers.JSONField(write_only=True, required=True)
+    comments = serializers.SerializerMethodField(read_only=True)
+    comments = CommentSerializer(many=True, read_only=True)
+
+    class Meta:
+        model = models.Thread
+        fields = [
+            "id",
+            "body",
+            "created_at",
+            "updated_at",
+            "creator",
+            "abilities",
+            "comments",
+            "resolved",
+            "resolved_at",
+            "resolved_by",
+            "metadata",
+        ]
+        read_only_fields = [
+            "id",
+            "created_at",
+            "updated_at",
+            "creator",
+            "abilities",
+            "comments",
+            "resolved",
+            "resolved_at",
+            "resolved_by",
+            "metadata",
+        ]
+
     def validate(self, attrs):
-        """Validate invitation data."""
+        """Validate thread data."""
         request = self.context.get("request")
         user = getattr(request, "user", None)
 
         attrs["document_id"] = self.context["resource_id"]
-        attrs["user_id"] = user.id if user else None
+        attrs["creator_id"] = user.id if user else None
 
         return attrs
+
+    def get_abilities(self, thread):
+        """Return thread's abilities."""
+        request = self.context.get("request")
+        if request:
+            return thread.get_abilities(request.user)
+        return {}

src/backend/core/api/viewsets.py

@@ -21,6 +21,7 @@
 from django.db.models.functions import Left, Length
 from django.http import Http404, StreamingHttpResponse
 from django.urls import reverse
+from django.utils import timezone
 from django.utils.functional import cached_property
 from django.utils.text import capfirst, slugify
 from django.utils.translation import gettext_lazy as _
@@ -2203,15 +2204,9 @@ def _load_theme_customization(self):
         return theme_customization
 
 
-class CommentViewSet(
-    viewsets.ModelViewSet,
-):
-    """API ViewSet for comments."""
+class CommentViewSetMixin:
+    """Comment ViewSet Mixin."""
 
-    permission_classes = [permissions.CommentPermission]
-    queryset = models.Comment.objects.select_related("user", "document").all()
-    serializer_class = serializers.CommentSerializer
-    pagination_class = Pagination
     _document = None
 
     def get_document_or_404(self):
@@ -2225,12 +2220,114 @@ def get_document_or_404(self):
                 raise drf.exceptions.NotFound("Document not found.") from e
         return self._document
 
+
+class ThreadViewSet(
+    ResourceAccessViewsetMixin,
+    CommentViewSetMixin,
+    drf.mixins.CreateModelMixin,
+    drf.mixins.ListModelMixin,
+    drf.mixins.RetrieveModelMixin,
+    drf.mixins.DestroyModelMixin,
+    viewsets.GenericViewSet,
+):
+    """Thread API: list/create threads and nested comment operations."""
+
+    permission_classes = [permissions.CommentPermission]
+    pagination_class = Pagination
+    serializer_class = serializers.ThreadSerializer
+    queryset = models.Thread.objects.select_related("creator", "document").filter(
+        resolved=False
+    )
+    resource_field_name = "document"
+
+    def perform_create(self, serializer):
+        """Create the first comment of the thread."""
+        body = serializer.validated_data["body"]
+        del serializer.validated_data["body"]
+        thread = serializer.save()
+
+        models.Comment.objects.create(
+            thread=thread,
+            user=self.request.user if self.request.user.is_authenticated else None,
+            body=body,
+        )
+
+    @drf.decorators.action(detail=True, methods=["post"], url_path="resolve")
+    def resolve(self, request, *args, **kwargs):
+        """Resolve a thread."""
+        thread = self.get_object()
+        if not thread.resolved:
+            thread.resolved = True
+            thread.resolved_at = timezone.now()
+            thread.resolved_by = request.user
+            thread.save(update_fields=["resolved", "resolved_at", "resolved_by"])
+        return drf.response.Response(status=status.HTTP_204_NO_CONTENT)
+
+
+class CommentViewSet(
+    CommentViewSetMixin,
+    viewsets.ModelViewSet,
+):
+    """Comment API: list/create comments and nested reaction operations."""
+
+    permission_classes = [permissions.CommentPermission]
+    pagination_class = Pagination
+    serializer_class = serializers.CommentSerializer
+    queryset = models.Comment.objects.select_related("user").all()
+
+    def get_queryset(self):
+        """Override to filter on related resource."""
+        return (
+            super()
+            .get_queryset()
+            .filter(
+                thread=self.kwargs["thread_id"],
+                thread__document=self.kwargs["resource_id"],
+            )
+        )
+
     def get_serializer_context(self):
         """Extra context provided to the serializer class."""
         context = super().get_serializer_context()
-        context["resource_id"] = self.kwargs["resource_id"]
+        context["document_id"] = self.kwargs["resource_id"]
+        context["thread_id"] = self.kwargs["thread_id"]
         return context
 
-    def get_queryset(self):
-        """Return the queryset according to the action."""
-        return super().get_queryset().filter(document=self.kwargs["resource_id"])
+    @drf.decorators.action(
+        detail=True,
+        methods=["post", "delete"],
+    )
+    def reactions(self, request, *args, **kwargs):
+        """POST: add reaction; DELETE: remove reaction.
+
+        Emoji is expected in request.data['emoji'] for both operations.
+        """
+        comment = self.get_object()
+        serializer = serializers.ReactionSerializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+
+        if request.method == "POST":
+            reaction, created = models.Reaction.objects.get_or_create(
+                comment=comment,
+                emoji=serializer.validated_data["emoji"],
+            )
+            if not created and reaction.users.filter(id=request.user.id).exists():
+                return drf.response.Response(
+                    {"user_already_reacted": True}, status=status.HTTP_400_BAD_REQUEST
+                )
+            reaction.users.add(request.user)
+            return drf.response.Response(status=status.HTTP_201_CREATED)
+
+        # DELETE
+        try:
+            reaction = models.Reaction.objects.get(
+                comment=comment,
+                emoji=serializer.validated_data["emoji"],
+                users__in=[request.user],
+            )
+        except models.Reaction.DoesNotExist as e:
+            raise drf.exceptions.NotFound("Reaction not found.") from e
+        reaction.users.remove(request.user)
+        if not reaction.users.exists():
+            reaction.delete()
+        return drf.response.Response(status=status.HTTP_204_NO_CONTENT)

src/backend/core/choices.py

@@ -33,15 +33,15 @@ class LinkRoleChoices(PriorityTextChoices):
     """Defines the possible roles a link can offer on a document."""
 
     READER = "reader", _("Reader")  # Can read
-    COMMENTATOR = "commentator", _("Commentator")  # Can read and comment
+    COMMENTER = "commenter", _("Commenter")  # Can read and comment
     EDITOR = "editor", _("Editor")  # Can read and edit
 
 
 class RoleChoices(PriorityTextChoices):
     """Defines the possible roles a user can have in a resource."""
 
     READER = "reader", _("Reader")  # Can read
-    COMMENTATOR = "commentator", _("Commentator")  # Can read and comment
+    COMMENTER = "commenter", _("Commenter")  # Can read and comment
     EDITOR = "editor", _("Editor")  # Can read and edit
     ADMIN = "administrator", _("Administrator")  # Can read, edit, delete and share
     OWNER = "owner", _("Owner")

src/backend/core/factories.py

@@ -258,12 +258,47 @@ class Meta:
     issuer = factory.SubFactory(UserFactory)
 
 
+class ThreadFactory(factory.django.DjangoModelFactory):
+    """A factory to create threads for a document"""
+
+    class Meta:
+        model = models.Thread
+
+    document = factory.SubFactory(DocumentFactory)
+    creator = factory.SubFactory(UserFactory)
+
+
 class CommentFactory(factory.django.DjangoModelFactory):
-    """A factory to create comments for a document"""
+    """A factory to create comments for a thread"""
 
     class Meta:
         model = models.Comment
 
-    document = factory.SubFactory(DocumentFactory)
+    thread = factory.SubFactory(ThreadFactory)
     user = factory.SubFactory(UserFactory)
-    content = factory.Faker("text")
+    body = factory.Faker("text")
+
+
+class ReactionFactory(factory.django.DjangoModelFactory):
+    """A factory to create reactions for a comment"""
+
+    class Meta:
+        model = models.Reaction
+
+    comment = factory.SubFactory(CommentFactory)
+    emoji = "test"
+
+    @factory.post_generation
+    def users(self, create, extracted, **kwargs):
+        """Add users to reaction from a given list of users or create one if not provided."""
+        if not create:
+            return
+
+        if not extracted:
+            # the factory is being created, but no users were provided
+            user = UserFactory()
+            self.users.add(user)
+            return
+
+        # Add the iterable of groups using bulk addition
+        self.users.add(*extracted)