# Werkjournal Private Arbeitszeit- und Habit-Erfassung mit Kotlin, Vaadin Flow und Spring Boot. **Stand: E-Mail-Anmeldung aktiv; Ersteinrichtung erfolgreich bestätigt.** Private Konten und der getrennte gemeinsame Gastzugang sind verfügbar. Vorhandene Daten müssen bei allen weiteren Migrationen erhalten bleiben. ## Planung und Arbeitsweise - `werkjournal.werkbaum`: Entscheidungen und aktueller Umsetzungsstand. - `gherkin/`: englische Abnahmeszenarien; noch nicht vollständig implementiert. - `docs/implementation/`: geprüfte Infrastruktur, Toolchain und Testzuordnung. Ein Umsetzungsknoten wird vor Beginn mit `[~]` committet und gepusht. Nach erfolgreicher Prüfung folgt `[x]` mit Abschlusscommit und Push. Abgeschlossene Entscheidungen sind ausdrücklich als solche beschriftet und nicht mit ausgelieferter Funktion gleichzusetzen. ## Anwendung bauen ```bash ./gradlew test bootJar -Pproduction=true ``` Der gepinnte Gradle-Wrapper prüft seine Distribution per SHA-256. Build und Tests verwenden Temurin JDK 25; Download und Prüfsumme sind in `packaging/jdk.properties` fixiert. Das Produktionsartefakt ist `build/libs/werkjournal.jar`. `tools/ci-jvm` baut, testet und prüft das JAR mit 256 MiB Heap und 192 MiB Metaspace in einer isolierten Testumgebung. ```bash cp .env.example .env remote backend install-jdk # Nach Änderung des gepinnten JDK-Stands: remote backend install-jdk --force ``` Die Installation benötigt keine Root-Rechte, verwendet eine SSH-Verbindung und aktiviert erst das vollständig heruntergeladene, geprüfte JDK. Ziel ist standardmäßig `~/opt/jdk25` beim Werkjournal-User. Bestehende JDK-Releases bleiben erhalten, damit laufende JVMs ihre Bibliotheken weiter erreichen. Geheimnisse gehören nicht in die JDK-Konfiguration. GraalVM ist optional zurückgestellt. Nur `-Pnative=true` aktiviert dessen Gradle-Plugin; `tools/ci-native` bleibt ein experimenteller Einstieg ohne CI-Trigger oder Freigabeanspruch. Die bisherigen Ergebnisse stehen in `docs/implementation/native-spike.md`. Die Anwendung bindet standardmäßig an `127.0.0.1:18090`. `/api/v1/info` liefert die Buildversion, `/` das Heute-Dashboard. Ein separates Bookworm-Rootfs für Werkdock lässt sich lokal über `tools/build-rootfs` vorbereiten. Dazu wird ein lokaler Docker-Dienst verwendet; auf Hostsharing laufen Builds anschließend in Werkdock. Die erzeugten Dateien liegen unter dem git-ignorierten `work/`. Mit direnv und `direnv allow` nimmt `.envrc` das Verzeichnis `tools/` in den PATH auf. Produktionsgeheimnisse bleiben außerhalb des Repositorys. ## Konten und Gastzugang Auf dem Server ist `WERKJOURNAL_GUEST_MODE=false` gesetzt. Die Loginseite bietet E-Mail-Anmeldung und einen ausdrücklichen Gastzugang. Der bisherige gemeinsame Gastbereich bleibt getrennt von privaten Konten. Die Datenbank liegt unter `data/werkjournal.mv.db`. Die frühere Erlaubnis, Gastdaten zu verwerfen, gilt nicht mehr. Migrationen benötigen erhaltende Changesets, einen Test mit befülltem Vorgängerstand und eine konsistente Sicherung vor der Migration; siehe `docs/implementation/deployment.md`. Das Datenfundament ist unter `docs/implementation/foundation.md` beschrieben. Die Kunden-/Projektpflege ist unter `/catalog` verfügbar. Der Quellstand enthält unter `/habits` frei konfigurierbare Gewohnheiten mit Tageszählern und optionalen Tages-/Wochenminima und -maxima. Grenzen sind Hinweise und blockieren das Zählen nicht. Einmalige, veränderbare Startvorgaben sind Kunde/Projekt „Allgemein“ sowie „Lesen“ und „Spaziergänge“ (Tagesminimum 1, Wochenminimum 5). Details und Testnachweise: `docs/implementation/habits.md`. Unter `/work` lassen sich Arbeitszeiten erfassen und ändern; Konflikte erhalten den Entwurf und erfordern eine ausdrückliche Auflösung. Entwürfe bleiben pro Tab erhalten und lassen sich auf demselben Gerät wiederaufnehmen. Details: `docs/implementation/work.md`. Dieser Funktionsstand ist öffentlich verfügbar. ## Erstdeployment ```bash remote backend deploy-prototype --artifact /pfad/zum/geprueften-ci-release ``` Das Verzeichnis enthält `werkjournal.jar` und das dazugehörige `manifest.json` aus einem erfolgreichen Werkator-Build. Der Befehl prüft den Hash lokal und auf dem Zielserver und baut nicht neu. Er richtet den systemd-User-Service sowie HTTP-Weiterleitung und HTTPS-Proxy auf dem Werkjournal-Host ein. Bereits vorhandene Releases, Dienste oder H2-Dateien werden abgelehnt: für reguläre Upgrades mit Datensicherung und Rollback dient `remote backend deploy`. Betriebsstand, Verzeichnisse und Prüfergebnisse: `docs/implementation/first-deploy.md`. Der laufende Dienst lässt sich mit `remote backend status` prüfen und mit `remote backend start|stop|restart` steuern. `remote backend enable|disable` ändert nur den Autostart. `remote backend log --lines 30` zeigt Journalzeilen, `remote backend log --follow` folgt neuen Meldungen. Mutierende Befehle verwenden die Deployment-Sperre; vorhandene Wartung bleibt bestehen. Details und Fehlerfälle: `docs/implementation/service-control.md`. `remote backend setup` schreibt die versionierte Unit und lädt systemd neu, ohne den Dienst neu zu starten. `remote backend info` prüft Version/Commit sowie interne und öffentliche Bereitschaft. `remote ssh [COMMAND ARG...]` öffnet eine Shell oder führt einen Befehl mit getrennten Argumenten aus. Details und vollständiger Befehlsabgleich: `docs/implementation/remote-utilities.md`. Die angebundenen Fach- und Chromium-Gherkin-Szenarien laufen im normalen Testlauf mit. Die vollständige Pipeline ergänzt die Firefox-Abnahme und den Produktions-JAR-Smoke. Lokal zuerst die gepinnten Browser installieren: ```sh JAVA_HOME=/pfad/zum/jdk25 ./gradlew --no-daemon installBrowsers ``` Der Werkdock-Build nutzt die Browser aus seinem vorbereiteten Image. Fehlende Browser werden im Testlauf nicht automatisch heruntergeladen oder übersprungen. | Bereich | Suite | Details | |---|---|---| | Arbeitszeit | `WorkCucumberTest` | `docs/implementation/work-gherkin.md` | | Habits | `HabitCucumberTest` | `docs/implementation/habit-gherkin.md` | | Push | `PushCucumberTest` | `docs/implementation/push-gherkin.md` | | Konten | `IdentityCucumberTest` | `docs/implementation/identity-gherkin.md` | | Chromium | `BrowserCucumberTest` | `docs/implementation/browser-gherkin.md` | | Firefox | `firefoxAcceptance` | `docs/implementation/firefox-acceptance.md` | | Produktions-JAR | `productionAcceptance` | `docs/implementation/production-smoke-gherkin.md` | Aufruf beispielsweise: `./gradlew test --tests '*BrowserCucumberTest' -Pproduction=true` mit gesetztem `JAVA_HOME`. Berichte stehen unter `build/reports/cucumber`; noch offene Bindungen in `docs/implementation/acceptance.md`. ## Erste Gastvorschau `remote backend deploy-guest-preview --artifact DIRECTORY` ermöglicht ausschließlich den einmaligen Wechsel vom bekannten datenlosen Prototyp. Der Übergang wurde ausgeführt. Bei vorhandener Datenbank verweigert der Befehl weitere Deployments; allgemeine sichere Upgrades erfolgen über `remote backend deploy`. Details: `docs/implementation/guest-preview.md`. Die zentrale [Betriebsanleitung](docs/RUNBOOK.md) beschreibt Konfiguration, Releases, Wiederherstellung, Admin-Recovery und den geplanten Trixie-Wechsel. ## Updates und Wiederherstellung ```bash remote backend deploy --artifact /pfad/zum/geprueften-ci-release remote backend recover ``` Mit `remote backend upload --artifact DIRECTORY` lässt sich ein geprüftes Release vorab bereitstellen. Es bleibt inaktiv, bis `remote backend deploy --artifact DIRECTORY` es mit Sicherung und Bereitschaftsprüfung aktiviert. Ein gewöhnlicher Neustart aktiviert den Upload nicht. Details: `docs/implementation/candidate-upload.md`. `remote backend backup [FILE]` erstellt eine konsistente private Sicherung von H2-Daten und passendem Programmstand. Ohne Dateinamen landet sie in `backups/`. Der Dienst wird dafür kurz unter Wartung gestoppt und anschließend nur dann wieder gestartet, wenn er vorher lief. Vorhandene Dateien werden nicht überschrieben. Ablauf und Fehlerbehandlung: `docs/implementation/operator-backup.md`. `remote backend restore --backup FILE` spielt diese Sicherung erst nach expliziter Bestätigung ein und sichert zuvor den bisherigen Stand. `remote backend restore --recover` behandelt einen unterbrochenen Versuch. Vorab lässt sich die Sicherung mit `JAVA_HOME=/path/to/jdk25 tools/probe-restore --backup FILE` isoliert prüfen. Details: `docs/implementation/operator-restore.md`. Updates verwenden Wartungsseite, Dienststopp, konsistente H2-Dateisicherung und einen dauerhaften Wiederherstellungszustand. Überholte Kandidaten werden abgewiesen. Ein fehlgeschlagener Versuch bleibt in der Pipeline fehlgeschlagen, auch wenn die bisherige Version erfolgreich wiederhergestellt wurde. Einzelheiten: `docs/implementation/deployment.md`. Werkator führt dieses Deployment nach erfolgreichem Build im selben Pipeline-Skript aus. ## Push-Schlüssel vorbereiten Mit `remote backend setup-push` werden die VAPID-Schlüssel direkt auf dem Server in der geschützten systemd-Umgebungsdatei erzeugt. Wiederholter Aufruf erhält die vorhandenen Schlüssel. Der Befehl startet keinen Dienst neu und aktiviert keinen Versand. Details: `docs/implementation/web-push-transport.md`.