feat(places): backend for the photo map (geo clusters API)

Phase 1 server side, gated on OXICLOUD_ENABLE_PLACES (off by default):

- migration: partial index on storage.file_metadata(longitude, latitude).
- FileBlobReadRepository::list_geo_clusters — plain-SQL grid aggregation
  (no PostGIS) scoped to the caller's own non-trashed photos, returning a
  centroid, count and a representative file id per non-empty cell.
- PlacesService (caller_id-scoped; user-scoped data needs no authz check,
  mirroring RecentService) with a zoom→cell-size mapping.
- GET /api/photos/geo?bbox=w,s,e,n&zoom=N returning GeoCluster[]. The route
  is mounted only when the Places service is present, and is registered in
  the OpenAPI path list.

The map frontend (PMTiles serving + MapLibre module) is deferred pending
the basemap-sourcing and vendoring decision.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JW6ghFMDtnRYuYNzZhb47M

src/interfaces/api/handlers/photos_handler.rs

@@ -9,6 +9,7 @@ use std::sync::Arc;
 use tracing::{error, info};
 
 use crate::application::dtos::file_dto::FileDto;
+use crate::application::dtos::geo_dto::GeoBounds;
 use crate::common::di::AppState;
 use crate::interfaces::middleware::auth::AuthUser;
 
@@ -110,3 +111,76 @@ pub async fn list_photos(
         }
     }
 }
+
+/// Query parameters for the photos map (clustered) endpoint.
+#[derive(Deserialize)]
+pub struct GeoQueryParams {
+    /// Bounding box as `west,south,east,north` (decimal degrees).
+    pub bbox: String,
+    /// Slippy-map zoom level (0–20); controls cluster granularity.
+    pub zoom: Option<u8>,
+}
+
+/// Lists the caller's geotagged photos aggregated into map clusters within a
+/// bounding box. Gated on `OXICLOUD_ENABLE_PLACES` (the route is only mounted
+/// when the Places service is present).
+#[utoipa::path(
+    get,
+    path = "/api/photos/geo",
+    params(
+        ("bbox" = String, Query, description = "Bounding box 'west,south,east,north' (decimal degrees)"),
+        ("zoom" = Option<u8>, Query, description = "Map zoom level (0-20), controls cluster size")
+    ),
+    responses(
+        (status = 200, description = "Geotagged photos aggregated into map clusters"),
+        (status = 400, description = "Invalid bounding box"),
+        (status = 401, description = "Unauthorized")
+    ),
+    security(("bearerAuth" = [])),
+    tag = "photos"
+)]
+pub async fn list_photos_geo(
+    State(state): State<Arc<AppState>>,
+    auth_user: AuthUser,
+    Query(params): Query<GeoQueryParams>,
+) -> impl IntoResponse {
+    let Some(places) = state.places_service.as_ref() else {
+        return (
+            StatusCode::NOT_FOUND,
+            Json(serde_json::json!({ "error": "Places feature is disabled" })),
+        )
+            .into_response();
+    };
+
+    let coords: Vec<f64> = params
+        .bbox
+        .split(',')
+        .filter_map(|s| s.trim().parse::<f64>().ok())
+        .collect();
+    if coords.len() != 4 {
+        return (
+            StatusCode::BAD_REQUEST,
+            Json(serde_json::json!({ "error": "bbox must be 'west,south,east,north'" })),
+        )
+            .into_response();
+    }
+    let bounds = GeoBounds {
+        west: coords[0],
+        south: coords[1],
+        east: coords[2],
+        north: coords[3],
+    };
+    let zoom = params.zoom.unwrap_or(3);
+
+    match places.clusters(auth_user.id, bounds, zoom).await {
+        Ok(clusters) => Json(clusters).into_response(),
+        Err(err) => {
+            error!("Error listing photo geo clusters: {}", err);
+            (
+                StatusCode::INTERNAL_SERVER_ERROR,
+                Json(serde_json::json!({ "error": format!("{}", err) })),
+            )
+                .into_response()
+        }
+    }
+}

src/interfaces/api/mod.rs

@@ -164,6 +164,7 @@ use crate::interfaces::api::handlers::file_handler::MoveFilePayload;
         handlers::recent_handler::clear_recent_items,
         // Photos handler (free function)
         handlers::photos_handler::list_photos,
+        handlers::photos_handler::list_photos_geo,
         // Batch handlers (free functions)
         handlers::batch_handler::move_files_batch,
         handlers::batch_handler::copy_files_batch,

src/interfaces/api/routes.rs

@@ -431,9 +431,11 @@ pub fn create_api_routes(app_state: &Arc<AppState>) -> Router<Arc<AppState>> {
     {
         use crate::interfaces::api::handlers::photos_handler;
 
-        let photos_router = Router::new()
-            .route("/", get(photos_handler::list_photos))
-            .with_state(app_state.clone());
+        let mut photos_router = Router::new().route("/", get(photos_handler::list_photos));
+        if app_state.places_service.is_some() {
+            photos_router = photos_router.route("/geo", get(photos_handler::list_photos_geo));
+        }
+        let photos_router = photos_router.with_state(app_state.clone());
 
         router = router.nest("/photos", photos_router);
     }