O fuso horário é do cliente, não do servidor

Servidores costumam rodar em UTC. Computadores de desenvolvimento rodam no fuso de quem programa. Clientes vivem no fuso deles. Quando um sistema mistura os três sem perceber, aparecem os erros mais difíceis de explicar: o lembrete que chegou na hora errada, o relatório do dia que inclui vendas da madrugada seguinte, a dose marcada como atrasada antes da hora.

"Hoje" depende de quem pergunta

Às 22h em São Paulo já é o dia seguinte em UTC. Se o sistema calcula "as tarefas de hoje" pelo relógio do servidor, um cliente que abre o app à noite vê a lista de amanhã. Ninguém percebe nos testes, porque quem testa costuma fazer isso de dia.

A regra que seguimos: toda data que tem significado para uma pessoa — hoje, esta semana, este mês — é calculada no fuso do cliente, nunca no da máquina. No sistema para pet centers, o fuso é do estabelecimento. No app de remédios de pets, é da família.

Guarde o nome do fuso, não o deslocamento

Um erro sutil é guardar o fuso como "-3 horas". O deslocamento muda com horário de verão, e países diferentes mudam em datas diferentes. Quando um dos nossos produtos começou a ser usado nos Estados Unidos, isso deixou de ser teoria. Por isso guardamos o nome do fuso — como America/Sao_Paulo ou America/New_York — e deixamos a biblioteca de datas calcular o deslocamento certo para cada dia.

Uma família, um relógio

No app de remédios, várias pessoas da mesma família marcam as doses. Se cada uma usasse o fuso do próprio celular, uma pessoa viajando faria a grade inteira andar. A decisão foi ter um fuso por família: a rotina do animal segue a casa, não o celular de quem marcou.

Teste à meia-noite

O teste que mais encontra problemas é rodar o sistema simulando o relógio às 23h50 e à 0h10, no fuso do cliente e num fuso diferente. Se "hoje" mudar de forma estranha, há uma data sendo calculada no lugar errado.