CodamAIDocs

Legende

Was die Bilder auf diesen Seiten bedeuten und wie man sie liest.

Auf allen Seiten gibt es dieselben Bildarten. Jede hat eine Aufgabe, und sobald du sie einmal gelesen hast, kannst du jede Seite lesen.

Farben der Beteiligten

Jeder Beteiligte hat überall dieselbe Farbe:

  1. 1
    Benutzer
    ein Mensch vor einem Bildschirm
  2. 2
    Client
    das Programm, das die API aufruft, also Frontend, BFF oder ein anderer Server
  3. 3
    CDMS
    die Datenschicht mit REST-API, System-Layer und Persistenz
  4. 4
    CIAS
    Identität und Zugang, dazu die Filterkette, die jedes Token prüft
  5. 5
    Keycloak
    der Identity Provider. Er prüft Passwörter und stellt die Tokens aus
  6. 6
    Datenbank
    System-Datenbank, Mandanten-Datenbank oder Dateispeicher
  7. 7
    E-Mail
    eine Mail, die an eine Person geht
  8. 8
    Hook
    eigene Fachlogik des Projekts, die sich in den Ablauf einhängt
  9. 9
    Hub
    die Modellierungsoberfläche mit ihrem MCP-Server. Hier stehen die Modelle
  10. 10
    Build
    der Maven-Build des Projekts mit dem Codegenerator

Schritte

Ein Ablauf von oben nach unten. Das farbige Etikett sagt, wer handelt, der Pfeil, an wen er sich wendet. Ein gestrichelter Kreis mit ? steht für eine Prüfung, ein roter Kasten für einen Fehlerausgang, ein grüner für das Ende.

  1. 1
    Client→CDMS
    schickt POST /crm/customer/create
  2. 2
    CDMS
    prüft, ob die Rolle für „anlegen“ im Token steht
  3. 3
    CDMS
    Rolle fehlt → Antwort 403
  4. 4
    CDMS→Datenbank
    schreibt die neue Zeile
    Ergebnis: Objekt angelegt, Antwort 200 mit den angeforderten Feldern

Stationen

Eine Anfrage wandert durch mehrere Stationen. An jeder Station wird etwas geprüft. Rechts steht, was passiert, wenn die Prüfung nicht besteht. Nur wer alle Stationen passiert, erreicht das grüne Ziel.

Beispiel einer Anfrage durch drei Stationen
  1. CIAS
    Filterkette
    Ist das Token gültig?
    ↳ nein 401 – Token erneuern
  2. CDMS
    Rechteprüfung
    Darf diese Rolle das Modell lesen?
    ↳ nein 403
  3. CDMS
    Zeilenfilter
    Gehört das Objekt zum eigenen Mandanten?
    ↳ nein 404 – als gäbe es das Objekt nicht
  4. Daten werden geliefert

Varianten

Viele Abläufe gibt es in mehreren Ausprägungen. Jede Ausprägung ist ein eigener Reiter. Wann sagt, in welcher Situation diese Variante gilt.

Beispiel mit zwei Ausprägungen

Wann: der Normalfall

  1. 1
    Client
    macht etwas
  2. 2
    CDMS
    antwortet

Wann: ein Sonderfall

Hier weicht der Ablauf ab, und zwar an genau dieser Stelle.

Ergebnis: anderes Ergebnis

Entscheidungstabelle

Wenn mehrere Bedingungen zusammen über das Ergebnis entscheiden, steht jede Kombination als eigene Zeile da. Die letzte Spalte ist das Ergebnis. „–“ heißt: spielt hier keine Rolle.

Rolle vorhanden?Ziel erlaubt?Was passiert
nein–Wechsel wird still ignoriert
janein403
jajaWechsel wirkt

Vergleich

Zwei oder mehr Dinge nebeneinander, die man leicht verwechselt.

PUT
ersetzt
  • Was fehlt, wird geleert
  • beschreibt den ganzen Zielzustand
PATCH
ändert
  • Was fehlt, bleibt unverändert
  • nennt nur die Änderung

Feldauswahl

Welche Felder eine Anfrage trifft. Grau heißt „nicht geliefert“, farbig „geliefert“. Referenzen sind gepunktet umrandet und kommen nur mit ihrer id.

einfaches FeldReferenzwird geliefert
AnfrageErgebnis
"+"
firstnamelastnamecompany
"*"
firstnamelastnamecompany (nur id)

Anfrage und Antwort

Anfrage
POST /api/rest/crm/customer/read/42
{ "response": ["id", "name"] }
Antwort
{ "data": { "id": "42", "name": "Muster GmbH" }, "meta": { "error": false } }

Sequenzdiagramme

Für Abläufe mit Hin und Her zwischen mehreren Beteiligten nehmen wir Mermaid-Sequenzdiagramme. Jede senkrechte Linie ist ein Beteiligter, die Zeit läuft nach unten. Ein durchgezogener Pfeil ist eine Anfrage, ein gestrichelter die Antwort. Die Nummern zeigen die Reihenfolge.

sequenceDiagram
    participant C as Client
    participant D as CDMS
    participant DB as Datenbank
    C->>D: POST /query
    D->>DB: SELECT … WHERE …
    DB-->>D: Zeilen
    D-->>C: data + meta

Kästen

Suchen