Changes for page Fuhrpark (Fleet Manager)

Summary

• Page properties (2 modified, 0 added, 0 removed)

Details

Page properties

Author

...	...	@@ -1,1 +1,1 @@
1		-XWiki.drupp
	1	+XWiki.gurschkap

Content

...	...	@@ -1,234 +1,157 @@
1		-{{box cssClass="floatinginfobox" title="**Auf dieser Seite**"}}
2		-{{toc/}}
3		-{{/box}}
	1	+= 🚗 Fuhrpark (Fleet Manager) =
4	4
5		-**Ablauf Fleet Manager:**
	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.
6	6
	5	+== Übersicht ==
7	7
8		-**~1. Fahrzeuge verwalten**
	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.
9	9
10		-Fahrzeuge werden bis jetzt einmal aus Rimo importiert und dann in der App gepflegt. (Geplant: retour schreiben in Rimo)
	9	+Das Projekt wurde von einer Streamlit-Monolith-Anwendung auf eine FastAPI-Backend- + React-Frontend-Architektur umgestellt.
11	11
	11	+== Technologie-Stack ==
12	12
13		-**Fahrzeug anlegen**
	13	+**Frontend:** React 18 · Vite · React Router · React Query (TanStack Query) · Axios · eigene UI-Komponentenbibliothek (kein UI-Framework wie MUI/shadcn)
14	14
15		-1. Menü **„Fahrzeuge“** öffnen
16		-1. Auf **„Fahrzeug hinzufügen“** klicken
17		-1. Pflichtfelder ausfüllen (MAT-ID, Marke, Modell verpflichtend)
18		-1. Fahrer und Line Manager (wird automatisch ergänzt, kann dennoch selbst ausgewählt werden) auswählen
19		-1. Speichern
	15	+**Backend:** FastAPI (Python) · SQLite (WAL-Modus) · Pandas · python-jose (JWT) · passlib/bcrypt · pyodbc (SQL-Server-Anbindung)
20	20
	17	+**Externe Anbindungen:**
21	21
	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	22
23		-**Fahrzeug bearbeiten**
	23	+== Projektstruktur ==
24	24
25		-* Fahrzeug auswählen
26		-* Änderungen durchführen
	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	+}}}
27	27
28		-Wenn ein Fahrer nur für einen Zeitraum zugewiesen wird, wird nach diesem Zeitraum wieder der Ursprungsfahrer eingetragen. Wenn kein Enddatum eingetragen wird, bleibt der Fahrer bis etwas geändert wird.
	58	+== Hauptfunktionen ==
29	29
30		-* Speichern
	60	+=== Fahrzeuge verwalten ===
31	31
	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.
32	32
	64	+=== Fahrer verwalten ===
33	33
34		-**Fahrzeug deaktivieren**
	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.
35	35
36		-* in "bearbeiten" kann das Fahrzeug auf inaktiv gesetzt werden und bleibt in der Tabelle
	68	+=== Kilometer-Daten ===
37	37
	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.
38	38
	72	+=== Kalkulation ===
39	39
40		-**Fahrzeug archivieren**
	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.
41	41
42		-* Fahrzeug kann archiviert werden, dann wird es automatisch auf inaktiv gesetzt und in der „archivierte Fahrzeuge“ Tabelle angezeigt (dort kann es wieder aktiviert werden)
	76	+=== Handlungsbedarf ===
43	43
44		-----
	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.
45	45
	80	+=== Dashboard ===
46	46
47		-**2. Fahrer verwalten**
	82	+Zentrale Übersicht: Anzahl Fahrzeuge, Kostenübersicht und relevante Kennzahlen zum aktuellen Fuhrparkstatus. Komponente: DashboardPage.
48	48
49		-Fahrer werden jeden Tag um 4:00 in der Früh in Rimo überprüft und wenn notwendig neu angelegt oder bei Veränderungen angepasst.
	84	+=== Benutzerverwaltung (Admin) ===
50	50
	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.
51	51
52		-**Fahrer anlegen (extern)**
	88	+=== Kalkulationsparameter ===
53	53
54		-1. Menü **„Fahrer“** öffnen
55		-1. Auf **„Fahrer hinzufügen“** klicken
56		-1. Stammdaten eingeben
57		-1. Speichern
	90	+Anpassungen hier wirken sich auf **alle** Fahrzeuge des jeweiligen Typs aus. Dem Controlling vorbehalten (Rollen admin, demo, controlling). Komponente: KalkParamsPage.
58	58
	92	+=== Export & Berichte ===
59	59
	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.
60	60
61		-**Fahrer bearbeiten**
	96	+== Routing ==
62	62
63		-* Stammdaten ändern (nur bei extern)
	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
64	64
65		-----
	109	+== Datenzugriff ==
66	66
	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).
67	67
68		-**3. Kilometer-Daten**
	113	+== Backend ==
69	69
70		-* Kilometerstände werden automatisch importiert (z. B. GPS / Tesla)
71		-** gpsat täglich um 4:00
72		-** tesla montags 4:00
73		-** beides jeweils Ende des Monats
74		-** Erinnerungsmail wird 3 Tage von Ende des Monats täglich ausgeschickt, wenn kein KM Stand in der Sharepoint Liste vorhanden ist. Sobald die Liste vollständig ist, wird sie auf die App übertragen.
	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.
75	75
	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).
76	76
	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.
77	77
78		-* Das System berechnet:
79		-** Differenzen
80		-** Jahreskilometer
81		-** aktuelle Laufleistung
	121	+== Architektur ==
82	82
	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]
83	83
	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	+}}}
84	84
85		-Diese Daten sind im **KM-Dashboard** einsehbar.
	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.
86	86
87		-----
	138	+== Server ==
88	88
	140	+Die App läuft auf 192.168.208.2, per Docker Compose (Services backend + frontend), und liegt unter /mnt/data/fleet-manager/fuhrpark.
89	89
90		-**4. Kalkulation**
	142	+**Deployment bei Codeänderungen** (manuell auf dem Server auszuführen):
91	91
92		-Für jedes Fahrzeug kann eine Kostenkalkulation durchgeführt werden:
	144	+{{{sudo -u www-data git pull
	145	+docker compose up -d --build
	146	+}}}
93	93
94		-* Anschaffungskosten
95		-* Laufende Kosten (Versicherung, Wartung etc.)
96		-* Verbrauch & Energiepreise
	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).
97	97
	150	+Erreichbar unter [[http:~~/~~/fleetmanager.spl-tele.com:8501>>url:http://fleetmanager.spl-tele.com:8501/]] — mit VPN und im SPL-TELE-Netzwerk.
98	98
	152	+== Hinweise ==
99	99
100		-Ergebnisse:
101		-
102		-* Kosten pro Monat
103		-* Kosten pro Jahr
104		-* Kosten pro Kilometer
105		-
106		-
107		-
108		-Wenn ein Fahrzeug hinzugefügt wird, werden die Default Parameter aus „Kalkulationsparameter“ nach Typ übernommen. Die 7 fehlenden Felder werden in „Kalkulation“ bei "bearbeiten" eingetragen und beim auf „Aktualisieren“ Drücken werden die Werte berechnet in die Tabelle eingetragen.
109		-
110		-----
111		-
112		-
113		-**5. Handlungsbedarf**
114		-
115		-Die Hochrechnungen in Handlungsbedarf werden immer neu berechnet mit den Importen der KM Stände.
116		-
117		-
118		-**Neues Fahrzeug bestellen**
119		-
120		-* Wenn neues Fahrzeug bestellt wurde, muss im Bereich „Handlungsbedarf“ das Häkchen bei „Bestellt“ gesetzt werden.
121		-* Erst danach ist es möglich, ein neues Fahrzeug im System anzulegen.
122		-
123		-
124		-
125		-**Neues Fahrzeug anlegen**
126		-
127		-* Ein Fahrzeug kann erst bearbeitet werden, nachdem es angelegt wurde
128		-* Nach der Anlage steht die Funktion „Geliefert“ zur Verfügung
129		-
130		-
131		-
132		-**Fahrzeug als geliefert markieren**
133		-
134		-* Sobald ein Fahrzeug als „geliefert“ markiert wird:
135		-** wird es automatisch aus der Handlungsbedarfsliste entfernt
136		-** gilt der Beschaffungsprozess als abgeschlossen
137		-
138		-
139		-
140		-**Darstellung im Forecast**
141		-
142		-* Neu hinzugefügte Fahrzeuge (Bereich „Fahrzeuge“)
143		-* sowie im Handlungsbedarf angelegte Fahrzeuge
144		-
145		-werden automatisch im Bereich „Forecast“ angezeigt.
146		-
147		-Zusätzlich gilt:
148		-
149		-* Fahrzeuge aus dem Handlungsbedarf enthalten im Forecast eine
150		-Referenz zum alten (ersetzten) Fahrzeug
151		-
152		-
153		-
154		-**Deaktivierung von Fahrzeugen**
155		-
156		-Wenn im Feld „Deactivation Date“ ein Datum eingetragen wird:
157		-
158		-wird das Fahrzeug ab diesem Datum automatisch:
159		-
160		-* deaktiviert
161		-* in den Bereich „Archivierte Fahrzeuge**“** verschoben
162		-
163		-----
164		-
165		-
166		-**6. Dashboard**
167		-
168		-Das Dashboard zeigt:
169		-
170		-* Anzahl Fahrzeuge
171		-* Kostenübersicht
172		-* relevante Kennzahlen
173		-
174		-Es dient als zentrale Übersicht für den aktuellen Fuhrparkstatus.
175		-
176		-----
177		-
178		-
179		-**7. Benutzerverwaltung (Admin)**
180		-
181		-Admins können:
182		-
183		-* Benutzer anlegen
184		-* Passwörter ändern
185		-* Fahrer und Fahrzeuge zuweisen
186		-
187		-----
188		-
189		-
190		-**8. Kalkulationsparameter**
191		-
192		-Wenn hier etwas angepasst wird, werden die Werte für alle Fahrzeuge dieses Typs abgeändert. Ist dem Controlling vorbehalten.
193		-
194		-----
195		-
196		-
197		-**9. Export & Berichte**
198		-
199		-* Monatliche Abrechnungen und Kostenstellen-Umbuchungen werden auf Klick erstellt
200		-* Export erfolgt als CSV-Datei
201		-* Daten können in Excel weiterverarbeitet werden
202		-* gefahrene KM können als Excel heruntergeladen werden
203		-
204		-----
205		-
206		-
207		-**10. Hinweise**
208		-
209		-* Änderungen im Demo-Modus werden nicht gespeichert
210		-* Benutzerrechte bestimmen die Sichtbarkeit der Daten
211		-* Regelmäßige Datenpflege (z. B. Fahrerzuordnung) ist wichtig für korrekte Auswertungen
212		-
213		-
214		-
215		-
216		-**Fehlerbehebung**
217		-
218		-* **Frontend:** Streamlit
219		-* **Backend:** Python
220		-* **Datenbank:** SQLite
221		-* **Externe APIs:** Microsoft Fabric Integration
222		-
223		-Die App läuft auf 192.168.208.2, in einem Docker und liegt in: /mnt/data/fleet-manager/fuhrpark.
224		-
225		-Falls etwas in Github geändert wird muss der git pull manuell auf dem Server passieren:
226		-
227		-* sudo -u www-data git pull
228		-* docker compose up -d –build
229		-
230		-Es gibt cronjobs in sudo www-data crontab -e, mit logs in /mnt/data/fleet-manager/fuhrpark/logs.
231		-
232		-Erreichbar unter: [[http:~~/~~/fleetmanager.spl-tele.com:8501>>http://fleetmanager.spl-tele.com:8501]] mit VPN und im SPL TELE Netzwerk
233		-
234		-
	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.