Sistema de Gestión y Trazabilidad de Donaciones
Trabajo Práctico Anual Integrador — Diseño de Sistemas (K3002) — 2026
DonaTrack es una solución digital desarrollada para UTN Solidaria, orientada a organizar, registrar y monitorear donaciones de bienes materiales desde su recepción en el depósito hasta su entrega a entidades beneficiarias.
La plataforma resuelve los desafíos de gestión y trazabilidad que enfrenta la organización, mejorando la distribución de recursos y fortaleciendo la transparencia frente a donantes y beneficiarios.
El microservicio de Logística se encuentra desplegado de forma independiente en la nube, conectado a una base de datos PostgreSQL en Supabase:
- 🚀 Swagger UI (Producción):
https://donatrack-logistica-50xn.onrender.com/swagger-ui/index.html - 📡 Health Check:
https://donatrack-logistica-50xn.onrender.com/actuator/health - 🗄️ Base de Datos Cloud: PostgreSQL en Supabase (Schema
logistica, Connection Pooler AWS US-East-1)
El sistema está diseñado como una arquitectura distribuida de microservicios:
┌─────────────────────────────────────────────────────────────────────┐
│ DonaTrack Platform │
├──────────────┬──────────────┬──────────────┬───────────────────────┤
│ Donaciones │ Incentivos │ Logística │ Notificaciones │
│ :8000 │ :8001 │ :8002 │ :8003 │
├──────────────┴──────────────┴──────────────┴───────────────────────┤
│ Server / Gateway :8080 │
├────────────────────────────────┬────────────────────────────────────┤
│ PostgreSQL :5432 │ RabbitMQ :5672 │
│ (schemas por servicio) │ (Message Broker) │
├────────────────────────────────┴────────────────────────────────────┤
│ n8n :5678 │
│ (automatización de flujos) │
└─────────────────────────────────────────────────────────────────────┘
Para más detalles sobre puertos, URLs de Swagger y comandos de ejecución, consultá
SERVICIOS.md. Para el detalle del diseño SOA y arquitectura hexagonal, consultádocs/arquitectura.md.
| Capa | Tecnología | Detalle |
|---|---|---|
| Lenguaje | Java 21 | Long-Term Support (LTS) |
| Framework | Spring Boot 3.5 | Spring Data JPA, OpenFeign, Springdoc OpenAPI |
| Build | Maven (multi-módulo) | Gestión centralizada de dependencias en pom.xml padre |
| API Docs | SpringDoc OpenAPI | Swagger UI interactivo por microservicio y unificado |
| Base de Datos | PostgreSQL 15 / Supabase / H2 | Schemas aislados (donaciones, logistica, incentivos, notificaciones) |
| Mensajería | RabbitMQ | Topic Exchanges y colas asíncronas |
| Contenedores | Docker + Docker Compose | Builds multi-stage optimizados para local y Render |
| Despliegue | Render | Docker Web Service en la nube |
| Automatización | n8n | Flujos low-code para difusión en redes sociales |
| Testing | JUnit 5 + Mockito + H2 | Tests unitarios y de persistencia JPA |
| Integrante | Legajo |
|---|---|
| Fernandez Cruz, Mateo | 209.986-0 |
| Hidalgo, Máximo Juan Manuel | 176.585-1 |
El trabajo práctico se construye de manera evolutiva e incremental a lo largo de 6 entregas (según el cronograma oficial de la cátedra):
📅 22 de Mayo
Ver alcance completo
- Servicio de Donaciones — Gestión de Donantes y Donaciones.
- Servicio de Donaciones — Importación masiva de donantes mediante archivo CSV.
- Servicio de Donaciones — Gestión de Entidades Beneficiarias y Necesidades.
- Bocetos de interfaz de usuario.
- Modelado de personas donantes (humanas y jurídicas) con medios de contacto.
- Registro de donaciones con segmentación automática por subcategoría.
- Entidades beneficiarias con necesidades recurrentes y extraordinarias.
- Importación masiva de donantes desde CSV (+10.000 filas).
- Bocetos de las principales interfaces de usuario.
- Modelo del Dominio (diagrama de clases por servicio).
- Diagramas de Arquitectura (despliegue y componentes).
- Justificaciones de Diseño Iniciales.
- Diagrama General de Casos de Uso.
- Bocetos de interfaz de usuario.
- Implementación de los requerimientos.
📅 19 de Junio
Ver alcance completo
- Servicio de Donaciones — Trazabilidad de estados de las donaciones.
- Servicio de Donaciones — Asignación de donaciones a entidades beneficiarias.
- Servicio de Incentivos — Analítica de donantes, misiones e insignias.
- Servicio de Incentivos — Difusión de insignias y ranking mensual.
- Servicio de Notificaciones — Integración con medios de notificación (email, SMS, WhatsApp).
- Exposición REST de los servicios (Parte I).
- Máquina de estados de donaciones (En Depósito → Asignada → Lista para entregar → En traslado → Entregada / Vencida / Entrega fallida).
- Algoritmos de asignación: Compatibilidad Semántica y Prioridad a Sub-atendidos (ejecución asincrónica en horarios de baja carga).
- Sistema de incentivos con categorías (Colaborador, Sostenedor, Transformador), misiones secuenciales e insignias.
- Integración con n8n para publicación automática en redes sociales al obtener insignias.
- Ranking mensual de donantes más activos.
- Servicio de Notificaciones con envío simulado por email, SMS y WhatsApp.
- Eventos de notificación: inactividad de donante (+20 días), asignación de donación, cumplimiento de misión, cambio de categoría.
- Modelo del Dominio (diagrama de clases).
- Diagrama de despliegue y componentes.
- Justificaciones de Diseño y Diagramas Complementarios.
- Implementación de requerimientos.
- Implementación del flujo automatizado de publicación y difusión de insignias (n8n).
📅 3 de Julio
Ver alcance completo
- Servicio de Logística — Flota de camiones, choferes, planificación externa de rutas y trazabilidad de entregas.
- Servicio de Donaciones — Eventos de logística y notificaciones a donantes/entidades.
- Revisión y maduración de Entregas 1 y 2 — Refactorización con patrones de diseño y desacoplamiento.
- Exposición REST & Contenerización — Documentación Swagger completa y Dockerización de cada servicio.
- Flota y Logística: Modelado de camiones (patente, capacidad en volumen m³, altura m, capacidad de carga kg) y choferes con legajo.
- Planificación de Rutas Asíncrona: Integración con componente externo en lotes de hasta 100 donaciones mediante endpoint de Callback (
/api/planificacion/callback). - Trazabilidad de Entregas: Ciclo de vida de la entrega (
Pendiente→En traslado→Entregada/No recibida). - Comprobante de Recepción: Registro de fecha/hora, camión responsable y fotos de la donación recibida.
- Eventos Logísticos: Notificaciones por inicio de ruta con enlace a mapa interactivo, entrega realizada exitosamente con comprobante, y reporte de entregas fallidas con justificación.
- Segmentación clara: Separación entre
DonacionOriginaly donaciones segmentadas (Donacion), delegada mediante fachada (ProcesadorCargaInicial) y Strategy de segmentación. - Necesidades Recurrentes: Modelo temporal con
PeriodoNecesidad(ABIERTA,SATISFECHA) y renovación periódica automática (RenovacionPeriodosJob). - Importador CSV: Detección y actualización de donantes duplicados por email (+10.000 filas) probado con tests unitarios.
- Matchmaking: Asignación con patrón Strategy (
CompatibilidadSemanticayPrioridadASubAtendidos). - Incentivos y Gamificación: Manejo de reset de progreso en misiones por inactividad ("Racha") e impacto directo de donaciones en el progreso.
- Notificaciones: Despacho multicanal con patrón Strategy (
EmailStrategy,SmsStrategy,WhatsAppStrategy).
- Modelo del Dominio: Diagrama de clases por servicio en
diagramas/. - Justificaciones de Diseño: Revisión detallada en
_notas_y_borradores/pendientes/entrega_3/revision_entrega_requerimiento.md. - APIs REST documentadas: Swagger UI interactivo para cada microservicio y colección en
docs/donatrack-api. - Contenerización Docker: Dockerfiles multi-stage por módulo y orquestación con
compose.yaml. - Diagrama de Componentes y Despliegue: Diagrama general de la solución en
diagramas/.
📅 Semana del 14 de Septiembre
Ver alcance completo
- Persistencia Relacional y ORM (JPA / Hibernate) — Mapeo de entidades de dominio de todos los servicios a PostgreSQL con esquemas aislados (
donaciones,logistica,incentivos,notificaciones). - Integración Asíncrona (RabbitMQ) — Publicación y consumo de eventos desacoplados (
donaciones.exchange,logistica.exchange) para notificaciones automáticas y trazabilidad. - Broker de Integración con Logística — Componente
LogisticaBrokerAdaptercon patrón Broker y fallback automático entre servicio remoto en la nube y copia local. - Despliegue del Servicio de Logística en la Nube — Desplegado y operativo en Render con conexión a PostgreSQL en Supabase.
- Documentación de Arquitectura y DER Físicos — Documento explicativo de arquitectura SOA/Hexagonal y diagramas de clases, componentes, despliegue y DER físicos por módulo.
- Migración de todo el modelo de objetos a JPA con estrategias de herencia (
JOINEDpara roles/personas ySINGLE_TABLEpara necesidades). - Aislamiento estricto por schemas PostgreSQL y soporte multi-entorno (
local,prod,testcon H2). - Comunicación asíncrona mediante Topic Exchanges en RabbitMQ para eventos como inicio de ruta, entregas exitosas, cambios de estado y recompensas.
- Patrón Broker en
donatrack-donaciones(LogisticaBrokerAdapter) con cliente Feign hacia la nube y fallback transparente alocalhost:8002. - Despliegue independiente del microservicio
donatrack-logisticaen Render conectado a Supabase.
- Modelo de Clases actualizado:
DonaTrack-Diagrama-Clases-Entrega4.puml. - Modelo de Datos (DER Físicos): Diagramas entidad-relación físicos por servicio en
diagramas/(DER-Donaciones,DER-Logistica,DER-Incentivos,DER-Notificaciones). - Justificaciones de Diseño y Documento de Arquitectura:
docs/arquitectura.md(justificación de arquitectura SOA, hexagonal, capas y patrones). - Diagrama de Componentes y Despliegue:
DonaTrack-Diagrama-Componentes-y-Despliegue-Entrega4.puml. - Implementación de requerimientos de integración: Mensajería con RabbitMQ y Broker de logística con fallback.
- Despliegue del Servicio de Logística: Operativo y accesible vía Swagger en
https://donatrack-logistica-50xn.onrender.com/swagger-ui/index.html.
📅 Semana del 19 de Octubre
Los detalles de esta etapa se actualizarán próximamente.
📅 Semana del 23 de Noviembre
Los detalles de esta etapa se actualizarán próximamente.
# Clonar el repositorio
git clone https://github.com/matefernandezcc/DonaTrack.git
cd DonaTrack
# Compilar todo el proyecto
make build
# Levantar un servicio individual
make donaciones # Puerto 8000
make incentivos # Puerto 8001
make logistica # Puerto 8002
make notificaciones # Puerto 8003
make server # Puerto 8080
# Levantar toda la plataforma con Docker (Postgres, RabbitMQ, n8n y servicios)
docker compose up --build -d📄 Ver
SERVICIOS.mdpara la guía completa de puertos, Swagger y comandos. 📄 Verdocs/arquitectura.mdpara la documentación técnica de arquitectura y diseño.