Fuhrpark (Fleet Manager)

= 🚗 Fuhrpark (Fleet Manager) =

>**Zweck:** Webbasiertes System zur Verwaltung des Firmenfuhrparks — von Fahrzeug- und Fahrerstammdaten über Kostenkalkulation und Kilometerauswertung bis zu automatisierter Ersatzbeschaffungs-Planung (Handlungsbedarf) und monatlicher Abrechnung.

4

5

== Übersicht ==

6

7

Fuhrpark unterstützt den gesamten Lebenszyklus eines Firmenfahrzeugs: Anlage und Zuordnung, laufende Kostenkalkulation, Kilometer-Tracking, Handlungsbedarf/Ersatzbeschaffung bis zur monatlichen Abrechnung und Kostenstellen-Umbuchung. Fahrzeug- und Fahrerstammdaten werden aus dem unternehmensweiten RIMO-System (SQL-Server-DWH) synchronisiert, Kilometerstände automatisiert über GPS-/Tesla-Anbindung und SharePoint importiert.

8

9

Das Projekt wurde von einer Streamlit-Monolith-Anwendung auf eine FastAPI-Backend- + React-Frontend-Architektur umgestellt.

10

11

== Technologie-Stack ==

12

13

**Frontend:** React 18 · Vite · React Router · React Query (TanStack Query) · Axios · eigene UI-Komponentenbibliothek (kein UI-Framework wie MUI/shadcn)

14

15

**Backend:** FastAPI (Python) · SQLite (WAL-Modus) · Pandas · python-jose (JWT) · passlib/bcrypt · pyodbc (SQL-Server-Anbindung)

16

17

**Externe Anbindungen:**

18

19

* **RIMO / SQL-Server (ai.sdmperson, rimo.sdmtool):** täglicher Fahrer-/Line-Manager-Sync, Datumsermittlung für Nachkorrekturen

20

* **Microsoft Fabric:** KM-Formular-E-Mails, SharePoint-Listenabgleich

21

* **GPS-AT / Tesla:** automatischer Kilometerstand-Import

22

23

== Projektstruktur ==

24

25

{{{fuhrpark/

26

├── _bootstrap.py Gemeinsames Setup für alle Skripte

27

├── 1_import_users_drivers.py Täglicher Fahrer-/Line-Manager-Sync (Cron)

28

├── 2_import_vehicles.py Einmaliger Fahrzeug-Erstimport

29

├── 3_import_vehicle_data.py Manueller Excel-Import (Fahrzeugdaten)

30

├── 4_import_km_history.py Manueller Excel-Import (KM-Historie)

31

├── import_km.py KM-Stand-Import (gpsat/tesla/sharepoint)

32

├── repair_stale_line_manager_assignments.py Einmaliges Reparatur-Skript (Altlasten)

33

├── docker-compose.yml

34

├── .env Secrets für Docker (SECRET_KEY, CORS)

35

├── data/ fleet.db, fleet_demo.db (nicht in Git)

36

├── abrechnungen/ Export-Ablage (nicht in Git)

37

├── backend/

38

│ ├── Dockerfile

39

│ ├── .env Secrets für Cron-Skripte (CONN_STR, SP_*, SMTP_*)

40

│ ├── requirements.txt

41

│ └── app/

42

│ ├── main.py FastAPI-Einstiegspunkt, Hintergrund-Jobs

43

│ ├── config.py Zentrale Konfiguration (ENV-Variablen)

44

│ ├── db.py Schema, Migrationen, Indizes

45

│ ├── auth.py JWT/Passwort-Logik

46

│ ├── services.py Geschäftslogik (Kalkulation, Zuordnung, ...)

47

│ └── routers/ vehicles, drivers, users, dashboard, calc_params, auth

48

└── frontend/

49

├── Dockerfile

50

├── nginx.conf Reverse-Proxy zu /api, SPA-Routing

51

└── src/

52

├── api/ zentraler Axios-Client

53

├── context/ AuthContext

54

├── components/ VehicleFormModal, DriverFormModal, ui/, ...

55

└── pages/ Dashboard, Fahrzeuge, Fahrer, KM-Dashboard, ...

56

}}}

57

58

== Hauptfunktionen ==

59

60

=== Fahrzeuge verwalten ===

61

62

Fahrzeuge werden initial aus RIMO importiert und danach in der App gepflegt (Rückschreiben nach RIMO ist geplant, aktuell nicht implementiert). Anlegen erfordert MAT-ID, Marke und Modell als Pflichtfelder; Fahrer und Line Manager können direkt zugewiesen werden (Line Manager wird bei Fahrer-Auswahl automatisch ergänzt, ist aber weiterhin manuell überschreibbar). Zuordnungen mit befristetem Zeitraum kehren nach Ablauf automatisch zum vorherigen Fahrer zurück — ohne Enddatum bleibt die Zuordnung bestehen, bis sie aktiv geändert wird. Fahrzeuge können auf inaktiv gesetzt (bleiben sichtbar) oder archiviert werden (wandern in die Archiv-Ansicht, von dort reaktivierbar). Ein gesetztes „Deactivation Date" deaktiviert und archiviert das Fahrzeug automatisch zum entsprechenden Datum. Komponenten: FahrzeugePage, VehicleFormModal, VehicleDrawer.

63

64

=== Fahrer verwalten ===

65

66

Fahrer werden täglich um 4:00 Uhr gegen RIMO abgeglichen (Neuanlage bei unbekannter Personalnummer, sonst Aktualisierung von Stammdaten, Kostenstelle und Line Manager). Externe Fahrer können manuell angelegt und bearbeitet werden; Stammdaten interner (per RIMO importierter) Fahrer sind schreibgeschützt. Komponenten: FahrerPage, DriverFormModal.

67

68

=== Kilometer-Daten ===

69

70

Kilometerstände werden automatisiert importiert: GPS-AT täglich um 4:00, Tesla montags um 4:00, jeweils zum Monatsende. Für Fahrzeuge ohne automatische Anbindung wird 3 Tage vor Monatsende täglich eine Erinnerungsmail verschickt, bis ein Wert in der SharePoint-Liste eingetragen ist; sobald die Liste vollständig ist, wird sie automatisch übernommen. Berechnet werden Differenzen, Jahreskilometer und aktuelle Laufleistung, einsehbar im KM-Dashboard — inklusive korrekter Zeitraum-Begrenzung bei unterjährigem Fahrer-/Line-Manager-Wechsel. Komponente: KmDashboardPage.

=== Kalkulation ===

Pro Fahrzeug wird eine Kostenkalkulation aus Anschaffungskosten, laufenden Kosten (Versicherung, Wartung etc.) sowie Verbrauch und Energiepreisen erstellt. Ergebnis: Kosten pro Monat, Jahr und Kilometer. Beim Anlegen eines Fahrzeugs werden die Default-Parameter aus „Kalkulationsparameter" nach Fahrzeugtyp übernommen; die verbleibenden individuellen Felder werden in „Kalkulation" ergänzt und per „Aktualisieren" neu berechnet. Komponente: KalkulationPage.

75

76

=== Handlungsbedarf ===

77

78

Hochrechnungen werden bei jedem KM-Stand-Import neu berechnet. Ein neu bestelltes Fahrzeug wird zunächst über das Häkchen „Bestellt" markiert — erst danach kann es im System angelegt werden. Nach Anlage steht die Funktion „Geliefert" zur Verfügung; sobald ein Fahrzeug als geliefert markiert wird, entfällt es automatisch aus der Handlungsbedarfsliste, der Beschaffungsprozess gilt als abgeschlossen. Neu angelegte sowie aus dem Handlungsbedarf stammende Fahrzeuge erscheinen automatisch im Forecast; Ersatzfahrzeuge enthalten dort eine Referenz auf das ursprüngliche (ersetzte) Fahrzeug. Komponente: HandlungsbedarfPage.

=== Dashboard ===

Zentrale Übersicht: Anzahl Fahrzeuge, Kostenübersicht und relevante Kennzahlen zum aktuellen Fuhrparkstatus. Komponente: DashboardPage.

83

84

=== Benutzerverwaltung (Admin) ===

85

86

Admins können Benutzer anlegen, Passwörter ändern sowie Fahrer und Fahrzeuge zuweisen. Änderungen an Line Manager und Kostenstelle werden nachvollziehbar protokolliert (driver_attribute_history), sowohl bei manueller Änderung als auch beim täglichen RIMO-Sync. Komponente: BenutzerPage.

87

88

=== Kalkulationsparameter ===

89

90

Anpassungen hier wirken sich auf **alle** Fahrzeuge des jeweiligen Typs aus. Dem Controlling vorbehalten (Rollen admin, demo, controlling). Komponente: KalkParamsPage.

91

92

=== Export & Berichte ===

93

94

Monatliche Abrechnungen und Kostenstellen-Umbuchungen werden auf Klick erstellt und als CSV exportiert, zur Weiterverarbeitung in Excel. Gefahrene Kilometer sowie die vollständige Fahrzeugliste (inkl. Kalkulationsaufschlüsselung) können als Excel-Datei heruntergeladen werden.

== Routing ==

|=Seite|=Beschreibung

99

|Dashboard|Startseite, zentrale Kennzahlen

100

|Fahrzeuge|Fahrzeugverwaltung, Zuordnung, Archiv

101

|Fahrer|Fahrerverwaltung

102

|KM-Dashboard|Kilometerauswertung, Monatsabrechnung

103

|Kalkulation|Kostenkalkulation je Fahrzeug

104

|Handlungsbedarf|Ersatzbeschaffung, Forecast

105

|Kalkulationsparameter|Typ-Defaults (Controlling)

106

|Benutzer|Benutzerverwaltung (Admin)

|Login|Anmeldung

== Datenzugriff ==

Der Zugriff erfolgt über einen zentralen Axios-Client (api/index.js) in Verbindung mit React Query für Caching, Invalidierung und Hintergrund-Aktualisierung. Jede Seite bindet die für sie relevanten REST-Endpunkte des FastAPI-Backends ein (vehiclesApi, driversApi, usersApi, calcParamsApi).

== Backend ==

**Authentifizierung:** JWT (python-jose), OAuth2-Password-Flow, 8-Stunden-Tokens. Rollen: admin, demo, controlling, Benutzer (Line Manager/Fahrer). Sichtbarkeit von Fahrzeugen/Fahrern für normale Nutzer richtet sich nach Line-Manager-Zuordnung.

116

117

**Datenbank:** SQLite im WAL-Modus. Schema und nicht-destruktive Migrationen in db.py. Änderungen an Fahrzeugen, Fahrern, Kalkulationsparametern und Passwörtern werden inklusive verantwortlicher Person nachvollzogen (updated_by); Zuordnungsänderungen (Fahrzeug↔Fahrer, Fahrer↔Line-Manager/Kostenstelle) führen eine vollständige, zeitlich abgegrenzte Historie (vehicle_assignment_history, driver_attribute_history).

118

119

**Externe Anbindung:** SQL-Server-Zugriff über pyodbc (CONN_STR) für den täglichen RIMO-Sync sowie Datumsermittlung bei nachträglichen Korrekturen (rimo.sdmtool.last_update). Microsoft-Fabric-Anbindung für KM-Formular-E-Mails und SharePoint-Abgleich.

== Architektur ==

{{{flowchart TD

A[React Frontend] --> B[React Query / Axios-Client]

125

B --> C[nginx Reverse-Proxy]

126

C --> D[FastAPI Backend]

127

D --> E[(SQLite<br/>fleet.db)]

128

D --> F[JWT Auth]

129

130

G[Cron-Skripte<br/>Projekt-Root] --> E

131

G --> H[SQL-Server / RIMO<br/>ai.sdmperson, rimo.sdmtool]

132

G --> I[Microsoft Fabric<br/>SharePoint / KM-Mails]

133

G --> J[GPS-AT / Tesla APIs]

134

}}}

135

136

Die Cron-Skripte laufen **unabhängig** von der FastAPI-App direkt auf dem Server (nicht im Docker-Container), schreiben aber in dieselbe fleet.db wie das Backend.

== Server ==

Die App läuft auf 192.168.208.2, per Docker Compose (Services backend + frontend), und liegt unter /mnt/data/fleet-manager/fuhrpark.

141

142

**Deployment bei Codeänderungen** (manuell auf dem Server auszuführen):

143

144

{{{sudo -u www-data git pull

145

docker compose up -d --build

146

}}}

147

148

**Cronjobs:** sudo -u www-data crontab -e, Logs unter /mnt/data/fleet-manager/fuhrpark/logs. Enthält u. a. den täglichen Fahrer-Sync (1_import_users_drivers.py) und die KM-Stand-Importe (gpsat/tesla/sharepoint über import_km.py).

149

150

Erreichbar unter [[http:~~/~~/fleetmanager.spl-tele.com:8501>>url:http://fleetmanager.spl-tele.com:8501/]] — mit VPN und im SPL-TELE-Netzwerk.

== Hinweise ==

* Änderungen im Demo-Modus werden nicht gespeichert.

155

* Benutzerrechte bestimmen die Sichtbarkeit der Daten (Line-Manager-Zuordnung).

156

* Regelmäßige Datenpflege (z. B. Fahrerzuordnung) ist wichtig für korrekte Auswertungen.

157

* backend/data/ bzw. data/ (Projekt-Root) enthält die produktive Datenbank und ist **nicht** Teil des Git-Repos — ein git pull verändert die Datenbank nie.

Wiki source code of Fuhrpark (Fleet Manager)