Engenharia · ArbeitszeitCheck

A anatomia de um registo offline

30 de outubro de 2026 · Software by Design

12:07, portão de um estaleiro, sem rede. O trabalhador regista a entrada à mesma. Aqui está tudo o que esse registo atravessa antes de aterrar no mapa de horas, e onde podia ter corrido mal.

Minuto zero: o telefone não chega ao servidor

A app móvel não tenta de novo às cegas e não finge sucesso. O registo entra numa fila FIFO cifrada no dispositivo, texto cifrado AES-GCM em AsyncStorage, com a chave de dados no SecureStore. Este último detalhe tem uma razão real: o SecureStore limita os valores a cerca de dois kilobytes no Android, por isso o desenho óbvio (fila no SecureStore, despachado) nunca esteve disponível. A própria fila tem um teto de 32 entradas, um buffer limitado, não uma promessa infinita. O estado otimista mostra o trabalhador «em serviço» de imediato. A fila esvazia-se quando a cobertura volta.

O esvaziamento é propositadamente picuinhas: a app faz um snapshot da fila sob um mutex, executa o trabalho de rede fora do bloqueio e depois funde o resultado de volta, assim um registo enfileirado durante um esvaziamento não é sobrescrito pela fusão. É a classe de erro que só se encontra sendo paranóico com escritas concorrentes.

O replay: reclamar antes de alterar

Quando o registo finalmente chega ao servidor traz duas coisas que um registo normal não traz: um clientRequestIdcodeoccurredAt e um carimbo temporal payload_hashcodeoccurredAt. O servidor não o aplica diretamente. Escreve primeiro uma linha de claim«este id de pedido agora é meu, resultado pendente». Só então altera o mapa de horas. Se duas repetições correm em paralelo, a segunda encontra o claim já tomado e recebe o desfecho da primeira tentativa em vez de um registo duplo.

A linha de claim leva um failedcode, sha256 sobre a ação e as suas entradas normalizadas. O mesmo id de pedido com um payload diferente responde 409, não uma sobreposição silenciosa: um cliente que repete «registar entrada» e reenvia por engano «registar saída» recebe um erro visível, não dados corrompidos. Claims pendentes há mais de 300 segundos são recuperados. A janela de replay inteira é de sete dias, findos os quais uma tarefa de limpeza apaga as linhas.

De quem é o relógio que conta

Os relógios dos telefones derivam e podem ser postos para trás de propósito, por isso a conformidade é avaliada no code, o momento em que o trabalhador registou de fato, não no momento de chegada. Até onde o servidor confia nesse carimbo é uma definição de administração limitada: skew configurável entre 24 e 72 horas para trás, cinco minutos para o futuro. O teto é deliberado. Um registo «de quinta-feira passada» precisa de uma pessoa que olhe para ele, não de um algoritmo que acredite nele.

O caminho do quiosque tem o mesmo contrato com as suas próprias dobras: uma cache de cartões NFC cifrada (TTL de sete dias, teto de 500 entradas) para que um terminal de corredor numa cave continue a abrir o ecrã de ação certo durante uma falha, e um esvaziamento bem-sucedido escreve o novo estado de volta nessa cache, caso contrário a falha seguinte ofereceria ao trabalhador ações que já estão erradas.

O que ainda falta, assumido por escrito

Duas lacunas. Um registo que falha permanentemente fica na fila marcado code, o utilizador vê um toast, mas ainda não há UI de repetição por linha. E as versões antigas da app, que não conhecem os novos campos, simplesmente registam só online. Nada quebra, apenas perdem a funcionalidade. Ambas estão escritas no documento de decisão porque o pior tipo de limitação é a que ninguém documenta.

O registo completo da decisão, incluindo a ordem dos bloqueios e a tarefa de limpeza, vive no repositório que a AGPL garante que podem ler. É a outra metade da resposta deste artigo: a fila não foi só desenhada para sobreviver a uma zona morta. Está documentada para que possam verificar que sobrevive.