feat(core): esquemas de dominio y motores puros NDVI/GSD/densidad (Fase 1)

- backend/core/schemas.py: FieldIn (valida polígono cerrado 4326), FieldOut,
NDVIPoint, WeatherPoint, ChatMessage.
- backend/core/ndvi.py: ndvi(), zonal_stats(), aggregate_monthly() (1 punto/mes).
- backend/core/geometry.py: gsd_cm_per_px(), density_per_ha(), geodesic_area_m2().
- Tests unitarios (TDD): test_domain_schemas, test_ndvi, test_geometry (verde, ruff limpio).

backend/core/geometry.py

@@ -0,0 +1,99 @@
+"""
+Archivo: geometry.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Funciones geométricas **puras** (Fase 1): distancia de muestreo terrestre (GSD) que
+relaciona la resolución con la geometría de vuelo del dron, densidad de siembra por
+hectárea y área geodésica de un polígono lon/lat. El área geodésica sirve de respaldo
+cuando no hay PostGIS disponible (en producción se usa `ST_Area(geom::geography)`).
+
+Acciones Principales:
+    - Calcula GSD, densidad por hectárea y área geodésica.
+
+Estructura Interna:
+    - `gsd_cm_per_px`: cm/píxel a partir de sensor/altura/focal/ancho.
+    - `density_per_ha`: plantas por hectárea a partir de conteo y área.
+    - `geodesic_area_m2`: área (m²) de un anillo [lon, lat] sobre la esfera.
+
+Entradas / Dependencias:
+    - `math` (biblioteca estándar).
+
+Salidas / Efectos:
+    - Ninguno; funciones puras.
+
+Ejemplo de Integración:
+    from backend.core.geometry import gsd_cm_per_px, density_per_ha, geodesic_area_m2
+"""
+
+from __future__ import annotations
+
+import math
+
+_EARTH_RADIUS_M: float = 6_378_137.0  # radio ecuatorial WGS84
+SQUARE_METERS_PER_HECTARE: int = 10_000
+
+
+def gsd_cm_per_px(
+    sensor_w_mm: float, flight_h_m: float, focal_mm: float, img_w_px: float
+) -> float:
+    """
+    Calcula la distancia de muestreo terrestre (GSD) en centímetros por píxel.
+
+    Args:
+        sensor_w_mm (float): Ancho del sensor en milímetros.
+        flight_h_m (float): Altura de vuelo en metros.
+        focal_mm (float): Distancia focal en milímetros.
+        img_w_px (float): Ancho de la imagen en píxeles.
+
+    Returns:
+        float: GSD en cm/px; 0.0 si focal o ancho son 0.
+    """
+    denom = focal_mm * img_w_px
+    if denom == 0:
+        return 0.0
+    return (sensor_w_mm * flight_h_m) / denom * 100
+
+
+def density_per_ha(count: int, area_m2: float) -> float:
+    """
+    Calcula la densidad de plantas por hectárea.
+
+    Args:
+        count (int): Número de plantas detectadas.
+        area_m2 (float): Área de la parcela en metros cuadrados.
+
+    Returns:
+        float: Plantas por hectárea; 0.0 si el área es 0.
+    """
+    if area_m2 <= 0:
+        return 0.0
+    return count / (area_m2 / SQUARE_METERS_PER_HECTARE)
+
+
+def geodesic_area_m2(coords: list[list[float]]) -> float:
+    """
+    Calcula el área geodésica (m²) de un anillo de coordenadas [lon, lat].
+
+    Usa la fórmula estándar de área de un polígono sobre la esfera (la misma de la
+    librería de geometría de Google Maps). El resultado es el valor absoluto, por lo
+    que no depende del sentido de giro.
+
+    Args:
+        coords (list[list[float]]): Vértices [lon, lat] en grados (anillo cerrado o no).
+
+    Returns:
+        float: Área en metros cuadrados (>= 0).
+    """
+    if len(coords) < 3:
+        return 0.0
+    total = 0.0
+    n = len(coords)
+    for i in range(n):
+        lon1, lat1 = coords[i]
+        lon2, lat2 = coords[(i + 1) % n]
+        total += math.radians(lon2 - lon1) * (
+            2 + math.sin(math.radians(lat1)) + math.sin(math.radians(lat2))
+        )
+    return abs(total * _EARTH_RADIUS_M * _EARTH_RADIUS_M / 2.0)

backend/core/ndvi.py

@@ -0,0 +1,98 @@
+"""
+Archivo: ndvi.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Motor NDVI **puro** (Fase 1), aislado de toda I/O para poder probar la matemática
+con arrays sintéticos. Incluye el cálculo vectorizado del índice, la estadística
+zonal (media/mín/máx sobre una máscara) y la agregación temporal **mensual** (un
+punto por mes, la escena de menor nubosidad), usada por el flujo de 5 años.
+
+Acciones Principales:
+    - Calcula NDVI por píxel, agrega estadística zonal y resume por mes.
+
+Estructura Interna:
+    - `ndvi`: índice normalizado de vegetación, vectorizado y seguro ante /0.
+    - `zonal_stats`: media/mín/máx sobre los píxeles de la máscara.
+    - `aggregate_monthly`: reduce una serie a 1 punto/mes (menor `cloud_cover`).
+
+Entradas / Dependencias:
+    - `numpy`.
+
+Salidas / Efectos:
+    - Ninguno; funciones puras.
+
+Ejemplo de Integración:
+    from backend.core.ndvi import ndvi, zonal_stats, aggregate_monthly
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def ndvi(nir: np.ndarray, red: np.ndarray) -> np.ndarray:
+    """
+    Calcula el NDVI vectorizado evitando la división por cero.
+
+    Args:
+        nir (np.ndarray): Reflectancia en el infrarrojo cercano (Banda 8).
+        red (np.ndarray): Reflectancia en el rojo visible (Banda 4).
+
+    Returns:
+        np.ndarray: NDVI por píxel; 0.0 donde NIR+Red == 0.
+    """
+    nir = nir.astype(float)
+    red = red.astype(float)
+    denom = nir + red
+    # `where` evita la división por cero sin emitir RuntimeWarning (np.where evaluaría
+    # ambas ramas y dispararía el aviso); las posiciones con denom == 0 quedan en 0.0.
+    return np.divide(nir - red, denom, out=np.zeros_like(denom), where=denom != 0)
+
+
+def zonal_stats(ndvi_arr: np.ndarray, mask: np.ndarray) -> dict[str, float]:
+    """
+    Calcula la estadística zonal (media/mín/máx) sobre los píxeles de la máscara.
+
+    Args:
+        ndvi_arr (np.ndarray): Array de NDVI por píxel.
+        mask (np.ndarray): Máscara booleana de los píxeles dentro de la parcela.
+
+    Returns:
+        dict[str, float]: Claves 'mean_ndvi', 'min_ndvi', 'max_ndvi'.
+    """
+    values = ndvi_arr[mask]
+    return {
+        "mean_ndvi": float(values.mean()),
+        "min_ndvi": float(values.min()),
+        "max_ndvi": float(values.max()),
+    }
+
+
+def aggregate_monthly(series: list[dict]) -> list[dict]:
+    """
+    Reduce una serie de observaciones a un punto por mes (la de menor nubosidad).
+
+    La fecha de cada punto resultante se normaliza al primer día del mes
+    (`AAAA-MM-01`) para coincidir con el `UNIQUE(field_id, date)` del esquema.
+
+    Args:
+        series (list[dict]): Observaciones con claves 'date' (ISO) y 'cloud_cover'.
+
+    Returns:
+        list[dict]: Observaciones mensuales ordenadas cronológicamente.
+    """
+    best_per_month: dict[str, dict] = {}
+    for point in series:
+        month_key = str(point["date"])[:7]  # 'AAAA-MM'
+        cloud = point.get("cloud_cover")
+        current = best_per_month.get(month_key)
+        cloud_value = cloud if cloud is not None else float("inf")
+        current_cloud = (
+            current.get("cloud_cover") if current and current.get("cloud_cover") is not None
+            else float("inf")
+        )
+        if current is None or cloud_value < current_cloud:
+            best_per_month[month_key] = {**point, "date": f"{month_key}-01"}
+    return [best_per_month[key] for key in sorted(best_per_month)]

backend/core/schemas.py

@@ -0,0 +1,108 @@
+"""
+Archivo: schemas.py (core/dominio)
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Esquemas de dominio de la plataforma completa (Fase 1). Modelan las entidades
+geoespaciales y analíticas con sus invariantes: una parcela (`FieldIn`/`FieldOut`)
+lleva un polígono GeoJSON validado (anillo cerrado, EPSG:4326); un punto NDVI vive
+en [-1, 1]; un mensaje de chat solo admite los roles 'user' o 'assistant'. Validar
+aquí evita insertar geometría o índices inválidos en PostGIS.
+
+Acciones Principales:
+    - Declara los contratos de dominio compartidos por servicios, repos y API.
+
+Estructura Interna:
+    - `FieldIn` / `FieldOut`: alta y lectura de parcelas.
+    - `NDVIPoint`: observación de la serie temporal NDVI.
+    - `WeatherPoint`: observación agroclimática diaria/mensual.
+    - `ChatMessage`: turno de la memoria conversacional.
+
+Entradas / Dependencias:
+    - `pydantic`.
+
+Salidas / Efectos:
+    - Ninguno; expone modelos de validación/serialización.
+
+Ejemplo de Integración:
+    from backend.core.schemas import FieldIn
+    parcela = FieldIn(name="Lote A", geojson={"type": "Polygon", "coordinates": [...]})
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class FieldIn(BaseModel):
+    """Datos de alta de una parcela: nombre + polígono GeoJSON (EPSG:4326)."""
+
+    name: str = Field(min_length=1, description="Nombre legible de la parcela")
+    geojson: dict = Field(description="Geometría GeoJSON tipo Polygon en EPSG:4326")
+
+    @field_validator("geojson")
+    @classmethod
+    def _validar_poligono(cls, value: dict) -> dict:
+        """
+        Verifica que la geometría sea un Polygon con un anillo cerrado y >=4 vértices.
+
+        Args:
+            value (dict): Geometría GeoJSON propuesta.
+
+        Returns:
+            dict: La misma geometría si es válida.
+
+        Raises:
+            ValueError: Si no es Polygon, el anillo no está cerrado o tiene <4 vértices.
+        """
+        if value.get("type") != "Polygon":
+            raise ValueError("La geometría debe ser de tipo 'Polygon'.")
+        coordinates = value.get("coordinates") or []
+        if not coordinates or not coordinates[0]:
+            raise ValueError("El polígono no tiene coordenadas.")
+        ring = coordinates[0]
+        if len(ring) < 4:
+            raise ValueError("El anillo del polígono requiere al menos 4 vértices.")
+        if ring[0] != ring[-1]:
+            raise ValueError("El polígono debe estar cerrado (primer punto == último).")
+        return value
+
+
+class FieldOut(BaseModel):
+    """Representación de lectura de una parcela persistida."""
+
+    id: str = Field(description="Identificador único (UUID) de la parcela")
+    name: str = Field(description="Nombre legible de la parcela")
+    area_ha: float | None = Field(default=None, ge=0, description="Área en hectáreas (PostGIS)")
+
+
+class NDVIPoint(BaseModel):
+    """Observación de la serie temporal de NDVI (una fecha)."""
+
+    date: dt.date = Field(description="Fecha de la escena (o primer día del mes si es mensual)")
+    mean_ndvi: float = Field(ge=-1, le=1, description="NDVI medio zonal en [-1, 1]")
+    min_ndvi: float | None = Field(default=None, ge=-1, le=1)
+    max_ndvi: float | None = Field(default=None, ge=-1, le=1)
+    cloud_cover: float | None = Field(default=None, ge=0, le=100, description="% de nubes")
+    source: str = Field(default="sentinel2", description="Origen de la observación")
+
+
+class WeatherPoint(BaseModel):
+    """Observación agroclimática por fecha (todas las variables son opcionales)."""
+
+    date: dt.date = Field(description="Fecha de la observación")
+    precip_mm: float | None = Field(default=None, ge=0, description="Precipitación (mm)")
+    temp_mean_c: float | None = Field(default=None, description="Temperatura media (°C)")
+    radiation: float | None = Field(default=None, ge=0, description="Radiación de onda corta")
+
+
+class ChatMessage(BaseModel):
+    """Turno de la memoria conversacional del agente RAG."""
+
+    role: Literal["user", "assistant"] = Field(description="Emisor del mensaje")
+    content: str = Field(min_length=1, description="Texto del turno")
+    session_id: str = Field(min_length=1, description="Hilo conversacional")

tests/unit/test_domain_schemas.py

@@ -0,0 +1,73 @@
+"""
+Archivo: test_domain_schemas.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Pruebas unitarias de los esquemas de dominio de la plataforma (Fase 1): validación
+de geometría de parcelas (polígono cerrado EPSG:4326), rango de NDVI y rol del chat.
+
+Ejemplo de Integración:
+    uv run python -m pytest tests/unit/test_domain_schemas.py
+"""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from backend.core.schemas import ChatMessage, FieldIn, NDVIPoint, WeatherPoint
+
+_CLOSED_SQUARE = {
+    "type": "Polygon",
+    "coordinates": [
+        [[-58.0, -34.0], [-58.0, -34.1], [-57.9, -34.1], [-57.9, -34.0], [-58.0, -34.0]]
+    ],
+}
+
+
+def test_field_in_acepta_poligono_cerrado() -> None:
+    """Un polígono con anillo cerrado y >=4 vértices se acepta."""
+    field = FieldIn(name="Lote A", geojson=_CLOSED_SQUARE)
+    assert field.name == "Lote A"
+
+
+def test_field_in_rechaza_poligono_abierto() -> None:
+    """Un anillo cuyo primer punto != último debe rechazarse."""
+    abierto = {
+        "type": "Polygon",
+        "coordinates": [[[-58.0, -34.0], [-58.0, -34.1], [-57.9, -34.1]]],
+    }
+    with pytest.raises(ValidationError):
+        FieldIn(name="x", geojson=abierto)
+
+
+def test_field_in_rechaza_tipo_no_poligono() -> None:
+    """Una geometría que no es Polygon debe rechazarse."""
+    punto = {"type": "Point", "coordinates": [-58.0, -34.0]}
+    with pytest.raises(ValidationError):
+        FieldIn(name="x", geojson=punto)
+
+
+def test_ndvi_point_acepta_rango_valido() -> None:
+    """Un NDVI dentro de [-1, 1] y nubosidad dentro de [0, 100] se acepta."""
+    punto = NDVIPoint(date="2026-04-01", mean_ndvi=0.72, cloud_cover=4.1)
+    assert punto.mean_ndvi == 0.72
+
+
+def test_ndvi_point_rechaza_fuera_de_rango() -> None:
+    """Un NDVI fuera de [-1, 1] dispara ValidationError."""
+    with pytest.raises(ValidationError):
+        NDVIPoint(date="2026-04-01", mean_ndvi=1.5)
+
+
+def test_weather_point_acepta_nulos() -> None:
+    """Las variables climáticas son opcionales (pueden faltar en una fecha)."""
+    punto = WeatherPoint(date="2026-04-01")
+    assert punto.precip_mm is None
+
+
+def test_chat_message_rechaza_rol_invalido() -> None:
+    """Solo se permiten los roles 'user' y 'assistant'."""
+    with pytest.raises(ValidationError):
+        ChatMessage(role="system", content="x", session_id="s1")

tests/unit/test_geometry.py

@@ -0,0 +1,46 @@
+"""
+Archivo: test_geometry.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Pruebas unitarias de las funciones geométricas puras (Fase 1): distancia de muestreo
+terrestre (GSD), densidad por hectárea y área geodésica de un polígono lon/lat.
+
+Ejemplo de Integración:
+    uv run python -m pytest tests/unit/test_geometry.py
+"""
+
+from __future__ import annotations
+
+from backend.core.geometry import density_per_ha, geodesic_area_m2, gsd_cm_per_px
+
+
+def test_gsd_valor_conocido() -> None:
+    """GSD = (sensor*altura)/(focal*ancho)*100; caso redondo -> 10 cm/px."""
+    g = gsd_cm_per_px(sensor_w_mm=10, flight_h_m=100, focal_mm=10, img_w_px=1000)
+    assert g == 10.0
+
+
+def test_density_per_ha_una_hectarea() -> None:
+    """100 plantas en 10.000 m² (1 ha) -> 100 pl/Ha."""
+    assert density_per_ha(100, 10_000) == 100.0
+
+
+def test_density_per_ha_area_cero() -> None:
+    """Área cero no debe dividir por cero; devuelve 0.0."""
+    assert density_per_ha(5, 0) == 0.0
+
+
+def test_geodesic_area_caja_un_grado_cerca_ecuador() -> None:
+    """Una caja de 1°x1° cerca del ecuador mide ~1.23e10 m² (≈12.300 km²)."""
+    box = [[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]
+    area = geodesic_area_m2(box)
+    assert 1.1e10 < area < 1.4e10
+
+
+def test_geodesic_area_independiente_del_sentido() -> None:
+    """El área no depende del sentido de giro del polígono (se toma valor absoluto)."""
+    horario = [[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]
+    antihorario = [[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]
+    assert round(geodesic_area_m2(horario), 2) == round(geodesic_area_m2(antihorario), 2)

tests/unit/test_ndvi.py

@@ -0,0 +1,64 @@
+"""
+Archivo: test_ndvi.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Pruebas unitarias del motor NDVI puro (Fase 1): cálculo vectorizado, evitación de
+división por cero, estadística zonal y agregación mensual (1 punto/mes, menor nube).
+
+Ejemplo de Integración:
+    uv run python -m pytest tests/unit/test_ndvi.py
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from backend.core.ndvi import aggregate_monthly, ndvi, zonal_stats
+
+
+def test_ndvi_valor_conocido() -> None:
+    """NDVI(0.8, 0.2) = (0.8-0.2)/(0.8+0.2) = 0.6."""
+    arr = ndvi(np.array([0.8]), np.array([0.2]))
+    assert round(float(arr[0]), 4) == 0.6
+
+
+def test_ndvi_evita_division_por_cero() -> None:
+    """Cuando NIR+Red = 0, el NDVI debe ser 0.0 (sin error)."""
+    arr = ndvi(np.array([0.0]), np.array([0.0]))
+    assert float(arr[0]) == 0.0
+
+
+def test_zonal_stats_mean_min_max() -> None:
+    """La estadística zonal devuelve media, mínimo y máximo sobre la máscara."""
+    arr = np.array([0.2, 0.4, 0.6])
+    mask = np.array([True, True, True])
+    stats = zonal_stats(arr, mask)
+    assert stats["min_ndvi"] == 0.2
+    assert stats["max_ndvi"] == 0.6
+    assert round(stats["mean_ndvi"], 2) == 0.4
+
+
+def test_aggregate_monthly_elige_menor_nube_por_mes() -> None:
+    """Por cada mes se conserva la escena de menor nubosidad; la fecha se normaliza al día 1."""
+    series = [
+        {"date": "2026-04-03", "mean_ndvi": 0.70, "cloud_cover": 40},
+        {"date": "2026-04-20", "mean_ndvi": 0.80, "cloud_cover": 5},  # mejor de abril
+        {"date": "2026-05-10", "mean_ndvi": 0.60, "cloud_cover": 10},
+    ]
+    out = aggregate_monthly(series)
+    assert len(out) == 2
+    abril = next(p for p in out if p["date"] == "2026-04-01")
+    assert abril["mean_ndvi"] == 0.80
+    assert abril["cloud_cover"] == 5
+
+
+def test_aggregate_monthly_ordena_cronologicamente() -> None:
+    """La salida queda ordenada por fecha ascendente."""
+    series = [
+        {"date": "2026-05-10", "mean_ndvi": 0.6, "cloud_cover": 10},
+        {"date": "2026-04-20", "mean_ndvi": 0.8, "cloud_cover": 5},
+    ]
+    out = aggregate_monthly(series)
+    assert [p["date"] for p in out] == ["2026-04-01", "2026-05-01"]