From f8254d9c2f09d1bb3c093e8fab5f8700086796a7 Mon Sep 17 00:00:00 2001 From: Michael Hoennig Date: Sun, 2 Mar 2025 17:00:18 +0100 Subject: [PATCH] ADR for exchanging the partner (+debitor) person --- ...025-02-27-exchanging-the-partner-person.md | 108 ++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 doc/adr/2025-02-27-exchanging-the-partner-person.md diff --git a/doc/adr/2025-02-27-exchanging-the-partner-person.md b/doc/adr/2025-02-27-exchanging-the-partner-person.md new file mode 100644 index 00000000..1d2dedd3 --- /dev/null +++ b/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** | + +