Entwicklung · ArbeitszeitCheck
Anatomie eines Offline-Stempels
12:07 Uhr, ein Baustellentor, kein Empfang. Die Arbeitskraft stempelt trotzdem ein. Hier ist alles, was dieser Stempel durchläuft, bevor er im Stundenzettel landet, und wo es hätte schiefgehen können.
Minute null: Das Telefon erreicht den Server nicht
Die mobile App versucht es nicht blind erneut und täuscht auch keinen Erfolg vor. Der Stempel wandert in eine verschlüsselte FIFO-Warteschlange auf dem Gerät, AES-GCM-Geheimtext in AsyncStorage, der Datenschlüssel liegt in SecureStore. Dieses letzte Detail hat einen realen Grund: SecureStore begrenzt Werte unter Android auf grob zwei Kilobyte, sodass der naheliegende Entwurf (Warteschlange in SecureStore, fertig) nie verfügbar war. Die Warteschlange selbst ist auf 32 Einträge gedeckelt, ein begrenzter Puffer, kein unendliches Versprechen. Der optimistische Status zeigt der Arbeitskraft sofort „eingestempelt“. Die Warteschlange leert sich, sobald der Empfang zurückkehrt.
Das Leeren ist absichtlich heikel: Die App erstellt unter einem Mutex einen Snapshot der Warteschlange, erledigt die Netzwerkarbeit außerhalb der Sperre und mergt das Ergebnis anschließend zurück, damit ein Stempel, der während des Leerens eingereiht wird, nicht vom Merge überschrieben wird. Das ist die Klasse von Fehlern, die man nur findet, wenn man bei konkurrierenden Schreibzugriffen paranoid ist.
Das Replay: Erst claimen, dann ändern
Wenn der Stempel den Server schließlich erreicht, trägt er zwei Dinge, die ein normaler Stempel nicht hat: eine clientRequestId und einen occurredAt-Zeitstempel. Der Server wendet ihn nicht direkt an. Er schreibt zuerst eine Claim-Zeile: „diese Request-ID gehört jetzt mir, Ergebnis ausstehend“. Erst dann ändert er den Stundenzettel. Wenn zwei Wiederholungen miteinander racen, findet die zweite den Claim bereits vergeben vor und bekommt das Ergebnis des ersten Versuchs statt eines Doppelstempels.
Die Claim-Zeile trägt einen payload_hash, sha256 über die Aktion und ihre normalisierten Eingaben. Dieselbe Request-ID mit einer anderen Payload beantwortet er mit 409, nicht mit einem stillen Überschreiben: Ein Client, der „einstempeln“ wiederholt und versehentlich „ausstempeln“ sendet, bekommt einen sichtbaren Fehler, keine korrupten Daten. Claims, die länger als 300 Sekunden ausstehend bleiben, werden zurückgefordert. Das gesamte Replay-Fenster beträgt sieben Tage, danach löscht ein Aufräumjob die Zeilen.
Wessen Uhr zählt
Telefonuhren driften und können absichtlich zurückgestellt werden. Deshalb wird die Einhaltung zum Zeitpunkt occurredAt bewertet, also zu dem Moment, in dem die Arbeitskraft tatsächlich gestempelt hat, nicht zur Ankunftszeit beim Server. Wie weit der Server diesem Zeitstempel vertraut, ist eine begrenzte Admin-Einstellung: konfigurierbare Abweichung zwischen 24 und 72 Stunden zurück, fünf Minuten in die Zukunft. Die Obergrenze ist Absicht. Ein Stempel „von letztem Donnerstag“ braucht einen Menschen, der ihn anschaut, keinen Algorithmus, der ihm glaubt.
Der Kiosk-Pfad bekommt denselben Vertrag mit eigenen Tücken: ein verschlüsselter NFC-Badge-Cache (sieben Tage TTL, gedeckelt auf 500 Einträge), damit ein Flur-Terminal im Keller bei einem Ausfall noch den richtigen Aktionsbildschirm öffnet, und ein erfolgreiches Leeren schreibt den neuen Status zurück in diesen Cache, sonst würde der nächste Ausfall der Arbeitskraft Aktionen anbieten, die längst falsch sind.
Was noch fehlt, aktenkundig
Zwei Lücken. Ein Stempel, der dauerhaft fehlschlägt, bleibt als code markiert in der Warteschlange, der Nutzer sieht einen Toast, aber es gibt noch keine Retry-UI pro Zeile. Und alte App-Versionen, die die neuen Felder nicht kennen, stempeln schlicht nur online. Nichts bricht, sie verlieren nur die Funktion. Beides steht im Entscheidungsdokument, weil die schlimmste Art von Einschränkung die ist, die niemand dokumentiert hat.
Die vollständige Entscheidungsakte, einschließlich Sperrreihenfolge und Aufräumjob, liegt im Repository, das Ihnen die AGPL zu lesen garantiert. Das ist die zweite Hälfte der Antwort dieses Beitrags: Die Warteschlange ist nicht nur so gebaut, dass sie eine Funkstille übersteht. Sie ist auch so dokumentiert, dass Sie es nachprüfen können.