Readme: Explain configuration

README.md

@@ -2,8 +2,38 @@
 
 Senden und Empfangen von Postfach-Nachrichten über die OSI-Postfach-Facade 2.0 (OPF).
 
+Das Maven-Artefakt `osiv2-postach` kann in ein Spring-Boot eingebunden werden.
+Die Spring-Bean `osiPostfachRemoteService` mit dem Interface
+`PostfachRemoteService` kann mit `ozgcloud.osiv2.enabled: true` aktiviert werden.
+
+## Konfiguration
+Um auf die Postfach-Facade zugreifen zu können muss der Client sich beim Servicekonto anmelden.
+Hierzu wird `ozgcloud.osiv2.auth` konfiguriert, wie bspw. hier für Stage-Schleswig-Holstein:
+```yaml
+client-id: 'OZG-Kopfstelle-SH'
+client-secret: 'changeme'
+scope: default, access_urn:dataport:osi:sh:stage:ozgkopfstelle
+token-uri: 'https://idp.serviceportal-stage.schleswig-holstein.de/webidp2/connect/token'
+resource: 'urn:dataport:osi:postfach:rz2:stage:sh'
+```
+Für die Postfach-Facade muss zudem die URL, der Tenant, und der SAML-Name-Identifier konfiguriert werden.
+Beim Nachschlagen des Postfachs der Antragsteller*in wird ein Postfach mit übereinstimmenden Tenant präferiert.
+Zudem werden Tenant und SAML-Name-Identifier beim Upload von Anhängen angegeben.
+
+Hierzu wird `ozgcloud.osiv2.api` konfiguriert:
+```yaml
+url: 'https://api-gateway-stage.dataport.de:443/api/osi_postfach/1.0.0'
+tenant: 'SH'
+name-identifier: 'ozgkopfstelle'
+```
+<small>(Der Wert von `name-identifier` wird momentan nicht von der Postfach-Facade geprüft.)</small>
+
 ## Senden einer Postfach-Nachricht
+Der Aufruf `sendMessage(PostfachNachricht)` sendet eine Nachricht an die Antragsteller*in. Jede Nachricht ist stets in Bezug zu einem Vorgang.
 
+1. Mit dem SAML-Name-Identifier der Antragsteller*in wird ein Postfach nachgeschlagen, welches die Nachricht empfangen soll.
+2. Vor dem Senden der Nachricht werden alle Anhänge in die Quarantäne hochgeladen und auf Viren geprüft.
+3. Nach dem erfolgreichen Hochladen der Anhänge wird die Nachricht an das Postfach gesendet.
 ```mermaid
 %% Senden einer Nachricht
   sequenceDiagram
@@ -40,7 +70,6 @@ Senden und Empfangen von Postfach-Nachrichten über die OSI-Postfach-Facade 2.0
       C-->>B: 
       deactivate C
     end
-    Note left of B: (3) Warten auf Prüfung der hochgeladenen Anhänge
     loop Regelmäßiges Polling bis alle Anhänge geprüft sind
       loop Für jeden Anhang
         B->>C: GET /Quarantine/v1/Upload/{guid}
@@ -49,7 +78,7 @@ Senden und Empfangen von Postfach-Nachrichten über die OSI-Postfach-Facade 2.0
         deactivate C
       end
     end
-    Note left of B: (4) Nachricht senden
+    Note left of B: (3) Nachricht senden
     B->>C: POST /MessageExchange/v1/Send/{mailboxId}
     activate C
     C-->>B: 
@@ -60,9 +89,13 @@ Senden und Empfangen von Postfach-Nachrichten über die OSI-Postfach-Facade 2.0
 ```
 
 ## Empfangen von Postfach-Nachrichten
+Der Aufruf `receiveMessages()` holt alle Nachrichten, die an das OZG-Cloud-Postfach gerichtet sind ab.
 
+1. Es wird eine Liste an Nachrichten-Kennungen abgerufen.
+2. Für jede Nachricht wird die Nachricht abgerufen und die Anhänge heruntergeladen.
+3. Ein Stream an Nachrichten wird zurückgegeben. Anhand der Vorgangs-Kennung lässt sich jede Nachricht stets einem Vorgang zugordnen.
 ```mermaid
-%% Empfangen einer Nachricht
+%% Empfangen von Nachrichten
   sequenceDiagram
     participant N as nachrichten-manager
     participant A as file-manager
@@ -92,8 +125,9 @@ Senden und Empfangen von Postfach-Nachrichten über die OSI-Postfach-Facade 2.0
         C-->>B: 
         deactivate C
       end
+      Note left of B: (3) Bereitstellung der Postfach-Nachricht
+      B-->>N: {Postfach-Nachricht als Stream-Element}
     end
-    B-->>N: {Stream an Postfach-Nachrichten}
     deactivate B
     deactivate N
 ```
@@ -132,7 +166,7 @@ Der Resource-Server liest die Resource-URI aus dem `aud`-Claim (siehe [RFC 9068,
 curl -v --output auth_response.json \
      -H "Content-Type: application/x-www-form-urlencoded" \
      --data-urlencode "grant_type=client_credentials" \
-     --data-urlencode "client_id=OZG-Kopfstelle" \
+     --data-urlencode "client_id=OZG-Kopfstelle-SH" \
      --data-urlencode "client_secret=${SH_STAGE_CLIENT_SECRET}" \
      --data-urlencode "scope=default access_urn:dataport:osi:sh:stage:ozgkopfstelle" \
      --data-urlencode "resource=urn:dataport:osi:postfach:rz2:stage:sh" \