Erweitere Workflows und Statusmails und bereinige Stadtbote-Tasks

Übernehme die PHP-Fachanpassungen für Foto-Workflows, Mail-Empfänger, Fahrzeugdaten, Nachbearbeitung und PZM-Festpreise.

Beschränke Cron-Funktionen auf Stadtbote, verbessere Java-Typsicherheit und Nullbehandlung und aktualisiere Tests und Dokumentation.

Erhöhe die Backend-Version auf 0.2.1 und passe Maven-Ressourcen sowie VS-Code-Projekteinstellungen an.

docs/FUNKTIONSABGLEICH-2026-11-09.md

@@ -0,0 +1,117 @@
+# PHP-Serveränderungen: Abgleich und Übernahme – 9. November 2026
+
+Die sechs beim Quellcode-Abgleich festgestellten Abweichungen wurden im lokalen NG-Arbeitsbaum umgesetzt. Der PHP-Server und das bereitgestellte Image wurden nicht verändert.
+
+## Umsetzung
+
+| Befund | Umsetzung in NG |
+| --- | --- |
+| Standard-Mail-Empfänger ersetzen | Checkbox bei Auftragserfassung und in der Statusmail-Ansicht bestehender Aufträge. `996` sperrt Standardmails und Stationsmails; zusätzliche Empfänger bleiben aktiv. Beim Aufheben bleiben vorherige Versandkennzeichen erhalten. Kopien und Daueraufträge übernehmen die Auswahl. |
+| Externe Workflow-Verwaltung | Kundenbezogener, acht Stunden gültiger HMAC-SHA256-Link; eingebetteter Editor und neuer Tab. Speichermeldungen werden auf Herkunft und Fenster geprüft. Neue Kundenkopien übertragen keine alten Workflow-Einstellungen mehr. Alte REST-Schreibwege sind für neue Vorgänge geschlossen; bestehende Übertragungsbelege bleiben abgleichbar. |
+| Globaler Foto-Schalter | Nur der Parameterwert `true` aktiviert Workflows. Ansonsten gelten klassische kundenspezifische Fotoanforderungen, Sperren und allgemeine Foto-Vorgaben; gespeichert als `tr_photo`. Keine Workflow-Service-Aufrufe im klassischen Modus. Bereits wartende Übertragungen bleiben bis zur Wiederaktivierung erhalten. |
+| Tragkraft Hebemittel | `crvh_working_load_limit_lift` im Fahrzeugstamm, ganzzahlig 0–99999 kg, einschließlich Speicherung und Fahrzeugkopie. |
+| Nachbearbeitung manuell aufheben | Freigabe ohne zugeordneten Transporteur wird vor Änderungen abgewiesen, auch bei noch offenen Aufträgen. |
+| Übernommener Festpreis | Die PZM-Herkunft wird getrennt ermittelt. Manuelle Festpreise bleiben bei Änderungen erhalten; für übernommene PZM-Preise gibt es nach Neukalkulation eine ausdrückliche Beibehaltungsoption. |
+
+Für die externe Verwaltung muss `WORKFLOW_MANAGEMENT_SECRET` als Laufzeit-Secret mit demselben Schlüssel wie im Workflow-Editor gesetzt werden. `WORKFLOW_MANAGEMENT_URL` kann die vollständige Editor-URL ohne Query enthalten; andernfalls wird `/wf/workflows/index.html` am Ursprung von `LEGACY_APP_URL` verwendet. Es wurde kein Schlüssel in Quellcode oder Beispieldateien übernommen.
+
+Der Workflow-Schalter wird in NG konsistent für Auswahl, Speicherung und Wiederholungsübertragung angewendet. Im aktuellen PHP ist der Schalter in `ajaxReqJob.php` vorhanden, während `job_options.php` ihn weiterhin fest auf `true` setzt.
+
+## Ausgangsbefunde vor der Umsetzung
+
+Die folgenden Feststellungen beschreiben den Zustand **vor** der Übernahme. Die genannten PHP-Fundstellen und Bestandsnachweise bleiben die Vergleichsbasis.
+
+## Historische Befunde des Abgleichs
+
+### 1. Standard-Mail-Empfänger pro Auftrag ersetzen – hohe Priorität
+
+PHP bietet jetzt „Standard-Mailempfänger für diesen Auftrag ersetzen“. Bei eingetragener Auftrags-Mailadresse setzt das Speichern `jb_automailsent`, `jb_automailsent2` und `jb_automailsent3` auf `996`; beim Aufheben der Option werden sie gegebenenfalls wieder auf `0` gesetzt. Beim Laden wird die Auswahl wiederhergestellt. Die Standard-Automailer für Erfassung, Abholung, Erledigung und Stationsmeldungen schließen `996` aus. Der getrennte Versand an die Auftragsadresse bleibt davon unberührt.
+
+NG besitzt zusätzliche Empfänger, aber weder die Ersetzen-Option noch die Behandlung von `996`. `AutomaticOrderMailPolicy` sperrt `998`/`999`, bei Erledigung zusätzlich `997`; `AutomaticStationMail` prüft ebenfalls nur `997`/`998`/`999`. Ein in PHP entsprechend markierter Auftrag kann bei aktiver NG-Mailverarbeitung deshalb weiterhin an die ausdrücklich ersetzten Standardempfänger versendet werden, sofern die übrigen Bedingungen erfüllt sind. Ein tatsächlicher Fehlversand wurde nicht ausgelöst oder behauptet.
+
+- PHP: `jobs/job_tour.php:1098`, `jobs/job_options.php:2011`, `jobs/get_saved_tour.php:374`, `jobs/job_edit.68.20.js:457`; Ausschlüsse in `include/inc_automailer.inc.php:63`, `:153`, `:246`, `:345` und den jeweiligen Barzahler-Abfragen.
+- NG: `backend/src/main/java/de/stadtbote/votian/OrderEntryMail.java:17`, `AutomaticOrderMailPolicy.java:51`, `AutomaticStationMail.java:36`.
+- Damals offen: Auswahl, Speicherung, Wiederherstellung und Aufhebung sowie die Sperre in allen betroffenen Standardversandwegen. Zusätzliche Empfänger dürfen dabei nicht pauschal gesperrt werden.
+
+### 2. Neue externe Sets-/Workflow-Verwaltung – fehlt
+
+PHP hat am 09.11. die bisherige Bearbeitung der Foto-Set-/Flow-Freigaben im Kundenformular ersetzt. „Sets/Flows bearbeiten“ öffnet die externe Verwaltung unter `/wf/workflows/index.html` für den gewählten Kunden über einen signierten, zeitlich begrenzten Link. Dialog und neuer Tab sind vorgesehen. Die bisherigen Schreibblöcke für Fotoeinstellungen beim Anlegen und Speichern des Kunden sind auskommentiert.
+
+NG verwendet weiterhin den eigenen `CustomerPhotoSettings`-Dialog und überträgt Änderungen an `/settings/kunde/{customer}`. Der neue Einstieg und die Rückmeldung aus der externen Verwaltung fehlen. Offen ist die neue Verwaltung, nicht die Fotoauswahl insgesamt. Ob der bisherige Service-Endpunkt weiterhin unterstützt wird, wurde nicht durch einen Schreibaufruf getestet.
+
+- PHP: `admin/customer_special.php:694`, `:1235`, `:3593`, `:3636`, `:3648`, `:3678`.
+- NG: `frontend/src/CustomerPhotoSettings.tsx:12`, Einbindung in `frontend/src/BusinessForms.tsx`; `backend/src/main/java/de/stadtbote/votian/CustomerPhotoSettings.java:14` und `:122`.
+- Damals offen: neuen Einstieg samt Berechtigungs-/Signaturvertrag anbinden und bisherigen Bearbeitungsweg entsprechend ablösen. Schlüsselwerte sind nicht Bestandteil dieses Berichts.
+
+### 3. Globaler Schalter `TR_PHOTO_WORKFLOW` – wird nicht berücksichtigt
+
+Seit 05.11. liest PHP den globalen Parameter `TR_PHOTO_WORKFLOW`; nur `true` aktiviert den Set-/Workflow-Zweig. Andernfalls liefert PHP die älteren kundenbezogenen Foto-Vorgaben aus `getCsPhotoConf`.
+
+NG entscheidet in `OrderPhotoWorkflows.options` ausschließlich anhand der konfigurierten Service-URL. Eine Auswertung von `TR_PHOTO_WORKFLOW` fehlt im NG-Anwendungscode. Bei ausgeschaltetem oder fehlendem Parameter weicht das Verhalten deshalb ab. Der tatsächlich gesetzte Datenbankwert wurde nicht geprüft.
+
+- PHP: `include/ajaxReqJob.php:13`, `:123`.
+- NG: `backend/src/main/java/de/stadtbote/votian/OrderPhotoWorkflows.java:28` und `:33`.
+- Damals offen: Umschaltung und vorgesehenen älteren Foto-Modus abbilden; eine vorhandene URL allein genügt nicht mehr als Aktivierungsbedingung.
+
+### 4. Fahrzeugfeld „Tragkraft Hebemittel“ – fehlt
+
+PHP liest und schreibt seit 30.10. `crvh_working_load_limit_crane` und `crvh_working_load_limit_lift`. Im aktuellen Formular ist „Tragkraft Hebemittel“ (`…_lift`) aktiv. Das Kranfeld ist mit `if (false)` ausgeblendet und wird nicht als zweites fehlendes aktives Eingabefeld gezählt.
+
+NGs Felddefinitionen enthalten beide Felder nicht. Der Hebemittelwert kann deshalb nicht angezeigt oder gepflegt werden und wird von der feldbasierten Fahrzeugkopie nicht übernommen. Das Vorhandensein der Spalten in der tatsächlich angeschlossenen Datenbank ist vor einer Umsetzung zu prüfen.
+
+- PHP: `admin/courier_vehicle.php:1069`, `:1649`; `include/inc_vehicle.inc.php:22`, `:210`, `:265` sowie die INSERT-/UPDATE-Feldlisten des Formulars.
+- NG: `backend/src/main/java/de/stadtbote/votian/MasterData.java:48`, `VehicleMasterSettings.java:13`, `VehicleCopy.java:29`.
+- Damals offen: aktives Feld, Werteprüfung, Speicherung und Kopierverhalten ergänzen. Das abgeschaltete Kran-Eingabefeld nicht ungeprüft aktivieren.
+
+### 5. Nachbearbeitungsmarkierung ohne Transporteur aufheben – nur teilweise abgesichert
+
+PHP verweigert seit 04.11. das manuelle Setzen von `jb_incomplete=0`, solange `cr_id` fehlt oder `0` ist. Die Prüfung ist nicht auf erledigte oder nicht stornierte Aufträge beschränkt.
+
+NG prüft den fehlenden Kurier in `OrderCompletionChecks.reasons` nur bei `jb_status=2` und `jb_storno=0`. Bei einem noch nicht erledigten Auftrag ohne Transporteur kann die Bearbeitung somit „Nachbearbeitung erforderlich“ aufheben, wenn die übrigen Prüfungen erfüllt sind. Der reguläre Abschluss über `COMPLETE`/`COMPLETE_STOP` verlangt in NG bereits einen Kurier und ist keine neue Lücke.
+
+- PHP: `admin/jb_detail.php:1711`.
+- NG: `backend/src/main/java/de/stadtbote/votian/OrderCompletionChecks.java:27`, `OrderOperations.java:68` und `:91`.
+- Damals offen: neue Bedingung für die manuelle Freigabe nachziehen; automatische Abschlussprüfungen und Stornofälle dabei bewusst unterscheiden.
+
+### 6. Übernommener manueller Festpreis bei PZM-Kunden – abweichende Neukalkulation
+
+PHP prüft einen bereits gefüllten Festpreis beim Absenden wegen geänderter Angaben nun nur erneut, wenn `fixprice_was_zone` gesetzt ist, der übernommene Preis also aus der PZM stammt. Der Benutzer kann den neuen Preis außerdem ablehnen und mit dem bisherigen Preis erneut absenden.
+
+NG setzt `templatePriceActive` beim Laden für jeden positiven Festpreis. `recalculateTemplate` schaltet bei einem PZM-Kunden daraufhin auf `AUTO`, ohne die Preisquelle zu unterscheiden. Eine Adressänderung nach dem Laden einer Vorlage mit manuell vereinbartem Festpreis führt damit ebenfalls zu automatischer Neukalkulation. Der Benutzer kann wieder auf „Festpreis“ umstellen; die neue PHP-Unterscheidung wird dadurch nicht automatisch übernommen.
+
+- PHP: `jobs/job_edit.68.20.js:6261`, `:6264`, `:6706`; Herkunftserkennung in `jobs/get_saved_tour.php:265`.
+- NG: `frontend/src/OrderEntryForm.tsx:202`, `:207`, `:245`, `:263`; ergänzend `backend/src/main/java/de/stadtbote/votian/OrderTemplatePricing.java:11`.
+- Damals offen: Preisursprung erhalten und nur den passenden übernommenen PZM-Preis automatisch neu ermitteln; bewusste Beibehaltung eines vereinbarten Festpreises ermöglichen.
+
+## Bereits abgedeckt oder keine neue Fachlücke
+
+- **Gruppenzuordnung:** PHP korrigiert NULL-Behandlung und doppeltes Anhängen der Gruppenliste. NG verwendet bereits eine deduplizierte ID-Menge und ersetzt den Wert per parametriertem UPDATE (`GroupAdministration.java:98`).
+- **Auftragslisten:** Die Umbenennung von `Ref.` zu `Refresh` ist keine neue Fachfunktion.
+- **Drittland-/Kommissionsprüfung und regulärer Abschluss:** Entsprechende NG-Prüfungen sind vorhanden. Die engere Abweichung beim manuellen Aufheben der Nachbearbeitung steht oben.
+- **Generierte Kataloge:** Elf geänderte `jobs/job_options_<NL>.js` enthalten Katalogvariablen, keine neuen Funktionsdefinitionen. NG liest die zugehörigen Kataloge aus der gemeinsamen Datenbank, unter anderem in `OrderEntryCatalog`. Alte generierte Inhalte waren nicht für alle gespeicherten Prüfsummen rekonstruierbar; eine vollständige Datenparität ihrer Werte wird nicht behauptet.
+- **Versions-/Sicherungskopien:** Neue Git-Pfade sind teilweise nachweislich Kopien bekannter Stände, etwa `customer_special_.php`, `group_31.php`, `jb_list_03.php`, `inc_vehicle_19.inc.php` und `inc_automailer_13.inc.php`. Sie wurden nicht allein wegen eines neuen Dateinamens als neue Funktionen gezählt. Die übrigen bereits inventarisierten aktiven Cron-/Autoranking-Dateien sind unverändert.
+- **Ausgeschlossener Umfang:** Classic-Sammelübergabe und die dokumentiert ausgeschlossenen HHA-/PTnova-/fremden Replikations- und PHP-Dateiwartungsfunktionen bleiben außerhalb der Restliste.
+
+## Umfang und Nachweise
+
+Frische Inventur am **09.11.2026 um 15:24 Uhr Europe/Berlin**: 2.710 Quell- und Hilfsdateien, keine Lesefehler oder während eines einzelnen Lesevorgangs instabilen Dateien. Die Zahl umfasst auch Bibliotheken, SQL-Dateien, Sicherungen und Verwaltungsdateien; sie ist keine Zahl von Fachfunktionen.
+
+Vergleichsbasis sind 1.363 eindeutige Pfade aus dem allgemeinen Abgleich vom 20.10., dessen Ergänzung und den Cron-Prüfbeständen vom 26./27.10.: **1.335 unverändert, 23 verändert, fünf entfernt.** Geändert sind elf PHP-Dateien, eine fachliche JavaScript-Datei und elf generierte JavaScript-Kataloge. Die fünf entfernten Dateien sind frühere Automailer-/Testvarianten.
+
+Alle zwölf geänderten fachlichen PHP-/JavaScript-Dateien wurden gegen exakt zur alten SHA-256-Prüfsumme passende Vorstände verglichen. Für `job_edit.68.20.js` wurde der passende alte Inhalt aus der Server-Git-Historie rekonstruiert. Zusätzlich wurden Git-Historie seit 20.10. einschließlich neuer Pfade und der aktuelle Server-Arbeitsbaum geprüft. Die 1.352 erstmals im erweiterten Inventar enthaltenen Dateien wurden nicht pauschal als seit Oktober neu entstanden gewertet.
+
+Server-HEAD: `f567b835974774c21260e30f781d9a89c475697c`. Abschließend wurden 27 gelesene Dateien außerhalb der regelmäßig generierten Kataloge erneut geprüft: **keine Änderung während des Abgleichs**.
+
+Nachweise unter `work/php-audit-2026-11-09/`: `server-manifest.json`, `comparison.json`, `server-git.json`, `download-manifest.json`, `baseline-files.json`, `baseline-git.json`, `diff/`, `current/`, `final-source-check.json`. Die ursprüngliche vorläufige Berichtsfassung liegt dort als `previous-report.md`.
+
+Dies ist ein Quellcode-Differenzabgleich, keine erneute vollständige Abnahme aller historischen PHP-Funktionen. Datenbankwerte, laufende Dienste, tatsächlicher Mailversand, externe Workflow-Oberfläche und bereitgestelltes Image wurden nicht funktional getestet. Der früher offene Kategorie-9-/RETRANS-903-Abgleich wurde nicht neu als Datenbankbefund bewertet.
+
+Bei der anschließenden Umsetzung wurden ausschließlich lokale Anwendungsdateien, Tests und Dokumentation geändert. Datenbanktests verwenden eine isolierte lokale MariaDB und synthetische Daten; Mailtransport und externe Dienste werden simuliert. Keine Serverdateien oder produktiven Geschäftsdaten wurden geändert, keine echten Mails versendet und kein Deployment ausgelöst.
+
+## Validierung der Umsetzung
+
+- Frontend: TypeScript-/Vite-Produktionsbuild und alle 44 Frontend-Tests erfolgreich.
+- Backend: `./mvnw -q clean verify` erfolgreich; 1.404 ausgeführte Tests, 242 ohne Integrationstest-Umgebung übersprungen.
+- Alle zehn ausgewählten MariaDB-Integrationstests erfolgreich: Auftragserfassung/-bearbeitung, Mailversandregeln, Kunden-/Fahrzeugkopie, Hebemittel-Tragkraft, Workflow-Verwaltung, klassische Fotos und Daueraufträge. Sie liefen mit `CRM_INTEGRATION_URL=jdbc:mariadb://127.0.0.1:33079/crm_qa` gegen eine isolierte Testdatenbank.
+- Nachweise: `work/php-parity-final-build.log`, `work/php-parity-unit-result.json`, `work/php-parity-final-integration.log`, `work/php-parity-integration-result.json`, `work/php-parity-frontend.log`, `work/php-parity-frontend-tests.log`.
+- Die tatsächliche externe Editor-Oberfläche, das gemeinsame Laufzeit-Secret und die produktive Datenbank wurden nicht funktional geprüft. Die Fahrzeugspalte muss wie im aktuellen PHP-Schema bereits existieren; es gibt keine produktive Schemaänderung.