feat(api): gateway + parcelas + teledetección NDVI/clima (Fase 3)

- backend/api/deps.py: proxy efímero BYOK (X-User-* con fallback DEV_*) + get_db.
- backend/services/remote_sensing.py: NDVI vía Sentinel Hub en CDSE (Statistical API
serie mensual 5 años + Process API heatmap PNG); OAuth client_credentials.
- backend/services/weather.py: Open-Meteo (sin llave) + agregación mensual.
- backend/services/parcels.py: CRUD + backfill NDVI de 5 años en background.
- backend/api/{fields,ndvi,weather}.py: /api/fields (CRUD), /api/ndvi (+/raster), /api/weather.
- main.py monta los routers nuevos; repositories.delete_field por id.
- Tests: unitarios (parse stats, agregación clima, deps) + integración en vivo
(NDVI real + cadena parcela->NDVI->persistencia). 52 passed, ruff limpio.
- Desviación: se usa Sentinel Hub (CDSE) en vez de pystac-client+rioxarray.

backend/api/deps.py

@@ -0,0 +1,80 @@
+"""
+Archivo: deps.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Dependencias compartidas de la API (gateway): el proxy **efímero** de credenciales
+BYOK y la sesión de base de datos. Las llaves del usuario llegan por cabeceras
+`X-User-*` (modelo de cero persistencia) y, para desarrollo local, hacen *fallback* a
+las variables `DEV_*`/`SUPABASE_*` del entorno. La `UserKeys` vive solo durante el
+request: nunca se escribe a disco, log ni BD.
+
+Acciones Principales:
+    - `get_user_keys`: extrae las llaves del request (header o entorno DEV).
+    - `get_db`: cede una sesión async de SQLAlchemy.
+
+Entradas / Dependencias:
+    - `fastapi.Header`, `backend.db.session`.
+
+Salidas / Efectos:
+    - Abre una sesión por request; no persiste credenciales.
+
+Ejemplo de Integración:
+    from backend.api.deps import get_user_keys, get_db
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+
+from fastapi import Header
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend.db.session import get_sessionmaker
+
+
+@dataclass
+class UserKeys:
+    """Llaves BYOK de la sesión (efímeras: viven solo durante el request)."""
+
+    groq: str | None = None
+    copernicus_id: str | None = None
+    copernicus_secret: str | None = None
+    supabase_url: str | None = None
+    supabase_key: str | None = None
+
+
+def get_user_keys(
+    x_user_groq_key: str | None = Header(default=None),
+    x_user_copernicus_id: str | None = Header(default=None),
+    x_user_copernicus_secret: str | None = Header(default=None),
+    x_user_supabase_url: str | None = Header(default=None),
+    x_user_supabase_key: str | None = Header(default=None),
+) -> UserKeys:
+    """
+    Construye las `UserKeys` del request: cabecera primero, entorno DEV como fallback.
+
+    El fallback permite el desarrollo local (las llaves en `.env` como `DEV_*`), pero en
+    producción siempre llegan por cabecera desde la UI y se descartan tras el request.
+
+    Returns:
+        UserKeys: Credenciales de la sesión (nunca se persisten).
+    """
+    return UserKeys(
+        groq=x_user_groq_key or os.getenv("DEV_GROQ_API_KEY") or None,
+        copernicus_id=x_user_copernicus_id or os.getenv("DEV_COPERNICUS_CLIENT_ID") or None,
+        copernicus_secret=(
+            x_user_copernicus_secret or os.getenv("DEV_COPERNICUS_CLIENT_SECRET") or None
+        ),
+        supabase_url=x_user_supabase_url or os.getenv("SUPABASE_URL") or None,
+        supabase_key=x_user_supabase_key or os.getenv("SUPABASE_ANON_KEY") or None,
+    )
+
+
+async def get_db() -> AsyncIterator[AsyncSession]:
+    """Cede una sesión async de SQLAlchemy y la cierra al terminar el request."""
+    async with get_sessionmaker()() as session:
+        yield session

backend/api/fields.py

@@ -0,0 +1,67 @@
+"""
+Archivo: fields.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Router del módulo *Creación de Parcelas*: CRUD de parcelas (`/api/fields`). Al crear una
+parcela, dispara en segundo plano el backfill NDVI de 5 años (si hay credenciales de
+Copernicus). La geometría se valida con `FieldIn` (polígono cerrado EPSG:4326).
+
+Estructura Interna:
+    - `POST /api/fields`, `GET /api/fields`, `GET /api/fields/{id}`, `DELETE /api/fields/{id}`.
+
+Entradas / Dependencias:
+    - `backend.services.parcels`, `backend.api.deps`.
+
+Ejemplo de Integración:
+    from backend.api.fields import router
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend.api.deps import UserKeys, get_db, get_user_keys
+from backend.core.schemas import FieldIn
+from backend.services import parcels
+
+router = APIRouter(prefix="/api/fields", tags=["parcelas"])
+
+
+@router.post("")
+async def create_field(
+    body: FieldIn,
+    background: BackgroundTasks,
+    keys: UserKeys = Depends(get_user_keys),
+    session: AsyncSession = Depends(get_db),
+) -> dict:
+    """Crea una parcela y agenda el backfill NDVI de 5 años en segundo plano."""
+    row = await parcels.create_parcel(session, body, user_id=None)
+    background.add_task(parcels.run_ndvi_backfill, str(row.id), body.geojson, keys)
+    return {"id": str(row.id), "name": row.name, "area_ha": row.area_ha}
+
+
+@router.get("")
+async def list_fields(session: AsyncSession = Depends(get_db)) -> list[dict]:
+    """Lista las parcelas registradas."""
+    rows = await parcels.list_parcels(session)
+    return [{"id": str(r.id), "name": r.name} for r in rows]
+
+
+@router.get("/{field_id}")
+async def get_field(field_id: str, session: AsyncSession = Depends(get_db)) -> dict:
+    """Devuelve una parcela por id (404 si no existe)."""
+    row = await parcels.get_parcel(session, field_id)
+    if row is None:
+        raise HTTPException(status_code=404, detail="Parcela no encontrada")
+    return {"id": str(row.id), "name": row.name, "area_ha": row.area_ha}
+
+
+@router.delete("/{field_id}")
+async def delete_field(field_id: str, session: AsyncSession = Depends(get_db)) -> dict:
+    """Borra una parcela por id (404 si no existía)."""
+    if not await parcels.delete_parcel(session, field_id):
+        raise HTTPException(status_code=404, detail="Parcela no encontrada")
+    return {"deleted": field_id}

backend/api/ndvi.py

@@ -0,0 +1,88 @@
+"""
+Archivo: ndvi.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Router de Teledetección (NDVI). `POST /api/ndvi` devuelve la serie mensual: si se pasa
+`field_id`, la lee persistida (rápida); si se pasa `geojson`, la calcula en vivo vía
+Sentinel Hub (default últimos 5 años). `POST /api/ndvi/raster` devuelve el heatmap NDVI
+(PNG ~10 m/px) para pintar como capa en el mapa.
+
+Estructura Interna:
+    - `POST /api/ndvi` (serie), `POST /api/ndvi/raster` (heatmap PNG).
+
+Entradas / Dependencias:
+    - `backend.services.remote_sensing`, `backend.db.repositories`, `backend.api.deps`.
+
+Ejemplo de Integración:
+    from backend.api.ndvi import router
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Response
+from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend.api.deps import UserKeys, get_db, get_user_keys
+from backend.db import repositories as repo
+from backend.services import remote_sensing
+
+router = APIRouter(prefix="/api/ndvi", tags=["teledetección"])
+
+
+class NdviRequest(BaseModel):
+    """Petición de serie NDVI: por parcela (persistida) o por geometría (en vivo)."""
+
+    field_id: str | None = None
+    geojson: dict | None = None
+    start: str | None = None
+    end: str | None = None
+
+
+class NdviRasterRequest(BaseModel):
+    """Petición de heatmap NDVI (PNG) para una geometría."""
+
+    geojson: dict
+    start: str | None = None
+    end: str | None = None
+
+
+def _require_copernicus(keys: UserKeys) -> None:
+    """Lanza 400 si faltan las credenciales de Copernicus para una consulta en vivo."""
+    if not (keys.copernicus_id and keys.copernicus_secret):
+        raise HTTPException(
+            status_code=400, detail="Faltan credenciales de Copernicus (pestaña Credenciales)."
+        )
+
+
+@router.post("")
+async def ndvi_series(
+    body: NdviRequest,
+    keys: UserKeys = Depends(get_user_keys),
+    session: AsyncSession = Depends(get_db),
+) -> dict:
+    """Devuelve la serie NDVI mensual (persistida por parcela o calculada en vivo)."""
+    if body.field_id:
+        series = await repo.get_ndvi_series(session, body.field_id)
+        return {"series": series}
+    if body.geojson:
+        _require_copernicus(keys)
+        series = await remote_sensing.ndvi_series_monthly(
+            body.geojson, body.start, body.end, keys.copernicus_id, keys.copernicus_secret
+        )
+        return {"series": series}
+    raise HTTPException(status_code=422, detail="Indica 'field_id' o 'geojson'.")
+
+
+@router.post("/raster")
+async def ndvi_raster(
+    body: NdviRasterRequest, keys: UserKeys = Depends(get_user_keys)
+) -> Response:
+    """Devuelve el heatmap NDVI (PNG ~10 m/px) recortado al polígono."""
+    _require_copernicus(keys)
+    png = await remote_sensing.ndvi_heatmap_png(
+        body.geojson, keys.copernicus_id, keys.copernicus_secret, body.start, body.end
+    )
+    return Response(content=png, media_type="image/png")

backend/api/weather.py

@@ -0,0 +1,44 @@
+"""
+Archivo: weather.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Router de clima (`/api/weather`). Devuelve la serie agroclimática mensual (precipitación,
+temperatura media, radiación) por coordenadas usando Open-Meteo (sin llave). Por defecto
+cubre los últimos 5 años, para cruzarse con la serie NDVI en Teledetección.
+
+Estructura Interna:
+    - `POST /api/weather`.
+
+Entradas / Dependencias:
+    - `backend.services.weather`.
+
+Ejemplo de Integración:
+    from backend.api.weather import router
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+from pydantic import BaseModel, Field
+
+from backend.services import weather
+
+router = APIRouter(prefix="/api/weather", tags=["clima"])
+
+
+class WeatherRequest(BaseModel):
+    """Petición de clima por coordenadas y rango opcional (default últimos 5 años)."""
+
+    lat: float = Field(ge=-90, le=90)
+    lon: float = Field(ge=-180, le=180)
+    start: str | None = None
+    end: str | None = None
+
+
+@router.post("")
+async def weather_series(body: WeatherRequest) -> dict:
+    """Devuelve la serie climática mensual de las coordenadas indicadas."""
+    series = await weather.weather_series(body.lat, body.lon, body.start, body.end)
+    return {"series": series}

backend/db/repositories.py

@@ -108,6 +108,16 @@ async def delete_fields_for_user(session: AsyncSession, user_id: str) -> None:
     await session.commit()
 
 
+async def delete_field(session: AsyncSession, field_id: Any) -> bool:
+    """Borra una parcela por id (cascada borra su NDVI). Devuelve True si existía."""
+    result = await session.execute(
+        text("delete from fields where id = :id returning id"), {"id": str(field_id)}
+    )
+    deleted = result.first() is not None
+    await session.commit()
+    return deleted
+
+
 async def upsert_ndvi_points(
     session: AsyncSession, field_id: Any, points: list[dict]
 ) -> int:

backend/main.py

@@ -40,6 +40,9 @@ from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
 from backend.api.count import router as count_router
+from backend.api.fields import router as fields_router
+from backend.api.ndvi import router as ndvi_router
+from backend.api.weather import router as weather_router
 from backend.config import get_settings
 from backend.core.inference import ModelNotAvailableError, create_adapter
 
@@ -87,7 +90,7 @@ def create_app() -> FastAPI:
     """
     settings = get_settings()
     app = FastAPI(
-        title="AgroVisión MVP — Backend",
+        title="AgroVisión — Backend (plataforma)",
         version=settings.model_version,
         lifespan=lifespan,
     )
@@ -95,9 +98,12 @@ def create_app() -> FastAPI:
         CORSMiddleware,
         allow_origins=list(settings.allowed_origins),
         allow_methods=["*"],
-        allow_headers=["*"],
+        allow_headers=["*"],  # necesario para las cabeceras BYOK X-User-*
     )
-    app.include_router(count_router)
+    app.include_router(fields_router)  # Creación de Parcelas
+    app.include_router(ndvi_router)  # Teledetección NDVI
+    app.include_router(weather_router)  # Clima
+    app.include_router(count_router)  # Conteo (en desarrollo / standby)
     return app
 
 

backend/services/parcels.py

@@ -0,0 +1,97 @@
+"""
+Archivo: parcels.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Servicio de parcelas (módulo *Creación de Parcelas*). Orquesta el alta/listado/borrado
+de parcelas sobre el repositorio y dispara el **backfill** NDVI de 5 años al crear una
+parcela. El backfill corre como tarea de fondo (no bloquea la respuesta) y persiste la
+serie mensual en `ndvi_timeseries` de forma idempotente.
+
+Acciones Principales:
+    - CRUD de parcelas y disparo del relleno histórico de NDVI.
+
+Estructura Interna:
+    - `create_parcel` / `list_parcels` / `get_parcel` / `delete_parcel`.
+    - `run_ndvi_backfill`: tarea de fondo (sesión propia) que llama a teledetección.
+
+Entradas / Dependencias:
+    - `backend.db` (repos/sesión), `backend.services.remote_sensing`.
+
+Salidas / Efectos:
+    - Escribe parcelas y serie NDVI en la BD del usuario.
+
+Ejemplo de Integración:
+    from backend.services import parcels
+    row = await parcels.create_parcel(session, field_in)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from sqlalchemy import Row
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend.api.deps import UserKeys
+from backend.core.schemas import FieldIn
+from backend.db import repositories as repo
+from backend.db.session import get_sessionmaker
+from backend.services import remote_sensing
+
+_logger = logging.getLogger("agrovision.parcels")
+
+
+async def create_parcel(
+    session: AsyncSession, field_in: FieldIn, user_id: str | None = None
+) -> Row:
+    """Crea una parcela (geometría validada por `FieldIn`) y devuelve id/nombre/área."""
+    return await repo.create_field(
+        session, name=field_in.name, geojson=field_in.geojson, user_id=user_id
+    )
+
+
+async def list_parcels(session: AsyncSession, user_id: str | None = None) -> list[Row]:
+    """Lista las parcelas (opcionalmente filtradas por usuario)."""
+    return await repo.list_fields(session, user_id=user_id)
+
+
+async def get_parcel(session: AsyncSession, field_id: Any) -> Row | None:
+    """Devuelve una parcela por id o None."""
+    return await repo.get_field(session, field_id)
+
+
+async def delete_parcel(session: AsyncSession, field_id: Any) -> bool:
+    """Borra una parcela por id; True si existía."""
+    return await repo.delete_field(session, field_id)
+
+
+async def run_ndvi_backfill(field_id: str, geojson: dict, keys: UserKeys) -> int:
+    """
+    Tarea de fondo: calcula la serie NDVI de 5 años y la persiste (idempotente).
+
+    Abre su propia sesión (se ejecuta después de responder). Captura errores para no
+    romper el request ya finalizado; los registra sin exponer secretos.
+
+    Args:
+        field_id (str): Parcela recién creada.
+        geojson (dict): Geometría de la parcela.
+        keys (UserKeys): Credenciales BYOK de la sesión (Copernicus).
+
+    Returns:
+        int: Número de puntos NDVI persistidos (0 si no hubo credenciales o falló).
+    """
+    if not (keys.copernicus_id and keys.copernicus_secret):
+        _logger.info("Backfill NDVI omitido: faltan credenciales de Copernicus.")
+        return 0
+    try:
+        series = await remote_sensing.ndvi_series_monthly(
+            geojson, None, None, keys.copernicus_id, keys.copernicus_secret
+        )
+        async with get_sessionmaker()() as session:
+            return await repo.upsert_ndvi_points(session, field_id, series)
+    except Exception as error:  # noqa: BLE001 - el request ya respondió; solo registramos
+        _logger.warning("Backfill NDVI falló para %s: %s", field_id, error)
+        return 0

backend/services/remote_sensing.py

@@ -0,0 +1,258 @@
+"""
+Archivo: remote_sensing.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Teledetección NDVI sobre Sentinel-2 usando **Sentinel Hub en Copernicus Data Space
+(CDSE)** con OAuth client credentials (BYOK). En vez de descargar COGs con rasterio,
+se usan dos APIs HTTP del propio CDSE:
+  - **Statistical API**: serie temporal NDVI agregada por mes (mean/min/max) sobre el
+    polígono, con default de los últimos 5 años.
+  - **Process API**: PNG colorizado (heatmap NDVI ~10 m/px) para la capa del mapa.
+Es más fiable y ligero en capa gratuita que el pipeline rasterio/GDAL.
+
+Acciones Principales:
+    - Obtiene token CDSE, calcula la serie NDVI mensual y el heatmap PNG.
+
+Estructura Interna:
+    - `_get_token`: client_credentials -> access_token (cacheado por expiración).
+    - `_default_range`: rango por defecto (últimos 5 años).
+    - `_parse_stats`: parseo puro de la respuesta de la Statistical API a la serie.
+    - `ndvi_series_monthly` / `ndvi_heatmap_png`: llamadas a SH (async).
+
+Entradas / Dependencias:
+    - `httpx`; credenciales Copernicus (client_id/secret) del usuario.
+
+Salidas / Efectos:
+    - Llamadas HTTPS a CDSE; no persiste credenciales.
+
+Ejemplo de Integración:
+    from backend.services.remote_sensing import ndvi_series_monthly
+    serie = await ndvi_series_monthly(geojson, None, None, cid, secret)
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import time
+
+import httpx
+from dateutil.relativedelta import relativedelta
+
+_TOKEN_URL = "https://identity.dataspace.copernicus.eu/auth/realms/CDSE/protocol/openid-connect/token"
+_STATS_URL = "https://sh.dataspace.copernicus.eu/api/v1/statistics"
+_PROCESS_URL = "https://sh.dataspace.copernicus.eu/api/v1/process"
+_CRS_4326 = "http://www.opengis.net/def/crs/EPSG/0/4326"
+_RES_DEG = 0.0001  # ~10 m/px en EPSG:4326 (grados)
+
+# Evalscript para la Statistical API: NDVI con máscara de nubes vía SCL.
+_STATS_EVALSCRIPT = """//VERSION=3
+function setup() {
+  return {
+    input: [{bands: ["B04", "B08", "SCL", "dataMask"]}],
+    output: [{id: "ndvi", bands: 1}, {id: "dataMask", bands: 1}]
+  };
+}
+function evaluatePixel(s) {
+  let ndvi = (s.B08 - s.B04) / (s.B08 + s.B04);
+  let cloudy = [3, 8, 9, 10, 11].indexOf(s.SCL) > -1;  // sombra/nube/cirros/nieve
+  return {ndvi: [ndvi], dataMask: [cloudy ? 0 : s.dataMask]};
+}"""
+
+# Evalscript para la Process API: NDVI colorizado (rojo->verde) como RGBA.
+_VIS_EVALSCRIPT = """//VERSION=3
+function setup() {
+  return {input: ["B04", "B08", "dataMask"], output: {bands: 4}};
+}
+const STOPS = [-0.2, 0.0, 0.2, 0.4, 0.6, 0.8];
+const COLORS = [[0.65,0,0.15],[0.96,0.43,0.26],[0.99,0.68,0.38],
+                [0.85,0.94,0.55],[0.40,0.74,0.39],[0,0.41,0.22]];
+function evaluatePixel(s) {
+  let ndvi = (s.B08 - s.B04) / (s.B08 + s.B04);
+  let c = colorBlend(ndvi, STOPS, COLORS);
+  return [c[0], c[1], c[2], s.dataMask];
+}"""
+
+_token_cache: dict[str, tuple[str, float]] = {}
+
+
+async def _get_token(client_id: str, client_secret: str) -> str:
+    """
+    Obtiene un access_token de CDSE (client_credentials), cacheado hasta su expiración.
+
+    Args:
+        client_id (str): Client id del OAuth client de Copernicus.
+        client_secret (str): Client secret correspondiente.
+
+    Returns:
+        str: Bearer token válido para las APIs de Sentinel Hub en CDSE.
+    """
+    cached = _token_cache.get(client_id)
+    if cached and cached[1] > time.time() + 60:
+        return cached[0]
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            _TOKEN_URL,
+            data={
+                "grant_type": "client_credentials",
+                "client_id": client_id,
+                "client_secret": client_secret,
+            },
+            timeout=30,
+        )
+    response.raise_for_status()
+    payload = response.json()
+    token = payload["access_token"]
+    _token_cache[client_id] = (token, time.time() + float(payload.get("expires_in", 600)))
+    return token
+
+
+def _default_range() -> tuple[str, str]:
+    """Devuelve el rango por defecto (últimos 5 años) como ISO datetimes UTC."""
+    end = dt.date.today()
+    start = end - relativedelta(years=5)
+    return f"{start.isoformat()}T00:00:00Z", f"{end.isoformat()}T23:59:59Z"
+
+
+def _parse_stats(payload: dict) -> list[dict]:
+    """
+    Convierte la respuesta de la Statistical API en la serie NDVI mensual.
+
+    Args:
+        payload (dict): JSON devuelto por la Statistical API.
+
+    Returns:
+        list[dict]: Puntos {date, mean_ndvi, min_ndvi, max_ndvi, cloud_cover, source}
+        ordenados por fecha; se omiten intervalos sin píxeles válidos.
+    """
+    series: list[dict] = []
+    for item in payload.get("data", []):
+        outputs = item.get("outputs", {})
+        bands = outputs.get("ndvi", {}).get("bands", {})
+        stats = bands.get("B0", {}).get("stats", {})
+        mean = stats.get("mean")
+        if mean is None or stats.get("sampleCount", 0) == 0:
+            continue
+        # En meses totalmente nublados/sin escena, mean puede venir como 'NaN'.
+        if isinstance(mean, str):
+            continue
+        month = item["interval"]["from"][:7]
+        series.append(
+            {
+                "date": f"{month}-01",
+                "mean_ndvi": round(float(mean), 4),
+                "min_ndvi": round(float(stats.get("min", mean)), 4),
+                "max_ndvi": round(float(stats.get("max", mean)), 4),
+                "cloud_cover": None,
+                "source": "sentinel2",
+            }
+        )
+    return sorted(series, key=lambda p: p["date"])
+
+
+def _stats_body(geojson: dict, start: str, end: str) -> dict:
+    """Construye el cuerpo de la Statistical API para NDVI mensual."""
+    return {
+        "input": {
+            "bounds": {"geometry": geojson, "properties": {"crs": _CRS_4326}},
+            "data": [{"type": "sentinel-2-l2a"}],
+        },
+        "aggregation": {
+            "timeRange": {"from": start, "to": end},
+            "aggregationInterval": {"of": "P1M"},
+            "evalscript": _STATS_EVALSCRIPT,
+            "resx": _RES_DEG,
+            "resy": _RES_DEG,
+        },
+    }
+
+
+async def ndvi_series_monthly(
+    geojson: dict,
+    start: str | None,
+    end: str | None,
+    client_id: str,
+    client_secret: str,
+) -> list[dict]:
+    """
+    Calcula la serie NDVI mensual de un polígono (default: últimos 5 años).
+
+    Args:
+        geojson (dict): Geometría Polygon (EPSG:4326).
+        start (str | None): Inicio ISO; si es None, se usan los últimos 5 años.
+        end (str | None): Fin ISO; si es None, hoy.
+        client_id (str): Client id de Copernicus.
+        client_secret (str): Client secret de Copernicus.
+
+    Returns:
+        list[dict]: Serie NDVI mensual lista para persistir/graficar.
+    """
+    if not start or not end:
+        start, end = _default_range()
+    token = await _get_token(client_id, client_secret)
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            _STATS_URL,
+            headers={"Authorization": f"Bearer {token}"},
+            json=_stats_body(geojson, start, end),
+            timeout=120,
+        )
+    response.raise_for_status()
+    return _parse_stats(response.json())
+
+
+async def ndvi_heatmap_png(
+    geojson: dict,
+    client_id: str,
+    client_secret: str,
+    start: str | None = None,
+    end: str | None = None,
+    size: int = 512,
+) -> bytes:
+    """
+    Genera un PNG colorizado del NDVI (heatmap ~10 m/px) recortado al polígono.
+
+    Args:
+        geojson (dict): Geometría Polygon (EPSG:4326).
+        client_id (str): Client id de Copernicus.
+        client_secret (str): Client secret de Copernicus.
+        start (str | None): Inicio del rango; default últimos 5 años.
+        end (str | None): Fin del rango; default hoy.
+        size (int): Lado del PNG en píxeles.
+
+    Returns:
+        bytes: Imagen PNG (RGBA) del heatmap NDVI.
+    """
+    if not start or not end:
+        start, end = _default_range()
+    token = await _get_token(client_id, client_secret)
+    body = {
+        "input": {
+            "bounds": {"geometry": geojson, "properties": {"crs": _CRS_4326}},
+            "data": [
+                {
+                    "type": "sentinel-2-l2a",
+                    "dataFilter": {
+                        "timeRange": {"from": start, "to": end},
+                        "mosaickingOrder": "leastCC",
+                    },
+                }
+            ],
+        },
+        "output": {
+            "width": size,
+            "height": size,
+            "responses": [{"identifier": "default", "format": {"type": "image/png"}}],
+        },
+        "evalscript": _VIS_EVALSCRIPT,
+    }
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            _PROCESS_URL,
+            headers={"Authorization": f"Bearer {token}"},
+            json=body,
+            timeout=120,
+        )
+    response.raise_for_status()
+    return response.content

backend/services/weather.py

@@ -0,0 +1,139 @@
+"""
+Archivo: weather.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Datos agroclimáticos por coordenadas usando **Open-Meteo** (archivo histórico, sin
+llave). Se consulta on-demand y se **agrega por mes** para los gráficos de Teledetección
+(precipitación sumada, temperatura media, radiación sumada). Por defecto cubre los
+últimos 5 años, alineado con la serie NDVI.
+
+Acciones Principales:
+    - Descarga el histórico diario y lo resume a puntos mensuales.
+
+Estructura Interna:
+    - `_default_range`: rango por defecto (últimos 5 años).
+    - `aggregate_weather_monthly`: agregación mensual pura (testeable sin red).
+    - `open_meteo` / `weather_series`: descarga async + serie mensual.
+
+Entradas / Dependencias:
+    - `httpx`; Open-Meteo (endpoint público, sin credenciales).
+
+Salidas / Efectos:
+    - Llamada HTTPS a Open-Meteo; sin persistencia.
+
+Ejemplo de Integración:
+    from backend.services.weather import weather_series
+    serie = await weather_series(-34.6, -58.38)
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from collections import defaultdict
+
+import httpx
+from dateutil.relativedelta import relativedelta
+
+_ARCHIVE_URL = "https://archive-api.open-meteo.com/v1/archive"
+_DAILY_VARS = "precipitation_sum,temperature_2m_mean,shortwave_radiation_sum"
+
+
+def _default_range() -> tuple[str, str]:
+    """Devuelve el rango por defecto (últimos 5 años) como fechas ISO."""
+    end = dt.date.today()
+    start = end - relativedelta(years=5)
+    return start.isoformat(), end.isoformat()
+
+
+def aggregate_weather_monthly(daily: dict) -> list[dict]:
+    """
+    Agrega el histórico diario de Open-Meteo a puntos mensuales.
+
+    Args:
+        daily (dict): Bloque 'daily' de Open-Meteo con listas paralelas 'time',
+            'precipitation_sum', 'temperature_2m_mean', 'shortwave_radiation_sum'.
+
+    Returns:
+        list[dict]: Puntos {date, precip_mm, temp_mean_c, radiation} por mes,
+        ordenados cronológicamente.
+    """
+    times = daily.get("time", [])
+    precip = daily.get("precipitation_sum", [])
+    temp = daily.get("temperature_2m_mean", [])
+    radiation = daily.get("shortwave_radiation_sum", [])
+
+    buckets: dict[str, dict[str, list[float]]] = defaultdict(
+        lambda: {"precip": [], "temp": [], "rad": []}
+    )
+    for i, day in enumerate(times):
+        month = str(day)[:7]
+        if i < len(precip) and precip[i] is not None:
+            buckets[month]["precip"].append(precip[i])
+        if i < len(temp) and temp[i] is not None:
+            buckets[month]["temp"].append(temp[i])
+        if i < len(radiation) and radiation[i] is not None:
+            buckets[month]["rad"].append(radiation[i])
+
+    series: list[dict] = []
+    for month in sorted(buckets):
+        values = buckets[month]
+        temps = values["temp"]
+        series.append(
+            {
+                "date": f"{month}-01",
+                "precip_mm": round(sum(values["precip"]), 1),
+                "temp_mean_c": round(sum(temps) / len(temps), 1) if temps else None,
+                "radiation": round(sum(values["rad"]), 1),
+            }
+        )
+    return series
+
+
+async def open_meteo(lat: float, lon: float, start: str, end: str) -> dict:
+    """
+    Descarga el bloque 'daily' del histórico de Open-Meteo para unas coordenadas.
+
+    Args:
+        lat (float): Latitud.
+        lon (float): Longitud.
+        start (str): Fecha inicial (YYYY-MM-DD).
+        end (str): Fecha final (YYYY-MM-DD).
+
+    Returns:
+        dict: Bloque 'daily' de la respuesta.
+    """
+    params = {
+        "latitude": lat,
+        "longitude": lon,
+        "start_date": start,
+        "end_date": end,
+        "daily": _DAILY_VARS,
+        "timezone": "UTC",
+    }
+    async with httpx.AsyncClient() as client:
+        response = await client.get(_ARCHIVE_URL, params=params, timeout=60)
+    response.raise_for_status()
+    return response.json().get("daily", {})
+
+
+async def weather_series(
+    lat: float, lon: float, start: str | None = None, end: str | None = None
+) -> list[dict]:
+    """
+    Devuelve la serie climática mensual de unas coordenadas (default: últimos 5 años).
+
+    Args:
+        lat (float): Latitud.
+        lon (float): Longitud.
+        start (str | None): Fecha inicial; default últimos 5 años.
+        end (str | None): Fecha final; default hoy.
+
+    Returns:
+        list[dict]: Serie mensual {date, precip_mm, temp_mean_c, radiation}.
+    """
+    if not start or not end:
+        start, end = _default_range()
+    daily = await open_meteo(lat, lon, start, end)
+    return aggregate_weather_monthly(daily)

tests/integration/test_teledeteccion.py

@@ -0,0 +1,104 @@
+"""
+Archivo: test_teledeteccion.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Pruebas de integración de Teledetección (Fase 3) contra Sentinel Hub (CDSE) y la BD del
+usuario. Verifican que la serie NDVI mensual se obtiene en vivo y que la cadena
+parcela → NDVI → persistencia funciona. Se omiten si faltan credenciales de Copernicus
+o `DATABASE_URL`.
+
+Ejecución:
+    uv run python -m pytest tests/integration/test_teledeteccion.py -v
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import os
+import uuid
+
+import pytest
+from dotenv import load_dotenv
+
+load_dotenv()
+
+_HAS_COP = bool(
+    os.getenv("DEV_COPERNICUS_CLIENT_ID") and os.getenv("DEV_COPERNICUS_CLIENT_SECRET")
+)
+_HAS_DB = bool(os.getenv("DATABASE_URL"))
+
+from backend.db import repositories as repo  # noqa: E402
+from backend.db.session import get_engine, get_sessionmaker  # noqa: E402
+from backend.services import remote_sensing  # noqa: E402
+
+_SMALL_GEOM = {
+    "type": "Polygon",
+    "coordinates": [
+        [[-58.50, -34.60], [-58.50, -34.58], [-58.47, -34.58], [-58.47, -34.60], [-58.50, -34.60]]
+    ],
+}
+_RANGE = ("2024-09-01T00:00:00Z", "2024-12-31T23:59:59Z")
+
+
+@contextlib.asynccontextmanager
+async def _engine_scope():
+    """Engine fresco por test (cada test usa su propio event loop)."""
+    get_engine.cache_clear()
+    get_sessionmaker.cache_clear()
+    try:
+        yield get_sessionmaker()
+    finally:
+        await get_engine().dispose()
+        get_engine.cache_clear()
+        get_sessionmaker.cache_clear()
+
+
+@pytest.mark.skipif(not _HAS_COP, reason="Faltan credenciales de Copernicus")
+def test_ndvi_series_live() -> None:
+    """La Statistical API devuelve una serie NDVI mensual con valores en [-1, 1]."""
+
+    async def _run() -> None:
+        series = await remote_sensing.ndvi_series_monthly(
+            _SMALL_GEOM,
+            _RANGE[0],
+            _RANGE[1],
+            os.environ["DEV_COPERNICUS_CLIENT_ID"],
+            os.environ["DEV_COPERNICUS_CLIENT_SECRET"],
+        )
+        assert len(series) >= 1
+        for point in series:
+            assert -1 <= point["mean_ndvi"] <= 1
+            assert point["date"].endswith("-01")
+
+    asyncio.run(_run())
+
+
+@pytest.mark.skipif(not (_HAS_COP and _HAS_DB), reason="Faltan Copernicus o DATABASE_URL")
+def test_parcel_ndvi_persist() -> None:
+    """Cadena completa: crear parcela → calcular NDVI → persistir → leer la serie."""
+    user_id = str(uuid.uuid4())
+
+    async def _run() -> None:
+        async with _engine_scope() as sm, sm() as session:
+            try:
+                field = await repo.create_field(
+                    session, name="Lote Teledet", geojson=_SMALL_GEOM, user_id=user_id
+                )
+                series = await remote_sensing.ndvi_series_monthly(
+                    _SMALL_GEOM,
+                    _RANGE[0],
+                    _RANGE[1],
+                    os.environ["DEV_COPERNICUS_CLIENT_ID"],
+                    os.environ["DEV_COPERNICUS_CLIENT_SECRET"],
+                )
+                await repo.upsert_ndvi_points(session, field.id, series)
+                persisted = await repo.get_ndvi_series(session, field.id)
+                assert len(persisted) == len(series)
+                assert len(persisted) >= 1
+            finally:
+                await repo.delete_fields_for_user(session, user_id)
+
+    asyncio.run(_run())

tests/unit/test_deps.py

@@ -0,0 +1,48 @@
+"""
+Archivo: test_deps.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Pruebas unitarias del proxy efímero de credenciales: la cabecera tiene prioridad y, si
+falta, se hace fallback al entorno DEV (desarrollo local).
+
+Ejecución:
+    uv run python -m pytest tests/unit/test_deps.py
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from backend.api.deps import get_user_keys
+
+
+def test_get_user_keys_fallback_a_entorno(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Sin cabecera, las llaves se toman de las variables DEV_* del entorno."""
+    monkeypatch.setenv("DEV_COPERNICUS_CLIENT_ID", "env-id")
+    monkeypatch.setenv("DEV_COPERNICUS_CLIENT_SECRET", "env-secret")
+    monkeypatch.setenv("DEV_GROQ_API_KEY", "env-groq")
+    keys = get_user_keys(
+        x_user_groq_key=None,
+        x_user_copernicus_id=None,
+        x_user_copernicus_secret=None,
+        x_user_supabase_url=None,
+        x_user_supabase_key=None,
+    )
+    assert keys.copernicus_id == "env-id"
+    assert keys.copernicus_secret == "env-secret"
+    assert keys.groq == "env-groq"
+
+
+def test_get_user_keys_cabecera_tiene_prioridad(monkeypatch: pytest.MonkeyPatch) -> None:
+    """La cabecera X-User-* gana sobre el entorno DEV."""
+    monkeypatch.setenv("DEV_COPERNICUS_CLIENT_ID", "env-id")
+    keys = get_user_keys(
+        x_user_groq_key=None,
+        x_user_copernicus_id="hdr-id",
+        x_user_copernicus_secret=None,
+        x_user_supabase_url=None,
+        x_user_supabase_key=None,
+    )
+    assert keys.copernicus_id == "hdr-id"

tests/unit/test_remote_sensing.py

@@ -0,0 +1,59 @@
+"""
+Archivo: test_remote_sensing.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Pruebas unitarias (sin red) del parseo de la Statistical API de Sentinel Hub y del
+rango por defecto de 5 años.
+
+Ejecución:
+    uv run python -m pytest tests/unit/test_remote_sensing.py
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+
+from backend.services.remote_sensing import _default_range, _parse_stats
+
+
+def _item(month: str, stats: dict) -> dict:
+    """Construye un item de la respuesta Statistical API con las stats dadas."""
+    return {
+        "interval": {"from": f"{month}-01T00:00:00Z", "to": f"{month}-28T00:00:00Z"},
+        "outputs": {"ndvi": {"bands": {"B0": {"stats": stats}}}},
+    }
+
+
+_SAMPLE = {
+    "data": [
+        _item("2024-09", {"mean": 0.274, "min": -0.143, "max": 0.923, "sampleCount": 60000}),
+        _item("2024-10", {"mean": 0.321, "min": -0.13, "max": 0.928, "sampleCount": 60000}),
+        _item("2024-12", {"sampleCount": 0}),  # mes sin píxeles válidos -> se descarta
+    ]
+}
+
+
+def test_parse_stats_extrae_y_ordena() -> None:
+    """Parsea la serie, normaliza la fecha al día 1 y descarta meses vacíos."""
+    series = _parse_stats(_SAMPLE)
+    assert [p["date"] for p in series] == ["2024-09-01", "2024-10-01"]
+    assert series[0]["mean_ndvi"] == 0.274
+    assert series[0]["min_ndvi"] == -0.143
+    assert series[0]["source"] == "sentinel2"
+
+
+def test_parse_stats_serie_vacia() -> None:
+    """Una respuesta sin datos produce una serie vacía (no error)."""
+    assert _parse_stats({"data": []}) == []
+
+
+def test_default_range_cinco_anios() -> None:
+    """El rango por defecto abarca 5 años y termina en formato ISO con Z."""
+    start, end = _default_range()
+    assert end.endswith("Z") and start.endswith("Z")
+    start_year = int(start[:4])
+    end_year = int(end[:4])
+    assert end_year - start_year == 5
+    assert end[:10] == f"{dt.date.today().isoformat()}"

tests/unit/test_weather.py

@@ -0,0 +1,37 @@
+"""
+Archivo: test_weather.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Pruebas unitarias (sin red) de la agregación mensual del clima de Open-Meteo.
+
+Ejecución:
+    uv run python -m pytest tests/unit/test_weather.py
+"""
+
+from __future__ import annotations
+
+from backend.services.weather import aggregate_weather_monthly
+
+_DAILY = {
+    "time": ["2026-04-01", "2026-04-02", "2026-05-01"],
+    "precipitation_sum": [10.0, 5.0, 20.0],
+    "temperature_2m_mean": [18.0, 20.0, 22.0],
+    "shortwave_radiation_sum": [100.0, 110.0, 120.0],
+}
+
+
+def test_aggregate_weather_monthly_suma_y_promedia() -> None:
+    """Precipitación y radiación se suman por mes; la temperatura se promedia."""
+    series = aggregate_weather_monthly(_DAILY)
+    assert [p["date"] for p in series] == ["2026-04-01", "2026-05-01"]
+    abril = series[0]
+    assert abril["precip_mm"] == 15.0
+    assert abril["temp_mean_c"] == 19.0
+    assert abril["radiation"] == 210.0
+
+
+def test_aggregate_weather_monthly_vacio() -> None:
+    """Un bloque diario vacío produce una serie vacía."""
+    assert aggregate_weather_monthly({}) == []