Maximilian Stubhan
b87c8ad64c
The database moved to a container of our own; the platform is gone. This takes out what was left of it — and, where the leftovers were load bearing, moves rather than deletes. Moved, not deleted: supabase/migrations/ -> db/migrations/ the schema's source of truth supabase/build-org.ts -> scripts/build-org.ts lib/supabase/types.ts -> lib/types.ts 52 import sites repointed The bookkeeping needed care. It lived in `supabase_migrations.schema_migrations`, and simply renaming the schema would have left the runner facing an empty table: it would have called all 67 migrations pending and replayed them against a database that is long since current. So the runner now creates `migrationen.schema_migrations` and, once, copies the old rows across — guarded so a second run does nothing and a fresh database skips it entirely. Only then does migration 20260907100000 drop the old schema. Deleted: the CLI config, the seed, the historical schema/function dumps (nothing read them), scripts/umzug-von-supabase.sh (the move is done), and both Supabase packages plus the CLI. Nothing in the application imported them — the build now succeeds with no environment variables at all, which is the proof. Integration tests: six of them signed in through Supabase Auth and asserted against the anon key and the service role. That model is gone, so the tests were not portable — they are deleted. session-context and employee-status-filter already ran on pg and are untouched; om-reporting is ported to a direct connection because it guards a real risk (the reporting line rule exists twice, once in SQL and once in TypeScript). CI: the integration job started a Supabase stack. It now runs a postgres service, applies deploy/db-init and every migration to an empty database — that was the valuable part, and it still holds — then checks that a second run is a no-op, which is what proves the bookkeeping works. Docs: security-review.md audited a service-role key, a cookie adapter and auth.users, none of which exist. Restating findings about removed components would suggest today's system had been reviewed; it has not. It now records what was removed and says a fresh review is due. data-model.md was already marked obsolete and described the pre-OM schema; azure-migration.md was a plan for a route not taken. Both deleted. Verified: npm ci, typecheck, lint, 445 tests, build — all clean without the packages. Integration tests skip cleanly with no database. Migration SQL and the runner are reviewed but NOT executed: no Docker here, and the old instance no longer resolves. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
164 lines
7.5 KiB
Markdown
164 lines
7.5 KiB
Markdown
# Alpenwerk HR Master
|
|
|
|
Interne HR-Stammdatenverwaltung: Mitarbeiter:innen, Organisationsstruktur
|
|
(Bereich/Abteilung/Team), Planstellen, Neueinstellungen, Versetzungen/
|
|
Beförderungen/Karenz, Reorganisationen und der zugehörige Audit-Trail.
|
|
|
|
## Zweck
|
|
|
|
Die App ersetzt Excel-basierte HR-Stammdatenpflege durch ein Werkzeug mit
|
|
verbindlichen Regeln (z. B. wirksame Daten statt sofortiger Änderungen,
|
|
eindeutige Positions-/Org-Nummern, verpflichtende Historie) und einem
|
|
lückenlosen Audit-Trail für jede Änderung.
|
|
|
|
**Alle Mitarbeiterdaten in diesem System sind vertraulich** — Stammdaten,
|
|
Verträge, Sozialversicherungsnummern, Angehörige und Audit-Daten. Zugriff ist
|
|
auf explizit aktivierte HR-Benutzer:innen beschränkt (siehe
|
|
[Sicherheitsprinzipien](#sicherheitsprinzipien)).
|
|
|
|
## Tech-Stack
|
|
|
|
- Next.js 16 (App Router) — **Achtung:** Next.js 16 hat Breaking Changes
|
|
gegenüber älteren Versionen (u. a. `proxy.ts` statt `middleware.ts`).
|
|
Vor Änderungen an Framework-nahen Dateien die lokalen Docs unter
|
|
`node_modules/next/dist/docs/` konsultieren; sie sind maßgeblich, ältere
|
|
Anleitungen im Netz beschreiben teils überholte APIs.
|
|
- React 19, TypeScript
|
|
- PostgreSQL, angesprochen über Kysely und `pg` — die Datenhaltung liegt in
|
|
der Datenbank, nicht im Next.js-Prozess. Der Zugriff läuft ausschliesslich
|
|
über `withUser()` (`lib/db/`), das den Sitzungskontext setzt.
|
|
- Auth.js gegen Microsoft Entra ID — keine eigenen Passwörter.
|
|
- Tailwind CSS v4
|
|
- Vitest — Unit- (Node), Komponenten- (jsdom) und Integrationstests
|
|
(gegen eine erreichbare Datenbank)
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
npm install
|
|
cp .env.example .env.local # Werte eintragen, siehe unten
|
|
npm run dev
|
|
```
|
|
|
|
Für eine lokale Datenbank genügt der Container aus `docker-compose.yml`:
|
|
|
|
```bash
|
|
docker compose up -d db
|
|
docker compose run --rm migrate # spielt db/migrations/ ein
|
|
```
|
|
|
|
Danach zeigt `DATABASE_URL` in `.env.local` auf diese Datenbank.
|
|
|
|
## Umgebungsvariablen
|
|
|
|
Siehe [`.env.example`](.env.example) für die vollständige, kommentierte
|
|
Liste. Kurzfassung:
|
|
|
|
| Variable | Sichtbarkeit | Zweck |
|
|
|---|---|---|
|
|
| `DATABASE_URL` | Nur Server | PostgreSQL-Verbindung. Die Rolle darf **kein** `BYPASSRLS` haben |
|
|
| `DATABASE_SSL` | Nur Server | `false` für lokal/CI ohne TLS |
|
|
| `AUTH_SECRET` | Nur Server | Signiert und verschlüsselt das Sitzungscookie |
|
|
| `AUTH_MICROSOFT_ENTRA_ID_ID` | Nur Server | Anwendungs-ID der Entra-Registrierung |
|
|
| `AUTH_MICROSOFT_ENTRA_ID_SECRET` | Nur Server | Client-Geheimnis dazu |
|
|
| `AUTH_MICROSOFT_ENTRA_ID_ISSUER` | Nur Server | Aussteller mit Mandanten-ID — nicht `common` |
|
|
| `CRON_SECRET` | Nur Server | Schützt `/api/cron/apply-pending-changes` |
|
|
|
|
**Es gibt keine `NEXT_PUBLIC_*`-Variablen mehr.** Nichts wird in das
|
|
Browser-Bundle eingebacken, weil der Browser mit nichts ausser der Anwendung
|
|
selbst spricht. Ein Docker-Abbild ist damit umgebungsneutral: einmal gebaut,
|
|
überall dasselbe — vorher brauchte jede Umgebung ihr eigenes.
|
|
|
|
## Scripts
|
|
|
|
| Befehl | Zweck |
|
|
|---|---|
|
|
| `npm run dev` | Lokaler Dev-Server |
|
|
| `npm run build` | Produktions-Build |
|
|
| `npm run start` | Produktions-Server (nach `build`) |
|
|
| `npm run lint` | ESLint (`eslint-config-next`, Flat Config) |
|
|
| `npm run typecheck` | `tsc --noEmit` |
|
|
| `npm run test` | Vitest, Unit-Tests (`tests/unit/**`) |
|
|
| `npm run test:integration` | Vitest gegen eine erreichbare Datenbank; überspringt sich ohne `DATABASE_URL` |
|
|
| `npm run test:e2e` | Playwright |
|
|
| `npm run migrate` | Ausstehende Migrationen einspielen (`--dry-run`, `--baseline`) |
|
|
| `npm run check` | lint + typecheck + test + build in Folge |
|
|
|
|
## Sicherheitsprinzipien
|
|
|
|
- **RLS ist die eigentliche Schranke, nicht die UI.** Jede Tabelle hat Row
|
|
Level Security aktiv; `proxy.ts` (App-Ebene) ist Defense-in-Depth, keine
|
|
Ersatzkontrolle.
|
|
- **Ein Rollenmodell:** `profiles.role = 'hr'` + `profiles.is_active = true`,
|
|
geprüft über die SQL-Funktion `is_hr_user()`. Kein Sub-Rollensystem —
|
|
siehe [`docs/datenkatalog.md`](docs/datenkatalog.md#zugriffsschutz).
|
|
- **Es gibt keinen privilegierten Zugang mehr.** Der Dienstschlüssel, der RLS
|
|
aushebelte, ist ersatzlos entfallen; auch der nächtliche Lauf benutzt
|
|
dieselbe Rolle ohne `BYPASSRLS`. Was ohne angemeldete Person laufen muss,
|
|
steht als `SECURITY DEFINER`-Funktion in der Datenbank und prüft dort
|
|
selbst, was es tut.
|
|
- **Jede Abfrage läuft in einer Transaktion mit gesetztem Sitzungskontext.**
|
|
Die Kysely-Instanz wird nicht exportiert — der einzige Weg an die Datenbank
|
|
ist `withUser()` (`lib/db/index.ts`), und eine ESLint-Regel verbietet den
|
|
Import von `pg` ausserhalb von `lib/db/`.
|
|
- **Audit-Log ist transaktional in der Datenbank**, nicht im App-Code: jede
|
|
mutierende SQL-Funktion schreibt ihren `audit_log`-Eintrag in derselben
|
|
Transaktion wie die Änderung selbst. Details und Prüfung siehe
|
|
[`docs/security-review.md`](docs/security-review.md).
|
|
- **Historie ist append-only** (`employee_history`, `audit_log`) — RLS
|
|
erlaubt kein `update`/`delete`. Korrekturen sind kompensierende Einträge.
|
|
|
|
## Cron-Konfiguration
|
|
|
|
`/api/cron/apply-pending-changes` wendet wirksam gewordene, zukunftsdatierte
|
|
Änderungen an (`pending_org_changes` → `apply_due_pending_changes()`).
|
|
|
|
- Den Zeitplan hält der `cron`-Container aus `docker-compose.yml`: täglich
|
|
03:00 Uhr, mit `Authorization: Bearer <CRON_SECRET>`.
|
|
- Fehlt `CRON_SECRET` oder stimmt der Header nicht, antwortet die Route mit
|
|
`401` (nicht `500` — bewusst, siehe `tests/unit/security.test.ts`).
|
|
|
|
## Datenbank
|
|
|
|
- Schema-Quelle der Wahrheit: `db/migrations/`. Menschlich lesbare Fassung,
|
|
aus der laufenden Datenbank erzeugt:
|
|
[`docs/datenkatalog.md`](docs/datenkatalog.md).
|
|
- Migrationen einspielen: `npm run migrate`. Der Läufer wendet nur die
|
|
fehlenden Dateien an, jede in ihrer eigenen Transaktion, und führt darüber
|
|
Buch in `migrationen.schema_migrations`.
|
|
- `lib/types.ts` wird von Hand gepflegt. `npm run types:check` hält sie
|
|
Spalte für Spalte gegen die Migrationen.
|
|
|
|
## Testing
|
|
|
|
- `npm run test` — schnell, keine externen Abhängigkeiten, läuft in CI.
|
|
- `npm run test:integration` — braucht eine erreichbare Datenbank
|
|
(`DATABASE_URL`). Geprüft werden Regeln, die es zweimal gibt: einmal als
|
|
SQL, einmal als TypeScript. Ohne `DATABASE_URL` überspringen sich die
|
|
Dateien, statt mit einem Verbindungsfehler abzubrechen.
|
|
- `npm run test:e2e` — Playwright gegen einen laufenden Dev-/Preview-Server.
|
|
|
|
## Deployment
|
|
|
|
Siehe [`DEPLOYMENT.md`](DEPLOYMENT.md): Anwendung und Datenbank als Container,
|
|
Reverse-Proxy/TLS, der nächtliche Lauf, Migrationen und Updates.
|
|
|
|
## Known TODOs vor Produktivbetrieb
|
|
|
|
- **Content-Security-Policy läuft im Nur-Bericht-Modus** (`next.config.ts`).
|
|
Erzwungen wird sie erst, wenn die Meldungen sauber sind — eine geratene,
|
|
erzwungene Richtlinie blendet die Anwendung für alle aus.
|
|
- **Seed für die Integrationstests fehlt.** Er lag in der abgelösten
|
|
Umgebung. Zwei der drei Integrationstests vergleichen Regeln über den
|
|
gesamten Bestand und brauchen dafür Daten; bis der Seed nachgezogen ist,
|
|
laufen sie nur gegen eine bereits befüllte Datenbank, nicht in der CI.
|
|
- **Sicherheitsprüfung des heutigen Aufbaus steht aus** — siehe
|
|
[`docs/security-review.md`](docs/security-review.md).
|
|
- **Bildschirmfotos unter `.scratch_shots/`** stammen aus einer früheren
|
|
Handprüfung. Sie sind über `.gitignore` ausgeschlossen; vor der Übergabe
|
|
durchsehen und löschen.
|
|
- **Kein granulareres Rollenmodell** — aktuell HR-only (alles-oder-nichts).
|
|
Falls z. B. eine reine Lese-Rolle künftig gebraucht wird, gehört die
|
|
Erweiterung in eine neue Migration (`is_hr_user()`/RLS-Policies), nicht in
|
|
App-seitigen Code.
|