feat(spp_api_v2_gis): implement QGIS plugin team recommendations for OGC Processes

Address consumer feedback from the QGIS plugin team:

- Always include geometries_failed in batch summary responses (#1)
- Always populate computed_at with current UTC timestamp, even for empty results (#2)
- Add Retry-After: 5 header to async 201 responses and in-progress job status (#3/#8)
- Track batch progress per-geometry via on_progress callback in job execution (#4)
- Add x-openspp-batch-limit: 100 extension to spatial-statistics process description (#5)

Author: jeremi

spp_api_v2_gis/models/process_job.py

@@ -82,6 +82,8 @@ def execute_process(self):
         This method is called by the job worker. It runs the appropriate
         SpatialQueryService method based on process_id, stores the results,
         and updates the job status accordingly.
+
+        For batch spatial-statistics requests, progress is updated per geometry.
         """
         self.ensure_one()
 
@@ -101,7 +103,11 @@ def execute_process(self):
             inputs = self.inputs or {}
 
             if self.process_id == "spatial-statistics":
-                results = run_spatial_statistics(service, inputs)
+                geometry = inputs.get("geometry")
+                if isinstance(geometry, list) and len(geometry) > 1:
+                    results = self._execute_batch_with_progress(service, inputs)
+                else:
+                    results = run_spatial_statistics(service, inputs)
             elif self.process_id == "proximity-statistics":
                 results = run_proximity_statistics(service, inputs)
             else:
@@ -111,6 +117,7 @@ def execute_process(self):
                 {
                     "status": "successful",
                     "finished_at": fields.Datetime.now(),
+                    "progress": 100,
                     "results": results,
                 }
             )
@@ -125,6 +132,29 @@ def execute_process(self):
                 }
             )
 
+    def _execute_batch_with_progress(self, service, inputs):
+        """Execute batch spatial-statistics with per-geometry progress updates.
+
+        Calls the service's batch method with a progress callback so that
+        the job record is updated after each geometry is processed.
+        """
+        geometry = inputs["geometry"]
+        geometries = [{"id": g["id"], "geometry": g["value"]} for g in geometry]
+        total = len(geometries)
+
+        def on_progress(completed):
+            self.write({"progress": int(completed / total * 100)})
+
+        result = service.query_statistics_batch(
+            geometries=geometries,
+            filters=inputs.get("filters"),
+            variables=inputs.get("variables"),
+            on_progress=on_progress,
+        )
+        for item in result.get("results", []):
+            item.pop("registrant_ids", None)
+        return result
+
     @api.model
     def cron_cleanup_jobs(self):
         """Clean up old and stale jobs.

spp_api_v2_gis/routers/jobs.py

@@ -17,7 +17,7 @@
 from odoo.addons.fastapi.dependencies import odoo_env
 from odoo.addons.spp_api_v2.middleware.auth import get_authenticated_client
 
-from fastapi import APIRouter, Depends, HTTPException, Path, Query, Request, status
+from fastapi import APIRouter, Depends, HTTPException, Path, Query, Request, Response, status
 
 from ..schemas.processes import JobList, StatusInfo
 from ._helpers import build_status_info, check_gis_scope, get_base_url
@@ -103,7 +103,18 @@ async def get_job_status(
 
     job = _get_job_or_404(env, job_id, api_client)
     base_url = get_base_url(request)
-    return build_status_info(job, base_url)
+    status_info = build_status_info(job, base_url)
+
+    # Add Retry-After header for in-progress jobs to guide client polling
+    if job.status in ("accepted", "running"):
+        return Response(
+            content=status_info.model_dump_json(by_alias=True, exclude_none=True),
+            status_code=200,
+            media_type="application/json",
+            headers={"Retry-After": "5"},
+        )
+
+    return status_info
 
 
 @jobs_router.get(

spp_api_v2_gis/routers/processes.py

@@ -294,5 +294,6 @@ def _execute_async(env, api_client, process_id, inputs, request):
         media_type="application/json",
         headers={
             "Location": f"{base_url}/gis/ogc/jobs/{job_id}",
+            "Retry-After": "5",
         },
     )

spp_api_v2_gis/services/process_registry.py

@@ -140,6 +140,7 @@ def _build_spatial_statistics_description(self):
             ),
             "version": "1.0.0",
             "jobControlOptions": ["sync-execute", "async-execute", "dismiss"],
+            "x-openspp-batch-limit": 100,
             "inputs": {
                 "geometry": {
                     "title": "Query Geometry",

spp_api_v2_gis/services/spatial_query_service.py

@@ -3,6 +3,7 @@
 
 import json
 import logging
+from datetime import UTC, datetime
 
 from odoo.addons.spp_aggregation.services import build_explicit_scope
 
@@ -30,7 +31,7 @@ def __init__(self, env):
         """
         self.env = env
 
-    def query_statistics_batch(self, geometries, filters=None, variables=None):
+    def query_statistics_batch(self, geometries, filters=None, variables=None, on_progress=None):
         """Execute spatial query for multiple geometries.
 
         Queries each geometry individually and computes an aggregate summary.
@@ -39,6 +40,7 @@ def query_statistics_batch(self, geometries, filters=None, variables=None):
             geometries: List of dicts with 'id' and 'geometry' keys
             filters: Additional filters for registrants (dict)
             variables: List of statistic names to compute
+            on_progress: Optional callback(completed_count) called after each geometry
 
         Returns:
             dict: Batch results with per-geometry results and summary
@@ -47,6 +49,7 @@ def query_statistics_batch(self, geometries, filters=None, variables=None):
         """
         results = []
         all_registrant_ids = set()
+        geometries_failed = 0
 
         for item in geometries:
             geometry_id = item["id"]
@@ -76,6 +79,7 @@ def query_statistics_batch(self, geometries, filters=None, variables=None):
                 )
             except Exception as e:
                 _logger.warning("Batch query failed for geometry '%s': %s", geometry_id, e)
+                geometries_failed += 1
                 results.append(
                     {
                         "id": geometry_id,
@@ -89,6 +93,9 @@ def query_statistics_batch(self, geometries, filters=None, variables=None):
                     }
                 )
 
+            if on_progress:
+                on_progress(len(results))
+
         # Compute summary by aggregating unique registrants with metadata
         summary_stats_with_metadata = {"statistics": {}}
         if all_registrant_ids:
@@ -97,6 +104,7 @@ def query_statistics_batch(self, geometries, filters=None, variables=None):
         summary = {
             "total_count": len(all_registrant_ids),
             "geometries_queried": len(geometries),
+            "geometries_failed": geometries_failed,
             "statistics": summary_stats_with_metadata.get("statistics", {}),
             "access_level": summary_stats_with_metadata.get("access_level"),
             "from_cache": summary_stats_with_metadata.get("from_cache", False),
@@ -327,7 +335,7 @@ def _compute_statistics(self, registrant_ids, variables):
                 "statistics": self._get_empty_statistics(),
                 "access_level": None,
                 "from_cache": False,
-                "computed_at": None,
+                "computed_at": datetime.now(UTC).isoformat(),
             }
 
         if "spp.aggregation.service" not in self.env:
@@ -368,7 +376,7 @@ def _compute_via_aggregation_service(self, registrant_ids, variables):
                 "statistics": {},
                 "access_level": None,
                 "from_cache": False,
-                "computed_at": None,
+                "computed_at": datetime.now(UTC).isoformat(),
             }
 
         # Call AggregationService (no sudo - let service determine access level from calling user)