Merge branch 'main' into johannes/duke-nukem

Author: Johennes

README.adoc

@@ -13,43 +13,32 @@ ifndef::env-github[:source-style: source]
 
 image::meta/gematik.png[logo,width=250,height=47,role=right]
 
-= TI Messenger Documentation v1.1.1
-
+= TI-Messenger
 
 image:https://github.com/gematik/api-ti-messenger/actions/workflows/lint.yml/badge.svg[link="https://github.com/gematik/api-ti-messenger/actions/workflows/lint.yml"]
 image:https://github.com/gematik/api-ti-messenger/actions/workflows/generate-images.yml/badge.svg[link="https://github.com/gematik/api-ti-messenger/actions/workflows/generate-images.yml"]
 
-image:https://img.shields.io/badge/Release%20Notes-v1.1.1-red?style=plastic&logo=github&logoColor=red[link="ReleaseNotes.md"] +
-image:https://img.shields.io/badge/I_TiMessengerContactManagement-v1.0.1-blue?style=plastic&logo=github&logoColor=blue[link=/src/openapi/TiMessengerContactManagement.yaml"] +
-image:https://img.shields.io/badge/TiMessengerTestDriver-v0.9.2-purple?style=plastic&logo=github&logoColor=purple[link="/src/openapi/TiMessengerTestTreiber.yaml"]
-image:https://img.shields.io/badge/TiMessengerTestSuite-v0.9.2-purple?style=plastic&logo=github&logoColor=purple[link="https://github.com/gematik/TI-Messenger-Testsuite"] +
-image:https://img.shields.io/badge/TI‐Messenger‐Dienst-v1.1.1-green?style=plastic&logo=github&logoColor=green[link="https://fachportal.gematik.de/fachportal-import/files/gemSpec_TI-Messenger-Dienst_V1.1.1.pdf"]
-image:https://img.shields.io/badge/TI‐Messenger‐FD-v1.1.1-green?style=plastic&logo=github&logoColor=green[link="https://fachportal.gematik.de/fachportal-import/files/gemSpec_TI-Messenger-FD_V1.1.1.pdf"]
-image:https://img.shields.io/badge/TI‐Messenger‐Client-v1.1.1-green?style=plastic&logo=github&logoColor=green[link="https://fachportal.gematik.de/fachportal-import/files/gemSpec_TI-Messenger-Client_V1.1.1.pdf"] +
-image:https://img.shields.io/badge/Matrix_Client_Server_API-v1.3-yellow?style=plastic&logo=github&logoColor=yellow[link="https://spec.matrix.org/v1.3/client-server-api/"] 
-image:https://img.shields.io/badge/Matrix_Server_Server_API-v1.3-yellow?style=plastic&logo=github&logoColor=yellow[link="https://spec.matrix.org/v1.3/server-server-api/"] 
-image:https://img.shields.io/badge/Matrix_Push_Gateway_API-v1.3-yellow?style=plastic&logo=github&logoColor=yellow[link="https://spec.matrix.org/v1.3/push-gateway-api/"] 
+image:https://img.shields.io/badge/Release%20Notes-tim‐pro‐1.0.0-red?style=plastic&logo=github&logoColor=red[link="ReleaseNotes.md"] +
+image:https://img.shields.io/badge/TI‐Messenger‐Basis-latest-green?style=plastic&logo=github&logoColor=green[link="https://gemspec.gematik.de/docs/gemSpec/gemSpec_TI-M_Basis/latest/"]
+image:https://img.shields.io/badge/TI‐Messenger‐ePA-latest-green?style=plastic&logo=github&logoColor=green[link="https://gemspec.gematik.de/docs/gemSpec/gemSpec_TI-M_ePA/latest/"]
+image:https://img.shields.io/badge/TI‐Messenger‐Pro-latest-green?style=plastic&logo=github&logoColor=green[link="https://gemspec.gematik.de/docs/gemSpec/gemSpec_TI-M_Pro/latest/"] +
+image:https://img.shields.io/badge/Matrix_Client_Server_API-v1.11-yellow?style=plastic&logo=github&logoColor=yellow[link="https://spec.matrix.org/v1.11/client-server-api/"]
+image:https://img.shields.io/badge/Matrix_Server_Server_API-v1.11-yellow?style=plastic&logo=github&logoColor=yellow[link="https://spec.matrix.org/v1.11/server-server-api/"]
+image:https://img.shields.io/badge/Matrix_Push_Gateway_API-v1.11-yellow?style=plastic&logo=github&logoColor=yellow[link="https://spec.matrix.org/v1.11/push-gateway-api/"]
 
 == Überblick
-Die folgende Dokumentation ergänzt die Spezifikation *TI-Messenger-Dienst* v1.1.1 gemäß *[gemSpec_TI-Messenger-Dienst]*. An dieser Stelle werden insbesondere die in der Spezifikation genannten Komponenten der Lösung sowie deren Schnittstellen weiter dargestellt und erläutert, um Hersteller und Anbieter eines *TI-Messenger-Dienstes* bestmöglich zu unterstützen. Der Funktionsumfang des *TI-Messenger-Dienst* v1.1.1 beinhaltet: +
-
-* Instant-Messaging zwischen Leistungserbringern und Leistungserbringerinstitutionen und
-* Instant-Messaging direkt zwischen Leistungserbringern.
-
-// 💡 _Hinweis: In der Spezifikationsversion v1.1.1 können keine Versicherten an dem *TI-Messenger-Dienst* teilnehmen_.
-
-IMPORTANT: Die Dokumentation ergänzt die Spezifikation gemäß link:https://fachportal.gematik.de/fachportal-import/files/gemSpec_TI-Messenger-Dienst_V1.1.1.pdf[[gemSpec_TI-Messenger-Dienst]], die als Grundlage für das Verständnis vorrausgesetzt wird. 
+Die folgende Dokumentation ergänzt die Spezifikationen *TI-Messenger ePA* und *TI-Messenger Pro*. An dieser Stelle werden insbesondere die in der Spezifikation genannten Komponenten der Lösung sowie deren Schnittstellen weiter dargestellt und erläutert, um Hersteller und Anbieter bestmöglich zu unterstützen.
 
 == Branches
 Für die Dokumentation des *TI-Messenger-Dienstes* werden in GitHub die folgenden Branches verwendet:
 
-- `main`: enthält die Dokumentation für das aktuell veröffentlichte Release gemäß *[gemSpec_TI-Messenger-Dienst]*,
+- `main`: enthält die Dokumentation für das aktuell veröffentlichte Release
 - `develop`: enthält die Dokumentation der in Entwicklung befindlichen Features, die noch nicht released sind, 
 - `hotfix`: enthält die Dokumentation kurzfristig notwendiger Änderungen am aktuellen Release, 
 - `feature/*`: enthält eine Vorschau, Vorbereitungen und Diskussion eines neuen Themas, welches noch nicht in der Entwicklung ist. Die Inhalte können unvollständig sein und sich bis zur Fertigstellung noch ändern.
 
 == Systemübersicht
-Die folgende Abbildung gibt einen Überblick über die Systemarchitektur des *TI-Messenger-Dienst* v1.1.1 insbesondere auf die Schnittstellen zwischen den Komponenten, die in den folgenden Kapiteln weiter betrachtet werden. 
+Die folgende Abbildung gibt einen Überblick über die Systemarchitektur des TI-Messengers insbesondere auf die Schnittstellen zwischen den Komponenten, die in den folgenden Kapiteln weiter betrachtet werden.
 
 image::System_overview.png[width="100%"]
 
@@ -116,22 +105,8 @@ TI-Messenger Dokumentation
 └── link:ReleaseNotes.md[ReleaseNotes.md]
 ----
 
-== Quellen
-Die nachfolgende Tabelle enthält die in der vorliegenden Online Dokumentation referenzierten Dokumente der gematik. 
-
-|===
-|[Quelle] |Herausgeber: Titel
-
-|link:https://fachportal.gematik.de/fachportal-import/files/gemSpec_TI-Messenger-Dienst_V1.1.1.pdf[gemSpec_TI-Messenger-Dienst_v1.1.1] |gematik: Spezifikation TI-Messenger-Dienst
-|link:https://fachportal.gematik.de/fachportal-import/files/gemSpec_TI-Messenger-FD_V1.1.1.pdf[gemSpec_TI-Messenger-FD_v1.1.1] |gematik: Spezifikation TI-Messenger-Fachdienst
-|link:https://fachportal.gematik.de/fachportal-import/files/gemSpec_TI-Messenger-Client_V1.1.1.pdf[gemSpec_TI-Messenger-Client_v1.1.1] |gematik: Spezifikation TI-Messenger-Client
-|link:https://gemspec.gematik.de/docs/gemSpec/gemSpec_VZD_FHIR_Directory/gemSpec_VZD_FHIR_Directory_V1.3.0[gemSpec_VZD_FHIR_Directory_v1.3.0] |gematik: Spezifikation Verzeichnisdienst FHIR-Directory
-|link:https://fachportal.gematik.de/hersteller-anbieter/komponenten-dienste/identity-provider-idp[zentraler IDP_Dienst] |gematik: zentraler IDP-Dienst der gematik
-|link:https://fachportal.gematik.de/hersteller-anbieter/komponenten-dienste/authenticator[Authenticator] |gematik: Authenticator der gematik
-|===
-
 == 💡 Onboarding
-Hersteller und Anbieter eines *TI-Messenger-Dienstes* können das von der gematik im https://fachportal.gematik.de/anwendungen/ti-messenger[Fachportal] bereitgestellte Welcome Package zum Onboarding nutzen. Dieses Welcome Package ist als "Schritt-für-Schritt"-Anleitung gedacht, um Hersteller und Anbieter beim Onboarding des *TI-Messenger-Dienstes* zu unterstützen.
+Hersteller und Anbieter eines TI-Messengers können das von der gematik im https://fachportal.gematik.de/anwendungen/ti-messenger[Fachportal] bereitgestellte Welcome Package zum Onboarding nutzen. Dieses Welcome Package ist als "Schritt-für-Schritt"-Anleitung gedacht, um Hersteller und Anbieter beim Onboarding des *TI-Messenger-Dienstes* zu unterstützen.
 
 == Weiterführende Seiten
 *Produkttypen* +

docs/Client/Client.adoc

@@ -26,8 +26,6 @@ Im Kontext des *TI-Messenger-Dienstes* wird zwischen den folgenden Ausprägungen
 
 Beide Arten von Clients basieren auf dem offenen Kommunikationsprotokoll Matrix und werden auf dem Endgerät eines Akteurs verwendet. In der folgenden Dokumentation werden die zwei Ausprägungen der Clients beschrieben.
 
-IMPORTANT: Die Seite ergänzt die Spezifikation gemäß link:https://fachportal.gematik.de/fachportal-import/files/gemSpec_TI-Messenger-Client_V1.1.1.pdf[[gemSpec_TI-Messenger-Client]], die als Grundlage für das Verständnis vorrausgesetzt wird. 
-
 == TI-Messenger-Client für Akteure
 Der *TI-Messenger-Client* für Akteure unterstützt die meisten aller, durch die Matrix-Spezifikation festgelegten Funktionalitäten eines Matrix-Messengers und weitere durch die gematik definierten Vorgaben. Die Funktionalität des *TI-Messenger-Clients* für Akteure kann in drei abstrakte Module unterteilt werden. In der folgenden Abbildung wird dies verdeutlicht.
 

docs/Fachdienst/Fachdienst.adoc

@@ -19,8 +19,6 @@ toc::[]
 == Überblick
 Die folgende Seite gibt Implementierungshinweise für die Entwicklung eines eigenen *TI-Messenger-Fachdienstes*.
 
-IMPORTANT: Die Seite ergänzt die Spezifikation gemäß link:https://fachportal.gematik.de/fachportal-import/files/gemSpec_TI-Messenger-FD_V1.1.1.pdf[[gemSpec_TI-Messenger-FD]], die als Grundlage für das Verständnis vorrausgesetzt wird. 
-
 Der *TI-Messenger-Fachdienst* besteht aus unterschiedlichen Teilkomponenten und Schnittstellen. Die nachfolge Abbildung verdeutlicht den Zusammenhang zwischen den Komponenten und den Kommunikationsschnittstellen. 
 
 image::I_Fachdienst.png[width="100%"]

images/generated/Other/chatbot.png

@@ -0,0 +1,31 @@
+# GSC000: Template für neue GSC Proposals
+
+*🇩🇪 Die TI-M Spezifikation und verwandte Dokumente sind aktuell leider
+ausschließlich auf Deutsch verfügbar. Um die Diskussion von Änderungsvorschlägen
+zu vereinfachen, sollten GSCs daher ebenfalls in deutscher Sprache verfasst
+werden.*
+
+*In diesem einleitenden Abschnitt sollte das zu lösende Problem ausführlich
+beschrieben und die vorgeschlagene Lösung knapp zusammengefasst werden.*
+
+## Änderungsvorschlag
+
+*Hier sollte die Lösung des eingangs aufgezeigten Problems mit allen dazu
+nötigen technischen Details beschrieben werden. Dabei sollten Entscheidungen
+motiviert und begründet werden um Spekulationen zu vermeiden.*
+
+## Sicherheit und Datenschutz
+
+*Welche Auswirkungen hat die Änderung auf Sicherheits- und Datenschutzaspekte?
+Bietet die vorgeschlagene Lösung Angriffspunkte? Falls ja, wie relevant sind
+diese Vektoren und wie könnten sie mitigiert werden?*
+
+## Kompatibilität & Migration
+
+*Ist die Änderung abwärtskompatibel zu TI-Messenger Implementierungen im Feld?
+Falls nein, wie könnte eine Migration umgesetzt werden?*
+
+## Alternativen
+
+*Welche Alternativen zur vorgeschlagenen Lösung gibt es und warum sind diese als
+schlechter zu bewerten?*

images/generated/Other/funktionalitaet_proxy.png

@@ -0,0 +1,71 @@
+# Entfernung der Custom State Events für strukturierte Daten
+
+TI-M Basis beschreibt in [Kapitel 5.5] die "TI-M spezifische Kommunikation".
+Hierbei werden eigene State Events definiert, zu denen auch die Events
+`de.gematik.tim.room.casereference.v1` und `de.gematik.tim.room.default.v1`
+gehören. In diesen State Events sollen strukturierte Daten, wie z. B.
+FHIR-Objekten zu einem Behandlungsfall gespeichert werden um damit spezielle
+Anwendungsfälle zu unterstützen.
+
+Vorraussetzung hierfür ist allerdings State Events verschlüsseln zu können was
+zum jetzigen Zeitpunkt noch nicht im Protokoll vorgesehen ist[^1]. Aus diesem
+Grund ist das [Unterkapitel 5.5.2] vollständig von der Umsetzung
+ausgenommen[^2]. Die Tatsache, dass dieses Kapitel trotzdem in der Spezifikation
+auftaucht und konkrete Anforderungen enthält führt dabei vielfach zu
+Irritationen und Nachfragen.
+
+Weiterhin müssen wegen [A_25756] und [A_25813] die State Events
+`de.gematik.tim.room.casereference.v1` und `de.gematik.tim.room.default.v1` beim
+Anlegen von Räumen gesendet werden, was auch im Rahmen der automatisierten
+Zulassungstests geprüft wird. Auch dies verursacht wiederkehrend Verwirrung,
+denn das zwangsweise Senden von Events, die gar nicht benutzt werden können
+erscheint vollständig zwecklos.
+
+Dieses Proposal strebt eine inkrementelle Verbesserung dieser Situation durch
+Entfernung bestimmter nutzloser Teile der Spezifikation an.
+
+## Änderungsvorschlag
+
+Das [Unterkapitel 5.5.2] wird vollständig aus der Spezifikation entfernt. Damit
+verschwinden [A_25756] und das State Event
+`de.gematik.tim.room.casereference.v1`.
+
+Da dieses Unterkapitel bereits heute unverbindlich ist, ergeben sich dadurch
+keine Auswirkungen auf die Zulassung oder bestehende Implementierungen. Der
+einzige Mehrwert dieses Abschnittes ist, dass ein Ausblick auf zukünftige
+Entwicklungen gegeben wird. Das ist aber zum einen nur bedingt Aufgabe der
+Spezifikation und zum anderen funktioniert es an dieser Stelle nicht richtig.
+Eine tatsächliche Verschlüsselung von State Events würde nämlich weitere
+inkompatible Änderungen am Schema erfordern, z. B. durch die Verschlüsselung des
+Event Typs. Durch die Entfernung dieses Unterkapitel wird die Spezifikation
+vereinfacht und zukünftigen Missverständnissen vorgebeugt. Der zugehörige Text
+kann unabhängig hiervon im Änderungsmanagementsystem der gematik verbleiben und
+in Zukunft wiederverwendet werden.
+
+Des Weiteren wird das State Event `de.gematik.tim.room.default.v1` aus den
+Pflichtparametern für [`/createRoom`] in [A_25813] entfernt. Das verpflichtende
+Senden eines nicht benutzbaren Events erscheint sinnlos. Eine zukünftige
+Verwendung des Events würde auch hier inkompatible Änderungen erfordern. Das
+heutige Senden des Events erfüllt daher auch keinen vorbereitenden Zweck. Da das
+Event nicht verwendet werden kann, bewirkt eine Entfernung aus [A_25813] zudem
+keine Inkompatibilitäten.
+
+Abschließend wird [A_25816] mit derselben Argumentation gestrichen.
+
+Das [Kapitel 5.5] ist mit diesen Änderungen zwar nicht abschließend
+bereinigt[^3] aber zumindest deutlich klarer und weniger anfällig für Nachfragen
+als in seiner heutigen Form.
+
+[^1]: Eine mögliche Variante hierfür ist [MSC3414].
+
+[^2]: Siehe hierzu den Hinweis ganz am Ende der Einleitung von [Kapitel 5.5].
+
+[^3]: Siehe auch <https://github.com/gematik/api-ti-messenger/issues/272>.
+
+  [Kapitel 5.5]: https://gemspec.gematik.de/docs/gemSpec/gemSpec_TI-M_Basis/gemSpec_TI-M_Basis_V1.1.1/#5.5
+  [Unterkapitel 5.5.2]: https://gemspec.gematik.de/docs/gemSpec/gemSpec_TI-M_Basis/gemSpec_TI-M_Basis_V1.1.1/#5.5.2
+  [A_25756]: https://gemspec.gematik.de/docs/gemSpec/gemSpec_TI-M_Basis/gemSpec_TI-M_Basis_V1.1.1/#A_25756-01
+  [A_25813]: https://gemspec.gematik.de/docs/gemSpec/gemSpec_TI-M_Basis/gemSpec_TI-M_Basis_V1.1.1/#A_25813-01
+  [`/createRoom`]: https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3createroom
+  [A_25816]: https://gemspec.gematik.de/docs/gemSpec/gemSpec_TI-M_Basis/gemSpec_TI-M_Basis_V1.1.1/#A_25816
+  [MSC3414]: https://github.com/matrix-org/matrix-spec-proposals/pull/3414

images/generated/TI-M_Basis/API-Messenger-Service.png

@@ -0,0 +1,68 @@
+# Optionale serverseitige Suche
+
+Das Matrix-Modul [Server Side Search] ist nach [A_25395] für alle TI-M Clients
+verpflichtend. Mit dem Endpunkt [`/_matrix/client/v3/search`] aus diesem Modul
+können Clients eine Volltextsuche auf Events in allen Räumen eines Benutzers
+ausführen. Diese Operation auf dem Server auszuführen hat den Vorteil, dass der
+Client für die Suche nicht erst die komplette Historie aller Räume laden muss.
+Aufgrund der Ende-zu-Ende-Verschlüsselung kann der Server allerdings nur
+unverschlüsselte Events durchsuchen, in verschlüsselten Räumen also nur State
+Events. Durch die zur Verfügung stehenden [Kategorien], sind das konkret nur die
+State Events für Raumname und Topic.
+
+Bei verschlüsselten Räumen erscheint eine auf Name und Topic beschränkte
+serverseitige Suche nur bedingt hilfreich. Das liegt u. a. auch daran, dass die
+Raumnamen üblicherweise für die Raumliste im Client ohnehin schon zur Verfügung
+stehen.
+
+In unverschlüsselten Räumen kann die serverseitige Suche ein nützliches Feature
+sein. Wegen [A_25324] aus TI-M Basis, [A_26015] und [A_25996] aus TI-M ePA sowie
+[A_25325] aus TI-M Pro dürfen unverschlüsselte Räume allerdings nur durch TI-M
+Pro Nutzer erzeugt werden. Weiterhin dürfen diese Räume wegen [A_26515] aus TI-M
+Pro nur durch Nutzer desselben Homeservers betreten werden.
+
+In Summe bedeutet das TI-M ePA Nutzer können keine unverschlüsselten Räume
+haben. Eine verpflichtende Umsetzung des Moduls [Server Side Search] erscheint
+für TI-M ePA Clients daher nicht sinnvoll.
+
+Für TI-M Pro Nutzer können zwar unverschlüsselte Räume existieren. Diese Räume
+werden allerdings nur einen Bruchteil der Kommunikation dieser Nutzer ausmachen.
+Eine Verpflichtung zur Umsetzung der serverseitigen Suche erscheint daher auch
+hier unnötig.
+
+Im diesem Proposal wird die Verpflichtung zur Umsetzung dieses Moduls daher
+abgeschwächt.
+
+## Änderungsvorschlag
+
+Das Modul [Server Side Search] wird in [A_25395] auf KANN herabgestuft. Clients
+haben damit die Wahlmöglichkeit das Modul zu verwenden oder nicht.
+
+## Sicherheit und Datenschutz
+
+Keine Auswirkungen.
+
+## Kompatibilität & Migration
+
+Durch [A_26210] müssen Homeserver das Modul weiterhin umsetzen.
+Kompatibilitätsprobleme kann es daher nicht geben.
+
+## Alternativen
+
+Das Modul könnte für TI-M Pro Clients als MUSS beibehalten werden. Die
+Modultabelle aus [A_25395] in TI-M Basis müsste dafür durch eine neue
+Anforderung in TI-M Pro überschrieben werden. Die daraus resultierende höhere
+Komplexität der Spezifikation erscheint nicht gerechtfertigt da der Use Case für
+dieses Feature wie oben beschrieben verhältnismäßig klein ist. Zudem ist die
+Verwendung des Moduls in TI-M Pro durch die KANN-Klassifizierung nicht verboten.
+
+  [Server Side Search]: https://spec.matrix.org/v1.13/client-server-api/#server-side-search
+  [A_25395]: https://gemspec.gematik.de/docs/gemSpec/gemSpec_TI-M_Basis/gemSpec_TI-M_Basis_V1.1.1/#A_25395-01
+  [`/_matrix/client/v3/search`]: https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3search
+  [Kategorien]: https://spec.matrix.org/v1.13/client-server-api/#search-categories
+  [A_25324]: https://gemspec.gematik.de/docs/gemSpec/gemSpec_TI-M_Basis/gemSpec_TI-M_Basis_V1.1.1/#A_25324
+  [A_26015]: https://gemspec.gematik.de/docs/gemSpec/gemSpec_TI-M_ePA/gemSpec_TI-M_ePA_V1.1.1/#A_26015
+  [A_25996]: https://gemspec.gematik.de/docs/gemSpec/gemSpec_TI-M_ePA/gemSpec_TI-M_ePA_V1.1.1/#A_25996
+  [A_25325]: https://gemspec.gematik.de/docs/gemSpec/gemSpec_TI-M_Pro/gemSpec_TI-M_Pro_V1.0.1/#A_25325
+  [A_26515]: https://gemspec.gematik.de/docs/gemSpec/gemSpec_TI-M_Pro/gemSpec_TI-M_Pro_V1.0.1/#A_26515
+  [A_26210]: https://gemspec.gematik.de/docs/gemSpec/gemSpec_TI-M_Basis/gemSpec_TI-M_Basis_V1.1.1/#A_26210