alpenwerk-hr/docs/datenkatalog.md

# Datenkatalog

Jede Tabelle, jede Spalte, jede Regel — ausgelesen aus der laufenden
Datenbank am **13.08.2026**.

Die Wahrheit steht in `db/migrations/` (68 Dateien). Dieses Dokument
ist eine lesbare Fassung davon und wurde nicht abgetippt, sondern aus dem
Systemkatalog erzeugt: Spaltentypen, Vorgabewerte, Schlüssel und
Prüfbedingungen stammen aus `information_schema` und `pg_catalog`. Wo unten
eine Regel in Worten steht, steht daneben, aus welcher `CHECK`-Bedingung sie
kommt.

| | |
|---|---|
| Tabellen | 15 |
| Spalten | 142 |
| Aufzählungstypen | 10 |
| Sichten (Views) | 0 |
| Eigene SQL-Funktionen | 38 (plus 31 aus der Erweiterung `pg_trgm`) |
| RLS-Policies | 21, auf jeder Tabelle mindestens eine |

---

## Wie das Modell gedacht ist

Drei Entscheidungen erklären fast jede Eigenheit weiter unten.

**Person und Planstelle sind zwei Dinge.** Eine Person (`employees`) hat
keine Spalte „Abteilung". Sie sitzt auf einer Planstelle (`om_positions`),
und die Planstelle hängt in einer Organisationseinheit (`org_units`). Wo
jemand arbeitet, ist damit nicht ein Feld, sondern ein Weg über zwei
Tabellen. Der Preis ist ein Join; dafür lässt sich eine Planstelle
ausschreiben, bevor jemand darauf sitzt, und eine Person wechseln, ohne dass
die Stelle verschwindet.

**Zuordnungen haben ein Von und ein Bis.** `position_assignments`,
`om_positions` und `org_units` tragen alle `valid_from` / `valid_to` als
halboffenes Intervall: `valid_from` gehört dazu, `valid_to` nicht mehr. Eine
Zuordnung, die heute endet, hat `valid_to = heute` und gilt heute schon nicht
mehr. Deshalb kann jede Auswertung einen Stichtag haben, auch einen in der
Vergangenheit, und deshalb ist eine Versetzung zum Ersten des nächsten Monats
kein Termin im Kalender, sondern eine Zeile, die erst dann greift.

**Geschichte wird geschrieben, nicht überschrieben.** `employee_history` und
`audit_log` haben keine Update- und keine Delete-Policy — RLS lässt nur
`select` und `insert` zu. Eine Korrektur ist ein neuer Eintrag, nie eine
geänderte Zeile.

Zwei Ausnahmen gibt es, und sie sind eng: `delete_history_entry` nimmt eine
irrtümlich erfasste Stammdaten- oder Vertragsänderung samt ihrer Wirkung
zurück, `update_history_entry` berichtigt Wert und Datum einer solchen. Die
Policies bleiben dabei unangetastet — beide laufen als `SECURITY DEFINER` an
ihnen vorbei und prüfen die Berechtigung selbst. Das Protokoll behält den
Vorgang, dort verschwindet nichts.

Die Namen der OM-Tabellen sind nicht zufällig gewählt: `org_units` ist der
SAP-Objekttyp O, `jobs` ist C, `om_positions` ist S, `employees` ist P, und
`position_assignments` ist die Verknüpfung A008 („Inhaber ist"). Das Flag
`is_chief` entspricht A012 („ist Leiter von"). Wer das Modell aus SAP kennt,
findet sich wieder; wer nicht, verliert nichts.

```
org_units ──parent_id──┐          (rekursiv: Gesellschaft › Bereich › Abteilung › Team)
    │                  │
    └──────────────────┘
    ▲
    │ org_unit_id
om_positions ──job_id──► jobs
    ▲
    │ position_id
position_assignments ──employee_id──► employees ──location_id──► locations
                                          ▲
                                          ├── employee_history      (Ereignisse)
                                          ├── employee_dependents   (Angehörige)
                                          ├── employee_notes        (HR-Notizen)
                                          ├── pending_org_changes   (wirkt später)
                                          └── audit_log             (wer/wann/was)

app_users ──1:1──► profiles        (Anmeldung ist nicht Berechtigung)
```

---

## Personen

### `employees` — 46 Spalten

Die Person selbst: Stammdaten, Vertrag, Status. **Nicht** die Organisation —
die kommt über die Planstelle.

| Spalte | Typ | Null | Vorgabe | Bedeutung |
|---|---|---|---|---|
| `id` | uuid | – | `gen_random_uuid()` | Schlüssel |
| `personnel_number` | int4 | – | – | **Eindeutig.** Wird eingegeben, nicht vergeben — sie muss mit Loga/Interflex übereinstimmen |
| `first_name`, `last_name` | text | – | – | |
| `gender` | `gender_type` | – | – | `m` / `w` |
| `birth_date` | date | – | – | |
| `sv_nummer` | text | ja | – | Österreichische SV-Nummer; gegen Prüfziffer *und* Geburtsdatum geprüft (Trigger `fn_validate_employee_svnr`) |
| `nationality` | text | – | `'Österreich'` | |
| `address`, `postal_code`, `city`, `address_country` | text | ja | – | Wohnanschrift |
| `email` | text | ja | – | **Private** E-Mail. Freiwillig, aber eindeutig, wenn angegeben |
| `phone` | text | ja | – | **Private** Telefonnummer. Freiwillig |
| `job_title` | text | – | – | Anzeigetitel. Der verbindliche Titel steht am Job der Planstelle |
| `location_id` | uuid | – | – | → `locations` |
| `employment_type` | `employment_type` | – | `Vollzeit` | |
| `weekly_hours` | numeric | – | `38.5` | An `employment_type` gekoppelt, siehe Regeln |
| `contract_type` | `contract_type` | – | `unbefristet` | |
| `contract_end_date` | date | ja | – | Pflicht bei `befristet` |
| `worker_type` | `worker_type` | – | `Angestellte:r` | |
| `collective_agreement` | `collective_agreement` | – | `Handel` | |
| `paygrade` | `paygrade_type` | – | `-` | Hay-Grade; der Spaltenname ist geblieben |
| `source` | `source_type` | – | `Extern` | Intern besetzt oder extern geholt |
| `work_days` | text[] | – | `{Mo,Di,Mi,Do,Fr}` | In Klickreihenfolge gespeichert, nicht sortiert |
| `status` | `employment_status` | – | `Aktiv` | Gilt für **heute**; für einen Stichtag wird er zurückgerechnet |
| `entry_date` | date | – | – | |
| `exit_date`, `exit_reason` | date/text | ja | – | |
| `karenz_start_date`, `karenz_return_date` | date | ja | – | Laufende Langzeitabwesenheit |
| `absence_type` | text | ja | – | Art der Abwesenheit; wird bei der Rückkehr geleert. 13 erlaubte Werte |
| `is_betriebsrat`, `is_laterale_fuehrung`, `is_c_level` | bool | – | `false` | |
| `has_dienstwagen` | bool | – | `false` | |
| `dienstwagen_art` | text | ja | – | `Verbrenner` / `Elektro`; nur zusammen mit `has_dienstwagen` |
| `emergency_contact_name`, `_phone`, `_relation` | text | ja | – | Daten einer dritten Person, nur für den Notfall erhoben |
| `title_prefix`, `title_suffix` | text[] | – | `{}` | Akademische Grade, gegen feste Listen geprüft |
| `avatar_color` | text | ja | – | Darstellung |
| `monthly_salary_gross` | numeric | ja | – | **Stillgelegt.** Gehalt ist ausserhalb des Funktionsumfangs; keine Funktion liest oder schreibt die Spalte mehr. Steht nur noch da, falls Altdaten drin sind |
| `created_at`, `updated_at` | timestamptz | – | `now()` | `updated_at` per Trigger |

**Regeln, die die Datenbank durchsetzt:**

- *Vollzeit heisst 38,5 Stunden; Teilzeit heisst mehr als 0 und weniger als
  38,5.* Ein Vollzeitvertrag mit 30 Stunden lässt sich nicht speichern
  (`chk_weekly_hours`).
- *Befristet ohne Enddatum gibt es nicht* (`chk_befristet_end`).
- *Austritt nicht vor Eintritt*, *Rückkehr nicht vor Eintritt*
  (`chk_exit_after_entry`, `chk_karenz_return_after_entry`).
- *Dienstwagen und Antriebsart gehören zusammen* — beides oder keins
  (`chk_dienstwagen_art`). Die Bedingung nennt den Fall ohne Wagen
  ausdrücklich, weil `art in (…)` bei `null` weder wahr noch falsch ergibt
  und die Regel sonst genau das durchgelassen hätte, was sie verhindern soll.
- *Notfallkontakt: Name und Telefon gemeinsam oder gar nicht*, und keiner der
  beiden leer (`chk_emergency_contact`).
- *Arbeitstage nur aus Mo–So und mindestens einer* (`chk_work_days_valid`).
- *Titel nur aus den bekannten Listen* — 10 vorangestellte, 12 nachgestellte
  (`chk_title_prefix_valid`, `chk_title_suffix_valid`).
- *Abwesenheitsart nur aus den 13 bekannten* (`chk_absence_type`).

### `employee_history` — die Zeitleiste

Eine Zeile je Ereignis: `employee_id`, `event_date`, `event_type`
(Aufzählung, 11 Werte), `description`. Ein Trigger verhindert Ereignisse vor
dem Eintrittsdatum (`fn_check_history_not_before_entry`). Nur einfügen und
lesen — kein Ändern, kein Löschen.

### `employee_dependents` — Angehörige

`first_name`, `last_name`, `relationship` (Ehepartner:in / Lebenspartner:in /
Kind / Sonstige), `birth_date`, optional `sv_nummer`. Ändern heisst löschen
und neu anlegen; ein In-place-Update gibt es nicht. Beim Löschen der Person
verschwinden sie mit (`on delete cascade`).

### `employee_notes` — HR-Notizen

`category` (Allgemein / Vertraulich / Personalgespräch / Wiedervorlage /
Lob / Anerkennung), `note_text`, optional `due_date` für die Wiedervorlage,
dazu `done` / `done_at` / `done_by`.

Bewusst **nicht** auf die verfassende Person eingeschränkt: jede aktive
HR-Person sieht jede offene Notiz. „Meine Notizen" ist ein gemeinsames
Postfach, kein privates.

---

## Organisation

### `org_units` — Einheiten (SAP-Objekttyp O)

`org_number` (eindeutig), `name`, `parent_id` (rekursiv), `unit_type`
(Gesellschaft / Bereich / Abteilung / Team), `valid_from` / `valid_to`.

`unit_type` ist ein Etikett für die Anzeige, keine Struktur — die Struktur
ist `parent_id`. Eine Abteilung unter einer Abteilung wäre erlaubt. Was die
Datenbank verhindert, ist nur, dass eine Einheit ihr eigenes Elternteil wird
(`chk_org_unit_not_own_parent`); tiefere Zyklen fängt sie nicht ab.

### `jobs` — Tätigkeiten (Objekttyp C)

`code` und `title`, beide eindeutig. Ein schlanker Katalog: die Planstelle
verweist darauf, statt den Titel abzuschreiben.

### `om_positions` — Planstellen (Objekttyp S)

`position_number` (eindeutig), `org_unit_id`, `job_id`, `is_chief`,
`valid_from` / `valid_to`.

Die Nummern haben die Form `6` + sieben Ziffern, weil
`next_position_number()` sie so erzeugt — erzwungen wird das Format aber
nicht: an der Spalte hängt nur Eindeutigkeit. Wer von aussen eine Nummer
einträgt, kann eine andere Form wählen, und die Zählfunktion übergeht sie
dann (sie sucht ihr Maximum nur unter `^6[0-9]{7}$`).

`is_chief` markiert die Leitungsstelle einer Einheit — daraus entsteht die
Führungslinie, nicht aus einem Feld „Vorgesetzte:r" an der Person. Eine
Planstelle lässt sich nur besetzen, solange sie gültig ist.

### `position_assignments` — Besetzungen (Verknüpfung A008)

`position_id`, `employee_id`, `valid_from` / `valid_to`. Diese Tabelle
beantwortet „wer sass wann wo" — die einzige Stelle, an der das steht.

### `locations` — Standorte

`name` (eindeutig) und `country`, beschränkt auf Österreich, Deutschland,
Tschechien und Slowenien.

---

## Ablauf und Nachweis

### `pending_org_changes` — was später wirkt

`change_type` (transfer / promotion / karenz_start / karenz_return /
contract_change / reorg / dependent_add / dependent_remove),
`effective_date`, `payload` (JSONB), `status` (pending / applied /
cancelled).

Der Weg ist `pending` → `applied`. Die Auswahl filtert immer auf `pending`,
ein zweiter Lauf wirkt also nicht doppelt. Verarbeitet wird täglich von
`apply_due_pending_changes()`.

### `audit_log` — wer, wann, was, an wem

`occurred_at`, `actor_user_id` + `actor_name`, `action`, `target_label`,
`target_employee_id`, `details`, und `changes` als JSONB in der Form
`[{feld, vorher, nachher}]` — daher die aufklappbare Detailansicht in der
Oberfläche. Bei Einträgen von vor der entsprechenden Migration ist `changes`
null.

Geschrieben wird ausschliesslich aus den SQL-Funktionen heraus, in derselben
Transaktion wie die Änderung selbst. Das ist der Punkt: ein fehlgeschlagener
Log-Eintrag lässt die ganze Änderung scheitern, statt still eine Änderung
ohne Nachweis zu hinterlassen. Einen Helfer im Anwendungscode gibt es nicht
und sollte es nicht geben — das wäre eine zweite, nicht atomare Quelle.

Dass `actor_name` als Text mitgeschrieben wird und nicht nur die Kennung: der
Nachweis soll lesbar bleiben, auch wenn das Benutzerkonto später verschwindet.

---

## Zugang

### `app_users`

Ersetzt `auth.users` aus der abgelösten Plattform. `external_id` ist die `oid` aus
Entra ID — **nicht** die E-Mail-Adresse, die kann sich ändern. Angelegt wird
die Zeile bei der ersten Anmeldung durch `app_upsert_user()`.

### `profiles`

Eine Zeile je Konto, gleicher Schlüssel wie `app_users`. `role` ist per
Prüfbedingung auf den einen Wert `'hr'` festgenagelt, `is_active` steht
anfangs auf `false`.

**Anmelden können heisst nichts.** Wer sich mit dem Firmenkonto anmeldet,
bekommt eine `app_users`-Zeile und kommt trotzdem an keine einzige
Personalzeile, solange `profiles.is_active` nicht gesetzt ist. Die Freigabe
ist ein bewusster zweiter Schritt.

### `hire_drafts`, `saved_reports`

Zwischenstand des Einstellungsassistenten (`payload` JSONB, `step`) und
gespeicherte Berichtskonfigurationen.

`saved_reports` gehört ganz der anlegenden Person. Bei `hire_drafts` gehen
Lesen und Schreiben seit September 2026 verschieden weit: **lesen** darf, wem
der Entwurf gehört, und wer die anlegende Person in seiner Glocke hinzugewählt
hat (`colleague_subscriptions`); **anlegen, ändern und löschen** darf nur die
anlegende Person selbst. Ein Entwurf ist unfertige Arbeit ohne Sperre und ohne
Historie — zwei Personen, die abwechselnd hineinschreiben, überschreiben
einander lautlos.

Die Anwendung liest deshalb bei `update` und `delete` die Zahl der
betroffenen Zeilen: eine Policy weist ein Schreiben nicht mit einem Fehler ab,
sie lässt es ins Leere laufen (`actions/hireDrafts.ts`).

### `colleague_subscriptions`

Wen jemand hinzugewählt hat, je eine Zeile aus `user_id` und
`author_user_id`. Die Vorgabe ist die eigene Person: **ohne** Zeile sieht man
nur die eigenen Notizen und Entwürfe, mit Zeile zusätzlich die der genannten
Person. Die Auswahl sitzt in der Glocke in der Kopfzeile und steuert beides.

Ein Abo auf sich selbst lässt `chk_kollegen_abos_nicht_selbst` nicht zu — die
eigenen Zeilen sind ohnehin immer dabei. Die Tabelle hiess bis September 2026
`note_subscriptions`, als die Auswahl nur für die Notizen galt.

---

## Aufzählungstypen

| Typ | Werte |
|---|---|
| `employment_status` | Aktiv, Karenz, Geplant, Ausgetreten |
| `employment_type` | Vollzeit, Teilzeit |
| `contract_type` | unbefristet, befristet |
| `worker_type` | Angestellte:r, Arbeiter:in, Lehrling |
| `collective_agreement` | Handel, Süßwaren |
| `paygrade_type` | -, HG09…HG19, HG19P, HG20 (Domain über text, kein Aufzählungstyp) |
| `source_type` | Intern, Extern |
| `gender_type` | m, w |
| `org_unit_type` | Gesellschaft, Bereich, Abteilung, Team |
| `history_event_type` | Eintritt, Beförderung, Versetzung, Karenz, Vertragsänderung, Stammdatenänderung, Austritt, Wiedereintritt, Reorganisation, Gehaltsanpassung, Rückkehr |

`Karenz` heisst in der Oberfläche „Langzeitabwesenheit" — der gespeicherte
Wert wurde beim Umbenennen bewusst nicht angefasst, die Beschriftung folgt
dem neuen Begriff.

Nicht als Aufzählungstyp, sondern als Prüfbedingung auf einer Textspalte
gelöst: Abwesenheitsart, Antriebsart, Verhältnis von Angehörigen,
Notizkategorie, Änderungsart, Land. Der praktische Unterschied: eine
Prüfbedingung lässt sich in einer Migration ändern, ein Aufzählungstyp nur
erweitern.

---

## Die SQL-Schnittstelle

Änderungen laufen nicht über `insert`/`update` aus der Anwendung, sondern
über Funktionen. Jede schreibt ihren Nachweis und ihre Historie in derselben
Transaktion mit.

**Personal:** `hire_employee`, `rehire_employee`, `terminate_employee`,
`transfer_employee`, `promote_employee`, `change_employee_data`,
`start_karenz`, `adjust_karenz_return`, `record_karenz_return`

**Planstellen:** `create_position`, `update_position`, `delete_position`,
`next_position_number`

**Historie:** `delete_history_entry` nimmt eine irrtümliche Stammdaten- oder
Vertragsänderung zurück: setzt je Feld auf den Wert davor, sofern kein
späterer Eintrag dasselbe Feld angefasst hat, und entfernt die Zeile.
`update_history_entry` berichtigt stattdessen Wert und Datum — das „vorher"
bleibt unangetastet, und der heutige Stand wird je Feld aus dem jüngsten
Eintrag abgeleitet, der es trägt. Beide sind der einzige Weg an den fehlenden
`update`- und `delete`-Policies vorbei, deshalb `SECURITY DEFINER` und mit
`require_hr_admin()` davor. `app_feld_karte` liefert beiden die Zuordnung
Beschriftung → Spalte und Typ.

**Umfeld:** `add_employee_dependent`, `delete_employee_dependent`,
`add_employee_note`, `complete_employee_note`

**Auswertung:** `om_reporting_lines(p_as_of)` — löst zum Stichtag auf, wer an
wen berichtet, samt Vertretung bei Abwesenheit (`acting_manager_id` neben
`formal_manager_id`)

**Zugang und Nachweis:** `is_hr_user`, `app_current_user_id`,
`app_upsert_user`, `current_actor_name`, `app_aenderung`,
`app_aenderungsfelder`

**Automatik:** `apply_due_pending_changes` (täglich), `rls_auto_enable`
(hängt am Ereignis-Trigger `ensure_rls`: neue Tabellen bekommen sofort RLS),
die vier `fn_*`-Trigger, `is_valid_svnr`

Sechs Funktionen laufen als `SECURITY DEFINER`, also mit den Rechten ihrer
Eigentümerin statt der aufrufenden Person: `is_hr_user`,
`app_current_user_id`, `app_upsert_user`, `apply_due_pending_changes`,
`delete_history_entry` und `update_history_entry`. Die ersten drei müssen es
sein, weil sie sonst gegen dieselben Policies liefen, die sie gerade auswerten
sollen — eine Rekursion. Die vierte läuft ohne angemeldete Person, es gibt ja
nur den Zeitplan. Die letzten beiden müssen an `employee_history` schreiben,
wo es absichtlich weder eine `update`- noch eine `delete`-Policy gibt; beide
prüfen die Berechtigung deshalb selbst, in ihrer ersten Zeile.

**Der Türsteher:** `require_hr_admin()` steht am Anfang von **16**
Funktionen — jeder ändernden. Es wirft, wenn `is_hr_user()` falsch ist, und
liefert damit eine lesbare Meldung statt einer nackten RLS-Verletzung. Der
Name täuscht: ein Admin-Rollenmodell gibt es nicht, `is_hr_admin()` ruft
schlicht `is_hr_user()` auf. Die Schranke selbst bleiben die Policies.

**Übrig geblieben:** `generate_company_email` steht noch in der Datenbank,
wird aber von nichts mehr gerufen — sie stammt aus der Zeit, als eine
Firmenadresse automatisch vergeben wurde; heute ist `employees.email` die
private Adresse und freiwillig.

---

## Zugriffsschutz

Auf **jeder** der 15 Tabellen ist Row Level Security aktiv, zusammen 21
Policies. Fast alle prüfen dasselbe: `is_hr_user()` — also `profiles.role =
'hr'` **und** `is_active`. Nachgereicht wird das nicht: der Ereignis-Trigger
`ensure_rls` schaltet RLS bei jeder neu angelegten Tabelle sofort ein.

Die Prüfung hängt an einer Sitzungsvariablen (`app.user_id`), die
`withUser()` als erste Anweisung jeder Transaktion setzt — transaktionslokal,
damit sie nicht an der Verbindung kleben bleibt und die nächste Anfrage aus
dem Pool mit fremder Kennung läuft.

Wie wirksam das ist, zeigt sich beim Erzeugen dieses Katalogs: die Verbindung
lief ohne Sitzungskontext, und **jede** Tabelle lieferte null Zeilen — bei
vollständig vorhandenen Strukturdaten. Nicht „alles", nicht ein Fehler,
sondern nichts. Die Anwendung verbindet sich ausserdem als `alpenwerk_app` —
eine Rolle ohne `BYPASSRLS` und ohne Superuser-Recht; es gibt also keinen Weg
daran vorbei, auch nicht versehentlich.

Wo das Muster abweicht:

- `audit_log` und `employee_history` haben je zwei Policies — lesen und
  einfügen, getrennt, und kein Ändern oder Löschen. Das ist die
  Unveränderlichkeit, technisch durchgesetzt.
- `profiles` hat vier, weil dort auch die Freischaltung anderer Konten
  passiert — und eine davon lässt jede Person die *eigene* Zeile lesen, auch
  ohne Freischaltung. Sonst könnte niemand erfahren, warum er nicht
  hineinkommt.
- `app_users` ebenso: die eigene Zeile oder HR.
- `saved_reports` und `colleague_subscriptions` verlangen zusätzlich, dass
  die Zeile der anfragenden Person gehört.
- `hire_drafts` hat vier — `select`, `insert`, `update`, `delete` getrennt,
  weil das Lesen seit September 2026 weiter reicht als das Schreiben (siehe
  oben). Die alte Sammelregel `for all` musste dafür weichen: Policies
  addieren sich, eine stehengebliebene hätte die vier neuen ausgehebelt.
- `locations` trennt Lesen und Schreiben in zwei Policies, prüft aber beide
  Male dasselbe.

---

## Was hier nicht steht

**Gehalt.** `monthly_salary_gross` ist stillgelegt und wird von keiner
Funktion mehr angefasst. Gehaltsdaten leben in Loga.

**Zeitwirtschaft.** Kommen und Gehen, Urlaubskonten, Krankenstände als
Einzelfälle — das ist Interflex. Hier steht nur die dauerhafte
Langzeitabwesenheit, weil sie die Führungslinie verschiebt.

**Bewerbungen.** Eine offene Planstelle ist hier eine Planstelle ohne
Besetzung, mehr nicht.

---

*Erzeugt aus dem Systemkatalog der laufenden Datenbank. Nach strukturellen
Änderungen gehört dieses Dokument nachgezogen — am ehrlichsten, indem es neu
aus der Datenbank erzeugt wird, statt es von Hand zu pflegen.*