Feature: document file versions (#12061)

src/documents/tests/test_api_document_versions.py

@@ -0,0 +1,811 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from unittest import TestCase
+from unittest import mock
+
+from auditlog.models import LogEntry  # type: ignore[import-untyped]
+from django.contrib.auth.models import Permission
+from django.contrib.auth.models import User
+from django.contrib.contenttypes.models import ContentType
+from django.core.exceptions import FieldError
+from django.core.files.uploadedfile import SimpleUploadedFile
+from rest_framework import status
+from rest_framework.test import APITestCase
+
+from documents.data_models import DocumentSource
+from documents.filters import EffectiveContentFilter
+from documents.filters import TitleContentFilter
+from documents.models import Document
+from documents.tests.utils import DirectoriesMixin
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class TestDocumentVersioningApi(DirectoriesMixin, APITestCase):
+    def setUp(self) -> None:
+        super().setUp()
+
+        self.user = User.objects.create_superuser(username="temp_admin")
+        self.client.force_authenticate(user=self.user)
+
+    def _make_pdf_upload(self, name: str = "version.pdf") -> SimpleUploadedFile:
+        return SimpleUploadedFile(
+            name,
+            b"%PDF-1.4\n1 0 obj\n<<>>\nendobj\n%%EOF",
+            content_type="application/pdf",
+        )
+
+    def _write_file(self, path: Path, content: bytes = b"data") -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(content)
+
+    def _create_pdf(
+        self,
+        *,
+        title: str,
+        checksum: str,
+        root_document: Document | None = None,
+    ) -> Document:
+        doc = Document.objects.create(
+            title=title,
+            checksum=checksum,
+            mime_type="application/pdf",
+            root_document=root_document,
+        )
+        self._write_file(doc.source_path, b"pdf")
+        self._write_file(doc.thumbnail_path, b"thumb")
+        return doc
+
+    def test_root_endpoint_returns_root_for_version_and_root(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+        )
+        version = Document.objects.create(
+            title="v1",
+            checksum="v1",
+            mime_type="application/pdf",
+            root_document=root,
+        )
+
+        resp_root = self.client.get(f"/api/documents/{root.id}/root/")
+        self.assertEqual(resp_root.status_code, status.HTTP_200_OK)
+        self.assertEqual(resp_root.data["root_id"], root.id)
+
+        resp_version = self.client.get(f"/api/documents/{version.id}/root/")
+        self.assertEqual(resp_version.status_code, status.HTTP_200_OK)
+        self.assertEqual(resp_version.data["root_id"], root.id)
+
+    def test_root_endpoint_returns_404_for_missing_document(self) -> None:
+        resp = self.client.get("/api/documents/9999/root/")
+
+        self.assertEqual(resp.status_code, status.HTTP_404_NOT_FOUND)
+
+    def test_root_endpoint_returns_403_when_user_lacks_permission(self) -> None:
+        owner = User.objects.create_user(username="owner")
+        viewer = User.objects.create_user(username="viewer")
+        viewer.user_permissions.add(
+            Permission.objects.get(codename="view_document"),
+        )
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+            owner=owner,
+        )
+        self.client.force_authenticate(user=viewer)
+
+        resp = self.client.get(f"/api/documents/{root.id}/root/")
+
+        self.assertEqual(resp.status_code, status.HTTP_403_FORBIDDEN)
+
+    def test_delete_version_disallows_deleting_root(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+        )
+
+        with mock.patch("documents.index.remove_document_from_index"):
+            resp = self.client.delete(f"/api/documents/{root.id}/versions/{root.id}/")
+
+        self.assertEqual(resp.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertTrue(Document.objects.filter(id=root.id).exists())
+
+    def test_delete_version_deletes_version_and_returns_current_version(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+            content="root-content",
+        )
+        v1 = Document.objects.create(
+            title="v1",
+            checksum="v1",
+            mime_type="application/pdf",
+            root_document=root,
+            content="v1-content",
+        )
+        v2 = Document.objects.create(
+            title="v2",
+            checksum="v2",
+            mime_type="application/pdf",
+            root_document=root,
+            content="v2-content",
+        )
+
+        with (
+            mock.patch("documents.index.remove_document_from_index"),
+            mock.patch("documents.index.add_or_update_document"),
+        ):
+            resp = self.client.delete(f"/api/documents/{root.id}/versions/{v2.id}/")
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        self.assertFalse(Document.objects.filter(id=v2.id).exists())
+        self.assertEqual(resp.data["current_version_id"], v1.id)
+        root.refresh_from_db()
+        self.assertEqual(root.content, "root-content")
+
+        with (
+            mock.patch("documents.index.remove_document_from_index"),
+            mock.patch("documents.index.add_or_update_document"),
+        ):
+            resp = self.client.delete(f"/api/documents/{root.id}/versions/{v1.id}/")
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        self.assertFalse(Document.objects.filter(id=v1.id).exists())
+        self.assertEqual(resp.data["current_version_id"], root.id)
+        root.refresh_from_db()
+        self.assertEqual(root.content, "root-content")
+
+    def test_delete_version_writes_audit_log_entry(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+        )
+        version = Document.objects.create(
+            title="v1",
+            checksum="v1",
+            mime_type="application/pdf",
+            root_document=root,
+        )
+        version_id = version.id
+
+        with (
+            mock.patch("documents.index.remove_document_from_index"),
+            mock.patch("documents.index.add_or_update_document"),
+        ):
+            resp = self.client.delete(
+                f"/api/documents/{root.id}/versions/{version_id}/",
+            )
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+
+        # Audit log entry is created against the root document.
+        entry = (
+            LogEntry.objects.filter(
+                content_type=ContentType.objects.get_for_model(Document),
+                object_id=root.id,
+            )
+            .order_by("-timestamp")
+            .first()
+        )
+        self.assertIsNotNone(entry)
+        assert entry is not None
+        self.assertIsNotNone(entry.actor)
+        assert entry.actor is not None
+        self.assertEqual(entry.actor.id, self.user.id)
+        self.assertEqual(entry.action, LogEntry.Action.UPDATE)
+        self.assertEqual(
+            entry.changes,
+            {"Version Deleted": ["None", version_id]},
+        )
+        additional_data = entry.additional_data or {}
+        self.assertEqual(additional_data.get("version_id"), version_id)
+
+    def test_delete_version_returns_404_when_version_not_related(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+        )
+        other_root = Document.objects.create(
+            title="other",
+            checksum="other",
+            mime_type="application/pdf",
+        )
+        other_version = Document.objects.create(
+            title="other-v1",
+            checksum="other-v1",
+            mime_type="application/pdf",
+            root_document=other_root,
+        )
+
+        with mock.patch("documents.index.remove_document_from_index"):
+            resp = self.client.delete(
+                f"/api/documents/{root.id}/versions/{other_version.id}/",
+            )
+
+        self.assertEqual(resp.status_code, status.HTTP_404_NOT_FOUND)
+
+    def test_delete_version_accepts_version_id_as_root_parameter(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+        )
+        version = Document.objects.create(
+            title="v1",
+            checksum="v1",
+            mime_type="application/pdf",
+            root_document=root,
+        )
+
+        with (
+            mock.patch("documents.index.remove_document_from_index"),
+            mock.patch("documents.index.add_or_update_document"),
+        ):
+            resp = self.client.delete(
+                f"/api/documents/{version.id}/versions/{version.id}/",
+            )
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        self.assertFalse(Document.objects.filter(id=version.id).exists())
+        self.assertEqual(resp.data["current_version_id"], root.id)
+
+    def test_delete_version_returns_404_when_root_missing(self) -> None:
+        resp = self.client.delete("/api/documents/9999/versions/123/")
+
+        self.assertEqual(resp.status_code, status.HTTP_404_NOT_FOUND)
+
+    def test_delete_version_reindexes_root_document(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+        )
+        version = Document.objects.create(
+            title="v1",
+            checksum="v1",
+            mime_type="application/pdf",
+            root_document=root,
+        )
+
+        with (
+            mock.patch("documents.index.remove_document_from_index") as remove_index,
+            mock.patch("documents.index.add_or_update_document") as add_or_update,
+        ):
+            resp = self.client.delete(
+                f"/api/documents/{root.id}/versions/{version.id}/",
+            )
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        remove_index.assert_called_once_with(version)
+        add_or_update.assert_called_once()
+        self.assertEqual(add_or_update.call_args[0][0].id, root.id)
+
+    def test_delete_version_returns_403_without_permission(self) -> None:
+        owner = User.objects.create_user(username="owner")
+        other = User.objects.create_user(username="other")
+        other.user_permissions.add(
+            Permission.objects.get(codename="delete_document"),
+        )
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+            owner=owner,
+        )
+        version = Document.objects.create(
+            title="v1",
+            checksum="v1",
+            mime_type="application/pdf",
+            root_document=root,
+        )
+        self.client.force_authenticate(user=other)
+
+        resp = self.client.delete(
+            f"/api/documents/{root.id}/versions/{version.id}/",
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_403_FORBIDDEN)
+
+    def test_delete_version_returns_404_when_version_missing(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+        )
+
+        resp = self.client.delete(f"/api/documents/{root.id}/versions/9999/")
+
+        self.assertEqual(resp.status_code, status.HTTP_404_NOT_FOUND)
+
+    def test_update_version_label_updates_and_trims(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+        )
+        version = Document.objects.create(
+            title="v1",
+            checksum="v1",
+            mime_type="application/pdf",
+            root_document=root,
+            version_label="old",
+        )
+
+        resp = self.client.patch(
+            f"/api/documents/{root.id}/versions/{version.id}/",
+            {"version_label": "  Label 1  "},
+            format="json",
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        version.refresh_from_db()
+        self.assertEqual(version.version_label, "Label 1")
+        self.assertEqual(resp.data["version_label"], "Label 1")
+        self.assertEqual(resp.data["id"], version.id)
+        self.assertFalse(resp.data["is_root"])
+
+    def test_update_version_label_clears_on_blank(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+            version_label="Root Label",
+        )
+
+        resp = self.client.patch(
+            f"/api/documents/{root.id}/versions/{root.id}/",
+            {"version_label": "   "},
+            format="json",
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        root.refresh_from_db()
+        self.assertIsNone(root.version_label)
+        self.assertIsNone(resp.data["version_label"])
+        self.assertTrue(resp.data["is_root"])
+
+    def test_update_version_label_returns_403_without_permission(self) -> None:
+        owner = User.objects.create_user(username="owner")
+        other = User.objects.create_user(username="other")
+        other.user_permissions.add(
+            Permission.objects.get(codename="change_document"),
+        )
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+            owner=owner,
+        )
+        version = Document.objects.create(
+            title="v1",
+            checksum="v1",
+            mime_type="application/pdf",
+            root_document=root,
+        )
+        self.client.force_authenticate(user=other)
+
+        resp = self.client.patch(
+            f"/api/documents/{root.id}/versions/{version.id}/",
+            {"version_label": "Blocked"},
+            format="json",
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_403_FORBIDDEN)
+
+    def test_update_version_label_returns_404_for_unrelated_version(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+        )
+        other_root = Document.objects.create(
+            title="other",
+            checksum="other",
+            mime_type="application/pdf",
+        )
+        other_version = Document.objects.create(
+            title="other-v1",
+            checksum="other-v1",
+            mime_type="application/pdf",
+            root_document=other_root,
+        )
+
+        resp = self.client.patch(
+            f"/api/documents/{root.id}/versions/{other_version.id}/",
+            {"version_label": "Nope"},
+            format="json",
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_404_NOT_FOUND)
+
+    def test_download_version_param_errors(self) -> None:
+        root = self._create_pdf(title="root", checksum="root")
+
+        resp = self.client.get(
+            f"/api/documents/{root.id}/download/?version=not-a-number",
+        )
+        self.assertEqual(resp.status_code, status.HTTP_404_NOT_FOUND)
+
+        resp = self.client.get(f"/api/documents/{root.id}/download/?version=9999")
+        self.assertEqual(resp.status_code, status.HTTP_404_NOT_FOUND)
+
+        other_root = self._create_pdf(title="other", checksum="other")
+        other_version = self._create_pdf(
+            title="other-v1",
+            checksum="other-v1",
+            root_document=other_root,
+        )
+        resp = self.client.get(
+            f"/api/documents/{root.id}/download/?version={other_version.id}",
+        )
+        self.assertEqual(resp.status_code, status.HTTP_404_NOT_FOUND)
+
+    def test_download_preview_thumb_with_version_param(self) -> None:
+        root = self._create_pdf(title="root", checksum="root")
+        version = self._create_pdf(
+            title="v1",
+            checksum="v1",
+            root_document=root,
+        )
+        self._write_file(version.source_path, b"version")
+        self._write_file(version.thumbnail_path, b"thumb")
+
+        resp = self.client.get(
+            f"/api/documents/{root.id}/download/?version={version.id}",
+        )
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        self.assertEqual(resp.content, b"version")
+
+        resp = self.client.get(
+            f"/api/documents/{root.id}/preview/?version={version.id}",
+        )
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        self.assertEqual(resp.content, b"version")
+
+        resp = self.client.get(
+            f"/api/documents/{root.id}/thumb/?version={version.id}",
+        )
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        self.assertEqual(resp.content, b"thumb")
+
+    def test_metadata_version_param_uses_version(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+        )
+        version = Document.objects.create(
+            title="v1",
+            checksum="v1",
+            mime_type="application/pdf",
+            root_document=root,
+        )
+
+        with mock.patch("documents.views.DocumentViewSet.get_metadata") as metadata:
+            metadata.return_value = []
+            resp = self.client.get(
+                f"/api/documents/{root.id}/metadata/?version={version.id}",
+            )
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        self.assertTrue(metadata.called)
+
+    def test_metadata_version_param_errors(self) -> None:
+        root = self._create_pdf(title="root", checksum="root")
+
+        resp = self.client.get(
+            f"/api/documents/{root.id}/metadata/?version=not-a-number",
+        )
+        self.assertEqual(resp.status_code, status.HTTP_404_NOT_FOUND)
+
+        resp = self.client.get(f"/api/documents/{root.id}/metadata/?version=9999")
+        self.assertEqual(resp.status_code, status.HTTP_404_NOT_FOUND)
+
+        other_root = self._create_pdf(title="other", checksum="other")
+        other_version = self._create_pdf(
+            title="other-v1",
+            checksum="other-v1",
+            root_document=other_root,
+        )
+        resp = self.client.get(
+            f"/api/documents/{root.id}/metadata/?version={other_version.id}",
+        )
+        self.assertEqual(resp.status_code, status.HTTP_404_NOT_FOUND)
+
+    def test_metadata_returns_403_when_user_lacks_permission(self) -> None:
+        owner = User.objects.create_user(username="owner")
+        other = User.objects.create_user(username="other")
+        other.user_permissions.add(
+            Permission.objects.get(codename="view_document"),
+        )
+        doc = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+            owner=owner,
+        )
+        self.client.force_authenticate(user=other)
+
+        resp = self.client.get(f"/api/documents/{doc.id}/metadata/")
+
+        self.assertEqual(resp.status_code, status.HTTP_403_FORBIDDEN)
+
+    def test_update_version_enqueues_consume_with_overrides(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+        )
+        upload = self._make_pdf_upload()
+
+        async_task = mock.Mock()
+        async_task.id = "task-123"
+
+        with mock.patch("documents.views.consume_file") as consume_mock:
+            consume_mock.delay.return_value = async_task
+            resp = self.client.post(
+                f"/api/documents/{root.id}/update_version/",
+                {"document": upload, "version_label": "  New Version  "},
+                format="multipart",
+            )
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        self.assertEqual(resp.data, "task-123")
+        consume_mock.delay.assert_called_once()
+        input_doc, overrides = consume_mock.delay.call_args[0]
+        self.assertEqual(input_doc.root_document_id, root.id)
+        self.assertEqual(input_doc.source, DocumentSource.ApiUpload)
+        self.assertEqual(overrides.version_label, "New Version")
+        self.assertEqual(overrides.actor_id, self.user.id)
+
+    def test_update_version_with_version_pk_normalizes_to_root(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+        )
+        version = Document.objects.create(
+            title="v1",
+            checksum="v1",
+            mime_type="application/pdf",
+            root_document=root,
+        )
+        upload = self._make_pdf_upload()
+
+        async_task = mock.Mock()
+        async_task.id = "task-123"
+
+        with mock.patch("documents.views.consume_file") as consume_mock:
+            consume_mock.delay.return_value = async_task
+            resp = self.client.post(
+                f"/api/documents/{version.id}/update_version/",
+                {"document": upload, "version_label": "  New Version  "},
+                format="multipart",
+            )
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        self.assertEqual(resp.data, "task-123")
+        consume_mock.delay.assert_called_once()
+        input_doc, overrides = consume_mock.delay.call_args[0]
+        self.assertEqual(input_doc.root_document_id, root.id)
+        self.assertEqual(overrides.version_label, "New Version")
+        self.assertEqual(overrides.actor_id, self.user.id)
+
+    def test_update_version_returns_500_on_consume_failure(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+        )
+        upload = self._make_pdf_upload()
+
+        with mock.patch("documents.views.consume_file") as consume_mock:
+            consume_mock.delay.side_effect = Exception("boom")
+            resp = self.client.post(
+                f"/api/documents/{root.id}/update_version/",
+                {"document": upload},
+                format="multipart",
+            )
+
+        self.assertEqual(resp.status_code, status.HTTP_500_INTERNAL_SERVER_ERROR)
+
+    def test_update_version_returns_403_without_permission(self) -> None:
+        owner = User.objects.create_user(username="owner")
+        other = User.objects.create_user(username="other")
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+            owner=owner,
+        )
+        self.client.force_authenticate(user=other)
+
+        resp = self.client.post(
+            f"/api/documents/{root.id}/update_version/",
+            {"document": self._make_pdf_upload()},
+            format="multipart",
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_403_FORBIDDEN)
+
+    def test_update_version_returns_404_for_missing_document(self) -> None:
+        resp = self.client.post(
+            "/api/documents/9999/update_version/",
+            {"document": self._make_pdf_upload()},
+            format="multipart",
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_404_NOT_FOUND)
+
+    def test_update_version_requires_document(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+        )
+
+        resp = self.client.post(
+            f"/api/documents/{root.id}/update_version/",
+            {"version_label": "label"},
+            format="multipart",
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_400_BAD_REQUEST)
+
+    def test_patch_content_updates_latest_version_content(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+            content="root-content",
+        )
+        v1 = Document.objects.create(
+            title="v1",
+            checksum="v1",
+            mime_type="application/pdf",
+            root_document=root,
+            content="v1-content",
+        )
+        v2 = Document.objects.create(
+            title="v2",
+            checksum="v2",
+            mime_type="application/pdf",
+            root_document=root,
+            content="v2-content",
+        )
+
+        resp = self.client.patch(
+            f"/api/documents/{root.id}/",
+            {"content": "edited-content"},
+            format="json",
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        self.assertEqual(resp.data["content"], "edited-content")
+        root.refresh_from_db()
+        v1.refresh_from_db()
+        v2.refresh_from_db()
+        self.assertEqual(v2.content, "edited-content")
+        self.assertEqual(root.content, "root-content")
+        self.assertEqual(v1.content, "v1-content")
+
+    def test_patch_content_updates_selected_version_content(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+            content="root-content",
+        )
+        v1 = Document.objects.create(
+            title="v1",
+            checksum="v1",
+            mime_type="application/pdf",
+            root_document=root,
+            content="v1-content",
+        )
+        v2 = Document.objects.create(
+            title="v2",
+            checksum="v2",
+            mime_type="application/pdf",
+            root_document=root,
+            content="v2-content",
+        )
+
+        resp = self.client.patch(
+            f"/api/documents/{root.id}/?version={v1.id}",
+            {"content": "edited-v1"},
+            format="json",
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        self.assertEqual(resp.data["content"], "edited-v1")
+        root.refresh_from_db()
+        v1.refresh_from_db()
+        v2.refresh_from_db()
+        self.assertEqual(v1.content, "edited-v1")
+        self.assertEqual(v2.content, "v2-content")
+        self.assertEqual(root.content, "root-content")
+
+    def test_retrieve_returns_latest_version_content(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+            content="root-content",
+        )
+        Document.objects.create(
+            title="v1",
+            checksum="v1",
+            mime_type="application/pdf",
+            root_document=root,
+            content="v1-content",
+        )
+
+        resp = self.client.get(f"/api/documents/{root.id}/")
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        self.assertEqual(resp.data["content"], "v1-content")
+
+    def test_retrieve_with_version_param_returns_selected_version_content(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+            content="root-content",
+        )
+        v1 = Document.objects.create(
+            title="v1",
+            checksum="v1",
+            mime_type="application/pdf",
+            root_document=root,
+            content="v1-content",
+        )
+
+        resp = self.client.get(f"/api/documents/{root.id}/?version={v1.id}")
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        self.assertEqual(resp.data["content"], "v1-content")
+
+
+class TestVersionAwareFilters(TestCase):
+    def test_title_content_filter_falls_back_to_content(self) -> None:
+        queryset = mock.Mock()
+        fallback_queryset = mock.Mock()
+        queryset.filter.side_effect = [FieldError("missing field"), fallback_queryset]
+
+        result = TitleContentFilter().filter(queryset, " latest ")
+
+        self.assertIs(result, fallback_queryset)
+        self.assertEqual(queryset.filter.call_count, 2)
+
+    def test_effective_content_filter_falls_back_to_content_lookup(self) -> None:
+        queryset = mock.Mock()
+        fallback_queryset = mock.Mock()
+        queryset.filter.side_effect = [FieldError("missing field"), fallback_queryset]
+
+        result = EffectiveContentFilter(lookup_expr="icontains").filter(
+            queryset,
+            " latest ",
+        )
+
+        self.assertIs(result, fallback_queryset)
+        first_kwargs = queryset.filter.call_args_list[0].kwargs
+        second_kwargs = queryset.filter.call_args_list[1].kwargs
+        self.assertEqual(first_kwargs, {"effective_content__icontains": "latest"})
+        self.assertEqual(second_kwargs, {"content__icontains": "latest"})
+
+    def test_effective_content_filter_returns_input_for_empty_values(self) -> None:
+        queryset = mock.Mock()
+
+        result = EffectiveContentFilter(lookup_expr="icontains").filter(queryset, "   ")
+
+        self.assertIs(result, queryset)
+        queryset.filter.assert_not_called()

src/documents/tests/test_api_documents.py

@@ -554,6 +554,36 @@ class TestDocumentApi(DirectoriesMixin, DocumentConsumeDelayMixin, APITestCase):
         self.assertIsNone(response.data[1]["actor"])
         self.assertEqual(response.data[1]["action"], "create")
 
+    def test_document_history_logs_version_deletion(self) -> None:
+        root_doc = Document.objects.create(
+            title="Root",
+            checksum="123",
+            mime_type="application/pdf",
+            owner=self.user,
+        )
+        version_doc = Document.objects.create(
+            title="Version",
+            checksum="456",
+            mime_type="application/pdf",
+            root_document=root_doc,
+            owner=self.user,
+        )
+
+        response = self.client.delete(
+            f"/api/documents/{root_doc.pk}/versions/{version_doc.pk}/",
+        )
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+
+        response = self.client.get(f"/api/documents/{root_doc.pk}/history/")
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertEqual(len(response.data), 2)
+        self.assertEqual(response.data[0]["actor"]["id"], self.user.id)
+        self.assertEqual(response.data[0]["action"], "update")
+        self.assertEqual(
+            response.data[0]["changes"],
+            {"Version Deleted": ["None", version_doc.pk]},
+        )
+
     @override_settings(AUDIT_LOG_ENABLED=False)
     def test_document_history_action_disabled(self) -> None:
         """
@@ -1212,6 +1242,38 @@ class TestDocumentApi(DirectoriesMixin, DocumentConsumeDelayMixin, APITestCase):
         self.assertIsNone(overrides.document_type_id)
         self.assertIsNone(overrides.tag_ids)
 
+    def test_document_filters_use_latest_version_content(self) -> None:
+        root = Document.objects.create(
+            title="versioned root",
+            checksum="root",
+            mime_type="application/pdf",
+            content="root-content",
+        )
+        version = Document.objects.create(
+            title="versioned root",
+            checksum="v1",
+            mime_type="application/pdf",
+            root_document=root,
+            content="latest-version-content",
+        )
+
+        response = self.client.get(
+            "/api/documents/?content__icontains=latest-version-content",
+        )
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        results = response.data["results"]
+        self.assertEqual(len(results), 1)
+        self.assertEqual(results[0]["id"], root.id)
+        self.assertEqual(results[0]["content"], version.content)
+
+        response = self.client.get(
+            "/api/documents/?title_content=latest-version-content",
+        )
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        results = response.data["results"]
+        self.assertEqual(len(results), 1)
+        self.assertEqual(results[0]["id"], root.id)
+
     def test_create_wrong_endpoint(self) -> None:
         response = self.client.post(
             "/api/documents/",

src/documents/tests/test_bulk_edit.py

@@ -1,4 +1,3 @@
-import hashlib
 import shutil
 from datetime import date
 from pathlib import Path
@@ -382,6 +381,55 @@ class TestBulkEdit(DirectoriesMixin, TestCase):
             [self.doc3.id, self.doc4.id, self.doc5.id],
         )
 
+    def test_delete_root_document_deletes_all_versions(self) -> None:
+        version = Document.objects.create(
+            checksum="A-v1",
+            title="A version",
+            root_document=self.doc1,
+        )
+
+        bulk_edit.delete([self.doc1.id])
+
+        self.assertFalse(Document.objects.filter(id=self.doc1.id).exists())
+        self.assertFalse(Document.objects.filter(id=version.id).exists())
+
+    def test_delete_version_document_keeps_root(self) -> None:
+        version = Document.objects.create(
+            checksum="A-v1",
+            title="A version",
+            root_document=self.doc1,
+        )
+
+        bulk_edit.delete([version.id])
+
+        self.assertTrue(Document.objects.filter(id=self.doc1.id).exists())
+        self.assertFalse(Document.objects.filter(id=version.id).exists())
+
+    def test_get_root_and_current_doc_mapping(self) -> None:
+        version1 = Document.objects.create(
+            checksum="B-v1",
+            title="B version 1",
+            root_document=self.doc2,
+        )
+        version2 = Document.objects.create(
+            checksum="B-v2",
+            title="B version 2",
+            root_document=self.doc2,
+        )
+
+        root_ids_by_doc_id = bulk_edit._get_root_ids_by_doc_id(
+            [self.doc2.id, version1.id, version2.id],
+        )
+        self.assertEqual(root_ids_by_doc_id[self.doc2.id], self.doc2.id)
+        self.assertEqual(root_ids_by_doc_id[version1.id], self.doc2.id)
+        self.assertEqual(root_ids_by_doc_id[version2.id], self.doc2.id)
+
+        root_docs, current_docs = bulk_edit._get_root_and_current_docs_by_root_id(
+            {self.doc2.id},
+        )
+        self.assertEqual(root_docs[self.doc2.id].id, self.doc2.id)
+        self.assertEqual(current_docs[self.doc2.id].id, version2.id)
+
     @mock.patch("documents.tasks.bulk_update_documents.delay")
     def test_set_permissions(self, m) -> None:
         doc_ids = [self.doc1.id, self.doc2.id, self.doc3.id]
@@ -922,15 +970,8 @@ class TestPDFActions(DirectoriesMixin, TestCase):
 
         mock_consume_file.assert_not_called()
 
-    @mock.patch("documents.tasks.bulk_update_documents.si")
-    @mock.patch("documents.tasks.update_document_content_maybe_archive_file.s")
-    @mock.patch("celery.chord.delay")
-    def test_rotate(
-        self,
-        mock_chord,
-        mock_update_document,
-        mock_update_documents,
-    ) -> None:
+    @mock.patch("documents.tasks.consume_file.delay")
+    def test_rotate(self, mock_consume_delay):
         """
         GIVEN:
             - Existing documents
@@ -941,19 +982,22 @@ class TestPDFActions(DirectoriesMixin, TestCase):
         """
         doc_ids = [self.doc1.id, self.doc2.id]
         result = bulk_edit.rotate(doc_ids, 90)
-        self.assertEqual(mock_update_document.call_count, 2)
-        mock_update_documents.assert_called_once()
-        mock_chord.assert_called_once()
+        self.assertEqual(mock_consume_delay.call_count, 2)
+        for call, expected_id in zip(
+            mock_consume_delay.call_args_list,
+            doc_ids,
+        ):
+            consumable, overrides = call.args
+            self.assertEqual(consumable.root_document_id, expected_id)
+            self.assertIsNotNone(overrides)
         self.assertEqual(result, "OK")
 
-    @mock.patch("documents.tasks.bulk_update_documents.si")
-    @mock.patch("documents.tasks.update_document_content_maybe_archive_file.s")
+    @mock.patch("documents.tasks.consume_file.delay")
     @mock.patch("pikepdf.Pdf.save")
     def test_rotate_with_error(
         self,
         mock_pdf_save,
-        mock_update_archive_file,
-        mock_update_documents,
+        mock_consume_delay,
     ):
         """
         GIVEN:
@@ -972,16 +1016,12 @@ class TestPDFActions(DirectoriesMixin, TestCase):
             error_str = cm.output[0]
             expected_str = "Error rotating document"
             self.assertIn(expected_str, error_str)
-            mock_update_archive_file.assert_not_called()
+            mock_consume_delay.assert_not_called()
 
-    @mock.patch("documents.tasks.bulk_update_documents.si")
-    @mock.patch("documents.tasks.update_document_content_maybe_archive_file.s")
-    @mock.patch("celery.chord.delay")
+    @mock.patch("documents.tasks.consume_file.delay")
     def test_rotate_non_pdf(
         self,
-        mock_chord,
-        mock_update_document,
-        mock_update_documents,
+        mock_consume_delay,
     ):
         """
         GIVEN:
@@ -993,17 +1033,18 @@ class TestPDFActions(DirectoriesMixin, TestCase):
         """
         with self.assertLogs("paperless.bulk_edit", level="INFO") as cm:
             result = bulk_edit.rotate([self.doc2.id, self.img_doc.id], 90)
-            output_str = cm.output[1]
-            expected_str = "Document 4 is not a PDF, skipping rotation"
-            self.assertIn(expected_str, output_str)
-            self.assertEqual(mock_update_document.call_count, 1)
-            mock_update_documents.assert_called_once()
-            mock_chord.assert_called_once()
+            expected_str = f"Document {self.img_doc.id} is not a PDF, skipping rotation"
+            self.assertTrue(any(expected_str in line for line in cm.output))
+            self.assertEqual(mock_consume_delay.call_count, 1)
+            consumable, overrides = mock_consume_delay.call_args[0]
+            self.assertEqual(consumable.root_document_id, self.doc2.id)
+            self.assertIsNotNone(overrides)
             self.assertEqual(result, "OK")
 
-    @mock.patch("documents.tasks.update_document_content_maybe_archive_file.delay")
+    @mock.patch("documents.tasks.consume_file.delay")
     @mock.patch("pikepdf.Pdf.save")
-    def test_delete_pages(self, mock_pdf_save, mock_update_archive_file) -> None:
+    @mock.patch("documents.data_models.magic.from_file", return_value="application/pdf")
+    def test_delete_pages(self, mock_magic, mock_pdf_save, mock_consume_delay):
         """
         GIVEN:
             - Existing documents
@@ -1011,28 +1052,22 @@ class TestPDFActions(DirectoriesMixin, TestCase):
             - Delete pages action is called with 1 document and 2 pages
         THEN:
             - Save should be called once
-            - Archive file should be updated once
-            - The document's page_count should be reduced by the number of deleted pages
+            - A new version should be enqueued via consume_file
         """
         doc_ids = [self.doc2.id]
-        initial_page_count = self.doc2.page_count
         pages = [1, 3]
         result = bulk_edit.delete_pages(doc_ids, pages)
         mock_pdf_save.assert_called_once()
-        mock_update_archive_file.assert_called_once()
+        mock_consume_delay.assert_called_once()
+        consumable, overrides = mock_consume_delay.call_args[0]
+        self.assertEqual(consumable.root_document_id, self.doc2.id)
+        self.assertTrue(str(consumable.original_file).endswith("_pages_deleted.pdf"))
+        self.assertIsNotNone(overrides)
         self.assertEqual(result, "OK")
 
-        expected_page_count = initial_page_count - len(pages)
-        self.doc2.refresh_from_db()
-        self.assertEqual(self.doc2.page_count, expected_page_count)
-
-    @mock.patch("documents.tasks.update_document_content_maybe_archive_file.delay")
+    @mock.patch("documents.tasks.consume_file.delay")
     @mock.patch("pikepdf.Pdf.save")
-    def test_delete_pages_with_error(
-        self,
-        mock_pdf_save,
-        mock_update_archive_file,
-    ) -> None:
+    def test_delete_pages_with_error(self, mock_pdf_save, mock_consume_delay):
         """
         GIVEN:
             - Existing documents
@@ -1041,7 +1076,7 @@ class TestPDFActions(DirectoriesMixin, TestCase):
             - PikePDF raises an error
         THEN:
             - Save should be called once
-            - Archive file should not be updated
+            - No new version should be enqueued
         """
         mock_pdf_save.side_effect = Exception("Error saving PDF")
         doc_ids = [self.doc2.id]
@@ -1052,7 +1087,7 @@ class TestPDFActions(DirectoriesMixin, TestCase):
             error_str = cm.output[0]
             expected_str = "Error deleting pages from document"
             self.assertIn(expected_str, error_str)
-            mock_update_archive_file.assert_not_called()
+            mock_consume_delay.assert_not_called()
 
     @mock.patch("documents.bulk_edit.group")
     @mock.patch("documents.tasks.consume_file.s")
@@ -1151,24 +1186,18 @@ class TestPDFActions(DirectoriesMixin, TestCase):
         self.doc2.refresh_from_db()
         self.assertEqual(self.doc2.archive_serial_number, 333)
 
-    @mock.patch("documents.tasks.update_document_content_maybe_archive_file.delay")
-    def test_edit_pdf_with_update_document(
-        self,
-        mock_update_document: mock.Mock,
-    ) -> None:
+    @mock.patch("documents.tasks.consume_file.delay")
+    def test_edit_pdf_with_update_document(self, mock_consume_delay):
         """
         GIVEN:
             - A single existing PDF document
         WHEN:
             - edit_pdf is called with update_document=True and a single output
         THEN:
-            - The original document is updated in-place
-            - The update_document_content_maybe_archive_file task is triggered
+            - A version update is enqueued targeting the existing document
         """
         doc_ids = [self.doc2.id]
         operations = [{"page": 1}, {"page": 2}]
-        original_checksum = self.doc2.checksum
-        original_page_count = self.doc2.page_count
 
         result = bulk_edit.edit_pdf(
             doc_ids,
@@ -1178,10 +1207,11 @@ class TestPDFActions(DirectoriesMixin, TestCase):
         )
 
         self.assertEqual(result, "OK")
-        self.doc2.refresh_from_db()
-        self.assertNotEqual(self.doc2.checksum, original_checksum)
-        self.assertNotEqual(self.doc2.page_count, original_page_count)
-        mock_update_document.assert_called_once_with(document_id=self.doc2.id)
+        mock_consume_delay.assert_called_once()
+        consumable, overrides = mock_consume_delay.call_args[0]
+        self.assertEqual(consumable.root_document_id, self.doc2.id)
+        self.assertTrue(str(consumable.original_file).endswith("_edited.pdf"))
+        self.assertIsNotNone(overrides)
 
     @mock.patch("documents.bulk_edit.group")
     @mock.patch("documents.tasks.consume_file.s")
@@ -1258,10 +1288,20 @@ class TestPDFActions(DirectoriesMixin, TestCase):
         mock_consume_file.assert_not_called()
 
     @mock.patch("documents.bulk_edit.update_document_content_maybe_archive_file.delay")
+    @mock.patch("documents.tasks.consume_file.delay")
+    @mock.patch("documents.bulk_edit.tempfile.mkdtemp")
     @mock.patch("pikepdf.open")
-    def test_remove_password_update_document(self, mock_open, mock_update_document):
+    def test_remove_password_update_document(
+        self,
+        mock_open,
+        mock_mkdtemp,
+        mock_consume_delay,
+        mock_update_document,
+    ):
         doc = self.doc1
-        original_checksum = doc.checksum
+        temp_dir = self.dirs.scratch_dir / "remove-password-update"
+        temp_dir.mkdir(parents=True, exist_ok=True)
+        mock_mkdtemp.return_value = str(temp_dir)
 
         fake_pdf = mock.MagicMock()
         fake_pdf.pages = [mock.Mock(), mock.Mock(), mock.Mock()]
@@ -1281,12 +1321,17 @@ class TestPDFActions(DirectoriesMixin, TestCase):
         self.assertEqual(result, "OK")
         mock_open.assert_called_once_with(doc.source_path, password="secret")
         fake_pdf.remove_unreferenced_resources.assert_called_once()
-        doc.refresh_from_db()
-        self.assertNotEqual(doc.checksum, original_checksum)
-        expected_checksum = hashlib.md5(doc.source_path.read_bytes()).hexdigest()
-        self.assertEqual(doc.checksum, expected_checksum)
-        self.assertEqual(doc.page_count, len(fake_pdf.pages))
-        mock_update_document.assert_called_once_with(document_id=doc.id)
+        mock_update_document.assert_not_called()
+        mock_consume_delay.assert_called_once()
+        consumable, overrides = mock_consume_delay.call_args[0]
+        expected_path = temp_dir / f"{doc.id}_unprotected.pdf"
+        self.assertTrue(expected_path.exists())
+        self.assertEqual(
+            Path(consumable.original_file).resolve(),
+            expected_path.resolve(),
+        )
+        self.assertEqual(consumable.root_document_id, doc.id)
+        self.assertIsNotNone(overrides)
 
     @mock.patch("documents.bulk_edit.chord")
     @mock.patch("documents.bulk_edit.group")
@@ -1295,12 +1340,12 @@ class TestPDFActions(DirectoriesMixin, TestCase):
     @mock.patch("pikepdf.open")
     def test_remove_password_creates_consumable_document(
         self,
-        mock_open,
-        mock_mkdtemp,
-        mock_consume_file,
-        mock_group,
-        mock_chord,
-    ):
+        mock_open: mock.Mock,
+        mock_mkdtemp: mock.Mock,
+        mock_consume_file: mock.Mock,
+        mock_group: mock.Mock,
+        mock_chord: mock.Mock,
+    ) -> None:
         doc = self.doc2
         temp_dir = self.dirs.scratch_dir / "remove-password"
         temp_dir.mkdir(parents=True, exist_ok=True)
@@ -1309,8 +1354,8 @@ class TestPDFActions(DirectoriesMixin, TestCase):
         fake_pdf = mock.MagicMock()
         fake_pdf.pages = [mock.Mock(), mock.Mock()]
 
-        def save_side_effect(target_path):
-            Path(target_path).write_bytes(b"password removed")
+        def save_side_effect(target_path: Path) -> None:
+            target_path.write_bytes(b"password removed")
 
         fake_pdf.save.side_effect = save_side_effect
         mock_open.return_value.__enter__.return_value = fake_pdf
@@ -1352,13 +1397,13 @@ class TestPDFActions(DirectoriesMixin, TestCase):
     @mock.patch("pikepdf.open")
     def test_remove_password_deletes_original(
         self,
-        mock_open,
-        mock_mkdtemp,
-        mock_consume_file,
-        mock_group,
-        mock_chord,
-        mock_delete,
-    ):
+        mock_open: mock.Mock,
+        mock_mkdtemp: mock.Mock,
+        mock_consume_file: mock.Mock,
+        mock_group: mock.Mock,
+        mock_chord: mock.Mock,
+        mock_delete: mock.Mock,
+    ) -> None:
         doc = self.doc2
         temp_dir = self.dirs.scratch_dir / "remove-password-delete"
         temp_dir.mkdir(parents=True, exist_ok=True)
@@ -1367,8 +1412,8 @@ class TestPDFActions(DirectoriesMixin, TestCase):
         fake_pdf = mock.MagicMock()
         fake_pdf.pages = [mock.Mock(), mock.Mock()]
 
-        def save_side_effect(target_path):
-            Path(target_path).write_bytes(b"password removed")
+        def save_side_effect(target_path: Path) -> None:
+            target_path.write_bytes(b"password removed")
 
         fake_pdf.save.side_effect = save_side_effect
         mock_open.return_value.__enter__.return_value = fake_pdf
@@ -1391,7 +1436,7 @@ class TestPDFActions(DirectoriesMixin, TestCase):
         mock_delete.si.assert_called_once_with([doc.id])
 
     @mock.patch("pikepdf.open")
-    def test_remove_password_open_failure(self, mock_open):
+    def test_remove_password_open_failure(self, mock_open: mock.Mock) -> None:
         mock_open.side_effect = RuntimeError("wrong password")
 
         with self.assertLogs("paperless.bulk_edit", level="ERROR") as cm:

src/documents/tests/test_consumer.py

@@ -16,6 +16,9 @@ from guardian.core import ObjectPermissionChecker
 
 from documents.barcodes import BarcodePlugin
 from documents.consumer import ConsumerError
+from documents.consumer import ConsumerPlugin
+from documents.consumer import ConsumerPreflightPlugin
+from documents.data_models import ConsumableDocument
 from documents.data_models import DocumentMetadataOverrides
 from documents.data_models import DocumentSource
 from documents.models import Correspondent
@@ -29,6 +32,7 @@ from documents.parsers import ParseError
 from documents.plugins.helpers import ProgressStatusOptions
 from documents.tasks import sanity_check
 from documents.tests.utils import DirectoriesMixin
+from documents.tests.utils import DummyProgressManager
 from documents.tests.utils import FileSystemAssertsMixin
 from documents.tests.utils import GetConsumerMixin
 from paperless_mail.models import MailRule
@@ -94,11 +98,13 @@ class FaultyGenericExceptionParser(_BaseTestParser):
         raise Exception("Generic exception.")
 
 
-def fake_magic_from_file(file, *, mime=False):
+def fake_magic_from_file(file, *, mime=False):  # NOSONAR
     if mime:
         filepath = Path(file)
         if filepath.name.startswith("invalid_pdf"):
             return "application/octet-stream"
+        if filepath.name.startswith("valid_pdf"):
+            return "application/pdf"
         if filepath.suffix == ".pdf":
             return "application/pdf"
         elif filepath.suffix == ".png":
@@ -664,6 +670,144 @@ class TestConsumer(
 
         self._assert_first_last_send_progress()
 
+    @mock.patch("documents.consumer.load_classifier")
+    def test_version_label_override_applies(self, m) -> None:
+        m.return_value = MagicMock()
+
+        with self.get_consumer(
+            self.get_test_file(),
+            DocumentMetadataOverrides(version_label="v1"),
+        ) as consumer:
+            consumer.run()
+
+        document = Document.objects.first()
+        assert document is not None
+
+        self.assertEqual(document.version_label, "v1")
+
+        self._assert_first_last_send_progress()
+
+    @override_settings(AUDIT_LOG_ENABLED=True)
+    @mock.patch("documents.consumer.load_classifier")
+    def test_consume_version_creates_new_version(self, m) -> None:
+        m.return_value = MagicMock()
+
+        with self.get_consumer(self.get_test_file()) as consumer:
+            consumer.run()
+
+        root_doc = Document.objects.first()
+        self.assertIsNotNone(root_doc)
+        assert root_doc is not None
+
+        actor = User.objects.create_user(
+            username="actor",
+            email="actor@example.com",
+            password="password",
+        )
+
+        version_file = self.get_test_file2()
+        status = DummyProgressManager(version_file.name, None)
+        overrides = DocumentMetadataOverrides(
+            version_label="v2",
+            actor_id=actor.pk,
+        )
+        doc = ConsumableDocument(
+            DocumentSource.ApiUpload,
+            original_file=version_file,
+            root_document_id=root_doc.pk,
+        )
+        preflight = ConsumerPreflightPlugin(
+            doc,
+            overrides,
+            status,  # type: ignore[arg-type]
+            self.dirs.scratch_dir,
+            "task-id",
+        )
+        preflight.setup()
+        preflight.run()
+
+        consumer = ConsumerPlugin(
+            doc,
+            overrides,
+            status,  # type: ignore[arg-type]
+            self.dirs.scratch_dir,
+            "task-id",
+        )
+        consumer.setup()
+        try:
+            self.assertTrue(consumer.filename.endswith("_v0.pdf"))
+            consumer.run()
+        finally:
+            consumer.cleanup()
+
+        versions = Document.objects.filter(root_document=root_doc)
+        self.assertEqual(versions.count(), 1)
+        version = versions.first()
+        assert version is not None
+        assert version.original_filename is not None
+        self.assertEqual(version.version_label, "v2")
+        self.assertTrue(version.original_filename.endswith("_v0.pdf"))
+        self.assertTrue(bool(version.content))
+
+    @override_settings(AUDIT_LOG_ENABLED=True)
+    @mock.patch("documents.consumer.load_classifier")
+    def test_consume_version_with_missing_actor_and_filename_without_suffix(
+        self,
+        m: mock.Mock,
+    ) -> None:
+        m.return_value = MagicMock()
+
+        with self.get_consumer(self.get_test_file()) as consumer:
+            consumer.run()
+
+        root_doc = Document.objects.first()
+        self.assertIsNotNone(root_doc)
+        assert root_doc is not None
+
+        version_file = self.get_test_file2()
+        status = DummyProgressManager(version_file.name, None)
+        overrides = DocumentMetadataOverrides(
+            filename="valid_pdf_version-upload",
+            actor_id=999999,
+        )
+        doc = ConsumableDocument(
+            DocumentSource.ApiUpload,
+            original_file=version_file,
+            root_document_id=root_doc.pk,
+        )
+
+        preflight = ConsumerPreflightPlugin(
+            doc,
+            overrides,
+            status,  # type: ignore[arg-type]
+            self.dirs.scratch_dir,
+            "task-id",
+        )
+        preflight.setup()
+        preflight.run()
+
+        consumer = ConsumerPlugin(
+            doc,
+            overrides,
+            status,  # type: ignore[arg-type]
+            self.dirs.scratch_dir,
+            "task-id",
+        )
+        consumer.setup()
+        try:
+            self.assertEqual(consumer.filename, "valid_pdf_version-upload_v0")
+            consumer.run()
+        finally:
+            consumer.cleanup()
+
+        version = (
+            Document.objects.filter(root_document=root_doc).order_by("-id").first()
+        )
+        self.assertIsNotNone(version)
+        assert version is not None
+        self.assertEqual(version.original_filename, "valid_pdf_version-upload_v0")
+        self.assertTrue(bool(version.content))
+
     @mock.patch("documents.consumer.load_classifier")
     def testClassifyDocument(self, m) -> None:
         correspondent = Correspondent.objects.create(
@@ -1179,7 +1323,7 @@ class PostConsumeTestCase(DirectoriesMixin, GetConsumerMixin, TestCase):
                 consumer.run_post_consume_script(doc)
 
     @mock.patch("documents.consumer.run_subprocess")
-    def test_post_consume_script_simple(self, m) -> None:
+    def test_post_consume_script_simple(self, m: mock.MagicMock) -> None:
         with tempfile.NamedTemporaryFile() as script:
             with override_settings(POST_CONSUME_SCRIPT=script.name):
                 doc = Document.objects.create(title="Test", mime_type="application/pdf")
@@ -1190,7 +1334,10 @@ class PostConsumeTestCase(DirectoriesMixin, GetConsumerMixin, TestCase):
                 m.assert_called_once()
 
     @mock.patch("documents.consumer.run_subprocess")
-    def test_post_consume_script_with_correspondent_and_type(self, m) -> None:
+    def test_post_consume_script_with_correspondent_and_type(
+        self,
+        m: mock.MagicMock,
+    ) -> None:
         with tempfile.NamedTemporaryFile() as script:
             with override_settings(POST_CONSUME_SCRIPT=script.name):
                 c = Correspondent.objects.create(name="my_bank")
@@ -1273,6 +1420,19 @@ class TestMetadataOverrides(TestCase):
         base.update(incoming)
         self.assertTrue(base.skip_asn_if_exists)
 
+    def test_update_actor_and_version_label(self) -> None:
+        base = DocumentMetadataOverrides(
+            actor_id=1,
+            version_label="root",
+        )
+        incoming = DocumentMetadataOverrides(
+            actor_id=2,
+            version_label="v2",
+        )
+        base.update(incoming)
+        self.assertEqual(base.actor_id, 2)
+        self.assertEqual(base.version_label, "v2")
+
 
 class TestBarcodeApplyDetectedASN(TestCase):
     """

src/documents/tests/test_document_model.py

@@ -78,6 +78,28 @@ class TestDocument(TestCase):
             empty_trash([document.pk])
             self.assertEqual(mock_unlink.call_count, 2)
 
+    def test_delete_root_deletes_versions(self) -> None:
+        root = Document.objects.create(
+            correspondent=Correspondent.objects.create(name="Test0"),
+            title="Head",
+            content="content",
+            checksum="checksum",
+            mime_type="application/pdf",
+        )
+        Document.objects.create(
+            root_document=root,
+            correspondent=root.correspondent,
+            title="Version",
+            content="content",
+            checksum="checksum2",
+            mime_type="application/pdf",
+        )
+
+        root.delete()
+
+        self.assertEqual(Document.objects.count(), 0)
+        self.assertEqual(Document.deleted_objects.count(), 2)
+
     def test_file_name(self) -> None:
         doc = Document(
             mime_type="application/pdf",

src/documents/tests/test_task_signals.py

@@ -7,7 +7,9 @@ from django.test import TestCase
 from documents.data_models import ConsumableDocument
 from documents.data_models import DocumentMetadataOverrides
 from documents.data_models import DocumentSource
+from documents.models import Document
 from documents.models import PaperlessTask
+from documents.signals.handlers import add_to_index
 from documents.signals.handlers import before_task_publish_handler
 from documents.signals.handlers import task_failure_handler
 from documents.signals.handlers import task_postrun_handler
@@ -198,3 +200,39 @@ class TestTaskSignalHandler(DirectoriesMixin, TestCase):
         task = PaperlessTask.objects.get()
 
         self.assertEqual(celery.states.FAILURE, task.status)
+
+    def test_add_to_index_indexes_root_once_for_root_documents(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+        )
+
+        with mock.patch("documents.index.add_or_update_document") as add:
+            add_to_index(sender=None, document=root)
+
+        add.assert_called_once_with(root)
+
+    def test_add_to_index_reindexes_root_for_version_documents(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+        )
+        version = Document.objects.create(
+            title="version",
+            checksum="version",
+            mime_type="application/pdf",
+            root_document=root,
+        )
+
+        with mock.patch("documents.index.add_or_update_document") as add:
+            add_to_index(sender=None, document=version)
+
+        self.assertEqual(add.call_count, 2)
+        self.assertEqual(add.call_args_list[0].args[0].id, version.id)
+        self.assertEqual(add.call_args_list[1].args[0].id, root.id)
+        self.assertEqual(
+            add.call_args_list[1].kwargs,
+            {"effective_content": version.content},
+        )

src/documents/tests/test_version_conditionals.py

@@ -0,0 +1,91 @@
+from types import SimpleNamespace
+from unittest import mock
+
+from django.test import TestCase
+
+from documents.conditionals import metadata_etag
+from documents.conditionals import preview_etag
+from documents.conditionals import thumbnail_last_modified
+from documents.models import Document
+from documents.tests.utils import DirectoriesMixin
+from documents.versioning import resolve_effective_document_by_pk
+
+
+class TestConditionals(DirectoriesMixin, TestCase):
+    def test_metadata_etag_uses_latest_version_for_root_request(self) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root-checksum",
+            archive_checksum="root-archive",
+            mime_type="application/pdf",
+        )
+        latest = Document.objects.create(
+            title="v1",
+            checksum="version-checksum",
+            archive_checksum="version-archive",
+            mime_type="application/pdf",
+            root_document=root,
+        )
+        request = SimpleNamespace(query_params={})
+
+        self.assertEqual(metadata_etag(request, root.id), latest.checksum)
+        self.assertEqual(preview_etag(request, root.id), latest.archive_checksum)
+
+    def test_resolve_effective_doc_returns_none_for_invalid_or_unrelated_version(
+        self,
+    ) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+        )
+        other_root = Document.objects.create(
+            title="other",
+            checksum="other",
+            mime_type="application/pdf",
+        )
+        other_version = Document.objects.create(
+            title="other-v1",
+            checksum="other-v1",
+            mime_type="application/pdf",
+            root_document=other_root,
+        )
+
+        invalid_request = SimpleNamespace(query_params={"version": "not-a-number"})
+        unrelated_request = SimpleNamespace(
+            query_params={"version": str(other_version.id)},
+        )
+
+        self.assertIsNone(
+            resolve_effective_document_by_pk(root.id, invalid_request).document,
+        )
+        self.assertIsNone(
+            resolve_effective_document_by_pk(root.id, unrelated_request).document,
+        )
+
+    def test_thumbnail_last_modified_uses_effective_document_for_cache_key(
+        self,
+    ) -> None:
+        root = Document.objects.create(
+            title="root",
+            checksum="root",
+            mime_type="application/pdf",
+        )
+        latest = Document.objects.create(
+            title="v2",
+            checksum="v2",
+            mime_type="application/pdf",
+            root_document=root,
+        )
+        latest.thumbnail_path.parent.mkdir(parents=True, exist_ok=True)
+        latest.thumbnail_path.write_bytes(b"thumb")
+
+        request = SimpleNamespace(query_params={})
+        with mock.patch(
+            "documents.conditionals.get_thumbnail_modified_key",
+            return_value="thumb-modified-key",
+        ) as get_thumb_key:
+            result = thumbnail_last_modified(request, root.id)
+
+        self.assertIsNotNone(result)
+        get_thumb_key.assert_called_once_with(latest.id)