Fremdformulare — Feldmapping & Prefill (AD-010 / MED-OP-FORM-5)

Kernaussage (BLUF). Fremde, ausfüllbare PDF-Formulare (Bank-/Partner-Formulare wie die apoBank-EDÜ) tragen opake Feldnamen (fill_6, fill_7 …) — ihre Bedeutung kennt nur ein Mensch, der das Formular ansieht. Medidentas liest ihre AcroForm-Felder aus, lässt je Feld ein kanonisches Weltmodell-Attribut (G-8) zuordnen und befüllt das Formular daraus aus den Stammdaten vor. Weg A (Hybrid): die differenzierende Eigenleistung ist ausschließlich das Mapping — das Füllen macht pdf-lib, das Signieren macht DocuSign (G-1: integrate-before-build). Entscheidung MED-D-235.

Zielgruppe: IT-Dev/Architektur (primär), Business/Management (Konzept). Verwandt: Weltmodell-Data-Dictionary.md (G-8) · Unterschriften.md (DocuSign/eIDAS) · Dokumentenverwaltung-NextCloud.md (Ablage R2) · Design-Entscheidungen-Akte.md (AD-010).

---

1. Das Problem (die tragenden Gründe)

• Kunden müssen Partner-Formulare ausfüllen (Bank-Einzugsermächtigung/Datenübermittlung, Vollmachten, Anträge). Diese kommen als fertiges, ausfüllbares PDF vom Partner — wir bauen sie nicht nach.
• Ihre Feldnamen sind bedeutungslos. Ein PDF-Editor benennt Felder automatisch fill_6, fill_7 … — aus dem Namen ist nicht ablesbar, was hineingehört (Name? PLZ? IBAN?). Nur ein Mensch, der das Formular ansieht, weiß es.
• Wir haben die Daten schon (Name, Anschrift, IBAN, Geburtsdatum …) — sie doppelt abzutippen ist fehleranfällig und widerspricht True North (#3: lückenlos, korrekt).

2. Die Entscheidung: Weg A (Hybrid) — nur das Mapping ist Eigenbau (G-1)

	Bauen	G-1	Ergebnis
A Hybrid (gewählt)	nur Feld-Mapping + Prefill/Write-back	✅ konform	strukturierte Felder rein & raus; Füllen via pdf-lib, Signieren via DocuSign
B Voller Eigenbau	Feld-Editor + Renderer + Fill, provider-unabhängig	⚠️ Abweichung	max. Kontrolle, aber Signatur/Placement nachgebaut
C nur Konzept	Design-Doc, Bau später	—	kein Nutzen jetzt

Warum A: Der PDF-/Signatur-Stack ist ein gelöstes Standardproblem (pdf-lib füllt AcroForms; DocuSign signiert eIDAS-konform). Der einzige Teil ohne Standard-Werkzeug ist die fachliche Abbildung „welches Fremdformular-Feld ist welches unserer Stammdaten" — das ist die Eigenleistung, und sie ist zugleich G-8-Arbeit (eine kanonische Definition je Attribut, überall gleich).

3. Ablauf (Mermaid)

4. Bausteine (Slice 1 — gebaut, MED-D-235)

Baustein	Datei	Rolle
PDF-Adapter	server/src/pdf/pdf-formular.ts	leseFormularfelder(bytes) (Name·Art·Seite·Optionen) · fuelleFormular(bytes, werte) — kein Flatten (Formular bleibt ausfüllbar/signierbar), je Feld defensiv
Weltmodell-Mapping	server/src/domain/fremdformular.ts	Katalog WELTMODELL_ATTRIBUTE (G-8) · bereinigeMapping · bauePrefillFelder/-Werte — rein, kein I/O
Dienst	server/src/api/fremdformular-service.ts	ansicht · mappingSetzen · vorbefuellen — bindet Adapter+Mapping an Ablage (R2/NextCloud-Seam) + Audit
Persistenz	dokument.fremdformular_mapping (JSON, Migration v46)	die menschliche Zuordnung (Feld → Attribut). Die extrahierten Felder werden nicht persistiert (abgeleitet aus dem PDF, G-2)
Routen	/api/dokumente/:docId/fremdformular (GET · PUT /mapping · POST /vorbefuellen)	eigener Sichtbarkeits-/RBAC-Guard je Handler (PII), Fremd-Mandant → 404
Feld-Editor (UI)	client/src/app/akte-feld-editor.component.ts	Overlay im Unterschriften-Assistenten: Felder ⇄ Attribut-Dropdown + Prefill-Vorschau; löst den früheren Platzhalter-Toast ab

Der Weltmodell-Attribut-Katalog (G-8)

Genau die Felder mit eindeutiger, verlustfreier Heimat in unseren Stammdaten sind wählbar (keine Freitext-Sammelfelder): person.* (anzeigename/nachname/vorname/titel/geburtsdatum) · kontakt.* (email/telefon) · anschrift.* (strasse/plz/ort strukturiert, plus abgeleitete anschrift.komplett) · bank.* (iban/inhaber — das gewählte Bankkonto vor der Alt-IBAN, MED-D-195) · praxis.* (name/strasse/plz/ort/iban). Eine Definition je Attribut — dieselbe wird im Editor angeboten, im Prefill gelesen und (Slice 2) beim Rücklauf zum Ziel.

5. Compliance & Datenschutz

• G-5/G-6 (Datensparsamkeit): kein neues PII persistiert — das Mapping trägt nur Attribut-Schlüssel (person.nachname), keine Werte. Audit-Events (fremdformular.gemappt/.vorbefuellt) protokollieren nur Feldanzahlen, nie Feldnamen/Attribute/Werte.
• G-4 (verlustfrei/auditierbar): das Vorbefüllen legt die gefüllte Fassung zurück in die Ablage — R2/NextCloud hält die Vorversion (blanko), nichts wird überschrieben-verloren; jeder Schritt ist auditiert.
• Ablage-Scope: die Routen lesen/schreiben nur Pfade im Mandanten-Ordner des Dokuments (dieselbe Absicherung wie die Datei-Download-Route) — die geteilte Ablage dient nie als generisches Lese-/Schreib-Primitiv.
• eIDAS (OP-SIGN-1): das Signieren des vorbefüllten Formulars läuft über DocuSign; das Niveau (SES/AES/QES) je Dokumenttyp bleibt die begründete Provider-Entscheidung — Fremdformulare ändern daran nichts.

6. Fahrplan

Slice	Inhalt	Status
1	AcroForm-Felder auslesen · Weltmodell-Mapping (persistiert) · Prefill aus Stammdaten · Feld-Editor-UI	✅ MED-D-235 (0.105.0)
2	Rücklauf (AD-009): die vom Kunden ausgefüllten/korrigierten Werte über DocuSign form_data zurücklesen → Review-and-apply (Diff aktuell↔neu, „Übernehmen" je Feld) auf die bestehende Übernahme-Maschine (baueVorschlaege/bauePatch); on-demand, nichts persistiert bis zur Übernahme (G-6), dann versioniert (Quelle formular, G-4). Rückschreib-Whitelist nur Person/Kontakt/Anschrift (ATTRIBUT_ZU_STAMMZIEL).	✅ MED-D-247 (0.112.0, live gegen DocuSign Demo verifiziert)
3	Einbindung neuer Fremd-Formulare = DocuSign-Templates/Tabs (Weg B) — s. §8. Vorlagen-Katalog (FremdformularVorlage, v47) + anfordernAusTemplate (compositeTemplates) + Prefill (baueTabWerte) + starten; Verwaltung-Registrierung + beim Mandanten „vorbefüllt starten"; Rücklauf via Identitäts-Mapping (AD-009).	✅ MED-D-250 (0.113.0, live gegen DocuSign Demo verifiziert: Template → Envelope → form_data-Prefill)

7. Bezug

• Leitprinzipien: CLAUDE.md G-1 (integrate-before-build) · G-8 (Weltmodell) · G-5/G-6 (PII).
• Entscheidungen: docs/betrieb/Decision-Log.md MED-D-235 (Weg A / Slice 1) · MED-D-247 (Rücklauf / Slice 2) · MED-D-248 (Einbindung neuer Formulare = Weg B, §8). Offene Punkte: MED-OP-FORM-5 (HANDOFF.md §4) · MED-OP-FORM-6 (Eigen-Formulare ebenfalls als DocuSign-Templates — Katalog an einer Stelle; bewusst zurückgestellt). Kundenklärung: MED-KB-11 (welche Formulare · Template-Pflege · Ankertext).
• Muster-Erbe: Rücklauf folgt dem verbindlichen Formular-Rückläufer-Regelkreis (CLAUDE.md, MED-D-89/MED-OP-FORM-4).

8. Einbindung neuer Fremd-Formulare — Weg B (DocuSign-Templates/Tabs), MED-D-248 · gebaut MED-D-250

Entscheidung (MED-D-248) · umgesetzt (MED-D-250, 0.113.0, live verifiziert). Neue Fremd-Formulare binden wir über DocuSign-Templates mit Tabs ein — nicht über einen Eigenbau-Feld-Editor. Katalog-Entität FremdformularVorlage (v47), Provider anfordernAusTemplate (compositeTemplates), Prefill baueTabWerte, Dienst FremdformularVorlageService.starten; Registrierung in der Verwaltung, „vorbefüllt starten" beim Mandanten. Das deckt auch flache PDFs (Druck/Scan ohne AcroForm-Felder), nutzt ein Werkzeug für Füllen + Signieren + Rücklesen und hält G-1 (integrate-before-build). Der heutige AcroForm-Weg A bleibt der Schnellpfad, wenn ein PDF ohnehin Felder trägt.

Warum B. Bankformulare kommen oft flach (kein AcroForm) — pdf-lib hat dann keine Felder zum Füllen. Ein DocuSign-Template legt die Felder als Tabs über das PDF (per Ankertext/„AnchorString" oder Koordinate); damit füllt und signiert dasselbe Werkzeug, und der Wert-Rücklauf (form_data, Slice 2) greift unverändert. Ein Eigenbau-Editor (Weg C) würde genau das nachbauen — bewusst nicht.

Einrichtung je Formular (einmalig).

1. PDF als DocuSign-Template anlegen; Tabs im DocuSign-Template-Editor platzieren (Ankertext bevorzugt — übersteht kleine Layout-Änderungen des Partners —, sonst Koordinate). Signaturfeld = signHere-Tab.
2. Konvention: tabLabel = Weltmodell-Attribut-Schlüssel (anschrift.plz, kontakt.email …). Damit ist das Mapping die Identität — Prefill und Rücklauf laufen ohne separate Feldnamen-Tabelle (anders als der opake AcroForm-Feldname bei Weg A).
3. In Medidentas nur eine Referenz speichern: {name, templateId, attribute[], eIDAS-Niveau} — ein kleiner Vorlagen-Katalog, kein PDF-Blob (G-1: das Template lebt bei DocuSign; G-6: nur Attribut-Schlüssel).

Laufzeit je Mandant.

1. Envelope aus dem Template erzeugen (compositeTemplates/templateRoles): Unterzeichner = Mandant bzw. zeichnungsberechtigte Person (AD-006); Tab-Werte vorbefüllt aus den Stammdaten (Attribut → tabLabel → Wert). DocuSign rendert das gefüllte PDF — kein pdf-lib, auch auf flachen PDFs.
2. Signieren: Remote-E-Mail oder embedded In-Person (beide gebaut, MED-D-236).
3. Rücklauf: form_data liefert die Werte je tabLabel = Attribut-Schlüssel → die AD-009-Review-and-apply (MED-D-247) läuft unverändert (Mapping = Identität).

Abgrenzung / offene Punkte.

• Weg A bleibt als Schnellpfad für PDFs mit AcroForm-Feldern (kein Template nötig).
• Prefill sendet nur Text-Tabs (offener Punkt, MED-OP-FORM-7): baueTabWerte → anfordernAusTemplate befüllt derzeit ausschließlich textTabs; ein gemappter Date-/Checkbox-/anderer Tab-Typ bliebe daher beim Vorbefüllen leer. (Der Rücklauf ist davon nicht betroffen — formularRuecklauf liest form_data generisch je name/value, also alle Tab-Typen.) Deshalb im Runbook (§9) alle vorbefüllten Datenfelder auf Text-Tabs legen (auch Geburtsdatum). Optional später: das Prefill auf weitere Tab-Typen (Date/Checkbox) ausdehnen — bewusst zurückgestellt, bis ein echtes Formular es erzwingt.
• MED-OP-FORM-6 (teilweise gebaut): Hausformular-Auto-Routing ist gebaut (MED-D-257) — eine Weg-B-Vorlage lässt sich optional an einen Hausformular-Dokumenttyp binden (FremdformularVorlage.dokumenttyp); beim Versenden eines Hausformulars ohne Datei startet dann automatisch die ausfüllbare DocuSign-Fassung (Kunde füllt selbst → AD-009-Rücklauf) statt der flachen PDF. Weiter offen: die R12-Eigen-Formulare vollständig als DocuSign-Templates bereitstellen, damit Eigen- und Fremd-Formulare an einer Stelle liegen (ein Vorlagen-Katalog, ein Füll-/Signier-/ Rücklauf-Pfad) — bewusst zurückgestellt.
• Korrektur-Schleife: der verbindliche Formular-Rücklauf-Regelkreis (MED-D-89/MED-OP-FORM-4 — approve/deny je Feld · Mail-Feedback · Korrektur über denselben Link · gesperrte akzeptierte Felder · append-only Audit) gilt auch hier; die AD-009-Berater-Prüfung ist der Übernahme-Schritt, kein Ersatz dafür. Offen ist nur die Anwendung auf signierte Formulare (ein signierter Envelope öffnet nicht „per Link") → MED-KB-11 (5).
• Kundenklärung MED-KB-11: welche Fremd-Formulare konkret · wer pflegt die DocuSign-Templates (Editor-Zugang) · Ankertext-Verlässlichkeit je Formular · eIDAS-Niveau je Formular (bezieht MED-KB-5/MED-KB-8 ein).

9. Runbook — ein neues Fremdformular-Template anlegen (Klick-für-Klick, MED-D-264)

Kernaussage (BLUF). Ein Partner-/Bankformular wird einmalig als DocuSign-Template angelegt und in Medidentas registriert. Der einzige fachliche Schritt ist: jedem ausfüllbaren Feld den passenden Weltmodell-Attribut-Schlüssel als tabLabel ("Data Label") geben — dieser Schlüssel ist zugleich die Vorbefüll- und die Rücklauf-Zuordnung (Mapping = Identität, §8). Zielgruppe: Anwender/Admin (Verwaltung).

9.1 Teil A — in DocuSign (einmalig je Formular)

1. Templates → New → Create Template; das flache Partner-PDF hochladen (kein AcroForm nötig — DocuSign legt die Felder als Tabs darüber).
2. Empfänger/Rolle anlegen: Rollenname mandant (Platzhalter — Medidentas setzt E-Mail/Name zur Laufzeit).
3. Tabs platzieren: Text-Tabs auf alle vorbefüllten Datenfelder — auch auf Datumsfelder wie Geburtsdatum (person.geburtsdatum): der Prefill befüllt aktuell ausschließlich Text-Tabs (baueTabWerte → textTabs, docusign.ts), ein DocuSign-Date-Tab bliebe also leer. Den Date-Tab-Typ nur für Daten nehmen, die der Unterzeichner beim Signieren selbst setzt (z. B. Unterschriftsdatum) — nicht für vorbefüllte Stammdaten. Ein Signature-Tab (signHere) auf die Unterschrift. Ankertext bevorzugen (übersteht kleine Layout-Änderungen des Partners) statt fester Koordinate.
4. Je Text-Tab das „Data Label" (= tabLabel) exakt auf einen Weltmodell-Schlüssel setzen (§9.3). Felder ohne Stammdaten-Bezug (Sondertext, Ankreuzfelder) bleiben ohne Data Label — der Kunde füllt sie selbst.
5. Template speichern, die Template-ID (GUID) kopieren.

9.2 Teil B — in Medidentas registrieren (Verwaltung, Admin)

1. Verwaltung → „Meine Rolle" → Admin (schaltet die Admin-Sektion frei, MED-D-260).
2. Verwaltung → „Fremd-Formular-Vorlagen": Name vergeben · Template aus dem Dropdown wählen (⟳-Refresh, falls es fehlt; oder GUID ins Freitextfeld) — die App zeigt die echten Felder mit ✓ erkannt vs. ⚠ unbekannt (MED-D-262). Alle Stammdaten-Felder sollten ✓ sein; ein ⚠ an einem Stammdaten-Feld heißt: tabLabel vertippt.
3. eIDAS-Niveau wählen (SES/AES/QES je Rechtswirkung; Bankvollmachten typ. AES — MED-KB-5/11). Optional an einen Hausformular-Dokumenttyp binden → Auto-Routing beim Versenden (MED-D-257). Registrieren.

9.3 tabLabel-Referenz (kanonisch, Quelle server/src/domain/fremdformular.ts → WELTMODELL_ATTRIBUTE)

Bedeutung	tabLabel (exakt)		Bedeutung	tabLabel (exakt)
Name (vollständig)	person.anzeigename		Straße & Hausnr.	anschrift.strasse
Nachname	person.nachname		PLZ	anschrift.plz
Vorname	person.vorname		Ort	anschrift.ort
Titel	person.titel		Anschrift (einzeilig)	anschrift.komplett
Geburtsdatum	person.geburtsdatum		IBAN	bank.iban
E-Mail	kontakt.email		Kontoinhaber	bank.inhaber
Telefon	kontakt.telefon		Praxis / Gesellschaft	praxis.name
Praxis · Straße	praxis.strasse		Praxis · PLZ / Ort / IBAN	praxis.plz · praxis.ort · praxis.iban

Genau schreiben (kleingeschrieben, mit Punkt). Diese Liste ist die Whitelist — ein unbekannter tabLabel wird als ⚠ geführt (kein Prefill/Rücklauf), nicht als Fehler.

9.4 Teil C — testen (je Mandant)

1. Bei einem Mandanten das Formular „vorbefüllt starten" → Envelope aus dem Template mit vorbefüllten Stammdaten.
2. Signieren: Remote (E-Mail) oder Vor Ort/In-Person (embedded, ohne Mailversand, MED-D-236) — Letzteres ist der noch nicht live durchgeklickte Pfad (OP-SIGN-1), also ein guter erster Härtetest.
3. Nach Abschluss läuft der Rücklauf (form_data → Feld-Sichtung/AD-009 → Stammdaten, §8/MED-D-247).