𝗠𝗶 𝗔𝗣𝗜 𝗳𝗮𝗹𝗹𝗮𝗯𝗮 𝗰𝗮𝗱𝗮 𝟭 𝗱𝗲 𝗲𝗻𝗲𝗿𝗼
Mi API falló exactamente a las 00:00 UTC el 1 de enero.
No falló a la medianoche de los usuarios. Falló a la medianoche UTC. Los usuarios en Tokio vieron datos erróneos a partir de las 9 AM de su hora local.
Las pruebas pasaron. El entorno de staging funcionó. El error solo existía en producción porque el servidor de producción utilizaba una zona horaria diferente a la de staging.
El problema residía en esta lógica:
function getDailyReport(date) {
const start = new Date(date).toISOString().split('T')[0];
const end = new Date(start + 'T23:59:59Z');
return db.reports.findMany({
where: {
createdAt: { gte: new Date(start), lt: end }
}
});
}
Cuando pasas una fecha como "2026-01-01" sin una hora, el sistema utiliza la zona horaria local.
Nuestro servidor de staging usaba UTC. Nuestro servidor de producción usaba US-East. Esto creaba un desfase de cinco horas en cada consulta de fecha.
Perdimos cinco horas de datos en cada consulta. Los números parecían lo suficientemente cercanos como para que nadie lo notara durante un año entero.
La solución fue sencilla. Forzar UTC añadiendo la hora a la cadena:
function getDailyReport(date: string) {
const start = new Date(`${date}T00:00:00Z`);
const end = new Date(`${date}T23:59:59.999Z`);
return db.reports.findMany({
where: {
createdAt: { gte: start, lt: end }
}
});
}
El cambio de código tomó segundos. La solución del sistema tomó una semana. Hicimos estas cuatro cosas:
• Añadimos una aserción de zona horaria en CI para asegurar que el entorno se mantenga en UTC. • Establecimos TZ=UTC en todos los Dockerfiles para mantener cada contenedor idéntico. • Añadimos una comprobación de zona horaria al script de despliegue. • Escribimos una regla de linter para marcar cualquier constructor de Date que carezca de información de zona horaria.
Los errores de zona horaria son peligrosos. No hacen que tu sistema colapse. Producen datos incorrectos que parecen correctos. Tus usuarios no verán una página de error. Verán números incorrectos y confiarán en ellos.
Sigue estas tres reglas:
- Nunca confíes en la zona horaria del sistema. Configura siempre TZ=UTC.
- Nunca proceses fechas sin zonas horarias.
- Nunca asumas que la zona horaria de tu CI coincide con la de producción.