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 strukturiertenAnschriftentfä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:
landfü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 · steuerId (geplant) | ✅ steuernummer (v56/MED-D-284) · ✅ steuerId (v73/MED-D-703, S0b-1; hash-versioniert) | R1. steuernummer: steuerliche Korrespondenz. steuerId (Steuer-Identifikationsnummer, §139b AO) war in MED-D-284 bewusst ausgeschlossen (G-6); MED-D-703 nimmt sie auf Nutzerentscheidung vom 2026-10-14 auf (Standard-Onboarding-Checkliste führt sie). Zweck, Rechtsgrundlage und Aufbewahrung sind noch zu dokumentieren (G-6, Issue #715) — vor Live-Betrieb Pflicht. |
Steuerberater | steuerberaterName · steuerberaterKanzlei · steuerberaterEmail · steuerberaterTelefon | ✅ am Mandanten (v56/MED-D-284) · ✅ zusätzlich je Praxis (v74/MED-D-703, S0b-2; praxis.steuerberater*) | R1. Wer betreut steuerlich? Wertobjekt mit identischen Feldnamen am Mandanten (privat) und an der Praxis (je Praxis, er kann abweichen); beim Erfassen wird die Übernahme der Daten eines schon erfassten Steuerberaters angeboten (Vorbelegung, nie stille Übernahme). Die Steuerberatervollmacht ist ein Textbaustein (Onboarding-Fragenkataloge.md OB-F7). Seit S6 gebaut: Praxis.steuerberater* (v74) mit Erfassen und Übernahmeangebot (api/steuerberater-service.ts). |
apoBank-Stammnummer | apobankStammnummer (Freitext, optional) | ✅ am Mandanten (v83/MED-D-779, hash-versioniert) | Weltmodell-Attribut bank.apobank_stammnummer. Zweck: Zuordnung bei der apoBank (Fremdformular apobank_edue, Feld fill_6); Rechtsgrundlage: Vertragserfüllung (Art. 6 Abs. 1 lit. b DSGVO); Aufbewahrung wie die Beratungsunterlagen (G-6, RISK-39). Format der Bank wird nicht angenommen — Freitext, weiche Prüfung. Wird nur über Review-and-apply aus dem bestätigten Katalog übernommen. |
Familienstand | Aufzählung: ledig · verheiratet · eheaehnliche_gemeinschaft · geschieden · getrennt_lebend | ✅ am Mandanten (v73/MED-D-703, S0b-1; enums.ts#FAMILIENSTAND, hash-versioniert) | Am Mandanten (person.familienstand). Werte aus den Standard-Formularen (Erfassungsbogen Kundendaten, Beratungsprotokoll); die Kundendaten-Formularfelder verheiratet/geschieden/getrennt lebend sind dort getrennte Ja/Nein-Felder → Abbildung auf einen Wert, Mehrdeutigkeiten klärt der Berater. Zweck: Beratungsgrundlage (G-6 zu belegen, #715). |
Stundensatz | art (berater · kunde) · ref (Benutzer-E-Mail bzw. Mandant-ID) · satzCent (ganze Cent je Stunde, 1 bis 1.000.000) · geaendertAm · geaendertVon | ✅ Tabelle stundensatz (v81/MED-D-660; domain/stundensatz.ts) | Standard-Satz je Berater (Verwaltung) und abweichender Satz je Kunde (Kunden-Detail → Erfasste Zeit), der dann für alle Zeiten dieses Kunden gilt. Der offene Betrag "Zu fakturieren" ist abgeleitet (Satz je Leistungszeit-Eintrag, je Eintrag auf Cent gerundet) und wird nie gespeichert (G-2). Der Satz und damit der Betrag sind netto (ohne Umsatzsteuer; die entsteht erst in der Rechnung, SevDesk) — so auch in der Oberfläche beschriftet (MED-D-660-3). Pflege: stundensatz_pflegen (admin, backoffice). Kein PII über die Referenz hinaus (G-6). |
KundenGruppe | MandantGruppe: id · name (1–80 Zeichen) · art (ehepaar · familie · sonstige, v87/MED-D-811) · archiviertAm (null = aktiv, v87) · angelegtAm · geaendertAm; Mitgliedschaft gruppeId · mandantId · seit (m:n) | ✅ Tabellen mandant_gruppe + mandant_gruppe_mitglied (v82/MED-D-413; domain/mandant-gruppe.ts) | Klammer über Kunden (z. B. Eheleute, D-32). Jede Person bleibt eigene Kunden-Detail; das Kunden-Detail zeigt Querverweise auf die anderen Mitglieder (nur die, die der Betrachter sehen darf, R7; sonst nur die Anzahl). Praxen bleiben einer Person zugeordnet (MED-D-662). Letzte Mitgliedschaft entfernt → Gruppe gelöscht (nicht, solange gemeinsame Dokumente da sind → 409). Audit nur mit Gruppen-ID (G-6). |
GruppenDokument | id · gruppeId · dateiname (bereinigt) · pfad · groesse (Bytes) · hochgeladenAm · hochgeladenVon · unterlageId (erfüllte Pflicht-Unterlage, optional, v87) | ✅ Tabelle gruppen_dokument (v84/MED-D-801; domain/mandant-gruppe.ts) | Geteilte Datei im gemeinsamen Gruppenordner <Basis>/<Buchstabe>/<Gruppenname> (grp<id-kurz>)/Gemeinsames/ (D-32, MED-D-661). Nur Ablage-Referenz, append-only (kein Löschen, G-4). Pfad wird beim Hochladen festgehalten; Umbenennen der Gruppe verschiebt nichts. Inhaltsabruf protokolliert (gruppen_dokument.eingesehen, D-50). Zählt nicht zur Vollständigkeit der Mitglieder. |
GruppenUnterlage | id · art (Gruppenart, bei Vorlagen) · gruppeId (bei Ergänzung je Gruppe) · bezeichnung (1–120 Zeichen) · angelegtAm | ✅ Tabelle gruppen_unterlage (v87/MED-D-811) | Pflicht-Unterlage einer Kunden-Gruppe: Vorlage je Gruppenart (Verwaltung, Admin) oder Ergänzung je Gruppe (Kunden-Detail). Vollständigkeit der Gruppen-Dokumente = Anteil der Pflicht-Unterlagen mit mindestens einem zugeordneten gemeinsamen Dokument — abgeleitet (G-2), zählt nicht für die einzelnen Kunden (E-801-2). Welche Unterlagen je Gruppenart Pflicht sind, legt der Betrieb fest (Start: leer). |
Kind | vorname · geburtsmonat (Format JJJJ-MM) (1:n am Mandanten) | ✅ Tabelle mandant_kind (v74/MED-D-703, S0b-2; domain/kind.ts) — noch nicht hash-versioniert, Schreibweg folgt mit dem Fragenkatalog (S3) | Wiederholungsgruppe im Fragenkatalog (Gruppe kind). Bewusst nur Vorname und Geburtsmonat/-jahr (Nutzerentscheidung 2026-10-14; Zweck: Beratung und Prognose) — kein Nachname, kein Geburtstag (G-6). Daten Minderjähriger → Rechtsgrundlage und Aufbewahrung zu belegen (#715). Die Alt-Formulare fragen Name und volles Geburtsdatum; der Katalog erhebt weniger. |
3.2a Dexman-Planungsbausteine (Entitäten, MED-D-381)
Eine Definition für Server, Browser und Doku: shared/dexman-kern/typen.ts (Typen) + pruefung.ts (Regeln).
Gespeichert als dexman_baustein (Art, Status) + dexman_baustein_version (append-only: gueltig_ab/gueltig_bis
im Format JJJJ-MM, daten als JSON nach diesem Schema, quelle, angelegt_von).
Baustein (art) | Felder | Datensparsamkeit (G-6) |
|---|---|---|
praxis (Praxis-Parameter, 1 je Praxis) | kontoStart · kontokorrentZins · arbeitstageJahr · saison[12] · materialQuote · agAufschlag · kostenpositionen[] (bezeichnung, betragMonat) · privatentnahmeMonat · erloesModus · kassenanteil · kassenVersatzMonate · privatVersatzMonate | keine PII |
person (MED-D-693) | Identität: bezeichnung · rolle · behandler · abschnitte[] (Wertobjekt Anstellung, s. u.) | Kürzel genügt; bewusst keine Steuerklasse/Kinder/Konfession — Stand heute (MED-D-709, §3.2b): AG-Kosten-Felder je Anstellungs-Spanne (u. a. KV-Status) und Lohnnebenkosten je Mitarbeiter und Monat; der pauschale AG-Aufschlag gilt nur noch, wenn keine Parameter vorliegen; weiterhin ohne Steuerklasse/Kinder/Konfession |
darlehen | bezeichnung · kreditgeber · zweck (geschaeftlich·privat·vermietet) · restschuld · zinssatz · zinsFestBis · anschlusszins · tilgungsform (annuitaet·fallend·tilgungsfrei) · rateMonat | keine Darlehens-/Kontonummer, keine IBAN |
anlage | bezeichnung · anschaffungswert · nutzungsdauerJahre · ausKonto | keine PII |
ereignis | bezeichnung · art (ausgabe_praxis·ausgabe_privat·einnahme·umsatzaenderung) · betrag · faktor | keine PII |
Wertobjekt Anstellung (MED-D-693, shared/dexman-kern/person.ts): ab · bis (inkl., null = läuft
weiter) · status (angestellt·freiberuflich·inhaber) · monatsbrutto · umsatzPlanMonat ·
beteiligungSatz · beteiligungAbMonatlich. Eine Spanne trägt den vollständigen Stand ihres Zeitraums;
Gehaltserhöhung, Teilzeit, Statuswechsel und Wiedereintritt sind je eine weitere Spanne (ein Ort je Zeitraum,
G-2). Eintritt/Austritt sind abgeleitet (erste/letzte Spanne) und werden nicht zusätzlich gespeichert; der
Rahmen der Baustein-Version (gueltig_ab/gueltig_bis) wird aus den Spannen gesetzt und nie von Hand
gepflegt. Lücken sind erlaubt (Wiedereintritt), Überlappungen nicht; offen laufen darf nur die letzte Spanne.
Alt-Form (status/monatsbrutto/gehaltsaenderungen[] am Baustein) wird lesend überführt
(Read-Fallback wie Legacy-Praxis.standort, MED-D-87) — kein Datenbank-Umbau, geschrieben wird nur die neue Form.
Ist-Umsatz ist kein Baustein, sondern ein Fakt in praxis_jahreswert: perioden_typ='monat',
feld_schluessel='dexman.umsatz.<personBausteinId>', quelle berater (später portal/pvs). Die
Festschreibung dieser Monate liegt in dexman_festschreibung (append-only Log je Praxis, MED-D-694):
jeder Eintrag setzt das Wasserzeichen „festgeschrieben bis
Beratungsvorschlag (Entität, MED-D-735, R6): ein Vorschlag aus einer Quelle (heute dexman) für die
Beratungsdokumentation, gespeichert in beratungsvorschlag (Kunde · Mandat · quelle · quelle_ref eindeutig ·
titel · text · schaetzung · status vorgeschlagen/uebernommen/verworfen/umgesetzt (verworfen ist auch nach der Übernahme möglich = „nicht umgesetzt") · begruendung ·
beratungsdoku_id · wer/wann vorgeschlagen und entschieden). Kein PII: Titel und Text entstehen aus den
Regeln des Rechenkerns (Kürzel statt Namen, G-6). Der Vorschlag schreibt nie selbst ins Protokoll; Status und
Entscheidung sind je Schritt auditiert (G-4), Systementwurf §10.9.
3.2b Lohnnebenkosten (AG-Kosten) — Parameter und Mitarbeiterfelder (MED-D-709/710, gebaut: Rechenkern shared/dexman-kern/lnk.ts + Parameter-Persistenz und Verwaltung lnk_parameter; Mitarbeiterfelder, Anschluss an rechne.ts, Ist-Beteiligung und Auswertung folgen)
Ziel: Arbeitgeberkosten je Mitarbeiter und Monat inkl. Jahresgrenzen statt pauschalem agAufschlag
(löst OP-DEX-9 ein). Zielmarkt zunächst nur DE. Es gibt keine belegte kostenlose Lohnnebenkosten-API
→ Eigenbau des Rechenkerns (shared/dexman-kern/), Parameter in der Verwaltung pflegbar. Lohnsteuer (BMF-PAP)
wird nicht gebraucht (nur Netto-Seite des Mitarbeiters).
Parameter lnk_parameter (admin-pflegbar, append-only, G-4):
| Feld | Typ / Regel |
|---|---|
schluessel | z. B. bbg_kv_pv_monat · bbg_rv_av_monat · satz_rv · satz_av · satz_kv_allgemein · satz_kv_zusatz_durchschnitt · satz_pv · satz_pv_ag_sachsen · grenze_minijob · grenze_uebergang_unten/_oben · umlage_u1_minijob · umlage_u2_minijob · umlage_insolvenzgeld · pauschale_kv_minijob · pauschale_rv_minijob |
wert | Betrag (€) oder Satz (Dezimal) |
gueltigAb | JJJJ-MM; gilt bis zum nächsten Eintrag desselben schluessel |
quelle | Pflicht: amtliche Fundstelle (URL/Norm) |
geprueftAm | Datum der Quellenprüfung |
belegt | false = Quelle nicht im Volltext gelesen; vor Produktivnutzung prüfen (Auswertungen weisen darauf hin) |
angelegtVon | Rolle/Benutzer (Audit) |
Gebaut (Slice 2): Tabelle lnk_parameter (Migration v73, Startwerte als eingefrorene Literale, angelegt_von = 'system'), API GET/POST /api/lnk-parameter, Verwaltung → "Lohnnebenkosten-Parameter". Lesen darf jede Rolle (die Berechnung braucht die Werte), Pflegen nur admin (Fähigkeit lnk_parameter_verwalten); jede Anlage wird PII-arm auditiert (lnk_parameter.angelegt). Eine Korrektur ist ein neuer Eintrag: bei gleichem Schlüssel und gleichem "gültig ab" gilt der später angelegte, der alte bleibt als "ersetzt" sichtbar (G-4). Sätze werden in der Verwaltung in Prozent eingegeben (14,6) und als Dezimalzahl gespeichert (0,146).
Abgeleitet, nie gespeichert (G-2): gueltigBis (= Beginn des Nachfolgers) und draft (= gueltigAb liegt nach dem
aktuellen Monat). Werte in der Zukunft sind zulässig und als Draft gekennzeichnet; Auswertungen, die einen Draft-Wert
nutzen, weisen darauf hin ("auf Basis vorläufiger Werte").
Seed 2026/2027 (Stand der Recherche 2026-10-15; "belegt" = Primärquelle gelesen):
| Parameter | Wert | Status | Quelle |
|---|---|---|---|
| BBG KV/PV | 5.812,50 €/Monat (69.750 €/Jahr) | belegt | Bundesregierung, BMAS |
| BBG RV/AV | 8.450 €/Monat (101.400 €/Jahr) | belegt | BMAS (wie oben) |
| BBG KV/PV 2027 | 6.375 €/Monat (76.500 €/Jahr), Draft | belegt (Kabinettsbeschluss 07.10.2026, Bundesrat steht aus) | BMAS, Pressemitteilung |
| BBG RV/AV 2027 | 8.850 €/Monat (106.200 €/Jahr), Draft | belegt (wie oben) | BMAS (wie oben) |
| Bezugsgröße | 3.955 €/Monat | belegt | BMAS (wie oben) |
| KV allgemein / ermäßigt | 14,6 % / 14,0 % Basissatz; der Zusatzbeitrag (nächste Zeile) kommt hinzu; Beitrag insgesamt je zur Hälfte AG/AN | belegt | BMG (Stand 03.09.2026) |
| Zusatzbeitrag | kassenindividuell; Ø-Richtwert 2,9 % | belegt (Richtwert) | BMG, BAnz AT 10.11.2025 |
| RV | 18,6 %, je zur Hälfte AG/AN | belegt (§ 168 Abs. 1 Nr. 1 SGB VI: je zur Hälfte) | DRV |
| AV | 2,6 %, je zur Hälfte AG/AN | belegt | § 341 Abs. 2 SGB III, § 346 Abs. 1 SGB III |
| PV | 3,6 % seit 01.01.2025; AG 1,8 % | belegt | BMG, Finanzierung der sozialen Pflegeversicherung (Stand 14.09.2026); die Gesetzesseite § 55 SGB XI zeigt im Satz 1 noch 3,4 %, der erhöhte Satz steht dort nicht im abgerufenen Auszug |
| PV Sachsen | Arbeitgeber 1,3 %, Beschäftigte 2,3 % | belegt | BMG (wie oben), DRV Lexikon Beitragstragung |
| Minijob-Grenze (Geringfügigkeitsgrenze) | 603 € ab 01.01.2026; 633 € ab 01.01.2027 (Draft) | belegt | Geringfügigkeits-Richtlinien 2026 (Minijob-Zentrale), BAnz AT 20.11.2025 B1 |
| Übergangsbereich | 603,01 € bis 2.000,00 € ab 01.01.2026 | belegt | DRV |
| Minijob-Pauschalen gewerblich | KV 13 %, RV 15 %, Steuer 2 % | belegt | Minijob-Zentrale |
| Umlagen Minijob | U1 0,80 % · U2 0,22 % · Insolvenzgeld 0,15 % | belegt | Minijob-Zentrale (wie oben) |
| U1/U2 reguläre Beschäftigte | kassenindividuell | — | Feld je Kasse/Mitarbeiter |
Vorlauf 2027 (Draft, Status teils unklar): Geringfügigkeitsgrenze 633 € und Beitragsbemessungsgrenzen (belegt, s. o.; im Seed) · durchschnittlicher Zusatzbeitrag: Schätzerkreis vom 14.10.2026 rechnerisch 2,9 % laut GKV-Spitzenverband, BMG-Bekanntmachung steht aus (nur Richtwert, nicht im Seed) · AG-Pflegebeitrag auf Minijob-Entgelt 3,6 % (BMG-Seite Pflegeneuordnungsgesetz, Stand 07.10.2026: nur Entwurf, Beginn dort nicht genannt) · Kinderlosenzuschlag PV 0,6 → 0,9 % (gleiche Quelle, nur Entwurf, trifft nur den Arbeitnehmer) · Minijob-KV-Pauschale 13 % → 17,5 %: nicht belegt (nur Suchtreffer; Gesetzesstatus und Satz prüfen, bis dahin nicht in den Seed).
Mitarbeiterfelder (gebaut, MED-D-709 Slice 3; Erweiterung des Wertobjekts Anstellung in abschnitte[], MED-D-693: ein Ort je Zeitraum, die Spanne ab/bis trägt das "gültig ab Monat", G-2). Alle Felder sind optional; beim Speichern werden Vorgaben eingetragen (regulaer, gesetzlich, kvZusatzbeitrag = null = Durchschnittssatz, 0). Der PKV-Zuschuss wird nur bei privat gespeichert, der Inhaber trägt keine AG-Kosten. Das Formular zeigt die Felder nur bei Status angestellt:
| Feld | Werte | Zweck |
|---|---|---|
beschaeftigungsart | regulaer · minijob · uebergangsbereich · azubi | Satz-/Grenzenwahl |
kvStatus | gesetzlich · privat | AG-Anteil KV oder PKV-Zuschuss |
kvZusatzbeitrag | Satz | kassenindividuell |
pkvAgZuschuss | € / Monat | nur bei privat |
umlageU1 · umlageU2 | Satz | kassenindividuell (reguläre Beschäftigte) |
anzahlPersonen | ganze Zahl 1 bis 50, Vorgabe 1 | Sammeleintrag: Grenzen je Person (MED-D-709 Slice 4) |
Rechenregel in der Auswertung (gebaut, MED-D-709 Slice 4): rechne() bekommt die Parameter über eingabe.lnkParameter (der Worker liefert sie in stand() aus lnk_parameter, der Browser rechnet mit denselben Werten). Personalkosten eines angestellten Mitarbeiters im Monat = Brutto + Umsatzbeteiligung (als laufender Arbeitslohn) + agKostenMonat(...). Rückfall: fehlt lnkParameter ganz, gilt der pauschale agAufschlag; fehlt für einen einzelnen Monat ein Parameter (z. B. vor dem ersten "gültig ab"), gilt für diesen Monat die Pauschale und die Lücke steht in Ergebnis.agKosten.fehlend — nie eine stille 0. Ergebnis.agKosten weist außerdem aus: Modus (lohnnebenkosten/pauschal), Draft (mindestens ein Parameter gilt erst in der Zukunft), unbelegt und Hinweise; die Oberfläche zeigt das im Reiter Personal. kvZusatzbeitrag = null nutzt den Parameter satz_kv_zusatz_durchschnitt. Vereinfachungen: Unfallversicherung nur mit dem Jahresbeitrag laut Bescheid (sonst 0 mit Hinweis), Freiberufler und Inhaber haben keine AG-Kosten, ein Eintrag für mehrere Personen (z. B. "ZFA-Team") trägt anzahlPersonen (Vorgabe 1; monatsbrutto und Beteiligung sind dann die Summe, die Grenzen gelten je Person = Brutto ÷ Anzahl); ohne Angabe würde ein Sammeleintrag als eine Person geprüft und die Nebenkosten zu niedrig gerechnet, dafür erscheint ein Hinweis.
Praxisfelder (Erweiterung praxis): pvSachsen (gebaut, Boolean, Vorgabe false; Beschäftigungsort Sachsen → abweichender AG-Anteil PV; Zuordnung Praxis vs.
Mitarbeiter zu bestätigen) · Unfallversicherungs-Beitrag (gebaut, Issue #805): unfallJahresbeitrag (€ je Jahr laut Beitragsbescheid der Berufsgenossenschaft, Vorgabe 0); in der Rechnung je Monat ein Zwölftel, solange angestellte Personen beschäftigt sind; ohne Angabe bleibt die Position 0 mit ausdrücklichem Hinweis. Der Beitrag ist kein fester Satz auf das Brutto (Jahresbeitrag = Entgelte × Gefahrklasse × Beitragsfuß ÷ 1.000, laut BG-Bescheid), deshalb gilt der Bescheid-Wert statt einer Schätzung.
Bewusst nicht erfasst (G-6): Steuerklasse, Faktor, Kinderfreibeträge, Konfession/Kirchensteuer — für AG-Kosten nicht nötig; Konfession wäre eine besondere Datenkategorie (Art. 9 DSGVO).
Ist-Umsatzbeteiligung (gebaut, MED-D-709 Slice 5; Wertobjekt BeteiligungIst): personId · monat (Zuflussmonat, rückwirkend
erfassbar) · lohnart (laufend · sonstiger_bezug, wählbar) · betrag. Gespeichert als Fakten der Kern-Faktentabelle praxis_jahreswert
(dexman.beteiligung.laufend.<personId> und dexman.beteiligung.sonstig.<personId>, perioden_typ = 'monat', Quelle berater), wie die
Ist-Umsätze: ein Wert je Person, Monat und Lohnart, eine Korrektur überschreibt; die Änderungshistorie trägt das Audit-Ereignis
dexman.beteiligung.erfasst (Monat, Anzahl, Rolle des Erfassers, keine Beträge). Festgeschriebene Monate sind gesperrt (MED-D-694).
Regel in der Auswertung: Der laufende Betrag ersetzt für seinen Zuflussmonat die geplante Beteiligung (auch 0 = nichts
ausgezahlt) und geht als laufender Arbeitslohn in die Arbeitgeberkosten ein (Grenzen je Monat und Person). Ein sonstiger Bezug zählt
als Auszahlung in den Personalkosten; die Arbeitgeberanteile darauf werden nach § 23a SGB IV gerechnet (Vorschlag, Issue #804, vom Steuerberater zu bestätigen):
- Abs. 3: Beitragspflichtig ist der Bezug, soweit das bisherige beitragspflichtige Entgelt des Jahres die anteilige Beitragsbemessungsgrenze nicht erreicht (Monatsgrenze × Monate mit laufendem Entgelt bis zum Zahlmonat). Das bisherige Entgelt zählt das laufende Entgelt je Monat höchstens bis zur Monatsgrenze plus frühere beitragspflichtige Einmalzahlungen. Je Versicherungszweig: Kranken-/Pflegeversicherung mit der Grenze KV/PV, Renten-/Arbeitslosenversicherung, Umlagen und Insolvenzgeld mit der Grenze RV/AV (gleiche Umlagebasis wie beim laufenden Entgelt).
- Abs. 4 (Märzklausel): Ein Bezug von Januar bis März, der zusammen mit dem übrigen Entgelt des Jahres die anteilige Grenze übersteigt, wird dem Vorjahr zugeordnet; beitragspflichtig ist dann nur, was dort noch unter der Jahresgrenze Platz hat (Monatsgrenze des Vorjahres × Monate mit laufendem Entgelt, abzüglich des Vorjahres-Entgelts).
- Vereinfachungen: Minijob: Pauschalen und Umlagen auf den vollen Bezug; die Besonderheit nach Abs. 5 (bei gesetzlich Versicherten entscheidet allein die KV-Grenze über die Märzklausel) und Bezüge nach Beendigung der Beschäftigung (Abs. 2) sind nicht abgebildet; der Text wurde über Zusammenfassungen gelesen (gesetze-im-internet.de war nicht abrufbar), nicht am Wortlaut geprüft. Fehlen die Grenzen, gilt für den Bezug die Pauschale.
Erfassung durch die Praxis (gebaut, Issue #790): freiwillig über die Portal-Monatsmeldung (Feld
beteiligung.<personId>, Wertlaufend;sonstiger Bezug), vom Berater je Person gesichtet; angenommen schreibt die Fakten mit Quelleportal. Das gilt ebenso für die Kassen-/Privatleistungen (Feldleistung, Wertkasse;privat).
Datenschutz (RISK-38): kvStatus, kvZusatzbeitrag und pkvAgZuschuss sind Beschäftigtendaten der Praxis. Es gelten wie bei
den übrigen Personaldaten: Zugriff nur über die Kunde (RBAC je Kunde), Lesezugriff protokolliert (D-50), Audit PII-arm.
Aufbewahrungsfrist und Art.-9-Einordnung sind vor Produktivnutzung festzulegen (RISK-38).
Kassen-/Privatleistungen (Zufluss, MED-D-710, gebaut): Wertobjekt Leistungsmix (monat · kasse · privat, € für die ganze
Praxis, beide Beträge immer zusammen). Gespeichert als zwei Fakten je Leistungsmonat in praxis_jahreswert
(dexman.leistung.kasse, dexman.leistung.privat, perioden_typ = 'monat', Quelle berater); Eingabe in der Ist-Tabelle
("Davon Kasse" / "Davon Privat"). Abgeleitet, nicht gespeichert (G-2): der Kassenanteil des Monats kasse ÷ (kasse + privat);
fehlt der Monat, gilt kassenanteil der Praxis. Die Umsätze je Person bleiben die Basis der Rechnung; der Mix liefert nur den
Anteil (Plausibilitäts-Hinweis leistung_abweichung, wenn die Summe um mehr als 1 % von den Behandler-Umsätzen abweicht).
Bestand unverändert: kassenanteil, kassenVersatzMonate (Vorgabe 6), privatVersatzMonate (Vorgabe 1) je Praxis.
Annahmen der Auswertung (Zahlungsannahmen, nicht gespeichert): Bezugsbasis leistung | zufluss und Verzug der Kasse
(0–12 Monate, einheitlich für alle Kassenleistungen), per Radio-Button direkt bei den Auswertungen (Kompass: Liquiditätsvorschau,
Klassisch: Monatsübersicht). Fehlt die Wahl, gilt die Praxis-Einstellung (erloesModus, kassenVersatzMonate). Regel für den
Zahlungseingang des Monats i: Kassenanteil(i − Verzug Kasse) × Umsatz(i − Verzug Kasse) + (1 − Kassenanteil(i − Verzug Privat)) × Umsatz(i − Verzug Privat). Umsatzbeteiligung folgt derselben Bezugsbasis (Basis = Zahlungseingang der Person). Der gespeicherte
Monat einer Beteiligung bleibt unverändert (Zuflussmonat, MED-D-709); die Wahl ändert nur die Auswertung.
3.3 Einbettung (Mermaid)
Hinweis (MED-D-195):
Mandant.ibanPrivat/Praxis.ibanbleiben 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.).
3.4 Feld / FormularSchema — kanonisches Formular-Feld-Modell (MED-D-294/295, G1)
Das eine Modell eines Formularfeldes (Onboarding-Greenfield-Neubau, docs/architektur/Onboarding-Neubau.md).
Es löst die drei bis dato divergenten Feld-Modelle ab — Onboarding-StammdatenFeld (pflicht:bool),
Ausfüll-KundenFeld (wichtigkeit), Fragebogen-KatalogFeld (klasse) — und ist damit die kanonische Form
für UI-Feld-Engine, API/DTO und (ab G2) den FormularVorgang.
| Feld | Typ | Bedeutung |
|---|---|---|
schluessel | string | stabiler Datenmodell-Key |
label | string | sprechendes Label (G-3) |
art | ValidierungsArt | 'jn' | 'auswahl' | Anzeige + weiche Validierung (Freitext nie abgelehnt); erweitert feld-typ.ts#ValidierungsArt |
wichtigkeit | pflicht | wichtig | optional | eine Skala (subsumiert pflicht:bool UND klasse) |
markierbar | boolean | „weiß nicht"/„nachgeliefert" erlaubt (DM-9) |
optionen? | {wert,label}[] | nur bei art='auswahl' |
strukturTyp? | 'oeffnungszeiten' | zusammengesetztes Sonderfeld |
abschnitt | string | Gruppierung → Stepper-Schritt und Abschnitts-Freigabe (N2, MED-D-292) |
rolle? | kunde | berater | wer beantwortet das Feld (Default kunde; MED-D-703, S1) |
sichtbarWenn? | Bedingung | Feld nur sichtbar/Pflicht, wenn erfüllt: ist · gesetzt · alle · eine (S1) |
gruppe? | string | Wiederholungsgruppe (FormularSchema.gruppen); Antworten als gruppe.<i>.<feld> (S1) |
attribut? | string | Weltmodell-Attribut (WELTMODELL_ATTRIBUTE), das das Feld beantwortet — Grundlage der Delta-Abfrage (jede Angabe nur einmal fragen; MED-D-703, S3) |
berechnet? | Ausdruck | abgeleitetes Feld (Zahl · Feldverweis · Summe · Produkt · Differenz · Rundung · Fallunterscheidung · Gruppensumme), nie erfasst/persistiert (G-2, S1) |
Bedingung/Ausdruck/Gruppe leben im geteilten shared/feld-kern/ (Worker und Browser, Muster dexman-kern).
FormularSchema bündelt typ (onboarding \| ausfuellformular \| fragebogen \| lead) · schluessel
(schemaRef) · titel · abschnitte[] · geordnete felder[]. Fundort: server/src/domain/feld.ts
(rein: Typen + Helfer pflichtFelder/markierbareFelder/felderJeAbschnitt/schemaVerstoesse);
Überführung der Alt-Kataloge in server/src/domain/formular-schema.ts (Adapter onboardingSchema/
ausfuellSchema/fragebogenSchema, verhaltensneutral, test-abgesichert). Wichtigkeits-Kollaps:
Onboarding pflicht→pflicht/sonst optional; Fragebogen essenziell→pflicht · wichtig→wichtig · nice_to_have→optional; Ausfüll-wichtigkeit 1:1. Ab G5 sind die drei Alt-Modelle abgelöst.
3.5 Attribut-Schlüsselraum für Fragenkataloge (MED-D-703, geplant)
Fragenkataloge (docs/architektur/Onboarding-Fragenkataloge.md) und Fremdformular-Mapping nutzen einen
Schlüsselraum: den Katalog WELTMODELL_ATTRIBUTE (server/src/domain/fremdformular.ts, Punkt-Schreibweise
gruppe.name). Heute stehen daneben getrennte Räume (STAMMDATEN_FELDER camelCase, STAMM_ZIELE, Ausfüll-
KundenFeld) — sie werden an den Weltmodell-Schlüssel angebunden, nicht dupliziert (Backlog §4).
Neue Schlüssel (Slice S0b; person.familienstand, steuer.* und steuerberater.* sind seit S0b-1 in WELTMODELL_ATTRIBUTE gebaut, praxis.steuerberater.* seit S0b-2; kind.* folgt mit der Wiederholungsgruppen-Unterstützung der Feld-Engine, S1):
| Schlüssel | Bedeutung | Quelle |
|---|---|---|
person.familienstand | Familienstand (Aufzählung, s. o.) | Mandant |
steuer.nummer · steuer.id | Steuernummer · Steuer-ID | Mandant |
bank.apobank_stammnummer | apoBank-Stammnummer (optional, MED-D-779) | Mandant |
steuerberater.name · .kanzlei · .email · .telefon | Kontaktsteuerberater privat | Mandant |
praxis.steuerberater.name · .kanzlei · .email · .telefon | Kontaktsteuerberater je Praxis | Praxis |
kind.vorname · kind.geburtsmonat | Wiederholungsgruppe Kinder (nur Vorname + Geburtsmonat/-jahr) | Kind (1:n) |
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 |
|---|---|---|
kundendatenbogen_v1 | ✅ MED-D-86 (0.59.1) | 3 Felder strasse/plz/ort → verlustfreie Übernahme (kein anschrift→strasse-Parser mehr) |
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) |
Getrennte Schlüsselräume (WELTMODELL_ATTRIBUTE · STAMMDATEN_FELDER · STAMM_ZIELE · Ausfüll-KundenFeld) | 🟡 offen (MED-D-703) | an den Weltmodell-Schlüssel anbinden (Slice S0b/S2), kein Big-Bang |
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)
- Neues Feld/Entität → zuerst ins Dictionary. Struktur (Felder/Typen/Regeln) hier festlegen, dann in Code (model/schema/DTO) + UI umsetzen.
- Wiederverwenden, nicht neu erfinden. Ein Wertobjekt wird mit identischen Feldnamen eingebettet.
- Je PR mitführen (wie Feature-Liste): neue/erweiterte Entitäten & Wertobjekte hier eintragen; eine angeglichene Divergenz aus §4 streichen.
- Abgeleitete Sichten (Anzeige-Adresse, Anzeigename) bleiben View-Logik, nie doppelt gespeichert (G-2).
- 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.mdG-8. Entscheidung:docs/betrieb/Decision-Log.mdMED-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.