Extract uploaded archives into local engagement storage

app/modules/services/engagement_resources.py

@@ -6,6 +6,7 @@ from typing import Any, Iterable
 
 from sqlalchemy import select
 
+from app.modules.documents.models import DocumentStorageJob
 from app.modules.documents.services import client_folder_parts, get_active_storage_node_for_branch, sanitize_segment
 from app.modules.services.models import FirmServiceTaskTemplate, ServiceTaskCategory
 
@@ -41,6 +42,25 @@ def _join_local_path(root: str, relative: str) -> str:
     return root + "/" + relative.lstrip("/")
 
 
+def _latest_local_final_path(db, version: Any) -> str:
+    """Return the branch-agent acknowledged final path for a document version.
+
+    For ordinary files this is the file path. For ZIP/TAR uploads handled by Local
+    Agent 1.22.1+ this is the extracted directory path, while the original archive
+    continues to remain the versioned source file for secure download/history.
+    """
+    version_id = int(getattr(version, "id", 0) or 0)
+    if not version_id:
+        return ""
+    job = db.execute(
+        select(DocumentStorageJob).where(
+            DocumentStorageJob.version_id == version_id,
+            DocumentStorageJob.status == "completed",
+        ).order_by(DocumentStorageJob.completed_at_utc.desc(), DocumentStorageJob.id.desc()).limit(1)
+    ).scalar_one_or_none()
+    return str(getattr(job, "local_final_path", "") or "").strip() if job else ""
+
+
 def _task_category_options(db, engagement, tasks: list[Any]) -> list[dict[str, Any]]:
     """Return the service's real task-category master mapped to this engagement's tasks.
 
@@ -203,6 +223,8 @@ def build_engagement_resource_context(db, engagement, tasks: Iterable[Any], docu
         versions = list(getattr(doc, "versions", None) or [])
         latest = versions[0] if versions else None
         latest_relative_path = str(getattr(latest, "local_relative_path", "") or "") if latest else ""
+        local_final_path = _latest_local_final_path(db, latest) if latest else ""
+        displayed_relative_path = local_final_path or latest_relative_path
         tally_year = _tally_document_year(doc)
         row = {
             "id": int(getattr(doc, "id", 0) or 0),
@@ -213,6 +235,8 @@ def build_engagement_resource_context(db, engagement, tasks: Iterable[Any], docu
             "task_instance_id": getattr(doc, "task_instance_id", None),
             "latest_filename": str(getattr(latest, "original_filename", "") or "") if latest else "",
             "latest_relative_path": latest_relative_path,
+            "local_final_path": local_final_path,
+            "displayed_relative_path": displayed_relative_path,
             "storage_status": str(getattr(latest, "storage_status", "") or "") if latest else "",
         }
         document_options.append(row)
@@ -220,7 +244,7 @@ def build_engagement_resource_context(db, engagement, tasks: Iterable[Any], docu
             tally_data_files.append({
                 **row,
                 "financial_year": tally_year,
-                "local_path": _join_local_path(storage_root_path, latest_relative_path) if latest_relative_path else "",
+                "local_path": _join_local_path(storage_root_path, displayed_relative_path) if displayed_relative_path else "",
             })
 
     tally_data_files.sort(key=lambda row: row.get("financial_year", ""), reverse=True)