timetracker-next/docs/plan
2026-11-04 14:27:09 +00:00
..
01-backend-foundation.md docs: add implementation plan 2026-11-04 14:04:48 +00:00
02-database.md docs: add implementation plan 2026-11-04 14:04:48 +00:00
03-auth.md docs: add implementation plan 2026-11-04 14:04:48 +00:00
04-settings.md docs: add implementation plan 2026-11-04 14:04:48 +00:00
05-time-entries.md docs: add implementation plan 2026-11-04 14:04:48 +00:00
06-vacation.md docs: add implementation plan 2026-11-04 14:04:48 +00:00
07-overtime.md docs: add implementation plan 2026-11-04 14:04:48 +00:00
08-export.md docs: add implementation plan 2026-11-04 14:04:48 +00:00
09-frontend.md docs: add implementation plan 2026-11-04 14:04:48 +00:00
10-finalize.md docs: add implementation plan 2026-11-04 14:04:48 +00:00
README.md feat(deploy): split non-secret chart config into ConfigMap and password into Secret 2026-11-04 14:27:09 +00:00

Zeiterfassung (timetracker-next) – Plan

Ein Zeiterfassungs-Tool nach deutschen Standards.

  • Backend: Go, Gin, Gin-Logrus, swaggo, GORM, godotenv (autoload)
  • Frontend: React (Vite, TypeScript)
  • Datenbanken: SQLite, MariaDB, PostgreSQL (über DB_DRIVER gewählt)

Leitentscheidungen

Thema Entscheidung
Registrierung Öffentlich, nur Benutzername + Passwort
Auth JWT (Bearer), Passwort-Hash mit bcrypt
Sollzeit Konfigurierbare Stunden pro Arbeitstag (Standard 8 h), Wochenziel = 5 × Tagesziel (Standard 40 h). Gilt Mo–Fr.
Überstunden Saldo = Summe (Ist − Soll) über alle Arbeitstage bis heute, plus optionaler Startsaldo. Urlaubstage zählen mit Soll-Stunden als erfüllt.
Zeiterfassung Start/Stopp-Timer (genau ein laufender Timer pro Benutzer) sowie manuelle Einträge mit Von/Bis. Überlappungen werden abgelehnt.
Urlaub Ganztägige Urlaubstage, Kontingent pro Jahr konfigurierbar (Standard 30).
Arbeitszeitgesetz Hinweis (keine Sperre), wenn ein Tag mehr als 10 h erfasst (ArbZG § 3); Warnung ab 8 h mit Hinweis auf Pausen (§ 4).
Formate Datum TT.MM.JJJJ, Dezimalkomma (8,50 h), Zeit HH:MM, Zeitzone Europe/Berlin.
CSV Semikolon-getrennt, UTF-8 mit BOM (Excel-kompatibel), Dezimalkomma.
PDF Monatsbericht/Zeitraumbericht mit Summen, Saldo und Unterschriftsfeld.
Tests Go: testing + httptest gegen SQLite in-memory; Frontend: Vitest + Testing Library.
Commits Pro Schritt ein Commit, nur wenn die Tests dieses Schritts grün sind.

Verzeichnisstruktur (Ziel)

backend/
  cmd/server/main.go
  internal/
    config/        Umgebungsvariablen (godotenv autoload)
    logging/       Logrus-Setup + Gin-Middleware
    database/      GORM-Öffnung für sqlite/mariadb/postgres, Migration
    models/        GORM-Modelle
    auth/          Registrierung, Login, JWT, Middleware
    settings/      Benutzereinstellungen (Sollzeit, Urlaubskontingent, Startsaldo)
    timeentries/   Start/Stopp, manuelle Einträge, Liste
    vacation/      Urlaubseinträge
    overtime/      Saldo-Berechnung und Summen
    export/        CSV- und PDF-Export
    httpapi/       Router, Handler-Registrierung, Fehlerformat
  docs/            swag-generierte Swagger-Dateien
frontend/
  src/             React-App (Auth, Dashboard, Einträge, Urlaub, Export, Einstellungen)
docs/plan/         diese Dateien

Schritte

  1. Backend-Grundgerüst
  2. Datenbank und Modelle
  3. Auth: Registrierung und Login
  4. Einstellungen und Sollzeit
  5. Zeiteinträge (Timer und manuell)
  6. Urlaub
  7. Überstundensaldo und Übersicht
  8. Export: CSV und PDF
  9. Frontend
  10. Abschluss: Doku, Swagger, Docker-Compose

Konfiguration (.env)

Variable Standard Bedeutung
APP_PORT 8080 HTTP-Port
APP_JWT_SECRET – (Pflicht) Signaturschlüssel für JWT
APP_JWT_TTL_HOURS 24 Gültigkeit des Tokens
APP_LOG_LEVEL info Logrus-Level
DB_DRIVER sqlite sqlite, mariadb oder postgres
DB_NAME timetracker.db Dateipfad (sqlite) bzw. Datenbankname
DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_SSLMODE – Verbindungsfelder für mariadb/postgres; die DSN wird im Backend zusammengesetzt