Skip to Content

Wiki source code of Zeitschreibung

Last modified by Dimitri Rupp on 2026/07/08 12:34
Show last authors
1 {{box cssClass="floatinginfobox" title="**Auf dieser Seite**"}}
2 {{toc/}}
3 {{/box}}
4
5 = ⏱️ SPL TimeTrack (Zeitschreibung) =
6
7 {{info}}
8 **Zweck:** Webbasierte Zeiterfassungs- und Dispositionslösung für Mitarbeiter und Führungskräfte — mit GPS-Nachweis, Offline-Fähigkeit und Genehmigungsworkflow.
9 **Zielgruppe:** Unternehmen mit Außendienst-, Montage- oder Servicepersonal.
10 {{/info}}
11
12 == Überblick ==
13
14 **SPL TimeTrack** ist eine webbasierte Zeiterfassungs- und Dispositionslösung. Die Anwendung besteht aus:
15
16 * **Frontend:** React + TypeScript (Vite)
17 * **Backend:** FastAPI (Python)
18 * **Datenbank:** PostgreSQL
19 * **Authentifizierung:** JWT + Refresh Tokens
20 * **Besonderheiten:** GPS-basierte Zeiterfassung, Offline-Fähigkeit, Genehmigungsprozesse, Kostenstellen-/Kostenträgerverwaltung, PWA-Unterstützung, Push-Benachrichtigungen
21
22 == Architektur ==
23
24 {{mermaid}}
25 flowchart TD
26 FE["Frontend<br/>React / Vite"] --> BE["FastAPI Backend"]
27 BE --> DB[("PostgreSQL")]
28 {{/mermaid}}
29
30 === Technologiestack ===
31
32 **Frontend:** React · TypeScript · React Router · TanStack Query · ShadCN UI · PWA-Unterstützung · IndexedDB (Offline-Betrieb)
33
34 **Backend:** FastAPI · SQLAlchemy · PostgreSQL 16 · JWT Authentication · bcrypt Passwort-Hashing · Web Push Notifications
35
36 == Hauptfunktionen ==
37
38 === 1. Zeiterfassung ===
39
40 **Start/Stopp:** Mitarbeiter können Arbeitszeiten starten und beenden. Erfasst werden: Startzeit, Endzeit, Beschreibung, GPS-Koordinaten, Kostenstelle, Kostenträger.
41
42 **Laufende Einträge:** Die Anwendung erkennt aktive Arbeitszeiten, offene Einträge und fehlende Tagesabschlüsse.
43
44 === 2. GPS-Tracking ===
45
46 **Funktionen:** GPS-Pflicht beim Buchen, Standortprüfung, GPS-Protokollierung, Kartenansicht, Standortwechsel-Erkennung.
47
48 **Komponenten:** GpsGate, GpsMiniMap, EntryGpsDialog, MultiEntryGpsDialog, GpsErrorAlert.
49
50 === 3. Kostenstellen & Kostenträger ===
51
52 Administratoren verwalten Kostenstellen, Kostenträger und Zuordnungen. Bei jeder Zeiterfassung kann ein Mitarbeiter Kostenstelle und Kostenträger auswählen sowie eine Beschreibung hinterlegen.
53
54 === 4. Genehmigungsworkflow ===
55
56 **Rollen:** Mitarbeiter, Manager, Administrator.
57
58 {{mermaid}}
59 flowchart LR
60 A["Mitarbeiter erfasst Zeiten"] --> B["Eintrag erhält Status"]
61 B --> C["Verantwortlicher prüft"]
62 C -->|"Genehmigung"| D["Freigegeben"]
63 C -->|"Ablehnung"| E["Abgelehnt<br/>(Grund gespeichert)"]
64 {{/mermaid}}
65
66 Funktionen: offene Genehmigungen anzeigen, Ablehnungsgründe speichern, Historie nachvollziehen.
67
68 === 5. Historie & Auswertungen ===
69
70 **Historie:** Kalenderansicht, Heatmap-Darstellung, Tagesübersicht, Zeitverlauf.
71
72 **Statistiken:** Backend-Endpunkte liefern Benutzerzusammenfassungen, Arbeitszeitübersichten und Genehmigungsstatus.
73
74 === 6. Offline-Betrieb ===
75
76 Die Anwendung funktioniert auch ohne Internet: lokale Speicherung, Warteschlange für Änderungen, automatische Synchronisation (IndexedDB, Offline Queue, Statusüberwachung).
77
78 === 7. PWA (Progressive Web App) ===
79
80 Installierbar auf Smartphones, offline nutzbar, Push-Benachrichtigungen. Komponenten: InstallBanner, InstallPage, PwaRouteGuard.
81
82 === 8. Push-Benachrichtigungen ===
83
84 Unterstützt Browser Push, Erinnerungen und Genehmigungsanfragen. Backend verwendet VAPID-Schlüssel und die Web Push API.
85
86 == Benutzerverwaltung ==
87
88 Administrationsbereiche:
89
90 |=Bereich|=Pfad
91 |Benutzer (Mitarbeiter, Rollen, Berechtigungen)|##/admin/users##
92 |Kostenstellen|##/admin/cost-centers##
93 |Kostenträger (≈ Sales Orders)|##/admin/cost-objects##
94 |Firmenstandorte|##/admin/company-location##
95 |Buchungsarten|##/admin/entry-types##
96
97 Tätigkeitsbeschreibungen bestehen für Kostenstellen und Kostenträger getrennt. Es gibt zwei Tabs: (1) Anlegen und Löschen, (2) pro Kostenstelle auswählen, welche Tätigkeiten im Dropdown verfügbar sind.
98
99 == Sicherheit ==
100
101 === Authentifizierung ===
102
103 * **Login:** ##/auth/sign-in##
104 * **Session:** JWT-basiert mit Access- und Refresh-Token
105 * **Passwortschutz:** bcrypt-Hashing, Passwortwechsel erzwingbar, Passwortänderungs-Guard
106
107 === Datenschutz ===
108
109 Mitarbeiter sehen ausschließlich eigene Zeiteinträge und Daten; Manager/Admins erhalten erweiterte Rechte. Schutzmechanismen: SQL-Injection-Schutz, CORS-Whitelist, Token-Widerruf, Rollenprüfung.
110
111 == KI-Funktionen ==
112
113 Das Backend unterstützt einen KI-gestützten Zeitsplit (##/functions/split-time-entry##). Er nutzt einen ##OPENAI_API_KEY## und teilt einen laufenden Zeiteintrag automatisch auf mehrere Tätigkeiten oder Projekte auf.
114
115 == Wichtige Seiten ==
116
117 |=Seite|=Zweck
118 |/|Dashboard
119 |/auth|Login
120 |/history|Historie
121 |/approvals|Genehmigungen
122 |/profile|Benutzerprofil
123 |/change-password|Passwortänderung
124 |/help|Hilfe & Doku
125 |/install|App-Installation
126
127 == Backend-API ==
128
129 **Auth:** POST /auth/sign-in · POST /auth/sign-up · POST /auth/sign-out · GET /auth/session · GET /auth/user · PATCH /auth/user
130
131 **Daten:** POST /data/select · POST /data/insert · PATCH /data/update · DELETE /data/delete
132
133 **Funktionen:** Benutzerstatistiken, Genehmigungen, Rollenverwaltung, Zeitsplit und weitere Business-Funktionen.
134
135 == Besondere Geschäftslogik: Mitternachtssplit ==
136
137 Das Backend teilt Zeiteinträge, die über Mitternacht laufen, automatisch auf. Beispiel: ##22:00 - 02:00## wird getrennt in ##22:00 - 23:59## und ##00:00 - 02:00##. Dadurch bleiben Tagesauswertungen korrekt.
138
139 == Server ==
140
141 Das Projekt liegt unter ##/mnt/data/spl_time_secure## auf dem KI-Server. Es läuft mit Docker Compose (Services: backend, frontend, db).
142
143 Erreichbar unter [[http://192.168.208.2:8100>>http://192.168.208.2:8100/]] — mit VPN und im SPL-TELE-Netzwerk.