ATLAS/docs/guias/troubleshooting.md

# Solucion de Problemas

Guia para diagnosticar y resolver problemas comunes en FlotillasGPS.

## Diagnostico Rapido

### Verificar Estado de Servicios

```bash
# Ver estado de todos los servicios
systemctl status flotillas-api flotillas-web traccar mediamtx cloudflared redis postgresql

# Resumen rapido
for svc in flotillas-api flotillas-web traccar mediamtx cloudflared; do
  echo "$svc: $(systemctl is-active $svc)"
done
```

### Verificar Logs

```bash
# API Backend
journalctl -u flotillas-api -f

# Frontend
journalctl -u flotillas-web -f

# Traccar (GPS)
journalctl -u traccar -f

# Cloudflare Tunnel
journalctl -u cloudflared -f
```

### Verificar Conectividad

```bash
# Puerto GPS
netstat -tlnp | grep 5055

# Puerto API
curl http://localhost:8000/api/v1/health

# Puerto Frontend
curl http://localhost:3000

# Base de datos
psql -U flotillas -d flotillas_db -c "SELECT 1"

# Redis
redis-cli ping
```

---

## Problemas de Acceso Web

### No puedo acceder al dashboard

**Sintomas**: El navegador muestra error de conexion o timeout.

**Verificar**:

1. Estado del tunnel de Cloudflare:
```bash
systemctl status cloudflared
cloudflared tunnel info flotillas
```

2. Estado del frontend:
```bash
systemctl status flotillas-web
curl http://localhost:3000
```

**Soluciones**:

- Reiniciar el tunnel:
```bash
systemctl restart cloudflared
```

- Verificar configuracion DNS en Cloudflare dashboard

- Verificar que el dominio apunta al tunnel correcto

### Error 502 Bad Gateway

**Causa**: El backend no esta respondiendo.

**Verificar**:
```bash
systemctl status flotillas-api
curl http://localhost:8000/api/v1/health
```

**Soluciones**:
```bash
# Reiniciar backend
systemctl restart flotillas-api

# Ver logs de error
journalctl -u flotillas-api -n 100 --no-pager
```

### Error de SSL/Certificado

**Causa**: Problema con Cloudflare.

**Soluciones**:

1. En Cloudflare dashboard, verificar que SSL este en "Full" o "Full (strict)"
2. Verificar que el dominio este activo
3. Esperar propagacion DNS (hasta 24 horas)

---

## Problemas con GPS

### Los dispositivos GPS no se conectan

**Sintomas**: Vehiculos aparecen offline, no se reciben ubicaciones.

**Verificar**:

1. Puerto 5055 abierto:
```bash
# Desde el servidor
netstat -tlnp | grep 5055

# Desde fuera (otra maquina)
nc -zv IP_SERVIDOR 5055
```

2. Traccar funcionando:
```bash
systemctl status traccar
journalctl -u traccar -f
```

3. Firewall:
```bash
ufw status
# Debe mostrar 5055/tcp ALLOW
```

**Soluciones**:

- Abrir puerto en firewall:
```bash
ufw allow 5055/tcp
```

- Verificar configuracion del GPS:
  - IP/dominio del servidor correcto
  - Puerto 5055
  - Protocolo correcto (ver manual del GPS)

- Reiniciar Traccar:
```bash
systemctl restart traccar
```

### GPS conecta pero no aparece en el mapa

**Causa**: El dispositivo no esta vinculado a un vehiculo.

**Solucion**:

1. Verificar que el dispositivo esta registrado en Traccar:
```bash
# Ver dispositivos en Traccar
curl http://localhost:8082/api/devices
```

2. Vincular el dispositivo al vehiculo desde el dashboard

### Ubicaciones con retraso

**Causas posibles**:

1. Problema de red del GPS
2. Intervalo de reporte muy largo
3. Problema de procesamiento

**Verificar**:
```bash
# Ver ubicaciones recientes en DB
psql -U flotillas -d flotillas_db -c "
  SELECT vehiculo_id, tiempo, lat, lng
  FROM ubicaciones
  ORDER BY tiempo DESC
  LIMIT 10;
"
```

---

## Problemas con la App Movil

### La app no envia ubicacion

**Verificar en el telefono**:

1. Permiso de ubicacion en "Siempre"
2. GPS activado
3. Datos moviles o WiFi activo
4. App no en modo ahorro de bateria

**Verificar en el servidor**:
```bash
# Ver ultimas ubicaciones de apps
journalctl -u flotillas-api | grep "ubicacion" | tail -20
```

### App no puede conectar al servidor

**Causas**:

1. Sin conexion a internet
2. Token expirado
3. Dispositivo no registrado

**Solucion**:

1. Verificar conexion a internet
2. Cerrar sesion y volver a entrar
3. Verificar que el conductor tiene dispositivo asignado

### Notificaciones no llegan

**Verificar**:

1. Permiso de notificaciones en el telefono
2. App no silenciada
3. Token de push registrado

**En el servidor**:
```bash
# Ver logs de notificaciones
journalctl -u flotillas-api | grep "push\|notification"
```

---

## Problemas de Video

### Camara no conecta

**Verificar**:

1. URL del stream correcta
2. Credenciales correctas
3. Camara accesible desde el servidor

```bash
# Probar conexion RTSP
ffprobe rtsp://usuario:password@IP_CAMARA/stream
```

**Soluciones**:

- Verificar que la camara y el servidor estan en la misma red (o hay ruta)
- Verificar puerto de la camara no bloqueado
- Probar con VLC desde otra maquina

### Video con lag/retraso

**Causas**:

1. Ancho de banda insuficiente
2. Servidor sobrecargado
3. Configuracion de bitrate muy alto

**Soluciones**:

- Reducir calidad del stream en configuracion de camara
- Verificar uso de CPU/RAM del servidor
- Usar HLS en lugar de WebRTC para conexiones lentas

### No se guardan grabaciones

**Verificar**:

1. Espacio en disco:
```bash
df -h /opt/flotillas/videos
```

2. Permisos:
```bash
ls -la /opt/flotillas/videos
```

**Solucion**:
```bash
# Liberar espacio
find /opt/flotillas/videos -name "*.mp4" -mtime +30 -delete

# Arreglar permisos
chown -R www-data:www-data /opt/flotillas/videos
```

---

## Problemas de Base de Datos

### Error de conexion a PostgreSQL

```bash
# Verificar estado
systemctl status postgresql

# Verificar que acepta conexiones
psql -U flotillas -d flotillas_db -c "SELECT 1"
```

**Soluciones**:
```bash
# Reiniciar PostgreSQL
systemctl restart postgresql

# Ver logs
journalctl -u postgresql -f
```

### Base de datos lenta

**Verificar**:
```bash
# Ver consultas lentas
psql -U flotillas -d flotillas_db -c "
  SELECT pid, now() - pg_stat_activity.query_start AS duration, query
  FROM pg_stat_activity
  WHERE state != 'idle'
  ORDER BY duration DESC;
"
```

**Soluciones**:

1. Ejecutar VACUUM:
```bash
psql -U flotillas -d flotillas_db -c "VACUUM ANALYZE;"
```

2. Verificar indices:
```bash
psql -U flotillas -d flotillas_db -c "\di"
```

### Disco lleno por ubicaciones

**Verificar**:
```bash
psql -U flotillas -d flotillas_db -c "
  SELECT pg_size_pretty(pg_total_relation_size('ubicaciones'));
"
```

**Solucion**: Comprimir datos antiguos (TimescaleDB):
```bash
psql -U flotillas -d flotillas_db -c "
  SELECT compress_chunk(c)
  FROM show_chunks('ubicaciones', older_than => INTERVAL '7 days') c;
"
```

---

## Problemas de Rendimiento

### Servidor lento

**Verificar recursos**:
```bash
# CPU y RAM
htop

# Disco
iostat -x 1

# Conexiones de red
ss -s
```

**Soluciones**:

1. Aumentar RAM de la VM
2. Agregar mas cores de CPU
3. Usar SSD para base de datos
4. Optimizar consultas lentas

### API responde lento

**Verificar**:
```bash
# Tiempo de respuesta
time curl http://localhost:8000/api/v1/health

# Workers activos
ps aux | grep uvicorn
```

**Soluciones**:

1. Aumentar workers en el servicio:
```bash
# Editar /etc/systemd/system/flotillas-api.service
# Cambiar --workers 4 a --workers 8
systemctl daemon-reload
systemctl restart flotillas-api
```

2. Verificar conexiones a Redis:
```bash
redis-cli info clients
```

---

## Problemas de Meshtastic

### Nodos no aparecen

**Verificar MQTT**:
```bash
# Estado de Mosquitto
systemctl status mosquitto

# Suscribirse para ver mensajes
mosquitto_sub -h localhost -t "flotillas/mesh/#" -u mesh_gateway -P password
```

**Verificar configuracion del gateway**:
- MQTT habilitado
- Servidor y credenciales correctos
- Topic correcto

### Ubicaciones de mesh no se guardan

**Verificar**:
```bash
journalctl -u flotillas-api | grep "meshtastic\|mesh"
```

**Solucion**: Verificar que el servicio MQTT esta corriendo en el backend.

---

## Backup y Restauracion

### Backup falla

**Verificar**:
```bash
# Espacio en disco
df -h /opt/flotillas/backups

# Permisos
ls -la /opt/flotillas/scripts/backup.sh
```

**Ejecutar manualmente para ver errores**:
```bash
/opt/flotillas/scripts/backup.sh 2>&1 | tee /tmp/backup.log
```

### Restauracion falla

**Verificar integridad del backup**:
```bash
gunzip -t /opt/flotillas/backups/db_FECHA.sql.gz
```

**Restaurar paso a paso**:
```bash
# Parar servicios
systemctl stop flotillas-api

# Recrear base de datos
psql -U postgres -c "DROP DATABASE flotillas_db;"
psql -U postgres -c "CREATE DATABASE flotillas_db OWNER flotillas;"

# Restaurar
gunzip -c backup.sql.gz | psql -U flotillas -d flotillas_db

# Iniciar servicios
systemctl start flotillas-api
```

---

## Comandos Utiles de Diagnostico

```bash
# Estado general del sistema
systemctl status flotillas-api flotillas-web traccar mediamtx cloudflared

# Uso de recursos
htop
df -h
free -h

# Logs en tiempo real
journalctl -u flotillas-api -f

# Conexiones activas
ss -tlnp

# Verificar puertos
netstat -tlnp

# Test de API
curl -s http://localhost:8000/api/v1/health | jq

# Test de base de datos
psql -U flotillas -d flotillas_db -c "SELECT COUNT(*) FROM vehiculos;"

# Ultimas ubicaciones
psql -U flotillas -d flotillas_db -c "
  SELECT v.nombre, u.tiempo, u.lat, u.lng, u.velocidad
  FROM ubicaciones u
  JOIN vehiculos v ON u.vehiculo_id = v.id
  ORDER BY u.tiempo DESC
  LIMIT 10;
"

# Alertas pendientes
psql -U flotillas -d flotillas_db -c "
  SELECT COUNT(*) as pendientes FROM alertas WHERE atendida = false;
"
```

---

## Contacto de Soporte

Si no puedes resolver el problema:

1. Recolectar informacion:
```bash
# Crear archivo de diagnostico
{
  echo "=== FECHA ==="
  date
  echo "=== SERVICIOS ==="
  systemctl status flotillas-api flotillas-web traccar mediamtx cloudflared
  echo "=== RECURSOS ==="
  free -h
  df -h
  echo "=== LOGS RECIENTES ==="
  journalctl -u flotillas-api -n 50 --no-pager
} > /tmp/diagnostico.txt
```

2. Enviar `diagnostico.txt` al equipo de soporte