Feature: Nested Tags (#10833)

---------

Co-authored-by: Trenton H <797416+stumpylog@users.noreply.github.com>

src/documents/models.py

@@ -7,12 +7,14 @@ from celery import states
 from django.conf import settings
 from django.contrib.auth.models import Group
 from django.contrib.auth.models import User
+from django.core.exceptions import ValidationError
 from django.core.validators import MaxValueValidator
 from django.core.validators import MinValueValidator
 from django.db import models
 from django.utils import timezone
 from django.utils.translation import gettext_lazy as _
 from multiselectfield import MultiSelectField
+from treenode.models import TreeNodeModel
 
 if settings.AUDIT_LOG_ENABLED:
     from auditlog.registry import auditlog
@@ -96,8 +98,10 @@ class Correspondent(MatchingModel):
         verbose_name_plural = _("correspondents")
 
 
-class Tag(MatchingModel):
+class Tag(MatchingModel, TreeNodeModel):
     color = models.CharField(_("color"), max_length=7, default="#a6cee3")
+    # Maximum allowed nesting depth for tags (root = 1, max depth = 5)
+    MAX_NESTING_DEPTH: Final[int] = 5
 
     is_inbox_tag = models.BooleanField(
         _("is inbox tag"),
@@ -108,10 +112,30 @@ class Tag(MatchingModel):
         ),
     )
 
-    class Meta(MatchingModel.Meta):
+    class Meta(MatchingModel.Meta, TreeNodeModel.Meta):
         verbose_name = _("tag")
         verbose_name_plural = _("tags")
 
+    def clean(self):
+        # Prevent self-parenting and assigning a descendant as parent
+        parent = self.get_parent()
+        if parent == self:
+            raise ValidationError({"parent": _("Cannot set itself as parent.")})
+        if parent and self.pk is not None and self.is_ancestor_of(parent):
+            raise ValidationError({"parent": _("Cannot set parent to a descendant.")})
+
+        # Enforce maximum nesting depth
+        new_parent_depth = 0
+        if parent:
+            new_parent_depth = parent.get_ancestors_count() + 1
+
+        height = 0 if self.pk is None else self.get_depth()
+        deepest_new_depth = (new_parent_depth + 1) + height
+        if deepest_new_depth > self.MAX_NESTING_DEPTH:
+            raise ValidationError(_("Maximum nesting depth exceeded."))
+
+        return super().clean()
+
 
 class DocumentType(MatchingModel):
     class Meta(MatchingModel.Meta):
@@ -398,6 +422,15 @@ class Document(SoftDeleteModel, ModelWithOwner):
     def created_date(self):
         return self.created
 
+    def add_nested_tags(self, tags):
+        tag_ids = set()
+        for tag in tags:
+            tag_ids.add(tag.id)
+            tag_ids.update(tag.get_ancestors_pks())
+
+        tags_to_add = self.tags.model.objects.filter(id__in=tag_ids)
+        self.tags.add(*tags_to_add)
+
 
 class SavedView(ModelWithOwner):
     class DisplayMode(models.TextChoices):