Ingeniería · ArbeitszeitCheck

Anatomía de un fichaje sin conexión

30 de octubre de 2026 · Software by Design

12:07, la verja de una obra, ni una barra de cobertura. El trabajador ficha igualmente. Esto es todo lo que ese fichaje atraviesa antes de aterrizar en el parte de horas, y dónde podría haber salido mal.

Minuto cero: el teléfono no alcanza el servidor

La app móvil no reintenta a ciegas ni finge un éxito. El fichaje entra en una cola FIFO cifrada en el dispositivo, texto cifrado AES-GCM en AsyncStorage, con la clave de datos en SecureStore. Ese último detalle tiene una razón real: SecureStore limita los valores a unos dos kilobytes en Android, así que el diseño obvio (la cola en SecureStore y listo) nunca estuvo disponible. La cola en sí está limitada a 32 entradas, un búfer acotado, no una promesa infinita. El estado optimista muestra al trabajador «fichado» al instante. La cola se vacía cuando vuelve la cobertura.

El vaciado es deliberadamente quisquilloso: la app toma una instantánea de la cola bajo un mutex, hace el trabajo de red fuera del bloqueo y después fusiona el resultado, así un fichaje encolado durante un vaciado no es sobrescrito por la fusión. Esta es la clase de bug que solo encuentras siendo paranoico con las escrituras concurrentes.

El reenvío: reclama antes de mutar

Cuando el fichaje por fin llega al servidor, lleva dos cosas que un fichaje normal no lleva: un clientRequestIdcodeoccurredAt y una marca temporal payload_hashcodeoccurredAt. El servidor no lo aplica directamente. Primero escribe una fila de reclamación«este id de petición ahora es mío, resultado pendiente». Solo entonces modifica el parte de horas. Si dos reintentos compiten, el segundo encuentra la reclamación ya tomada y recibe el resultado del primer intento en lugar de un fichaje doble.

La fila de reclamación lleva un failedcode, sha256 sobre la acción y sus entradas normalizadas. El mismo id de petición con una carga diferente responde 409, no una sobrescritura silenciosa: un cliente que reintenta «fichar entrada» y reenvía por accidente «fichar salida» recibe un error que puede ver, no datos corruptos. Las reclamaciones pendientes más de 300 segundos se recuperan. Toda la ventana de reenvío es de siete días, tras lo cual una tarea de limpieza borra las filas.

De quién es el reloj que cuenta

Los relojes de los teléfonos derivan y pueden atrasarse a propósito, así que el cumplimiento se evalúa en code, el momento en que el trabajador fichó de verdad, no en la hora de llegada. Hasta dónde confía el servidor en esa marca es un ajuste de administración acotado: desfase configurable entre 24 y 72 horas hacia atrás, cinco minutos hacia el futuro. El techo es deliberado. Un fichaje «del jueves pasado» necesita un humano que lo mire, no un algoritmo que se lo crea.

La vía kiosco recibe el mismo contrato con sus propias complicaciones: una caché cifrada de tarjetas NFC (TTL de siete días, limitada a 500 entradas) para que un terminal de pasillo en un sótano siga abriendo la pantalla de acción correcta durante un apagón, y un vaciado exitoso escribe el nuevo estado de vuelta en esa caché, si no, el siguiente apagón ofrecería al trabajador acciones que ya son incorrectas.

Lo que aún falta, para que conste

Dos carencias. Un fichaje que falla permanentemente se queda en la cola marcado code, el usuario ve un toast, pero aún no hay UI de reintento por fila. Y las versiones antiguas de la app que no conocen los campos nuevos simplemente fichan solo en línea. Nada se rompe, solo pierden la función. Ambas están escritas en el documento de decisión porque el peor tipo de limitación es la que nadie documentó.

El expediente de decisión completo, incluido el orden de bloqueo y la tarea de limpieza, vive en el repositorio que la AGPL le garantiza poder leer. Esa es la otra mitad de la respuesta de este artículo: la cola no solo está diseñada para sobrevivir a una zona muerta, está documentada para que pueda comprobarlo.