Una plataforma integral de logística y paquetería para empresas que necesitan gestionar envíos, oficinas, repartidores y políticas de precios de forma centralizada y escalable.
- ¿Qué es LDH?
- Características
- Arquitectura
- Tecnologías
- Requisitos Previos
- Instalación y Configuración
- Estructura del Proyecto
- UI/UX
- Uso
- API Endpoints
- Seguridad
- Base de Datos
- Contribuciones
- Licencia
LDH es una aplicación web full-stack de logística y paquetería diseñada para:
- ✅ Clientes: cotizar envíos, crear pedidos, rastrear paquetes en tiempo real
- ✅ Repartidores: gestionar entregas, actualizar estados, escanear códigos de barras
- ✅ Administradores: paneles de control, gestión de precios, auditoría de operaciones
Centraliza información que típicamente está dispersa en hojas de cálculo y correos electrónicos, garantizando precios coherentes, trazabilidad completa y roles diferenciados.
- Elimina errores manuales al cotizar envíos
- Proporciona historial completo de estados
- Permite configurar precios por zona geográfica con auditoría
- Escalable de desarrollo local (H2) a producción (PostgreSQL/Supabase)
- 🗺️ Localizador de oficinas con mapa interactivo (Leaflet)
- 📦 Cotización en tiempo real según origen, destino, peso y tipo de entrega
- 🔍 Rastreo público de envíos sin necesidad de login
- 💬 Asistente IA (powered by Groq) con respuestas en streaming
- 📱 Responsive y optimizado para móvil
- 📝 Wizard de envío guiado en 4 pasos
- 📋 Mi área de cliente con historial de envíos
- 📥 Descarga de facturas y etiquetas en PDF
- 🎯 Seguimiento detallado de pedidos
- 👥 Gestión de cuenta y datos personales
- 📱 Lista de envíos asignados con filtros
- 📷 Escaneo de códigos de barras con cámara del navegador (ZXing)
- ⏱️ Control de turno (inicio/fin)
- 📍 Actualización de estado con ubicación
- 🔔 Historial de entregas del turno actual
- 📊 Dashboard con KPIs y gráficos en tiempo real
- 📦 Gestión de envíos con auditoría de cambios de estado
- 🏢 Administración de oficinas y sedes
- 👨💼 Gestión de repartidores y cuentas
- 💰 Motor de precios completo:
- Zonas geográficas por código postal
- Matriz de precios origen × destino
- Modificadores por tipo de entrega
- Tramos de peso con tarifas escalonadas
- Export/import de datos en CSV
┌─────────────────────────────────────────────────────────────┐
│ Navegador del Cliente │
└──────────────────────────┬──────────────────────────────────┘
│ HTTPS + JWT
▼
┌─────────────────────────────────────────────────────────────┐
│ Frontend: Astro + React + TypeScript │
│ (Sitio público, wizards, dashboards, mapas, PDF) │
└──────────────────────────┬──────────────────────────────────┘
│ fetch(JSON)
▼
┌─────────────────────────────────────────────────────────────┐
│ Backend: Spring Boot 4.0.5 (Java 21) │
│ API REST JSON │
│ ├─ Seguridad: JWT + roles (CLIENTE, REPARTIDOR, ADMIN) │
│ ├─ Servicios: cotización, envíos, precios, auditoría │
│ ├─ Repositorios: Spring Data JPA │
│ └─ Validación: Bean Validation + custom validators │
└──────────────────────────┬──────────────────────────────────┘
│ SQL
▼
┌─────────────────────────────────────────────────────────────┐
│ Base de Datos (H2 / PostgreSQL) │
│ Usuarios, Envíos, Oficinas, Zonas, Matriz de Precios, │
│ Auditoría, Modificadores de Entrega │
└─────────────────────────────────────────────────────────────┘
- Spring Boot → Ecosistema maduro, JPA/Hibernate, transacciones claras
- Astro + React → Islas de interactividad, excelente rendimiento y SEO
- PostgreSQL → Modelo relacional fuerte, índices, FK, integración con Liquibase
- JWT → API stateless, escalable horizontalmente, sin sesiones en servidor
- Liquibase → Migraciones versionadas y reproducibles
| Tecnología | Propósito |
|---|---|
| Java 21 | Lenguaje base |
| Spring Boot 4.0.5 | Framework web |
| Spring Security + JWT | Autenticación/autorización |
| Spring Data JPA | ORM y persistencia |
| Liquibase | Migraciones versionadas |
| H2 | BD desarrollo/testing |
| PostgreSQL | BD producción |
| Jakarta Validation | Validación de entrada |
| JJWT 0.12.6 | Firma y validación JWT |
| Lombok | Reducir boilerplate |
| Tecnología | Propósito |
|---|---|
| Astro 6.1.8 | Framework web SSR/static |
| React 19 | Componentes interactivos |
| TypeScript | Tipado seguro |
| Tailwind CSS v4 | Utilidad-first styling |
| Leaflet | Mapas OpenStreetMap |
| ZXing | Escaneo códigos de barras |
| jsPDF | Generación PDFs en cliente |
| Recharts | Gráficos en dashboards |
| Lucide React | Iconografía SVG |
- Groq AI → Asistente IA con streaming
- Nominatim (OSM) → Geocoding opcional de oficinas
- Supabase → PostgreSQL gestionado (alternativa)
- Java 21 o superior
- Node.js 22+ (recomendado nvm)
- Maven 3.9+
- Git
- Opcional: Docker para PostgreSQL si usas Supabase en local
Copiar plantilla y adaptar:
cp backend/env.supabase.example backend/.envPara desarrollo local (H2 por defecto):
JWT_SECRET=tu-clave-secreta-super-fuerte-minimo-32-caracteres
JWT_EXPIRATION_MS=86400000Para producción (PostgreSQL/Supabase):
SPRING_PROFILES_ACTIVE=supabase
DB_URL=jdbc:postgresql://host:5432/database
DB_USER=user
DB_PASSWORD=password
GROQ_API_KEY=tu-clave-groq-opcional
LDH_CORS_ALLOWED_ORIGINS=https://tudominio.comgit clone https://github.com/Ennhila/ldh.git
cd ldhcd backend
# Compilar
mvn clean package -DskipTests
# Ejecutar (H2 por defecto)
mvn spring-boot:runEl servidor estará disponible en: http://localhost:8080
La consola H2 (desarrollo): http://localhost:8080/h2-console
cd ../frontend
# Instalar dependencias
npm install
# Ejecutar en desarrollo
npm run devEl sitio estará disponible en: http://localhost:3000
Backend: crear backend/.env
JWT_SECRET=dev-secret-32-chars-minimun-here-ok
JWT_EXPIRATION_MS=86400000
GROQ_API_KEY=gsk_... # opcional para chat IAFrontend: actualizar .env (si aplica)
PUBLIC_API_URL=http://localhost:8080ldh/
├── backend/ # API REST Spring Boot
│ ├── src/
│ │ ├── main/
│ │ │ ├── java/com/ldh/
│ │ │ │ ├── config/ # Configuración seguridad, JWT, Bootstrap
│ │ │ │ ├── domain/ # Entidades JPA
│ │ │ │ ├── repository/ # Spring Data JPA
│ │ │ │ ├── service/ # Lógica de negocio
│ │ │ │ ├── security/ # JWT, autenticación
│ │ │ │ ├── validation/ # Validadores custom
│ │ │ │ ├── web/ # REST Controllers + DTOs
│ │ │ │ └── geocoding/ # Nominatim integration
│ │ │ └── resources/
│ │ │ ├── application.properties
│ │ │ ├── application-supabase.properties
│ │ │ └── db/changelog/ # Liquibase migrations
│ │ └── test/
│ ├── pom.xml # Dependencias Maven
│ └── .gitignore
│
├── frontend/ # Sitio Astro + React
│ ├── src/
│ │ ├── pages/ # Rutas Astro (.astro)
│ │ ├── layouts/ # Layouts compartidos
│ │ ├── components/ # Componentes React (.tsx)
│ │ ├── lib/ # Utilidades, helpers, API
│ │ └── styles/ # CSS global
│ ├── package.json
│ ├── astro.config.mjs
│ ├── tsconfig.json
│ └── .gitignore
│
├── PROJECT_REPORT.md # Informe técnico detallado
└── README.md # Este archivo
config/→ Seguridad JWT, CORS, Bootstrap de datos inicialesdomain/→ Modelos JPA (User, Envio, Oficina, ShippingZone, PriceMatrixCell…)service/→ Lógica de negocio (cotización, envíos, auditoría, precios)repository/→ Acceso a datos con Spring Data JPAweb/→ REST controllers y DTOs para cada dominiosecurity/→ JWT, autenticación, Custom UserDetails
pages/→ Rutas públicas, autenticación, área cliente, admin, repartidorcomponents/→ Widgets React reutilizables (forms, dashboards, mapas, chat)lib/→ API wrappers, helpers de validación, exportación PDF, hooks
-
Home Page
-
Oficinas
-
Sigue un envio
-
Login
-
Signup
-
Paso 1
-
Paso 2
-
Paso 3
-
Paso 4
-
Paso 5
-
Paso 6
-
Factura factura
-
Shipment Label Shipment Label
-
Dashboard
-
Oficinas
-
Repartidor
-
Envios
-
Zonas Graph
-
Matriz de Precios -- Oficina a Oficina
-- Domicilio a Domicilio
-- Modificadores de entrega
-
Envios Activo
-
Entregados e incidencias
-
Inico
-
Mis envios
-
Seguimiento
-
Oficinas
- Ir a
/envio/paso-1 - Seleccionar origen/destino (CP español o internacional)
- Peso y dimensiones
- Tipo de entrega (oficina/domicilio)
- Revisar cotización y datos destinatario
- Confirmar → pago simulado → ¡éxito!
- Ir a
/seguimiento - Ingresar número de tracking (p.ej.
LDH-XXXX-YYYY) - Ver timeline de estados en tiempo real
- Login como admin
- Ir a
Admin→Precios - Zonas: crear/editar áreas geográficas
- Matriz: configurar precios por par origen × destino
- Modificadores: ajustar tarifa por tipo entrega
- Export CSV para análisis externo
- Login como repartidor
Repartidor→Mis Envíos- Escanear código de barras con cámara
- Actualizar estado (ENTREGADO, EXCEPCIÓN…)
- Finalizar turno
| Método | Endpoint | Descripción |
|---|---|---|
GET |
/api/public/oficinas |
Lista todas las sedes |
GET |
/api/public/envios/track/{tracking} |
Rastreo público |
GET |
/api/public/pricing/delivery-types |
Tipos entrega disponibles |
POST |
/api/public/pricing/quote |
Cotización |
POST |
/api/public/chat/stream |
Chat IA (SSE streaming) |
| Método | Endpoint | Descripción |
|---|---|---|
POST |
/api/auth/register |
Registro cliente |
POST |
/api/auth/login |
Login (devuelve JWT) |
GET |
/api/auth/me |
Datos usuario actual |
| Método | Endpoint | Descripción |
|---|---|---|
GET |
/api/client/envios |
Mis envíos |
POST |
/api/client/envios |
Crear envío |
GET |
/api/client/envios/{id}/checkout-snapshot |
Factura/recibo |
| Método | Endpoint | Descripción |
|---|---|---|
GET |
/api/repartidor/envios |
Envíos asignados |
PATCH |
/api/repartidor/envios/{id}/status |
Actualizar estado |
POST |
/api/repartidor/shift/start |
Iniciar turno |
POST |
/api/repartidor/shift/end |
Finalizar turno |
| Sección | Método | Endpoint | Descripción |
|---|---|---|---|
| Dashboard | GET |
/api/admin/dashboard/stats |
KPIs |
GET |
/api/admin/dashboard/charts |
Series gráficos | |
| Envíos | GET |
/api/admin/envios |
Todos los envíos |
PATCH |
/api/admin/envios/{id}/status |
Cambiar estado + auditoría | |
GET |
/api/admin/envios/{id}/audit |
Historial cambios | |
| Oficinas | GET |
/api/admin/oficinas |
Lista sedes |
POST / PUT / DELETE |
/api/admin/oficinas |
CRUD sedes | |
| Repartidores | GET |
/api/admin/repartidores |
Lista repartidores |
POST / PUT / DELETE |
/api/admin/repartidores |
CRUD repartidores | |
| Precios | GET |
/api/admin/prices/zones |
Zonas |
POST / PUT / DELETE |
/api/admin/prices/zones |
CRUD zonas | |
GET |
/api/admin/prices/matrix |
Matriz células | |
PATCH |
/api/admin/prices/matrix/cells/{id} |
Editar precio célula | |
POST |
/api/admin/prices/matrix/bulk |
Crear múltiples células | |
GET |
/api/admin/prices/matrix/export.csv |
Descargar CSV | |
GET |
/api/admin/prices/delivery-modifiers |
Modificadores tipo entrega |
Ver PROJECT_REPORT.md para detalles de cuerpos de request/response.
- Token emitido tras login exitoso
- Cabecera:
Authorization: Bearer <token> - Validez: configurable (default 24 horas)
- Secreto: mínimo 32 caracteres
| Rol | Acceso |
|---|---|
| CLIENTE | Área cliente, crear/consultar propios envíos |
| REPARTIDOR | Panel repartidor, actualizar estados |
| ADMIN | Paneles administrativos completos |
- Bean Validation con anotaciones (
@NotBlank,@Email,@Size…) - Validadores custom: CP español, contraseña fuerte, email realista
- GlobalExceptionHandler: respuestas JSON coherentes en errores
- Configurable por entorno (
LDH_CORS_ALLOWED_ORIGINS) - Localhost permitido por defecto en desarrollo
- Whitelist en producción obligatoria
- Motor de cotización reside en servidor (no confiable en cliente)
- Endpoint público
/api/public/pricing/quotedevuelve precio calculado desde BD - Nota: Para máxima seguridad, considerar recalcular y validar precio al crear envío en v2
mvn spring-boot:run
# BD en memoria, se limpia cada arranque
# Datos iniciales via Liquibase + DataInitializerAcceder a consola H2: http://localhost:8080/h2-console
- JDBC URL:
jdbc:h2:mem:ldh - User:
sa - Password: (vacío)
export SPRING_PROFILES_ACTIVE=supabase
mvn spring-boot:runConfigurar en application-supabase.properties o variables de entorno:
spring.datasource.url=jdbc:postgresql://host:5432/db
spring.datasource.username=user
spring.datasource.password=pwd
spring.jpa.hibernate.ddl-auto=validateTodos los cambios de esquema versionados en:
backend/src/main/resources/db/changelog/
├── db.changelog-master.xml
├── changes/
│ ├── 001-initial-schema.xml # Tablas base
│ ├── 004-pricing-schema.xml # Zonas, matriz, precios
│ ├── 005-envio-checkout-snapshot.xml # Snapshot facturas
│ └── 006-envio-audit-exception.xml # Auditoría estados
Flujo típico:
- Cambio en entidad JPA
- Crear archivo
changes/NNN-descripcion.xmlen Liquibase - Incluir en
db.changelog-master.xml - Migración automática al arrancar
- Tipado fuerte esencial en dominios financieros (precios, cálculos)
- Ecosistema JPA/Hibernate → modelo relacional sólido
- Transacciones declarativas con
@Transactional - Estándar en equipos empresariales
- Astro: rendimiento, SSR, SEO, contenido estático por defecto
- Islas React: interactividad solo donde es necesaria
- Carga inicial rápida sin overhead de SPA global
- Relacional fuerte (FK, índices, integridad)
- Matriz de precios requiere joins complejos
- Mejor soporte para GIS, tipos avanzados, cloud moderno
- Test de smoke (
BackendApplicationTests) para contexto Spring
# Backend: tests unitarios/integración
mvn test
# Frontend: tests componentes
npm run testPROJECT_REPORT.md→ Informe técnico detallado (arquitectura, bugs enfrentados, timeline, todas las clases)- Javadoc (backend) → Generar con
mvn javadoc:javadoc - Storybook (frontend) → Considerado para v2
| Problema | Causa | Solución |
|---|---|---|
UnknownHostException Supabase |
Host IPv6 vs IPv4 | Usar Session Pooler IPv4 + usuario postgres.PROJECT |
| CORS rechaza API desde otro dominio | Headers faltantes | Configurar LDH_CORS_ALLOWED_ORIGINS |
| Escaneo no encuentra envío | Guiones inconsistentes | Normalización alfanumérica en cliente |
| Pantalla éxito "cargando" indefinido | Hidratación SSR/async | Ajuste estado inicial + finally en fetch |
- ✅ MVP actual → Funcionalidad core completa
- 📋 v2 planeada:
- Tests automatizados ampliados
- Rate limiting endpoints públicos
- Observabilidad: Actuator + métricas
- Recalcular precio en servidor (mayor seguridad)
- Integración SMS/email notificaciones
- Aplicación móvil nativa (React Native)
- Integraciones ecommerce (Shopify, WooCommerce)
Las contribuciones son bienvenidas. Por favor:
- Fork el repositorio
- Branch para tu feature (
git checkout -b feature/tu-caracteristica) - Commit cambios (
git commit -am 'Añadir característica') - Push al branch (
git push origin feature/tu-caracteristica) - Pull Request con descripción clara
- Backend: Java + Spring conventions, Lombok, records para DTOs
- Frontend: TypeScript strict, Astro + React, Tailwind utilities
- BD: Liquibase para todas las migraciones
- Commits: mensajes descriptivos en inglés o español
Distribuido bajo licencia MIT. Ver LICENSE para detalles.
- Issues: Reportar bugs en la sección de Issues
- Discussions: Preguntas y propuestas en Discussions
- Email: ennhila78@gmail.com
- Spring Boot Team → Framework robusto
- Astro Community → Herramienta de frontend moderna
- Groq → API IA rápida
- OpenStreetMap / Nominatim → Datos geográficos abiertos
Hecho con ❤️ para empresas de logística que necesitan control.