Portiere PHP-Cronjobs auf Spring-Tasks und ergänze Legacy-Tests

Migriert die weiterhin benötigten Zeitaufgaben einschließlich SOAP-Importen, Betriebsstatus und Wiederanlaufkontrolle. Aktiviert 115 native Spring-Tasks im Docker-Image ohne Cron-Daemon oder PHP und dokumentiert die entfallenen HHA-Aufrufe. Ergänzt PHP-/UI-Testwerkzeuge und aktualisiert den Projektstand auf Version 0.2.0.

docs/CRON-MIGRATION.md

@@ -0,0 +1,235 @@
+# PHP-Crontab → Spring Boot
+
+Stand: 27.10.2026. Grundlage sind die am 26.10.2026 per SSH gelesenen Dateien
+unter `172.16.0.158:/data/0/votian-test/html` sowie ergänzend
+`/data/0/votian-test-2/html`. Der Zeitplan stammt aus
+`sysadmin/votian_admin/crontab_20211207.sav`. Der Betreiber hat diese Crontab
+als aktuell bestätigt und angekündigt, auf dem Testsystem keine PHP-Cronjobs
+mehr auszuführen. Der frühere lokale PHP-Bestand wurde nicht verwendet.
+
+## Native Implementierung
+
+| PHP-Aufruf | NG-Gruppe | Termin Europe/Berlin | Verhalten |
+|---|---|---|---|
+| `do_auto_logout_by_autorevokes` | `courier-logout` | Jede halbe Stunde | NL 3, mindestens zwei automatische Entzüge in 30 Minuten, keine Annahme/Ablehnung, numerische Standort-PLZ; Belegungsprüfung, `LOGOUT`, PDA-Kommando mit 16 Stunden Gültigkeit, Audit 143. |
+| `do_cron_STB_MAILS` | `stb-compliance` | Mo–Fr 04:00 | 78 getrennte Tasks: 1710, 1623, 1717–1720, 1629 für NL 1–11; 1715 nur NL 8. Datumswarnungen und PBSG/COV/FZ/GDP/BMS-Filterpflege. |
+| `do_cron_export_SB` | `sb-master-export` | Täglich 20:45 | 30 Tasks: Debitoren, Kreditoren, Fahrzeuge für NL 1–9 und 11. Originale Benutzer, RETRANS-Profile, Nummern und Dateinamen. Dauerhafte Dateispeicherung, Änderungskennzeichen, FTP-Übergabe über die vorhandenen nativen Exportdienste. |
+| `do_cron_special_HHA` | `hha-safebags` | Täglich 09:40 | Safebags Artikel 4285, Kennzeichen 28=1, mindestens sieben Tage alt; HTML-Bericht bei Treffern. |
+| `mysql_status.php` | `mysql-status` | Alle fünf Minuten | Zähler der konfigurierten Anwendungsdatenbank, Gesamtraten und Intervallraten; persistente Historie für 62 Tage, monatlicher CSV-Download. |
+| `do_bzip2.php` | `file-maintenance` | Täglich 00:01 | Native bzip2-Kompression der älteren `mps2-bin.0*`-Dateien und der Logdateien des Vormonats; Löschung regulärer Dateien aus expliziten temporären Verzeichnissen. |
+| `do_cron_monitor_replication` | `replication-monitor` | Alle 15 Minuten | Fachliche Zählervergleiche mit PHP-Toleranzen: STB 4, HTG/HTM/HTM_OLD/HHA 2, INT 7, MUH 1. Alarm bei Rückstand oder Nichterreichbarkeit. |
+| `do_cron_soap_1` | `hha-soap-master` | Täglich 05:10 | PTnova-Gerätestammdaten und Betriebsmeldungen; neue Serviceunits, Objektlager und Container-Lagerbestände. |
+| `do_cron_soap_0` | `hha-soap-status` | Täglich 05:20 | PTnova-Gerätestatus, offene Betriebsmeldungen, Geld- und Kartenbestände, Tageshistorie um 03:00. |
+
+Damit sind alle neun weiterhin benötigten PHP-Cron-Aufrufe als
+115 einzeln protokollierte Spring-Tasks implementiert. Die zwei weiteren Aufrufe
+der bestätigten Crontab entfallen gemäß Betreiberentscheidung vom 27.10.2026.
+Kein Task startet PHP, Shell-Kommandos
+oder eine alte HTTP-Oberfläche. Die getrennt vorhandenen sechs NG-Dauerdienste
+(Auftragsabschluss, Daueraufträge, Statusmail, Angebote, Angebotsentzug,
+BWV-Retouren) behalten ihre bisherigen Konfigurationsschalter.
+
+## Bewusst entfallene HHA-Aufrufe
+
+Der Betreiber hat am 27.10.2026 bestätigt, dass diese beiden Funktionen keine
+Rolle mehr spielen und in NG entfallen dürfen:
+
+* 02:15 `do_cron_vht_dispo_days_HHA` → `include/cron_vht_dispo_days_HHA.php`.
+* 04:30 `do_cron_export_HHA` → `export/export_illt_MC.php`, Modi 101/102/103.
+
+Sie sind keine offenen Migrationspunkte mehr und erscheinen nicht mehr als
+fehlende Funktionen im Betriebsstatus. Für diese Aufrufe werden keine NG-Tasks
+registriert. Die Entscheidung betrifft nur diese beiden Aufrufe; die beiden
+PTnova-SOAP-Importe und die HHA-Safebag-Prüfung bleiben enthalten.
+Die Implementierung der weiterhin benötigten PHP-Cron-Aufrufe ist damit
+vollständig. Das Docker-Image aktiviert die Tasks künftig beim Start; Produktionskonfiguration und Bereitstellung auf dem Zielserver stehen noch aus.
+
+## Grundlage der SOAP-Übernahme und Abgrenzung
+
+Die beiden SOAP-Modi wurden anhand von
+`/data/0/votian-test-2/html/sysadmin/soap/soap.php` und dessen aktiven
+Datenbankpfaden portiert (SHA256
+`b4e8580d63c1f2545870ca596dfca820adc452879af05b709b2e4578dc5fb407`).
+Die Wrapper nennen zwei frühere Instanzen unter `/home/mps2/hha` und
+`/home/mps2/hha_test`. Eine NG-Instanz verarbeitet ihre konfigurierte Datenbank
+und SAP-Umgebung; es erfolgt kein zusätzlicher automatischer Produktionslauf.
+
+`ping`, `certbot`, `/sbin/handle_log` und der aktive Shell-Wrapper `do_rsync`
+sind Betriebssystemaufgaben, keine PHP-Cronjobs. Sie werden durch diese Änderung
+nicht übernommen oder abgeschaltet. Der auskommentierte `do_rsync.php` und
+andere nicht aktive Skriptvarianten werden ebenfalls nicht aktiviert.
+
+## Konfiguration und Inbetriebnahme
+
+Das Docker-Image setzt `SPRING_TASK_GROUPS` auf alle neun Gruppen und plant
+beim Start 115 Tasks direkt im Spring-`ThreadPoolTaskScheduler` ein.
+Der Container startet ausschließlich `java -jar /app/app.jar` als Hauptprozess.
+Es werden weder Cron-Daemon noch Crontab, PHP-Prozesse oder Shell-Wrapper
+für diese Aufgaben benötigt. Die Cron-Ausdrücke sind nur das Zeitplanformat
+innerhalb von Spring Boot.
+
+`SPRING_TASK_GROUPS` kann als Container-Umgebungsvariable mit einer
+kommagetrennten Auswahl überschrieben werden. Beispiel für ausschließlich
+Diagnose: `-e SPRING_TASK_GROUPS=mysql-status`. Ein ausdrücklich leerer Wert
+(`-e SPRING_TASK_GROUPS=`) deaktiviert alle neun Gruppen.
+Die Variable hat Vorrang vor dem bisherigen `LEGACY_CRON_JOBS`; dessen leerer
+Eintrag in einer bestehenden `.env` deaktiviert die Image-Vorgabe deshalb nicht.
+Beim direkten Java-Start ohne `SPRING_TASK_GROUPS` gilt weiterhin
+`LEGACY_CRON_JOBS` (standardmäßig leer). Die sechs gesonderten NG-Dauerdienste
+behalten ihre bisherigen eigenen Schalter.
+
+Die Vorlage `.env.example` enthält die Produktionsparameter. Ohne passende
+SAP-Zugänge, SMTP-Konfiguration, Exportprofile, Replikationsziele oder
+Dateimounts können die betreffenden Tasks nicht erfolgreich arbeiten und
+melden die fehlenden Voraussetzungen im Betriebsstatus. Eine eingeplante
+Aufgabe ist noch kein Nachweis einer erfolgreichen fachlichen Ausführung.
+Der Startlog nennt Anzahl und Gruppen der tatsächlich eingeplanten Aufgaben.
+Beim Herunterfahren werden noch nicht fällige Aufgaben verworfen; laufende
+Aufgaben erhalten bis zu 30 Sekunden zum Abschluss. Für Docker deshalb
+`--stop-timeout 40` setzen. Unterbrochene Läufe behalten ihren dauerhaften Beleg.
+
+Die Aktivierung ist für den späteren Docker-Betrieb vorbereitet. Es wurde
+keine Produktionsinstanz gestartet und keine vorhandene lokale `.env`
+verändert. Echte Empfänger, FTP-/SAP-Endstellen und Bestandsverzeichnisse
+wurden nicht für Funktionstests verwendet.
+
+* **STB:** SMTP muss eingerichtet sein; Empfänger werden aus
+  `MAIL_CRON_106_TO_ADDRESS` bzw. für EG-Lizenz aus `MAIL_CRON_102_TO_ADDRESS`
+  gelesen (NL, dann global). Absender ist `SMTP_FROM`. Die in PHP hart
+  codierten Entwickler-Fallbacks und Bcc-Adressen werden nicht übernommen.
+* **HHA-Safebags:** `LEGACY_CRON_HHA_MAIL_TO` und optional
+  `LEGACY_CRON_HHA_MAIL_BCC` explizit setzen. Absender aus NL-Parameter
+  `MAIL_SENDER_ADDRESS`, sonst `SMTP_FROM`.
+* **Export:** Bestehende Exportablage, FTP-Parameter, Exportkonten und Rechte
+  müssen verfügbar sein. Fehlende Profile oder Felddefinitionen sperren den
+  jeweiligen Task. NL 90 bleibt wie im PHP-Quelltext auskommentiert.
+* **PTnova/SOAP:** `LEGACY_CRON_SOAP_URL`, `_USER`, `_PASSWORD` für den
+  zu dieser Instanz gehörenden SAP-Endpunkt setzen. HTTPS-Zertifikate werden
+  geprüft, Weiterleitungen nicht verfolgt; fünf Minuten Gesamtzeit und 32 MiB
+  Antwortgröße begrenzen den Abruf. `_HEADQUARTERS` ist standardmäßig 1,
+  `_CONTAINER_STOCK` 1000 wie in PHP. Der Betriebsdatenbankbenutzer braucht
+  Zugriff auf `articleitemhistory` im konfigurierten `HISTORY_DB_SCHEMA` sowie
+  die Bestands-, Artikel-, Parameter- und Laufbelegtabellen. SAP-Zugänge bleiben
+  außerhalb des Quellcodes. Die beiden Gruppen getrennt aktivieren.
+* **Replikation:** `LEGACY_CRON_REPLICATION_TARGETS` ist ein JSON-Objekt,
+  z. B. `{"STB":["primary.example:3391","replica.example:3391"]}`.
+  Erster Eintrag ist der Primärserver. Zugänge ausschließlich über
+  `LEGACY_CRON_REPLICATION_USER` / `_PASSWORD`, Alarmempfänger über `_MAIL_TO`.
+  Kein automatischer Zugriff auf die fest codierten Produktionsserver aus PHP.
+  TT ist im aktuellen PHP deaktiviert und wird nicht registriert.
+* **Dateiwartung:** Die drei `LEGACY_CRON_*_DIRECTORIES`-Variablen nennen
+  ausschließlich hierfür eingebundene Altverzeichnisse. Temporäre Verzeichnisse
+  werden vollständig von regulären Dateien geleert, wie im PHP-Aufruf.
+  Keine NG-Dokument- oder Exportablage eintragen. Verzeichnisse dürfen sich
+  nicht überlappen; Symlinks werden nicht verfolgt. Die neueste Binlogdatei
+  (einschließlich Gleichständen) und aktuelle Monatslogs bleiben erhalten.
+  Vor dem Entfernen einer Quelle wird das Archiv sicher veröffentlicht;
+  vorhandene abweichende Archive werden nicht überschrieben.
+* **MySQL-Status:** Verwendet `DB_URL` statt PHPs festem lokalen Port 3391.
+  Originale Zähler und abgeleitete Raten sind als CSV unter
+  `/api/administration/cron/database-status?month=2026-10` abrufbar.
+  Nach Serverneustart oder bei fehlender Vorgängermessung bleiben
+  Intervallraten leer. Werte liegen in `genericdatacontainer` statt unter `/root`.
+
+Cron-Ausdrücke lassen sich pro Gruppe über die in `.env.example` genannten
+Variablen überschreiben. Sie haben sechs Felder inklusive Sekunden.
+`Europe/Berlin` gilt unabhängig von der JVM-/Container-Zeitzone.
+Verpasste Termine während eines Stillstands werden nicht nachgeholt.
+
+## Laufkontrolle und Wiederanlauf
+
+Der Betriebsstatus zeigt die Tasks, feste Termine, nächsten Lauf und Ergebnisse. Laufbelege liegen unter
+`genericdatacontainer.gdc_obj_type='ngcron'`. Der vor der Verarbeitung
+gespeicherte Beleg und eine datenbankweite Sperre verhindern doppelte
+Verarbeitung durch mehrere NG-Instanzen. Wartende Tasks behalten ihren
+ursprünglichen Termin auch bei ausgelasteten Scheduler-Threads.
+
+Ein unterbrochener Lauf bleibt `RUNNING` oder `UNCERTAIN` und wird auch am
+nächsten Tag nicht automatisch wiederholt. Vor Freigabe mögliche Teilwirkungen
+prüfen (SMTP-Logs, gespeicherte Exportdatei, FTP-Eingang, PTnova-Bestände und Tageshistorie). Exportvorgänge können
+über die bestehende Datentransfer-Oberfläche unter dem jeweiligen Exportkonto
+fortgesetzt werden. Danach im Betriebsstatus „Bisherige Teilwirkungen und
+Versandprotokolle geprüft“ markieren und „Nächsten Termin freigeben“ wählen.
+Die entsprechende API lautet:
+
+`POST /api/administration/cron/{id}/review`
+
+mit `{"slot":"<slot aus Betriebsstatus>","reviewed":true}` und gültiger
+Sitzung/CSRF-Token. Erfordert Mitarbeiterverwaltungsrecht in der ursprünglichen
+Niederlassung, prüft die Laufversion und protokolliert die Freigabe. Ein aktuell
+laufender Task lässt sich nicht freigeben. Die Freigabe erlaubt nur den nächsten
+regulären Termin, keinen sofortigen Neuversand.
+
+Bekannte bewusste Korrekturen gegenüber PHP: ungültige Kalenderdaten blockieren
+den Lauf; Filterupdates erhalten fremde Tokens und verwenden die richtige
+Kurier-ID statt des in den PHP-Prüfskripten vorkommenden `crvid`-Tippfehlers.
+Die Belegungsprüfung verwendet bei fehlenden PLZ-Fahrzeiten 30 Minuten,
+damit ein aktiver Fahrer nicht wegen eines SQL-NULL-Ergebnisses abgemeldet wird.
+Leere Fristen verändern keine Filter. Führungszeugnisdatum plus sechs Monate
+verwendet den PHP-Monatsüberlauf. Das Skript mit Dateiname 1629 prüft im
+aktuellen Quelltext Feld **441**, was auch NG übernimmt.
+
+## PTnova-Importverhalten
+
+Anfrage und SOAPAction entsprechen den SAP-Operationen `ZPtnWstpMasterdata`
+und `ZPtnWstpStatusdata`. Die Lesemarken bleiben kompatibel zu PHP:
+`genericdatacontainer`, Objekt `hq`, Feld `pt_nova`, Kontext `1` bzw. `0`.
+Abgerufen wird ab der neueren Marke aus gespeichertem Lauf und gestern 00:00.
+Die neue Marke wird erst nach gültiger Antwort und abgeschlossenen Schreibvorgängen
+auf die Startzeit des Abrufs gesetzt. Bei HTTP-/XML-Fehlern bleibt sie unverändert.
+
+Bestehende Geräte werden über die Seriennummer gefunden und im Stammdatenlauf
+nicht überschrieben. Neue Geräte erhalten wie im aktiven PHP-Code das
+Containerlager, ein Objektlager und einen erhöhten Stückbestand. Betriebsmeldungen
+werden je Artikeltyp/Code aktualisiert. Statusdaten übernehmen offene Meldungen,
+`NominalAmnt` für BEK/MEK/ZGS/RGS sowie `NominalStock` für KARTEN bei
+STU/STH/STB/STVS. Kartenbestände überschreiben Feld 09 nach der Geldübernahme.
+Karten allein erzeugen wie in PHP keine neue Tageshistorie. Unbekannte Artikeltypen
+oder Geräte werden gezählt und übersprungen.
+
+Beide Modi teilen eine datenbankweite Importsperre. Die anschließenden Schreibvorgänge
+verwenden Tabellensperren, damit auch MyISAM-Tabellen berücksichtigt sind.
+MyISAM-Änderungen sind nicht rückrollbar: Fehler während der Schreibphase markieren
+den Lauf deshalb als `UNCERTAIN`, behalten die alte Lesemarke und erfordern die
+beschriebene Prüfung. SOAP-Netzwerkzugriffe erfolgen vor den Tabellensperren.
+
+Bewusste Korrekturen: SOAP-Fehler mit HTTP 200 gelten nicht als Erfolg;
+DTD/externe XML-Entitäten sind gesperrt; auch Geräte-Stammdaten werden auf
+HHA/HDAG und die angefragten Gerätetypen begrenzt. Mehrdeutige Seriennummern,
+Artikelzuordnungen und fremde Niederlassungslager lösen einen Fehler aus.
+Die von PHP undefiniert übergebene Meldungspriorität wird bei Neuanlage mit 0
+belegt. Deaktivierte PHP-Blöcke für automatische Standortpflege und weitere
+Statusattribute werden nicht als zusätzliche Schreibaktionen aktiviert.
+
+## Prüfung
+
+Automatisierte Prüfungen decken Crontab-Zuordnung, Wochenenden/Zeitumstellung,
+dauerhafte Laufbelege, parallele Starts, unbestätigten Versand, Datums-/Filterregeln,
+Dateikompression mit Konflikten und Symlinks sowie Datenbank- und Replikationszähler
+ab. Eine isolierte MariaDB prüft die tatsächlichen SQL-Schreibpfade einschließlich
+PDA-Abmeldung, Filterpflege und der Wiederanlaufsperre. Ergänzende SOAP-Tests prüfen
+Anfragen, sichere XML-Auswertung, Größenlimit, Importwiederholungen,
+Bestands-/Historienzuordnung und einen absichtlich ausgelösten MyISAM-Teilabbruch. Echte SAP-, SMTP- und
+FTP-Endstellen sowie produktive Dateimounts sind damit nicht abgenommen.
+
+Abschlussprüfung am 26.10.2026: vollständiges `mvn verify` erfolgreich mit
+1646 Backendtests, keinen Fehlern und 3 umgebungsabhängig übersprungenen Tests.
+Die 19 gezielten Cron-/SOAP-Prüfungen einschließlich isolierter MariaDB bestanden
+ebenfalls. Die zuvor geprüfte Oberfläche ist unverändert (44 Frontendtests).
+Der ausführbare Backend-Build 0.2.0 liegt unter
+`backend/target/votian-backend-0.2.0.jar`; der Hashabgleich bestätigte denselben
+Quellstand wie beim Testlauf. Es erfolgte keine Aktivierung der Jobs im Test-
+oder Produktionsbetrieb. Die lokale MariaDB-Testinstanz wurde danach entfernt.
+
+Nach Betreiberentscheidung am 27.10.2026: offene HHA-Meldungen entfernt,
+12 bestehende Cron-Tests erfolgreich und Backend-Paket neu gebaut. Zu diesem
+Zeitpunkt waren die Jobs noch deaktiviert; die PHP-Serverdateien wurden nicht verändert.
+
+Container-Aktivierung vorbereitet und geprüft am 27.10.2026: Das Image aktiviert
+alle neun Gruppen über `SPRING_TASK_GROUPS`. 14 gezielte Tests bestanden,
+einschließlich Konfigurationsvorrang und vollständigem Scheduler-Shutdown.
+Ein lokal gebauter Container ohne Netzwerk und ohne Produktionszugänge startete
+mit Java als PID 1 und meldete „115 von 115 eingeplant“. `cron`, `crond` und
+`php` sind im Laufzeit-Image nicht vorhanden. Der Container wurde anschließend
+sauber beendet und entfernt. Das Image wurde nicht veröffentlicht und auf dem
+späteren Produktionsserver wurde keine Instanz gestartet.