Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
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
|
||||
|
||||

|
||||
|
||||
## Codeumfang
|
||||
|
||||
[](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).
|
||||
|
||||
[](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
|
||||
```
|
||||
|
||||
|
||||
Reference in new issue
Block a user