Wiki source code of Fuhrpark (Fleet Manager)
Version 7.2 by Patrizia Gurschka on 2026/09/09 13:08
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | = đźš— Fuhrpark (Fleet Manager) = | ||
| 2 | |||
| 3 | >**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. | ||
| 71 | |||
| 72 | === Kalkulation === | ||
| 73 | |||
| 74 | 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. | ||
| 79 | |||
| 80 | === Dashboard === | ||
| 81 | |||
| 82 | 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. | ||
| 95 | |||
| 96 | == Routing == | ||
| 97 | |||
| 98 | |=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) | ||
| 107 | |Login|Anmeldung | ||
| 108 | |||
| 109 | == Datenzugriff == | ||
| 110 | |||
| 111 | 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). | ||
| 112 | |||
| 113 | == Backend == | ||
| 114 | |||
| 115 | **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. | ||
| 120 | |||
| 121 | == Architektur == | ||
| 122 | |||
| 123 | {{{flowchart TD | ||
| 124 | 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. | ||
| 137 | |||
| 138 | == Server == | ||
| 139 | |||
| 140 | 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. | ||
| 151 | |||
| 152 | == Hinweise == | ||
| 153 | |||
| 154 | * Ă„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. |