DDM_ENTITY_TYPE_ATTRIBUTE

Status: Entwurf · Spec-Kandidat: ja

Zweck

Beschreibt ein einzelnes Feld eines DDM_ENTITY_TYPE. Steuert Validierung, Sichtbarkeit, Sortierung, Such- und Filterfähigkeit konkreter Entitäten. Ist die zentrale Schaltstelle der Metadatensteuerung (FR-002, FR-003, FR-006).

Felder

Feld	Typ	Pflicht	Hinweise
`id`	uuid	ja	PK
`entity_type_id`	uuid	ja	FK → `DDM_ENTITY_TYPE`
`key`	text	ja	Format `^[a-z][a-z0-9_]*$`, eindeutig je `entity_type_id`
`label`	text	ja	Anzeigename
`description`	text	nein
`data_type`	`mdm.attribute_data_type`	ja	siehe Wertebereich
`required`	boolean	ja	default `false`
`unique_per_type`	boolean	ja	erzeugt im Service-Layer Eindeutigkeitsprüfung über JSONB-Pfad
`searchable`	boolean	ja	default `false`, Hinweis für Volltextindex/Expression-Index
`filterable`	boolean	ja	default `true`
`sortable`	boolean	ja	default `false`
`sort_order`	integer	ja	default `100`, steuert UI-Reihenfolge
`default_value`	jsonb	nein	typkonform interpretiert im Service
`enum_set_id`	uuid	bedingt	bei `data_type IN ('enum','multi_enum')` Pflicht
`reference_entity_type_id`	uuid	nein	optionaler Ziel-Entitätstyp einer Referenz
`relation_type_id`	uuid	bedingt	bei `data_type IN ('reference','multi_reference')` Pflicht
`min_value` / `max_value`	numeric	nein	Wertbereich für numerische Typen
`regex_pattern`	text	nein	Regex für Strings
`validation_rule`	jsonb	ja	default `'{}'`, freier Regelausdruck (Service-Layer)
`is_active`	boolean	ja	default `true`
`metadata`	jsonb	ja	default `'{}'`
`created_at` / `updated_at` / `created_by` / `updated_by`	–	–	Standardfelder

Wertebereich `data_type`

string, text, integer, decimal, boolean, date, datetime, enum, multi_enum, reference, multi_reference, money, json.

`money` — Format

Geldbetrag mit Währung. Im DDM_ENTITY.attributes-JSONB als Objekt mit zwei Pflicht-Keys abgelegt:

{ "value": "1234.56", "currency": "EUR" }

Key	Typ	Hinweise
`value`	string	Dezimalzahl als String (vermeidet Float-Rundungsfehler). Format `^-?\d+(\.\d+)?$`. Service-Layer parst auf `BigDecimal`/`numeric`. Vorzeichen erlaubt (negative Beträge z. B. für Gutschriften).
`currency`	string	ISO-4217-Code, exakt 3 Großbuchstaben (`^[A-Z]{3}$`). Beispiele: `EUR`, `USD`, `CHF`.

Konvention: keine Tausendertrennzeichen, Dezimaltrenner ist ., kein Whitespace. Skala (Anzahl Nachkommastellen) wird nicht im Datentyp festgenagelt; Service-Layer prüft gegen währungsspezifische Standardskala (z. B. EUR=2, JPY=0, BHD=3) bei validation_rule.scale = "currency" oder gegen explizit konfiguriertes validation_rule.scale = N.

min_value / max_value greifen auch für money und beziehen sich auf den value-Anteil bei gleicher currency. Cross-Currency-Vergleiche (Wechselkurse) sind explizit nicht Teil von V1 — siehe OP-39 für fx_rate-Stammtabelle.

Für reine Mengen (Wert + Einheit ohne Währung) ist money nicht geeignet; dafür kommt der separate quantity-Datentyp aus OP-39 in einer späteren Version.

Constraints

entity_type_attribute_unique_per_type_uk: (entity_type_id, key) eindeutig
entity_type_attribute_key_format_chk
entity_type_attribute_metadata_is_object_chk, …_validation_rule_is_object_chk
entity_type_attribute_min_max_chk: min_value <= max_value falls beide gesetzt
entity_type_attribute_enum_chk: bei enum/multi_enum ist enum_set_id zwingend
entity_type_attribute_reference_chk: bei reference/multi_reference ist relation_type_id zwingend

Trigger

trg_entity_type_attribute_set_updated_at setzt updated_at bei UPDATE.

Verhalten

Service-Layer leitet aus den Attributdefinitionen die Validierung des DDM_ENTITY.attributes-JSONB ab.
unique_per_type = true ist eine Service-Layer-Pflicht, nicht durch DB-Constraint abgedeckt – siehe Validierung. Bei häufiger Nutzung kann ein partielles Expression-Index erstellt werden (siehe Indizes).
searchable-Flag steuert Aufnahme in den search_vector und/oder Anlegen eines gezielten Expression-Indexes.

Required + Backfill-Pflicht

Wird ein Attribut neu mit required=true angelegt oder ein bestehendes auf required=true umgestellt, muss im selben Service-Aufruf:

default_value gesetzt sein (sonst Ablehnung mit fachlichem Fehler — kein required=true ohne Default).
Backfill aller bestehenden DDM_ENTITY-Datensätze des betroffenen entity_type_id ausgeführt werden, deren attributes den Key noch nicht enthalten oder null führen.
Pro betroffener Zeile ein AA_AUDIT_LOG-Eintrag mit action='update', actor_principal_id=<system|caller>, Begründung “backfill of newly required attribute <key>”.
Erst nach erfolgreichem Backfill wird required=true persistiert. Atomar in einer Transaktion — schlägt der Backfill teilweise fehl, rollt das gesamte Aktivieren zurück.

Service-Operation (logisch): add_required_attribute(entity_type_id, key, data_type, default_value, …). Pseudocode-Skizze:

BEGIN
  validate(default_value matches data_type)
  INSERT DDM_ENTITY_TYPE_ATTRIBUTE (..., required=false, default_value=$default)
                                  -- oder UPDATE auf bestehendes Attribut
  UPDATE mdm.DDM_ENTITY
     SET attributes = attributes || jsonb_build_object($key, $default),
         updated_at = now(), updated_by = $actor
   WHERE entity_type_id = $type
     AND deleted_at IS NULL
     AND (attributes ? $key) = false;
  -- AA_AUDIT_LOG + AA_OUTBOX_EVENT je betroffener Zeile (Bulk-Insert)
  UPDATE mdm.DDM_ENTITY_TYPE_ATTRIBUTE SET required = true WHERE id = $attr;
COMMIT

Damit ist garantiert, dass required=true nie auf einem Bestand mit fehlenden Werten landet. Bei großen Beständen ist die Operation Admin-pflichtig und sollte über einen dedizierten Endpoint (nicht das normale Attribut-Update) laufen.

Offen

Versionierung von Attributdefinitionen über DDM_ENTITY_TYPE.version hinaus.
Detailspezifikation des validation_rule-JSONB-Schemas (Operatoren, Schemarelationen).
Migration: was passiert mit bestehenden DDM_ENTITY.attributes-Werten, wenn Attributdefinitionen entfernt oder geändert werden?
Genaue Last-/Performance-Schwelle, ab wann der Backfill für required=true als Hintergrundjob (statt synchron) erfolgen muss.