🌊 SX Smart-Link

Plataforma de Telemetría IoT para la Industria de Desalinización

📋 Descripción

SX Smart-Link es un MVP de plataforma de monitoreo en tiempo real para equipos industriales de desalinización. Recibe datos de telemetría de sensores IoT, detecta condiciones críticas y visualiza métricas en un dashboard interactivo.

🏗️ Arquitectura

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│                 │     │                 │     │                 │
│   Simulador     │────▶│   Backend       │────▶│   PostgreSQL    │
│   IoT (Java)    │ API │   Spring Boot   │ JPA │   Database      │
│                 │     │                 │     │                 │
└─────────────────┘     └────────┬────────┘     └─────────────────┘
                                 │
                                 │ REST API
                                 ▼
                        ┌─────────────────┐
                        │                 │
                        │   Frontend      │
                        │   React + Vite  │
                        │                 │
                        └─────────────────┘

📁 Estructura del Proyecto

TestingAppSX/
├── docker-compose.yml          # Orquestación de PostgreSQL
├── backend/                    # API Spring Boot
│   ├── pom.xml
│   └── src/main/java/com/sx/smartlink/
│       ├── SmartLinkApplication.java
│       ├── config/CorsConfig.java
│       ├── entity/Telemetria.java
│       ├── dto/TelemetriaDTO.java
│       ├── repository/TelemetriaRepository.java
│       ├── service/TelemetriaService.java
│       └── controller/TelemetriaController.java
├── frontend/                   # Dashboard React
│   ├── package.json
│   ├── vite.config.ts
│   ├── tailwind.config.js
│   └── src/
│       ├── App.tsx
│       ├── components/
│       │   ├── StatusCard.tsx
│       │   ├── PressureChart.tsx
│       │   └── AlertsTable.tsx
│       ├── hooks/useTelemetria.ts
│       ├── services/api.ts
│       └── types/Telemetria.ts
├── simulator/                  # Simulador IoT
│   └── TelemetriaSimulator.java
└── README.md

🚀 Instrucciones de Ejecución

Prerrequisitos

• Docker y Docker Compose instalados
• Java 17+ (JDK)
• Maven 3.8+
• Node.js 18+ y npm

Paso 1: Iniciar PostgreSQL con Docker

# En la raíz del proyecto
docker-compose up -d

# Verificar que el contenedor está corriendo
docker ps

Paso 2: Iniciar el Backend (Spring Boot)

# Navegar al directorio del backend
cd backend

# Compilar y ejecutar
./mvnw spring-boot:run

# O si prefieres:
mvn spring-boot:run

El backend estará disponible en: http://localhost:8080

Endpoints disponibles:

• POST /api/telemetria - Recibir datos de telemetría
• GET /api/telemetria/recientes - Últimos 20 registros
• GET /api/telemetria/alertas - Alertas críticas recientes
• GET /api/telemetria/actual - Último registro
• GET /api/telemetria/health - Health check

Paso 3: Iniciar el Frontend (React)

# En otra terminal, navegar al directorio del frontend
cd frontend

# Instalar dependencias
npm install

# Iniciar el servidor de desarrollo
npm run dev

El dashboard estará disponible en: http://localhost:5173

Paso 4: Ejecutar el Simulador IoT

# En otra terminal, navegar al directorio del simulador
cd simulator

# Ejecutar con Java (Single File Source Code)
java TelemetriaSimulator.java

El simulador enviará datos cada 3 segundos con ~15% de probabilidad de generar anomalías.

🎯 Funcionalidades

Backend

• ✅ API REST para recepción de telemetría
• ✅ Persistencia en PostgreSQL con JPA/Hibernate
• ✅ Detección de alertas críticas (Presión > 65 PSI o Vibración > 4 mm/s)
• ✅ Logging de alertas con prefijo [ALERTA CRÍTICA]
• ✅ CORS configurado para frontend

Frontend

• ✅ Dashboard industrial con Dark Mode
• ✅ StatusCard con indicador visual (Verde/Rojo)
• ✅ Gráfico de líneas en tiempo real (Recharts)
• ✅ Tabla de últimas 5 alertas críticas
• ✅ Polling cada 2 segundos para actualizaciones
• ✅ Diseño SaaS profesional con TailwindCSS

Simulador

• ✅ Generación de datos realistas con variación gradual
• ✅ Simulación de anomalías aleatorias
• ✅ Indicadores visuales en consola
• ✅ Single File Source Code (Java 11+)

📊 Umbrales de Alerta

Métrica	Rango Normal	Umbral Crítico
Presión	45-65 PSI	> 65 PSI
Vibración	1-4 mm/s	> 4 mm/s
Flujo	100-150 L/s	N/A

🛠️ Comandos Útiles

# Detener PostgreSQL
docker-compose down

# Detener y eliminar volúmenes (borrar datos)
docker-compose down -v

# Ver logs del backend
cd backend && ./mvnw spring-boot:run | grep -E "(ALERTA|INFO)"

# Build de producción del frontend
cd frontend && npm run build

📝 Variables de Entorno

PostgreSQL (docker-compose.yml)

POSTGRES_USER: sx_user
POSTGRES_PASSWORD: sx_secure_pass_2026
POSTGRES_DB: sx_telemetry

Backend (application.yml)

spring.datasource.url: jdbc:postgresql://localhost:5432/sx_telemetry
spring.datasource.username: sx_user
spring.datasource.password: sx_secure_pass_2026

🔮 Próximas Mejoras (Roadmap)

• WebSockets para actualizaciones push en tiempo real
• Dockerización completa del backend y frontend
• Autenticación JWT
• Panel de configuración de umbrales
• Historial y exportación de datos
• Notificaciones por email/SMS

---

🐛 Troubleshooting - Problemas Conocidos y Soluciones

Problema 1: Fechas ilegibles en el Frontend (Array en lugar de String)

Síntoma: El frontend no puede parsear las fechas recibidas del backend. En la consola del navegador aparece un error al intentar crear objetos Date.

Causa: Spring Boot por defecto serializa LocalDateTime como arrays JSON: [2026, 1, 25, 10, 30, 0] en lugar del formato ISO-8601 que React espera: "2026-01-25T10:30:00".

Solución: Agregar configuración de Jackson en backend/src/main/resources/application.yml:

spring:
  # ... otras configuraciones ...
  
  jackson:
    serialization:
      WRITE_DATES_AS_TIMESTAMPS: false

---

Problema 2: Error JSON "Unexpected character" en el Backend

Síntoma: El backend muestra errores como:

HttpMessageNotReadableException: JSON parse error: Unexpected character ('5' (code 53)): was expecting double-quote to start field name

Causa: El simulador Java usa String.format() sin especificar Locale, y en sistemas con configuración regional en español, los números decimales usan coma (,) como separador en lugar de punto (.). Esto genera JSON inválido como {"presion": 55,25} en lugar de {"presion": 55.25}.

Solución: Modificar el método buildJsonPayload() en simulator/TelemetriaSimulator.java para forzar el uso de Locale.US:

import java.util.Locale;

// En el método buildJsonPayload():
private String buildJsonPayload() {
    return String.format(
            Locale.US,  // ← Forzar punto como separador decimal
            """
            {
                "equipoId": %d,
                "tipoEquipo": "%s",
                "presion": %.2f,
                "flujo": %.2f,
                "vibracion": %.3f
            }
            """,
            EQUIPO_ID,
            TIPO_EQUIPO,
            currentPresion,
            currentFlujo,
            currentVibracion
    );
}

---

Problema 3: Puerto ocupado al iniciar el Frontend

Síntoma: Vite muestra "Port 5173 is in use, trying another one..." y usa el puerto 5174.

Causa: Otra instancia del frontend o un proceso previo sigue corriendo en el puerto 5173.

Solución: Cerrar el proceso que usa el puerto:

# Encontrar y matar el proceso
lsof -ti:5173 | xargs kill -9

# O simplemente usar el nuevo puerto que Vite asigna (5174)

---

Cómo Detener Todos los Servicios

Para cerrar todos los servicios de una vez:

# Opción 1: Ctrl+C en cada terminal

# Opción 2: Matar todos los procesos de una vez
pkill -f "spring-boot:run"
pkill -f "TelemetriaSimulator"
pkill -f "vite"

# Detener PostgreSQL
docker-compose down

---

© 2026 Rodrigo Vásquez (VASQODEV) - Sistema de Monitoreo Industrial #AppSx