No description
  • TypeScript 47.7%
  • Go 47.4%
  • CSS 3.9%
  • JavaScript 0.4%
  • Go Template 0.3%
  • Other 0.3%
Find a file
Jonas Leder 1999fcd96b
Some checks are pending
ci / backend-test (push) Waiting to run
ci / frontend-test (push) Waiting to run
ci / backend-docker (push) Blocked by required conditions
ci / frontend-docker (push) Blocked by required conditions
ci / chart (push) Blocked by required conditions
ci / build (push) Waiting to run
ci / build-1 (push) Waiting to run
ci / build-2 (push) Blocked by required conditions
Merge pull request 'Revert Renovate PRs merged with failed pipelines' (#44) from revert-failed-renovate into master
2026-11-18 23:07:54 +00:00
.forgejo/workflows CI: app version defaults to the commit SHA in the helm workflow 2026-11-18 01:37:42 +01:00
backend Revert "Merge pull request 'fix(deps): update module github.com/go-sql-driver/mysql to v1.10.2' (#40) from renovate/github.com-go-sql-driver-mysql-1.x into master" 2026-11-19 00:07:50 +01:00
deploy/helm/timetracker fix(deploy): give the frontend pod the writable paths nginx needs 2026-11-04 15:28:58 +00:00
docs/plan feat(deploy): split non-secret chart config into ConfigMap and password into Secret 2026-11-04 14:27:09 +00:00
frontend Revert "Merge pull request 'chore(deps): update cgr.dev/chainguard/nginx docker digest to d660885' (#42) from renovate/cgr.dev-chainguard-nginx into master" 2026-11-19 00:07:50 +01:00
.gitignore ci: add gitlab pipeline for tests, images and helm chart; document deployment 2026-11-04 14:25:26 +00:00
docker-compose.yml Merge branch 'renovate/postgres-18.x' into 'master' 2026-11-07 11:08:23 +00:00
Makefile fix(deploy): give the frontend pod the writable paths nginx needs 2026-11-04 15:28:58 +00:00
README.md CI: port GitLab pipeline to Forgejo Actions 2026-11-18 00:57:34 +01:00
renovate.json add renovate config 2026-11-07 11:57:20 +01:00

Zeiterfassung

Zeiterfassung nach deutschen Standards: Timer (Start/Stopp), manuelle Einträge, Urlaub, Überstundensaldo und Export als CSV oder PDF.

  • Backend: Go, Gin, Gin-Logrus, swaggo, GORM, godotenv
  • Frontend: React, Vite, TypeScript
  • Datenbanken: SQLite (Standard), MariaDB, PostgreSQL

Die Planung liegt unter docs/plan.

Funktionen

  • Öffentliche Registrierung mit Benutzername und Passwort
  • Timer mit Start/Stopp und manuelle Einträge mit Von/Bis (Überlappungen werden abgelehnt)
  • Ort pro Eintrag (Auswahl vor dem Start, z. B. Büro, Homeoffice, Dienstreise); die Orte pflegt jede:r selbst in den Einstellungen
  • Verlauf pro Monat mit Blättern durch alle Monate, Tagessummen und Nachtragen von Lücken
  • Sollzeit pro Arbeitstag einstellbar (Standard 8 h, Wochenziel 40 h, Mo–Fr)
  • Urlaub als ganze Tage, Kontingent pro Jahr (Standard 30), Wochenenden nicht buchbar
  • Überstundensaldo mit optionalem Startsaldo, Wochen- und Monatssummen
  • Warnstufen für den Überstundensaldo, pro Benutzer einstellbar: erst Gelb, dann Rot (0 schaltet eine Stufe aus)
  • Mobil nutzbar und installierbar (PWA); Zeiten lassen sich auch ohne Netz erfassen und werden später gesendet
  • Export als CSV (Semikolon, UTF-8 mit BOM, Dezimalkomma) und PDF
  • Hinweise nach dem Arbeitszeitgesetz (ArbZG): Pausenhinweis ab 8 h, Warnung über 10 h
  • Gesetzliche Feiertage: bundesweite und die des eigenen Bundeslandes (in den Einstellungen wählbar). An Feiertagen ist kein Soll hinterlegt, Urlaub lässt sich dort nicht buchen. Nur vollständige Feiertage zählen; Feiertage, die nur in Teilen eines Landes gelten (z. B. Fronleichnam in Sachsen und Thüringen), fehlen.
  • Sitzungen: Jede Anmeldung ist eine Sitzung. Mit „Angemeldet bleiben“ läuft sie nicht ab, sonst nach 24 h. Im Tab „Sitzungen“ sind alle Anmeldungen zu sehen; dauerhafte lassen sich dort beenden, und ablaufende dauerhaft machen. Ein beendetes Gerät ist sofort abgemeldet.
  • PDF-Export: erst als Vorschau im Browser, danach herunterladen
  • Sprache: Deutsch und Englisch. Standard ist „Automatisch“ (Sprache des Browsers, Deutsch als Rückfall). In den Einstellungen oder über den Umschalter in der Navigation lässt sich „Deutsch“ oder „English“ festlegen; die Auswahl wird mit den Benutzereinstellungen gespeichert und gilt auf allen Geräten. Zahlen und Datumsangaben folgen der Sprache; die CSV-Datei bleibt im deutschen Format.
  • Oracle Fusion: Eine Woche (Montag bis Sonntag) kann als Zeitkarte an Oracle Fusion übertragen werden. Basis-URL und die numerische Oracle-PersonId stehen in den Einstellungen; die PersonId ist für jede Übertragung Pflicht. Der Bearer-Token wird abgefragt und nicht protokolliert. Auf Wunsch wird ein JWT-Token im Browser gemerkt, bis er abläuft (sein exp-Claim bestimmt das Ablaufdatum); beim Abmelden wird er gelöscht. Im Browser gespeicherte Tokens sind für Skripte erreichbar, die in der App laufen – deshalb nur auf eigenen Geräten merken. Erlaubt sind nur https-URLs auf *.oraclecloud.com ohne Pfad. Jeder Versuch wird mit Ergebnis festgehalten. Vor der ersten echten Übertragung die Feldnamen prüfen: GET <Basis-URL>/hcmRestApi/resources/latest/timeCards/describe.
  • Überstunden aus Oracle: Auf der Export-Seite liest „Saldo aus Oracle abrufen“ dein Überstunden-Konto (den aktiven Ausgleichsplan in Stunden, z. B. „Flex Time DE“) über planBalances und zeigt es neben dem lokalen Saldo. Erst „Differenz übernehmen“ verschiebt das lokale Anfangssaldo um die Differenz, sodass beide Salden übereinstimmen. Oracle zählt nur verarbeitete Zeitkarten; deshalb vorher die Wochen übertragen und die Zahlen prüfen.
  • Name: In den Einstellungen kann ein vollständiger Name hinterlegt werden. Er ersetzt in der App den Benutzernamen und steht im Kopf des PDF-Exports; angemeldet wird weiterhin mit dem Benutzernamen.
  • Datensicherung: In den Einstellungen exportiert „Alles exportieren“ alle Daten des Benutzers in eine JSON-Datei (Einstellungen, Orte, Zeiteinträge, Urlaub, Zuschläge, Oracle-Übertragungen; kein Passwort, keine Sitzungen, kein Oracle-Token). „Datei einspielen“ ersetzt nach einer Bestätigung alle bisherigen Daten des Benutzers. Die Datei wird vollständig geprüft (Format, Version, Überschneidungen, Grenzwerte) und in einer Transaktion eingespielt: Bei einem Fehler bleibt alles unverändert. API: GET/POST /api/v1/backup.
  • Zeitzuschläge: Pro Benutzer bis zu 10 Regeln, die die geleistete Zeit an bestimmten Wochentagen und/oder Feiertagen gewichten, z. B. Samstag × 1,5 (8 h zählen als 12 h). Faktor zwischen 0,50 und 3,00, zwei Nachkommastellen. Trifft an einem Tag mehr als eine Regel zu, gilt der höchste Faktor. Gewichtete Stunden fließen in Saldo und Übersicht ein; die tatsächlich geleisteten Stunden bleiben sichtbar.

Feiertage werden nicht berücksichtigt. Pausen werden nicht erfasst, Einträge sind Arbeitszeit.

Offline-Erfassung

Die Oberfläche funktioniert auf dem Handy auch ohne Verbindung, sobald sie einmal geladen wurde:

  • Timer starten und stoppen sowie manuelle Einträge werden in einer Warteschlange auf dem Gerät gespeichert, mit den echten Zeiten.
  • Sobald wieder eine Verbindung besteht, werden sie der Reihe nach gesendet (auch beim Öffnen der App und alle 15 Sekunden, solange etwas wartet).
  • Ein offline gestarteter und gestoppter Timer wird zu einem einzelnen Eintrag. Ein vom Server abgelehnter Eintrag (z. B. wegen einer Überschneidung) wird mit Begründung angezeigt und blockiert die übrigen nicht.
  • Neue Versionen der App (PWA) werden nicht automatisch eingespielt: Die neue Version wird im Hintergrund geladen, die App zeigt „Neue Version verfügbar“ und wechselt erst nach „Jetzt aktualisieren“. Nicht gesendete Einträge bleiben dabei erhalten.
  • Bestehende Einträge bearbeiten oder löschen, Urlaub, Einstellungen und Export brauchen eine Verbindung.
  • Gesendet wird nur, solange die App geöffnet ist; ein Hintergrund-Sync gibt es nicht. Beim Abmelden mit wartenden Einträgen fragt die App nach.

Vollständig offline

Ohne Anmeldung auf der Anmeldeseite („Ohne Anmeldung offline nutzen“) oder in den Einstellungen unter „Offline-Modus“ („Vollständig offline nutzen“) arbeitet die App nur im Browser:

  • Alle Daten (Einstellungen, Orte, Zeiteinträge, Urlaub, Zuschläge, Oracle-Übertragungen) liegen im Browser-Speicher (localStorage). Auf dem Server wird nichts gespeichert; die App braucht dafür keine Verbindung.
  • Die Regeln sind dieselben wie auf dem Server: Überschneidungen, Warnungen nach ArbZG, Feiertage, Zuschläge, Urlaub und der Überstundensaldo werden im Browser berechnet.
  • Beim Wechsel vom Server in den Offline-Modus werden die Daten des Kontos einmalig in den Browser kopiert; der Überstundensaldo bleibt dabei gleich. Auf dem Server bleiben die Daten unverändert liegen.
  • Oracle-Übertragungen und der Oracle-Abgleich gehen über zwei zustandslose Endpunkte (/api/v1/oracle/relay/transfer und /api/v1/oracle/relay/overtime). Der Server leitet die Anfrage an Oracle weiter und speichert nichts; dafür braucht der Offline-Modus eine Verbindung zum Server.
  • PDF-Export: Offline öffnet sich der Bericht im Druckfenster des Browsers; dort „Als PDF speichern“ wählen. CSV-Export ist unverändert.
  • „Offline-Modus beenden“ lädt die Daten als Sicherungsdatei herunter und meldet ab. Zum Übernehmen auf dem Server danach die Datei unter „Datensicherung“ einspielen. Die Daten bleiben bis dahin im Browser.
  • Der Browser-Speicher ist an den Browser und seine Website-Daten gebunden: Löschen der Website-Daten entfernt auch die Offline-Daten. Eine Sicherungsdatei regelmäßig herunterladen.

Schnellstart mit Docker

cp backend/.env.example .env   # APP_JWT_SECRET setzen
docker compose up --build

Frontend: http://localhost:8080 · Swagger UI: http://localhost:8080/swagger/index.html

Die Images werden aus ihrem Unterverzeichnis gebaut (backend/Dockerfile, frontend/Dockerfile), das ist auch der Build-Kontext in der CI. Das Frontend-Image schreibt den Commit aus der Datei frontend/GIT_SHA in die Anzeige; lokal steht dort dev.

Kubernetes mit Helm

Das Chart liegt unter deploy/helm/timetracker. Es startet ein Backend-Pod und ein Frontend-Pod. Das Frontend leitet /api an den Service backend weiter, daher gilt: ein Release pro Namespace.

helm install timetracker deploy/helm/timetracker \
  --set image.backend.repository=registry.example.com/timetracker/backend \
  --set image.backend.tag=<tag> \
  --set image.frontend.repository=registry.example.com/timetracker/frontend \
  --set image.frontend.tag=<tag> \
  --set secrets.inline.jwtSecret="$(openssl rand -hex 32)" \
  --set ingress.enabled=true --set 'ingress.hosts={timetracker.example.com}'
  • SQLite (Standard): eine Datei in einem PersistentVolumeClaim unter /data. Nur ein Replica möglich, das Chart verweigert mehr.
  • PostgreSQL / MariaDB: config.database.driver, config.database.host, config.database.user, config.database.name setzen und secrets.inline.dbPassword übergeben. Nicht geheime Werte liegen in einer ConfigMap, Passwort und JWT-Secret in einem Secret. Für Produktion besser secrets.existingSecret mit den Schlüsseln APP_JWT_SECRET und DB_PASSWORD verwenden.
  • Sicherheit: Beide Pods laufen als Nutzer 65532 ohne Root-Rechte, mit read-only Root-Dateisystem (nginx schreibt nur nach /tmp, /run und /var/lib/nginx/tmp, jeweils ein emptyDir), ohne Capabilities, ohne Privilege Escalation, mit RuntimeDefault-Seccomp und ohne ServiceAccount-Token. NetworkPolicies lassen nur Frontend-Pods zum Backend. Die Abschnitte securityContext in values.yaml bzw. den Templates sind die Stelle für Anpassungen.

CI

.forgejo/workflows/ci.yml führt Go- und Frontend-Tests aus, baut beide Images über die wiederverwendbaren Workflows aus infra/ci-snippets, rendert und prüft das Chart (helm lint --strict, helm template) und veröffentlicht es als OCI-Chart. Der Chart-Tag ist die Workflow-Run-Nummer als Patch-Version; Image-Tags und Registry-Pfad werden im Workflow in values.yaml eingesetzt.

Lokale Entwicklung

Voraussetzungen: Go (siehe backend/go.mod), Node.js mit pnpm.

# Backend
cd backend
cp .env.example .env          # APP_JWT_SECRET setzen
go run ./cmd/server           # läuft auf :8080

# Frontend (zweites Terminal)
cd frontend
pnpm install
pnpm dev                      # Vite leitet /api an :8080 weiter

Konfiguration

Variable Standard Bedeutung
APP_PORT 8080 HTTP-Port
APP_JWT_SECRET – (Pflicht) Schlüssel für JWT-Tokens
APP_JWT_TTL_HOURS 24 Gültigkeit des Tokens
APP_LOG_LEVEL info debug, info, warn oder error
DB_DRIVER sqlite sqlite, mariadb oder postgres
DB_NAME timetracker.db (sqlite) / timetracker sqlite: Dateipfad; mariadb/postgres: Datenbankname
DB_HOST – Host für mariadb und postgres (Pflicht dort)
DB_PORT 3306 / 5432 Port; leer = Standard des Treibers
DB_USER timetracker Benutzer für mariadb und postgres
DB_PASSWORD – Passwort für mariadb und postgres (Geheimnis)
DB_SSLMODE disable nur postgres

Die Verbindung wird aus diesen Feldern zusammengesetzt, es gibt keinen Verbindungsstring mehr. Beispiele stehen in backend/.env.example. Für MariaDB und PostgreSQL in Docker: docker compose --profile postgres up bzw. --profile mariadb, danach DB_DRIVER, DB_HOST, DB_USER und DB_PASSWORD entsprechend setzen.

Tests

make test            # Go- und Frontend-Tests
make lint-chart      # Helm-Chart prüfen
make swagger         # Swagger-Dateien neu erzeugen

API

Alle Endpunkte liegen unter /api/v1. Die vollständige Beschreibung steht in der Swagger UI unter /swagger/index.html. Geschützte Endpunkte erwarten Authorization: Bearer <token>.

Hinweise

  • Der Export ist auf 366 Tage pro Datei begrenzt.
  • Die Zeitzone für Tage, Exporte und Anzeige ist Europe/Berlin.