~/projects/agro-plus

Agro+

Terminado

Backend de gestión agrícola para productores comerciales colombianos: registro de fincas, lotes y ciclos de cultivo, con seguridad por propietario y catálogo agronómico controlado.

RepositorioAPI en vivo

status --brief

Resumen técnico

Rol
Desarrollador backend del proyecto: diseño de API REST, seguridad, persistencia, reglas de negocio y despliegue.
Arquitectura
Arquitectura por capas (Controller -> Service -> Repository -> Entity), con DTOs que desacoplan el contrato de la API del modelo de persistencia. Validación de propiedad en cascada a través de relaciones anidadas (Lote -> Finca -> Agricultor).
Datos
PostgreSQL gestionado en Supabase para el entorno desplegado y PostgreSQL 15 con Docker para desarrollo local. Persistencia con Spring Data JPA / Hibernate, fetch LAZY explícito y límites transaccionales (@Transactional) para evitar LazyInitializationException.

stack --project

Stack principal

Java 25Spring Boot 4Spring SecurityJWTSpring Data JPA / HibernatePostgreSQLDockerRender

cat features.md

Funcionalidades implementadas

  • Autenticación JWT (registro/login)
  • Gestión de fincas y lotes con seguridad por propietario
  • Catálogo agronómico fijo: tipos de cultivo, variedades y etapas fenológicas
  • Ciclo de cultivo con avance de etapas estrictamente secuencial (sin saltos ni retrocesos)
  • Manejo centralizado de errores con códigos HTTP semánticamente correctos (404/403/409)
  • Seed de datos idempotente para evitar duplicados al reiniciar la aplicación

api routes --public-contract

Endpoints documentados

POST/api/auth/register

Registra un nuevo agricultor y devuelve un JWT.

POST/api/auth/login

Autentica y devuelve un JWT.

POST/api/fincas

Crea una finca asociada al agricultor autenticado.

GET/api/fincas

Lista las fincas del agricultor autenticado.

POST/api/lotes

Crea un lote validando propiedad de la finca.

GET/api/lotes

Lista los lotes del agricultor autenticado.

POST/api/registroCultivo

Inicia un ciclo de cultivo, asignando la etapa inicial automáticamente.

PATCH/api/registroCultivo/{id}/avanzar-etapa

Avanza el cultivo a la siguiente etapa fenológica.

GET/api/catalogos/cultivos

Lista los tipos de cultivo disponibles en el catálogo del sistema.

GET/api/catalogos/cultivos/{cultivoId}/variedades

Lista variedades de un cultivo, con distancia de siembra y densidad.

GET/api/catalogos/cultivos/{cultivoId}/etapas

Lista etapas fenológicas de un cultivo en orden secuencial.

audit security

Seguridad

JWT + Spring Security, contraseñas con BCrypt, autorización por propiedad de recurso (un agricultor solo accede a sus propios datos, validado en cascada), y manejo centralizado de excepciones que evita fugas de información en los errores.

test evidence

Pruebas

Verificación manual exhaustiva con Postman durante todo el desarrollo: casos de éxito, errores, ownership y reglas de negocio. Pruebas automatizadas planificadas como siguiente paso.

lessons learned

Aprendizajes

  • Arquitectura por capas y separación de responsabilidades en Spring Boot
  • Modelado de relaciones JPA (@ManyToOne) y manejo de fetch LAZY con @Transactional
  • Diseño de manejo de excepciones centralizado con códigos HTTP semánticos
  • Despliegue containerizado con Docker multi-stage build en Render, conectado a PostgreSQL gerenciado (Supabase)

roadmap next

Siguientes mejoras

  • Calculadora de capacidad de siembra (área -> cantidad estimada de plantas)
  • Integración del módulo de IA (asistente contextual, diagnóstico por visión computacional) como microservicio separado
  • Pruebas automatizadas con JUnit