checklist/TIMEZONE_SETUP.md

Configuración de Zona Horaria - Atlantic/Canary

Cambios Implementados

Se ha configurado la zona horaria de Atlantic/Canary (Islas Canarias, España) en toda la aplicación:

1. Base de Datos PostgreSQL

• Zona horaria: Atlantic/Canary (UTC+0 en invierno, UTC+1 en verano con horario de verano)
• Variables de entorno agregadas:
  • TZ=Atlantic/Canary
  • PGTZ=Atlantic/Canary

2. Backend FastAPI

• Configuración de zona horaria de Python al inicio de la aplicación
• Conexión a PostgreSQL configurada con timezone
• Event listener para establecer timezone en cada conexión
• Variable de entorno: TZ=Atlantic/Canary

3. Frontend React

• Los filtros de fecha usan el constructor de Date con zona horaria local
• Las fechas se muestran en formato español (es-ES)

Aplicar los Cambios

Desarrollo Local

1. Parar los contenedores actuales:

   docker-compose down
   

2. Aplicar la migración de zona horaria a la base de datos:

   docker-compose up -d postgres
   
   # Esperar a que PostgreSQL esté listo
   Start-Sleep -Seconds 5
   
   # Aplicar migración
   docker-compose exec postgres psql -U checklist_user -d checklist_db -f /docker-entrypoint-initdb.d/../migrations/set_timezone_canary.sql
   

   Alternativa manual:

   # Copiar el archivo SQL al contenedor
   docker cp migrations/set_timezone_canary.sql checklist-db:/tmp/
   
   # Ejecutarlo
   docker-compose exec postgres psql -U checklist_user -d checklist_db -f /tmp/set_timezone_canary.sql
   

3. Reconstruir y levantar todos los servicios:

   docker-compose build
   docker-compose up -d
   

4. Verificar la configuración:

   # Verificar timezone en PostgreSQL
   docker-compose exec postgres psql -U checklist_user -d checklist_db -c "SHOW timezone;"
   
   # Verificar timezone en backend
   docker-compose exec backend python -c "import time; print(time.tzname)"
   

Producción

Docker Compose Production

1. Parar servicios:

   docker-compose -f docker-compose.prod.yml down
   

2. Aplicar migración:

   docker-compose -f docker-compose.prod.yml up -d postgres
   docker cp migrations/set_timezone_canary.sql syntria-db-prod:/tmp/
   docker-compose -f docker-compose.prod.yml exec postgres psql -U syntria_user -d syntria_db -f /tmp/set_timezone_canary.sql
   

3. Reconstruir imágenes y desplegar:

   ./build-and-push.sh  # o build-and-push.ps1 en Windows
   docker-compose -f docker-compose.prod.yml pull
   docker-compose -f docker-compose.prod.yml up -d
   

Docker Swarm

1. Aplicar migración en el nodo manager:

   # Encontrar el contenedor de PostgreSQL
   docker ps | grep syntria_db
   
   # Copiar y ejecutar migración
   docker cp migrations/set_timezone_canary.sql <container_id>:/tmp/
   docker exec <container_id> psql -U syntria_user -d syntria_db -f /tmp/set_timezone_canary.sql
   

2. Actualizar stack:

   docker stack deploy -c docker-stack.yml syntria
   

Verificación Post-Despliegue

1. Verificar Zona Horaria de PostgreSQL

-- Debería mostrar: Atlantic/Canary
SHOW timezone;

-- Verificar hora actual del servidor
SELECT NOW();
SELECT CURRENT_TIMESTAMP;

2. Verificar Backend

docker-compose exec backend python -c "
from datetime import datetime
import time
print('Timezone:', time.tzname)
print('Hora actual:', datetime.now())
print('UTC:', datetime.utcnow())
"

3. Probar en la Aplicación

1. Crear una nueva inspección
2. Verificar que la fecha/hora de inicio coincida con la hora local de Canarias
3. Filtrar por fecha y verificar que el filtro funcione correctamente

Comportamiento de las Fechas

Fechas Existentes

• Las fechas ya guardadas en la base de datos no se modifican
• PostgreSQL las almacena internamente en UTC
• Se mostrarán en hora de Canarias al consultarlas

Nuevas Fechas

• Se guardarán con timezone de Canarias
• Se convertirán automáticamente a UTC para almacenamiento
• Se mostrarán en hora de Canarias al recuperarlas

Horario de Verano

La zona horaria Atlantic/Canary maneja automáticamente el horario de verano:

• Invierno (octubre - marzo): UTC+0 / WET (Western European Time)
• Verano (marzo - octubre): UTC+1 / WEST (Western European Summer Time)

Troubleshooting

Las fechas siguen mostrándose incorrectas

1. Verificar que los contenedores se reiniciaron después de los cambios:

   docker-compose restart
   

2. Verificar logs del backend:

   docker-compose logs backend | Select-String -Pattern "timezone|TZ"
   

3. Limpiar caché del navegador y recargar la aplicación

Error al conectar a la base de datos

Si ves errores relacionados con timezone al conectar:

could not find timezone "Atlantic/Canary"

Solución:

# Entrar al contenedor de PostgreSQL
docker-compose exec postgres sh

# Instalar datos de zona horaria (si no están instalados)
apk add --no-cache tzdata

# Salir y reiniciar
exit
docker-compose restart postgres

Las fechas en el frontend no coinciden

El frontend usa la zona horaria del navegador del usuario. Si el usuario está en una zona diferente a Canarias, verá las fechas en su hora local. Para forzar visualización en hora de Canarias en el frontend, se pueden usar bibliotecas como date-fns-tz o luxon.

Archivos Modificados

• ✅ docker-compose.yml - Variables TZ para postgres y backend
• ✅ docker-compose.prod.yml - Variables TZ para postgres y backend
• ✅ docker-stack.yml - Variables TZ para db y backend
• ✅ backend/app/core/database.py - Configuración de conexión con timezone
• ✅ backend/app/main.py - Configuración de TZ de Python
• ✅ migrations/set_timezone_canary.sql - Script de migración
• ✅ frontend/src/App.jsx - Uso correcto de fechas locales

Notas Importantes

⚠️ Después de aplicar estos cambios en producción:

• Hacer backup de la base de datos antes de aplicar cambios
• Aplicar en horario de bajo tráfico
• Verificar que todas las funcionalidades de fecha/hora funcionan correctamente
• Informar a los usuarios si hay cambios visibles en las fechas mostradas