Engineering · ArbeitszeitCheck

Anatomie van een offline-stempel

30 oktober 2026 · Software by Design

12:07, een bouwplaatspoort, geen bereik. De medewerker klokt toch in. Hier is alles wat die stempel doorstaat voordat hij in de urenregistratie landt, en waar het mis had kunnen gaan.

Minuut nul: de telefoon bereikt de server niet

De mobiele app probeert het niet blindelings opnieuw en doet ook niet alsof het gelukt is. De stempel gaat een versleutelde FIFO-wachtrij op het toestel in, AES-GCM-ciphertekst in AsyncStorage, met de datasleutel in SecureStore. Dat laatste detail heeft een echte reden: SecureStore begrenst waarden op grofweg twee kilobyte op Android, dus het voor de hand liggende ontwerp (wachtrij in SecureStore, klaar) was nooit beschikbaar. De wachtrij zelf is begrensd op 32 items, een afgebakende buffer, geen oneindige belofte. De optimistische status toont de medewerker meteen als «ingeklokt». De wachtrij leegt zodra het bereik terugkeert.

Het legen is bewust pietluttig: de app maakt onder een mutex een snapshot van de wachtrij, doet het netwerkwerk buiten de lock en merget het resultaat daarna terug, zodat een stempel die tijdens een legrun wordt toegevoegd niet door de merge wordt overschreven. Dit is het soort bug dat je alleen vindt door paranoïde te zijn over gelijktijdige schrijfacties.

Het nazenden: eerst claimen, dan muteren

Als de stempel eindelijk de server bereikt, draagt hij twee dingen die een normale stempel niet heeft: een clientRequestIdcodeoccurredAt en een payload_hashcodeoccurredAt-tijdstempel. De server past hem niet direct toe. Hij schrijft eerst een claim-rij«deze request id is nu van mij, uitkomst in behandeling». Pas daarna muteert hij de urenregistratie. Racen twee retries, dan vindt de tweede de claim al bezet en krijgt hij de uitkomst van de eerste poging in plaats van een dubbele stempel.

De claim-rij draagt een failedcode, sha256 over de actie en zijn genormaliseerde invoer. Dezelfde request id met een andere payload antwoordt met 409, geen stille overschrijving: een client die «inklokken» opnieuw probeert en per ongeluk «uitklokken» meestuurt krijgt een zichtbare fout, geen corrupte data. Claims die langer dan 300 seconden in behandeling blijven worden teruggevorderd. Het hele replay-venster is zeven dagen, waarna een opschoningsjob de rijen verwijdert.

Wiens klok telt

Telefoonklokken lopen voor en kunnen bewust teruggezet worden, dus compliance wordt beoordeeld op code, het moment waarop de medewerker echt stempelde, niet op aankomsttijd. Hoe ver de server die tijdstempel vertrouwt is een begrensde beheerdersinstelling: configureerbare skew tussen 24 en 72 uur terug, vijf minuten vooruit. Het plafond is bewust. Een stempel «van vorige week donderdag» heeft een mens nodig die ernaar kijkt, geen algoritme dat het gelooft.

Het kiosk-pad krijgt hetzelfde contract met eigen rimpels: een versleutelde NFC-badgecache (TTL van zeven dagen, begrensd op 500 items) zodat een gangterminal in een kelder tijdens een storing nog steeds het juiste actiescherm opent, en een geslaagde legrun schrijft de nieuwe status terug in die cache, anders zou de volgende storing de medewerker acties aanbieden die al niet meer kloppen.

Wat er nog mist, zwart op wit

Twee gaten. Een stempel die definitief mislukt blijft in de wachtrij staan, gemarkeerd als code, de gebruiker ziet een toast, maar een retry-UI per rij is er nog niet. En oude app-versies die de nieuwe velden niet kennen klokken gewoon online-only. Er breekt niets, ze verliezen alleen de feature. Beide staan in het decision doc omdat de ergste beperking degene is die niemand heeft gedocumenteerd.

Het volledige decision record, inclusief de lockvolgorde en de opschoningsjob, staat in de repository die de AGPL je garandeert te kunnen lezen. Dat is de andere helft van het antwoord van deze post: de wachtrij is niet alleen zo ontworpen dat hij een dode zone overleeft, hij is zo gedocumenteerd dat je dat kunt controleren.