ADR for exchanging the partner (+debitor) person

doc/adr/2025-02-27-exchanging-the-partner-person.md

@@ -0,0 +1,108 @@
+# Änderung eines Geschäftspartners oder Rechnungsempfängers (Debitor)
+
+**Status:**
+- [x] vorgeschlagen von (Michael Hönnig)
+- [ ] akzeptiert von (...)
+- [ ] abgelehnt von (...)
+- [ ] ersetzt durch (ersetzende ADR)
+
+## Kontext und Problemstellung
+
+In vorgegebenen Datenmodell von Geschäftspartnern und Rechnungsempfängern (Debitor), das auch fachliche Rollen wie Repräsentant, technische Ansprechpartner oder   modellieren kann, stellt sich die Frage, wie eine Änderung der Geschäftspartner-Person effizient und konsistent umgesetzt werden kann.
+Diese fachlichen Rollen hängen jeweils an der Partner-Person.
+
+Ein konkretes Beispiel hierfür ist die Änderung von einer natürlichen Person, die verstorben ist, zu deren Erbengemeinschaft.
+**Hierbei stellte sich heraus, dass der die API-Bedienung sehr komplex und damit fehleranfällig ist, weil viele neue Objekte erzeugt und korrekt miteinander verbunden werden müssen. Dies wäre zudem nicht transaktionssicher.** 
+
+Angepasst werden müssen:
+
+1. alle Relations mit der alten Partner-Person:
+- die PARTNER-Relation
+- die DEBITOR-Relations (ggf. mehrere)
+- die OPERATIONS-Relations (ggf. mehrere)
+- die SUBSCRIBER-Relations (ggf. mehrere)
+- die REPRESENTATIVE-Relations (ggf. mehrere)
+- etc.
+2. Die PARTNER-Relation hat die Besonderheit, dass sie zusätzlich im Debitor ausgetauscht werden muss.
+3. Die DEBITOR-Relation die Besonderheit, dass sie zusätzlich im Debitor ausgetauscht werden muss.
+
+Daher sollen möglichst viele dieser *Neuverdrahtungen* im Backend gemacht werden.
+Und dafür braucht es dann eine zentrale Stelle, an der die Kaskade ausgelöst wird. 
+
+Derzeit gibt es zwei mögliche Varianten, diese Änderung dynamisch umzusetzen, die jeweils unterschiedliche Auswirkungen auf die API und die Zugriffsrechte haben.
+
+### Technischer Hintergrund
+
+Zum Zeitpunkt der Erstellung dieses ADR existieren folgende relevante Entitäten:
+- **Person**: Natürliche oder juristische Person (Name, Firma, Anrede etc.)
+- **Contact**: Kontaktdaten einer fachlichen Rolle
+- **Relation**: Mit einem Typ (z.B. PARTNER, DEBITOR, REPRESENTATIVE) und Kontaktdaten versehene Beziehung von einer Person (Holder) zu einer anderen (Anchor)
+- **Partner**: Sind quasi Zusatzdaten einer PARTNER-Relation (derzeit nur die Partnernummer), welche eine Partner-Person mit der Hostsharing-Person verknüpft
+- **Debitor**: Sind quasi Zusatzdaten einer DEBITOR-Relation, welche eine Debitor-Person mit einer Partner-Person verknüpft
+
+Zugriffsrechte werden über ein hierarchisches, dynamisches RBAC-System gesteuert, bei dem der **OWNER** einer Entitäten-Instanz alle Rechte hat, **ADMIN** definierte Spalten aktualisieren darf, **AGENT** Verknüpfungen anlegen kann, und **TENANT**, **GUEST** sowie **REFERRER** nur Lesezugriff haben.
+Partner und Debitor nutzen dabei die RBAC-Rollen der zugehörigen Relations.
+
+## In Betracht gezogene Optionen
+
+* **Variante 1:** Austausch der PARTNER-/DEBITOR-/OPERATIONS-/...-Relations gegen eine neue Relation für die Erbengemeinschaft als neuen Holder
+* **Variante 2:** Änderung des Holders in der bestehenden PARTNER-Relation auf die Erbengemeinschaft
+
+### Variante 1: Austausch der Relations mit neuen Holdern
+
+Ein Austausch der bestehenden PARTNER-/DEBITOR-/OPERATIONS-/...-Relations mit einer neuen Relation, die die Erbengemeinschaft als neuen Holder referenziert.
+
+#### Vorteile
+
+- **Beibehaltung der API:** Dieses Verhalten ist bereits implementiert und benötigt keinen großen Umbau an der API, sondern nur eine Erweiterung um das Austauschen weiterer Relations
+- **UPDATE-Permission für AGENT:** Es wäre möglich, der AGENT-Rolle einer Relation UPDATE-Rechte an der Relation zu geben, weil nur der unkritisch Contact änderbar wäre.
+- **Übereinstimmung von Fachlichkeit und API**: Fachlich handelt es sich um den Austausch der Partner-Person, dazu passend wäre der Endpunkt, allerdings würde nicht direkt die Partner-Person ausgetauscht, sondern eine neue PARTNER-Relation mit der neuen Partner-Person eingesetzt werden.
+
+#### Nachteile
+
+- **Verlust expliziter GRANTs:** Gibt es explizite GRANTs an der PARTNER-Relation, gehen diese verloren, da die Relation ausgetauscht wird. Die Übernahme dieser expliziten Grants erfordert also einen zusätzlichen Implementationsaufwand.
+- **Divergenz zwischen Fachlichkeit und API:** Fachlich handelt es sich um den Austausch der Partner-Person, würde aber eine neue PARTNER-Relation dieser Person in den Partner eingesetzt werden. Das erfordert ein höheres Verständnis des Datenmodells.
+
+### Variante 2: Änderung des Holders in der bestehenden PARTNER-Relation
+
+Die bestehende PARTNER-Relation bleibt erhalten, und der Holder wird von der verstorbenen Person auf die Erbengemeinschaft geändert.
+
+#### Vorteile
+
+- **Erhalt expliziter GRANTs:** Wer explizite Grants an der PARTNER-Relation oder DEBITOR-Relation vergeben hat, behält diese, da die Relation-Instanzen unverändert bleiben.
+- **Einheitliche API-Struktur:** Die REST-API für Änderungen gehört dann einheitlich zum Relation-Endpunkt, was der bestehenden Handhabung von Contact-Änderungen entspricht.
+- **Übereinstimmung von Fachlichkeit und API**: Fachlich handelt es sich um den Austausch der Partner-Person, genau das würde man dann an der API machen, wenn auch nicht am Partner selbst, sondern an der PARTNER-Relation.
+
+#### Nachteile
+
+- **Kein UPDATE durch Relation-AGENT:** Der Relation-AGENT darf nicht das Recht bekommen, den Holder auszutauschen. Da es keine Spalten-spezifischen Update-Rechte gibt, könnte dieser auch den Contact nicht mehr austauschen. Derzeit ist das aber auch nicht vorgesehen.
+- **Umbau der API:** Der Austausch einer Partner-Person würde vom Partner-Endpunkt (/api/hs/office/partner) zur Relation (/api/hs/office/partner) wandern, was ein größerer Umbau, auch bei den Tests wäre.
+- **Divergenz von Fachlichkeit und API**: Fachlich handelt es sich um den Austausch der Partner-Person, aber man würde die Person nicht am Partner selbst austauschen, sondern an der PARTNER-Relation.
+
+## Entscheidung und Ergebnis
+
+**Entscheidung:** Noch kein klares Ergebnis
+
+**Begründung:**
+- Die meisten Vor- und Nachteile gleichen sich aus, was besonders bei der Übereinstimmung bzw. Divergenz zwischen Fachlichkeit und API zum Ausdruck kommt.
+- Diese Variante erfordert keinen grundsätzlichen Umbau der API und daher weniger aufwändig.
+- Ein großer Aufwand, nämlich die Übernahme der GRANTs, könnte sogar zunächst zurückgestellt werden.
+
+| Bereich                                                    | 1. Relations ersetzen | 2. Relations aktualisieren |
+|------------------------------------------------------------|----------------------:|---------------------------:|
+| **Aufwände**                                               |                       |                            |
+| Beibehaltung der API vs. Umbau, inkl. Risiko               |                       |                         -3 |
+| Anwendbar auf Partner-Person + Debitor-Person              |                       |                         +1 |
+| Aufwand für explizite Grants                               |                    -1 |                            |
+| **Zwischenergebnis für Aufwände**                          |                **-1** |                     **-2** |
+|                                                            |                       |                            | 
+| **Fachlichkeit/Einheitlichkeit etc.**                      |                       |                            |
+| Kongruenz von Fachlichkeit+API                             |                    +1 |                         -1 |
+| Einheitlichkeit/Generizität der API                        |                       |                         +1 |
+| Direktheit der API                                         |                       |                         +1 |
+| UPDATE Permission für Relation-AGENT möglich               |                    +1 |                            |
+| **Zwischenergebnis für Fachlichkeit/Einheitlichkeit etc.** |                **+2** |                     **+1** |
+|                                                            |                       |                            |
+| **Ergebnis**                                               |                **+1** |                     **-1** | 
+
+