Weltmodell / Data Dictionary — kanonische Entitäten & Wertobjekte

Kernaussage (BLUF). Medidentas führt ein Data Dictionary / Weltmodell: den kanonischen Katalog der Domänen-Entitäten und Wertobjekte. Jeder Begriff wird einmal definiert und überall in derselben Struktur gehandhabt — in UI · API/DTO · Persistenz · Doku. Es gibt nie zwei divergierende Formen desselben Begriffs. Wertobjekte sind zusammengesetzt und atomar (keine Freitext-Sammelfelder). Anschrift ist das erste kanonische Wertobjekt: strasse (Straße inkl. Hausnummer) · plz (Postleitzahl) · ort (Ort) — immer getrennt. Leitprinzip G-8, Entscheidung MED-D-85.

Zielgruppe: IT-Dev/Architektur (primär), Business/Management (Konzept & Governance). Verwandt: System-Charakter.md · Prozessmodell.md · Lastenheft.md (Modul-Felder R1–R13).

---

1. Warum ein Weltmodell? (die tragenden Gründe)

• Eine Wahrheit je Begriff (G-2). "Anschrift", "Name", "Bankverbindung", "Kontakt" bedeuten überall dasselbe — gleiche Felder, gleiche Typen, gleiche Regeln. Kein Feld wird an einer Stelle als Einzeltext, an anderer strukturiert geführt.
• Selbsterklärbarkeit (G-3). Sprechende, stabile Feldnamen aus der Fachpraxis; ein Entwickler, ein Fachanwender und die Doku benennen dasselbe Feld identisch.
• Weniger Abbildungs-Bugs. Divergierende Formen erzwingen verlustbehaftete Mappings — z. B. die bewusst grobe anschrift→strasse-Übernahme in MED-D-84 (einzeilige Adresse ohne Parser). Mit einer strukturierten Anschrift entfällt der Verlust: strasse→strasse, plz→plz, ort→ort.
• Auswertbarkeit & Compliance. Strukturierte Felder sind filter-/prüf-/löschbar (DSGVO Art. 15/17), einzeilige Sammelfelder nicht.

2. Begriffe: Entität vs. Wertobjekt

Begriff	Merkmal	Beispiele
Entität	eigene Identität (ID) + Lebenszyklus; wird referenziert	Mandant (R1) · Praxis/Gesellschaft (R1) · Beratungsauftrag (0..n je Mandant, MED-D-95 — eigener Status anbahnung→…→abgeschlossen, Detail: Beratungsauftraege.md) · Bankkonto (0..n je Mandant, R1-F33/MED-D-195 — 1:n-Bank-Entität mit eigener Identität + Prüfstatus neu/geprüft/archiviert + sepaGueltig, Kontext privat/Praxis; löst das eingebettete Wertobjekt Bankverbindung ab, zwei-phasig) · Dokument (R3) · Wiedervorlage (R5) · Meeting (R11) · StammdatenVersion (0..n je Mandant, MED-D-179 — append-only, per-Mandant hash-verkettet; eigene Identität version je Mandant, hält frühere Stammdaten-Snapshots vor; Detail: Lastenheft.md §4.4)
Wertobjekt	keine eigene Identität; zusammengesetzter Wert, wird eingebettet und 1:1 wiederverwendet	Anschrift · Name (nachname/titel/vorname) · Bankverbindung (IBAN) · Kontakt (email/telefon)

Regel: Ein Wertobjekt wird als Ganzes in Entitäten eingebettet — mit denselben Feldnamen. Es wird nicht je Entität neu erfunden.

3. Der Katalog (Start)

3.1 Anschrift (Wertobjekt) — kanonisch

Feld	Typ	Bedeutung	Regeln
strasse	string | null	Straße inkl. Hausnummer (eine Zeile: "Lindenstr. 14")	getrimmt; Straße + Hausnr. zusammen
plz	string | null	Postleitzahl (postal code)	getrimmt; separat (nicht im Ort)
ort	string | null	Ort (city)	getrimmt; separat

• Immer diese drei getrennten Felder — nie eine einzeilige Freitext-Adresse. (Optional später: land für AT/CH; wird bei Bedarf hier ergänzt, dann überall.)
• Anzeige (abgeleitet, G-2): strasse, plz ort (z. B. "Lindenstr. 14, 40210 Düsseldorf") — die Zusammensetzung ist View-Logik, kein gespeichertes Feld (anschrift(m)-Helper in Client/Doku).

3.2 Weitere Wertobjekte (bereits im Code, hier katalogisiert)

Wertobjekt	Felder	Status	Fundort
Name	nachname · titel · vorname (→ abgeleiteter anzeigename, G-2)	✅ strukturiert	R1, domain/mandant-name.ts (D-31)
Bankverbindung	iban (normalisiert, Mod-97)	✅ strukturiert	domain/iban.ts (MED-D-71); seit MED-D-195 (S3a) zur eigenen 1:n-Bankkonto-Entität ausgebaut (Inhaber · IBAN · Zeichnungsberechtigung · Prüfstatus · SEPA); die Einzel-Felder Mandant.ibanPrivat/Praxis.iban bleiben zwei-phasig lesbar (Backfill), werden aber nicht mehr weiterentwickelt
Kontakt	email · telefon (Festnetz) · handynummer (mobil)	✅ Felder vorhanden	R1 (email v24, telefon v33/MED-D-84, handynummer v56/MED-D-284)
Anschrift	strasse · plz · ort	✅ strukturiert (MED-OP-DATA-1 geschlossen)	Mandant v33 (MED-D-84) · Praxis v34 (MED-D-87) · Kundendatenbogen (MED-D-86) · Dienstleistungsauftrag rechnung_* (MED-D-87) · Onboarding-Stammdaten (einwilligung.ts). Legacy-Praxis.standort = Read-Fallback.
Steuer	steuernummer	✅ Feld vorhanden (v56/MED-D-284)	R1. Datensparsam (G-6): bewusst NUR die Steuernummer — KEINE Steuer-ID (§139b AO, kein allgemeines Ordnungsmerkmal).
Steuerberater	steuerberaterName · steuerberaterKanzlei · steuerberaterEmail · steuerberaterTelefon	✅ Felder vorhanden (v56/MED-D-284)	R1. Wer betreut den Mandanten steuerlich? Als Wertobjekt am Mandanten (kein eigener Entitätstyp) — die Steuerberatervollmacht bleibt ein separates Onboarding-Dokument.

3.3 Einbettung (Mermaid)

Hinweis (MED-D-195): Mandant.ibanPrivat / Praxis.iban bleiben als eingebettete Alt-Wertobjekte erhalten (verlustfreier Backfill), die maßgebliche Bankverbindung ist aber die 1:n-Bankkonto-Entität (Feldspec: Lastenheft.md §4.4 R1-F33 ff.; Prüfstatus-Zustandsmaschine ebd.).

4. Angleichungs-Backlog (bestehende Divergenzen → Anschrift)

Der Bestand war bewusst gemischt (kein retroaktiver Big-Bang, analog ID-System): divergierende Formen wurden beim nächsten inhaltlichen Anfassen auf das Wertobjekt gezogen. MED-OP-DATA-1 ist damit abgeschlossen (alle bekannten Einzeilen-Adressen strukturiert bzw. mit Read-Fallback):

Fundstelle	Status	Umsetzung
Ausfüll-Formular kundendatenbogen_v1	✅ MED-D-86 (0.59.1)	3 Felder strasse/plz/ort → verlustfreie Übernahme (kein anschrift→strasse-Parser mehr)
Ausfüll-Formular dienstleistungsauftrag_…	✅ MED-D-87 (0.60.0)	rechnungsanschrift → rechnung_strasse/rechnung_plz/rechnung_ort (Rechnungs- ≠ Wohnanschrift, keine Rückübernahme)
Praxis.standort	✅ MED-D-87 (0.60.0)	strukturierte Anschrift strasse/plz/ort je Praxis (Migration v34); Legacy-standort = Read-Fallback (kein Parser für Bestandsdaten)

Governance-Rest (kein offener Bau): neue Adressfelder kommen laut G-8 immer strukturiert; der Legacy-Praxis.standort bleibt als Anzeige-Fallback für Altdaten, wird aber nicht mehr befüllt.

5. Governance (Way-of-Working)

1. Neues Feld/Entität → zuerst ins Dictionary. Struktur (Felder/Typen/Regeln) hier festlegen, dann in Code (model/schema/DTO) + UI umsetzen.
2. Wiederverwenden, nicht neu erfinden. Ein Wertobjekt wird mit identischen Feldnamen eingebettet.
3. Je PR mitführen (wie Feature-Liste): neue/erweiterte Entitäten & Wertobjekte hier eintragen; eine angeglichene Divergenz aus §4 streichen.
4. Abgeleitete Sichten (Anzeige-Adresse, Anzeigename) bleiben View-Logik, nie doppelt gespeichert (G-2).
5. Kein Verlust-Mapping als Dauerlösung. Wo ein grobes Mapping nötig war (kein Parser), steht ein Eintrag in §4 — bis die Quelle strukturiert ist.

6. Bezug

• Leitprinzip: CLAUDE.md G-8. Entscheidung: docs/betrieb/Decision-Log.md MED-D-85.
• Offener Punkt: MED-OP-DATA-1 (Angleichung der Einzeilen-Adressen, HANDOFF.md §4).
• Erste Anwendung / Anlass: MED-D-84 (Formular → Stammdaten) machte die grobe anschrift→strasse- Abbildung sichtbar → Auslöser für das Weltmodell.
• Fachliche Feld-Spezifikation je Modul: docs/fachlich/Lastenheft.md (R1–R13, IDs) — das Dictionary bündelt die quer-liegenden Wertobjekte, das Lastenheft die Modul-Details.