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/README.md
+++ b/README.md
@@ -0,0 +1,680 @@
+# Sistema de Tracking de Trenes en Tiempo Real
+
+Sistema web para visualizar en tiempo real la posición de todos los trenes operados por Renfe en España, con capacidad de consultar histórico mediante un timeline slider.
+
+## Características
+
+- 🚄 **Visualización en tiempo real** de posiciones de trenes en mapa OpenStreetMap
+- 📊 **Información detallada** de cada tren (velocidad, dirección, estado, ruta)
+- ⏱️ **Timeline slider** para navegar por el histórico de posiciones
+- 🗺️ **Datos geoespaciales** usando PostGIS
+- 🔄 **Actualización automática** cada 30 segundos desde feed GTFS-RT
+- 📡 **WebSocket** para actualizaciones en tiempo real sin polling
+- 🎨 **Interfaz moderna** con React + Leaflet.js
+
+## Stack Tecnológico
+
+### Frontend
+- React + JavaScript (JSX)
+- Leaflet.js para mapas (OpenStreetMap)
+- Socket.io client para WebSocket
+- Vite como bundler
+
+### Backend
+- Node.js + Express/Fastify
+- Socket.io para WebSocket server
+- Parser GTFS-RT (gtfs-realtime-bindings)
+
+### Infraestructura
+- PostgreSQL 15 + PostGIS (datos geoespaciales)
+- Redis (caché de posiciones actuales)
+- Nginx (reverse proxy)
+- Flyway (migraciones de base de datos)
+- Docker + Docker Compose
+
+## Requisitos Previos
+
+- Docker >= 20.10
+- Docker Compose >= 2.0
+- Make (opcional, pero recomendado)
+- Git
+
+## Instalación Rápida
+
+### Usando Make (Recomendado)
+
+```bash
+# 1. Clonar el repositorio
+git clone <repository-url>
+cd trenes
+
+# 2. Ver comandos disponibles
+make help
+
+# 3. Configurar variables de entorno
+cp .env.example .env
+# Editar .env con tus credenciales
+
+# 4. Ejecutar migraciones
+make migrate
+
+# 5. Iniciar servicios
+make start
+```
+
+### Instalación Manual (sin Make)
+
+#### 1. Clonar el repositorio
+
+```bash
+git clone <repository-url>
+cd trenes
+```
+
+#### 2. Configurar variables de entorno
+
+```bash
+cp .env.example .env
+```
+
+Editar `.env` y configurar las contraseñas y secretos:
+
+```env
+POSTGRES_PASSWORD=tu_password_seguro
+REDIS_PASSWORD=tu_redis_password
+JWT_SECRET=tu_jwt_secret_minimo_32_caracteres
+```
+
+#### 3. Ejecutar migraciones de base de datos
+
+```bash
+# Primera vez: ejecutar migraciones
+docker-compose --profile migration up flyway
+
+# Verificar que las migraciones se aplicaron correctamente
+docker-compose logs flyway
+```
+
+#### 4. Iniciar todos los servicios
+
+```bash
+docker-compose up -d
+```
+
+#### 5. Verificar que todo está funcionando
+
+```bash
+# Ver logs de todos los servicios
+docker-compose logs -f
+
+# Verificar estado de los servicios
+docker-compose ps
+```
+
+## Acceso a los Servicios
+
+Una vez iniciado, el sistema estará disponible en:
+
+- **Aplicación Web**: http://localhost
+- **API REST**: http://localhost/api
+- **WebSocket**: ws://localhost/ws
+- **Adminer** (DB admin): http://localhost:8080 (solo en modo debug)
+- **Redis Commander**: http://localhost:8081 (solo en modo debug)
+
+## Uso
+
+### Comandos Make Disponibles
+
+```bash
+# Ver todos los comandos disponibles
+make help
+
+# Comandos de Producción
+make start              # Iniciar servicios
+make stop               # Detener servicios
+make restart            # Reiniciar servicios
+make logs               # Ver logs
+make status             # Ver estado de servicios
+make migrate            # Ejecutar migraciones
+make debug-start        # Iniciar con herramientas de debug
+
+# Comandos de Testing
+make test-start         # Iniciar entorno de testing
+make test-stop          # Detener entorno de testing
+make test-logs          # Ver logs de testing
+make test-clean         # Limpiar datos de testing
+make test-reset         # Reset completo de testing
+
+# Utilidades
+make psql               # Conectar a PostgreSQL
+make redis-cli          # Conectar a Redis
+make backup-db          # Crear backup de BD
+make cleanup-old-data   # Limpiar datos antiguos
+```
+
+### Modo Normal (Producción)
+
+```bash
+# Usando Make
+make start              # Iniciar todos los servicios
+make logs               # Ver logs
+make stop               # Detener servicios
+
+# O manualmente con docker-compose
+docker-compose up -d
+docker-compose logs -f
+docker-compose down
+```
+
+### Modo Testing
+
+El entorno de testing usa el archivo `.env.testing` que incluye configuraciones específicas para pruebas:
+
+```bash
+# Iniciar entorno de testing
+make test-start
+
+# Ver logs
+make test-logs
+
+# Detener y limpiar
+make test-clean
+```
+
+El entorno de testing incluye:
+- Configuración de desarrollo con logs detallados
+- Polling más frecuente (15 segundos)
+- Debug endpoints habilitados
+- Rate limiting deshabilitado
+- Herramientas de administración (Adminer, Redis Commander) activadas por defecto
+
+### Modo Debug (con herramientas de administración)
+
+```bash
+# Usando Make
+make debug-start
+
+# O manualmente
+docker-compose --profile debug up -d
+
+# Acceder a Adminer: http://localhost:8080
+# - Sistema: PostgreSQL
+# - Servidor: postgres
+# - Usuario: trenes_user
+# - Contraseña: [tu POSTGRES_PASSWORD]
+# - Base de datos: trenes_db
+```
+
+### Ejecutar Migraciones
+
+```bash
+# Usando Make
+make migrate            # Aplicar migraciones
+make migrate-info       # Ver información
+make migrate-validate   # Validar migraciones
+
+# O manualmente
+docker-compose --profile migration up flyway
+docker-compose --profile migration run --rm flyway info
+docker-compose --profile migration run --rm flyway validate
+```
+
+## Estructura del Proyecto
+
+```
+trenes/
+├── backend/                    # Backend Node.js
+│   ├── src/
+│   │   ├── api/               # API REST
+│   │   │   └── server.js
+│   │   └── worker/            # Worker GTFS-RT polling
+│   │       └── gtfs-poller.js
+│   ├── Dockerfile
+│   └── package.json
+│
+├── frontend/                   # Frontend React
+│   ├── src/
+│   │   ├── components/
+│   │   ├── hooks/
+│   │   └── App.jsx
+│   ├── Dockerfile
+│   ├── nginx.conf             # Configuración nginx del contenedor
+│   └── package.json
+│
+├── database/
+│   ├── init/                  # Scripts de inicialización (solo primera vez)
+│   │   ├── 01-init-extensions.sql
+│   │   ├── 02-create-schema.sql
+│   │   └── 03-seed-data.sql
+│   └── migrations/            # Migraciones versionadas (Flyway)
+│       ├── V1__initial_schema.sql
+│       ├── V2__create_partitions.sql
+│       ├── V3__create_views_and_functions.sql
+│       └── V4__seed_initial_data.sql
+│
+├── nginx/                     # Configuración Nginx (reverse proxy)
+│   ├── nginx.conf
+│   └── conf.d/
+│       └── default.conf
+│
+├── docker-compose.yml
+├── .env.example
+└── README.md
+```
+
+## API Endpoints
+
+### Posiciones de Trenes
+
+```bash
+# Obtener posiciones actuales de todos los trenes
+GET /api/trains/current
+
+# Obtener histórico de un tren
+GET /api/trains/history?train_id=XXX&from=TIMESTAMP&to=TIMESTAMP
+
+# Obtener información de un tren específico
+GET /api/trains/:id
+
+# Obtener rutas disponibles
+GET /api/routes
+
+# Obtener estaciones
+GET /api/stations
+```
+
+### WebSocket Events
+
+```javascript
+// Conectar al WebSocket
+const socket = io('ws://localhost/ws');
+
+// Escuchar actualizaciones de posiciones
+socket.on('train:update', (position) => {
+    console.log('Nueva posición:', position);
+});
+
+// Suscribirse a un tren específico
+socket.emit('subscribe', { train_id: 'AVE-03041' });
+```
+
+## Base de Datos
+
+### Tablas Principales
+
+- **trains**: Catálogo de trenes
+- **train_positions**: Histórico de posiciones (particionada por mes)
+- **routes**: Rutas y líneas
+- **stations**: Estaciones
+- **alerts**: Alertas e incidencias
+
+### Vistas
+
+- **current_train_positions**: Última posición de cada tren
+- **active_trains**: Trenes activos en las últimas 24 horas
+
+### Funciones Útiles
+
+```sql
+-- Limpiar posiciones antiguas (mayores a 90 días)
+SELECT cleanup_old_positions(90);
+
+-- Crear siguiente partición mensual
+SELECT create_next_partition();
+
+-- Obtener trayectoria de un tren
+SELECT * FROM get_train_path('AVE-03041', '2025-01-01', '2025-01-02');
+
+-- Obtener trenes en un área
+SELECT * FROM get_trains_in_area(40.0, -4.0, 41.0, -3.0);
+
+-- Calcular estadísticas de un tren
+SELECT * FROM calculate_train_statistics('AVE-03041', '2025-01-01', '2025-01-02');
+```
+
+## Gestión de Migraciones
+
+Este proyecto usa **Flyway** para gestionar las migraciones de base de datos de forma versionada y reproducible.
+
+### Convención de Nombres
+
+Las migraciones siguen el formato: `V{version}__{description}.sql`
+
+- `V1__initial_schema.sql` - Versión 1: Schema inicial
+- `V2__create_partitions.sql` - Versión 2: Crear particiones
+- etc.
+
+### Crear Nueva Migración
+
+1. Crear archivo en `database/migrations/` siguiendo la convención:
+   ```
+   V5__add_train_operators.sql
+   ```
+
+2. Aplicar migración:
+   ```bash
+   docker-compose --profile migration up flyway
+   ```
+
+### Comandos de Flyway
+
+```bash
+# Ver estado de migraciones
+docker-compose --profile migration run --rm flyway info
+
+# Validar migraciones
+docker-compose --profile migration run --rm flyway validate
+
+# Limpiar base de datos (¡CUIDADO! Borra todo)
+docker-compose --profile migration run --rm flyway clean
+
+# Reparar tabla de migraciones
+docker-compose --profile migration run --rm flyway repair
+```
+
+## Mantenimiento
+
+### Backup de Base de Datos
+
+```bash
+# Crear backup
+docker-compose exec postgres pg_dump -U trenes_user trenes_db > backup.sql
+
+# Restaurar backup
+docker-compose exec -T postgres psql -U trenes_user trenes_db < backup.sql
+```
+
+### Limpiar Datos Antiguos
+
+```bash
+# Conectar a PostgreSQL
+docker-compose exec postgres psql -U trenes_user -d trenes_db
+
+# Ejecutar función de limpieza (elimina datos > 90 días)
+SELECT cleanup_old_positions(90);
+```
+
+### Crear Nuevas Particiones
+
+```bash
+# Conectar a PostgreSQL
+docker-compose exec postgres psql -U trenes_user -d trenes_db
+
+# Crear próxima partición
+SELECT create_next_partition();
+```
+
+## Desarrollo
+
+### Modo Desarrollo
+
+Para desarrollo local con hot-reload:
+
+```bash
+# Backend
+cd backend
+npm install
+npm run dev
+
+# Frontend
+cd frontend
+npm install
+npm run dev
+```
+
+### Estructura de Logs
+
+```bash
+# Ver logs de un servicio específico
+docker-compose logs -f api
+docker-compose logs -f worker
+docker-compose logs -f frontend
+
+# Ver logs de todos los servicios
+docker-compose logs -f
+```
+
+## Troubleshooting
+
+### El worker no puede conectar con GTFS-RT
+
+```bash
+# Verificar que el worker está corriendo
+docker-compose logs worker
+
+# Probar manualmente el endpoint
+curl -I https://gtfsrt.renfe.com/vehicle_positions.pb
+```
+
+### La base de datos no inicia
+
+```bash
+# Ver logs de PostgreSQL
+docker-compose logs postgres
+
+# Verificar permisos de volúmenes
+ls -la postgres_data/
+
+# Reiniciar contenedor
+docker-compose restart postgres
+```
+
+### No se ven los trenes en el mapa
+
+1. Verificar que el worker está recolectando datos:
+   ```bash
+   docker-compose logs worker
+   ```
+
+2. Verificar que hay datos en la base de datos:
+   ```bash
+   docker-compose exec postgres psql -U trenes_user -d trenes_db -c "SELECT COUNT(*) FROM train_positions;"
+   ```
+
+3. Verificar que el API responde:
+   ```bash
+   curl http://localhost/api/trains/current
+   ```
+
+## Despliegue en Producción
+
+### Requisitos del Servidor
+
+- Linux (Debian/Ubuntu recomendado)
+- Docker >= 20.10
+- Docker Compose >= 2.0
+- Mínimo 2GB RAM, 20GB disco
+- Puerto 80 y 443 abiertos
+- Dominio apuntando al servidor
+
+### Despliegue Rápido
+
+```bash
+# 1. Copiar proyecto al servidor
+rsync -avz --exclude 'node_modules' --exclude '.git' --exclude 'postgres_data' \
+  ./ root@tu-servidor:/opt/trenes/
+
+# 2. En el servidor, crear archivo .env de producción
+cat > /opt/trenes/.env << 'EOF'
+POSTGRES_USER=trenes
+POSTGRES_PASSWORD=TU_PASSWORD_SEGURO_GENERADO
+POSTGRES_DB=trenes
+DATABASE_URL=postgres://trenes:${POSTGRES_PASSWORD}@postgres:5432/trenes
+REDIS_URL=redis://redis:6379
+NODE_ENV=production
+PORT=3000
+CORS_ORIGINS=https://tu-dominio.com
+EOF
+
+# 3. Iniciar servicios
+cd /opt/trenes
+docker compose -f docker-compose.prod.yml up -d
+```
+
+### Configuración SSL con Let's Encrypt
+
+```bash
+# 1. Iniciar nginx temporal para obtener certificado
+docker run -d --name temp-nginx -p 80:80 \
+  -v /opt/trenes/nginx/prod.conf:/etc/nginx/conf.d/default.conf:ro \
+  -v certbot_webroot:/var/www/certbot nginx:alpine
+
+# 2. Obtener certificado
+docker run --rm \
+  -v trenes_certbot_certs:/etc/letsencrypt \
+  -v certbot_webroot:/var/www/certbot \
+  certbot/certbot certonly --webroot \
+  --webroot-path=/var/www/certbot \
+  --email tu-email@dominio.com \
+  --agree-tos --no-eff-email \
+  -d tu-dominio.com
+
+# 3. Detener nginx temporal
+docker stop temp-nginx && docker rm temp-nginx
+
+# 4. Iniciar servicios completos
+docker compose -f docker-compose.prod.yml up -d
+```
+
+### Lecciones Aprendidas del Despliegue
+
+#### 1. PostgreSQL/PostGIS - Compatibilidad de Versiones
+**Problema**: Error `FATAL: database files are incompatible with server` al usar datos existentes.
+
+**Solución**: Asegurar que la versión de PostgreSQL en producción coincida con la de desarrollo. Si los datos fueron creados con PostgreSQL 16, usar `postgis/postgis:16-3.4-alpine` en producción.
+
+#### 2. Socket.io - Configuración de URL
+**Problema**: Error "Invalid namespace" al conectar WebSocket.
+
+**Causa**: Socket.io añade automáticamente `/socket.io/` al path. Si `VITE_WS_URL=wss://dominio.com/ws`, intentará conectar a `/ws/socket.io/`.
+
+**Solución**: Configurar `VITE_WS_URL=https://dominio.com` (sin path adicional) para que Socket.io conecte correctamente a `/socket.io/`.
+
+#### 3. Nginx - Variables y Proxy Pass
+**Problema**: Cuando se usan variables en `proxy_pass`, nginx NO hace sustitución automática de URI.
+
+**Solución**: Usar `rewrite` explícito:
+```nginx
+location /api/ {
+    set $backend api:3000;
+    rewrite ^/api/(.*)$ /$1 break;
+    proxy_pass http://$backend;
+}
+```
+
+#### 4. Nginx - Resolución DNS de Contenedores
+**Problema**: Error `host not found in upstream` al iniciar nginx antes que otros servicios.
+
+**Solución**: Usar el resolver DNS de Docker:
+```nginx
+resolver 127.0.0.11 valid=30s;
+```
+
+#### 5. Nginx - Directiva HTTP/2
+**Problema**: Warning `the "listen ... http2" directive is deprecated`.
+
+**Solución**: Cambiar de `listen 443 ssl http2;` a:
+```nginx
+listen 443 ssl;
+http2 on;
+```
+
+#### 6. Variables VITE en Docker
+**Problema**: Las variables `VITE_*` del `.env` no se aplican en el build de Docker.
+
+**Solución**: Pasar las variables como build args en docker-compose:
+```yaml
+frontend:
+  build:
+    args:
+      VITE_API_URL: https://tu-dominio.com/api
+      VITE_WS_URL: https://tu-dominio.com
+```
+
+Y en el Dockerfile del frontend:
+```dockerfile
+ARG VITE_API_URL
+ARG VITE_WS_URL
+ENV VITE_API_URL=${VITE_API_URL}
+ENV VITE_WS_URL=${VITE_WS_URL}
+```
+
+#### 7. Migración de Datos
+**Comando para exportar e importar datos históricos**:
+```bash
+# Exportar desde desarrollo
+docker compose exec -T postgres pg_dump -U trenes_user -d trenes_db \
+  --data-only --exclude-table='flyway_schema_history' | gzip > backup.sql.gz
+
+# Copiar al servidor
+scp backup.sql.gz root@servidor:/tmp/
+
+# Importar en producción
+gunzip -c /tmp/backup.sql.gz | docker exec -i trenes-postgres \
+  psql -U trenes -d trenes
+```
+
+### Verificación del Despliegue
+
+```bash
+# Verificar servicios
+docker ps --format "table {{.Names}}\t{{.Status}}"
+
+# Test API
+curl https://tu-dominio.com/api/health
+
+# Test Dashboard
+curl https://tu-dominio.com/api/dashboard/current
+
+# Test WebSocket (debe devolver sid)
+curl "https://tu-dominio.com/socket.io/?EIO=4&transport=polling"
+```
+
+## Roadmap
+
+- [x] **Fase 1: MVP** ✅ COMPLETADA
+  - [x] Arquitectura y Docker Compose
+  - [x] Backend API y Worker GTFS-RT
+  - [x] Frontend con mapa Leaflet
+  - [x] WebSocket en tiempo real
+  - [x] Timeline slider (UI básica)
+
+- [x] **Fase 2: Enriquecimiento** ✅ BACKEND COMPLETADO
+  - [x] GTFS Static Syncer (sync diario)
+  - [x] Trip Updates Poller (retrasos)
+  - [x] Service Alerts Poller (alertas)
+  - [x] API de Alertas y Trips
+  - [ ] Frontend: componentes de alertas y puntualidad
+
+- [x] **Fase 3: Analytics** ✅ BACKEND COMPLETADO
+  - [x] Analytics API (heatmaps, estadísticas)
+  - [x] Explorer API (planificador de viajes)
+  - [x] Exportación de datos (CSV, JSON, GeoJSON)
+  - [ ] Frontend: dashboard de analytics
+
+- [ ] **Fase 4: ML y Predicciones** (Futuro)
+  - [ ] Predicción de retrasos
+  - [ ] Detección de anomalías
+  - [ ] Correlación con meteorología
+
+## Licencia
+
+MIT
+
+## Contribuir
+
+Las contribuciones son bienvenidas. Por favor:
+
+1. Fork el proyecto
+2. Crea una rama para tu feature (`git checkout -b feature/AmazingFeature`)
+3. Commit tus cambios (`git commit -m 'Add some AmazingFeature'`)
+4. Push a la rama (`git push origin feature/AmazingFeature`)
+5. Abre un Pull Request
+
+## Recursos
+
+- [GTFS Realtime Specification](https://gtfs.org/documentation/realtime/)
+- [Renfe Data Portal](https://data.renfe.com/)
+- [PostGIS Documentation](https://postgis.net/)
+- [Leaflet.js](https://leafletjs.com/)
+- [Flyway Documentation](https://flywaydb.org/documentation/)