CERESAT — Guía de uso

Guía didáctica de la aplicación. Explica, paso a paso, qué consigue cada acción y qué ocurre al pulsar cada botón o elemento de la interfaz. Para saber qué es CERESAT, consulta la Introducción; para la tecnología, la ficha de Tecnología.

Los acrónimos se explican al pie la primera vez que aparecen. Los nombres de botones se muestran «entre comillas angulares».

1. Cómo leer este manual#

Cada apartado sigue el mismo esquema:

• Para qué sirve — el objetivo del usuario.
• Cómo se hace — los pasos en la interfaz.
• Qué ocurre por debajo — el endpoint que se invoca y su efecto.

El icono 🔽 indica un menú desplegable; 🗺️, una acción sobre el mapa.

2. Acceso a la aplicación#

2.1 Registro#

Para qué sirve: crear una cuenta.

Cómo se hace: en /login, pestaña «Register», introducir email y contraseña y pulsar «Registrarse».

Qué ocurre por debajo: el registro lo gestiona directamente Supabase Auth² desde el navegador (no pasa por un endpoint propio de CERESAT). Supabase envía un correo de confirmación. Además, el sistema avisa al administrador de la nueva alta.

Importante — doble puerta de acceso: registrarse no da acceso inmediato. Hacen falta dos pasos: (1) confirmar el email pulsando el enlace del correo, y (2) que el administrador apruebe la cuenta (se activa una prueba gratuita de 3 meses). Hasta completar ambos, al iniciar sesión se verá el aviso «cuenta pendiente de aprobación».

2.2 Inicio de sesión#

Cómo se hace: pestaña «Login», email y contraseña, «Iniciar Sesión».

Qué ocurre por debajo: Supabase valida las credenciales y emite un token JWT³. El navegador lo guarda en una cookie que las páginas de CERESAT usan para autenticar. Si la cuenta está aprobada y vigente, se redirige a /dashboard.

Casos de aviso:

• «pendiente de aprobación» — email confirmado pero el administrador aún no ha aprobado.

• «acceso caducado» — la suscripción venció; aparece el botón «Renovar acceso» que lleva a /billing (ver §12).

2.3 Recuperar contraseña#

Pestaña «Forgot» → introducir email → Supabase envía un enlace de restablecimiento.

3. El panel principal (/dashboard)#

Al entrar se muestra un mapa a pantalla completa con las parcelas de la cuenta y una barra de herramientas superior.

Qué ocurre por debajo al cargar: el navegador pide GET /api/parcels (lista de parcelas) y las dibuja sobre el mapa. Las notas, tareas y alertas se cargan como capas independientes.

3.1 La barra de herramientas#

De izquierda a derecha:

• Botón «✚» (Crear nuevo) 🔽 — siempre visible. Al pulsarlo despliega un menú con tres grupos (píldoras):

  • Operaciones: «📝 Nota», «🔧 Tarea», «⚠️ Alerta».
  • Parcelas: «🟩 Parcela (AOI⁴)», «🌞 Temporada», «🏞️ Unidad Territorial (UT)».
  • «📋 Informe» (píldora destacada en rojo). Cada opción abre su formulario. (Detalle de cada uno en los apartados siguientes.)

• Botón «⚙️» (colapsar barra) — oculta/muestra el resto de herramientas con una transición suave, para ganar espacio de mapa.

• Botón «🔍» (Buscar herramienta) — abre un panel lateral con la lista de todas las herramientas; se cierra al pulsar fuera.

• Botón «🌤️» (Datos AEMET⁵) — abre el modal de meteorología (ver §9).

3.2 El mapa#

Sobre el mapa se puede: hacer zoom, buscar una dirección (geocodificador), localizar la posición, ver un minimapa, entrar en pantalla completa, y activar/desactivar capas (parcelas, notas, tareas, alertas) desde el control de capas.

4. Crear una parcela (AOI)#

Una parcela es el área de interés sobre la que CERESAT calcula todo. Hay cuatro formas de crearla; todas abren el mismo formulario final (nombre, cultivo, etc.).

4.1 Dibujar en el mapa 🗺️#

Cómo se hace: «✚» → «Parcela (AOI)» → herramienta de dibujo → trazar el polígono → confirmar.

Qué ocurre por debajo: POST /api/parcels con la geometría GeoJSON⁶ dibujada. La superficie y el centroide se calculan automáticamente en la base de datos.

Aviso: dibujar áreas muy grandes (más de ~20 ha) a mano puede dar problemas de rendimiento. Para parcelas grandes es preferible el clic sobre el Catastro (§4.2).

4.2 Clic en el mapa (parcela catastral real) 🗺️#

Para qué sirve: obtener la geometría exacta de una parcela del Catastro sin dibujarla.

Cómo se hace: en el formulario de parcela, «📍 Seleccionar en el mapa» → hacer clic sobre la parcela deseada.

Qué ocurre por debajo: POST /api/parcels/from-point envía el punto; el servidor consulta el Catastro⁷ (servicio WFS⁸ INSPIRE), obtiene la parcela real y guarda su referencia catastral. Tarda 1-5 segundos (depende del Catastro).

4.3 Por referencia catastral#

«✚» → «Parcela (AOI)» → introducir la referencia catastral → el sistema resuelve la geometría vía POST /api/parcels/from-refcat.

4.4 Subir un archivo#

Subir un fichero vectorial (GeoJSON, shapefile⁹ comprimido en ZIP, o KML¹⁰) mediante POST /api/parcels/from-file. El sistema lo parsea y reproyecta a coordenadas geográficas.

5. El panel lateral de la parcela (AOI)#

Al seleccionar una parcela en el mapa se abre un panel lateral con su información y acciones. De arriba abajo:

• Cabecera: nombre, superficie, cultivo, referencia catastral (editable con «💾»).

• Píldoras de temporada y de UT (en verde): la temporada activa/anterior y las unidades territoriales a las que pertenece.

• Tres botones de acceso (cada uno de un color):

  • «📊 Ver ficha completa» (verde) → abre /parcel/{id}, la página completa de la parcela.
  • «📋 Crear informe» (rojo) → abre el flujo de informe con esta parcela ya seleccionada (ver §8).
  • «🌤️ Ver meteo» (azul) → abre el modal de meteorología con esta parcela ya precargada.

• Botones «📝 Nota / 🔧 Tarea / ⚠️ Alerta»: crean el elemento correspondiente asociado a esta parcela.

• Listas con desplazamiento de las notas, tareas y alertas de la parcela.

6. Notas, tareas y alertas#

Son los tres tipos de anotación georreferenciada. Se crean desde el botón «✚» (grupo Operaciones) o desde el panel de la parcela.

Cómo se crean: al elegir el tipo, se abre un formulario (título, descripción, prioridad, fecha…) y opcionalmente se marca su posición en el mapa. Al guardar, se invoca POST /api/tasks (los tres tipos comparten la tabla, distinguidos por un campo type).

6.1 Los carruseles#

Las notas, tareas y alertas se muestran en carruseles¹³ de tarjetas (una fila deslizable horizontalmente por tipo), con un contador y un buscador.

• Cada tarjeta muestra un icono de estado: ☐ (abierta) o ✅ (hecha).
• Al pulsar una tarjeta se abre un popup de detalle unificado, donde se puede marcar como hecha/abierta o borrarla. Al cambiar el estado, los carruseles se recargan.

Qué ocurre por debajo: la lista se obtiene con GET /api/tasks; marcar hecho/abierto es un PATCH /api/tasks/{id}; borrar, DELETE /api/tasks/{id}.

7. Temporadas y cuaderno de campo#

7.1 Temporada#

Para qué sirve: representar una campaña de cultivo en una parcela (siembra, fin previsto, cultivo).

Cómo se hace: «✚» → «Temporada» → elegir parcela y cultivo, fechas → guardar (POST /api/seasons). La primera temporada activa fija el cultivo actual de la parcela.

7.2 Cuaderno de campo#

Para qué sirve: registrar las operaciones realizadas: siembras, riegos, fertilizaciones, tratamientos y cosechas.

Cómo se hace: cada operación tiene su formulario y su endpoint (POST /api/sowings, /api/irrigations, /api/fertilizations, /api/treatments, /api/harvests). El endpoint GET /api/field-notebook devuelve el cuaderno unificado: todas las operaciones de la cuenta en orden cronológico.

7.bis Unidades Territoriales (UT) — solo Pro#

Para qué sirve: agrupar varias parcelas bajo una misma unidad de gestión (por ejemplo, todas las de una finca o de un cliente).

Cómo se hace:

1. «✚» → «Unidad Territorial (UT)» → nombre y descripción → guardar (POST /api/uts).

2. Añadir parcelas a la UT desde su ficha /ut/{id} (PUT /api/uts/{id}/parcels/{parcel_id}) o quitarlas (DELETE ...).

Qué ocurre por debajo: la ficha de la UT (/ut/{id}) muestra el mapa con todas sus parcelas y sus estadísticas agregadas (número de parcelas y superficie total). La creación de UT está reservada al plan Pro; con el plan Básica el botón devuelve un aviso de que es una función Pro.

8. Generar y ver un informe#

Para qué sirve: producir un informe PDF¹¹ de la parcela con mapas de índices, gráficos de evolución y datos meteorológicos, además de un mapa interactivo autocontenido.

Cómo se hace:

1. «✚» → «Informe» (o «Crear informe» desde el panel de la parcela).

2. Elegir la parcela y, opcionalmente, una fecha pasada concreta (esto último solo en plan Pro; el plan Básica genera el informe de la última imagen disponible).

3. Pulsar «Generar».

Qué ocurre por debajo (flujo en dos tiempos):

• El navegador llama a POST /api/parcels/{id}/reports. El servidor hace una comprobación rápida de disponibilidad de imagen y, si hay, encola la generación en segundo plano, devolviendo 202 con un task_id. No genera el informe en la petición (sería demasiado pesado).

• Si no hay imagen para la fecha pedida, responde con la fecha más cercana disponible y ofrece usarla.

• El navegador consulta GET /api/parcels/{id}/reports/tasks/{task_id} cada pocos segundos (polling¹²) hasta que el estado pasa a done. La generación puede tardar de 1 a 30 minutos según la imagen (descarga de bandas Sentinel-2, cálculo de índices, render del PDF).

• Al terminar, el informe queda listado en GET /api/parcels/{id}/reports con un enlace de descarga, y se envía por correo con el PDF y el mapa adjuntos.

Ver el informe: la vista /dashboard/report/view muestra el PDF y el mapa interactivo embebidos. El PDF se descarga con GET /api/reports/download-pdf; el mapa se sirve con GET /api/reports/render-map.

9. Meteorología#

9.1 El modal «Datos AEMET»#

Cómo se abre: botón «🌤️» de la barra, o «Ver meteo» desde el panel de la parcela.

Cómo se usa: elegir una estación (o dejar que se sugieran las más cercanas a la parcela), un rango de fechas, y pulsar «Buscar datos».

Qué ocurre por debajo: se consulta GET /api/meteo/nearest para sugerir estaciones cercanas y GET /api/meteo/stations/{idema}/period para el periodo (que rellena los datos que falten desde AEMET y luego los lee). El resultado se muestra en un recuadro:

• Verde con botón «👁 Ver» si hay registros → lleva a /dashboard-station.
• Rojo si no hay datos o si AEMET devolvió un error (por ejemplo, HTTP 429, demasiadas peticiones).

9.2 El dashboard de estación (/dashboard-station)#

Muestra las series de una estación con gráficos de temperatura, precipitación y humedad, organizados en secciones: «Últimas 24 horas», «Datos periodo» (si se buscó uno) y «7/15 días».

El botón de cuadrícula (disposición de los gráficos): arriba a la derecha hay un selector con dos opciones:

• «🔲 1» — un gráfico por fila, a ancho completo.
• «▦ 3» — tres gráficos por fila (temperatura, precipitación, humedad juntos), aprovechando las pantallas anchas.

En pantallas estrechas (móvil) siempre se fuerza a una columna aunque esté seleccionado «3», para que los gráficos sigan siendo legibles.

Qué ocurre por debajo: los datos vienen de GET /api/meteo/stations/{idema}/hourly (horario) y /daily (diario). El botón de cuadrícula solo cambia la disposición visual (una clase CSS¹⁴), no vuelve a pedir datos.

9.3 Seguimiento de estaciones#

Con el botón de seguimiento se activa el refresco periódico automático de una estación (POST /api/meteo/stations/{idema}/monitoring). Una tarea en segundo plano actualiza cada 3 horas los datos de las estaciones en seguimiento y regenera sus gráficos.

10. Panel de mercado (/market)#

Para qué sirve: consultar la evolución de precios. (En construcción: la estructura está montada, pero las fuentes de precios reales aún no están conectadas.)

Cómo se usa:

1. Elegir el mercado (primer nivel): «🌾 Cultivos», «⚡ Energías» o «🧪 Insumos».

2. Buscar el producto en el combo (el catálogo cambia según el mercado; en cultivos es el catálogo GET /api/crops).

3. Elegir el ámbito (pestañas): «🌍 Internacional», «🇪🇸 Nacional», «📍 Local».

4. Ver las tarjetas de «Último mes» y «Último año».

Actualmente cada gráfico muestra el aviso «Fuente de precios pendiente de conectar». La selección se refleja en la URL (?market=...&crop=...) para poder compartirla.

11. Explorador de datos (/data)#

Para qué sirve: navegar los ficheros de la cuenta (alertas, notas, tareas, cuaderno, parcelas, UTs, informes, facturas) como un árbol de carpetas virtual, sin que existan carpetas físicas — el árbol se construye sobre la base de datos y el almacenamiento.

Cómo se usa: navegar con GET /api/list; ver un fichero con GET /api/file/...; descargar con GET /api/download; descargar una carpeta comprimida con GET /api/zip; borrar con DELETE /api/delete.

12. Cuenta, suscripción y pago#

12.1 Página de cuenta (/account)#

Muestra los datos del perfil y la cuenta (GET /profile): nombre, email, rol, fecha de alta, estado de la suscripción (fecha de expiración) y accesos a cambiar contraseña, modo oscuro y cerrar sesión. El botón «Ver facturación» lleva a /billing.

12.2 Renovar la suscripción (/billing)#

Para qué sirve: contratar o renovar el acceso. Es la única página accesible incluso con la cuenta caducada (para poder renovar).

Cómo se hace (pago por transferencia con verificación manual):

1. Elegir un plan (Básica o Pro; anual o mensual) y pulsar «Pagar».

2. El sistema crea la contratación (POST /api/billing/orders) y muestra los datos de transferencia: IBAN¹⁵, titular e importe, y una referencia única que hay que poner exactamente en el concepto de la transferencia (es lo que permite identificar el pago).

3. Hacer la transferencia desde el banco.

4. Subir el justificante (POST /api/billing/orders/{id}/proof). El administrador recibe un correo con el justificante adjunto y un enlace de activación.

5. Una vez verificado, el acceso se extiende y se recibe un correo de confirmación.

Se pueden tener varias contrataciones abiertas a la vez (renovar por adelantado, subir de nivel): cada una lleva su propia referencia. Al verificarse, los periodos se suman — renovar antes de caducar no pierde los días restantes.

El historial de contrataciones y las facturas se listan en la misma página (GET /api/billing/summary), con descarga por URL firmada.

13. Resumen: qué botón invoca qué#

Glosario (acrónimos)#