votianng/docs/CRON-MIGRATION.md

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.