feat: Initial commit - Train tracking system

Complete real-time train tracking system for Spanish railways (Renfe/Cercanías): - Backend API (Node.js/Express) with GTFS-RT polling workers - Frontend dashboard (React/Vite) with Leaflet maps - Real-time updates via Socket.io WebSocket - PostgreSQL/PostGIS database with Flyway migrations - Redis caching layer - Docker Compose configuration for development and production - Gitea CI/CD workflows (lint, auto-tag, release) - Production deployment with nginx + Let's Encrypt SSL 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-28 00:21:15 +01:00
commit 34c0cb50c7
64 changed files with 15577 additions and 0 deletions
--- a/FUENTES_DATOS.md
+++ b/FUENTES_DATOS.md
@@ -0,0 +1,395 @@
+# Fuentes de Datos Abiertas para el Sistema de Tracking de Trenes
+
+## Resumen
+
+Este documento recopila todas las fuentes de datos abiertas identificadas para alimentar el sistema de tracking de trenes en España, incluyendo estaciones, rutas, horarios e información en tiempo real.
+
+---
+
+## 1. Renfe Data (Oficial)
+
+### Portal Principal
+- **URL**: https://data.renfe.com/
+- **Tipo**: Portal de datos abiertos oficial de Renfe
+- **Actualización**: Continua
+- **Formatos**: GTFS, JSON, CSV, XML
+
+### Datasets Disponibles
+
+#### Estaciones
+- **Endpoint**: https://data.renfe.com/dataset
+- **Descripción**: Información de todas las estaciones donde opera Renfe
+- **Incluye**:
+  - Estaciones con servicio Atendo (movilidad reducida)
+  - Coordenadas GPS
+  - Servicios disponibles
+  - Accesibilidad
+
+#### Horarios (GTFS Static)
+- **Cobertura**: 366 rutas, 769 paradas
+- **Vigencia**: 18 marzo 2025 - 15 diciembre 2025
+- **Servicios**:
+  - Alta Velocidad (AVE)
+  - Larga Distancia
+  - Media Distancia
+  - Cercanías y Rodalies
+
+**URLs de descarga**:
+- Renfe general: `https://data.renfe.com/dataset?res_format=GTFS/`
+- Via datos.gob.es: https://datos.gob.es/es/catalogo
+
+#### Tiempo Real (GTFS-RT)
+
+**1. Posiciones de vehículos (Vehicle Positions)**
+- **URL**: https://gtfsrt.renfe.com/vehicle_positions.pb
+- **Formato**: Protocol Buffer (GTFS-RT)
+- **Servicios**: Cercanías
+- **Frecuencia**: Cada 30 segundos
+- **Información**:
+  - Posición GPS (lat/lon)
+  - Estado (parado, en movimiento)
+  - Identificadores de tren y viaje
+  - Velocidad y dirección
+
+**2. Actualizaciones de viaje (Trip Updates)**
+- **Cercanías**: https://gtfsrt.renfe.com/trip_updates_cercanias.pb
+  - Cancelaciones
+  - Cambios de horario
+  - Retrasos
+  - Frecuencia: 30 segundos
+
+- **Alta Velocidad / Larga Distancia / Media Distancia**:
+  - URL similar (verificar en portal)
+  - Frecuencia: 30 segundos
+
+**3. Alertas (Service Alerts)**
+- **URL**: https://gtfsrt.renfe.com/alerts.pb
+- **Información**:
+  - Incidencias
+  - Servicios de autobús sustitutorio
+  - Problemas de vías
+  - Problemas de accesibilidad
+
+### Integración con otros portales
+- **datos.gob.es**: Federado con el portal nacional de datos abiertos
+- **European Data Portal**: Accesible desde el portal europeo
+- **Total datasets**: 63 conjuntos de datos en 6 formatos diferentes
+
+---
+
+## 2. ADIF (Infraestructura Ferroviaria)
+
+### Portal de Datos Espaciales
+- **URL**: https://ideadif.adif.es/
+- **Nombre**: IDEADIF (Infraestructura de Datos Espaciales de ADIF)
+- **Descripción**: Infraestructura de datos geoespaciales de ADIF
+
+### Servicios WMS (Web Map Service)
+- **Especificación**: OGC WMS 1.1.1 y 1.3.0
+- **Versión actual**: Julio 2024
+- **URL**: https://inspire-geoportal.ec.europa.eu/srv/api/records/191574be-5eca-4315-b4b4-756dc50ac553
+- **Normativa**: INSPIRE (Transport Networks Annex I)
+
+### PISERVI - Sistema de Información de Servicios
+- **URL**: https://www.adif.es/en/sobre-adif/declaracion-red
+- **Descripción**: Acceso a características técnicas de instalaciones
+- **Información disponible**:
+  - Terminales de mercancías
+  - Estaciones de pasajeros
+  - Instalaciones de mantenimiento
+  - Apartaderos particulares
+  - Cambiadores de ancho de vía
+
+### Datos Disponibles
+- **Kilómetros de vía**: 11,689 km (ADIF) + 3,926 km (ADIF-Alta Velocidad)
+- **Estaciones**: 1,451 (ADIF) + 46 (ADIF-Alta Velocidad)
+- **Mapa interactivo**: Red Ferroviaria de Interés General (RFIG)
+- **Búsquedas por**:
+  - Ubicación geográfica
+  - Tipo de instalación
+  - Tipo de servicio
+
+### Declaración de Red
+- **URL**: https://www.adif.es/en/sobre-adif/declaracion-red
+- **Contenido**:
+  - Características de la infraestructura
+  - Condiciones de acceso
+  - Servicios ofrecidos
+  - Cánones aplicables
+
+---
+
+## 3. Datos.gob.es (Portal Nacional)
+
+### Portal General
+- **URL**: https://datos.gob.es/
+- **Búsqueda transporte**: https://datos.gob.es/en/nti-reference/transporte
+
+### Datasets Relevantes
+
+#### Estadística sobre Transporte Ferroviario
+- **URL**: https://datos.gob.es/en/catalogo/ea0010587-estadistica-sobre-transporte-ferroviario
+- **Organismo**: Ministerio de Transportes
+- **Periodicidad**: Mensual/Anual
+
+#### Archivos GTFS
+- **URL**: https://datos.gob.es/en/catalogo/l03380010-archivos-gtfs
+- **Múltiples operadores**: Renfe, FGC, Metro, etc.
+
+#### FGC - GTFS Realtime
+- **URL**: https://datos.gob.es/en/catalogo/a09002970-fgc-actualitzaciones-de-viaje-gtfs_realtime
+- **Organismo**: Ferrocarrils de la Generalitat de Catalunya
+
+---
+
+## 4. Portales Regionales
+
+### CRTM (Consorcio Regional de Transportes de Madrid)
+- **Plataforma**: ArcGIS Open Data
+- **URL**: https://learning.esri.es/caso-de-exito/plataforma-datos-abiertos-del-crtm/
+- **Formato base**: GTFS
+- **Servicios**:
+  - Metro de Madrid
+  - Tren Ligero
+  - Cercanías Madrid
+  - Autobuses EMT
+
+### CTB (Consorcio de Transportes de Bizkaia)
+- **URL**: https://data.ctb.eus/en/dataset
+- **Filtros**: GTFS + Tren + Renfe
+- **Servicios**: Cercanías Bilbao, EuskoTren, etc.
+
+---
+
+## 5. Agregadores Internacionales
+
+### Mobility Database (Recomendado)
+- **URL**: https://mobilitydatabase.org/
+- **Descripción**: Base de datos global de feeds GTFS y GTFS-RT
+- **Cobertura España**: Sí
+- **Búsqueda por**:
+  - Ubicación
+  - Estado (activo/inactivo)
+  - Características
+
+### OpenMobilityData / TransitFeeds (Deprecado)
+- **URL**: https://transitfeeds.com/p/renfe
+- **Estado**: Deprecado en diciembre 2025
+- **Migración**: Mobility Database
+- **Útil para**: Datos históricos hasta 2025
+
+### GTFS.pro
+- **URL**: https://gtfs.pro/en/spain
+- **Descripción**: Agregador comercial de datos GTFS
+- **Servicios España**:
+  - Madrid (metro, cercanías, autobuses)
+  - Barcelona (metro, ferrocarril)
+  - Otras ciudades
+
+### Transport Data France (para AVE Francia-España)
+- **URL**: https://transport.data.gouv.fr/datasets/horaires-ave-espagne-france
+- **Descripción**: Horarios AVE red europea (España-Francia)
+- **Formato**: GTFS
+
+---
+
+## 6. Repositorios GitHub
+
+### API Renfe (No oficial)
+- **URL**: https://github.com/ferranpm/renfe
+- **Autor**: ferranpm
+- **Descripción**: API no oficial para consultar información de Renfe
+- **Estado**: Verificar actualización
+
+### GTFS Data Pipeline
+- **URL**: https://github.com/CxAalto/gtfs_data_pipeline/blob/master/gtfs-sources.yaml
+- **Descripción**: Pipeline de datos con fuentes GTFS documentadas
+- **Útil para**: Referencias a múltiples fuentes europeas
+
+---
+
+## 7. Fuentes Adicionales de Interés
+
+### European Data Portal
+- **URL**: https://data.europa.eu/
+- **Búsqueda**: "transporte ferroviario España"
+- **Contenido**: Datos agregados de toda Europa
+
+### INSPIRE Geoportal
+- **URL**: https://inspire-geoportal.ec.europa.eu/
+- **Normativa**: Directiva INSPIRE
+- **Servicios**: WMS/WFS de redes de transporte
+
+### Observatorio del Ferrocarril en España
+- **URL**: https://cdn.transportes.gob.es/portal-web-transportes/ferroviario/observatorio/
+- **Formato**: PDF (Informes anuales)
+- **Contenido**: Estadísticas, análisis de red, evolución
+
+---
+
+## Recomendaciones de Implementación
+
+### Prioridad 1: Datos Esenciales (MVP)
+
+1. **GTFS-RT Posiciones** (ya implementado)
+   - URL: https://gtfsrt.renfe.com/vehicle_positions.pb
+   - Polling: 30 segundos
+   - Almacenar en PostgreSQL + Redis
+
+2. **GTFS Static de Renfe**
+   - Descargar de: https://data.renfe.com/dataset
+   - Frecuencia: Semanal (verificar actualizaciones)
+   - Tablas: routes, stops, trips, stop_times
+
+3. **Estaciones ADIF/Renfe**
+   - Fuente: data.renfe.com o IDEADIF
+   - Frecuencia: Mensual
+   - Enriquecer tabla stations
+
+### Prioridad 2: Datos en Tiempo Real Adicionales
+
+4. **Trip Updates**
+   - URL: https://gtfsrt.renfe.com/trip_updates_cercanias.pb
+   - Frecuencia: 30 segundos
+   - Tabla: alerts (retrasos, cancelaciones)
+
+5. **Service Alerts**
+   - URL: https://gtfsrt.renfe.com/alerts.pb
+   - Frecuencia: 30 segundos
+   - Tabla: alerts (incidencias)
+
+### Prioridad 3: Enriquecimiento de Datos
+
+6. **Infraestructura ADIF**
+   - Fuente: IDEADIF WMS
+   - Uso: Visualización de vías, topología
+   - Formato: GeoJSON/WMS overlay
+
+7. **Datos Regionales**
+   - CRTM (Madrid)
+   - CTB (Bilbao)
+   - Otros consorcios
+   - Integrar según demanda
+
+### Prioridad 4: Análisis y Estadísticas
+
+8. **Estadísticas Ministerio**
+   - Fuente: datos.gob.es
+   - Frecuencia: Mensual/Anual
+   - Uso: Dashboards, métricas
+
+9. **Observatorio Ferroviario**
+   - Fuente: Informes PDF
+   - Uso: Contexto, KPIs benchmark
+
+---
+
+## Plan de Actualización Automática
+
+### Script de Sincronización (Sugerido)
+
+```javascript
+// Pseudocódigo para worker de sincronización
+
+const syncJobs = [
+    {
+        name: 'GTFS Static Renfe',
+        url: 'https://data.renfe.com/api/gtfs/latest',
+        frequency: '0 0 * * 0', // Domingo a medianoche
+        parser: parseGTFSZip,
+        tables: ['routes', 'stops', 'trips', 'stop_times']
+    },
+    {
+        name: 'Estaciones Renfe',
+        url: 'https://data.renfe.com/api/stations',
+        frequency: '0 0 1 * *', // Primero de mes
+        parser: parseStations,
+        tables: ['stations']
+    },
+    {
+        name: 'GTFS-RT Vehicle Positions',
+        url: 'https://gtfsrt.renfe.com/vehicle_positions.pb',
+        frequency: '*/30 * * * * *', // Cada 30 segundos
+        parser: parseGTFSRT,
+        tables: ['train_positions']
+    }
+];
+```
+
+### Monitorización de Cambios
+
+- **Checksums**: Calcular hash de archivos descargados
+- **Versiones**: Detectar cambios en GTFS feeds
+- **Logs**: Registrar actualizaciones exitosas/fallidas
+- **Alertas**: Notificar si falla alguna sincronización
+
+---
+
+## APIs Recomendadas para Integración
+
+### A Implementar en el Backend
+
+```javascript
+// Endpoints sugeridos
+
+// 1. Actualizar catálogo GTFS Static
+POST /api/admin/sync/gtfs-static
+
+// 2. Actualizar estaciones
+POST /api/admin/sync/stations
+
+// 3. Estado de sincronización
+GET /api/admin/sync/status
+
+// 4. Información de fuentes
+GET /api/data-sources
+```
+
+---
+
+## Notas Legales y de Uso
+
+### Licencias
+- **Renfe Data**: Datos abiertos, verificar condiciones de uso en portal
+- **ADIF**: Datos públicos bajo normativa INSPIRE
+- **Datos.gob.es**: Datos abiertos del sector público español
+
+### Atribución
+Incluir en la aplicación:
+```
+Datos de trenes en tiempo real proporcionados por Renfe
+Información de infraestructura proporcionada por ADIF
+Fuente: data.renfe.com | ideadif.adif.es
+```
+
+### Rate Limiting
+- GTFS-RT: Respetar frecuencia de 30 segundos mínimo
+- GTFS Static: No hacer polling agresivo, descargar una vez al día
+- WMS: Cachear tiles, no hacer requests excesivos
+
+---
+
+## Próximos Pasos
+
+1. ✅ Implementar polling GTFS-RT Vehicle Positions (YA HECHO)
+2. ⬜ Descargar e importar GTFS Static inicial
+3. ⬜ Crear worker de sincronización semanal GTFS Static
+4. ⬜ Implementar Trip Updates y Alerts
+5. ⬜ Integrar datos de estaciones desde Renfe Data
+6. ⬜ (Opcional) Overlay WMS de ADIF para visualización de vías
+7. ⬜ (Futuro) Integración con datos regionales según demanda
+
+---
+
+## Referencias
+
+- **GTFS Specification**: https://gtfs.org/
+- **GTFS Realtime**: https://gtfs.org/documentation/realtime/
+- **Renfe Data**: https://data.renfe.com/
+- **ADIF IDEADIF**: https://ideadif.adif.es/
+- **Datos.gob.es**: https://datos.gob.es/
+- **Mobility Database**: https://mobilitydatabase.org/
+
+---
+
+*Documento actualizado: 27 noviembre 2025*