Enhancment: Formatted filename for single document downloads (#12095)

---------

Co-authored-by: shamoon <4887959+shamoon@users.noreply.github.com>

src/documents/tests/test_api_documents.py

@@ -445,6 +445,40 @@ class TestDocumentApi(DirectoriesMixin, DocumentConsumeDelayMixin, APITestCase):
         self.assertEqual(response.status_code, status.HTTP_200_OK)
         self.assertEqual(response.content, content)
 
+    @override_settings(FILENAME_FORMAT="")
+    def test_download_follow_formatting(self) -> None:
+        content = b"This is a test"
+        content_archive = b"This is the same test but archived"
+
+        doc = Document.objects.create(
+            title="none",
+            filename="my_document.pdf",
+            archive_filename="archived.pdf",
+            mime_type="application/pdf",
+        )
+
+        with Path(doc.source_path).open("wb") as f:
+            f.write(content)
+
+        with Path(doc.archive_path).open("wb") as f:
+            f.write(content_archive)
+
+        # Without follow_formatting, should use public filename
+        response = self.client.get(f"/api/documents/{doc.pk}/download/")
+        self.assertIn("none.pdf", response["Content-Disposition"])
+
+        # With follow_formatting, should use actual filename on disk
+        response = self.client.get(
+            f"/api/documents/{doc.pk}/download/?follow_formatting=true",
+        )
+        self.assertIn("archived.pdf", response["Content-Disposition"])
+
+        # With follow_formatting and original, should use source filename
+        response = self.client.get(
+            f"/api/documents/{doc.pk}/download/?original=true&follow_formatting=true",
+        )
+        self.assertIn("my_document.pdf", response["Content-Disposition"])
+
     def test_document_actions_not_existing_file(self) -> None:
         doc = Document.objects.create(
             title="none",

src/documents/views.py

@@ -10,6 +10,7 @@ from collections import deque
 from datetime import datetime
 from pathlib import Path
 from time import mktime
+from typing import TYPE_CHECKING
 from typing import Any
 from typing import Literal
 from unicodedata import normalize
@@ -616,6 +617,12 @@ class EmailDocumentDetailSchema(EmailSerializer):
                 type=OpenApiTypes.BOOL,
                 location=OpenApiParameter.QUERY,
             ),
+            OpenApiParameter(
+                name="follow_formatting",
+                description="Whether or not to use the filename on disk",
+                type=OpenApiTypes.BOOL,
+                location=OpenApiParameter.QUERY,
+            ),
         ],
         responses={200: OpenApiTypes.BINARY},
     ),
@@ -1061,6 +1068,7 @@ class DocumentViewSet(
             use_archive=not self.original_requested(request)
             and file_doc.has_archive_version,
             disposition=disposition,
+            follow_formatting=request.query_params.get("follow_formatting", False),
         )
 
     def get_metadata(self, file, mime_type):
@@ -3445,14 +3453,30 @@ class SharedLinkView(View):
         return response
 
 
-def serve_file(*, doc: Document, use_archive: bool, disposition: str) -> HttpResponse:
+def serve_file(
+    *,
+    doc: Document,
+    use_archive: bool,
+    disposition: str,
+    follow_formatting: bool = False,
+) -> HttpResponse:
     if use_archive:
+        if TYPE_CHECKING:
+            assert doc.archive_filename
+
         file_handle = doc.archive_file
-        filename = doc.get_public_filename(archive=True)
+        filename = (
+            doc.archive_filename
+            if follow_formatting
+            else doc.get_public_filename(archive=True)
+        )
         mime_type = "application/pdf"
     else:
+        if TYPE_CHECKING:
+            assert doc.filename
+
         file_handle = doc.source_file
-        filename = doc.get_public_filename()
+        filename = doc.filename if follow_formatting else doc.get_public_filename()
         mime_type = doc.mime_type
         # Support browser previewing csv files by using text mime type
         if mime_type in {"application/csv", "text/csv"} and disposition == "inline":