votianng/README.md

VoTiAn NG · Stadtbote

React-/TypeScript-Oberfläche und Spring-Boot-Anbindung für die vorhandene PHP-Anwendung in votian/. Die neue Anwendung verwendet dieselbe vorhandene MySQL-Datenbank und deren Tabellen. Sie enthält keine eigene Datenbank, keine automatischen Schemaänderungen und keine Demodatensätze.

Stand

Die Altanwendung wurde fachlich und technisch analysiert. Die neue Oberfläche bildet Auftragslisten, Disposition, Touren, Kunden, Kuriere und Auswertung ab. Das Spring-Boot-Backend greift ausschließlich über den zentralen DatabaseService auf das vorhandene Schema zu. Die Anmeldung verwendet vorhandene VoTiAn-Zentralenbenutzer mit ihren Niederlassungs- und Mitarbeiterrechten.

Die vollständige Ablösung der PHP-Anwendung ist noch nicht abgeschlossen. Schreibende Vorgänge wie Auftragserfassung, Tarifberechnung, Storno und Rechnungserzeugung haben im Altcode zahlreiche weitere Auswirkungen (unter anderem Fahrerbenachrichtigungen und Gegenbuchungen). Solange diese nicht vollständig portiert und am aktiven Bestand geprüft sind, öffnet die Oberfläche dafür die passenden Module der vorhandenen PHP-Anwendung, wenn LEGACY_APP_URL konfiguriert ist. Es gibt keine vereinfachten Schreibzugriffe, die diese Regeln umgehen.

Die vollständige Analyse und Abdeckungsmatrix stehen in docs/ALTSYSTEM-ANALYSE.md.

Start

Benötigt: Java 21, Node.js 22.12 oder neuer, Python 3 sowie der Netzwerk-/VPN-Zugang zur bestehenden Datenbank. Maven wird über den mitgelieferten Wrapper verwendet.

cd /Users/svencarstensen/Documents/Entwicklung/Source/Kunden/Assecutor/votianNG
./dev.sh

Die Oberfläche ist anschließend unter http://localhost:5173 erreichbar. Strg+C beendet die gestarteten Prozesse. Das Backend-Protokoll liegt in work/backend.log.

dev.sh, run.sh und die Datenbankdiagnose laden DB_URL, DB_USER und DB_PASSWORD aus der lokalen .env im Projektstamm. Bereits gesetzte Umgebungsvariablen haben Vorrang. Die Zugangsdaten werden ausschließlich als Prozessumgebung an Java übergeben, ohne sie auszugeben oder in Prozessargumente zu schreiben.

Die vorhandenen lokalen Datenbankwerte wurden nach .env übernommen. Bei einer neuen Einrichtung .env.example nach .env kopieren und die drei Werte eintragen. DB_URL enthält den vom jeweiligen Rechner erreichbaren Host bzw. die VPN-Adresse, Port und Datenbanknamen:

DB_URL=jdbc:mariadb://DB-HOST:3306/DB-NAME?connectTimeout=3000&socketTimeout=5000&allowMultiQueries=false

Diese Zeile gehört in .env. Werte werden wörtlich gelesen; $, #, = und Backslashes im Passwort bleiben erhalten. Die Datei wird nicht als Shellskript ausgeführt und sollte nicht mit source geladen werden. Für die zusätzliche Verwendung mit Docker die Werte ohne umschließende Anführungszeichen schreiben. .env und lokale Varianten sind per .gitignore ausgeschlossen; .env.example enthält ausschließlich Platzhalter.

Nur die Konfiguration ohne Datenbankverbindung prüfen:

python3 scripts/run-backend.py --check-config

Die neue Anwendung liest connection.local.json und die PHP-Konfiguration nicht mehr als Zugangsdatenquelle. Der PHP-Altbestand bleibt eigenständig; seine Konfiguration wird durch diese Umstellung nicht verändert.

Gebündelte Anwendung

./build.sh
./run.sh

build.sh baut React, integriert die gebauten Dateien in das Spring-Boot-JAR und führt die Backend-Tests aus. Die gebündelte Oberfläche ist über http://localhost:8080 erreichbar. run.sh übernimmt dieselbe .env wie der Entwicklungsstart. Build und Unit-Tests laden keine lokalen Datenbankzugangsdaten.

Docker-Image veröffentlichen

docker login registry.assecutor.org
./docker_push.sh
# Alternativer Image-Tag:
./docker_push.sh 0.1

Das Skript führt build.sh einschließlich Tests aus und pusht das Java-21-Image mit gebündeltem React-Frontend für linux/amd64 nach registry.assecutor.org/votianng. Ohne Argument verwendet es die Version aus backend/pom.xml; ein expliziter Tag ändert nur den Image-Tag. Das Ziel lässt sich über REGISTRY_IMAGE überschreiben.

Im Container lauscht die Anwendung auf Port 8080 an 0.0.0.0. Die .env wird beim Containerstart übergeben:

docker run --rm --env-file .env -p 127.0.0.1:8080:8080 registry.assecutor.org/votianng:0.1

Die vorhandene PHP-Anwendung und .env sind nicht im Image enthalten. Bei Bedarf LEGACY_APP_URL zusätzlich als Umgebungsvariable übergeben. Beim direkten Start über Maven oder java -jar wird .env über den gemeinsamen Wrapper geladen, beispielsweise aus backend/: python3 ../scripts/env_config.py ./mvnw spring-boot:run.

Anmeldung und Reverse Proxy

VoTiAn verwendet serverseitige Sitzungen mit dem Cookie VOTIANSESSION. Die Systemzugangsdaten werden einmal beim Anmelden übertragen; die Oberfläche speichert sie nicht im Browser und setzt keinen Authorization-Header. Ein zusätzlicher HTTP-Basic-Passwortschutz im Nginx Proxy Manager kann deshalb bestehen bleiben: Dessen Zugangsdaten verwaltet der Browser unabhängig von der VoTiAn-Sitzung. Die Abmeldung in VoTiAn beendet nur die Sitzung der Anwendung.

Für https://votian.app muss der Proxy die Oberfläche und /api/** an denselben VoTiAn-Dienst weiterleiten, Cookies durchlassen und das ursprüngliche HTTPS-Protokoll als X-Forwarded-Proto: https übermitteln. Die Anwendung wertet diese Header mit der nativen Tomcat-Unterstützung aus. Nur der vertrauenswürdige Proxy sollte den Backend-Port erreichen; er muss vom Client übermittelte Forwarded-Header ersetzen. Tomcat vertraut standardmäßig internen Proxyadressen. Bei anderer Netzwerkstruktur die erlaubten Proxyadressen gezielt über SERVER_TOMCAT_REMOTEIP_INTERNAL_PROXIES konfigurieren; die Prüfung nicht durch einen leeren Wert abschalten. Siehe Spring Boot: Reverse Proxy.

Im HTTPS-Produktionsbetrieb zusätzlich SERVER_SERVLET_SESSION_COOKIE_SECURE=true als Container-Umgebungsvariable setzen, zum Beispiel mit docker run --env-file .env -e SERVER_SERVLET_SESSION_COOKIE_SECURE=true .... Damit wird das Sitzungscookie ausschließlich über HTTPS übertragen. Der direkte HTTP-Aufruf per Server-IP ist dann kein Anmeldeweg mehr. Für die lokale Entwicklung über HTTP diese Einstellung weglassen; ohne explizite Vorgabe richtet sich Secure nach dem vom Backend erkannten Request-Protokoll.

Das Sitzungscookie ist HttpOnly und SameSite=Lax. Standardmäßig ist nach 30 Minuten ohne Anfrage an die Sitzung eine erneute Anmeldung erforderlich. Sitzungen liegen im Arbeitsspeicher des Backends und gehen bei einem Neustart verloren; mehrere Instanzen benötigen Sitzungsaffinität oder eine später einzurichtende gemeinsame Sitzungsablage. Benutzerrechte werden bei der Anmeldung geladen und gelten bis zur Abmeldung bzw. zum Sitzungsablauf. Änderungen an Konten oder Rechten beenden vorhandene Sitzungen nicht sofort.

Konfiguration

Variable	Bedeutung
DB_URL, DB_USER, DB_PASSWORD	Datenbankzugang aus .env; Prozessumgebung hat Vorrang
LEGACY_APP_URL	Basis-URL der vorhandenen PHP-Anwendung, damit Aktionen die bestehenden Fachabläufe öffnen
PORT	Spring-Boot-Port, Standard 8080
SERVER_ADDRESS	Bind-Adresse, Standard 127.0.0.1
FORWARD_HEADERS_STRATEGY	Auswertung der Proxy-Header, Standard native
SERVER_SERVLET_SESSION_COOKIE_SECURE	Im HTTPS-Produktionsbetrieb true setzen; lokal über HTTP weglassen
SESSION_TIMEOUT	Ablauf bei Inaktivität, Standard 30m
MAX_RESULTS	Obergrenze des geladenen Listenausschnitts, Standard 500

Die neue Anwendung ist standardmäßig nur lokal erreichbar. Für einen Serverbetrieb sind TLS und die korrekte Weiterleitung über einen Reverse Proxy zu konfigurieren. Es werden keine Standardkonten angelegt. Kunden- und Kurierlogins sind noch keine portierten Zugangswege; vorhandene Zentralenrechte werden nicht pauschal erweitert.

Prüfungen

python3 -m unittest discover -s tests -p 'test_*.py' -v
cd backend && ./mvnw test

Die Tests verwenden Mocks und getrennte Testfixtures im Arbeitsspeicher der Tests. Sie erzeugen keine Testdatenbank und führen keine Schreibzugriffe gegen den Bestand aus. Ein erfolgreicher Build ersetzt nicht die noch notwendige Prüfung mit aktivem VPN, dem korrekten Datenbankendpunkt und fachlichen Vergleichsfällen aus dem Altbetrieb.

Die optionale Diagnose python3 scripts/check-database.py startet das gebaute Backend-JAR im Modus --database-check, ohne Webserver. Verbindung und benötigte Tabellenspalten werden ausschließlich über denselben DatabaseService mit SELECT auf Serverversion und information_schema geprüft. Die Diagnose liest keine Auftrags-/Benutzerdatensätze, gibt keine Zugangsdaten aus und beendet danach den Prozess. Ein eigener Python-Datenbanktreiber ist nicht mehr erforderlich.

Datenbank-Serviceschicht

Alle Zugriffe der neuen Anwendung laufen über backend/src/main/java/de/stadtbote/votian/database/DatabaseService.java: Anmeldung, Aufträge und Stationen, Kunden, Kuriere, CSV-Daten sowie Verbindungs- und Schemadiagnose. Nur dieser Service verwendet JDBC und steuert Datenbanktransaktionen. Auftragsanzahl, Liste und Stationen werden in einer gemeinsamen Lesetransaktion gelesen. SQL-Werte werden als Parameter gebunden.

Der zentrale Schreibzugang update(...) ist in der aktuellen Ausbaustufe gesperrt und öffnet keine Verbindung. Die Fachprozesse für schreibende Vorgänge sind weiterhin erst vollständig zu portieren. Architekturtests prüfen Java-Bytecode und Python-Launcher auf Direktzugriffe außerhalb dieser Schicht. Die vorhandene PHP-Anwendung ist von dieser Umstellung nicht betroffen.

Projektstruktur

votian/       Bestehende PHP-Anwendung, unverändert weiter nutzbar
frontend/     React, TypeScript, Vite und Stadtbote-Oberfläche
backend/      Spring Boot, JDBC und vorhandene Benutzer-/Rechtestruktur
docs/         Analyse, Fachregeln, Abdeckung und weitere Abnahme
scripts/      Lokaler Start mit vorhandener Konfiguration
tests/        Zusätzliche Konfigurations- und Browserprüfungen