Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen der Seite angezeigt.

--- projekte:etermin:start [14.09.2026 15:24] – [Technische Dokumentation] hwehrs
+++ projekte:etermin:start [20.09.2026 22:18] (aktuell) – [Einleitung] hwehrs
@@ Zeile 20: / Zeile 20: @@
 wird ein neuer Interessent angelegt.
 </WRAP>
-----
 <WRAP tip round 80% justify>
@@ Zeile 34: / Zeile 32: @@
 **Teil 3 – Datenübergabe an PW**\\
 Wie wird geprüft, ob die Person bereits vorhanden ist, und was geschieht anschließend?
+</WRAP>
+<WRAP center 80%>
+<WRAP 80%>
+{{:projekte:etermin:teil-1-comic.png?direct|}}
+</WRAP>
 </WRAP>
@@ Zeile 66: / Zeile 70: @@
 <WRAP info round 80% justify>
-**Was bedeutet „Webhook“?**
+<wrap em>Was bedeutet „Webhook“?</wrap>
 Ein Webhook ist vereinfacht gesagt ein **digitaler Datenbote**. Sobald eine neue
@@ Zeile 294: / Zeile 298: @@
 <WRAP todo>\\
 <wrap em>Die einzelnen Scripte für Webhook und Datenanpassung folgen.</wrap>
+</WRAP>
+----
+====== Betrieb & Fehlersuche ======
+<WRAP tip round 80% justify>
+===== Was passiert, wenn etwas nicht funktioniert? =====
+Die Datenübertragung zwischen eTermin und Professional Works läuft im Normalbetrieb
+**vollständig automatisch**. Ein manueller Eingriff ist daher grundsätzlich nicht
+erforderlich.
+Trotzdem muss jederzeit nachvollziehbar bleiben, ob eine Buchung erfolgreich verarbeitet
+wurde oder an welcher Stelle die Verarbeitung abgebrochen ist.
+Deshalb werden die wesentlichen Verarbeitungsschritte und deren Ergebnis
+**protokolliert**. Tritt ein Fehler auf, darf daraus insbesondere kein unkontrollierter
+oder unvollständiger Datensatz in Professional Works entstehen.
+Je nach Art des Fehlers kann zusätzlich eine **Benachrichtigung an den Administrator**
+erfolgen.
+</WRAP>
+<mermaid>
+flowchart TD
+    A["📦 Neue Buchungsdaten"] --> B["⚙️ Automatische Verarbeitung"]
+    B --> C{"Verarbeitung<br/>erfolgreich?"}
+    C -->|"JA"| D["✅ Vorgang erfolgreich<br/>abgeschlossen"]
+    D --> E["📝 Ergebnis<br/>protokollieren"]
+    C -->|"NEIN"| F["🛑 Verarbeitung<br/>abbrechen"]
+    F --> G["📝 Fehler und Ursache<br/>protokollieren"]
+    G -.-> H["✉️ Optional:<br/>Administrator<br/>benachrichtigen"]
+</mermaid>
+<WRAP important round 80% justify>
+===== Grundsatz bei Fehlern =====
+**Ein Fehler darf nicht durch Raten „repariert“ werden.**
+Kann ein Datensatz nicht eindeutig oder sicher verarbeitet werden, wird die automatische
+Verarbeitung an der betreffenden Stelle beendet. Der Fehler wird protokolliert und kann
+anschließend gezielt geprüft werden.
+Insbesondere werden bei Fehlern **keine widersprüchlichen Angaben in Professional Works
+blind überschrieben** und keine technisch zweifelhaften Daten erzeugt, nur damit der
+Vorgang formal als erfolgreich abgeschlossen werden kann.
+Damit gilt auch im automatisierten Betrieb:
+<wrap em>Im Zweifel kontrolliert abbrechen und nachvollziehbar protokollieren statt falsche Daten zu erzeugen.</wrap>
+</WRAP>
+<WRAP info round 80% justify>
+===== Wo finde ich die technischen Informationen? =====
+Die konkreten Informationen für den Betrieb werden an dieser Stelle ergänzt, sobald
+die technische Umsetzung abgeschlossen ist. Dazu gehören insbesondere:
+  * Speicherort und Aufbau der Protokolle
+  * mögliche Fehlerzustände und deren Bedeutung
+  * Benachrichtigungen an den Administrator
+  * Prüfung des Betriebszustands
+  * Vorgehen bei fehlgeschlagenen Übertragungen
+  * Wiederholung bzw. erneute Verarbeitung eines Vorgangs
+Diese Angaben werden aus der **tatsächlich eingesetzten Implementierung** dokumentiert
+und nicht vorab angenommen.
+</WRAP>
+----
+====== Schnittstellen / API ======
+<WRAP tip round 80% justify>
+===== Über welche Schnittstellen kommunizieren die Systeme? =====
+Für die automatische Verarbeitung einer eTermin-Buchung werden zwei technisch
+unterschiedliche Schnittstellen und Kommunikationswege verwendet.
+<wrap em>eTermin → unsere Datenschnittstelle</wrap>\\
+eTermin stößt die Verarbeitung über einen **Webhook** an. Nach Abschluss einer
+Buchung sendet eTermin die vorgesehenen Buchungsdaten selbstständig an eine
+dafür bereitgestellte Adresse unserer Datenschnittstelle.
+Die Buchungsdaten werden dabei als **JSON-Datenblock** übertragen. Dieser enthält
+die von eTermin bereitgestellten Informationen zur Buchung und zur betreffenden
+Person.
+<wrap em>Unsere Datenschnittstelle ↔ Professional Works</wrap>\\
+Die weitere Kommunikation erfolgt über die **API von Professional Works**.
+Unsere Datenschnittstelle übernimmt hierbei die aktive Rolle und stellt gezielte
+HTTP-Anfragen an PW.
+Je nach benötigter Aktion werden insbesondere **GET-Anfragen** zum Abrufen bzw.
+Prüfen vorhandener Informationen und **POST-Anfragen** zur Übergabe neuer Daten
+bzw. zum Auslösen entsprechender Aktionen verwendet. Die Antworten von
+Professional Works werden anschließend von unserer Datenschnittstelle ausgewertet.
+<wrap em>Der Zwischenstopp auf unserer Datenschnittstelle ist deshalb technisch notwendig:</wrap>\\
+Der von eTermin gelieferte JSON-Datenblock kann nicht einfach unverändert an
+Professional Works weitergereicht werden. Die enthaltenen Daten müssen geprüft,
+den entsprechenden PW-Datenfeldern zugeordnet und bei Bedarf um technisch
+erforderliche Angaben ergänzt werden. Anschließend erzeugt unsere
+Datenschnittstelle daraus die jeweils benötigten HTTP-Anfragen an die
+Professional-Works-API.
+Unsere Datenschnittstelle übernimmt damit nicht nur den Transport, sondern die
+**Übersetzung und kontrollierte Vermittlung zwischen zwei unterschiedlichen
+Schnittstellen**.
+</WRAP>
+<mermaid>
+flowchart LR
+    ET["📅 eTermin<br/><br/>Buchung<br/>abgeschlossen"]
+    HOOK["⚙️ Unsere Datenschnittstelle<br/><br/>Webhook<br/>empfangen"]
+    PROC["🔎 Verarbeitung<br/><br/>prüfen<br/>zuordnen<br/>aufbereiten"]
+    PW["🗄️ Professional Works<br/><br/>API"]
+    ET -->|"Webhook<br/>Buchungsdaten"| HOOK
+    HOOK --> PROC
+    PROC -->|"API-Anfrage"| PW
+    PW -->|"API-Antwort"| PROC
+</mermaid>
+<WRAP info round 80% justify>
+===== Webhook und API – der entscheidende Unterschied =====
+**Webhook**\\
+Beim Webhook beginnt das sendende System die Kommunikation. eTermin meldet
+unserer Datenschnittstelle sinngemäß:
+//„Es ist etwas passiert – hier sind die Daten dazu.“//
+Unsere Datenschnittstelle muss eTermin daher nicht ständig nach neuen Buchungen
+fragen.
+**API**\\
+Bei der Kommunikation mit Professional Works beginnt dagegen unsere
+Datenschnittstelle die jeweilige Aktion. Sie fragt beispielsweise sinngemäß:
+//„Existiert diese Person bereits?“//\\
+//„Lege diesen Interessenten an.“//\\
+//„Ergänze diese zulässigen Angaben.“//
+Professional Works verarbeitet die Anfrage und liefert eine Antwort zurück.
+<wrap em>Webhook = eTermin meldet ein Ereignis. API = unsere Datenschnittstelle führt gezielte Aktionen mit Professional Works aus.</wrap>
+</WRAP>
+<WRAP important round 80% justify>
+===== Technische Referenz =====
+Die konkreten technischen Angaben werden mit der tatsächlich eingesetzten
+Implementierung dokumentiert. Dazu gehören insbesondere:
+  * verwendete URLs bzw. Endpunkte
+  * HTTP-Methoden und erwartete Statuscodes
+  * Authentifizierung
+  * übertragene Datenfelder und Datenformate
+  * Zuordnung eTermin-Felder → interne Verarbeitung → PW-Felder
+  * Pflichtfelder und verwendete technische Standardwerte
+  * Doublettenprüfung
+  * Fehlerantworten und deren Behandlung
+  * Versionsstand der verwendeten Schnittstellen
+Diese Angaben werden **nicht aus Annahmen vorab erzeugt**, sondern aus den
+tatsächlich eingesetzten Webhook- und API-Implementierungen übernommen.
 </WRAP>
 ----