Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -4,18 +4,31 @@ HiveGrid Cloud ist die Produkt-Codebase fuer HiveGrid 2.0. Das Repo basiert hist
![coverage](https://img.shields.io/badge/coverage-see%20ci-blue)
## Codeumfang
[![LOC-Verlauf](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/releases/download/loc-metrics/loc-history.svg)](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/releases/download/loc-metrics/loc-history.csv)
Der Verlauf zaehlt nicht-leere Quellcodezeilen auf dem First-Parent-Pfad von `main`. Ausgangspunkt ist der Fork-/Code-Import vom 04.06.2026; die importierte Codebasis wird deshalb als Baseline und nicht als Wachstum gewertet. Die [CSV-Rohdaten](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/releases/download/loc-metrics/loc-history.csv) werden nach jedem Push auf `main` aktualisiert. Lokal laesst sich der Graph mit `pnpm metrics:loc-history` neu erzeugen; die Regeln stehen im [Generator](scripts/metrics/loc-history.mjs).
[![Commit-Aktivität](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/releases/download/loc-metrics/commit-history.svg)](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/releases/download/loc-metrics/commit-history.csv)
Die Commit-Aktivitaet zeigt die letzten 60 Kalendertage bis zur veroeffentlichten `main`-Revision. Gezaehlt werden alle von `main` erreichbaren Commits nach Berliner Kalendertag, inklusive Merge- und Branch-Commits; Tage ohne Commit bleiben als Null-Tage sichtbar. Die [CSV-Rohdaten](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/releases/download/loc-metrics/commit-history.csv) und das SVG werden mit jedem LOC-Lauf aktualisiert. Lokal laesst sich der Graph mit `pnpm metrics:commit-history` neu erzeugen; die Regeln stehen im [Generator](scripts/metrics/commit-history.mjs).
## Zuerst lesen
- [`AGENTS.md`](AGENTS.md) ist die zentrale Arbeitsregel fuer Coding-Agents und Menschen, inklusive Ticket-Scope, Plane-Tracking, DoD, Prisma-Regeln und EU-Stack.
- [`CLAUDE.md`](CLAUDE.md) ist der Claude-Code-Einstieg und importiert `AGENTS.md`, damit Claude dieselben Projektregeln nutzt.
- [Ticket-Docs README](.planning/ticket-docs/README.md) beschreibt den Einstieg in ein Ticket.
- [Entity Model](.planning/ENTITY-MODEL.md) ist die Datenmodell-Quelle der Wahrheit, besonders fuer P6-P9.
- [Architecture Decisions](docs/ARCHITECTURE-DECISIONS.md) dokumentiert verbindliche Architekturentscheidungen.
- [Architecture Decisions](docs/ARCHITECTURE-DECISIONS.md) ist das kompakte Register mit AD-IDs,
Gründen und Status; die operativen Regeln stehen in `AGENTS.md`.
- [Agent Checklist](docs/AGENT-CHECKLIST.md) ist vor Commit und Push abzuarbeiten.
## Arbeitsmodus
Wir nutzen die `.planning/`-Struktur als Projektgedaechtnis, aber keine GSD-Slash-Commands. Gebaut wird nach Plane-Tickets und den zugehoerigen Ticket-Docs. Wenn Ticket-Doc, Entity Model und aeltere Specs widersprechen, gewinnt das Entity Model beziehungsweise `AGENTS.md`.
Gebaut wird nach Plane-Tickets und den zugehoerigen Ticket-Docs. `AGENTS.md` besitzt die repo-weiten
Architektur- und Sicherheitsregeln, das Entity Model besitzt das Datenmodell, die Ticket-Doc besitzt
Scope und DoD. Aeltere Specs sind nur historische Quellen.
Wichtig fuer neue Arbeit:
@@ -37,45 +50,79 @@ Wichtig fuer neue Arbeit:
## Lokales Setup
Voraussetzungen: Node 24.18.0 (`.nvmrc`), Docker (fuer Postgres/Redis/ClamAV) und pnpm ueber corepack.
**1. Abhaengigkeiten**
```sh
corepack enable
corepack prepare pnpm@10.33.0 --activate
corepack prepare pnpm@11.12.0 --activate
pnpm install
```
Mit Zugriff auf die geteilten Dev-Secrets:
**2. Infrastruktur starten**
```sh
pnpm env:pull
pnpm dev:services # Postgres (pgvector) :5432, Redis :6379, ClamAV :3310
pnpm dev:services:mark-local # einmalig fuer ein bereits bestehendes lokales Postgres-Volume
pnpm dev:services:down # wieder stoppen
```
Ohne Secrets fuer eine lokale Wegwerf-Umgebung:
Alle drei binden nur auf `127.0.0.1`. Zwei Dinge, die sonst Zeit kosten:
- **ClamAV** laedt beim allerersten Start rund 250 MB Signaturen, bevor er auf Verbindungen hoert. Bis `docker compose ps` ihn als `healthy` zeigt, schlaegt **jeder** Upload mit Malware-Gate fehl (Profilbild, HR-Dokumente) — der Scan ist bewusst fail-closed, ein nicht erreichbarer Scanner ist eine Ablehnung, keine Ausnahme.
- **Meilisearch** wird nur fuer die Volltextsuche gebraucht und ist deshalb nicht in `dev:services`: `docker compose up -d meilisearch`.
**3. `.env` anlegen**
Ohne Zugriff auf die geteilten Secrets — die Defaults aus `.env.example` passen genau zu `pnpm dev:services`:
```sh
cp .env.example .env
```
Danach die lokalen Werte in `.env` setzen. Mindestens relevant sind `DATABASE_URL`, `SESSION_SECRET`, `CRYPTO_SECRET`, `APP_BASE_DOMAIN`, `WEB_APP_HOST`, `ADMIN_APP_HOST`, `API_HOST`, `APP_PROTOCOL` und `JWT_SECRET`. Worker/Redis ist nur noetig, wenn Worker-Flows lokal getestet werden.
Datenbank und Seed:
Mit Zugriff auf die geteilten Dev-Secrets (SOPS+age, siehe [`secrets/README.md`](secrets/README.md)):
```sh
pnpm exec prisma migrate dev
pnpm env:pull
```
> `pnpm env:pull` ueberschreibt `.env` komplett — auch `DATABASE_URL`. Der geteilte Blob zeigt auf einen PgBouncer (`:6432`), der lokal **nicht** laeuft (`infra/pgbouncer/userlist.txt` liegt nicht im Repo). Nach `env:pull` deshalb lokal auf die direkte Verbindung stellen:
> `DATABASE_URL="postgres://hivegrid:hivegrid@127.0.0.1:5432/hivegrid"`.
Adressen konsequent als `127.0.0.1`, nicht `localhost`: auf Windows loest `localhost` zuerst nach `::1` auf, waehrend die Container nur auf IPv4 veroeffentlichen.
**4. Datenbank aufsetzen**
```sh
pnpm dev:db:roles # einmalig: RLS-Rollen anlegen
pnpm run db:migrate:deploy
pnpm seed
pnpm run permissions:sync
```
Web-App starten:
`dev:db:roles` muss **vor** der ersten Migration laufen: die RLS-Cutover-Migration vergibt Rechte an `hivegrid_app`/`hivegrid_worker`, und ohne diese Rollen bricht sie mittendrin ab und laesst die Datenbank in einem Failed-Migration-Zustand zurueck (`P3009`). Der Befehl ist ein lokaler Helfer, der Wegwerf-Passwoerter wuerfelt — lokal spielen sie keine Rolle, weil die App als DATABASE_URL-Besitzer verbindet und nicht als eine dieser Rollen. Staging und Produktion nutzen weiter `pnpm run db:roles:provision` mit verwalteten Secrets.
**5. Starten**
```sh
pnpm dev
pnpm dev:local
```
Standard lokal:
- Tenant-App: `http://app.localhost:3000`
- Admin-App: `http://admin.localhost:3000`
- API bei Bedarf separat: `pnpm --filter @hivegrid/api dev`
- Login aus dem Seed: `admin@email.com` / `password`
`pnpm dev:local` stellt vor jedem Start den einzigen lokalen Plattform-Admin samt `SuperAdmin`-Rolle
wieder her und setzt bei allen passwortfähigen Plattform- und Portal-Benutzern der lokalen
Wegwerf-Datenbank das Passwort auf `password`. Passwortlose Magic-Link-Konten bleiben passwortlos.
Der Guard verweigert CI-, Staging-/Production-, RLS-required-, nicht lokale und nicht explizit als
wegwerfbar markierte Datenbankziele. Frische `pnpm dev:services`-Datenbanken tragen den Marker
automatisch; fuer ein bestehendes lokales Compose-Volume ist einmalig `pnpm dev:services:mark-local`
noetig. `pnpm dev` ist nur der rohe Web-Prozess ohne diesen lokalen Credential-Vertrag.
Row-Level-Security laeuft lokal auf `RLS_RUNTIME_MODE=off` (Default in `.env.example`); die Policies werden erst in Staging/Produktion erzwungen, wo die App als `hivegrid_app` ohne Bypass verbindet.
## Verifikation
@@ -93,7 +140,6 @@ Je nach Aenderung zusaetzlich die passenden `verify:*`-Gates aus der Agent-Check
pnpm run verify:ci-baseline
pnpm run verify:env-drift
pnpm run verify:docs-links
pnpm run verify:production-docs
pnpm run verify:deploy-readiness
```