Workflow/tasks/pdf_stamp_interactive.md

pdf_stamp_interactive — Interaktive Stempelplatzierung

Zweck: Zeigt dem Bearbeiter eine PDF-Vorschau, in der er per Doppelklick (Desktop) bzw. langem Drücken (Tablet) die Stempelposition setzt; ein Schieberegler skaliert den Stempel live (30–300 %). Der Workflow wartet, bis platziert wurde; dann wird das Stempelbild dauerhaft eingebrannt. Keine kryptografische Signatur — dafür ist pdf_sign zuständig.

Parameter

Name	Pflicht?	Default	Beschreibung
file	ja	—	Eingabe-PDF.
vorlage	ja¹	—	Vordefinierter Stempelgenerator: posteingang, postausgang oder bau.
vorlage_params	nein	—	Query-Parameter für den Stempelgenerator (nur mit vorlage).
stempel_auswahl	nein	—	Nur vorlage=bau: Komma-Liste von Stempelarten (oder alle). Der Bearbeiter wählt die Art in der GUI aus einem Dropdown; Bild und Maße wechseln mit.
stempel_default	nein	1. Eintrag	Voreingestellte Stempelart, z. B. ng.
stempel	ja¹	—	Pfad zu einer fertigen Stempelbild-Datei (PNG/JPG).
stempel_text	ja¹	—	Text, aus dem automatisch ein Stempelbild erzeugt wird (dunkelblau, zentriert).
breite_mm / hoehe_mm	nein	auto	Stempelmaße in mm. auto = aus der Bildgröße abgeleitet; ist nur eine Achse auto, bleibt das Seitenverhältnis erhalten. Text-Stempel ohne Bild: Fallback 60 × 25 mm.
output_var	nein	—	Zusätzlicher Variablenname für den Ergebnispfad (setzt auch <output_var>_url).

¹ Genau eine Stempelquelle angeben; Priorität bei Mehrfachangabe: vorlage → stempel → stempel_text.

Stempelarten der Vorlage bau (Parameter stempel von stempel-core.php):

ID	Bedeutung	druckt Summe?
frf	Fachtechnisch, rechnerisch und festgestellt	ja
ga	Geprüft und Anerkannt	ja
v	vorgeprüft	ja
f	freigegeben	ja
ng	Angebot Nachgerechnet	ja
zs	Zustimmung Aufsicht	nein
u	Unterschreiben (Unterschrift-Stempel)	nein
wb	Beauftragung	nein

Die fünf Block-Stempel drucken „auf ‹Summe› € — am ‹Datum› durch ‹Person›". Ihnen muss über vorlage_params eine summe mitgegeben werden (deutsches Format erlaubt: 12.345,67); fehlt sie, wird 0,00 € gedruckt. datum fällt auf heute zurück, person auf {{ICH.nachname}}.

<vorlage_params>summe={{summe}}&amp;datum={{DATE}}&amp;person={{ICH.nachname}}</vorlage_params>
<stempel_auswahl>ng,frf,ga,v,f</stempel_auswahl>
<stempel_default>ng</stempel_default>

Die geklickte Position ist der Mittelpunkt des Stempels; der Task rechnet auf die Seitengröße um und begrenzt den Stempel auf den Seitenrand. Das Ergebnis wird als neue Datei im Arbeitsverzeichnis abgelegt.

Eingangswerte: {{latest_pdf_path}} bzw. PDF-Pfad-Variable; {{temp_dir}}.

Ausgangswerte:

• latest_pdf_path, latest_pdf_url (gestempeltes PDF)
• <task_id>_page, <task_id>_x_mm, <task_id>_y_mm (Position obere linke Ecke in mm), <task_id>_breite, <task_id>_hoehe (finale Maße in mm), <task_id>_scale_pct
• bei stempel_auswahl: <task_id>_stempel_art (z. B. ng) und <task_id>_stempel_label
• optional <output_var> und <output_var>_url

<task type="pdf_stamp_interactive" id="eingangsstempel">
  <assign_to>{{registratur_mail}}</assign_to>
  <config>
    <file>{{latest_pdf_path}}</file>
    <vorlage>posteingang</vorlage>
    <breite_mm>50</breite_mm>
    <hoehe_mm>auto</hoehe_mm>
  </config>
</task>

Eigene Signatur (kryptografisch, mit P12)

Setzt man <eigene_signatur>true</eigene_signatur> (optional <grund>Unterschrift</grund>), verlangt die Platzier-GUI zusätzlich die eigene Zertifikatsdatei (.p12/.pfx) und das Zertifikat-Passwort. Statt das Stempelbild nur einzubrennen, wird das PDF dann kryptografisch signiert (pyHanko/PAdES-LTA über den ltv-signer) — mit dem Stempel als sichtbarer Signatur-Optik an der geklickten Position.

<task type="pdf_stamp_interactive" id="unterschrift">
  <assign_to>{{unterzeichner_mail}}</assign_to>
  <config>
    <file>{{doc_pfad}}</file>
    <vorlage>bau</vorlage>
    <eigene_signatur>true</eigene_signatur>
    <grund>Unterschrift</grund>
    <output_var>signiert</output_var>
  </config>
</task>

Sicherheit: P12 wird nur als echter Upload angenommen (is_uploaded_file), gegen das Passwort geprüft (openssl_pkcs12_read), in einer 0600-Tempdatei gehalten und nach dem Signieren gelöscht. Das Passwort wird nicht geloggt. Die P12/Passwort-Felder liegen sichtbar in der Kopfleiste, gehören per form="posForm" aber zum (multipart-)Formular; „Bestätigen" wird erst frei, wenn Position und Zertifikat+Passwort gesetzt sind.

Fallen / Hinweise

• Quelle außerhalb des Docroots (z. B. Bauakte-Datei aus upload_neu): der Task kopiert sie über AbstractTask::browserFile() selbst ins temp_dir, sonst könnte der Browser die PDF nicht laden. Das Original bleibt unangetastet.
• Stempelgröße: auto leitet die mm-Maße aus der Pixelgröße ab. Die bau-Vorlage rendert mit scale=2 → 4 px/pt. (Bis 07/2026 wurde mit 96 dpi gerechnet — die Stempel waren dadurch dreimal zu groß, breiter als eine A4-Seite.) Block-Stempel messen jetzt 84,7 × 22,9 mm.
• Die im Browser gemerkte Skalierung liegt unter wf_stempel_scale2:<art|bild> im localStorage.
• vorlage=bau wird lokal erzeugt (stempel_erzeugen()); es gibt keinen HTTP-Fallback mehr, damit echte Fehler (z. B. ungültige summe) sichtbar werden statt als „Vorlage nicht ladbar" zu erscheinen.