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,6 +4,42 @@
|
||||
> **hier** steht das praktische „bevor du pushst, mach es lokal grün" + die Footguns aus echten Vorfällen.
|
||||
> Die DoD-/Scope-/Ticket-Regeln aus AGENTS.md gelten zusätzlich.
|
||||
|
||||
## 0. Jede mutierende Session isoliert starten
|
||||
|
||||
Aus einem vorhandenen Clone:
|
||||
|
||||
```bash
|
||||
pnpm session:start -- <type>/<kurzer-slug>
|
||||
cd <ausgegebener-worktree>
|
||||
```
|
||||
|
||||
Der Befehl erstellt Branch und Geschwister-Worktree immer neu vom aktuellen `origin/main`, hydriert
|
||||
`.env` atomar über den kanonischen SOPS-Age-Key und führt `pnpm install --frozen-lockfile` aus. Bereits
|
||||
vorhandene lokale oder Remote-Branches und vorhandene Zielverzeichnisse werden verweigert.
|
||||
|
||||
- Nicht im dirty Haupt-Workspace arbeiten.
|
||||
- Einen Session-Branch nicht für ein neues Ticket oder einen Folge-Fix wiederverwenden.
|
||||
- Rein lesende Diagnose ist ausgenommen; vor der ersten Dateiänderung muss ein Session-Worktree stehen.
|
||||
- Scheitert SOPS oder die Installation, muss der Start ohne leere `.env` und ohne halben Worktree
|
||||
zurückrollen.
|
||||
|
||||
## 0.5 Atomare Checkpoints während der Umsetzung
|
||||
|
||||
Nicht bis zum Ende des Auftrags mit dem Committen warten. Nach jeder abgeschlossenen, separat
|
||||
revertierbaren Änderung:
|
||||
|
||||
1. `git status --short` prüfen und nur die Dateien des aktuellen fachlichen Checkpoints stagen.
|
||||
2. `git diff --cached --name-only` und `git diff --cached --stat` lesen.
|
||||
3. Bei mindestens 25 Dateien oder 800 geänderten Zeilen ohne reine Generierung, Migration oder
|
||||
Massendeletion den Commit vor dem Fortfahren fachlich aufteilen.
|
||||
4. `git diff --cached --check`, fokussierte Tests und den Typecheck der betroffenen Pakete ausführen.
|
||||
5. Den Checkpoint sofort committen, bevor ein unabhängiger Bug, Refactor, Tooling-/Test-Fix oder der nächste
|
||||
Plan-/DoD-Punkt begonnen wird.
|
||||
|
||||
Tests, Typen, Übersetzungen, Redirects und generierte Artefakte bleiben bei der Änderung, die sie
|
||||
erforderlich macht. Änderungen eines anderen Checkpoints bleiben unstaged. `git add -A` ist nur zulässig,
|
||||
wenn `git status --short` nachweislich genau einen Checkpoint enthält.
|
||||
|
||||
## 1. Vor JEDEM Push: lokal grün machen
|
||||
|
||||
CI läuft auf node1 mit begrenzten Slots (~7 Min/Lauf). Fang Fehler **lokal** ab, nicht im CI.
|
||||
@@ -29,7 +65,8 @@ Je nach Änderung die relevanten Validatoren laufen — CI bricht sonst:
|
||||
| **Neues `packages/<x>`** | `pnpm run verify:docker-baseline` ← **Dockerfile deps-Target braucht `COPY packages/<x>/package.json`** (sonst Deploy rot, §3) |
|
||||
| **Neues Prisma-Modell mit `tenantId`** | `TENANT_SCOPED_MODELS` in `packages/cli/src/commands/tenant/models.ts` ergänzen (Eltern vor Cascade-Kindern) + RLS-Policy in `prisma/rls/<modul>-isolation.sql`. Test: `packages/cli/.../tenant/models.test.ts` (§3) |
|
||||
| **Neue Default-Permission** | In **alle vier** Registries: `packages/db/.../permissions-seed.server.ts` (Seed + Rollen-Grant) · `apps/web/app/application/dtos/shared/DefaultPermissions.ts` (Enum) · `apps/web/app/components/core/roles/roleDisplay.ts` (Scope- + Action-Map) · `translations.json` unter `models.permission.defaultPermissions.{scopes,actions}` (de **und** en). Tests: `rolesAndPermissionsService.role-matrix` + `roleDisplay` (§3) |
|
||||
| **`prisma/schema/**` geändert** | `pnpm run verify:migrations-parity` ← Schema ohne Merge-Migration = CI rot (AD-21-Gate; braucht Docker). Auf dem Branch mit `db push` arbeiten ist ok, aber **vor dem Merge** muss die Migration existieren |
|
||||
| **`prisma/schema/**` geändert** | **Beide** Gates, nicht nur das erste: `pnpm run verify:migrations-parity` ← Schema ohne Merge-Migration = CI rot (AD-21-Gate; braucht Docker) · `HIVEGRID_RLS_REQUIRE_MIGRATION_CHAIN_PARITY=1 pnpm run verify:rls-live` ← spielt die Kette als **Nicht-Superuser** durch. Auf dem Branch mit `db push` arbeiten ist ok, aber **vor dem Merge** muss die Migration existieren |
|
||||
| **FK auf eine Tabelle mit FORCE RLS** | Der Constraint wird mit einem internen Join über die referenzierte Tabelle validiert, und FORCE gilt auch für den Owner → `ALTER TABLE "<Ziel>" NO FORCE ROW LEVEL SECURITY;` … FK … `FORCE` wieder an (Policies bleiben ENABLED, kein DML im Fenster). **Eine leere referenzierende Tabelle hilft nicht** — die Anweisung wird abgelehnt, bevor eine Zeile gelesen wird. Ein lokaler Replay als Superuser sieht das nicht; nur `verify:rls-live` und die CI-Shadow-DB fangen es |
|
||||
| Dockerfile / Runtime | `verify:docker-baseline` · `verify:docker-non-root` |
|
||||
| UI-Texte | `pnpm run verify:i18n` (keine hartkodierten Strings) |
|
||||
| Allgemein | `verify:ci-baseline` · `verify:source-health` |
|
||||
@@ -41,12 +78,33 @@ Je nach Änderung die relevanten Validatoren laufen — CI bricht sonst:
|
||||
- **Default-Permission lebt in 4 Registries.** Nur in den Seed schreiben reicht NICHT (siehe §2): `role-matrix`-Test verlangt den Eintrag im `DefaultPermissions`-Enum, `roleDisplay`-Test verlangt Scope- **und** Action-Mapping in `roleDisplay.ts` **plus** Übersetzungen unter `models.permission.defaultPermissions.{scopes,actions}` (de+en). Bei mehrstufigem Scope **flache** Keys (`hr.leave` → `hrLeave`), sonst Pfad-Kollision mit dem `hr`-String-Leaf. (AK-P17b)
|
||||
- **Kein `"…"` (doppelte Anführungszeichen) in Kommentaren im `defaultPermissionSeeds`-Array.** Der `roleDisplay`-Test **regex-extrahiert jedes doppelt-gequotete Literal im Array** als Permission-Namen — ein zitiertes Wort im Kommentar wird zur Phantom-Permission und bricht den Test (`… is not valid JSON`). Im Kommentar einfache Anführungszeichen / Backticks nutzen. (AK-P17b)
|
||||
- **Coverage-Gate läuft vom Repo-Root (jsdom).** Tests, die Node-Kontext brauchen (`fs`, `process`), mit `// @vitest-environment node` pinnen. **Kein `process.chdir`** in parallelen Tests (race). `vi.mock` **leakt** zwischen Files in shared Workers → Mocks pro File isolieren / `vi.restoreAllMocks`.
|
||||
- **RLS ist lokal AUS und in Staging/Prod AN.** Ein grüner lokaler Lauf beweist **nichts** über RLS. Greifst du in einer Route/einem Service direkt auf `db.<model>` zu, binde den Kontext (`runWithRlsContext` / `withTenantRLS`) — sonst liefert die Query dort **null Zeilen**, ohne Fehler und ohne Log (2026-07-14: eine neue Route hätte in Prod jedes Profilbild als 404 ausgeliefert). Db-Mocks, die auf jede Query antworten, verstecken genau das. Details: `AGENTS.md` §Row-Level-Security.
|
||||
- **Kein Laufzeit-Flag mit `SEED_`-Präfix.** Der Deploy-Vertrag (`assert-runtime-db-env`) weist jeden `SEED_*`-Schlüssel auf Runtime-Ressourcen ab. Ein Feature-Schalter, der zufällig nach Seed klingt, wird beim Deploy stillschweigend entfernt — genau daran sind die Staging-Demo-Logins gestorben (2026-07-14).
|
||||
- **`.server.ts`-Re-Export ist verboten** (RR7-Client-Build bricht). Stattdessen Component-Extraktion.
|
||||
- **pre-push-Hook blockt?** Erst die Checks **manuell** laufen + Ursache fixen — nicht blind `git push --no-verify`. `--no-verify` nur, wenn der Hook-Fehler nachweislich irrelevant ist (z.B. Hook-Timeout, kein echter Lint-/Typ-Fehler).
|
||||
|
||||
## 4. Branch / PR / Merge
|
||||
|
||||
- **Nie direkt auf `main` pushen** → Branch + PR (Squash-Merge).
|
||||
- **Gitea-Identität fail-closed prüfen:** `git config --local hivegrid.giteaUser` muss den persönlichen
|
||||
Dev-Login dieses Clones enthalten. Die effektive Git-/API-Credential muss vor jedem Push und jedem
|
||||
Gitea-Write via `GET /api/v1/user` exakt diesen Login + `active=true` ergeben. `gitea-admin`, `Sudo`
|
||||
und andere Impersonation sind für Routinearbeit verboten. Nur CI-/Deploy-Bots sind als explizite
|
||||
Servicekonto-Ausnahme zulässig.
|
||||
- **Nie direkt auf `main` pushen** → Branch + PR + normaler Merge-Commit. **Squash ist verboten.**
|
||||
- **Commit-Historie erhalten:** Vor dem Merge erwartete PR-Head-SHA prüfen und Gitea ausschließlich mit
|
||||
der normalen Merge-Strategie (`Do=merge`, nie `Do=squash`) aufrufen. Nach dem Merge muss
|
||||
`git merge-base --is-ancestor <feature-head> origin/main` erfolgreich sein; die einzelnen
|
||||
Feature-Commits behalten ihre ursprünglichen SHAs.
|
||||
- **Versehentlichen Squash append-only reparieren:** Geteiltes `main` niemals umschreiben oder
|
||||
force-pushen. Stattdessen einen bytegleichen History-Repair-PR erstellen, der den ursprünglichen
|
||||
Feature-Head per normalem Merge-Commit anbindet, CI vollständig abwarten und die erhaltene Ancestry
|
||||
nachweisen.
|
||||
- **Session nach normalem Merge aufräumen:** Sobald der PR per normalem Merge-Commit in `main` liegt:
|
||||
`pnpm session:finish -- <branch>`. Der Helfer prüft dirty State, aktuelle Main-Ancestry, den
|
||||
Merge-Commit, identische lokale/Remote-Heads, geschlossene PRs und persönliche Gitea-Identität. Erst
|
||||
danach löscht er Remote-Branch, Worktree und lokalen Branch. Bei Squash, Fast-Forward, offenem PR,
|
||||
weitergelaufenem Branch oder lokalen Änderungen stoppt er. Nicht durch `rm -rf` oder `git branch -D`
|
||||
umgehen.
|
||||
- **Parallel-Schema (AD-21):** Modul = eigene `prisma/schema/<modul>.prisma`; am Branch `prisma db push`, **Migration erst beim Merge** (forward-only + Inverse-SQL als Kommentar, aus dem Nichts reproduzierbar — `DO $$ … IF [NOT] EXISTS … $$`-Guards).
|
||||
- **Deploy-Path-Filter:** test-/doc-/workflow-only-Merges (`**/*.test.*`, `docs/**`, `.planning/**`, `.gitea/workflows/**`, `*.md`) skippen den Staging-Deploy automatisch. Code-Änderungen triggern ihn.
|
||||
- **Abhängige nicht brechen:** bei Contract-/`core.prisma`-/Querschnitt-Änderungen `blocked-by` UND `blocks` lesen, Konsumenten nachziehen, Auswirkung dokumentieren.
|
||||
|
||||
@@ -1,563 +1,78 @@
|
||||
# HiveGrid 2.0 — Architektur-Entscheidungen
|
||||
|
||||
> Entscheidungen aus dem Boilerplate-Abgleich, den späteren HiveGrid-Pivots und
|
||||
> der Bespoke-Planung. Diese ADR-Liste ergänzt `AGENTS.md` und ist verbindlich
|
||||
> für die Umsetzung. Die historischen Boilerplate-Mapping-Ordner wurden im
|
||||
> Bespoke-Cleanup entfernt; aktuelle Quellen sind `.planning/ENTITY-MODEL.md`,
|
||||
> `.planning/PHASE-SOURCES.md`, die Ticket-Docs und `docs/milestones/`.
|
||||
> Legende: ✅ entschieden · 🅿️ Backlog (Entscheidung später).
|
||||
|
||||
---
|
||||
|
||||
## AD-1 — Mandanten-Trennung: echtes Postgres-RLS ✅
|
||||
|
||||
**Entscheidung:** Row-Level-Security in Postgres als bauliche Vorgabe (nicht nur App-Level-Scoping).
|
||||
- RLS-Policies (USING/WITH CHECK) als Forward-Migration mit Inverse-SQL-Kommentar
|
||||
- Request-Middleware setzt `SET LOCAL app.tenant_id`
|
||||
- App-DB-Rolle **ohne** `BYPASSRLS`
|
||||
- Worker-/Job-Tenant-Context-Wrapper
|
||||
- Cache-Präfix `tenant:{id}:`, S3-Pfad `tenants/{id}/`
|
||||
- Ausnahmen ohne RLS: `users`, `subscription_*`, `feature_flags`, Branchen-Templates
|
||||
|
||||
**Warum:** Spec A.4 + M019-Erfolgskriterium (Pen-Test). Defense-in-depth — ein vergessener
|
||||
Query-Filter kann keine Fremddaten mehr leaken. Boilerplate hat **nur** App-Level-Scoping.
|
||||
**Betrifft:** M019 (+ jedes tenant-scoped Modul).
|
||||
|
||||
## AD-2 — Daten-Modell: typisierte Tabellen, Entity-Builder raus ✅
|
||||
|
||||
**Entscheidung:** HiveGrid-Fachentitäten (CRM, Deals, Aufträge, Tasks, …) als dedizierte,
|
||||
typisierte First-Class-Prisma-Tabellen. Das Entity-Builder-CRM der Boilerplate
|
||||
(`Entity`+`Row`+`RowValue`, `apps/web/app/modules/crm`) wird **entfernt**, nicht angepasst.
|
||||
Custom-Felder über purpose-built `CustomFieldDefinition` + `CustomFieldValue` (JSONB-Wert),
|
||||
nicht über die polymorphe Row-Engine.
|
||||
|
||||
**Warum:** Spec M01 verlangt typisierte Tabellen mit Constraints, Indizes (`pg_trgm`,
|
||||
`tenant_id, archived_at, last_activity_at`), `ContactEmail`/`ContactPhone`, M:N-Relationen,
|
||||
zentrale `Activity`-Tabelle. Polymorphes `RowValue` ist damit unvereinbar (Performance bei
|
||||
10k+, Indizes, Permissions, RLS). Zwei Architekturen parallel = Fremd-Architektur sickert ein.
|
||||
**Betrifft:** M01, M02, M03, M04, M26 (+ alle Fachmodule).
|
||||
|
||||
> **🔄 REVIDIERT 2026-06-13 (Modell-Pivot, siehe AD-20):** Deal + Project verschmelzen zu EINER
|
||||
> typisierten `Projekt`-Tabelle (Superset der Felder) + `CustomFieldDefinition/Value` + einem
|
||||
> neuen **Pipeline-Feld-Config-Layer** (welche Felder pro Pipeline+Status sichtbar/pflichtig sind;
|
||||
> nicht sichtbare Felder bleiben im Hintergrund erhalten). Die Konfigurierbarkeit ist **Metadaten
|
||||
> über typisierten Spalten** — der generische Entity-Builder (Entity/Row/RowValue) bleibt entfernt.
|
||||
> AD-2-Prinzip („typisiert, kein Generikum") bleibt gewahrt. Anker: `.planning/ENTITY-MODEL.md`.
|
||||
|
||||
> **🔴 PRÄZISIERUNG & VERBINDLICHE REGEL 2026-06-29 (R-P6 / R-P6B):** Das „✅" oben gilt bislang **nur für den CRM-Pfad** (R-P6 typisierte Kontakte + R-P6B-α + R-P6C). Der **generische Entity-Builder läuft noch** und wird weiter genutzt von EmailMarketing, Form-Submission (`apps/worker`/`apps/api`), WorkflowEngine, formulas und ~49 `EntitiesSingleton`-Konsumenten (Konsumenten-Matrix + Reihenfolge/Ownership: `.planning/ticket-docs/R-P6B.md`).
|
||||
>
|
||||
> **Regel (ab jetzt verbindlich): KEINE neuen Entity-Builder-Konsumenten.** Jedes neue Fachmodul/Feature nutzt **typisierte** Prisma-Tabellen (wie CRM), niemals `Entity`/`Row`/`RowValue`, `modules/rows`, `utils/db/entities`, `EntitiesSingleton`, die `*Api.server`-Entity-Layer oder den `CrmService`-Legacy. Ein PR, der einen **neuen** Builder-Konsumenten einführt, wird abgelehnt (wie ein Anti-Listen-Verstoß).
|
||||
>
|
||||
> **Ablöse-Pflicht: Der generische Entity-Builder MUSS vollständig abgelöst werden** (R-P6B-β; kein „optional"). Vorgehen **organisch**: jedes Builder-nutzende Modul wird **typisiert, sobald es ohnehin angefasst wird** (Migration durch Neubau < Refactor); neue Module sowieso typisiert. Ist der letzte Konsument weg, fällt `entityBuilder.prisma` (+ Tenant-Daten-Entscheidung). **Spätlimit:** vor produktivem Masseneinsatz von `Row`-Daten (sonst wird die Schema-Löschung zur Daten-Migration).
|
||||
|
||||
## AD-3 — Plattform-Admin-Identität: getrennt, Email+PW+TOTP, optional Authentik-SSO ✅
|
||||
|
||||
**Entscheidung:** Vollständig getrennte Admin-Welt — eigene `AdminUser`-Tabelle (eigenes
|
||||
`passwordHash`/`totpSecret`/`status`), eigene `AdminSession` (server-side, IP-gebunden),
|
||||
eigene `AdminRole`/`AdminPermission`-RBAC. Primärer Login: **Email + Passwort + TOTP**
|
||||
(Magic-Link verboten). **Zusätzlich** optionaler **Authentik-OIDC/SSO**-Login, gemappt auf
|
||||
dieselbe getrennte Admin-Identität. **Kein** Generalschlüssel zwischen Plattform und Mandanten.
|
||||
- `AdminAuditLog` braucht **kein** neues Schema: vorhandener `AuditEvent` (Hash-Kette,
|
||||
`tenantId=null` = plattformweit) deckt das ab.
|
||||
- Boilerplate-Admin-Auth (Login-Flow, MFA-Step-up-Gate, Rate-Limit, Session-Cookie-Policy)
|
||||
dient als **Vorlage**, nicht 1:1 (BP hat AdminUser nur als `User`-Extension).
|
||||
|
||||
**Warum:** Spec 37.1 / M034 verbietet den geteilten Identity-/RBAC-Pfad explizit.
|
||||
**Betrifft:** M034–M041 (M37).
|
||||
|
||||
## AD-4 — Sessions: Postgres als Source-of-Truth + Redis-Cache ✅
|
||||
|
||||
**Entscheidung:** Server-side Session-Tabelle in Postgres (Geräte-Liste mit Browser/IP/
|
||||
Standort/letzter Aktivität, Revoke, „von allen Geräten abmelden", 4h-Inaktivität,
|
||||
30-Tage-Sliding-Window, Auto-Logout bei Passwort-/2FA-/Email-Änderung) als Quelle der
|
||||
Wahrheit; **Redis-Cache** für schnelle Pro-Request-Validierung. Cookie hält nur die
|
||||
Session-ID-Referenz.
|
||||
|
||||
**Warum:** Spec B.5 braucht dauerhafte, abfragbare Geräte-Liste + verlässliches Revoke-all;
|
||||
reine Cookies (BP-Default) können nicht serverseitig widerrufen werden; reines Redis verliert
|
||||
Geräte-Historie bei Flush.
|
||||
**Betrifft:** M021 (Mandanten-User), M034 (`AdminSession`), M141 (Customer-Portal).
|
||||
|
||||
## AD-5 — Such-Engine: Meilisearch (self-hosted) + pgvector-Hybrid ✅
|
||||
|
||||
**Entscheidung:** Keyword-Suche über das **selbst gehostete Meilisearch** (BP-`@hivegrid/search`
|
||||
weitgehend 1:1), semantische Suche über **pgvector + EU-Embeddings** (Scaleway 1024-dim, BP 1:1),
|
||||
kombiniert via **RRF-Fusion**. Embedding-Pipeline + Outbox + Indexer-Worker aus der BP übernehmen.
|
||||
|
||||
**Warum:** Meilisearch wird ohnehin selbst gehostet (EU-Datenhoheit + Ops bereits gelöst) →
|
||||
bessere Tippfehler-Toleranz/Relevanz + maximaler Reuse. **Weicht bewusst von M056
|
||||
„Postgres-FTS, kein Extra-Service" ab → Change-Request gegen M056 nötig.**
|
||||
**Betrifft:** M24 / M056–M058.
|
||||
|
||||
## AD-6 — EU-Email-Provider ✅
|
||||
|
||||
**Entscheidung (2026-06-16, EXT-02):** **Mailjet** (EU/FR) als EU-Email-Provider für
|
||||
transaktionale **und** Marketing-Mails. MailerSend (BP-Default) wird **verworfen** — MailerSend,
|
||||
Inc. ist US-Entität (Transfers via EU-US Data Privacy Framework), unter strikter LP-13-Lesart
|
||||
(„keine US-Gesellschaft im Boot", wie bei OpenAI/Anthropic) problematisch.
|
||||
|
||||
**Warum:** EU-Datenhoheit ohne US-Gesellschaft im Boot; feature-reich (transaktional + Marketing
|
||||
+ A/B in P14). Boilerplate ist bereits auf `MAILJET_*` verdrahtet.
|
||||
|
||||
**Verifikationsstand (EXT-02):** Sende-Domain `hivegrid.de` bei Mailjet verifiziert — SPF
|
||||
(`include:spf.mailjet.com`) + DKIM (Selector `mailjet`) Auto-Probe **grün**, Sender `*@hivegrid.de`
|
||||
aktiv; DMARC `p=none` (Monitoring während Warm-up).
|
||||
**Cleanup-Follow-ups:** (a) `include:_spf.mailersend.net` aus dem SPF-Record entfernen, sobald die
|
||||
Migration vollständig ist; (b) DMARC nach Warm-up von `p=none` auf `p=quarantine` ziehen.
|
||||
|
||||
**Betrifft:** M09, M10, M22, M102.
|
||||
|
||||
## AD-7 — Captcha / Bot-Schutz 🅿️ (Backlog)
|
||||
|
||||
**Status:** Entscheidung später. **Tendenz: EU** — Friendly Captcha (DE, GDPR-first) oder
|
||||
self-hosted mCaptcha (passt zum Meilisearch-Self-Host-Ansatz).
|
||||
- Turnstile (BP) und hCaptcha (Spec) sind beide US-Firmen → bei strikter Linie Change-Request.
|
||||
**Betrifft:** Login (M020), Public-Forms (M05/M125), Booking (M06).
|
||||
|
||||
## AD-8 — Verschlüsselung: Per-Tenant-DEK + Envelope ✅
|
||||
|
||||
**Entscheidung:** Pro Mandant ein Data-Encryption-Key (DEK), verschlüsselt mit einem Master-Key
|
||||
(Scaleway Key Manager o.ä.) — Envelope-Encryption. Crypto-Shredding bei Mandanten-Löschung
|
||||
(M165: Tenant-Key wegwerfen → alle verschlüsselten Daten unlesbar).
|
||||
|
||||
**Warum:** Spec verlangt Per-Tenant für Passwort-Safe (M134) + OAuth-Tokens; globaler Key
|
||||
(BP-Default) exponiert bei Kompromiss alle Mandanten und erlaubt kein Crypto-Shredding.
|
||||
**Betrifft:** M134 (HR-Passwort-Safe), OAuth-Tokens (M09/M25/M12), M165 (DSGVO-Löschung).
|
||||
|
||||
## AD-9 — Realtime: WebSocket für Chat + SSE für Read-Updates ✅
|
||||
|
||||
**Entscheidung:** Generischer WebSocket-Room-Layer für bidirektionale Echtzeit (Team-Chat M13:
|
||||
Rooms, Presence, Typing, Read-Receipts). SSE (BP-Default) bleibt für einseitige Live-Updates
|
||||
(Kanban M03, Notifications M22). `hocuspocus` bleibt CRDT-only (Kollab-Dokumente).
|
||||
|
||||
**Warum:** SSE ist einseitig → für Chat ungeeignet; hocuspocus ist CRDT, kein Chat-Broadcast.
|
||||
**Betrifft:** M13 (M110–M114); SSE-Pfad: M03, M22.
|
||||
|
||||
## AD-10 — Naming-Konvention: HiveGrid-Scope ohne Alt-Aliase ✅
|
||||
|
||||
**Entscheidung:** Alle Workspace-Pakete und technischen Produkt-Contracts nutzen HiveGrid-Namen:
|
||||
`@hivegrid/*`, `hivegrid-cli`, `HIVEGRID_*`, `hivegrid_*`-Cookies, `x-hivegrid-*`-Header und
|
||||
`hivegrid.*`-Queue-Namen. Es gibt keine Alt-Scope-Package-Aliase und keine parallel gepflegten
|
||||
Alt-Binaries.
|
||||
- `packages/ui-app`, `packages/ui-subframe` und `packages/ui-mock` behalten ihre realen Pfade.
|
||||
Ein fiktives `packages/ui-hivegrid` wird nicht eingeführt.
|
||||
- Estate-Slugs bleiben dort erhalten, wo sie externe Infrastruktur beschreiben
|
||||
(`git.tool-ctrl.de`, `toolctrl-labs`, `toolctrl-ci`, Plane-Workspace `toolctrl`).
|
||||
- HiveGrid-Doku (`AGENTS.md`, `docs/INTEGRATION-CONTRACTS.md`, PLANs, Reports) wird auf diese
|
||||
Realität gezogen; ältere `ui-hivegrid`- oder Alt-Scope-Erwähnungen sind Doku-Drift.
|
||||
|
||||
**Warum:** HiveGrid wird bespoke weitergeführt. Einheitliche Produktnamen reduzieren kognitive
|
||||
Last, vermeiden falsche Imports und verhindern, dass neue Arbeit versehentlich alte Contracts
|
||||
weiterträgt.
|
||||
**Betrifft:** Querschnitt (alle Module), Phase 0.
|
||||
|
||||
---
|
||||
|
||||
# Delivery- & Scope-Entscheidungen
|
||||
|
||||
## AD-11 — Bau-Strategie: Hybrid (Fundament-Kern, dann Geerkens-Kernpfad) ✅
|
||||
|
||||
**Entscheidung:** Nach Phase 0 zuerst der Fundament-Kern (M27 Auth + M33a Apps-Engine + M01 CRM-Datenmodell),
|
||||
dann sofort die Geerkens-Wertschöpfungskette **Lead → Projekt (konfigurierbare Pipelines) → KWP**, danach die Breite
|
||||
(HR, Portal, Marketing, Mobile, Billing-Feinheiten). Balance aus sauberem Fundament und früh sichtbarem Nutzen.
|
||||
|
||||
> **🔄 REVIDIERT 2026-06-13 (Modell-Pivot, AD-20):** Kette ist nicht mehr „Lead → Sales(Deal) → Auftrag(Project)",
|
||||
> sondern **Lead → Projekt → KWP**. Sales und Auftrag sind konfigurierbare Pipeline-Views auf denselben `Projekt`-Kern.
|
||||
|
||||
## AD-12 — SHK-Domänen-Defaults: aus Spec als Seed, Noah validiert ✅
|
||||
|
||||
**Entscheidung:** Die SHK-Inhalte (10 Standard-Rollen + Permission-Bundles [27.7/N1], SHK-Sales-Pipeline-Stufen [M59],
|
||||
Standard-Custom-Felder + Tags [M44], Provisionierungs-Daten [M158]) werden aus Spec/Pflichtenheft als
|
||||
**deklaratives, leicht änderbares Seed** umgesetzt; Noah/Geerkens validieren iterativ im Klick-Pfad. Blockiert den Bau nicht.
|
||||
|
||||
> **🔄 AMENDMENT 2026-06-19 (Owner-Entscheidung Raffael, Partner-validiert):** Die spekulativen „10 Standard-Rollen"
|
||||
> aus 27.7/N1 sind auf die **6 vom Partner gelieferten Rollen** festgelegt: **Geschäftsführer, Projektleiter,
|
||||
> Verwaltung, Vertriebler, Kundensupporter, Monteur** (Seed `apps/web/app/utils/services/shkRoles.server.ts`,
|
||||
> idempotent, `is_demo_data`). Das deklarative-Seed-Prinzip bleibt unverändert; nur die Anzahl/Liste ist fixiert.
|
||||
> R-P2b-DoD + Planungs-Docs (.planning/, Milestone-Layer) entsprechend von 10 auf 6 nachgezogen.
|
||||
|
||||
## AD-13 — Go-Live-Scope: breiter Launch ✅
|
||||
|
||||
**Entscheidung:** Der erste Geerkens-Go-Live umfasst nicht nur die Vertriebskette, sondern auch **HR-Hub,
|
||||
Customer-Portal, Marketing und Mobile**. Scope ≈ Großteil der 35 Module. (Sequenzierung trotzdem nach AD-11.)
|
||||
|
||||
## AD-14 — Migration: sauberer Start + KWP-Sync füllt nach ✅
|
||||
|
||||
**Entscheidung:** Geerkens startet weitgehend leer; KWP-Sync (M089ff) bringt Auftrags-/Stammdaten automatisch.
|
||||
HubSpot/Quiply-Altdaten bleiben **extern als Read-only-Archiv**; nur punktuelle CSV-Importe via `packages/imports`.
|
||||
Keine vollen Migrations-Pipelines pro Quelle zum Launch.
|
||||
|
||||
## AD-15 — Pricing/Billing: Engine bauen, Preise geparkt ✅
|
||||
|
||||
**Entscheidung (revidiert 2026-07-04, siehe AD-27):** Legacy-Provider wird nicht mehr als Billing-/Payment-Default gebaut.
|
||||
HiveGrid nutzt eine selbst gehostete Billing-Engine und einen EU-Payment-Processor. Für v1 sind nur **Plans + Seats**
|
||||
im Scope; **kein Usage-Billing** und keine konkreten öffentlichen Preisstufen. Geerkens läuft weiter auf manueller
|
||||
Sonderkondition/Trial. Self-Service-Checkout-Preise bleiben eine eigene spätere Pricing-Runde.
|
||||
|
||||
## AD-16 — USP-Säulen (Automation + KI): volle Tiefe zum Launch ✅ (⚠ KI-Hälfte abgelöst von AD-26, 2026-06-22)
|
||||
|
||||
**Entscheidung:** Kompletter visueller Automation-Editor (M075–M082, alle Trigger/Aktionen, 24h-Undo, Guards) **und**
|
||||
voller KI-Layer (M083–M088, EU-Provider, RAG, Sprach-zu-Automation, Pay-as-you-go) sind day-1 dabei — nicht nur Fundament.
|
||||
|
||||
> **⚠ KI-Hälfte abgelöst durch [AD-26] (2026-06-22):** Kein selbst-gehostetes LLM/RAG/HiveMind mehr — KI kommt via **MCP-Server** (externe Clients), M083–M088 gestrichen. Die **Automation-Säule bleibt** unverändert day-1.
|
||||
|
||||
## AD-17 — Mobile: PWA-only (v1 + v2), kein nativer Client ✅ (revidiert 16.06.)
|
||||
|
||||
**Entscheidung (revidiert 2026-06-16):** Mobile läuft **ausschließlich als installierbare PWA / responsive Web** — in v1 **und** v2. Monteur kann auf der Baustelle offline Aufträge bearbeiten, Abnahmen erfassen, Plantafel sehen; alles wird über Service-Worker + IndexedDB-Offline-Queue + Background-Sync gequeued und bei Sync mit „KWP gewinnt" aufgelöst (KWP-Sync = v2). **Kein Expo, kein Capacitor, keine native iOS/Android-App, keine App-Store-Einreichung.** Push = **Web-Push (VAPID)** — aktiviert in v2 den in P1 ruhenden `notify()`-Push-Kanal. Native-App + App-Store → frühestens **v3** (Backlog, nicht beauftragt).
|
||||
|
||||
**Historie:** 10.05. voller Offline-Betrieb (Capacitor, M167–M171) · 11.06. Capacitor→Expo + native Hülle nach v2 · **16.06. komplett auf PWA-only reduziert** (kein nativer Client in v1/v2; M167–M171 entfallen, „Mobile-App"-Arbeit = PWA-Ausbau: Installierbarkeit, Service-Worker, Offline-Härtung, Web-Push).
|
||||
|
||||
## AD-18 — Customer-Portal: voll inkl. Skalierungs-Sicht ✅
|
||||
|
||||
**Entscheidung:** Komplettes Portal day-1: Projekt-Sicht + Upload + Reklamation + Subunternehmer-Zugang +
|
||||
Skalierungs-Sicht (Service-Inbox + Routing + Pro-Kunden-Lebensdauer), M141–M146 inkl. [N19].
|
||||
|
||||
> **Scope-Muster (historisch):** AD-13/16 wählen den maximalen Umfang → der erste Go-Live ist faktisch
|
||||
> das **vollständige Phase-1-Produkt** in großer Tiefe. Sequenzierung nach AD-11. **AD-17 (Mobile) und
|
||||
> AD-18 (Portal) wurden später revidiert** (AD-18 → v2; AD-17 → PWA-only v1/v2) und folgen diesem Maximal-Muster
|
||||
> nicht mehr. Dies bleibt eine bewusst große Scope-Wahl (siehe Scope-Check in der Session + SCOPE-V1-CUTS.md).
|
||||
|
||||
## AD-19 — Go-Live-Modus: Big-Bang ✅
|
||||
|
||||
**Entscheidung:** Geerkens geht erst live, wenn das vollständige Phase-1-Produkt steht — **ein großer Launch**,
|
||||
kein phasiertes Produktiv-Go-Live. Interne Bau-Reihenfolge bleibt AD-11 (Fundament → Kernpfad → Breite),
|
||||
aber es gibt kein inkrementelles Produktiv-Schalten einzelner Module für Geerkens.
|
||||
|
||||
**Bewusst akzeptiert:** längste Zeit bis zum ersten echten Nutzer-Feedback, höchstes „am-Alltag-vorbei"-Risiko.
|
||||
**Gegenmaßnahme empfohlen:** Noah/Geerkens-Validierung pro Modul über den PROGRESS-TRACKER-Klick-Pfad
|
||||
(READY-TO-VERIFY → Sign-Off) als Feedback-Ersatz vor dem Big-Bang.
|
||||
|
||||
## AD-20 — Projekt-zentrisches CRM/Pipeline-Modell ✅ (NEU 2026-06-13)
|
||||
|
||||
**Entscheidung:** Das CRM/Pipeline-Modell wird **Projekt-zentrisch** (auf Basis von Davids UX-Briefing,
|
||||
voll adoptiert). Statt getrennter Deal- und Project-Entitäten gibt es **EINEN `Projekt`-Kern**, auf den
|
||||
**frei konfigurierbare Pipelines als Views** schauen. „Deal" und „Auftrag" sind nur Pipeline-Namen/-Typen,
|
||||
keine eigenen Objektarten.
|
||||
- **Pipeline = View:** Admin legt Pipelines an/benennt sie, steuert Zugriff (wer sieht), Feld-Sichtbarkeit,
|
||||
Pflichtfelder pro Pipeline/Status und die Statuswerte. Ein Projekt ist genau **einer** Pipeline zugeordnet;
|
||||
`Status` ist pipeline-intern (kein globaler Projektstatus). Nicht sichtbare Felder bleiben im Hintergrund erhalten.
|
||||
- **Lead-Flow:** Lead/LeadInput ist Vorstufe mit Datenpunkt `Weiterverarbeitungsfreigabe` (Ja/Nein/Unklar);
|
||||
bei Freigabe → Vererbung ins Projekt. **Lead → Projekt** (das frühere Lead→Contact-Promotions-Modal entfällt;
|
||||
Kontakt wird separat verknüpft).
|
||||
- **Kontaktmodell:** `Kontakt` ist Oberbegriff mit `Kontakttyp` (Privatperson/Organisation), `Kontaktstatus`
|
||||
(Kontakt/Kunde/Bestandskunde) und `Kontaktart` (Haupt-/Sekundärkontakt als Rolle/Relation).
|
||||
- **Scope-Calls (13.06.):** Abnahme bleibt **v1** als Checklisten/Protokoll-Sub-Area am Projekt (Mängel = Checkliste);
|
||||
Material/Zeiterfassung/Leistungspositionen/Baustelle/Support → v2-Backlog. **Rechnung** = einfaches Sub-Entity am Projekt in v1.
|
||||
KWP-Felder bleiben v2-Sync, v1 nur Feld-Halter.
|
||||
|
||||
**Warum:** Davids konsolidiertes UX-Modell wird zur Bau-Grundlage gemacht; Raffael richtet die Planung daran aus
|
||||
(statt David einzunormen). Höhere Konfigurierbarkeit (SHK-Betriebe brauchen frei benennbare Pipelines) bei
|
||||
erhaltenem typisiertem Kern.
|
||||
**Betrifft:** AD-2 (revidiert), AD-11 (Kette revidiert), M01–M04, ENTITY-MODEL, ROADMAP P6–P9, REQUIREMENTS, SCREEN-MAP.
|
||||
**Anker:** `.planning/ENTITY-MODEL.md`.
|
||||
|
||||
## AD-21 — Prisma: Schema-Folder + Migrations-Disziplin für parallele Branches ✅ (NEU 2026-06-16)
|
||||
|
||||
**Kontext:** 2 Devs (Raffael + Akeshan) bauen Modul-Phasen parallel in eigenen Branches. Risiko: Kollisionen im Datenmodell und in der Migrations-Historie.
|
||||
|
||||
**Befund (16.06.):** Prisma **7.8.0**; das Schema ist **bereits als Ordner** organisiert (`prisma/schema/` mit 29 Domänen-Dateien: `core`, `accounts`, `permissions`, `appsEngine`, `email`, `workflows`, `notifications`, `marketingLeads`, `ai` …). Die **Datei-Ebene ist damit gelöst** — Module in verschiedenen Domänen-Dateien kollidieren nicht. Es existieren bereits 153 Migrations (lineare Timestamp-Historie). Connection-URLs in `prisma.config.ts` (Prisma 7): `DIRECT_URL` für Migrate, `DATABASE_URL` via PgBouncer zur Laufzeit.
|
||||
|
||||
**Verbleibende Risiken:** (1) `core.prisma`/`accounts.prisma` sind der geteilte Kern (Tenant/User/Audit/File/ApiKey/Credential) — gleichzeitige Relations-Edits kollidieren *in dieser Datei*. (2) Zwei Branches mit je `migrate dev` erzeugen divergierende Migrations-Ordner → „applied out of order" beim Merge.
|
||||
|
||||
**Entscheidung — drei verbindliche Konventionen:**
|
||||
1. **Ein Modul = eine eigene `prisma/schema/<modul>.prisma`.** Neue Modelle **nie** in `core.prisma`/`accounts.prisma`. Diese nur für Relationen zu `Tenant`/`User` anfassen, Rück-Relationsfelder dort minimal halten.
|
||||
2. **Migrationen erst beim Merge.** Auf dem Feature-Branch mit `prisma db push` iterieren (kein Migrations-File). Die **eine** Migration pro Phase erzeugt der Dev, der zuerst auf `main` merged — Forward-only mit Inverse-SQL als Kommentar (AGENTS.md DoD 28). Tägliche Integration hält Diffs klein.
|
||||
3. **CI-Gate vor Merge:** `prisma validate` + `prisma migrate status` grün (pre-push-Hook schärfen).
|
||||
|
||||
**Warum:** Schema-Splittung erledigt die Datei-Konflikte bereits; was bleibt (core-Hotspot + lineare Migrations-Historie) löst Konvention/Disziplin, nicht neue Technik.
|
||||
**Betrifft:** alle parallel gebauten Modul-Phasen (P2–P21, v2), `AGENTS.md` §Prisma-Schema, lefthook pre-push.
|
||||
**Anker:** `prisma/schema/`, `AGENTS.md`.
|
||||
|
||||
## AD-22 — GeoIP lokal + IP-Anonymisierung (EXT-12) ✅
|
||||
|
||||
**Entscheidung:** Geo-Auflösung von Login-/Session-IPs über eine **lokale GeoIP-Datenbank**
|
||||
(DB-IP Lite Country, CC-BY-4.0, MMDB-Format) statt eines externen Dienstes. Die gespeicherte IP wird
|
||||
**pseudonymisiert** (HMAC-SHA256 mit geheimem Pepper); persistiert wird nur das **Land**
|
||||
(`countryCode`/`countryName`). **Kein** EU-SaaS-Geo-Dienst, **kein** ipstack (US/apilayer, LP-13).
|
||||
|
||||
**Warum:**
|
||||
- Ein externer Geo-Dienst — auch ein EU-gehosteter — bekäme die Endnutzer-IP (personenbezogen)
|
||||
übermittelt → DPA + Subprozessor (M166) + Latenz + Abhängigkeit. Der **Transfer selbst** ist das Risiko.
|
||||
- Lokale MMDB: Lookup passiert auf unserem Server, **die IP verlässt unsere Infra nie**. Kein DPA,
|
||||
kein Subprozessor. Passt zur Self-Host-Linie (Meilisearch/mCaptcha).
|
||||
|
||||
**Wofür Geo-IP (Zweck):** „Login aus Land X" + Anomalie „Login aus neuem Land" in der Session-/
|
||||
Security-Sicht (P2); optionale Analytics-Anreicherung nach Land (Default aus); Feature-Flag-Targeting
|
||||
nach Land. Der HIBP-Breach-Check (EXT-12, `password-policy.server.ts`) ist davon unabhängig und bereits aktiv.
|
||||
|
||||
**Speicher-/Minimierungs-Regeln:**
|
||||
- IP nie im Klartext: `IpAddress.ip`/`IpAddressLog.ip` speichern `HMAC-SHA256(IP, IP_HASH_PEPPER)`.
|
||||
Der Pepper liegt in den Coolify-Secrets, **nicht** in der DB → ein DB-Leak allein ist wertlos; der
|
||||
Gleichheits-Vergleich („gleicher Client?") bleibt möglich (Pseudonymisierung statt Anonymisierung).
|
||||
- Geo nur Land: `regionCode`/`city`/`zipCode`/`latitude`/`longitude` bleiben leer/null.
|
||||
- Der Blacklist-Abgleich nutzt die Roh-IP nur zur Laufzeit (Security-Liste), persistiert sie nicht im Log.
|
||||
|
||||
**Provisionierung:** Die MMDB ist ein **Deploy-Artefakt** (nicht im Git), Pfad via `GEOIP_DB_PATH`
|
||||
(Default `./data/geoip/dbip-country-lite.mmdb`); `scripts/update-geoip-db.sh` lädt die Monatsversion.
|
||||
Fehlt die Datei, ist die Land-Auflösung ein No-op (Stub) ohne Fehler. Reader: npm `maxmind` (MIT).
|
||||
|
||||
**Env:** `IP_HASH_PEPPER` (Secret), `GEOIP_DB_PATH` (optional).
|
||||
|
||||
**Folge-Arbeit (offen):** monatlicher Worker-Cron (BullMQ) statt Shell-Skript; `IpAddress`/`IpAddressLog`
|
||||
perspektivisch auf Land + Hash-IP eindampfen (Spalten entfernen, sobald Session-Filter/Feature-Flag-
|
||||
Konsumenten umgestellt sind); UI, die bisher die Roh-IP zeigte, auf Land umstellen.
|
||||
**Betrifft:** EXT-12, P2 (Sessions/Security), P21 (DSGVO/Retention), `modules/ipAddress`, `services/auth/password-policy`.
|
||||
**Anker:** `apps/web/app/modules/ipAddress/`, `docs/ARCHITECTURE-DECISIONS.md`.
|
||||
|
||||
## AD-23 — Media-Auslieferung: privater Bucket + authentifizierter App-Proxy (kein public-read) ✅
|
||||
|
||||
**Entscheidung (2026-06-17):** Hochgeladene Medien werden **nicht** über public-read S3 ausgeliefert.
|
||||
Der Bucket bleibt **privat**; die App liefert Medien über eine **authentifizierte Proxy-Route** aus
|
||||
(Session + Tenant-Scope + Permission), die das Objekt aus dem privaten Bucket streamt bzw. auf eine
|
||||
kurzlebige signierte Download-URL weiterleitet. `STORAGE_PUBLIC_BASE_URL` bleibt leer; der `publicUrl`-
|
||||
Pfad (`RowHelper`/`MediaHelper`/`ApiHelper`, `publicUrl ?? file`) zeigt auf die Proxy-Route.
|
||||
|
||||
**Warum:** CRM-Medien enthalten Kundendaten/Dokumente — world-readable Buckets sind DSGVO-untragbar
|
||||
(jeder mit der URL käme ohne Auth/Tenant-Check ran). Weg A (public-read) ist damit verworfen.
|
||||
|
||||
**Für P4 (Files, `AK-P4a/b`) umzusetzen:**
|
||||
- Proxy-Route (z.B. `/media/…` bzw. `/storage/…`) mit Auth + `withTenantScope()` + `withPermission()`,
|
||||
streamt aus dem privaten Bucket oder redirected auf signierte Download-URL (kurze TTL).
|
||||
- `publicUrl` in den Media-Helpern auf die Proxy-Route verdrahten (statt null/rohem Key).
|
||||
- **Genuin öffentliche Assets** (E-Mail-Bilder, öffentliche Formular-/Booking-/Portal-Seiten,
|
||||
Branding-Logos) können keinen Auth-Proxy nutzen → signierte URLs mit TTL **oder** ein separater
|
||||
`public/`-Prefix mit eng begrenztem public-read. Pro Asset-Typ entscheiden.
|
||||
- DSGVO-Export-Artefakte nutzen bereits signierte URLs (unverändert).
|
||||
|
||||
**Betrifft:** P4 (Files), EXT-06 (nur Bucket/Infra), `packages/storage`, `apps/web` Media-Helper.
|
||||
**Anker:** AD-8 (Verschlüsselung), `packages/storage`, `apps/web/app/utils/helpers/MediaHelper.ts`.
|
||||
|
||||
---
|
||||
|
||||
## Phase-0-Pflichten (kein „Entscheid", sondern Voraussetzung — siehe `_SUMMARY.md`)
|
||||
|
||||
Diese Punkte sind vor der ersten Fachmodul-Umsetzung abzuarbeiten:
|
||||
1. **Codebase lauffähig halten** (pnpm-Workspace, Apps, Packages, Prisma).
|
||||
2. **Naming-Drift beheben:** `@hivegrid/*`, `hivegrid-cli`, `HIVEGRID_*`, `hivegrid_*`,
|
||||
`x-hivegrid-*`, `hivegrid.*`, Sidebar-Konvention, falsche AGENTS.md-Pfade
|
||||
(`indexed-entities.ts`, `sidebar.config.ts`).
|
||||
3. **EU-Sterilisation:** GitHub/Google-OAuth-Reste + `User.githubId/googleId` entfernen.
|
||||
4. **M00 aktivieren** + 4 echte Neubauten: `logActivity()`/Activity-Stream, Search-`indexed-entities`-Registry,
|
||||
**Subframe-Adapter-Code** (Quer-Voraussetzung für jede UI-Route), Mass-Action-Schutz.
|
||||
5. **Fehlende Dependencies** ergänzen (PLAN.md teils falsch): `signature_pad`,
|
||||
`browser-image-compression`, `react-grid-layout`, `@dnd-kit` (statt react-beautiful-dnd),
|
||||
`libphonenumber`, `ics`/`ical-generator`, `btree_gist`/`EXCLUDE`-Constraint u.a.
|
||||
|
||||
## AD-24 — Prod unter eigenem Hetzner-Account (dediziert, self-contained) ✅
|
||||
|
||||
**Entscheidung (2026-06-19, Owner Raffael):** Produktion läuft in einem **eigenen, dedizierten
|
||||
Hetzner-Cloud-Account**, vollständig getrennt von Staging/dev. Topologie — **5 VMs** (fsn1, x86 cx-Linie):
|
||||
- **control** — eigenes **Coolify** + Orchestrierung/Bastion (cx33: 4 vCPU/8 GB)
|
||||
- **web**, **api** (je cx33)
|
||||
- **worker + services** — 5 Worker-Queue-Gruppen + **self-hosted Meilisearch + ClamAV + mCaptcha** (cx43: 8 vCPU/16 GB)
|
||||
- **db** — Postgres + PgBouncer + Redis + Daten-Volume (cx33 + Volume)
|
||||
|
||||
mCaptcha nutzt die Postgres/Redis der db-VM (eigene DB), keine separate VM. Self-contained: eigene
|
||||
Zentral-Dienste (kein Zugriff aufs Staging-Privatnetz), eigener **DEK-Master-Key** (AD-8) + eigener
|
||||
**S3-Bucket** (`hivegrid-prod`, fsn1), eigenes Coolify.
|
||||
|
||||
**Ingress (Variante „Cloudflare-Proxy"):** Cloudflare **proxied** vor `app./api./captcha.` (Edge-TLS,
|
||||
DDoS/WAF, Origin-IP versteckt) → **Coolify/Traefik pro Host** (Let's-Encrypt am Origin). `admin.`
|
||||
restriktiv (dns-only + Firewall bzw. Cloudflare Access). **Kein Hetzner-Load-Balancer** bis zur
|
||||
horizontalen Skalierung — die App ist über serverseitige Sessions in Postgres+Redis (AD-4) dafür bereit;
|
||||
LB + 2+ web/api-Instanzen kommen nach Anhebung des VPS-Limits.
|
||||
|
||||
**Netzwerk:** privates Hetzner-Network + Firewall — `db`/`services` nur privat erreichbar, öffentlich
|
||||
nur 80/443 (web/api/control), SSH eingeschränkt.
|
||||
|
||||
**Warum:** Blast-Radius/Isolation (getrennte Tokens/Billing, kein Cross-Deploy-Unfall Staging↔Prod),
|
||||
saubere DSGVO-/Audit-Grenze, Crypto-Shredding-Grenze pro Account. Revidiert/erweitert die Infra-ADR-009
|
||||
(Hetzner+Coolify) um die Account-Trennung.
|
||||
|
||||
**Grenzen:** Hetzner-Default-Limit 5 VPS/Projekt → echtes HA (web1/web2 + api1/api2 hinter LB) erst nach
|
||||
Limit-Anhebung (Support). Provisionierungs-Schritte + Go-Gates: `docs/ops/prod-rollout-hivegrid.md`.
|
||||
|
||||
**Betrifft:** Prod-Deploy, Ops, alle Module.
|
||||
|
||||
## AD-25 — E-Signatur: gehärtete SES-Eigenbau, kein externer Provider (v1); QES-Add-on via DE-QTSP (v2) ✅ (NEU 2026-06-21)
|
||||
|
||||
**Entscheidung (2026-06-21, Owner Raffael):** HiveGrid baut die elektronische Signatur (Angebote/Aufträge/Abnahmen)
|
||||
für v1 **selbst als gehärtete SES** und macht das zum **Default für alle Tenants** — **kein externer Provider als
|
||||
Zwang**. **PandaDoc bleibt als optionale BYOK-Anbindung** erhalten: Tenants mit eigenem PandaDoc-Account tragen
|
||||
ihren **eigenen API-Key** ein und signieren über *ihren* Account (Opt-in). Damit ist die Annahme „PandaDoc ist der
|
||||
*zentrale/erzwungene* Provider" abgelöst (Abweichung vom Pflichtenheft V.4.4), PandaDoc selbst aber **nicht** —
|
||||
es wird vom Default zum **Opt-in-Adapter**. Betrifft AK-P16d, EXT-09, EXT-17, VR-P16.
|
||||
|
||||
**BYOK-Vorteil (CLOUD Act):** Bei BYOK nutzt der Tenant bewusst seinen *eigenen* PandaDoc — die CLOUD-Act-/Drittland-
|
||||
Verantwortung liegt damit beim Tenant (dessen Account, dessen Entscheidung), nicht bei HiveGrid. Das „100 % EU"-
|
||||
Default (SES-Eigenbau) bleibt unangetastet; PandaDoc ist eine transparente Opt-in-Wahl (Subprozessor-Liste/AVV).
|
||||
|
||||
**Begründung (dreifach belegt):**
|
||||
- **Rechtlich:** SHK-Dokumente sind formfrei oder Textform (§§ 631, 650i Abs. 2, 640 BGB) → **SES genügt** (auch
|
||||
beim Verbraucherbauvertrag, der nur Textform verlangt — keine QES). Einziger zwingender QES-Fall im ganzen SHK:
|
||||
**Kündigung eines Bauvertrags (§ 650h BGB)** — kein Tagesgeschäft, selten.
|
||||
- **Praxis:** Marktstandard im DE-Handwerk ist die **SES-Touch-Unterschrift vor Ort** (+ Fern-Link). Alle
|
||||
etablierten Tools (HERO, plancraft, Craftnote, ToolTime …) bieten SES; AES/QES spielt im Tagesgeschäft keine
|
||||
Rolle, **kein Marktdruck**. Wettbewerbsfaktor ist der Prozess (papierlos → schneller zur Rechnung), nicht die Stufe.
|
||||
- **Souveränität:** PandaDoc/DocuSign = US-Firmen → **CLOUD Act §2713**, bricht das „100 % EU"-Versprechen (A.12.4).
|
||||
EU-Provider geprüft (Yousign FR am besten; Skribble CH hat US-Subprozessoren/kein echtes Embedding/per-Seat). OSS
|
||||
geprüft (Documenso = nur SES + AGPL). **Eigenbau ist souveränster + günstigster + rechtlich ausreichend.**
|
||||
|
||||
**Umsetzung v1 (P16 / AK-P16d) — „gehärtete SES" (praktisch auf AES-Beweisniveau, ohne PKI-pro-Person/QTSP):**
|
||||
1. **Touch-Signatur vor Ort** (Canvas → PDF) + **Fern-Link-Signatur** (Angebot remote annehmen)
|
||||
2. **OTP-Identifizierung** (E-Mail; SMS als stärkere Zwei-Kanal-Variante)
|
||||
3. **PDF-Versiegelung** (PAdES mit HiveGrid-Organisations-Zertifikat → jede Änderung bricht die Signatur)
|
||||
4. **Zeitstempel** (TSA, RFC 3161; nicht-qualifiziert genügt für SES/AES)
|
||||
5. **Audit-Trail** über M001 (Link/Öffnen/OTP/Signatur: wer, wann, IP, Gerät, Geo, PDF-Hash; append-only)
|
||||
6. **Completion-Certificate** als PDF-Anhang (sichtbare Beweis-Doku)
|
||||
7. **Einmal-Link** (personengebunden) + expliziter **„Intent to sign"**
|
||||
> Beweiskraft: gehärtete SES wie AES unter freier Beweiswürdigung (§ 286 ZPO) — der Audit-Trail trägt, nicht das Stufen-Etikett. Anscheinsbeweis (§ 371a) hat nur QES.
|
||||
|
||||
**Architektur:** Signatur über `defineAdapter` (Apps-Engine, provider-agnostisch). Adapter:
|
||||
- **`ses-selfhosted`** — Default (v1), die gehärtete Eigenbau-SES.
|
||||
- **`pandadoc-byok`** — optional (v1), Tenant bringt eigenen PandaDoc-API-Key (DEK-verschlüsselt im Credential-Store); Mandanten-Trennung via eigener Account + Webhook-Routing (pro-Tenant-URL + `metadata.hivegrid_tenant_id`). Anbindungs-Spec: [[EXT-17]].
|
||||
- Spätere Optionen ohne Fachcode-Umbau: **AES** (Yousign managed oder EU-DSS-Library self-hosted, Java-Sidecar), **QES** (DE-QTSP **D-Trust sign-me**, Hash-only — Dokument bleibt im Perimeter) für § 650h-Bauvertragskündigung.
|
||||
|
||||
**Betrifft:** P16 (AK-P16d), EXT-09 (SES-Eigenbau-Default), EXT-17 (PandaDoc-BYOK-Adapter), VR-P16.
|
||||
PandaDoc bleibt als BYOK-Opt-in. Vor Produktivschaltung der Signatur: anwaltliche Bestätigung der Form-/Beweis-Einordnung (SES genügt, § 650h→QES).
|
||||
|
||||
**Pflichtenheft-Status (Pivot-Vorrang):** Abweichung von **V.4.4** (PandaDoc als zentraler/erzwungener Signatur-Provider) sowie von den Phase-1-App-Listen in Block 4 (33a.1.1 / 33a.1.4 / 33a.2.3). **Change-Request gegen das Pflichtenheft nötig (M176)**; bis dieser eingepflegt ist, gilt **AD-25 vor dem Pflichtenheft** (Pivot-Vorrang, analog AD-20/AD-26). PandaDoc bleibt in den Listen, wechselt aber vom *Default* zum *Opt-in-Adapter*. **Offen (mit M176):** Pivot-Hinweis an der V.4.4-/PandaDoc-Stelle im Pflichtenheft + Aufnahme in die CR-Liste.
|
||||
|
||||
## AD-26 — KI-Pivot: MCP-only, kein selbst-gehostetes LLM/RAG (löst die KI-Hälfte von AD-16 ab) ✅ (NEU 2026-06-22)
|
||||
|
||||
**Entscheidung (2026-06-22, Owner Raffael):** HiveGrid hostet **kein** eigenes LLM/RAG/HiveMind mehr. Statt eine KI-App
|
||||
zu sein, wird HiveGrid **KI-anschließbar** über einen **MCP-Server** (Model Context Protocol): externe KI-Clients
|
||||
(Claude Desktop/Cursor/ChatGPT) docken an, **Inferenz liegt beim Client**. Damit entfällt der EU-LLM-Provider-/DSGVO-
|
||||
Zwang für HiveGrid selbst (kein Mistral/Scaleway/AlephAlpha-Hosting mehr). Löst die **KI-Hälfte von AD-16** ab — die
|
||||
**Automation-Säule bleibt**.
|
||||
|
||||
**Begründung:** Kleines Team; der teure/harte Teil (LLM-Hosting, RAG-Infra, Promptfoo-Eval, AiCredits-Abrechnung,
|
||||
EU-Provider-Compliance) fällt weg. MCP nutzt **dieselbe mandanten-gescopte Daten-/Aktions-Fläche** wie die geplante
|
||||
Public-API ([[VR-P22a]]/[[VR-P22b]]) → keine Doppelarbeit.
|
||||
|
||||
**v1 (KI komplett gestrichen):** R-P13 (KI-Layer/Mistral-Gateway) + D-P13 entfernt, EXT-11 + Mistral-Key gelöscht,
|
||||
Milestones **M083–M088 gelöscht**, R-P12b verliert den Sprach→Automation-Teil (bleibt reiner visueller Flow-Editor).
|
||||
Neues letztes v1-Glied = R-P12b (~1 Tag Puffer → Härtung). Freeze/Launch **09./10.07.** bleiben fix.
|
||||
|
||||
**v2:** VR-P25/VD-P25 (HiveMind/RAG/Whisper) **gestrichen** (Plane: Cancelled) → neu **VR-MCP + VD-MCP** im Slot
|
||||
**18.–20.07.**, `blocked-by` VR-P22a/b (Public-API, fertig 17.07. → kein Konflikt).
|
||||
|
||||
**Public-API-/MCP-Surface (2026-07-03, verbindlich):** Public API läuft ausschließlich auf
|
||||
`api.hivegrid.de` (staging: `staging-api.hivegrid.de`) mit Versionierungs-Prefix `/v1/...`; es gibt keine
|
||||
Public-API-Routen unter `app.hivegrid.de/api`. MCP läuft ausschließlich auf `mcp.hivegrid.de` (staging:
|
||||
`staging-mcp.hivegrid.de`) als eigener Coolify-Service/Container `hivegrid-mcp` mit eigener Runtime (`apps/mcp`),
|
||||
ohne zusätzlichen `/mcp`-Pfad.
|
||||
Auth/Scopes/Rate-Limit werden aus der Public-API-Schicht wiederverwendet, aber die Runtime-/Host-Surface bleibt
|
||||
getrennt.
|
||||
|
||||
**MCP-Design (Best-Practice, MCP-Spec-Rev 2025-11-25):** Remote-Server über **Streamable HTTP** (stateless Start),
|
||||
SDK **`@modelcontextprotocol/sdk`**. **Auth v1 = OAuth 2.1 Authorization Code + PKCE** mit Protected-Resource-Metadata
|
||||
(RFC 9728), Authorization-Server-Metadata (RFC 8414), Resource-/Audience-Bindung und Consent. API-Key-Bearer aus VR-P22
|
||||
bleibt nur als Operator-/Fallback-Pfad, nicht als primärer User-Connect-Flow. **Tenant aus dem Token** (nie aus Tool-Argumenten) → `withTenantScope()` + RLS.
|
||||
**Read-Tools + Write-Tools** (`withPermission()` + Client-Confirmation + `auditEvent`/`logActivity`). Annotations
|
||||
(`readOnlyHint`/`destructiveHint`) nur als Hint — echte Guards serverseitig. Rate-Limit + Output-Limits + Pagination;
|
||||
Tenant-Daten sind **Daten, nie Instruktionen** (Prompt-Injection).
|
||||
|
||||
**Code-Rip-out (Variante a):** raus = `packages/ai`, `packages/vector-store`, Module ai/ai-gen/ai-cost/chatbot/
|
||||
ai-elements, AI-Routen, Worker-AI-Jobs, `ai.prisma` — UND die Legacy-PromptFlow-Engine (promptBuilder/admin/prompts/
|
||||
`promptFlows.prisma`). **Bleiben:** `@modelcontextprotocol/sdk`, `modules/mcp/`, der EU-Sterilisations-Guard.
|
||||
|
||||
**Pflichtenheft:** A.12.3 (EU-LLM-Provider) und V.2.2 („KI als Bedienoberfläche der Automation") widersprechen jetzt →
|
||||
**Change-Request (M176) nötig**; bis dahin gilt diese AD vor dem Pflichtenheft (Pivot-Vorrang). Anti-Liste V.3.2.7
|
||||
(HiveMind autonom) bleibt erfüllt (wird gar nicht gebaut).
|
||||
|
||||
**Betrifft:** R-P13/D-P13/EXT-11/M083–M088 (entfernt), R-P12b (Trim), VR-P25/VD-P25 (gestrichen), VR-MCP/VD-MCP
|
||||
(neu), R-P11a/R-P11b/D-P3/R-P5/D-P5/D-P20 (KI-Andock umdeuten/trimmen), VA-P24b/VA-P29/VR-P31/VR-P33 (KI-Teile entfallen).
|
||||
|
||||
## AD-27 — Billing-Recut: Lago self-hosted + Mollie Payments, kein Legacy-Provider-Default ✅ (NEU 2026-07-04)
|
||||
|
||||
**Entscheidung (2026-07-04, Owner Raffael):** HiveGrid nutzt **kein Legacy-Provider** als Billing- oder Payment-Default,
|
||||
weil kein relevantes CLOUD-Act-Risiko in der zentralen Billing-Abhängigkeit akzeptiert wird. Billing wird in drei
|
||||
Schichten getrennt:
|
||||
|
||||
1. **HiveGrid** bleibt Produkt- und Zugriffsschicht: Tenants, Seats, Plan-Status, Feature-Gates, Read-only/Frozen-State.
|
||||
2. **Lago self-hosted** wird Billing-Engine: Plans, Seats, Subscriptions, Invoices und Billing-Status.
|
||||
3. **Mollie** wird v1-Payment-Processor: Checkout/Zahlung, Payment-Status, Refund-/Failure-Events. Mollie wird **nicht**
|
||||
zur Billing-Source-of-Truth und nicht fuer Invoicing genutzt.
|
||||
|
||||
**v1-Scope:** nur **Plans + Seats**. Kein Usage-Billing, keine Credits, keine Add-on-Metering-Logik, keine oeffentlichen
|
||||
Preisversprechen im Code. Bestehende Usage-/Quota-Felder duerfen als technische Altlast bleiben, werden aber nicht als
|
||||
neuer Billing-Scope erweitert.
|
||||
|
||||
**Invoicing:** Lago erzeugt die fachliche Rechnung/Invoice-Records. Rechnungssteller und finale Rechnungs-/Steuerlogik
|
||||
werden entschieden, wenn die rechtliche/gesellschaftliche Struktur feststeht. Bis dahin bleibt die Umsetzung auf
|
||||
technisches Invoicing + Testdaten begrenzt.
|
||||
|
||||
**Infrastruktur:**
|
||||
- **Staging:** eine geteilte `lago-staging`-Instanz im Estate-Coolify auf `node1-estate`, aktuell intern erreichbar.
|
||||
Mehrere Staging-Services koennen dieselbe Instanz nutzen, solange Testkunden/Plans sauber ueber Codes/Metadata
|
||||
getrennt werden.
|
||||
- **Production:** bekommt spaeter eine eigene `lago-production`-Instanz im HiveGrid-Prod-Setup. Staging und Prod werden
|
||||
**nicht** in derselben Lago-Instanz gemischt.
|
||||
- Lago bleibt als separater Service angebunden. Keine Lago-Core-Patches im HiveGrid-Repo. Falls Lago-Code angepasst
|
||||
werden muesste, ist wegen AGPL-3.0 vorher Legal-/Lizenz-Entscheidung oder Commercial-License-Pfad erforderlich.
|
||||
|
||||
**Payment-Minimierung:** Mollie erhaelt nur Billing-/Payment-Minimum: Customer-Referenz, Invoice-Referenz, Betrag,
|
||||
Zahlungsmethode und noetige Kontaktdaten. HiveGrid-Fachdaten, CRM-Inhalte, Projektinhalte und MCP-Daten werden niemals
|
||||
an Mollie oder Lago gesendet.
|
||||
|
||||
**Abgeloeste Annahmen:** Die aktiven Billing-Ticketdocs wurden in `BILL-00` auf Lago/Mollie recuttet. Alte
|
||||
Legacy-Provider-Erwaehnungen in historischen Umsetzungsnotizen, Roadmap-/Milestone-Alttexten oder Legacy-Code sind
|
||||
Migrationsinventar und duerfen nicht als Zielarchitektur gelesen werden.
|
||||
|
||||
**Betrifft:** AK-P20, D-P20, VA-P24a/b, VD-P24, AK-P19, AK-P21, EXT-07, EXT-16, H-PAYLINK, R-P1b/Feature-Gates.
|
||||
|
||||
## AD-28 — Interim-UI: Dev baut Vorschau-Screens aus `~/ui`, finale Optik wird getrackter Nachzug ✅ (NEU 2026-07-04)
|
||||
|
||||
**Entscheidung (2026-07-04, Owner Akeshan + Raffael):** UI-lastige Dev-Tickets bleiben **nicht** bis zu
|
||||
Davids finalem Screen-Delta auf „On Hold". Stattdessen baut der Dev eine **Interim-UI** (Vorschau-Screen)
|
||||
aus den bereits im Repo gesyncten Subframe-Components (`apps/web/app/ui/`, Alias `~/ui/*`) und stellt das
|
||||
Ticket damit fertig. Präzisierung der Done-Definition für solche Tickets: Ein Ticket ist **Done-fähig**,
|
||||
sobald **Dev-DoD 100 % + Interim-Screen aus `~/ui` (VM als Prop, kein handgeschriebenes Tailwind) + Tests
|
||||
grün** sind. Die **finale Subframe-Optik** ist dann **kein Done-Blocker** mehr, sondern ein **getrackter
|
||||
Nachzug** (Plane-Label `design-nachzug` + „Dev-Nachzug"-Sektion der Ticket-Doc + Interim-Visual-Baseline,
|
||||
die beim Nachzug neu gezogen wird).
|
||||
|
||||
**Goldene Regel:** Interim-Screens werden aus `~/ui`-Components + `~/ui/layouts/*` komponiert und beziehen
|
||||
ihre Daten aus dem bestehenden View-Model (`packages/view-models/**`). Handgeschriebenes Tailwind statt
|
||||
`~/ui` ist ein PR-Block — nur die `~/ui`-Komposition hält den späteren Tausch gegen Davids Screen billig
|
||||
(Component-Swap hinter stabiler VM/Loader-Grenze, Hot-Swap-Gedanke M015/M017). Die drei Anti-Patterns und
|
||||
die Layer-Trennung (Abschnitt „Drei Anti-Patterns") bleiben unangetastet.
|
||||
|
||||
**Warum:** Davids Screens dauern noch lange, während die Component-Basis (79 `~/ui`-Components + Layouts,
|
||||
gesynct via `.subframe/sync.json`) und die View-Models bereits stehen. Die Designer-first-Reihenfolge
|
||||
bleibt erhalten — David überschreibt/finalisiert weiterhin —, aber Backend-Tickets werden nicht länger
|
||||
formal von leeren `D-*`-Deltas blockiert. Begriff „Interim-UI" ist bewusst von `packages/ui-mock`
|
||||
(M017-Hot-Swap-Drop-in) abgegrenzt.
|
||||
|
||||
**Betrifft:** alle UI-lastigen Dev-Tickets v1+v2 (Akeshan + Raffael), u. a. R-P2/P8/P9/P11/P12,
|
||||
AK-P3/P4/P14/P16/P17/P19/P20/P21, VR-P22b, VR-MCP; sowie den `plan-ticket`-Command und die Designer-first-
|
||||
Regel in `.planning/ticket-docs/README.md`.
|
||||
|
||||
**Anker:** `.planning/INTERIM-UI-PLAYBOOK.md` (ausführliches Wie) · `.planning/INTERIM-UI-DESIGN-STANDARDS.md`
|
||||
(Davids Layout-/Komponenten-/State-Werte als In-Repo-Spiegel von `../HiveGrid-Wireframes/`, damit die
|
||||
Interim-UI nah an Davids finalen Screens landet) · `.claude/commands/plan-ticket.md` (§4/§5/§8) ·
|
||||
`AGENTS.md` (Ein Ticket bauen + DoD) · `docs/INTEGRATION-CONTRACTS.md` (§12) · `.planning/ticket-docs/README.md`
|
||||
(Konvention „Dev-Nachzug"/Interim-UI-Vermerk).
|
||||
|
||||
## AD-29 — Rollen-Seed: Produktion startet admin-only, SHK-Seeds nur Staging/Dev ✅ (NEU 2026-07-07)
|
||||
|
||||
**Entscheidung (2026-07-07, Owner Akeshan):** Auf **Produktion** startet ein frischer Tenant nur mit der
|
||||
**Admin-Systemrolle** — die 6 SHK-Standard-Rollen (Geschäftsführer, Projektleiter, Verwaltung, Vertriebler,
|
||||
Kundensupporter, Monteur; Partner-Liste 2026-06-19) werden dort **nicht** mehr automatisch geseedet. Auf
|
||||
**Staging/Dev** bleiben die SHK-Seeds als Test-Komfort aktiv. Damit ist der Widerspruch zwischen dem
|
||||
R-P2b-Seed (Owner-Entscheidung Raffael) und Davids validierter D-P2-Design-Entscheidung („zum Start nur
|
||||
die Systemrolle Admin, keine vorgebauten Seed-Rollen") zugunsten des Designs aufgelöst; die SHK-Liste
|
||||
bleibt als Definition erhalten (perspektivisch Rollen-**Vorlagen**, Davids WIP-Konzept in M04A).
|
||||
|
||||
**Mechanik:** Gate `shouldSeedShkRoles()` in `apps/web/app/utils/services/shkRoles.server.ts` —
|
||||
`SENTRY_ENVIRONMENT=production` ⇒ kein Seed. Bewusst die **deploy-scoped** Variable (Estate-Standard §1),
|
||||
weil `NODE_ENV` auf Staging-Containern ebenfalls `production` ist; lokal (ohne `SENTRY_ENVIRONMENT`)
|
||||
entscheidet `nodeEnv`. Override in beide Richtungen per `SEED_SHK_ROLES=true|false`, falls der Partner
|
||||
die Seeds produktiv doch will. Die übrige Auto-SHK-Provisionierung (AK-P20: Pipelines, Custom-Felder,
|
||||
Form-/Projekt-Templates, Checkliste) ist **nicht** betroffen — nur der Rollen-Seed.
|
||||
|
||||
**Betrifft:** R-P2b (DoD „6 SHK-Rollen geseedet" gilt Staging/Dev), AK-P20 (`provisionShkTenantDefaults`
|
||||
ruft den Rollen-Seed weiter auf, er no-opt auf Prod), D-P2/S02 (Rollen-Liste zeigt auf Prod initial nur
|
||||
Systemrollen), `REQUIREMENTS.md` REQ-auth-rbac, `ROADMAP.md` Phase-2-SC 4.
|
||||
|
||||
## KWP (separater Strang — siehe `_bmad-output/specs/M19-kwp-integration.md` und `docs/milestones/M19-KWP-API-RECUT.md`)
|
||||
|
||||
KWP bekommt eine offizielle **API-Anbindung** → M089 (Windows-Sync-Programm) entfällt,
|
||||
M090/M091/M092/M094/M095 vereinfachen sich, M093 bleibt. KWP als `DataConnection type='rest-api'`
|
||||
ins Apps-Engine-Muster (M33a). M089–M095 vor Umsetzung neu schneiden.
|
||||
# HiveGrid 2.0 — Entscheidungsregister
|
||||
|
||||
**Stand:** 2026-08-02
|
||||
|
||||
Diese Datei sichert die Architekturentscheidungen und ihre IDs. Sie ist bewusst kein zweites
|
||||
Agenten-Handbuch:
|
||||
|
||||
- Operative, repo-weite Regeln stehen in `AGENTS.md`.
|
||||
- Das Datenmodell steht in `.planning/ENTITY-MODEL.md`.
|
||||
- Scope, Abhängigkeiten und DoD stehen in der jeweiligen Ticket-Doc.
|
||||
- Genehmigte Produktänderungen stehen in `docs/CHANGE-REQUESTS.md`.
|
||||
- Infrastrukturentscheidungen folgen `../infra/STANDARDS.md` und `../infra/decisions/`.
|
||||
|
||||
Die ausführliche Fassung vor diesem Recut bleibt über die Git-Historie erhalten. Dieses Register hält
|
||||
stattdessen pro ID nur den aktuellen Entscheid, den Grund und den maßgeblichen Anker fest.
|
||||
|
||||
**Status:** `aktiv` = bindende Zielarchitektur · `historisch` = Kontext, keine operative Regel ·
|
||||
`abgelöst` = durch eine neuere Entscheidung ersetzt.
|
||||
|
||||
## Aktive Kernentscheidungen
|
||||
|
||||
| ID | Entscheidung | Grund und Anker |
|
||||
|---|---|---|
|
||||
| **AD-1** | Mandantendaten werden durch Postgres-RLS mit `FORCE ROW LEVEL SECURITY`, kontextgebundene App-/Worker-Rollen ohne `BYPASSRLS` und tenant-sichere Nebenpfade geschützt. Neue Tabellen benötigen Policy und Contract-Gate. | Defense-in-depth gegen vergessene App-Filter. Operativer Vertrag: `AGENTS.md` §Row-Level-Security. |
|
||||
| **AD-2** | Fachmodelle sind typisierte Prisma-Tabellen. Der generische `Entity`/`Row`/`RowValue`-Builder erhält keine neuen Konsumenten und wird bei Berührung seiner Altmodule typisiert abgelöst. | Typen, Indizes, Constraints, Permissions und RLS bleiben fachlich prüfbar. Migration: `AGENTS.md` §Entity-Builder und `.planning/ticket-docs/R-P6B.md`. |
|
||||
| **AD-3** | Die Plattform-Admin-Welt nutzt eigene `AdminUser`-, Session-, RBAC- und MFA-Grenzen. Produktiv ist Authentik-OIDC der einzige Admin-Login; der lokale Passwort-Fallback bleibt development-only und fail-closed. | Kein Generalschlüssel zwischen Plattform und Mandanten. Anker: `AGENTS.md` §Kanonische lokale Login-Daten und Estate-Infrastruktur. |
|
||||
| **AD-4** | Sessions sind serverseitig; Postgres ist Source of Truth, Redis nur der schnelle Validierungs-Cache. Cookies enthalten ausschließlich die Sessionreferenz. | Dauerhaftes Revoke, Geräteliste und verlässliches Revoke-all. |
|
||||
| **AD-8** | Sensible Tenant-Daten und Provider-Credentials nutzen per-Tenant-DEKs mit Envelope-Encryption. Der aktuelle Wrapper nutzt getrennte Environment-Secrets (`CRYPTO_SECRET`), bleibt aber gegen einen externen Key-Wrapper austauschbar; Tenant-Löschung zerstört den DEK. | Begrenzter Blast-Radius und Crypto-Shredding. Anker: `packages/db/src/crypto/tenant-envelope.server.ts`, `docs/env-vars.md`. |
|
||||
| **AD-20** | CRM und Pipelines sind projekt-zentrisch: ein typisierter `Projekt`-Kern, Pipelines als konfigurierbare Views, Lead → Projekt; Deal/Auftrag sind keine eigenen Kernentitäten. | Ein konsistentes Domänenmodell statt paralleler Objektwelten. Source of Truth: `.planning/ENTITY-MODEL.md`. |
|
||||
| **AD-21** | Prisma bleibt ein Schema-Ordner. Neue Domänenmodelle erhalten eine eigene Datei; `core.prisma`/`accounts.prisma` bleiben minimale gemeinsame Kerne. Feature-Branches nutzen `db push`, die lineare Forward-only-Migration entsteht beim Merge. | Vermeidet Schema- und Migrationskonflikte bei paralleler Arbeit. Operativer Vertrag: `AGENTS.md` §Prisma-Schema & Migrationen. |
|
||||
| **AD-22** | GeoIP wird lokal aus einer MMDB aufgelöst. Persistiert werden HMAC-pseudonymisierte IPs und höchstens das Land, keine präzisen Geodaten. | Keine Übermittlung von Endnutzer-IPs an einen Geo-SaaS; Datenminimierung. Anker: `apps/web/app/modules/ipAddress/`. |
|
||||
| **AD-23** | Uploads liegen privat. Zugriff erfolgt über authentifizierte, tenant- und permission-geprüfte App-Routen oder eng begrenzte signierte URLs. DSGVO-Exporte werden wegen SSE-C ausschließlich durch die geprüfte App-Route gestreamt. | Kundendokumente dürfen nie durch erratbare oder dauerhafte Public-URLs erreichbar sein. |
|
||||
| **AD-29** | Jeder neue Workspace erhält fünf versionierte, editierbare SHK-Rollen; der Owner erhält nur die globale Rolle `Admin`. Bestehende Tenants werden nicht automatisch umgeschrieben. | Reproduzierbares produktionsgleiches Bootstrap ohne `SEED_*`-Runtime-Schalter. Anker: `apps/web/app/domain/tenant-bootstrap/`. |
|
||||
|
||||
## Aktive Plattform- und Produktentscheidungen
|
||||
|
||||
| ID | Entscheidung | Grund und Anker |
|
||||
|---|---|---|
|
||||
| **AD-5** | Suche ist selbst gehostetes Meilisearch mit `hivegrid-*`-Indizes, Tenant-Filter, Outbox-Indexer und SQL-Revalidierung. v1/v2 bleiben keyword-only; pgvector, Embeddings und RRF entfallen. Staging nutzt den Estate-Dienst, Produktion die dedizierte HiveGrid-Instanz aus AD-24. | Gute Keyword-Suche ohne eigene KI-/RAG-Infrastruktur. Anker: `docs/deploy/meilisearch.md`. |
|
||||
| **AD-6** | Mailjet ist Provider für transaktionale und Marketing-Mails. MailerSend ist keine Zielarchitektur. | EU-Anbieter und ein gemeinsamer Mailpfad. |
|
||||
| **AD-7** | Captcha ist self-hosted. `mCaptcha` bleibt der kompatible Default; `Cap` ist der eingecheckte Ersatzpfad. Google-, Cloudflare- und hCaptcha-Abhängigkeiten sind keine Zielarchitektur. | Kein externer US-Captcha-Subprozessor. Anker: `packages/captcha/`, `infra/mcaptcha/`, `infra/cap/`. |
|
||||
| **AD-9** | Bidirektionaler Chat nutzt WebSockets; einseitige Live-Updates nutzen SSE. Hocuspocus bleibt auf CRDT-Kollaboration begrenzt. | Passendes Transportmodell je Interaktion statt eines Universal-Realtime-Layers. |
|
||||
| **AD-10** | Produktcode und interne Contracts heißen ausschließlich `@hivegrid/*`, `HIVEGRID_*`, `hivegrid_*`, `x-hivegrid-*` und `hivegrid.*`. Externe Estate-Namen wie `toolctrl-labs` bleiben unverändert. | Keine parallelen Alt-Aliase oder fiktiven Paketpfade. Operativer Vertrag: `AGENTS.md` §Naming-Konvention. |
|
||||
| **AD-17** | Mobile ist in v1/v2 ausschließlich responsive Web/PWA mit Service Worker, IndexedDB/Offline-Queue und Web Push. Keine native App, kein Expo/Capacitor, kein App-Store-Scope vor v3. | Eine auslieferbare mobile Oberfläche ohne zweiten Client-Stack. |
|
||||
| **AD-24** | HiveGrid-Produktion läuft als Ausnahme zum Estate-Default in einem eigenen Hetzner-Account mit eigenem Coolify und fünf VMs. Gitea Registry, Sentry und Cloudflare bleiben geteilte, authentifizierte Dienste; Meilisearch, ClamAV und Captcha laufen innerhalb des Prod-Accounts. | Harte Blast-Radius- und Spin-off-Grenze. Autoritative Infra-Entscheidung: `../infra/decisions/016-hivegrid-prod-dedicated-account-and-coolify.md`; Runbook: `docs/ops/prod-rollout-hivegrid.md`. |
|
||||
| **AD-25** | Die Standard-E-Signatur ist eine gehärtete, selbst betriebene SES mit Intent, OTP, PDF-Versiegelung, Zeitstempel und Audit-Trail. PandaDoc bleibt optionales Tenant-BYOK; QES ist ein späteres DE-QTSP-Add-on. Vor Produktivfreigabe bleibt juristische Bestätigung Pflicht. | Souveräner Standardpfad bei erhaltener Provider-Option. Anker: `packages/integrations/src/adapters/ses-selfhosted.ts`, `.planning/ticket-docs/AK-P16d.md`. |
|
||||
| **AD-26** | HiveGrid hostet in v1/v2 kein LLM, RAG, Whisper oder HiveMind. KI-Clients bringen die Inferenz mit und greifen über den separaten MCP-Service auf permission- und tenant-gescopte Tools zu. | Kein eigener KI-Provider-, Modell- oder Tokenabrechnungs-Stack. Anker: `apps/mcp`, `.planning/ticket-docs/VR-MCP.md`. |
|
||||
| **AD-27** | Billing ist dreigeteilt: HiveGrid hält Produktrechte, Lago self-hosted hält Billing/Invoices, Mollie verarbeitet Zahlungen. Kein Usage-Billing in v1; Fachdaten werden nicht an Billing-/Payment-Provider übertragen. | Klare Source-of-Truth-Grenzen ohne Legacy-Provider-Default. Anker: `BILL-*`-Ticket-Docs und `docs/ops/lago-*.md`. |
|
||||
| **AD-28** | Fehlende finale Screens blockieren Dev-Tickets nicht. Der Dev baut eine getestete Interim-UI aus `~/ui` gegen stabile View-Models; die finale Subframe-Optik bleibt als `design-nachzug` getrackt. | Backend- und Integrationsarbeit bleibt lieferbar, ohne den Designer-Workflow zu umgehen. Operativer Vertrag: `AGENTS.md` und `.planning/INTERIM-UI-PLAYBOOK.md`. |
|
||||
| **AD-30** | Das Customer-Portal läuft auf einem eigenen Host und in der getrennten Runtime `hivegrid-portal`, zunächst aus demselben unveränderlichen Web-Image. Eigene Sessions, minimale DB-Rechte, Entitlement-Gates und verifizierte Custom-Domains sind Pflicht. | Öffentliche Endkunden-Surface braucht eine eigene Trust Boundary. Kommerzieller und Domain-Vertrag: `docs/CHANGE-REQUESTS.md` CR-001; Routen: `docs/INTEGRATION-CONTRACTS.md`. |
|
||||
| **AD-31** | Plattform-Leads gehören tenantlos in die Admin-Domäne von HiveGrid. Der separate `lead-inbox`-Dienst wird erst nach gesichertem Backfill, Cutover und Drain stillgelegt. | Kein zweites CRM und keine künstliche Tenant-Zuordnung für HiveGrids eigenen Vertrieb. Anker: `.planning/ticket-docs/R-LEADS.md`, `.planning/ticket-docs/VA-P28b.md`. |
|
||||
| **AD-32** | Der initiale KWP-Scope ist fachlich read-only: OAuth-Lifecycle und die feste Read-Allowlist sind erlaubt, KWP-Mutationen sind vor HTTP fail-closed gesperrt. Writeback braucht zuerst `VEXT-6` und eine neue ausdrückliche Produktfreigabe. | Kein spekulativer oder nicht auslieferbarer Schreibpfad. Vollvertrag: `.planning/KWP-API-CONTRACT.md`, CR-003/CR-005 und `VR-P32*`. |
|
||||
|
||||
## Historische oder abgelöste Entscheidungen
|
||||
|
||||
| ID | Status | Gesicherter Kontext |
|
||||
|---|---|---|
|
||||
| **AD-11** | historisch | Der ursprüngliche Baupfad „Fundament, Kernkette, Breite“ erklärt die frühe Reihenfolge. Operativ gelten heute Plane, Ticket-Docs und Roadmaps. |
|
||||
| **AD-12** | abgelöst durch AD-29 | Frühere SHK-Rollen-Seeds mit zehn beziehungsweise sechs Rollen wurden entfernt. Das deklarative Bootstrap-Prinzip lebt in AD-29 weiter. |
|
||||
| **AD-13** | historisch | Der frühe Produktentscheid war ein breiter Geerkens-Launch. Aktueller Lieferumfang und Termine werden ausschließlich über Requirements, Ticket-Docs und Plane gesteuert. |
|
||||
| **AD-14** | teilweise abgelöst durch AD-32 | Der saubere Start ohne vollständige HubSpot-/Quiply-Migrationspipelines bleibt Kontext. Die Annahme, KWP fülle den Bestand direkt per Vollsync, ist nicht mehr der aktuelle Vertrag. |
|
||||
| **AD-15** | abgelöst durch AD-27/AD-30 | Die alte Billing- und Preisparker-Entscheidung wurde durch Lago/Mollie und die ausdrücklich genehmigten Portalpreise ersetzt. Weitere Preise bleiben ohne CR unentschieden. |
|
||||
| **AD-16** | teilweise abgelöst durch AD-26 | Die Automation-Säule bleibt im Requirement-Scope. Der eigene KI-Layer ist vollständig gestrichen. |
|
||||
| **AD-18** | abgelöst durch AD-30 und P26-Tickets | Der alte „vollständiges Portal day-1“-Text ist kein Liefervertrag mehr. Runtime, Features und Rollout liegen in CR-001 und `VA-P26*`. |
|
||||
| **AD-19** | historisch | „Big Bang“ war eine frühe Go-live-Strategie. Aktuelle Release-, Pilot- und Sign-off-Entscheidungen liegen in Plane, Ticket-Docs und Runbooks. |
|
||||
|
||||
## Pflegevertrag
|
||||
|
||||
Eine neue oder geänderte Entscheidung aktualisiert in derselben Änderung:
|
||||
|
||||
1. die operative Regel in `AGENTS.md`, falls Agents sie beim Bauen beachten müssen,
|
||||
2. dieses Register mit Status und Verweis,
|
||||
3. die betroffenen Ticket-Docs/Contracts,
|
||||
4. bei Scope- oder Produktänderungen `docs/CHANGE-REQUESTS.md`.
|
||||
|
||||
Neue Langform-ADRs werden nur angelegt, wenn Trade-offs oder Rollback nicht sinnvoll in einem Ticket oder
|
||||
Infra-ADR dokumentiert werden können. Das Register darf nicht erneut zu einem parallelen Planungsarchiv
|
||||
anwachsen.
|
||||
@@ -0,0 +1,172 @@
|
||||
# HiveGrid Change-Requests
|
||||
|
||||
Diese Liste ist der vollständige Change-Request-Vertrag gemäß `AGENTS.md` §Produktgrenzen. Eine Änderung
|
||||
wirkt erst, wenn Datum, Initiator, betroffener Vertrag, gewünschte Änderung, Begründung,
|
||||
Aufwandsauswirkung, Entscheidung und Entscheidungsdatum dokumentiert sind. Genehmigte Änderungen müssen
|
||||
anschließend in den zuständigen aktiven Quellen und Ticket-Docs nachgezogen werden.
|
||||
|
||||
| ID | Datum | Initiator | Betrifft (Punkt-Adresse) | Was soll geändert werden | Warum (Begründung) | Auswirkung auf Aufwand | Entscheidung | Datum der Entscheidung |
|
||||
| ------ | ---------- | --------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
|
||||
| CR-001 | 2026-07-15 | Raffael / Produktteam | 15.1.1, 15.14.2, 27.14.2, 31.4.1, 31.4.6, 31.5.3, AD-15 | Das Customer-Portal erhält als Standard `portal.hivegrid.de/<tenant>/...` statt `app.hivegrid.de/portal/<tenant>/...`. Starter und Team können das Portal für 19,99 EUR netto/Monat je Workspace buchen; Business und Enterprise enthalten es. PortalUser und Projekte sind unbegrenzt, bestehende Plan-/Fair-Use-Limits für Speicher, Uploads und Mail bleiben. Eine eigene Portal-Subdomain kostet für Starter/Team/Business 299,99 EUR netto einmalig pro Einrichtung; Enterprise enthält eine Domain. Der Standardhost bleibt Fallback. Domain-Wechsel sind eine neue Einrichtung. | Das Portal ist eine eigenständige Endkunden-Oberfläche und ein vermarktbares Add-on. Eine eigene Kundendomain stärkt das Branding, soll aber ohne Einzelprojekt durch HiveGrid self-service-fähig sein. | `VA-P26a` wird um den separaten Runtime-/DB-Trust-Boundary erweitert und muss vor Baubeginn neu geschätzt/terminiert werden. Neuer Ticket-Scope `VA-P26c` für Entitlements/Checkout, Host-Auflösung, DNS-Verifikation, TLS/Ingress, Lifecycle, UI und Betrieb. Abhängigkeiten zu `VA-P26a`, `VA-P24a`, `VD-P26` und `VJ-3`; kein Termin wird durch diesen CR automatisch verschoben. Die endgültige Slice-Schätzung erfolgt im Ticketplan. | Genehmigt; am 2026-07-16 ergänzt: Business enthält das Portal, die Custom-Domain bleibt dort eine einmalige 299,99-EUR-Einrichtung; öffentlicher Produktstart erst nach `VA-P26b`, Domain-Cooldown 30 Tage. | 2026-07-16 |
|
||||
| CR-002 | 2026-07-17 | Akeshan | M011 (Notifications-Querschnitt), R-P5 DoD #4 (Connection-Health), AGENTS.md §Querschnitt-Hülle | M011 bekommt nicht-unterdrückbare, kritische Notification-Kategorien. `isNotificationEnabled` liefert für Kategorien in `CRITICAL_NOTIFICATION_CATEGORIES` (`packages/foundation`) immer `true`, unabhängig von jeder gespeicherten Präferenz. Die Präferenz-UI zeigt sie als gesperrte, immer-aktive Gruppe (kein Toggle, „Immer aktiv"-Hinweis). Die Connection-degraded/broken-Benachrichtigung aus R-P5 (Worker-Sweeps + Web-Health-Probe) wird auf die kritische Kategorie `critical` umgehängt und läuft einheitlich über `notify()`. | Eine kaputte Integration stoppt still den Sync eines Tenants; die Warnung muss den Besitzer erreichen, auch wenn er System-Benachrichtigungen abbestellt hat, analog zu nicht-abbestellbaren Transaktionsmails. Vorher fiel die Integrations-Kategorie `system` auf die `default`-Präferenz zurück und konnte durch das Abschalten von „Allgemein" unterdrückt werden. | Klein bis mittel. `isNotificationEnabled` + Set in `packages/foundation`, Locked-Registry + UI-Zweig in `packages/view-models`/`NotificationSettingsPage`, i18n de+en, zwei Integrations-Call-Sites. Baut auf PR #149 (R-P5 notify-RLS-Fix) auf; kein Termin wird verschoben. | Genehmigt (User-Freigabe im Chat 2026-07-17). | 2026-07-17 |
|
||||
| CR-003 | 2026-07-22 | Raffael / Produktteam | 4.6.14, 17.3.7, 19.2.1, 19.3.3, 19.7.1–19.7.3, M091, M094, M074, Phase 32, AD-32 | Der initiale Scope der KWP-Integration in v2-P5/Phase 32 ist read-only: HiveGrid verbindet sich per OAuth2, liest KWP-Daten und verarbeitet sie in HiveGrid, führt aber keine fachlichen KWP-Mutationen aus. Writeback einschließlich Project-/Auftrag-Create, `kwp.push_auftrag`, M091 sowie der Outbound-Anteile von M094 und M074 wird geparkt. | KWP stellt keinen Endpoint zur Neuanlage eines kaufmännischen Projekts/Auftrags bereit. Ohne belastbaren Providervertrag und kontrollierten Testpfad wäre eine generische Push-Queue oder ein anderer Schreibpfad nicht fachlich abnehmbar und könnte produktive KWP-Daten verändern. | Der bereits bewiesene Connector-/Health-Scope kann unabhängig abgeschlossen werden. Pull-, Sentinel-, Konflikt- und Inbound-Sync-Arbeit bleibt planbar. Writeback wird nicht gelöscht, sondern nach `VEXT-6` erst bei dokumentierten Operationen, Scopes/Rechten, Payloads, Fehler-/Idempotenzvertrag und erneuter Produktfreigabe als eigener Dev-Slice geschnitten. | Genehmigt. Initial/current KWP bleibt read-only; keine KWP-Mutationen. Writeback wird bis zu einem belastbaren Providervertrag und einer erneuten ausdrücklichen Freigabe geparkt. | 2026-07-22 |
|
||||
| CR-004 | 2026-07-23 | Raffael / Produktteam | M092/093, Phase 32, `VR-P32b`, `VR-P32d`, CRM-Projektadressen | `VR-P32b` und `VR-P32d` werden in einem gemeinsamen PR umgesetzt, intern strikt in der Reihenfolge Schutzschicht vor Projektimport. `VR-P32d` wird von einem behaupteten cursorlosen Vollabzug auf einen gezielten Projektimport erweitert: Suche, Detailansicht, explizites Create/Link nach Diff, stabile Status-Zuordnung sowie Bindung von Projekt-, Rechnungs- und Bauherradresse an bestehende oder bewusst neu angelegte CRM-Kontakte. Pro Rolle kann höchstens ein primärer Ansprechpartner gewählt werden. | Der bestätigte KWP-Vertrag bietet Projekt-Suche und Detailabrufe, aber keine garantierte Pagination für einen vollständigen Bestand. Ein Vollimport wäre daher nicht beweisbar. Der erste fachlich nutzbare read-only Slice muss ein ausgewähltes KWP-Projekt vollständig und wiederholbar mit HiveGrid-Projektkern und CRM verbinden. | Groß, geschätzt 14–20 Entwicklungstage inklusive Schutzschicht, persistenter Bindings, Polling, Interim-UI, Tests und CI. `VR-P32d` wächst von 7 auf 10 überprüfbare DoD-Punkte. `VR-P32c` konsumiert dieselbe Schutz-/Binding-Schicht; `VN-2` bleibt nachgelagerter Live-Proof. `VD-P32` bleibt Design-Nachzug und blockiert die Interim-UI nicht. | Genehmigt. Ein gemeinsamer PR ist zulässig; KWP bleibt fachlich read-only. Die lokale HiveGrid-Projektnummer bleibt erhalten, KWP-`projNr` ist eine externe Referenz. Erstimport löst keine Automationen aus; spätere Stage-Wechsel senden das bestehende Event mit `source=kwp`. Beim Trennen bleiben lokale Projekt-/CRM-Daten erhalten. | 2026-07-23 |
|
||||
| CR-005 | 2026-07-24 | Raffael / Produktteam | Phase 32, M089–M095, M074, `VR-P32c`, `VEXT-6`, AD-32 | Der KWP-Adapter wird gegen die vollständige aktuelle Tenant-OpenAPI inventarisiert. Von 554 dokumentierten Operationen liegen 113 in den fünf für HiveGrid lizenzierten `*-extern`-Scopes: 77 semantisch lesende und 36 mutierende Operationen. Alle 113 erhalten einen expliziten, schema-validierten Adaptervertrag und capability-spezifische Drift-Abdeckung. Die 77 Leseoperationen dürfen nur über eine feste Allowlist ausgeführt werden. Die 36 Mutationen werden als echte, fixture-validierte Verträge erfasst, bleiben aber im Runtime-Transport fail-closed gesperrt und werden weder als Action noch als Queue oder UI-Aktion registriert. | Der bisherige Drei-Operationen-Adapter deckt nur Projekt-Suche, Projektdetails und eine Adresse ab. Für Plantafel, Aktivitäten, Vorgänge, Archiv, Aufgaben und Material braucht HiveGrid den gesamten tatsächlich lizenzierten Vertragsraum, ohne einen generischen URL-Pass-through oder ungeprüfte Rohpayloads einzuführen. Gleichzeitig dürfen Staging- oder Kundendaten während der Adapterentwicklung nicht verändert werden. | `VR-P32c` wächst von 5 auf 9 überprüfbare DoD-Punkte und umfasst den vollständigen Scoped-Contract, 77 Read-Adapter, 36 gesperrte Mutation-Contracts und capability-spezifischen Sentinel zusätzlich zum bisherigen Inbound-Scope. Die vollständigen 554 Operationen werden inventarisiert; 441 Operationen außerhalb der lizenzierten fünf Scopes werden bewusst nicht ausführbar gemacht. `VEXT-6` bleibt 0/4, weil weiterhin Project-/Auftrag-Create, Provider-Idempotenzvertrag und freigegebener Live-Write-Testpfad fehlen. `VN-2` bleibt der kontrollierte Inbound-Live-E2E. | Genehmigt. Lesende Operationen dürfen auf Staging secretsicher und ohne Import-Nebenwirkung verprobt werden. Schreibende Operationen werden nur gegen Vertrags-Fixtures getestet; kein Live-Write ohne erneute gemeinsame Freigabe. Der Merge erfolgt als normaler Merge, nicht als Squash. | 2026-07-24 |
|
||||
| CR-006 | 2026-07-24 | Raffael / Produktteam | Phase 32, `VR-P32b`, `VR-P32d`, `VR-P32c`, `VN-2`, KWP-Projektkatalog | Eine bestätigte KWP-Verbindung startet automatisch einen read-only Projektkatalog-Lauf. `Projektampel/LoadProjekteNachFilter` entdeckt die im bestätigten Mandanten und in den KWP-Projektampel-Einstellungen sichtbaren Projektnummern; Worker reichern sie unter gemeinsamem Rate-Budget in begrenzten, replay-sicheren Batches an. Manuelle KWP-Suchen schreiben Treffer sofort in denselben tenant-/connectiongebundenen Cache. Die Importansicht sucht cache-first mit einem indizierten normalisierten Suchtext und ergänzt Treffer kontrolliert über die Live-Suche. Response-Drift wird für den Import nur anhand der tatsächlich konsumierten, Zod-validierten Felder bewertet; bekannte, aber ungenutzte OpenAPI-Felder mit providerseitig abweichender Nullable-Semantik pausieren die Capability nicht. Die Interim-UI wird gegen Überlappungen korrigiert und zeigt den Katalogzustand. | Der echte Staging-Payload liefert bei ungenutzten Adressfeldern wie `ortPstf`, `briefanrede`, `selekt1`, `selekt2` und `bank` `null`, obwohl die Tenant-OpenAPI dort nur Objekte beschreibt. Die konsumierten Projekt-/Adressfelder sind gültig; die bisherige Vollobjektvalidierung erzeugt daher einen falschen Capability-Stopp. Außerdem ist eine ausschließlich synchrone Provider-Suche bei großen Projektbeständen langsam und unnötig abhängig von KWP-Verfügbarkeit. | `VR-P32d` wächst von 10 auf 14 DoD. Neue tenant-scoped Katalogtabellen, Forward-only-Migration, RLS/Registry, Queue-Job, Maintenance-Scheduling, read-through Cache, trigram-indizierte Suche, Katalogstatus im VM und fokussierte Worker-/Route-/Visual-Tests. `VR-P32b` behält echte semantische Drift als Pause-Grund; `VR-P32c` konsumiert weiter denselben Read-only-Transport. `VN-2` bleibt der kontrollierte Live-Importbeweis. | Genehmigt durch ausdrücklichen User-Auftrag im Chat. KWP bleibt fachlich read-only. Es wird kein leerer `Projekt/Search`-Aufruf und kein garantierter providerweiter Vollbestand behauptet: `LoadProjekteNachFilter` ist laut Vertrag ein einstellungsabhängiger sichtbarer Projektplatzhalter-Bestand ohne Pagination. Der lokale Katalog ist für große Bestände ausgelegt und wird asynchron vervollständigt; kein Request hält eine lange DB-Transaktion offen. Merge ausschließlich als normaler Merge-Commit, niemals Squash. | 2026-07-24 |
|
||||
| CR-007 | 2026-07-27 | Raffael / Produktteam | M006, `R-LEADS`, `VA-P28b`, `AK-SET-01`, `VA-P26a/b/c` | Die fertigen Kernfunktionen Plattform-Leads, Gruppenverwaltung und Kundenportal werden nicht mehr durch die globalen Flags `platform_admin_leads`, `row-groups` und `customer-portal` geschaltet. Sie sind standardmäßig verfügbar und werden ausschließlich durch Identität, Permissions, Tenant-/Subscription-Zustand und Portal-Entitlements begrenzt. Vorhandene Flag-Zeilen werden als Audit-Tombstones archiviert und aus Auswertung sowie Verwaltung ausgeblendet. Der externe Lead-Ingress-Schalter bleibt als separater operativer Sicherheitsschalter bestehen. | Ein fehlender Datenbank-Flag-Eintrag erzeugte auf Staging trotz korrekter Berechtigung eine tote Admin-Route (404). Abgeschlossene Produktfunktionen dürfen nicht von manuell gepflegten Rollout-Daten abhängen. | Mittel. Web, Worker, RLS-Vertrag, Seed-/Bootstrap-Pfade, Flag-Verwaltung, Tests, Migration und Betriebsdokumentation werden gemeinsam nachgezogen. Bestehende Permission-, RLS-, Subscription- und Entitlement-Grenzen bleiben unverändert. | Genehmigt durch ausdrücklichen User-Auftrag im Chat: standardmäßig aktivieren und die drei Flags entfernen. | 2026-07-27 |
|
||||
| CR-008 | 2026-07-30 | Raffael / Produktteam | `BILL-10`, `BILL-11`, `VA-P24a`, `AK-P14b`, Billing-Checkout und Verbrauchsanzeige | HiveGrid erhält vor dem Mollie Hosted Checkout eine eigene, serverseitig aus der Mollie Methods API geladene Zahlungsmethoden-Auswahl. Tarif- und Add-on-Käufe zeigen Preis, Leistung und Zahlart zusammenhängend in HiveGrid; die Bank-/3DS-Bestätigung bleibt als sicherer Top-Level-Handoff bei Mollie. Produktkäufe erhalten einen tenant-gebundenen Return-Flow. Speicher- und E-Mail-Marketing-Verbrauch werden read-only gegen die bereits erzwungenen Quoten sichtbar. Ein Wechsel des E-Mail-Marketing-Pakets aktiviert das neue Kontingent erst nach bestätigter Zahlung und beendet das alte Paket danach atomar mit durablem Provider-Cleanup. | Wenige Tage vor dem Pilot sollen Checkout, Rückkehr und Freischaltung wie ein zusammenhängender HiveGrid-Flow wirken. Nutzer müssen vor dem Kauf wissen, welche Zahlart, Leistung und Auslastung gelten. Das alte „erst kündigen, dann neu buchen“ erzeugt eine unnötige Funktionslücke; ein voreiliges Kündigen vor Zahlung wäre dagegen abrechnungsgefährlich. | Mittel bis groß. Mollie-Gateway-Vertrag, Billing-VM/Interim-UI, Add-on-Ledger-/Webhook-Sync, Return-Route, Usage-Queries, i18n, Visual-/Hot-Swap-/Route-/Provider-Tests und kontrolliertes Staging-E2E werden gemeinsam nachgezogen. Keine neue Usage-Abrechnung, kein Iframe und keine Abhängigkeit von Mollies privater Checkout-Session-Beta. `BILL-08` / `EXT-16` bleiben unveränderte Production-Gates. | Genehmigt durch ausdrücklichen User-Auftrag im Chat am 2026-07-30: alle offenen Billing-Nachzüge fertigstellen und die Mollie-Zahlung sauber in HiveGrid einbetten. | 2026-07-30 |
|
||||
| CR-009 | 2026-07-31 | Raffael / Produktteam | Registrierung, `BILL-11`, `BILL-13`, Billing-Checkout | Die Registrierung erhält nach den Kontoangaben eine separate Teamgrößen-Seite. Der Nutzer gibt Büro- und Monteur-/Baustellen-Nutzer an; HiveGrid berechnet mit dem kanonischen Monatskatalog für Core, Swarm und Colony jeweils Basis- plus Zusatznutzerpreis und empfiehlt die günstigste Konfiguration. Die Empfehlung bleibt überschreibbar. Gewählte Mengen und Tarif werden bis nach der E-Mail-Verifizierung persistiert und im bestehenden Billing-/Mollie-Checkout vorausgefüllt. | Die bisherige statische Tarifliste verlangt vom Nutzer, Inklusivmengen und Zusatznutzerpreise selbst gegeneinander zu rechnen. Eine nachvollziehbare Empfehlung reduziert Fehlbuchungen und macht den Weg von Registrierung zu Zahlung konsistent. | Mittel. Reiner Empfehlungscontract, zweistufige Interim-UI, optionale Felder am Pre-Auth-Registrierungsdatensatz, sichere Replay-/Verifizierungsübergabe, Billing-VM-Prefill, Forward-only-Migration sowie Unit-, Route-, A11y-, Visual- und Hot-Swap-Tests. Preise, Planleistungen, Lago-/Mollie-Verträge und Production-Gates bleiben unverändert. | Genehmigt durch ausdrücklichen User-Auftrag im Chat am 2026-07-31. | 2026-07-31 |
|
||||
| CR-010 | 2026-08-01 | Raffael / Produktteam | Tenant-Bootstrap, `VA-P26a`, `VA-P26c`, Customer-Portal-Admin | Jeder Tenant erhält beim Bootstrap atomar einen unveröffentlichten Customer-Portal-Scaffold; bereits bestehende Tenants ohne Portal werden einmalig idempotent nachgezogen. Der Scaffold übernimmt Tenant-Slug und -Name, veröffentlicht nichts und erzeugt keinerlei Billing-, Entitlement-, Checkout- oder Domain-Zustand. | Der vollständige Staging-UAT nach der Registrierung hat gezeigt, dass die Portal-Admin-Routen einen vorhandenen Portal-Datensatz voraussetzen, während der normale Tenant-Bootstrap keinen erzeugt. Frische zahlende Tenants landeten deshalb vor dem Portal-Add-on-Kauf auf einem generischen 500er. | Klein. Eine zusätzliche Query in der bestehenden Bootstrap-Transaktion, eine konfliktprüfende Forward-only-Datenmigration, fokussierte Unit-/Performance-/Migrationsverträge sowie erneuter Staging-UAT des Portal-Add-on-Kaufs. Keine Preis-, Entitlement-, RLS- oder Veröffentlichungsänderung. | Genehmigt durch ausdrücklichen User-Auftrag im Chat, alle Billing- und Customer-Portal-Flows bis zum erfolgreichen Staging-Test fertigzustellen. | 2026-08-01 |
|
||||
| CR-011 | 2026-08-01 | Raffael / Produktteam | `BILL-14`, `BILL-15`, `BILL-11`, wiederkehrende Produktkäufe und Rechnungsinkasso | Wiederkehrende Add-on-Käufe spiegeln nach bestätigter Mollie-Zahlung die exakte initiale Lago-Rechnung als bezahlt. HiveGrid persistiert die getrennten Lago-Providerreferenzen, unterscheidet `subscription_starting` strikt von `subscription_periodic`, markiert die bereits per Checkout bezahlte Erstrechnung idempotent und lässt ausschließlich echte Folgerechnungen in das wiederkehrende Mollie-Inkasso. Bestehende aktive Käufe werden über den bounded 5-Minuten-Reconciler tenantweise nachgezogen. | Der vollständige Staging-UAT hat bewiesen, dass E-Mail-Marketing und Customer-Portal korrekt freigeschaltet werden, ihre Lago-Rechnungen aber auf „Ausstehend“ bleiben. Gleichzeitig fehlt dem lokalen Produkt-Mirror die Lago-Provider-Subscription-ID; eine spätere Invoice-Webhook-Wiederholung könnte die Erstrechnung nicht sicher von einer Folgerechnung unterscheiden. Das ist ein Rechnungs- und potenzielles Doppelabbuchungsrisiko vor dem Pilot. | Mittel. Zwei nullable Provider-Mirror-Felder, Forward-only-Migration, erweiterter Lago-Invoice-Contract, exakte Outbox-Side-Effects, bounded Self-Heal im bestehenden Reconciler, Initialrechnungs-Gate vor dem Recurring-Collector sowie Unit-, Worker-, API-, Migration-, RLS- und Staging-E2E-Proof. Preise, Entitlements und Mollie-Live-Gates bleiben unverändert. | Genehmigt durch den ausdrücklichen User-Auftrag im Chat, alle Billing-Flows vollständig fertigzustellen, mit Mollie-Testzahlungen live zu prüfen und sichere Launch-Fixes selbstständig umzusetzen. | 2026-08-01 |
|
||||
| CR-012 | 2026-08-01 | Raffael / Produktteam | `EXT-02`, Signup-Willkommensmail, `packages/mail` Mailjet-Adapter | Mailjets `CustomID` wird auf den im Staging-Sandbox-Test bestätigten 64-Zeichen-Vertrag begrenzt. Kurze IDs bleiben lesbar; längere Replay-Keys erhalten eine deterministische SHA-256-Korrelation mit exakt höchstens 64 Zeichen. Sender, Template, Queue, Retry- und Idempotenzvertrag bleiben unverändert. | Frische direkte Registrierungen erzeugen einen 93 Zeichen langen Welcome-Replay-Key. Mailjet akzeptiert im Sandbox-Proof 64 Zeichen, weist 65 und mehr jedoch mit `mj-0006` zurück. Die bisherige 100-Zeichen-Annahme ließ dadurch jede Welcome-Delivery dauerhaft fehlschlagen. | Klein. Ein Provider-Normalizer, fokussierte Grenz-/Kollisions-/Replay-Tests, Full-Gate, Staging-Deploy und Zustellproof an einem frischen Test-Signup. Keine neue Mail, kein Providerwechsel und kein Eingriff in Marketingversand. | Genehmigt durch den ausdrücklichen User-Auftrag im Chat, nach Billing auch Willkommens-E-Mails und die SaaS-Onboarding-Experience bis zum Staging-Proof zu prüfen und sichere Launch-Fixes umzusetzen. | 2026-08-01 |
|
||||
| CR-013 | 2026-08-01 | Raffael / Produktteam | Phase 32, `VR-P32c`, `VN-2`, KWP-Inbound-Runtime | Die vier KWP-Inbound-Bereiche Termine, Aufgaben, Material und Archiv werden voneinander entkoppelt. Termine, Aufgaben und Material laufen weiter alle 15 Minuten und werden je Bereich unabhängig übernommen. Das Archiv wird höchstens alle sechs Stunden in fortsetzbaren Fünf-Ordner-Batches bis zu einer Sicherheitsgrenze von 1.000 Ordnern entdeckt. Jede Datei bleibt ein eigener Job mit drei Versuchen und exponentiellem 60-Sekunden-Backoff. Temporäre Archiv-Providerfehler lassen die Connection aktiv und erscheinen als Dateifehler mit automatischem Retry statt als Reconnect-Aufforderung. | Der kontrollierte Staging-Read zeigte 35 zugängliche Archivordner und überschritt damit die bisherige harte 20-Ordner-Grenze. Drei repräsentative `archivExternalExportDatei`-Reads lieferten reproduzierbar HTTP 500, obwohl OAuth, Tokenrotation, Health und alle sechs Capabilities aktiv blieben. Der bisherige gekoppelte Vollsnapshot verwarf dadurch auch gesunde Kerndomänen und erzeugte 111 fehlgeschlagene Vollwiederholungen in 24 Stunden. | Mittel. Keine Schema- oder KWP-Write-Änderung. Neue resumierbare Queue-Payloads, tenant-sichere Archivauflösung, bereichssichere Missing-Reconciliation, Retry-Klassifizierung, Klartextstatus und fokussierte Integrations-/Worker-/Queue-Tests. `VR-P32c` bleibt implementiert; `VN-2` bleibt bis zum kontrollierten Staging-Importbeweis offen und `VH-1` bis dahin blockiert. | Genehmigt durch den ausdrücklichen User-Auftrag im Chat, den permanenten Fix vollständig umzusetzen, auszurollen und kontrolliert zu beobachten. CR-003/AD-32 bleibt unverändert: keinerlei fachliche KWP-Mutation. | 2026-08-01 |
|
||||
| CR-014 | 2026-08-01 | Raffael / Produktteam | `BILL-13`, `BILL-11`, dedizierter Billing-Usage-Tab | Der separate Usage-Tab verwendet für Speicher dieselbe RLS-gebundene, kommerzielle Kapazitätsprojektion wie die Billing-Hauptseite und die Upload-Grenze. Verbrauch ist gespeicherte plus laufend reservierte Bytes; Limit ist Basistarif plus feste Speicher-Add-ons. Ein nicht sicher bestimmbares Limit wird als Klartext-Fehler statt als „kein Limit“ dargestellt. | Der abschließende Staging-UAT zeigte auf demselben aktiven Swarm-Workspace mit `storage_100gb` korrekt 350 GB in der Billing-Hauptseite, aber „0 BYTES / kein Limit“ im Usage-Tab. Die alte Route las ausschließlich Legacy-`SubscriptionFeature`-/UsageRecord-Daten und band ihre eigenen Queries nach dem Modul-Gate nicht an RLS. | Klein. Bestehenden Resolver wiederverwenden, Read-Grenze binden, Service-/Route-Regressionstests, i18n und erneuter Staging-Screenshot. Keine Migration, kein Katalog-, Preis-, Checkout- oder Providerwechsel. | Genehmigt durch den ausdrücklichen User-Auftrag im Chat, den vollständigen Billing-Flow live zu prüfen und gefundene sichere Launch-Fixes selbstständig fertigzustellen. | 2026-08-01 |
|
||||
| CR-015 | 2026-08-01 | Raffael / Produktteam | `MAIL-01`, transaktionale React-E-Mail-Templates, Signup-Willkommensmail | Transaktionale E-Mails erhalten die tatsächliche Dokumentsprache, einen vollständig lokalisierten Footer und die bereits vom Renderer erzeugte Plaintext-Alternative bis in Queue, Outbox und Mailjet-`TextPart`. Der künstliche einzelne Bindestrich in der Signatur entfällt. | Der reale MAIL-01-Screenshot zeigte deutschen Hauptinhalt unter `lang="en"`, einen englischen Footer und eine isolierte Bindestrichzeile. Der Renderer erzeugte korrekt Plaintext, der Web-Wrapper verwarf ihn jedoch vor dem Versand. Mailjet empfiehlt passende `lang`-Attribute und stets eine lesbare Reintext-Version. | Klein bis mittel. Expliziter, optionaler Mail-Chrome-Vertrag, vorhandene de/en-Mailübersetzungen, Text-Propagation im bestehenden Payload und fokussierte Template-/Signup-/Outbox-/Provider-Tests. Keine neue Mail, kein neuer CTA, keine Provider-, Secret-, Retry-, Idempotenz- oder Marketingänderung. | Genehmigt durch den ausdrücklichen User-Auftrag im Chat, nach Billing die Willkommensmail wie bei einem klassischen SaaS zu prüfen und sichere, recherchierte Launch-Verbesserungen selbstständig umzusetzen. | 2026-08-01 |
|
||||
| CR-016 | 2026-08-01 | Raffael / Produktteam | `BILL-14`, öffentliche Registrierung, self-hosted CAP | Der Team-/Tarif-Schritt erhält eine responsive Entscheidungshierarchie mit Rollen-Steppern, prominenter Tarifempfehlung, eingeklappten Alternativen und klarer Vorab-Zahlungsinformation. Der Client bindet die CAP-Events `solve`, `reset` und `error`; ein Submit bleibt bis zu einem frischen Proof gesperrt. Nach jedem fehlgeschlagenen initialen Registrierungs-POST remountet ein opaker serverseitiger Retry-Schlüssel eine neue Challenge. | `noValidate` erlaubte einen Registrierungs-POST ohne CAP-Proof. Ein bereits erfolgreich verifizierter CAP-Token ist einmalig und konnte bei einem späteren Validierungsfehler dennoch im optisch gelösten Widget verbleiben; der nächste Versuch scheiterte dadurch wiederholt bis zum Reload. Gleichzeitig war der lange schmale Tarifscreen kurz vor dem Piloten schwer erfassbar. | Mittel. Reiner UI-/Request-Response-Nachzug ohne Migration oder Provideränderung: vorhandene `~/ui`-Komponenten, CAP-Statusvertrag, opaker Reset-Key, de/en/formal-i18n, Unit-/Service-Regressionen und Desktop-/Mobile-Pixelbaselines. Preise, Empfehlung, E-Mail-Verifikation, Mollie/Lago und Entitlements bleiben unverändert. | Genehmigt durch den ausdrücklichen User-Auftrag im Chat, den gezeigten Checkout-Vorlauf neu zu gestalten und den blockierenden CAPTCHA-Fehler vollständig zu beheben. | 2026-08-01 |
|
||||
| CR-017 | 2026-08-02 | Raffael / Produktteam | `BILL-14`, `BILL-18`, Registrierung, Subscription-Gate, Billing-Erstkauf | Synchron prüfbare Passwortregeln blockieren den Wechsel aus dem Konto-Schritt und werden dort inline erklärt. Nach dem technischen Workspace-Bootstrap erscheint für Tenants ohne Subscription-Produkt und ohne aktive Testphase ein eigener, app-chrome-freier Aktivierungscheckout. Er übernimmt die registrierte Tarif-/Sitzpräferenz, zeigt die serverseitig geprüfte Preiszusammenfassung und führt mit genau einer Primäraktion zu Mollie. Laufende Nutzung, Rechnungen und unabhängige Add-ons bleiben bis zur Basisaktivierung aus diesem Zustand ausgeblendet. | Der reale Staging-Flow meldete ein zu kurzes Passwort erst nach dem finalen Tarif-Submit. Nach erfolgreicher Registrierung zeigte er anschließend die vollständige Workspace-/Settings-Hülle und eine lange Verwaltungsseite, obwohl noch keine Zahlung und keine aktive Testphase vorlagen. Das Backend sperrte Fachmodule korrekt, die visuelle Systemgrenze und Informationsarchitektur vermittelten jedoch das Gegenteil. | Mittel. Reiner UI-/Routing-/Gate-Nachzug mit bestehenden View-Models, `~/ui`, Preisvorschau und Checkout-Actions. Route-, Component-, A11y-, Desktop-/Mobile- und Live-Mollie-Testproof. Keine Migration, keine neue Trial, keine Preis-, Provider-, Rechnungs- oder Entitlement-Änderung. | Genehmigt durch den ausdrücklichen User-Auftrag im Chat, die verspätete Passwortwarnung, den unbezahlten Workspace-Eindruck und die unübersichtliche Erstkaufseite vollständig UX-technisch zu korrigieren. | 2026-08-02 |
|
||||
| CR-018 | 2026-08-02 | Raffael / Produktteam | `BILL-19`, `AK-P20`, `VA-P24a`, Checkout-Return, Onboarding, aktive Billing-Verwaltung | Nach bestaetigter Basiszahlung fuehrt HiveGrid ohne Timer in eine eigene, app-chrome-freie Welcome-/Setup-Surface. Sie verwendet die vorhandene RLS-gebundene Erste-Schritte-Session, ergaenzt Team-Einladung als automatisch erkannten Setup-Schritt und bleibt im Dashboard resumierbar. Die aktive Billing-Hauptseite trennt Uebersicht, Tarif/Nutzer und Zusatzmodule; Speicher, E-Mail-Marketing und Customer-Portal verwenden weiterhin ihre bestehenden Checkout-/Entitlement-Vertraege. | Der aktuelle Return verteilt Nutzer auf drei gleichrangige Ziele und erzwingt nach zehn Sekunden das Dashboard. Gleichzeitig stapelt die aktive Billing-Seite Vertragsstatus, Nutzung, Trial-Hinweis, kompletten Tarif-/Seat-/Speicher-Builder und E-Mail-Marketing. Kurz vor dem Piloten fehlt damit eine klare erste Nutzungsphase und eine aufgabenorientierte Billing-Informationsarchitektur. | Mittel bis gross. Neue pure Welcome-VM und Route, `~/ui`-Interim-Screen, synthetischer tenantgebundener Team-Detection-Step ohne Migration, fokussierte Billing-Navigation, bestehende Portal-Deep-Links sowie Unit-/Route-/A11y-/Visual-/Staging-UAT-Proof. Keine Preis-, Trial-, Provider-, Schema-, Rechnungs- oder Entitlement-Aenderung; der gecancelte 10-Step-Scope aus `VA-P24b` bleibt geparkt. | Genehmigt durch den ausdruecklichen User-Auftrag im Chat, die Journey von Registrierung und Mollie-Zahlung bis Welcome, Team-Setup und uebersichtlichem Billing komplett fuer den Pilot-Launch zu ueberarbeiten und end-to-end zu belegen. | 2026-08-02 |
|
||||
| CR-019 | 2026-08-02 | Raffael / Produktteam | `BILL-08`, `BILL-11`, `BILL-13`, `BILL-14`, Mollie-Erst- und Folgezahlungen | Bei einem an Mollie übergebenen Bruttobetrag bis einschließlich 1.000,00 EUR bleibt der bestehende Mandatsvertrag gültig. Ab 1.000,01 EUR ist `creditcard` für Basisplan-, Änderungs- und Add-on-Checkouts sowie invoice-getriebene Folgezahlungen zwingend. Fehlt die Karte im konkreten Mollie-Profil, bricht HiveGrid vor Provider-Mutationen mit Klartext ab. Der technische Katalogcode `annual_sepa` bleibt migrationsstabil, bestimmt oberhalb der Grenze aber nicht die Zahlart. | Mollies dokumentiertes Standardmaximum für SEPA Direct Debit beträgt 1.000 EUR. Colony liegt bereits ohne Extras bei 1.069,81 EUR brutto. Der bisherige 12-Monatsvertrag blendete Karten aus, autorisierte per iDEAL ein SEPA-Mandat und erzwang im Worker später erneut `directdebit`; damit war der größte Standardtarif nicht sicher wiederkehrend einziehbar. | Mittel. Zentraler Payment-Policy-Resolver, serverseitige Methodenauswahl, fail-closed Kartenverfügbarkeit, Recurring-Worker-Nachzug, Klartext-UI und Grenzwerttests. Keine Migration, keine Preis-, Laufzeit-, Steuer-, Lago-, Entitlement- oder Hosted-Checkout-Änderung. Das bisherige externe SEPA-Limit-Gate in `BILL-08` entfällt; Mollie-Live-KYC und Legal-/Steuerfreigabe bleiben. | Genehmigt durch den ausdrücklichen User-Auftrag im Chat, Zahlungen über 1.000 EUR zwingend per Mollie-Karte abzuwickeln. | 2026-08-02 |
|
||||
| CR-020 | 2026-08-02 | Raffael / Produktteam | `REQ-i18n-architektur`, `REQ-i18n-outbound`, ROADMAP Phase 3/30, bisheriger v1-DE-only-Vertrag | HiveGrid erweitert den statischen Produkt- und Transaktionskatalog von Deutsch/Englisch um Polnisch (`pl`), Russisch (`ru`), Ukrainisch (`uk`) und Ungarisch (`hu`). Alle sechs Basis-Sprachen und ihre formellen Anredevarianten werden vollständig verdrahtet. Vorhandene Kataloge und produktiv aktivierte Sprachen werden getrennt: `I18N_ENABLED_LOCALES` aktiviert standardmäßig nur `de,en`; jede weitere Sprache bleibt bis zum dokumentierten Muttersprachler-Gate deaktiviert. UI-Sprache, Customer-Portal, Billing-Hülle und Systemmails folgen derselben aktivierten Empfängersprache. Knowledge-Base-Inhaltssprachen und nutzergenerierte Inhalte bleiben getrennte Verträge. | Polnisch und Ukrainisch decken den priorisierten Handwerks-Arbeitsmarkt ab; Russisch und Ungarisch gehören zum ausdrücklich freigegebenen Produktscope. Der bestehende i18n-Unterbau ist bereits katalogbasiert, aber harte `de/en`-Sonderfälle würden neue Sprachen unvollständig oder unkontrolliert aktivieren. | Groß. Vier vollständige Kataloge mit je neun Namespaces, formelle Overrides, Release-Konfiguration, Locale-Auflösung, Portal-/Mail-/Billing-Nachzug, Terminologie-/Review-Artefakte, automatisierte Paritäts-/Token-/Plural-/Fallback-Gates sowie Browser- und Mail-UAT. Keine Datenbankmigration, kein Runtime-Übersetzungsdienst und keine neue LLM-Abhängigkeit. Rumänisch wird nur als nächster Ausbau dokumentiert. | Genehmigt durch den ausdrücklichen User-Auftrag im Chat, den vorliegenden Umsetzungsplan für Polnisch, Russisch, Ukrainisch und Ungarisch vollständig umzusetzen. | 2026-08-02 |
|
||||
| CR-021 | 2026-08-02 | Raffael / Produktteam | `BILL-11`, `BILL-14`, `BILL-19`, `BILL-20`, `BILL-21`, Registrierungs- und Mollie-Erstkaufpfad | Registrierung und Aktivierung werden als geführter Ablauf neu geschnitten: Teamgröße vor Tarif, serverseitig live berechnete Empfehlung und Preise, anschließend getrennte und überspringbare Speicher- sowie E-Mail-Marketing-Upsells und eine fokussierte Zahlungsseite. Bis einschließlich 1.000,00 EUR kann der Kunde alle von Mollie für den konkreten Betrag angebotenen Erstzahlarten einschließlich Kreditkarte frei wählen; ab 1.000,01 EUR bleibt Karte zwingend. Wiederkehrende Belastungen verwenden ein gültiges Mandat der gewählten Methodenfamilie und fallen nie still auf SEPA zurück. Der technische Cadence-Code `annual_sepa` bleibt migrationsstabil, ist aber keine UI- oder Methodenpflicht mehr. | Der aktuelle Flow vermischt fünf Entscheidungen, versteckt alternative Tarife und bindet 12-Monatsverträge unnötig an iDEAL/SEPA. Zusätzlich widersprach der Mollie-Adapter dem in `BILL-21` eingeführten Recurring-Kartenvertrag. Kurz vor dem Piloten müssen Produktauswahl, Upsells, Betrag und Zahlart getrennt verständlich und technisch konsistent sein. | Mittel bis groß. Reiner UI-/Service-/Worker-Nachzug mit bestehenden `~/ui`-Komponenten, Katalog-/Preview-Verträgen und Hosted Checkout; keine Schemaänderung und keine eigenen Zahlungsfelder. Speicherpreise werden in diesem Slice nur anhand aktueller Hetzner-Kosten bewertet und nicht ohne separate Produktentscheidung geändert. | Genehmigt durch den ausdrücklichen User-Auftrag im Chat, Kreditkarte auch unter 1.000 EUR frei anzubieten und Team-, Tarif-, Speicher-, E-Mail- sowie Zahlungsschritte vollständig neu zu ordnen. | 2026-08-02 |
|
||||
| CR-022 | 2026-08-02 | Raffael / Produktteam | `MAIL-01`, `MAIL-02`, `I18N-01`, alle festen transaktionalen und runtime-erzeugten HiveGrid-Systemmails | Alle von HiveGrid selbst formulierten Systemmails verwenden einen gemeinsamen, responsiven Markenrahmen mit horizontalem HiveGrid-Logo, klarer Typografie, abgestufter Informationshierarchie, lokalisiertem Preheader, konkretem CTA, vollständiger Plaintext-Alternative, Supportkontakt sowie den verbindlichen Plattformlinks `https://hivegrid.de/agb`, `https://hivegrid.de/datenschutz` und `https://hivegrid.de/impressum`. Bestehende rohe HTML-/Text-Versandpfade werden auf denselben Renderer umgestellt. Plattformlogo und Plattform-Rechtslinks bleiben fest; Tenant-/Projektkontext erscheint in Inhalt und Absenderkontext, ersetzt aber nicht die HiveGrid-Absenderidentität. | Der reale Inbox-UAT zeigte ein inkonsistentes Produktbild: Der Brand-Resolver liefert verschachtelte Tokens, während das Mail-Theme flache Werte erwartet; dadurch erscheint oft nur ein Textfallback. Zudem umgehen zahlreiche Runtime-Mails den React-Renderer vollständig, besitzen weder Logo noch einheitlichen Footer und enthalten teils knappe oder hartkodierte Texte. Der Empfänger soll Anlass, Bedeutung und nächste Aktion auf einen Blick verstehen und HiveGrid eindeutig als vertrauenswürdigen Absender erkennen. | Mittel bis groß. Gemeinsames Mail-Designsystem, absolut gehostetes E-Mail-Logo, zentraler Brand-Adapter, generische Systemmail-Komponenten, Nachzug aller festen Web-/Worker-Mailpfade, sechs Basis-Sprachen plus formelle Fallbacks, Rendering-/Snapshot-/Text-/Link-Verträge und realer Inbox-UAT. Keine neue Mailkategorie, kein Marketing- oder nutzergenerierter Inhalt, kein Provider-, Secret-, Queue-, Retry-, Tracking-, Billing- oder Datenbankvertrag. Die vier neuen Sprachen bleiben produktiv deaktiviert. | Genehmigt durch den ausdrücklichen User-Auftrag im Chat, sämtliche festen HiveGrid-Systemmails mit Logo, Farben, visueller Hierarchie und professionelleren Texten vollständig zu überarbeiten und danach ohne Testkennzeichnung wie an einen echten Kunden zuzustellen. | 2026-08-02 |
|
||||
| CR-023 | 2026-08-02 | Raffael / Produktteam | `BILL-08`, `BILL-11`, `BILL-17`, `BILL-22`, Storage-Kapazität, Checkout, Usage und Lago-Katalog | Speicher wird als gemeinsamer Workspace-Pool verkauft, der mit bezahlten Nutzerplätzen wächst: Core 100 GB plus 10 GB je Zusatznutzer, Swarm 500 GB plus 20 GB, Colony 2 TB plus 40 GB. Büro und Baustelle zählen für Speicher gleich. Feste `Cloud-Speicher Plus`-Pakete bleiben vorhersehbar und kosten 1,25/6,25/12,50/62,50 EUR netto für 100 GB/500 GB/1 TB/5 TB. Die Rohmarge ist selbst ohne Egress auf maximal 50 Prozent gegen 6,26 EUR/TB direkte Hetzner-Speicherkosten gedeckelt. | Pauschaler Planspeicher plus rollenabhängige Zusatzkontingente ist schwer greifbar, obwohl Projektdateien dem Workspace gehören. Die bisherigen Add-ons erzielen 84 bis 93 Prozent Rohmarge und sind für den Pilotkunden unnötig teuer. Ein lizenzbasierter gemeinsamer Pool ist transparent, skaliert mit dem Team und vermeidet persönliche Dateisilos. | Mittel. Versionierter Katalog-, Kapazitäts-, VM-, Checkout-, Usage-, Lago-Sync-, i18n- und Visual-Nachzug ohne Schemaänderung oder Usage-Metering. Technische Codes bleiben stabil; Production-Sync bleibt hinter `BILL-08`. | Genehmigt durch den ausdrücklichen User-Auftrag im Chat, die Speicherabrechnung vollständig neu zu denken, intelligent in den geführten Billing-Flow zu integrieren und die Rohmarge auf maximal 50 Prozent zu begrenzen. | 2026-08-02 |
|
||||
| CR-024 | 2026-08-03 | Raffael / Produktteam | `BILL-08`, `BILL-23`, Speicher-Upsell, Checkout und Lago-Katalog | Neu buchbare Speicherpakete verwenden ein konsistentes, wertigeres `,99`-Raster: 500 GB für 4,99 EUR, 1 TB für 9,99 EUR und 5 TB für 49,99 EUR netto pro Monat. Das bisherige 100-GB-Paket bleibt nur für Bestandsverträge technisch auflösbar und wird für Neuabschluss und Upsell serverseitig gesperrt. Die maximal 50-prozentige direkte Rohmarge bleibt unverändert verbindlich. | Die bisherigen Viertel-/Halbeuropreise wirken wie interne Kalkulationswerte; ein 100-GB-Einstieg für 1,25 oder 1,99 EUR setzt einen zu billigen Preisanker. Drei klare Größen sind leichter vergleichbar, wertiger und halten mit rund 37 Prozent direkter Rohmarge genügend Abstand zur vereinbarten Obergrenze. | Klein bis mittel. Versionierter Katalog-, Self-Service-, Checkout-, Test-, Doku-, Visual- und Staging-Sync-Nachzug ohne Schema-, Basisplan- oder Production-Änderung. Technische Codes bleiben stabil. | Genehmigt durch den ausdrücklichen User-Auftrag im Chat, alle Speicherpreise auf schönere `,99`-Endungen zu stellen und den billigen `1,99`-Preisanker zu vermeiden. | 2026-08-03 |
|
||||
| CR-025 | 2026-08-03 | Raffael / Produktteam | `BILL-08`, `BILL-22`, `BILL-24`, Speicher-Upsell, Download-Telemetrie und Lago-Katalog | Neu buchbare Speicherpakete kosten 6,99 EUR für 500 GB, 12,99 EUR für 1 TB und 60,99 EUR für 5 TB netto pro Monat. Die Kalkulation verwendet die tatsächlich als 1024³ Bytes je GB gewährte Quota gegen Hetzners dezimale TB und trägt konservativ fünf vollständig kostenpflichtige externe Auslieferungen der gebuchten Paketkapazität bei 1 EUR/TB Mehrtraffic. Nur die kleinste wertige ,99-Stufe liegt ohne Egress mit 51,9 Prozent knapp über der angestrebten direkten 50-Prozent-Marge; 5,99 EUR wäre bei 5× Egress bereits negativ. Der accountweite Hetzner-Freibetrag bleibt Plattformpuffer und wird keinem Workspace versprochen. HiveGrid trennt Provider-Istkosten, aggregierte autorisierte Downloadbytes und die nur näherungsweise Workspace-bezogene Signed-URL-Nutzung; es entsteht kein Traffic-Overage-Billing. | Die bisherige Kalkulation vermischte binäre HiveGrid-Quota mit dezimalen Provider-TB und war dadurch nach fünf vollständigen Auslieferungen leicht negativ. Für den Piloten soll normaler Dokumenten-/Fotodownload ohne variable Nachberechnung wirtschaftlich bleiben, während öffentliche Links, Hotlinking und ungewöhnliche Transfermuster früh sichtbar werden. | Mittel. Versionierter Katalog-/Lago-Nachzug, automatisierte Egress-Kalkulation, niedrig-kardinale Download-Telemetrie, Betriebsvertrag sowie erneuter Registrierungs-/Mollie-TEST-/Invoice-/Add-on-UAT. Keine Schemaänderung, kein Download-Proxy, keine neue CDN-/Serverinfrastruktur und keine echte Production-Zahlung. Production-Katalog erst nach grünem Staging-Proof; Billing-Side-Effects bleiben bis `BILL-08` geschlossen. | Genehmigt durch den ausdrücklichen User-Auftrag im Chat, die Preise minimal für vier bis fünf vollständige Egress-Zyklen anzuheben, Storage-Traffic sauber beobachtbar zu machen und den kompletten Billing-/Registrierungsflow erneut bis Staging und kontrolliertem Production-Katalog zu prüfen. | 2026-08-03 |
|
||||
|
||||
## Verbindliche Auslegung zu CR-006
|
||||
|
||||
- Automatischer KWP-Sync darf nicht vom Freigabestatus des generischen Dateiimports abhängen. KWP-Projekt-,
|
||||
Katalog-, Contract- und Archivjobs laufen deshalb über die eigene Queue `hivegrid.kwp-imports`, die der
|
||||
bestehende `worker-import` in jedem gültigen Runtime-Modus konsumiert.
|
||||
- Die generische Queue `hivegrid.imports` bleibt unverändert hinter
|
||||
`IMPORT_QUEUE_ENABLED=true` plus `IMPORT_QUEUE_RUNTIME_READY=true`. Der schmale
|
||||
`PORTAL_GDPR_EXPORT_QUEUE_ENABLED=true`-Modus konsumiert KWP plus `hivegrid.exports`, aber weiterhin
|
||||
keine generischen Dateiimporte.
|
||||
- Bereits vor dieser Trennung auf `hivegrid.imports` persistierte KWP-Jobs bleiben replay-fähig. Neue
|
||||
typisierte KWP-Producer können ausschließlich die dedizierte Queue adressieren.
|
||||
|
||||
## Verbindliche Auslegung zu CR-013
|
||||
|
||||
- Ein Fehler in Termine, Aufgaben oder Material darf erfolgreiche Bereiche nicht verwerfen. Nur Bindings
|
||||
eines erfolgreich gelesenen Bereichs dürfen in diesem Lauf als fehlend markiert werden.
|
||||
- Das Archiv ist keine Voraussetzung für den Abschluss des Kernlaufs. Sein Queue-Cursor enthält nur
|
||||
numerische Ordner-IDs, ist auf 1.000 eindeutige Ordner begrenzt und bleibt über Worker-Restarts replaybar.
|
||||
- Der 15-Minuten-Takt des Kernlaufs bleibt bestehen. Archiv-Discovery und erneute Dateiexporte sind über
|
||||
einen sechs Stunden breiten Idempotenz-Bucket entkoppelt; innerhalb dieses Buckets erhält ein Dateijob
|
||||
höchstens drei Versuche mit exponentiellem 60-Sekunden-Backoff.
|
||||
- `provider_outage`, Rate-Limit- und vergleichbare temporäre Dateifehler sind retrybar und ändern den
|
||||
Connection-Status nicht. Vertragsdrift, fehlende Berechtigung, pausierte Capability, ungültige lokale
|
||||
Credentials, nicht mehr vorhandene Ressourcen und feste Importgrenzen werden im Job nicht sinnlos
|
||||
wiederholt; der nächste reguläre Lauf bleibt davon unberührt.
|
||||
- Keine neue Mutation-Operation, kein Writeback und keine Änderung am OAuth-/Refresh-Vertrag. Ein echter
|
||||
Authentifizierungsfehler darf weiterhin den vorhandenen Connection-Health-Pfad auslösen.
|
||||
|
||||
## Verbindliche Auslegung zu CR-001
|
||||
|
||||
- Die Custom-Domain gilt nur für das Customer-Portal. Sie ist kein vollständiges App-White-Label für
|
||||
`app.hivegrid.de` und ändert den Enterprise-only-Scope des allgemeinen White-Label-Pakets nicht.
|
||||
- Die Einmalgebühr umfasst die erste DNS-/TLS-Einrichtung eines exakten Hostnamens. Apex-Domains,
|
||||
Wildcards und mehrere parallele Portal-Domains sind nicht enthalten.
|
||||
- Business enthält das Portal, aber keine Domain; die Einrichtung kostet dort wie bei Starter/Team
|
||||
299,99 EUR netto. Enterprise enthält Portal und eine Domain als vertraglichen Override.
|
||||
- Entfernte oder gewechselte Hostnamen bleiben 30 Tage gegen eine Übernahme durch einen anderen Workspace
|
||||
gesperrt. Der Standardhost bleibt währenddessen erreichbar.
|
||||
- Eine aktive HiveGrid-Subscription und ein aktives Portal-Entitlement sind Voraussetzung. Fällt das
|
||||
Portal-Entitlement weg, wird auch die Custom-Domain deaktiviert.
|
||||
- Die Endkunden-Surface läuft im separaten Coolify-Service/Container `hivegrid-portal`, zunächst aus
|
||||
demselben unveränderlichen Web-Image. Eigene Runtime-Grenzen und der minimal berechtigte DB-Login
|
||||
`hivegrid_portal` gehören zu `VA-P26a`; der Domain-Controller aus `VA-P26c` routet nur auf diesen Service.
|
||||
- Technischer Vertrag und Sicherheitsgrenzen stehen in `AGENTS.md` §Architektur-Baseline,
|
||||
dieser CR-001-Auslegung und `docs/INTEGRATION-CONTRACTS.md` §3/§14; AD-30 bleibt die
|
||||
rückverfolgbare Entscheidungs-ID.
|
||||
|
||||
## Verbindliche Auslegung zu CR-003
|
||||
|
||||
- „Read-only“ bezeichnet die fachliche Richtung der initialen KWP-Integration: KWP → HiveGrid. OAuth-Code-
|
||||
Austausch, automatische Refresh-Token-Rotation, Connection-Health und andere notwendige
|
||||
Verbindungs-Lifecycle-Operationen sind keine fachlichen KWP-Mutationen.
|
||||
- HiveGrid sendet im aktuellen Scope keine Create-, Update-, Delete-, Import- oder sonstigen fachlichen
|
||||
Schreibrequests an KWP. Das gilt auch für vorhandene Termin-, Aufgaben- oder Archiv-Schreiboperationen.
|
||||
- M091, `kwp.push_auftrag`, Project-/Auftrag-Create sowie M094-outbound und M074-outbound bleiben als
|
||||
verpflichtender, aber geparkter Writeback-Nachzug erhalten. Sie sind keine DoD-Voraussetzung des
|
||||
initialen read-only Scopes.
|
||||
- `VEXT-6` hält den externen Write-Vertrag nach. Erst dessen belastbarer Abschluss plus eine erneute
|
||||
ausdrückliche Produktfreigabe erlauben das Schneiden eines Dev-Tickets; bis dahin wird kein spekulativer
|
||||
Write-Adapter gebaut.
|
||||
- KWP bleibt v2-P5/Phase 32. CR-003 verschiebt KWP nicht nach v1 und ändert nicht die historische
|
||||
v1/v2-Scope-Schnitt-Entscheidung.
|
||||
|
||||
## Verbindliche Auslegung zu CR-004
|
||||
|
||||
- Der gemeinsame PR hebt die fachliche Dependency nicht auf: `VR-P32b` wird intern vollständig vor
|
||||
`VR-P32d` umgesetzt und verifiziert. `VR-P32d` bleibt bis dahin formal blockiert.
|
||||
- Es gibt keinen behaupteten KWP-Vollimport. `POST /api/Projekt/Search` benötigt einen Suchbegriff mit
|
||||
mindestens zwei Zeichen; ausgewählte Treffer werden über die freigegebenen Detailoperationen geladen.
|
||||
- `AppEntityBinding` ist die dauerhafte providerneutrale External↔Local-Zuordnung. `AppSyncItem` bleibt die
|
||||
Historie eines einzelnen Laufs und ist allein kein dauerhaftes Mapping.
|
||||
- KWP-eigene Projektfelder sind Projektname, KWP-Status mit daraus abgeleiteter Pipeline/Stage, Beginn,
|
||||
Auftragswert, externe KWP-Projektnummer sowie gebundene KWP-Adressen und ausgewählte KWP-Kontaktdaten.
|
||||
Lokale Beschreibung, Priorität, Deadline, Mitglieder, Checklisten, Portalzugänge, Tasks, Notizen und Custom
|
||||
Fields bleiben lokal editierbar.
|
||||
- Projekt-, Rechnungs- und Bauherradresse werden je Rolle explizit mit einem vorhandenen CRM-Kontakt verbunden
|
||||
oder bewusst neu angelegt. Es gibt kein automatisches Fuzzy-Merge und keine ungefragte Massenübernahme von
|
||||
Ansprechpartnern. Architektenadressen und weitere KWP-Ansprechpartner bleiben außerhalb dieses Slices.
|
||||
- IBAN, Bank, Kreditlimit, Steuerdaten, Geburtstag, interne KWP-Hinweise und Benutzerfelder werden weder in
|
||||
typisierten Tabellen noch in Roh-Snapshots gespeichert.
|
||||
- Der Erstimport schreibt Search, Audit und Activity, veröffentlicht aber kein Workflow-Event. Nur spätere
|
||||
KWP-Stage-Änderungen veröffentlichen `project.stage_changed` mit `source=kwp`.
|
||||
- Trennen stoppt den Sync und entfernt das Binding, behält aber Projekt und CRM-Daten lokal. Ein expliziter
|
||||
Restore trennt zuerst atomar, stellt danach den vor der KWP-Überschreibung gesicherten lokalen Stand wieder
|
||||
her und protokolliert Audit sowie Activity.
|
||||
- Der kontrollierte Live-Geerkens-E2E bleibt ausschließlich in `VN-2` und blockiert den Merge dieses
|
||||
fixture-validierten Implementierungs-PRs nicht.
|
||||
|
||||
## Verbindliche Auslegung zu CR-005
|
||||
|
||||
- „Vollständig“ bedeutet den aktuellen, durch die fünf angeforderten OAuth-Scopes
|
||||
`adresse-extern`, `archiv-extern`, `termin-extern`, `vorgang-extern` und `aktivitaet-extern`
|
||||
erreichbaren Vertrag. Die übrigen 441 OpenAPI-Operationen werden inventarisiert, aber nicht als
|
||||
ausführbare HiveGrid-Capability ausgegeben.
|
||||
- Jede der 113 Scoped-Operationen besitzt eine feste Kombination aus ID, HTTP-Methode, Pfad, Capability,
|
||||
Modus und Request-/Response-Schema. Fachcode darf weder freie KWP-Pfade noch URL, Token, Mandant oder
|
||||
rohe Credentials übergeben.
|
||||
- „Read“ wird semantisch klassifiziert. Deshalb dürfen auch nachweislich lesende `POST`-Operationen wie
|
||||
`Search`, `Load`, `Count`, `Get` und `Check` in der Read-Allowlist stehen. `Save`, `Add`, `Delete`,
|
||||
`Remove`, `Import`, `Publish` und `Reset` bleiben unabhängig von ihrer HTTP-Methode Mutation.
|
||||
- Ein Mutation-Contract ist kein freigegebener Writeback. Die Runtime muss die 36 Operationen vor
|
||||
Budgetverbrauch, Relay-Auflösung und HTTP blockieren. Es entstehen kein Mutation-Export für Web/Worker,
|
||||
keine Automation-Action, keine Push-Queue und keine UI-Aktion.
|
||||
- Responses werden vor Domain-Mapping gegen den eingecheckten Scoped-Vertrag validiert. Der tägliche
|
||||
Sentinel vergleicht semantisch pro Capability nur konsumierte Operationen und ihre rekursiv referenzierten
|
||||
Schemas; Drift in einem Bereich pausiert nicht automatisch alle anderen Bereiche.
|
||||
- Live-Tests auf Staging bleiben read-only, secretsicher und selektiv. Sie dürfen weder einen
|
||||
unbestätigten Realprojektimport noch eine KWP-Mutation auslösen. Der kontrollierte fachliche Importbeweis
|
||||
bleibt in `VN-2`.
|
||||
- `VEXT-6` bleibt das Gate für ausführbaren Writeback und Project-/Auftrag-Create. CR-005 erfüllt keinen
|
||||
seiner vier externen DoD-Punkte und deutet `/api/Projekt/Save` nicht als Create um.
|
||||
|
||||
## Verbindliche Auslegung zu CR-006
|
||||
|
||||
- Automatisch synchronisiert wird der im bestätigten Mandanten durch
|
||||
`GET /api/Projektampel/LoadProjekteNachFilter` sichtbare Platzhalterbestand. Da KWP weder Cursor noch
|
||||
Pagination und laut Hersteller keinen Delta-Filter liefert, bleibt die Aussage bewusst auf diesen
|
||||
einstellungsabhängigen Bestand begrenzt. HiveGrid behauptet keinen darüber hinausgehenden Vollabzug.
|
||||
- Der Discovery-Call speichert zunächst ausschließlich erlaubte Projektnummern. Details werden asynchron in
|
||||
kleinen, lease- und replay-sicheren Batches angereichert. 50.000 Einträge dürfen weder eine lange
|
||||
DB-Transaktion noch eine synchrone 50.000-Request-Schleife erzeugen.
|
||||
- Jede gezielte Live-Suche ist zugleich read-through: schema-valide Treffer werden idempotent in den
|
||||
Katalog geschrieben und stehen danach auch bei einer vorübergehenden KWP-Störung für die Suche zur
|
||||
Verfügung. Ein Live-Fehler darf vorhandene Cache-Treffer nicht vernichten.
|
||||
- Der Katalog enthält nur die bereits freigegebenen KWP-Projektfelder. Rohpayloads sowie IBAN, Bank,
|
||||
Kreditlimit, Steuerdaten, Geburtstag, interne Hinweise und Benutzerfelder werden weiterhin nicht
|
||||
gespeichert.
|
||||
- Der komplette Scoped-Adapter aus CR-005 bleibt für generische Operationen vollvertraglich validiert. Der
|
||||
fachliche Projektimport verwendet zusätzlich eine engere Zod-Projektion: Nur ein Typfehler in einem
|
||||
konsumierten Feld gilt dort als Response-Drift. Abweichungen in ungenutzten Feldern bleiben redigiert und
|
||||
ohne Capability-Pause.
|
||||
- Auto-Recovery ist nur bei identischem genehmigtem und beobachtetem semantischem Fingerprint sowie
|
||||
erfolgreicher aktueller Projektion erlaubt. Echte OpenAPI-Drift, konsumierte Typfehler und fehlende
|
||||
Providerrechte bleiben pausiert.
|
||||
|
||||
**Produktgrenzen:** `AGENTS.md` §Produktgrenzen / Anti-Liste bleibt verbindlich. Dieser CR führt keine
|
||||
zusätzliche Ausnahme ein.
|
||||
BIN
Binary file not shown.
@@ -4,7 +4,7 @@
|
||||
|
||||
Diese Datei ist Quelle der Wahrheit für: Sidebar-Gruppen, Route-Patterns, Breadcrumbs, Permissions, Search-Index, Activity-Stream, Audit, i18n.
|
||||
|
||||
> **Naming-/Pfad-Realität (Stand 2026-06-04, siehe `docs/ARCHITECTURE-DECISIONS.md` AD-10):**
|
||||
> **Naming-/Pfad-Realität (siehe `AGENTS.md` §Naming-Konvention; Entscheidungs-ID AD-10):**
|
||||
> Das HiveGrid-UI-Paket heißt real **`packages/ui-app`** (nicht `packages/ui-hivegrid`). Die
|
||||
> Sidebar-Konfiguration liegt in **`apps/web/app/application/sidebar/`** (nicht `sidebar.config.ts`).
|
||||
> Der Such-Index / `indexedEntities` gehört nach **`packages/search/`** (nicht
|
||||
@@ -103,7 +103,8 @@ Verbindliche URL-Schemata. Abweichungen erfordern Change-Request.
|
||||
| Mandanten-App | `app.hivegrid.de/<modul>/...` | `app.hivegrid.de/sales/D-2026-0042` |
|
||||
| Mandant-Settings | `app.hivegrid.de/settings/<modul>/...` | `app.hivegrid.de/settings/integrationen/kwp` |
|
||||
| Plattform-Admin | `admin.hivegrid.de/<bereich>/...` | `admin.hivegrid.de/mandanten/123` |
|
||||
| Customer-Portal | `app.hivegrid.de/portal/<tenant>/...` | `app.hivegrid.de/portal/geerkens/projekte/42` |
|
||||
| Customer-Portal (Standard) | `portal.hivegrid.de/<tenant>/...` | `portal.hivegrid.de/geerkens/projekte/42` |
|
||||
| Customer-Portal (verifizierte Custom-Domain) | `<portal-host>/...` | `portal.geerkens.de/projekte/42` |
|
||||
| Public-Forms | `app.hivegrid.de/f/<tenant>/<slug>` | `app.hivegrid.de/f/geerkens/kontaktformular` |
|
||||
| Public-Booking | `app.hivegrid.de/b/<tenant>/<slug>` | `app.hivegrid.de/b/geerkens/wartungstermin` |
|
||||
| Public-Help | `app.hivegrid.de/help/<lang>/<kategorie>/<slug>` | `app.hivegrid.de/help/de/integrationen/kwp-setup` |
|
||||
@@ -113,14 +114,21 @@ Verbindliche URL-Schemata. Abweichungen erfordern Change-Request.
|
||||
|
||||
Die Tenant-Slug ist **nicht** im Pfad bei der Mandanten-App — Tenant kommt aus Subdomain oder Session.
|
||||
|
||||
**Customer-Portal (AD-30):** Auf dem Standardhost bleibt der Tenant-Slug Pflicht. Auf einer verifizierten
|
||||
Custom-Domain steht er nicht im Pfad; der Tenant kommt dort ausschließlich aus der global eindeutigen,
|
||||
aktiven Host-Zuordnung. Unbekannte, noch nicht verifizierte oder deaktivierte Portal-Hosts liefern 404.
|
||||
Staging verwendet `staging-portal.hivegrid.de/<tenant>/...`. Eine interne Route darf weiter auf einen
|
||||
normalisierten Portal-Namespace abbilden, aber die öffentliche kanonische URL folgt immer dieser Tabelle.
|
||||
|
||||
**Public API und MCP:** Public API läuft ausschließlich auf `api.hivegrid.de` (staging: `staging-api.hivegrid.de`)
|
||||
und nutzt das Versionspraefix `/v1/...`. Es gibt keine Public-API-Routen unter `app.hivegrid.de/api`.
|
||||
Der MCP-Server läuft ausschließlich auf `mcp.hivegrid.de` (staging: `staging-mcp.hivegrid.de`) als separater
|
||||
Service/Container (`hivegrid-mcp`), ohne zusätzlichen `/mcp`-Pfad und nicht im Web- oder Public-API-Service.
|
||||
|
||||
**Externe OAuth-Connectors (Google-Kalender, KWP, später AirCall/Microsoft/…):** Der Redirect-/Callback-Endpoint
|
||||
liegt **immer** auf `app.` (nicht `api.`) unter `/integrations/<provider>/oauth/callback` — konsistent zu den
|
||||
Connector-Settings-Screens (`/settings/integrations/<modul>`, `/integrations/<provider>/…`). Begründung: Der
|
||||
liegt **immer** auf `app.` (nicht `api.`) unter `/integrations/<provider>/oauth/callback`. Die verwaltenden
|
||||
Connector-Screens liegen davon getrennt unter `/settings/integrations/<modul>` bzw. der generische Katalog unter
|
||||
`/settings/integrations`. Begründung: Der
|
||||
OAuth-Rückweg ist browser-basiert und braucht die an `app.` gebundene Nutzer-Session, um den Token dem richtigen
|
||||
Nutzer/Tenant zuzuordnen; `api.hivegrid.de` (token-basiert, ohne Session) ist dafür nicht geeignet. Tenant wird
|
||||
im OAuth-`state` mitgeführt (eine feste Callback-URL je Umgebung, kein Tenant im Pfad). Pro Umgebung registriert:
|
||||
@@ -243,4 +251,57 @@ Neue Funktionen, die in der Mobile-App relevant sind, müssen in `packages/ui-hi
|
||||
|
||||
## 14. Customer-Portal-Wiring (M142, M143)
|
||||
|
||||
Funktionen, die Endkunden sehen sollen, müssen explizit in `packages/ui-hivegrid/src/customer-portal/portal-shell.config.ts` registriert sein. Default-Sichtbarkeit: **NICHT sichtbar**. Tenant-Admin gibt explizit frei (M142.5).
|
||||
Funktionen, die Endkunden sehen sollen, müssen explizit in
|
||||
`packages/ui-app/src/customer-portal/portal-shell.config.ts` registriert sein. Default-Sichtbarkeit:
|
||||
**NICHT sichtbar**. Tenant-Admin gibt Projekte, Stages und Dokumente explizit frei (M142.5).
|
||||
|
||||
**Runtime-/Trust-Boundary (AD-30):** Öffentliche Portalrequests laufen über einen eigenen Coolify-Service
|
||||
und Container `hivegrid-portal`. Im ersten Schnitt verwenden `hivegrid-web` und `hivegrid-portal` dasselbe
|
||||
immutable `hivegrid/web:<sha>`-Image, aber getrennte Runtime-Modi, Secrets, Sessions, Ressourcenlimits und
|
||||
DB-Logins. `WEB_RUNTIME_SURFACE=core|portal` ist in Produktion Pflicht und bei fehlender, ungültiger oder
|
||||
zur Resource unpassender Konfiguration ein Boot-Fehler. Die Trennung erfolgt vor Static-Asset-Serving und
|
||||
React Router und ist fail-closed:
|
||||
|
||||
| Resource | Erlaubt | Muss 404 liefern |
|
||||
|---|---|---|
|
||||
| `hivegrid-web` | App-/Admin-/Root-Hosts sowie Workspace-Admin-Konfiguration unter `app.hivegrid.de/settings/customer-portal/...` | Standard- und Custom-Portalhosts |
|
||||
| `hivegrid-portal` | `portal.hivegrid.de`, Staging-Portalhost, aktive verifizierte Custom-Hosts, Portalroutes, Assets und Health | App-, Admin-, API-, Root- und interne Routen |
|
||||
|
||||
`hivegrid-portal` verwendet den dedizierten DB-Login `hivegrid_portal` mit minimalen Grants und
|
||||
PortalUser-/Projektzugriffs-RLS. Ein zweiter Container mit dem breiten `hivegrid_app`-Login erfüllt diesen
|
||||
Trust-Boundary-Vertrag nicht. Ein eigenes `apps/portal`, ein eigenes Portal-Image, eine eigene VM oder ein
|
||||
Deployment pro Tenant sind im ersten Schnitt nicht vorgesehen.
|
||||
|
||||
Vor dem React-Router-Dispatch normalisiert die Portal-Runtime beide öffentlichen URL-Formen auf einen
|
||||
reservierten, nur intern dispatchbaren Portal-Namespace (Arbeitsvertrag
|
||||
`/__portal/<resolved-tenant>/...`). Beim Standardhost stammt der Tenant aus dem validierten ersten
|
||||
Pfadsegment, beim Custom-Host ausschließlich aus der aktiven Host-Zuordnung. Direkte öffentliche Requests
|
||||
auf den internen Namespace sowie Portalpfade auf `hivegrid-web` liefern 404; dadurch kann keine bestehende
|
||||
TenantUser-/Admin-Route versehentlich einen Portalrequest übernehmen.
|
||||
|
||||
### 14.1 Host- und Tenant-Auflösung (AD-30)
|
||||
|
||||
- `portal.hivegrid.de/<tenant>/...` und `staging-portal.hivegrid.de/<tenant>/...` lösen den Tenant aus dem
|
||||
ersten Pfadsegment auf; Reserved-Words und Tenant-Existenz werden vor Auth geprüft.
|
||||
- Ein Custom-Host löst den Tenant ausschließlich über eine aktive, verifizierte Domain-Zuordnung auf. Ein
|
||||
Tenant-Slug im Pfad ist dort weder nötig noch als Override zulässig.
|
||||
- Bei Konflikt zwischen Pfad, Session und Host wird geschlossen abgebrochen. Ein Request darf niemals über
|
||||
einen vom Client gelieferten Hostnamen den Tenant wechseln.
|
||||
- Jede Portal-Session nutzt ein hostgebundenes `__Host-*`-Cookie. Auf dem geteilten Standardhost bleibt die
|
||||
Session zusätzlich unveränderlich an den Tenant gebunden; ein anderes Pfadsegment darf sie nicht umhängen.
|
||||
App-, Admin- und Portal-Cookies werden nicht geteilt; Sitzungen auf Standard- und Custom-Host sind ebenfalls
|
||||
hostgetrennt.
|
||||
|
||||
### 14.2 Custom-Domain-Lifecycle (VA-P26c)
|
||||
|
||||
1. Nur ein Workspace-Admin mit Portal- und Domain-Entitlement kann einen exakten Subdomain-Host anlegen.
|
||||
2. Der Host durchläuft `pending_dns → verified → provisioning → active`; Fehler und Deaktivierung sind
|
||||
explizite Zustände. Global eindeutige Hostnamen und idempotente Übergänge sind Pflicht.
|
||||
3. Ownership-Proof erfolgt per zufälligem TXT-Token; der Traffic-CNAME zeigt auf
|
||||
`domains.portal.hivegrid.de`. Erst danach provisioniert der getrennte Controller Traefik + TLS und
|
||||
routet den exakten Host ausschließlich auf `hivegrid-portal`.
|
||||
4. Absolute Links in Einladungen, Magic-Links und Status-Mails stammen aus der gespeicherten aktiven
|
||||
Portal-Origin. Der Standardhost bleibt als sichere Fallback-Origin verfügbar.
|
||||
5. DNS/TLS-Monitoring, Revalidierung, Deprovisionierung, ein 30-tägiger Reclaim-Cooldown und
|
||||
Operator-Kill-Switch gehören zum Lifecycle. Apex-Domains, Wildcards und mehrere parallele Domains sind
|
||||
nicht Teil des ersten Vertrags.
|
||||
@@ -1,101 +1,42 @@
|
||||
# Mid-Stream-Änderungen — Rollback-Playbook
|
||||
|
||||
**Zweck:** Wenn ein AI-Coding-Agent ein Milestone falsch baut und du es mittendrin korrigieren musst, ohne dass 5 andere Module brechen.
|
||||
**Zweck:** Ein laufendes Ticket sicher korrigieren, ohne abhängige Tickets oder bereits ausgelieferte Daten zu beschädigen.
|
||||
|
||||
## Grundsatz: atomare Commits pro Slice
|
||||
## Grundsatz
|
||||
|
||||
Der HiveGrid committet pro Slice atomar. Eine Slice rückgängig zu machen heißt: einen Commit-Range zu reverten — nicht einen einzelnen File.
|
||||
- Plane hält Status und Dependencies; die Ticket-Doc hält Scope, DoD, Rollback und Proof.
|
||||
- Änderungen werden an atomaren Checkpoints committed. Ein Rollback erfolgt mit `git revert`, nicht durch Umschreiben veröffentlichter Historie.
|
||||
- Vor Contract-, Schema- oder Scope-Änderungen werden `blocked-by` und `blocks` in beide Richtungen geprüft.
|
||||
|
||||
## Eskalations-Stufen
|
||||
## Eingriffsstufen
|
||||
|
||||
### Stufe 1: Kosmetik / UI falsch
|
||||
### 1. UI/Wording
|
||||
|
||||
**Anzeichen:** Funktion läuft technisch, aber Layout/Wording/Reihenfolge falsch.
|
||||
Interim-UI beziehungsweise Subframe-Adapter korrigieren, Visual-Baseline nachziehen und die stabile VM-/Action-Grenze beibehalten. Keine fachliche Logik in Routes oder UI verschieben.
|
||||
|
||||
**Vorgehen:**
|
||||
1. NIEMALS direkt im `app/routes/**` korrigieren — Designer baut neu in Subframe
|
||||
2. Subframe-Update → AI-Agent integriert in `packages/ui-hivegrid/src/adapters/`
|
||||
3. Visual-Regression-Gate (M016) zeigt Diff
|
||||
4. Merge
|
||||
### 2. View-Model oder Domain-Logik
|
||||
|
||||
**Risiko:** sehr niedrig. Layer-Trennung schützt.
|
||||
Pure VM-Builder, Zod-Schema und fokussierte Tests gemeinsam ändern. Bei Schreiblogik zusätzlich Audit, Activity, Notifications, Permission- und RLS-Kontext prüfen.
|
||||
|
||||
### Stufe 2: View-Model falsch (Daten-Form)
|
||||
### 3. Datenmodell oder öffentlicher Contract
|
||||
|
||||
**Anzeichen:** Funktion zeigt falsche Daten / fehlende Felder / falsche Aggregation.
|
||||
- Neue Forward-only-Migration; angewandte Migrationen nicht umbenennen oder editieren.
|
||||
- Inverse-SQL als Kommentar dokumentieren.
|
||||
- Alle abhängigen Ticket-Docs und Konsumenten im selben Änderungsschnitt nachziehen.
|
||||
- Prisma-Validierung, Migrations-Parität, RLS-Verträge und fokussierte Consumer-Tests ausführen.
|
||||
|
||||
**Vorgehen:**
|
||||
1. View-Model in `packages/view-models/src/<domain>/*.vm.ts` korrigieren
|
||||
2. Zod-Schema mit-aktualisieren
|
||||
3. Loader-Funktion im `app/routes/**` korrigieren
|
||||
4. UI-Component in `packages/ui-hivegrid/**` muss NICHT geändert werden (sonst war die Trennung schlecht)
|
||||
### 4. Ticket-Ansatz verwerfen
|
||||
|
||||
**Risiko:** mittel. Wenn die UI-Component die VM-Form falsch annimmt: neuer Vertrag.
|
||||
Noch nicht gemergte Checkpoints gezielt reverten oder den Branch verwerfen. Bereits gemergte Änderungen ausschließlich über neue Revert-/Fix-Commits korrigieren. Ticket-Doc mit Ursache, Auswirkungen, neuem Plan und aktuellem DoD-Prozentsatz aktualisieren.
|
||||
|
||||
### Stufe 3: Domain-Logik falsch
|
||||
## Notbremse
|
||||
|
||||
**Anzeichen:** Daten werden falsch geschrieben, Permissions stimmen nicht, falsche Side-Effects.
|
||||
Wenn ein ausgeliefertes Modul einen vorhandenen Feature- oder Ingress-Schalter besitzt, ihn kontrolliert deaktivieren und die operative Auswirkung dokumentieren. Kein neuer Schalter außerhalb des Ticket-Scopes und kein Deploy-Bypass.
|
||||
|
||||
**Vorgehen:**
|
||||
1. `app/domain/**` korrigieren (NICHT UI, NICHT VM)
|
||||
2. Bei DB-Schema-Änderung: neue Prisma-Migration als FORWARD-MIGRATION (kein Backward-Edit der alten)
|
||||
3. Bei Permission-Bug: Permission-Wrapper-Test in M004 erweitern
|
||||
4. Cross-Tenant-Probe-Test (M005) muss grün bleiben
|
||||
## Pflichtnachweise vor Push
|
||||
|
||||
**Risiko:** hoch. Daten könnten bereits in der DB falsch sein.
|
||||
|
||||
### Stufe 4: Komplettes Milestone neu
|
||||
|
||||
**Anzeichen:** Architektur-Fehler, falscher Layer-Schnitt, Anti-Pattern in der Foundation.
|
||||
|
||||
**Vorgehen:**
|
||||
1. Branch identifizieren — TC arbeitet pro Milestone in einem Branch
|
||||
2. Branch nicht mergen → revert ist trivial
|
||||
3. Wenn schon gemergt: `git revert <merge-commit>` als neuer Commit
|
||||
4. PLAN.md des Milestones aktualisieren (Lessons Learned als Hinweis für Slice-Planung)
|
||||
5. TC neu starten auf das Milestone
|
||||
|
||||
**Risiko:** sehr hoch wenn andere Milestones bereits darauf bauen. Deshalb: vor jedem Milestone PLAN.md prüfen, ob die Abhängigkeiten klar sind.
|
||||
|
||||
## Reversibilitäts-Pflichten pro Milestone
|
||||
|
||||
Bevor TC ein Milestone als fertig markiert, müssen folgende Rollback-Pfade existieren:
|
||||
|
||||
| Artefakt | Rollback-Pfad |
|
||||
|---|---|
|
||||
| **Code-Änderungen** | `git revert <slice-commit>` — atomic per Slice |
|
||||
| **DB-Migration** | Forward-Only-Migration mit dokumentiertem Inverse-SQL als Kommentar im Migration-File |
|
||||
| **Sidebar-Eintrag** | Eintrag in `sidebar.config.ts` löschen → Sidebar baut sich neu |
|
||||
| **Routes** | Route-Datei löschen → RR7 verweigert die URL |
|
||||
| **Permissions** | Permission-Key in `permissions.ts` als deprecated markieren |
|
||||
| **Feature-Flag** | Flag aus auf `false` → Modul unsichtbar ohne Code-Deploy |
|
||||
|
||||
## Notbremse: Feature-Flag
|
||||
|
||||
Jedes Modul, das in Produktion landet, kann via Feature-Flag aus M006 ausgeschaltet werden — ohne Deploy. Wenn etwas live brennt:
|
||||
|
||||
1. Plattform-Admin → Feature-Flags
|
||||
2. Flag des betroffenen Moduls auf `false` für betroffenen Mandanten
|
||||
3. Modul verschwindet aus der Sidebar (siehe sidebar.config.ts `feature_flag` Feld)
|
||||
4. Bug in Ruhe fixen
|
||||
5. Flag wieder auf `true`
|
||||
|
||||
## Was du als Mensch nicht selbst korrigieren solltest
|
||||
|
||||
- **NICHT direkt in `packages/ui-subframe/**`** — das ist Subframe-Output, wird beim nächsten Designer-Update überschrieben
|
||||
- **NICHT direkt in `packages/ui-hivegrid/src/adapters/**`** — der AI-Agent generiert das aus dem Subframe-Output
|
||||
- **NICHT in TC-State (`.tc/`)** ohne Backup
|
||||
|
||||
## Was du selbst korrigieren KANNST
|
||||
|
||||
- `docs/milestones/M*/PLAN.md` — Pflichtenheft-Bezug, Hinweise, Erfolgskriterien anpassen
|
||||
- `AGENTS.md` und `docs/INTEGRATION-CONTRACTS.md` — Agent-Regeln verschärfen
|
||||
- `docs/CHANGE-REQUESTS.md` — Change-Request festhalten
|
||||
|
||||
## Eskalationspfad
|
||||
|
||||
1. Feature-Flag aus (Notbremse)
|
||||
2. PLAN.md aktualisieren mit klarer Korrektur-Anweisung
|
||||
3. TC auf das Milestone neu starten oder gezielt eine Slice via `/tc steer` umsteuern
|
||||
4. Verify-Gates laufen lassen, bis grün
|
||||
5. Flag wieder an
|
||||
1. Betroffene Ticket-DoD und Dependencies konsistent.
|
||||
2. Passende fokussierte Tests und `verify:*`-Gates grün.
|
||||
3. `pnpm typecheck`, `pnpm lint` und `pnpm test` gemäß `docs/AGENT-CHECKLIST.md` grün.
|
||||
4. Rollback-Pfad und Forward-only-DB-Vertrag in der Ticket-Doc dokumentiert.
|
||||
5. Plane-Kommentar und Status erst nach dem lokalen Proof aktualisieren.
|
||||
@@ -1,329 +0,0 @@
|
||||
# HiveGrid 2.0 — Progress-Tracker
|
||||
|
||||
**Zweck:** Live-Übersicht über alle 176 Milestones. Der Agent updatet diese Datei nach jedem Milestone-Abschluss. Du als User prüfst über den Klick-Pfad und setzt Sign-Off.
|
||||
|
||||
**Master-Quellen:**
|
||||
- Master-Index: [`docs/milestones/README.md`](milestones/README.md)
|
||||
- Per-Milestone-Plan: `docs/milestones/M???-<slug>/PLAN.md`
|
||||
- Definition of Done: in jeder PLAN.md am Ende
|
||||
- Coverage: [`docs/milestones/PFLICHTENHEFT-COVERAGE.md`](milestones/PFLICHTENHEFT-COVERAGE.md)
|
||||
|
||||
---
|
||||
|
||||
## Status-Legende
|
||||
|
||||
| Status | Bedeutung |
|
||||
|---|---|
|
||||
| `⚪ NICHT-GESTARTET` | Milestone wartet, Abhängigkeiten ggf. offen |
|
||||
| `🔵 IN-ARBEIT` | Agent plant oder führt Slices aus |
|
||||
| `🟡 READY-TO-VERIFY` | Agent fertig, Verify-Gates grün, wartet auf User-Sign-Off via Klick-Pfad |
|
||||
| `🟢 SIGNED-OFF` | User hat Klick-Pfad durchlaufen und bestätigt |
|
||||
| `🔴 BLOCKED` | Agent kann nicht weiter, User-Input nötig |
|
||||
| `🟣 PARKED` | Bewusst zurückgestellt |
|
||||
| `🟦 BOILERPLATE-PATTERN` | Pattern in Boilerplate vorhanden — HiveGrid-Agent füllt nur Inhalte ein |
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 — Vorbedingungen (außerhalb der 176)
|
||||
|
||||
| Aufgabe | Status | Bemerkung |
|
||||
|---|---|---|
|
||||
| EU-Sterilisation der Boilerplate | 🟢 SIGNED-OFF | 2026-05-11 verifiziert: Anthropic/OpenAI/Google-Auth raus; Mistral via `@ai-sdk/mistral` (`packages/ai/src/providers/mistral.ts`), Scaleway + AlephAlpha + compatible-Adapter vorhanden; Multi-Provider-Fallback (`packages/ai/src/fallback.ts`) |
|
||||
| RR7-Migration zu Ende | 🟢 SIGNED-OFF | 2026-05-11 verifiziert: `apps/web/app` ist authoritative, kein Root-Hybrid mehr (siehe `boilerplate/docs/architecture-migration-status.md`) |
|
||||
| Phase-C-Foundation in Boilerplate (`packages/foundation`, `view-models`, `ui-app`, `ui-mock`, `ui-subframe`) | 🟢 SIGNED-OFF | 2026-05-11 verifiziert: `pnpm verify:phase-c-boundaries` läuft grün; alle Foundation-Patterns in `@hivegrid/foundation` exportiert |
|
||||
| Boilerplate-Inhalt in `HiveGrid-Cloud/` übernommen | 🟢 erledigt | 2026-06-04 via **git-merge** (downstream), nicht rsync — siehe `docs/ARCHITECTURE-DECISIONS.md` AD-10 |
|
||||
| **Phase-0 Pre-Flight im Code umgesetzt** | 🟢 erledigt | 2026-06-05: AGENTS Pre-Flight-Check besteht alle 4 Schritte; Build-Baseline + EU-Steri (OAuth raus) + M00-Neubauten (4/4) committed; offen nur #19 Deps (just-in-time) |
|
||||
| `AGENTS.md` + `docs/INTEGRATION-CONTRACTS.md` + `docs/MID-STREAM-CHANGES.md` + `docs/TC-PLANNING-BRIEFING.md` im Repo | 🟢 SIGNED-OFF | 2026-05-10 |
|
||||
| 176 Milestone-Verzeichnisse mit `PLAN.md` | 🟢 SIGNED-OFF | 2026-05-10 |
|
||||
| `docs/PROGRESS-TRACKER.md` (diese Datei) angelegt | 🟢 SIGNED-OFF | 2026-05-10 |
|
||||
| Doku-Naming-Anpassung an Boilerplate-Realität (`ui-app` → `ui-app`, `@hivegrid/foundation` → `@hivegrid/foundation`, AdapterStatus, VMStatus) | 🟢 erledigt | 2026-06-05, AGENTS.md (commit `206e1ea3`); ältere PLANs/Specs via AD-10-Mapping-Notiz abgedeckt (kein flächiges Rename) |
|
||||
|
||||
**Boilerplate-Realität ab 2026-05-11:** Die EU-Sterilisation + RR7-Migration + Phase-C-Foundation sind technisch abgeschlossen. Die HiveGrid-Milestones M001-M017 sind in der Boilerplate als **Pattern** umgesetzt — der HiveGrid-Agent muss sie nicht implementieren, sondern nur mit HiveGrid-spezifischen Inhalten befüllen.
|
||||
|
||||
**Pattern-Standorte in der Boilerplate (für HiveGrid-Agent):**
|
||||
|
||||
| HiveGrid-Pflicht | Pattern in Boilerplate |
|
||||
|---|---|
|
||||
| Audit-Log default (M001) | `@hivegrid/foundation` → `withAuditMiddleware`, `AuditEventInput`, `AuditEventClient`; DB: `packages/db/src/audit-events.server.ts` |
|
||||
| Klartext-Diagnostik (M002) | `@hivegrid/foundation` → `CatalogError`, `catalogRegistry` (leer, HiveGrid füllt), `foundationErrors`, `toPinoLogObject` |
|
||||
| i18n-Pflicht (M003) | `@hivegrid/foundation` → `assertI18nKey`; CI: `pnpm verify:i18n` (i18n-check.ts + ESLint) |
|
||||
| Tenant-Scope + Permissions (M004, M005) | `@hivegrid/foundation` → `withTenantScope`, `withPermission`, `withOwnerCheck`, `requirePermission`, `PermissionContext` |
|
||||
| Feature-Flag-Engine (M006) | `@hivegrid/foundation` → `defineFlag`, `featureFlag`, `FlagDefinition`, `FlagResolutionInput` |
|
||||
| Idempotenz-Wrapper (M007) | `@hivegrid/foundation` → `IdempotencyClient`, `IdempotencyResponse` |
|
||||
| Apps-Engine-Adapter + State-Machine (M008, M009, M010) | `@hivegrid/foundation` → `defineAdapter`, `getAdapter`, `AdapterStatus` (`not_configured \| configured \| healthy \| degraded \| unavailable`); Plugin-Loader: `@hivegrid/plugins` |
|
||||
| Notification-Service (M011) | `@hivegrid/foundation` → `notify`, `notifyMany`, `bundleNotifications`, `isNotificationEnabled`, `NotificationInput` |
|
||||
| Workspace-Topologie (M012) | Bereits angelegt: `packages/view-models`, `packages/ui-app`, `packages/ui-subframe`, `packages/ui-mock` |
|
||||
| View-Model-Konvention (M013) | `@hivegrid/view-models` → `VMState<T>` (`idle \| loading \| ready \| empty \| error`), `ActionCallbacks<T>`, `I18nLabel`, `RegistryGate`, `ready`, `empty`, `assertI18nLabel` |
|
||||
| Action-Callback-Contract (M014) | `@hivegrid/view-models` → `ActionCallbacks<T>` mit `onCreate`, `onUpdate`, `onDelete`, `onRefresh` |
|
||||
| Subframe-Adapter-Layer (M015) | `packages/ui-subframe` ist als leeres Paket reserviert (README erklärt die Vendor-Import-Boundary) |
|
||||
| Visual-Regression-Gate (M016) | CI-Script `pnpm verify:ui-visual` läuft + `scripts/verify-ui-mock-visual.ts` |
|
||||
| Hot-Swap-Drill (M017) | CI-Job „Test UI mock hot-swap" in `.gitea/workflows/ci.yml` + `pnpm test:hot-swap` → `pnpm verify:ui-hot-swap` |
|
||||
|
||||
---
|
||||
|
||||
## Master-Tabelle (176 Milestones)
|
||||
|
||||
| ID | Titel | Status | DoD-Score | Slices | Sign-Off |
|
||||
|---|---|---|---|---|---|
|
||||
| **M001** | Audit-Log default | 🟦 BOILERPLATE-PATTERN | – | – | HiveGrid füllt Inhalte |
|
||||
| **M002** | Klartext-Diagnostik | 🟦 BOILERPLATE-PATTERN | – | – | HiveGrid füllt Inhalte |
|
||||
| **M003** | i18n-Pflicht-Wiring | 🟦 BOILERPLATE-PATTERN | – | – | HiveGrid füllt Inhalte |
|
||||
| **M004** | Tenant-Scope-Wrapper + Owner-Check | 🟦 BOILERPLATE-PATTERN | – | – | HiveGrid füllt Inhalte |
|
||||
| **M005** | URL-Tampering Hardening + Mass-Action-Schutz | 🟦 BOILERPLATE-PATTERN | – | – | HiveGrid füllt Inhalte |
|
||||
| **M006** | Feature-Flag-Engine (Code-Layer) | 🟦 BOILERPLATE-PATTERN | – | – | HiveGrid füllt Inhalte |
|
||||
| **M007** | Idempotenz-Wrapper für BullMQ-Steps | 🟦 BOILERPLATE-PATTERN | – | – | HiveGrid füllt Inhalte |
|
||||
| **M008** | Apps-Engine: Adapter-Interface + State-Machine | 🟦 BOILERPLATE-PATTERN | – | – | HiveGrid füllt Inhalte |
|
||||
| **M009** | Apps-Engine: Setup-Wizard + Sync-Log | 🟦 BOILERPLATE-PATTERN | – | – | HiveGrid füllt Inhalte |
|
||||
| **M010** | Apps-Engine: Probe-Scheduler + Webhook-Sturm-Schutz | 🟦 BOILERPLATE-PATTERN | – | – | HiveGrid füllt Inhalte |
|
||||
| **M011** | Notification-Service-Layer | 🟦 BOILERPLATE-PATTERN | – | – | HiveGrid füllt Inhalte |
|
||||
| **M012** | Workspace-Topologie | 🟦 BOILERPLATE-PATTERN | – | – | HiveGrid füllt Inhalte |
|
||||
| **M013** | View-Model-Konvention | 🟦 BOILERPLATE-PATTERN | – | – | HiveGrid füllt Inhalte |
|
||||
| **M014** | Action-Callback-Contract | 🟦 BOILERPLATE-PATTERN | – | – | HiveGrid füllt Inhalte |
|
||||
| **M015** | Subframe-Adapter-Layer | 🟦 BOILERPLATE-PATTERN | – | – | HiveGrid füllt Inhalte |
|
||||
| **M016** | Visual-Regression-Gate | 🟦 BOILERPLATE-PATTERN | – | – | HiveGrid füllt Inhalte |
|
||||
| **M017** | Hot-Swap-Drill | 🟦 BOILERPLATE-PATTERN | – | – | HiveGrid füllt Inhalte |
|
||||
| **M018** | Mandanten-Anlage | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M019** | Mandanten-Trennung Hardening | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M020** | Email/Passwort-Auth + HIBP + Brute-Force | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M021** | Magic-Link + Sitzungs-Verwaltung | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M022** | TOTP-2FA + Notfall-Codes | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M023** | Rollen-Engine + 6 SHK-Standard-Rollen + Gruppen | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M024** | Mitarbeiter-Einladung / Deaktivierung / Umverteilung | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M025** | Konto-Löschung (User + Admin) | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M026** | Mandanten-Lebenszyklus | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M027** | API-Keys + Tarif-Feature-Gates | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M028** | User/Tenant Sprach-Settings + Auflösungs-Reihenfolge | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M029** | Sprach-Wechsler + Fallback-Hinweise | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M030** | Hell/Dunkel-Modus + PWA Theme-Color | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M031** | Feature-Flag Schalter-Definition + Lifecycle | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M032** | Feature-Flag Filter-Editor + Einzel-Ausnahme-Editor | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M033** | Feature-Flag Massen-Funktionen + Statistik + Audit-Historie | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M034** | Plattform-Admin-Auth (admin.<domain>) | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M035** | Plattform-Admin-Dashboard | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M036** | Mandanten-Verwaltung (Plattform-Admin) | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M037** | Stellvertreter-Anmeldung („Login as") | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M038** | Mandanten-Mitarbeiter-Verwaltung (Plattform-Admin) | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M039** | Plattform-Admin-Konten + Rollen | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M040** | Interne Lead-Pipeline (HiveGrid-Verkäufe) | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M041** | System-Health + Audit-Anzeige + Datenschutz + Support | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M042** | Kontakt-Stammdaten | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M043** | Firma-Stammdaten + Hierarchie | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M044** | Schlagwörter + Custom-Felder + Datenherkunft | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M045** | Aktivitäts-Stream | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M046** | Listen + Segmente + DSGVO-Felder | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M047** | Lead-Inbox + Quellen-Adapter | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M048** | Lead-Routing pro Quelle [N4] | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M049** | Auto-Projekt-Anlage | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M050** | Spam/Duplikat-Erkennung | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M051** | Lead-Status-Pipeline + Verlust-Gründe + Notifications | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M052** | Datei-Upload (Anti-Virus + Format-Whitelist) | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M053** | Speicher-Backend (Hetzner Object Storage) | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M054** | Datei: Permissions + Sharing + Versionierung | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M055** | Datei: Suche + Tagging + Archivierung | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M056** | Globale Suche: Such-Index | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M057** | Globale Suche: Permission-aware | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M058** | Globale Suche: UI + Saved-Searches | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M059** | Sales-Pipeline: Konfiguration + SHK-Standard-Pipeline | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M060** | Projekt-CRUD in Sales-Pipeline-Sicht [N6] | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M061** | Sales-Pipeline: Kanban-UI + Drag&Drop | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M062** | Sales-Pipeline: Verlust/Gewinn-Gründe [N8] | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M063** | Auto-Auftragsprojekt [N7] + Setter-Closer [N17] | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M064** | Sales-Pipeline: Reporting + KWP-Sync | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M065** | Auftragspipeline: Konfiguration | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M066** | Auftrag-CRUD + KWP-Dokumenten-Archiv [N5] | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M067** | Plantafel mit Tagen-Granularität [N10] | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M068** | Auftrag: Mitglieder-Mgmt + Rollen pro Auftrag | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M069** | Auftrag: Abnahme-Workflow + Mängel-Liste | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M070** | Auftrag: Material-Listen + Lager-Anbindung | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M071** | Aufgaben-CRUD + Zuweisung | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M072** | Aufgaben-Listen pro Modul (Inline) | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M073** | Aufgaben: Erinnerungen + Push + Email | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M074** | Aufgaben-Sync mit ERP-Aufgaben-Welt [N11] | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M075** | Automation: Schema + Auslöser-Registry | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M076** | Automation: Aktion-Registry + Steuerungs-Bausteine | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M077** | Automation: Bedingungen | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M078** | Automation: Visueller Editor | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M079** | Automation: Test-Lauf + Schwellenwert-Vorschau | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M080** | Automation: 24h-Undo-Fenster + Reversibilität | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M081** | Automation: Schleifen-Schutz + Webhook-Sturm + Anomalie | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M082** | Automation: Klartext-Logs + Re-Run + Trigger-Volumen-Metering | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M083** | KI: EU-Provider-Layer | 🟣 PARKED | – | – | Entfällt nach AD-26 |
|
||||
| **M084** | KI: Multi-Provider-Fallback | 🟣 PARKED | – | – | Entfällt nach AD-26 |
|
||||
| **M085** | KI: Promptfoo-Eval-Suite | 🟣 PARKED | – | – | Entfällt nach AD-26 |
|
||||
| **M086** | KI: Sprach-zu-Automation | 🟣 PARKED | – | – | Entfällt nach AD-26 |
|
||||
| **M087** | KI: RAG-Layer + Aktions-Grenze | 🟣 PARKED | – | – | v3-Kandidat; v2 ist VR-MCP |
|
||||
| **M088** | KI: Token-Limits + Pay-as-you-go | 🟣 PARKED | – | – | Entfällt nach AD-26 |
|
||||
| **M089** | KWP-API-Connector (REST/OAuth über Apps-Engine) [Re-Cut] | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M090** | KWP-API Connection-Health [Re-Cut] | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M091** | KWP-Push-Queue + Replay (Cloud-Outbox) [Re-Cut] | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M092** | KWP-API-Contract-Sentinel [Re-Cut] | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M093** | KWP: Konflikt-Auflösung „KWP gewinnt" [N14] | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M094** | KWP: Bidirektionale Plantafel-Sync [N10] | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M095** | KWP: Dokumenten-Archiv-Sync KWP→HiveGrid [N5] | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M096** | Email-Inbox: Gmail-OAuth-Integration via Apps-Engine | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M097** | Email-Inbox: Sync + Inbox-UI + Threading + Auto-Verknüpfung | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M098** | Email-Versand + Vorlagen + Variable-Resolution | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M099** | Email-Tracking + Delivery-Status + Bounces | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M100** | Email-Marketing: Editor (Block-Style) | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M101** | Email-Marketing: Segmente + Empfänger-Auswahl | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M102** | Email-Marketing: Versand-Engine + DKIM/SPF + Frequenz-Schutz | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M103** | Email-Marketing: Reporting (Open/Click + Klick-Karte + Pro-Empfänger) | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M104** | Email-Marketing: Unsubscribe + Bounce-Handling + Pflicht-Footer | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M105** | Telefonie: HalloPetra-Adapter [N16] | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M106** | Telefonie: AirCall-Adapter | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M107** | Telefonie: Anruf-Eingang + CRM-Verknüpfung + Auto-Match | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M108** | Telefonie: Anruf-Ausgang + Click-to-Call | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M109** | Telefonie: Voicemail + Anruf-Notizen + Aufgaben-Auto-Anlage | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M110** | Team-Chat: Channel-Modell + Permissions | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M111** | Team-Chat: Nachrichten + Threads + Pinned + Reactions | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M112** | Team-Chat: Datei/Foto-Anhänge | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M113** | Team-Chat: Modul-Verknüpfungen | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M114** | Team-Chat: Mentions + Push + Lese-Bestätigungen | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M115** | Notification-Center + Lese-Status | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M116** | Notifications: User-Settings (Kanal + Stille Stunden) | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M117** | Notifications: Kategorien + Bündelung + Anti-Spam | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M118** | Calendar: Google + Microsoft via Apps-Engine | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M119** | Calendar: Termin-Sync (bidirektional) + Konflikt-Auflösung | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M120** | Calendar: Display + Modul-Verknüpfung + Activity-Stream | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M121** | Form-Builder: Editor | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M122** | Form-Builder: Veröffentlichung + Sharing + Embed | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M123** | Form-Builder: Submission-Eingang + CRM-Verknüpfung + Aktionen | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M124** | Form-Builder: Conditional-Display (kein Branching) | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M125** | Form-Builder: Rate-Limit + Captcha + DSGVO-Pflicht | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M126** | Booking: Buchungs-Seite + Time-Slot-Engine | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M127** | Booking: Verfügbarkeits-Berechnung | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M128** | Booking: Bestätigungs-Flow + Verknüpfungen | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M129** | Booking: Stornierung + Verschiebung + No-Show-Tracking | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M130** | Angebot: Erstellung (PDF aus Datei-Speicher oder Upload) | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M131** | Angebot: Self-hosted E-Signatur + optionale Anbieter-Adapter | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M132** | Angebot: Status-Tracking + Auto-Stage-Wechsel | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M133** | HR: Mitarbeiter-Stammdaten + Standorte | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M134** | HR: Dokumente + Lohnabrechnungen + Verschlüsselter Passwort-Safe | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M135** | HR: Urlaubsanträge + Genehmigungs-Workflow | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M136** | HR: Krankmeldungen + Atteste | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M137** | HR: Schwarzes Brett (Bekanntmachungen) + Quick-Links + Resources | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M138** | HR: Onboarding-Drittanbieter (Memberspot/Boobora) [N18] | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M139** | HR: Generische Anträge + Berichte + Lohn-Export + Surveys | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M140** | HR: Mitarbeiter-Selbstbedienung + Mobile-First | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M141** | Customer-Portal: Auth (separater Login-Flow) | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M142** | Customer-Portal: Projekt-Sicht + Status-Mails | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M143** | Customer-Portal: Datei-Upload durch Endkunde + Reklamations-Forms | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M144** | Customer-Portal: Subunternehmer-Zugang [N19] | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M145** | Customer-Portal: Skalierungs-Sicht (Service-Inbox + Routing) [N19] | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M146** | Customer-Portal: Pro-Kunden-Lebensdauer + DSGVO + Konfig [N19] | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M147** | Dashboard: Layout + Widget-Engine | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M148** | Dashboard: 7 Rollen-Standard-Layouts | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M149** | Dashboard: Drill-Down + Custom-Widget-Konfiguration | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M150** | Dashboard: Export + Report-Versand | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M151** | Audit-Log: Anzeige + Filter + Volltext-Suche | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M152** | Audit-Log: Compliance-Export + Aufbewahrung + Legal Hold | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M153** | Subscriptions: Legacy-Provider-Integration (EU) | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M154** | Subscriptions: Plan-Engine + Seat-Modell (Büro/Monteur) | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M155** | Subscriptions: Trial-Phase + Read-Only-Downgrade + Frozen-Modus | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M156** | Subscriptions: Verbrauchs-Erfassung + Pay-as-you-go [N13] | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M157** | Onboarding: Wizard-Framework + State-Machine | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M158** | Onboarding: SHK-Standard-Daten-Provisionierung | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M159** | Onboarding: Branchen-Templates deklarativ (A.3) | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M160** | Onboarding: Demo-Daten + Bulk-Löschung | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M161** | Public-API: OpenAPI-Spec + Read-Endpoints | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M162** | Public-API: API-Key-Auth + Scopes + Rate-Limit | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M163** | Public-API: Webhooks (signiert, ein- und ausgehend) | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M164** | DSGVO: User-Daten-Export + Mandanten-Daten-Export | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M165** | DSGVO: Account-Löschung + Mandanten-Lösch-Workflow | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M166** | DSGVO: AVV-Vertrag + Subprozessoren-Liste + Auskunfts-Workflow | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M167** | Mobile-PWA: Manifest + Installierbarkeit + Update-Basis | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M168** | Mobile-PWA: Web-Push + Kamera/Web-Features + Deep Links | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M169** | Mobile-PWA: Mobile Navigation + Mobile-First-Routes (Baustelle) | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M170** | Mobile-PWA: Offline-Modus für Baustelle | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M171** | Mobile-PWA: Force-Update + PWA-Härtung | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M172** | Help-Center: Markdown-Artikel-Mgmt (Git-PRs) | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M173** | Help-Center: Routes + Suche + SEO + Kontextuelle Hilfe | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M174** | Help-Desk: Email-basiertes Ticket-System + Plattform-Admin-Bearbeitung | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M175** | Help-Desk: In-App-Feedback-Widget („Problem melden") | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
| **M176** | Anti-Liste + Change-Request-Workflow als Repo-Doku | ⚪ NICHT-GESTARTET | 0/14 | – | – |
|
||||
|
||||
---
|
||||
|
||||
## Detail-Sektionen pro Milestone
|
||||
|
||||
> **Anweisung an den Agent:** Sobald ein Milestone in IN-ARBEIT geht, ergänze hier eine Detail-Sektion gemäß folgender Vorlage. Nach Abschluss aller Slices: Status auf `🟡 READY-TO-VERIFY`. User trägt nach Sign-Off `🟢 SIGNED-OFF` mit Datum ein.
|
||||
|
||||
### Vorlage (zu kopieren pro Milestone)
|
||||
|
||||
```markdown
|
||||
### M??? — <Titel> — Status: 🔵 IN-ARBEIT
|
||||
|
||||
**Pflichtenheft-Bezug:** _bmad-output/pflichtenheft/blocks/blockX.md Sektion Y.Z
|
||||
|
||||
**Slice-Status:** N von M abgeschlossen
|
||||
- [x] S01: <slice-title> — Commit: <hash>
|
||||
- [x] S02: <slice-title> — Commit: <hash>
|
||||
- [ ] S03: <slice-title>
|
||||
|
||||
**Definition of Done:**
|
||||
|
||||
*Erreichbarkeit*
|
||||
- [ ] Sidebar-Eintrag — Datei: `apps/web/app/application/sidebar/` — Gruppe: <Gruppe> — Permission: <key>
|
||||
- [ ] Route — `app/routes/<...>.tsx`
|
||||
- [ ] Breadcrumb — `packages/ui-app/src/breadcrumbs/<...>.ts`
|
||||
- [ ] Mobile-Tab-Bar — falls relevant: `packages/ui-app/src/mobile/tab-bar.config.ts`
|
||||
- [ ] Customer-Portal-Sichtbarkeit — falls relevant: `packages/ui-app/src/customer-portal/portal-shell.config.ts`
|
||||
|
||||
*Querschnitt-Wiring*
|
||||
- [ ] Audit (auto via M001 oder manuell)
|
||||
- [ ] Activity-Stream via logActivity()
|
||||
- [ ] Notifications via notify()
|
||||
- [ ] Search-Index registriert
|
||||
- [ ] Permission-Filter via withTenantScope() + withPermission()
|
||||
- [ ] Feature-Flag-fähig
|
||||
|
||||
*Code-Layer-Disziplin*
|
||||
- [ ] Loader baut VM, UI nur Props
|
||||
- [ ] Keine Prisma-Imports in ui-app
|
||||
- [ ] Alle UI-Texte als i18n-Keys
|
||||
|
||||
*Tests*
|
||||
- [ ] Unit-Test (VM-Builder + Zod): `<test-path>`
|
||||
- [ ] Smoke-Test: `e2e/smoke/<modul>.spec.ts`
|
||||
- [ ] Hot-Swap-Drill: grün
|
||||
- [ ] Visual-Regression-Snapshot: <Anzahl> Bilder
|
||||
|
||||
*Klartext + Rollback*
|
||||
- [ ] Fehler-Texte aus M002-Catalog
|
||||
- [ ] Empty/Loading/Error-States
|
||||
- [ ] 404 statt 403 bei fehlender Permission
|
||||
- [ ] Forward-Only-DB-Migration mit Inverse-SQL-Kommentar
|
||||
- [ ] Feature-Flag zum Abschalten ohne Deploy
|
||||
|
||||
**DoD-Score:** N/14 erfüllt
|
||||
|
||||
**Klick-Pfad zum Prüfen** (für User):
|
||||
1. Login als <user-typ> auf `app.hivegrid.de`
|
||||
2. Sidebar → <Gruppe> → <Eintrag>
|
||||
3. <Aktion ausführen>
|
||||
4. <Erwartetes UI / Ergebnis>
|
||||
|
||||
**Notes vom Agent:** <was war nicht offensichtlich, was hat länger gedauert, was muss User wissen>
|
||||
|
||||
**User-Sign-Off:** [ ] Klick-Pfad durchlaufen, alles wie erwartet — Datum: <YYYY-MM-DD>, User: <Name>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Agent startet Milestone** → Status auf `🔵 IN-ARBEIT`, Detail-Sektion anlegen
|
||||
2. **Agent baut Slices** → Slice-Liste abhaken, Commit-Hashes eintragen
|
||||
3. **Agent hat alle DoD-Punkte erfüllt** → Status auf `🟡 READY-TO-VERIFY`
|
||||
4. **User durchläuft Klick-Pfad** → wenn alles ok: User trägt `🟢 SIGNED-OFF` + Datum ein. Wenn nicht ok: User trägt Notes ein, Status zurück auf `🔵 IN-ARBEIT`
|
||||
5. **Agent geht zum nächsten Milestone** — nicht vorher
|
||||
|
||||
## Konsistenz-Check
|
||||
|
||||
- DoD-Score in der Master-Tabelle muss zur Detail-Sektion passen
|
||||
- `🟡 READY-TO-VERIFY` ohne 14/14 DoD = inkonsistent → Agent muss korrigieren
|
||||
- `🟢 SIGNED-OFF` ohne Datum + User = inkonsistent → User muss ergänzen
|
||||
|
||||
## Pflege
|
||||
|
||||
Diese Datei ist Live-Dokument. Pflicht-Update bei jedem Status-Wechsel. Bei mehr als 5 Milestones IN-ARBEIT gleichzeitig: STOP, an User melden — wir wollen Fokus, nicht Chaos.
|
||||
@@ -2,22 +2,22 @@
|
||||
|
||||
`docs/` ist **technische Plattform-Referenz** plus HiveGrid-spezifische Entscheidungs-/Bau-Dokumente.
|
||||
|
||||
> **Du willst PLANEN/steuern?** → nicht hier, sondern **`.planning/`** (Live-Planung: PROJECT, ROADMAP, STATE, REQUIREMENTS, ENTITY-MODEL).
|
||||
> **Du willst BAUEN?** → `docs/milestones/` (die PLAN.md je Milestone) + `docs/ARCHITECTURE-DECISIONS.md` + `docs/INTEGRATION-CONTRACTS.md`.
|
||||
> **Du willst PLANEN/steuern?** → Plane für Status und Dependencies, `.planning/ticket-docs/<ID>.md` für Scope und DoD.
|
||||
> **Du willst BAUEN?** → Ticket-Doc + `AGENTS.md` + `docs/INTEGRATION-CONTRACTS.md`.
|
||||
> **Du willst wissen, warum?** → `docs/ARCHITECTURE-DECISIONS.md`.
|
||||
|
||||
**Stand:** 2026-07-01 · Infra-Realität: **Hetzner + Coolify + Cloudflare**.
|
||||
**Stand:** 2026-08-02 · Infra-Realität: **Hetzner + Coolify + Cloudflare**.
|
||||
|
||||
## HiveGrid-spezifisch (wichtig, gepflegt)
|
||||
| Datei/Ordner | Inhalt |
|
||||
|---|---|
|
||||
| **ARCHITECTURE-DECISIONS.md** | verbindliche ADRs (inkl. Projekt-zentrisches Modell und Bespoke-Pivot) |
|
||||
| **ARCHITECTURE-DECISIONS.md** | kompaktes Register der AD-IDs, Gründe und Status; operative Regeln stehen in `AGENTS.md` |
|
||||
| **INTEGRATION-CONTRACTS.md** | Modul-Integrationsvertrag (Sidebar/Routes/Search/Notifications/Entitlement-Gate) |
|
||||
| **milestones/** | Milestone-PLANs — **aktiv** von `.planning/PHASE-SOURCES.md` referenziert |
|
||||
| **feature-inventory.md** + **feature-decisions/** + **feature-manifests/** | Feature-Klassifikation. ⚠ `feature-manifests/*.json` werden **zur Laufzeit/von Tests geladen** — nicht anfassen |
|
||||
| **TC-PLANNING-BRIEFING.md** · **MID-STREAM-CHANGES.md** · **PROGRESS-TRACKER.md** | Agent-Briefing · Rollback-Playbook · Live-Fortschritts-Tracker |
|
||||
| **UAT.md** | stabile Golden-Journey-Landkarte; Details und DoD bleiben in den Ticket-Docs |
|
||||
| **MID-STREAM-CHANGES.md** | Rollback-Playbook für ticket-getriebene Änderungen |
|
||||
|
||||
## Plattform-Referenz (Boilerplate — Nachschlagen, selten Startpunkt)
|
||||
deployment*.md · worker.md · database.md / db-*.md · mail*.md · env-vars.md / env-access-inventory.md · plugins.md · api.md · observability.md · security.md + **security/** · **architecture/** · troubleshooting.md · upgrade(s).md · versioning.md · configuration.md · local-dev.md · quickstart.md · production-checklist.md / release-checklist.md · roles-matrix.md · data-retention.md
|
||||
deployment.md · staging-live-uat.md · worker.md · database.md / db-*.md · mail*.md · env-vars.md / env-access-inventory.md · plugins.md · api.md · observability.md · security.md + **security/** · **architecture/** · troubleshooting.md · configuration.md · local-dev.md · quickstart.md · roles-matrix.md · data-retention.md
|
||||
|
||||
## Betriebs-/Spezial-Ordner
|
||||
- **ops/** = operative Runbooks (Queues, PgBouncer, Backups, CDN, Lago-Staging/Production-Prep, Billing-Meter)
|
||||
@@ -26,5 +26,7 @@ deployment*.md · worker.md · database.md / db-*.md · mail*.md · env-vars.md
|
||||
- **deploy/** (Service-Runbooks, z.B. Meilisearch) · **deployments/** (Referenz-Deploy boiler-saas-ctrl) · **agent-playbooks/** · **contributing/** · **testing/** · **plugins/** · **ui-inventory/** · **compliance/** · **storage/** · **auth/** · **verification/**
|
||||
|
||||
## Historisch — NICHT Startpunkt
|
||||
- **archive/** · **releases/** · **reports/** — abgeschlossene Artefakte.
|
||||
- Die früheren Boilerplate-Abgleichs-Ordner (`boilerplate-mapping/`, `boilerplate-inventory/`, `improvement-plan/`) wurden im Bespoke-Cleanup entfernt. Quelle für HiveGrid sind `.planning/`, `docs/milestones/`, `docs/ARCHITECTURE-DECISIONS.md` und die Ticket-Docs.
|
||||
- **archive/** · **reports/** — abgeschlossene Artefakte.
|
||||
- Die früheren Boilerplate-Abgleichs- und Milestone-Archive wurden im Bespoke-Cleanup entfernt. Aktive
|
||||
Quellen sind `AGENTS.md`, die Ticket-Docs, `.planning/ENTITY-MODEL.md` und
|
||||
`.planning/REQUIREMENTS.md`; das AD-Register erklärt Entscheidungen, dupliziert aber keine Regeln.
|
||||
Binary file not shown.
@@ -1,286 +0,0 @@
|
||||
# HiveGrid-Briefing für HiveGrid 2.0
|
||||
|
||||
**Adressat:** HiveGrid + alle AI-Coding-Agents (Sub-Agents von TC), die an HiveGrid arbeiten.
|
||||
**Stand:** 2026-05-10
|
||||
**Verbindlichkeit:** dieses Dokument plus die hier referenzierten Pfade definieren das Vorgehen vollständig.
|
||||
|
||||
---
|
||||
|
||||
## 0. Was du baust
|
||||
|
||||
HiveGrid 2.0 ist eine Multi-Tenant-SaaS-Plattform für SHK-Handwerksbetriebe. Erstkunde: Geerkens. EU-Stack komplett (kein US-Anbieter). Repository-Wurzel: `/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud`.
|
||||
|
||||
176 Milestones in `docs/milestones/M001/` bis `docs/milestones/M176/`. Jedes Verzeichnis enthält genau eine Datei `PLAN.md`. Diese sind deine Arbeits-Aufträge.
|
||||
|
||||
## 0.1 Die Boilerplate IST deine Codebase — nicht „eine Vorlage"
|
||||
|
||||
Das Repo `HiveGrid-Cloud/` enthält die EU-sterilisierte HiveGrid-Boilerplate als Fundament. Das ist **dein Code**, du editierst, erweiterst und löschst ihn. Du klonst nichts, du importierst nichts „von außen", du baust **nicht** parallel ein neues Projekt.
|
||||
|
||||
Konkret heißt das:
|
||||
- `apps/web/`, `apps/api/`, `apps/worker/`, `packages/db/`, `packages/mail/`, `packages/queue/`, `packages/ui/`, `prisma/`, `package.json` mit pnpm-Workspace, Tailwind 4, shadcn/Radix, BullMQ, MailerSend → das ist deine Arbeitsbasis. Du nutzt sie.
|
||||
- Du erweiterst, was fehlt: neue `packages/view-models/`, `packages/ui-hivegrid/`, `packages/ui-subframe/` (Phase 1 leer), neue Routes unter `app/routes/...`, neue Module unter `app/domain/...`, neue Prisma-Modelle in `prisma/schema/...`
|
||||
- Du löschst, was nicht zu HiveGrid gehört (Affiliate/Marketing/CMS-Reste aus dem HiveGrid-Boilerplate, falls noch vorhanden)
|
||||
- Du baust **in** dieser Codebase, nicht **neben** ihr
|
||||
|
||||
## 0.2 Pre-Flight-Check beim Start (jedes Mal)
|
||||
|
||||
Bevor du das erste Milestone planst, verifiziere die Vorbedingungen:
|
||||
|
||||
1. `package.json` im Repo-Root existiert mit pnpm-Workspace-Konfig — wenn nein: STOP, melde „Boilerplate-Inhalt fehlt im Repo"
|
||||
2. `apps/`, `packages/`, `prisma/` existieren — wenn nein: STOP
|
||||
3. `pnpm install && pnpm typecheck && pnpm test` läuft grün — wenn nein: STOP, melde welche Tests rot sind
|
||||
4. Kein US-Provider im Code: `grep -rE "@ai-sdk/openai|@ai-sdk/anthropic|remix-auth-google|from \"openai\"" --include="*.ts" --include="*.tsx" --include="*.json" .` ist leer — wenn nein: STOP, EU-Sterilisation nicht abgeschlossen
|
||||
5. `docs/PROGRESS-TRACKER.md` existiert — wenn nein: STOP
|
||||
|
||||
Erst nach 5/5 grün beginnst du mit dem ersten Milestone.
|
||||
|
||||
---
|
||||
|
||||
## 1. Wo du alles findest
|
||||
|
||||
| Was | Wo |
|
||||
|---|---|
|
||||
| **Verbindliches Pflichtenheft v1.1** | `_bmad-output/pflichtenheft/` |
|
||||
| → Vision + Anti-Liste | `_bmad-output/pflichtenheft/02-vision.md` |
|
||||
| → 20 Architektur-Bauprinzipien | `_bmad-output/pflichtenheft/03-architektur.md` |
|
||||
| → 7 Modul-Blöcke mit Detail-Pflichten | `_bmad-output/pflichtenheft/blocks/block1.md` … `block7.md` |
|
||||
| → Anhang (Geparktes, Noah-Anmerkungen N1-N19) | `_bmad-output/pflichtenheft/99-anhang.md` |
|
||||
| **Master-Milestone-Index** | `docs/milestones/README.md` |
|
||||
| **Pflichtenheft → Milestone Coverage-Map** | `docs/milestones/PFLICHTENHEFT-COVERAGE.md` |
|
||||
| **Per-Milestone-Plan** (176 Stück) | `docs/milestones/M???-<slug>/PLAN.md` |
|
||||
| **Live-Progress-Tracker** (du updatest ihn) | `docs/PROGRESS-TRACKER.md` |
|
||||
| **Agent-Regeln + Definition of Done** | `AGENTS.md` (Repo-Root) |
|
||||
| **Integration-Contracts** (Sidebar, Routes, Wiring) | `docs/INTEGRATION-CONTRACTS.md` |
|
||||
| **Mid-Stream-Korrektur-Playbook** | `docs/MID-STREAM-CHANGES.md` |
|
||||
| **Change-Request-Workflow** | `docs/CHANGE-REQUESTS.md` (entsteht in M176) |
|
||||
|
||||
---
|
||||
|
||||
## 2. Wie du ein Milestone planst (Pflicht-Reihenfolge)
|
||||
|
||||
Pro Milestone arbeitest du diese Schritte ab — nicht überspringen:
|
||||
|
||||
1. **Lies `docs/milestones/M???-<slug>/PLAN.md` vollständig.** Sie enthält Ziel, Pflichtenheft-Sektionen, Abhängigkeiten, Out-of-Scope, Erfolgskriterium, Hinweise und am Ende die **Definition of Done**.
|
||||
2. **Lies die referenzierten Pflichtenheft-Sektionen** (`_bmad-output/pflichtenheft/blocks/blockX.md` Sektion Y.Z). Klartext-Hinweise und Edge-Cases stehen dort, nicht in PLAN.md.
|
||||
3. **Lies `AGENTS.md`.** Verbindliche Regeln für Layer-Trennung, drei Anti-Patterns, EU-Stack, Querschnitt-Wiring, Klartext-Pflicht.
|
||||
4. **Lies `docs/INTEGRATION-CONTRACTS.md`.** Hier steht, wo dein Modul in Sidebar / Routes / Tab-Bar / Search-Index andockt.
|
||||
5. **Prüfe Abhängigkeiten:** Sind alle in PLAN.md genannten Vorbedingungs-Milestones abgeschlossen? Wenn nein: STOP und an User melden.
|
||||
6. **Plane Slices** (TC-Standard, 5–8 pro Milestone):
|
||||
- Erste Slice ist meist Datenmodell + Migration
|
||||
- Folge-Slices: Domain-Logik → Loader/Action → View-Model → UI-Component → Sidebar/Routing-Wiring → Tests
|
||||
- Letzte Slice: Smoke-Test + Hot-Swap-Drill
|
||||
7. **Plane Tasks pro Slice** (5 Tasks à 30 Min – 2 Std). Pro Task konkrete Files + Verify-Befehle.
|
||||
8. **Vor Execute:** prüfe gegen die **Definition of Done** in PLAN.md. Sind alle Punkte über die geplanten Slices abgedeckt? Wenn nicht: ergänze Slices.
|
||||
9. **Execute pro Slice atomar.** Pro Slice ein Commit. Forward-Only-DB-Migrations mit Inverse-SQL als Kommentar.
|
||||
10. **Nach jeder Slice: Verify-Gate.** Erst nach grünem Verify zur nächsten.
|
||||
|
||||
---
|
||||
|
||||
## 3. UI-Bauen ohne Subframe (Phase-1-Bootstrap)
|
||||
|
||||
**Wichtig:** Der finale UI-Workflow läuft über Subframe (Designer baut → Subframe-Output → AI-Agent integriert via Adapter). **Aber jetzt** baust du UI mit den **vorhandenen Komponenten der Boilerplate** — sauber, austauschbar, testbar.
|
||||
|
||||
Ziel: Geerkens-tauglich aussehende UI, die später ohne Logik-Bruch durch Subframe-Output ersetzt werden kann.
|
||||
|
||||
### Was du verwenden darfst
|
||||
|
||||
| Layer | Quelle |
|
||||
|---|---|
|
||||
| Primitives | shadcn/ui + Radix-UI (alle `@radix-ui/*`-Pakete sind in der Boilerplate) |
|
||||
| Icons | lucide-react |
|
||||
| Tabellen | bestehende `components/ui/table.*` aus Boilerplate-`packages/ui` |
|
||||
| Forms | react-hook-form + zod (bereits in Deps) |
|
||||
| Charts | recharts oder @tremor/react |
|
||||
| Tipp-Trigger / Suche | kbar |
|
||||
| Editor | TipTap (für Notizen, Marketing-Editor) |
|
||||
| Drag-&-Drop | react-beautiful-dnd / xyflow (für Automation-Editor) |
|
||||
| PDF | @react-pdf/renderer |
|
||||
| Touch-Signatur | signature_pad |
|
||||
| Tailwind 4 | bereits konfiguriert |
|
||||
|
||||
### Was du NICHT machst
|
||||
|
||||
- ❌ KEIN Subframe-MCP-Aufruf für irgendwas in Phase 1.
|
||||
- ❌ KEIN `packages/ui-subframe`-Inhalt füllen — das Verzeichnis bleibt leer (oder mit Dummy-README), bis der Designer kommt.
|
||||
- ❌ KEINE Custom-CSS-Stylesheets pro Komponente — Tailwind-Utility-Klassen.
|
||||
- ❌ KEINE eigenen Component-Libraries erfinden — nur shadcn/Radix-Composites.
|
||||
|
||||
### Wie du UI strukturierst
|
||||
|
||||
Genau gleich wie es später mit Subframe sein wird — **die Layer-Trennung ist jetzt schon Pflicht**, sonst funktioniert der spätere Hot-Swap nicht:
|
||||
|
||||
```
|
||||
app/routes/<modul>/<route>.tsx → Loader baut View-Model, rendert <Page vm={...} actions={{...}} />
|
||||
packages/view-models/src/<modul>/*.vm.ts → Pure Funktion (entity, ctx) → VM, mit Zod-Schema
|
||||
packages/ui-hivegrid/src/pages/<modul>/... → React-Component, baut auf shadcn/Radix mit Tailwind, KEIN Server-Code
|
||||
packages/ui-hivegrid/src/components/... → Wiederverwendbare Composites (Tabellen, Karten, Modale)
|
||||
```
|
||||
|
||||
Components in `packages/ui-hivegrid/src/pages/<modul>/<Component>.tsx` empfangen IMMER:
|
||||
- `vm: <ModulVM>` als Prop (das View-Model)
|
||||
- `actions: { onX: (...) => ... }` als Prop (Callbacks)
|
||||
|
||||
KEINE Hooks für Daten-Fetching innerhalb dieser Components. KEINE direkten Server-Imports.
|
||||
|
||||
### Warum das den späteren Hot-Swap erlaubt
|
||||
|
||||
Wenn der Designer später Subframe-Output liefert, wird der Inhalt von `packages/ui-hivegrid/src/pages/<modul>/<Component>.tsx` durch den Subframe-konformen Adapter ersetzt — die **Schnittstelle** (Props: `vm` + `actions`) bleibt identisch. Routes, View-Models, Domain-Logik werden NICHT angefasst. Der Tausch ist atomar.
|
||||
|
||||
Genau deshalb gilt für die Phase-1-Bootstrap-UI:
|
||||
- Kein direkter `useLoaderData` in Components (auch jetzt nicht!)
|
||||
- Kein direkter Prisma-Import (auch jetzt nicht!)
|
||||
- Alle Texte über i18n (M003)
|
||||
- Alle Aktionen als Callback-Props
|
||||
- View-Model hat Zod-Schema, das später dem Subframe-Adapter den Vertrag erzwingt
|
||||
|
||||
### Visuelles Anspruchsniveau
|
||||
|
||||
„Sauber genug zum Testen", nicht „pixel-perfect Designer-Output". Konkret:
|
||||
- Konsistentes Spacing (Tailwind 4-Standard)
|
||||
- Hell + Dunkel-Modus respektiert (nutze Tailwind `dark:`)
|
||||
- DE-Long-Strings testen (47-Zeichen-Buttons dürfen nicht überlaufen)
|
||||
- Empty-States, Loading, Error mit Klartext (siehe AGENTS.md Punkt E)
|
||||
- Mobile-Viewport-Test (kein Desktop-Only-Layout)
|
||||
|
||||
---
|
||||
|
||||
## 4. Pro Milestone — Pflicht-Deliverables (Definition of Done)
|
||||
|
||||
Aus jeder PLAN.md am Ende. In Stichpunkten:
|
||||
|
||||
**Erreichbarkeit** (siehe INTEGRATION-CONTRACTS.md §1)
|
||||
- Sidebar-Eintrag in `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` mit Permission-Gate
|
||||
- Route registriert
|
||||
- Breadcrumb für Detail-Routes
|
||||
- Mobile-Tab-Bar-Eintrag falls relevant
|
||||
- Customer-Portal-Sichtbarkeit explizit konfiguriert
|
||||
|
||||
**Querschnitt-Wiring**
|
||||
- Audit (auto via M001 oder manuell)
|
||||
- Activity-Stream via `logActivity` (M045)
|
||||
- Notifications via `notify()` (M011)
|
||||
- Search-Index in `indexed-entities.ts`
|
||||
- Permission-Filter via `withTenantScope()` + `withPermission()` (M004)
|
||||
- Feature-Flag-fähig (M006)
|
||||
|
||||
**Code-Layer-Disziplin** (PR-Block bei Verstoß)
|
||||
- Loader baut VM; UI empfängt nur VM + Actions
|
||||
- Keine Prisma-/Server-Imports in `packages/ui-hivegrid/**`
|
||||
- Keine Direktimporte aus `packages/ui-subframe` in `app/routes/**` (ist eh leer in Phase 1)
|
||||
- Alle UI-Texte als i18n-Keys
|
||||
|
||||
**Tests**
|
||||
- Unit-Test für VM-Builder mit Zod-Schema
|
||||
- Smoke-Test in `e2e/smoke/<modul>.spec.ts`
|
||||
- Hot-Swap-Drill grün (Smoke-Test gegen `packages/ui-mock` aus M017)
|
||||
- Visual-Regression-Snapshot (M016)
|
||||
|
||||
**Klartext**
|
||||
- Fehler-Texte aus M002-Catalog
|
||||
- Empty/Loading/Error mit Klartext + nächster Aktion
|
||||
- Permission-Denied → 404 statt 403
|
||||
|
||||
**Rollback-Pfad**
|
||||
- Forward-Only-DB-Migration mit Inverse-SQL als Kommentar
|
||||
- Atomic-Slice-Commits
|
||||
- Feature-Flag vorhanden zum Abschalten ohne Deploy
|
||||
|
||||
**Klick-Pfad zum Prüfen** (steht in PLAN.md unten)
|
||||
- 4-Schritt-Anleitung, wie der User die Funktion findet und testet
|
||||
|
||||
---
|
||||
|
||||
## 5. Drei harte Anti-Patterns (sofortiger PR-Block)
|
||||
|
||||
1. `@prisma/client` oder `~/db` in `packages/ui-hivegrid/**`
|
||||
2. Direktimport aus `packages/ui-subframe` in `app/routes/**` (das Paket ist Phase-1 leer, aber der Import-Pfad bleibt verboten)
|
||||
3. `useLoaderData<typeof loader>()` innerhalb von `packages/ui-hivegrid/**`
|
||||
|
||||
Plus: jede Erweiterung, die der Anti-Liste in `_bmad-output/pflichtenheft/02-vision.md` V.3 widerspricht. Vollständige Liste siehe dort.
|
||||
|
||||
---
|
||||
|
||||
## 6. EU-Stack — nicht verhandelbar
|
||||
|
||||
- KEIN `@ai-sdk/anthropic`, `@ai-sdk/openai`, `openai`
|
||||
- KEIN `remix-auth-google`, KEIN Apple-/Google-/Microsoft-Login (Phase 1)
|
||||
- JA Mistral primär, Scaleway sekundär, AlephAlpha tertiär
|
||||
- JA Email+PW + Magic-Link + TOTP-2FA
|
||||
- Hosting Scaleway (EU), DB in EU, Storage Scaleway-S3 (EU)
|
||||
|
||||
Wenn etwas im Boilerplate-Code noch US-Provider referenziert: STOP und an User melden — die Boilerplate sollte EU-sterilisiert sein.
|
||||
|
||||
---
|
||||
|
||||
## 7. Wenn du nicht weiterkommst
|
||||
|
||||
| Situation | Vorgehen |
|
||||
|---|---|
|
||||
| Pflichtenheft-Sektion ist mehrdeutig | STOP. Frage formulieren, an User. Kein Auto-Refactor. |
|
||||
| Abhängigkeits-Milestone fehlt | STOP. An User: „M??? braucht M??? — wann fertig?" |
|
||||
| Boilerplate hat Bug, der dich blockiert | STOP. Bug an User mit konkretem Pfad + Repro. |
|
||||
| Anti-Listen-Punkt in PLAN.md gewünscht | STOP. Change-Request via `docs/CHANGE-REQUESTS.md` (M176). |
|
||||
| Layer-Trennung lässt sich nicht einhalten | STOP. Architektur-Frage, nicht selber lösen. |
|
||||
|
||||
---
|
||||
|
||||
## 8. Erste konkrete Aufgabe
|
||||
|
||||
Beginne mit **M001 (Audit-Log default)**. Lies:
|
||||
|
||||
1. `docs/milestones/M001-audit-log-default/PLAN.md`
|
||||
2. `_bmad-output/pflichtenheft/03-architektur.md` Sektion A.6
|
||||
3. `AGENTS.md`
|
||||
4. `docs/INTEGRATION-CONTRACTS.md` (§5 Audit-Wiring, §6 — der Audit-Eintrag selbst gehört zu diesem Milestone)
|
||||
|
||||
Plane M001 in Slices, präsentiere den Plan, warte auf User-Bestätigung, dann Execute.
|
||||
|
||||
Nach M001 → M002 → ... in der Reihenfolge der Master-Liste, ABER: prüfe in jeder PLAN.md die Abhängigkeiten — manche Milestones lassen sich parallelisieren (siehe `Wird benötigt von`-Felder).
|
||||
|
||||
---
|
||||
|
||||
## 9. Was du dem User nach jedem Milestone meldest
|
||||
|
||||
Kurzer Statusbericht in dieser Form:
|
||||
|
||||
```
|
||||
Milestone: M??? — <Titel>
|
||||
Status: READY-TO-VERIFY | BLOCKED | NEEDS-USER-INPUT
|
||||
Slices: X von Y abgeschlossen
|
||||
Tests: Smoke ✓ / Hot-Swap-Drill ✓ / Visual-Regression: <Anzahl Diffs zu prüfen>
|
||||
DoD-Score: N/14 erfüllt
|
||||
Sidebar-Eintrag: <Gruppe> > <Eintrag>
|
||||
Klick-Pfad zum Prüfen: <wie aus PLAN.md>
|
||||
PROGRESS-TRACKER aktualisiert: ✓
|
||||
Offene Punkte (falls relevant): <Liste>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Progress-Tracker-Pflicht (`docs/PROGRESS-TRACKER.md`)
|
||||
|
||||
Diese Datei ist Live-Übersicht für den User. Du updatest sie **nach jedem Status-Wechsel**:
|
||||
|
||||
### Bei Milestone-Start
|
||||
1. Status in der Master-Tabelle: `⚪ NICHT-GESTARTET` → `🔵 IN-ARBEIT`
|
||||
2. Detail-Sektion gemäß Vorlage (Abschnitt „Vorlage" in der Tracker-Datei) anlegen — kopiere den Block, fülle Pflichtenheft-Bezug, leere Slice-Liste, leere DoD-Checkboxen ein
|
||||
3. Klick-Pfad-Block aus PLAN.md übernehmen, mit konkreten User-Typ + Sidebar-Pfad ausfüllen
|
||||
|
||||
### Bei Slice-Abschluss
|
||||
4. In der Detail-Sektion die Slice abhaken mit Commit-Hash
|
||||
5. DoD-Checkboxen abhaken, sobald die jeweilige Pflicht erfüllt ist
|
||||
6. DoD-Score in der Master-Tabelle aktualisieren (z.B. `8/14`)
|
||||
|
||||
### Bei Milestone-Abschluss (alle DoD-Punkte erfüllt + Tests grün)
|
||||
7. Status in Master-Tabelle: `🔵 IN-ARBEIT` → `🟡 READY-TO-VERIFY`
|
||||
8. „Notes vom Agent"-Block in Detail-Sektion ausfüllen (was war nicht offensichtlich, was muss User wissen)
|
||||
9. STOP. Warte auf User-Sign-Off. Starte KEIN nächstes Milestone.
|
||||
|
||||
### Nach User-Sign-Off
|
||||
10. User trägt selbst `🟢 SIGNED-OFF` + Datum in die Detail-Sektion ein
|
||||
11. Du übernimmst diesen Status in die Master-Tabelle und beginnst das nächste Milestone
|
||||
|
||||
### Konsistenz-Pflicht
|
||||
- DoD-Score in Master-Tabelle muss zur Detail-Sektion passen
|
||||
- `🟡 READY-TO-VERIFY` ohne 14/14 DoD = Inkonsistenz → korrigiere sofort
|
||||
- Mehr als 5 Milestones in `🔵 IN-ARBEIT` parallel → STOP, Fokus-Verlust → an User melden
|
||||
@@ -0,0 +1,45 @@
|
||||
# UAT — kanonische Journey-Landkarte
|
||||
|
||||
Diese Datei ist die kurze, stabile Übersicht der fachlichen End-to-End-Abnahme. Die konkrete
|
||||
Definition of Done und die atomaren Akzeptanzfälle stehen in
|
||||
`.planning/ticket-docs/<ID>.md`; automatisierbare Flows liegen unter `e2e/` und `e2e/smoke/`.
|
||||
Status und Abhängigkeiten werden ausschließlich in Plane gepflegt.
|
||||
|
||||
## Abnahme-Regeln
|
||||
|
||||
- Lokal nur mit synthetischen, wegwerfbaren Daten arbeiten.
|
||||
- Staging-/Live-Aktionen nur nach dem Ablauf in [staging-live-uat.md](staging-live-uat.md);
|
||||
Browser- und Provider-Prüfungen bleiben manuell, sofern sie nicht ausdrücklich freigegeben sind.
|
||||
- Evidenz enthält nur Status, Ziel, Revision, Request-/Job-ID und redigierte Diagnostik; niemals
|
||||
Secrets, Tokens, Cookies, Kundendaten, Tenant-IDs, Payloads oder unredigierte Logs.
|
||||
- Ein Ticket ist erst bei 100 % seiner eigenen DoD abgeschlossen. Diese Übersicht erzeugt keine
|
||||
zusätzliche oder konkurrierende DoD.
|
||||
|
||||
## Golden Journeys
|
||||
|
||||
1. Ein neuer Mandant wird vollständig arbeitsfähig.
|
||||
2. Ein Lead wird zu einem Projekt.
|
||||
3. Ein Projekt läuft durch Vertrieb, Auftrag und Abnahme.
|
||||
4. Ein mobiler Techniker erledigt seinen Arbeitstag.
|
||||
5. Eine öffentliche Buchung wird zum Termin.
|
||||
6. Ein Formular erzeugt korrekt nachgelagerte Arbeit.
|
||||
7. Kommunikation erreicht den richtigen Kunden und das richtige Projekt.
|
||||
8. Eine Kampagne läuft DSGVO-konform.
|
||||
9. Eine Automation verarbeitet ein Ereignis nachvollziehbar und rückgängig machbar.
|
||||
10. Ein Mitarbeiter durchläuft den HR-Lebenszyklus.
|
||||
11. Self-Service-Abonnementänderungen ändern die Zugriffsrechte korrekt.
|
||||
12. DSGVO-Self-Service erreicht zuverlässig den Worker-Endzustand.
|
||||
13. Ein Plattform-Admin löst ein Mandantenproblem.
|
||||
14. Ein eingeschränkter API-Client sieht und ändert nur erlaubte Daten.
|
||||
15. Ein externer KI-Client nutzt HiveGrid über die Remote-MCP-Schnittstelle.
|
||||
16. Eine Website-Anfrage wird zum Plattform-Lead.
|
||||
17. Ein Kunde erledigt einen freigegebenen Portal-Workflow.
|
||||
|
||||
## Quellen für die Durchführung
|
||||
|
||||
- Ticket-Scope und DoD: `.planning/ticket-docs/<ID>.md`
|
||||
- Architektur- und Integrationsregeln: `AGENTS.md`,
|
||||
[ARCHITECTURE-DECISIONS.md](ARCHITECTURE-DECISIONS.md) und
|
||||
[INTEGRATION-CONTRACTS.md](INTEGRATION-CONTRACTS.md)
|
||||
- Staging-/Live-Evidenz: [staging-live-uat.md](staging-live-uat.md)
|
||||
- Release, Health und Rollback: [deployment.md](deployment.md)
|
||||
@@ -1,43 +0,0 @@
|
||||
# Agent Entrypoints
|
||||
|
||||
Use this file as a technical helper index when a coding agent plans or implements feature work in HiveGrid. For ticket work, `AGENTS.md` and `.planning/ticket-docs/README.md` are the primary entrypoints.
|
||||
|
||||
## Start Here
|
||||
|
||||
- Ticket-driven HiveGrid work: read `AGENTS.md`, then `.planning/ticket-docs/README.md`, then the specific `.planning/ticket-docs/<ID>.md`.
|
||||
- New or migrated feature: read `docs/agent-playbooks/feature-integration.md` and update the matching manifest before implementation.
|
||||
- Existing MVP import: read `docs/agent-playbooks/mvp-intake.md` before proposing code changes.
|
||||
- Admin-managed tenant feature: read `docs/agent-playbooks/admin-managed-features.md`.
|
||||
- Foundation, billing usage, notifications, flags, permissions, audit, or idempotency changes: read `docs/agent-playbooks/foundation-boundaries.md`.
|
||||
- Worker-backed or browser-backed feature: read `docs/agent-playbooks/worker-backed-features.md`, `docs/ops/worker-queues.md`, and `packages/queue/src/payloads.ts`.
|
||||
- Plugin, WASM, lifecycle, or hook work: read `docs/features/plugins.md`, `docs/operations/plugin-lifecycle.md`, and `docs/security/plugin-runtime-signoff.md`.
|
||||
- UI surface or component changes: start with `docs/ui-inventory/surface-map.md`, then read `docs/agent-playbooks/ui-changes.md`, `docs/ui-inventory/`, and `apps/web/app/application/ui/uiRegistry.ts`.
|
||||
- Navigation, sidebar, or route-helper changes: read `docs/navigation-architecture.md`.
|
||||
- UI adapter or hotswap work: read `docs/agent-playbooks/ui-adapter-migration.md` and `packages/ui/README.md`.
|
||||
- Feature ownership, dependencies, configuration, provider, worker and UAT contracts: read `docs/feature-manifests/`.
|
||||
- New manifest scaffold: run `pnpm run manifest:new -- --id my-feature --title "My Feature" --classification plugin-candidate --ownership hybrid`, then replace placeholders before coding.
|
||||
- Architecture Closure closure/status contract: start from the aligned sources `docs/archive/architecture-handoff-summary.md`, `docs/architecture-migration-status.md`, `docs/feature-inventory.md`, and `docs/feature-manifests/*.json`; read them together before planning implementation, extraction, or removal work.
|
||||
|
||||
## Agent Rule
|
||||
|
||||
Do not jump from a user request directly into implementation when the request imports an existing product, adds a proprietary feature, adds provider credentials, changes admin-managed behavior, or introduces workers.
|
||||
|
||||
For those requests, produce or update a feature manifest first. The manifest is the contract the implementation must satisfy.
|
||||
|
||||
## Expected Planning Output
|
||||
|
||||
For a substantial feature, the planning output should identify:
|
||||
|
||||
- Existing user flows and target boilerplate flows.
|
||||
- Feature ownership: `tenant-owned`, `admin-managed`, `hybrid`, or `system-only`.
|
||||
- Admin, tenant, public and API surfaces.
|
||||
- Runtime route ownership and helper choice: admin host paths use `adminPath`, tenant app paths use `appPath` or `UrlUtils.getModulePath(...)`, and API host paths use `apiPath`/`/v1`.
|
||||
- Tenant-scope and negative access checks for every loader/action/API mutation that touches tenant data.
|
||||
- i18n surfaces, including new locale keys and `pnpm run verify:i18n` when UI text changes.
|
||||
- Deploy/static gates affected by the change, especially `pnpm run verify:deploy-workflow`, Docker baseline/static checks, and production seed artifact checks for deploy work. Run live Docker smokes only when the task explicitly requires them.
|
||||
- Database models and migrations.
|
||||
- Provider credentials and secret ownership.
|
||||
- Worker queues and jobs.
|
||||
- Permissions and audit events.
|
||||
- Billing or usage-metering impact.
|
||||
- UAT checks the operator can run.
|
||||
+3
-3
@@ -13,11 +13,11 @@ An admin-managed feature is configured by admin/platform operators and consumed
|
||||
- Tenant feature enabled only for selected plans or accounts.
|
||||
- Browser automation where admin controls allowed domains and runtime policy.
|
||||
|
||||
## Required Manifest Entries
|
||||
## Required ticket contract
|
||||
|
||||
The feature manifest must declare:
|
||||
The owning ticket doc must declare:
|
||||
|
||||
- `integration.ownership = "admin-managed"` or `"hybrid"`.
|
||||
- Admin-managed or hybrid ownership.
|
||||
- Admin routes that manage provider/policy.
|
||||
- Tenant routes that consume the feature.
|
||||
- Secrets and who owns them.
|
||||
|
||||
@@ -1,68 +0,0 @@
|
||||
# Feature Integration Playbook
|
||||
|
||||
Use this playbook when adding a feature to the boilerplate or adapting a proprietary feature from another product.
|
||||
|
||||
## Goal
|
||||
|
||||
Make the feature understandable before implementation. A human operator and a coding agent should be able to answer where the feature lives, who owns its configuration, which flows it exposes, and how to verify it.
|
||||
|
||||
## Required Steps
|
||||
|
||||
1. Read `docs/agent-entrypoints.md`.
|
||||
2. Find or create a manifest in `docs/feature-manifests/`.
|
||||
3. Classify ownership:
|
||||
- `tenant-owned`: tenant configures and uses it.
|
||||
- `admin-managed`: admin/platform configures it; tenant only uses approved surfaces.
|
||||
- `hybrid`: admin defines policy/defaults; tenant can configure local behavior.
|
||||
- `system-only`: internal platform feature with no tenant-owned controls.
|
||||
4. Map surfaces:
|
||||
- Admin route source files and canonical admin-host runtime paths.
|
||||
- Tenant route source files and canonical tenant-host runtime paths.
|
||||
- Public route source files and root/web-host runtime paths.
|
||||
- API route source files and canonical API-host `/v1/...` runtime paths.
|
||||
- Link/form/action helpers: `adminPath`, `appPath`, `apiPath`, cross-host helpers, or `UrlUtils.getModulePath(...)` for tenant modules.
|
||||
5. Map persistence:
|
||||
- Prisma models.
|
||||
- Existing tables reused.
|
||||
- Migrations required.
|
||||
- Tenant scoping fields.
|
||||
6. Map configuration:
|
||||
- Admin settings.
|
||||
- Tenant settings.
|
||||
- Environment variables.
|
||||
- Secrets and their owner.
|
||||
7. Map runtime:
|
||||
- Request/response only.
|
||||
- Queue-backed.
|
||||
- Worker-backed.
|
||||
- Browser-backed.
|
||||
8. Map controls:
|
||||
- Permissions.
|
||||
- Audit events.
|
||||
- Billing or usage limits.
|
||||
9. Define UAT:
|
||||
- Operator-visible checks.
|
||||
- Negative checks for forbidden access.
|
||||
- Secret exposure checks if providers are involved.
|
||||
|
||||
## Implementation Rules
|
||||
|
||||
- Do not expose provider secrets through tenant loaders, API responses, client bundles or logs.
|
||||
- Do not add sidebar/nav entries without stable UI IDs.
|
||||
- Do not add new root UI primitives without updating `docs/ui-inventory/components.json`.
|
||||
- Do not add worker behavior without declaring queues and jobs in the manifest.
|
||||
- Do not add admin-managed tenant behavior without admin permissions and audit events.
|
||||
- Keep proprietary feature logic behind explicit module boundaries.
|
||||
- Do not hard-code legacy runtime paths such as `/admin/...`, `/app/...`, or `/api/v1/...` outside tests that explicitly cover legacy redirects.
|
||||
- Do not ship visible UI text without locale keys and `pnpm run verify:i18n`.
|
||||
|
||||
## Done Criteria
|
||||
|
||||
- Manifest updated and valid.
|
||||
- Routes and surfaces match the manifest.
|
||||
- Permissions are enforced on admin/API/tenant surfaces.
|
||||
- Tenant-scope negative tests cover forbidden reads and mutations.
|
||||
- Route helpers and runtime host ownership are tested for new navigation.
|
||||
- i18n and deploy/static verifiers relevant to the change have run.
|
||||
- Required worker queues/jobs exist or are explicitly deferred.
|
||||
- UAT checks pass or are marked as deferred with a reason.
|
||||
+4
-2
@@ -1,6 +1,7 @@
|
||||
# Foundation Boundary Playbook
|
||||
|
||||
Use this when moving feature logic into the reusable boilerplate layer or when touching audit, idempotency, flags, permissions, billing usage, or notifications.
|
||||
Use this when moving feature logic into HiveGrid's shared foundation or when touching audit,
|
||||
idempotency, flags, permissions, billing usage, or notifications.
|
||||
|
||||
## Ownership Rules
|
||||
|
||||
@@ -20,5 +21,6 @@ Use this when moving feature logic into the reusable boilerplate layer or when t
|
||||
## Done Criteria
|
||||
|
||||
- Add or update focused tests in the owning package.
|
||||
- Update feature manifests when a feature changes ownership, billing, provider, worker, or admin-managed behavior.
|
||||
- Update the owning ticket doc and architecture decision when ownership, billing, provider, worker,
|
||||
or admin-managed behavior changes.
|
||||
- Run `pnpm run test:foundation`, the affected package tests, and the app-level route tests for changed runtimes.
|
||||
@@ -1,62 +0,0 @@
|
||||
# MVP Intake Playbook
|
||||
|
||||
Use this before adapting an existing MVP onto this boilerplate.
|
||||
|
||||
## Purpose
|
||||
|
||||
Prevent agents from copying product code blindly. The MVP must first be decomposed into flows, roles, data, providers, ownership and runtime behavior.
|
||||
|
||||
## Intake Checklist
|
||||
|
||||
Capture the following before implementation:
|
||||
|
||||
- Product summary: what the MVP does in one paragraph.
|
||||
- Primary user roles.
|
||||
- Admin/operator roles.
|
||||
- Tenant roles.
|
||||
- Critical user flows.
|
||||
- Data objects and ownership.
|
||||
- External providers.
|
||||
- Secrets and credentials.
|
||||
- Background jobs.
|
||||
- Browser automation or long-running work.
|
||||
- Billing or usage limits.
|
||||
- Existing UI surfaces.
|
||||
- Must-keep behavior.
|
||||
- Behavior that should become plugin-only.
|
||||
- Behavior that should be removed.
|
||||
|
||||
## Flow Mapping
|
||||
|
||||
For every flow, record:
|
||||
|
||||
- Entry point.
|
||||
- Actor.
|
||||
- Preconditions.
|
||||
- Data read.
|
||||
- Data written.
|
||||
- Provider calls.
|
||||
- Sync versus async behavior.
|
||||
- Success state.
|
||||
- Failure state.
|
||||
- UAT check.
|
||||
|
||||
## Boilerplate Mapping
|
||||
|
||||
Map each flow into:
|
||||
|
||||
- `apps/web/app/routes/admin*` for admin/platform management files; runtime links must use `adminPath` or admin-host helpers.
|
||||
- `apps/web/app/routes/app.$tenant*` for tenant-facing usage files; runtime links must use `appPath`, `UrlUtils.getModulePath(...)`, or an equivalent host-aware wrapper.
|
||||
- `apps/api/src/app.ts` under `/v1` for canonical public/service APIs and webhooks. If a `/v1` route temporarily proxies a web `internal/api` handler, record `apps/api` as the external route owner and the web handler as the temporary implementation owner until extraction lands.
|
||||
- `apps/web/app/modules/<feature>` for feature-owned application logic.
|
||||
- `apps/worker` and `packages/queue` for async jobs.
|
||||
- `docs/feature-manifests/<feature>.json` for the integration contract.
|
||||
|
||||
## Output Required From Agent
|
||||
|
||||
Before coding, the agent should produce:
|
||||
|
||||
- A short MVP decomposition.
|
||||
- A feature manifest draft or update.
|
||||
- A list of unknowns that block safe implementation.
|
||||
- An implementation plan tied to the manifest.
|
||||
+5
-4
@@ -12,11 +12,11 @@ Use this when a feature performs slow, retryable, external, scheduled, browser-b
|
||||
- Work should continue after a user navigates away.
|
||||
- Usage metering or cleanup must be reliable.
|
||||
|
||||
## Required Manifest Entries
|
||||
## Required ticket contract
|
||||
|
||||
The feature manifest must declare:
|
||||
The owning ticket doc must declare:
|
||||
|
||||
- `integration.workers.required`.
|
||||
- Whether a worker is required.
|
||||
- Queue names from `packages/queue/src/names.ts`.
|
||||
- Job names from `packages/queue/src/payloads.ts`.
|
||||
- Notes about retries, idempotency and cleanup.
|
||||
@@ -31,7 +31,8 @@ The feature manifest must declare:
|
||||
- Jobs should be idempotent or have explicit duplicate protection.
|
||||
- Browser jobs must enforce admin-owned navigation policy.
|
||||
- Failures should be visible to the initiating user or admin.
|
||||
- AI/browser-backed features use `hivegrid.ai-chatbot` and `hivegrid.browser-automation` unless a manifest explicitly justifies a new queue.
|
||||
- Browser-backed features use the existing queue contracts unless the ticket explicitly approves a
|
||||
new queue.
|
||||
|
||||
## Browser-Backed Work
|
||||
|
||||
|
||||
@@ -17,11 +17,11 @@ The API server listens on `API_PORT` when set, falls back to `PORT`, and otherwi
|
||||
| `GET` | `/v1/session/current-user`, `/v1/accounts`, `/v1/accounts/:id` | Service token | Service principal and account metadata. |
|
||||
| `GET` | `/v1/usage` | Tenant API key | Usage metadata for the credential-scoped tenant. |
|
||||
| `POST` | `/v1/api-keys/validate` | Optional presented API key or service token | Redacted API-key/service-token validation helper. |
|
||||
| `POST` | `/v1/ai/upload` | Service token | AI upload through configured service storage. |
|
||||
| `POST` | `/v1/maintenance/export-retention/enqueue` | Service token | Operator maintenance enqueue action. |
|
||||
| `POST` | `/v1/support/inbound-email` | Webhook signature | Signed inbound support email ingress that creates tenant support tickets. |
|
||||
| `GET` | `/v1/analytics/public`, `/v1/analytics/admin` | Analytics token or service token | Analytics read surfaces. |
|
||||
| `POST` | `/v1/analytics/events`, `/v1/analytics/page-views` | Analytics token | Public analytics ingress. |
|
||||
| `GET` | `/v1/analytics/public` | Public-setting gate | Tenantless global aggregates; unavailable unless `AnalyticsSettings.public` is enabled. |
|
||||
| `GET` | `/v1/analytics/admin` | Service token plus verified operator user | Global tenantless aggregates or an exact `tenantId` + `portalId` scope. |
|
||||
| `POST` | `/v1/analytics/events`, `/v1/analytics/page-views` | Analytics ingest token | Anonymous tenantless analytics ingress; user and portal identity fields are rejected. |
|
||||
| `GET` | `/v1/notifications/stream` | Service token | Notification diagnostics stream. |
|
||||
| `GET` | `/v1/entities/:entity` | Service token | Entity metadata lookup. |
|
||||
| `GET/POST/PATCH/DELETE` | `/v1/entities/:entity/rows*` | Service token or tenant API key | Tenant-scoped entity row operations. |
|
||||
@@ -38,6 +38,8 @@ Tenant-scoped row, relationship, and export requests resolve tenant scope from t
|
||||
|
||||
Set `API_ACCESS_TOKEN` in the API runtime environment to enable the service-token endpoints. Authenticated calls use `Authorization: Bearer <service-token>`; key validation may also read the candidate key from the `x-api-key` header or from the JSON `apiKey` request body when using `POST /v1/api-keys/validate`.
|
||||
|
||||
`ANALYTICS_TOKEN` is browser-readable by design and is therefore only a bounded ingest capability, not a read credential. It permits anonymous event/page-view submissions after rate limiting. Public aggregate reads rely solely on the operator-controlled public setting, while admin aggregate reads require the service credential and an `x-hivegrid-operator-user-id` that resolves to an RLS-visible `AdminUser` row.
|
||||
|
||||
Authentication failures return JSON error envelopes without echoing token values, API keys, bearer fragments, headers, request bodies, tenant identifiers, customer identifiers, or environment values. Support notes should record only the generic endpoint, response status, stable error code, and request ID. Never paste real authorization headers, raw API key inputs, or token-shaped values into tickets, chat, logs, screenshots, or documentation examples.
|
||||
|
||||
## OpenAPI contract
|
||||
@@ -108,7 +110,7 @@ for marker in ('TO' + 'DO', 'T' + 'BD', 'FIX' + 'ME'):
|
||||
PY
|
||||
pnpm exec eslint apps/api/src/app.ts apps/api/src/cors.ts --max-warnings=0
|
||||
pnpm exec vitest run apps/api/src/app.test.ts apps/api/src/cors.test.ts
|
||||
pnpm run verify:production-docs
|
||||
pnpm run verify:docs-links
|
||||
```
|
||||
|
||||
Browser automation, Playwright, Cypress, live Docker, live registry, and E2E execution are manual-only unless a human explicitly approves the exact focused run in the current session.
|
||||
|
||||
@@ -0,0 +1,210 @@
|
||||
# Public Lead Intake — eingehender Webhook
|
||||
|
||||
Öffentlicher Endpunkt, über den externe Systeme (Website-Kontaktformular,
|
||||
Landingpage, Zapier/Make, Partner-CRM …) einen **Lead** direkt in einen
|
||||
HiveGrid-Tenant einliefern. Aus dem eingelieferten JSON wird ein `InboxLead`
|
||||
im Ziel-Tenant erzeugt, gegen bestehende Kontakte gematcht und optional als
|
||||
`webhook.received`-Trigger für Automationen ausgewertet.
|
||||
|
||||
- **Route:** `POST /v1/webhooks/incoming/:tenant/:slug`
|
||||
- **Implementierung:** Route `apps/api/src/routes/public-api-routes.ts`
|
||||
(`postPublicIncomingWebhookRequest`) → Service
|
||||
`ingestPublicLeadWebhook` in `packages/db/src/public-api.server.ts`
|
||||
- **Content-Type:** `application/json` (Body muss ein JSON-**Objekt** sein,
|
||||
kein Array/Skalar)
|
||||
|
||||
## Adressierung: `:tenant` und `:slug`
|
||||
|
||||
- `:tenant` — Tenant-**ID** oder Tenant-**Slug** (beides wird aufgelöst).
|
||||
- `:slug` — Slug des Webhook-Endpunkts (`PublicIncomingWebhookEndpoint`),
|
||||
pro Tenant eindeutig. Der Endpunkt muss `status = "active"` sein.
|
||||
|
||||
Unbekannter Tenant, unbekannter Slug **oder** inaktiver Endpunkt liefern
|
||||
einheitlich `404 not_found` — bewusst ohne Unterscheidung, damit von außen
|
||||
nicht erkennbar ist, ob Tenant oder Slug falsch war (keine Enumeration).
|
||||
|
||||
## Authentifizierung — drei Modi
|
||||
|
||||
Der Auth-Modus ist **pro Endpunkt** konfiguriert (`authMode`). Es gilt genau
|
||||
der Modus des adressierten Endpunkts; ein anderer Modus wird nicht akzeptiert.
|
||||
|
||||
### 1. `api_key`
|
||||
|
||||
- Header **`x-api-key: <api-key>`** (alternativ Feld `apiKey` im JSON-Body).
|
||||
- Der Schlüssel muss zum **selben Tenant** gehören wie der Endpunkt; ist am
|
||||
Endpunkt ein `apiKeyId` hinterlegt, muss es **genau dieser** Schlüssel sein.
|
||||
- Der Schlüssel muss `active` und nicht abgelaufen sein und den Scope
|
||||
**`public_api:webhooks:incoming`** (oder `*`) besitzen. Fehlt der Scope →
|
||||
`403 insufficient_scope`.
|
||||
|
||||
### 2. `url_token`
|
||||
|
||||
- Header **`X-HiveGrid-Webhook-Token: <token>`** — alternativ Query-Parameter
|
||||
**`?token=<token>`** (praktisch für Formular-Tools, die keine Custom-Header
|
||||
senden können).
|
||||
- Das Token wird gegen den gespeicherten `tokenHash` geprüft (der Klartext
|
||||
wird nie gespeichert und ist nur einmal bei der Erstellung sichtbar).
|
||||
|
||||
### 3. `hmac`
|
||||
|
||||
- Header **`X-HiveGrid-Webhook-Token: <secret>`** (das einmalig ausgegebene
|
||||
Secret), **`X-HiveGrid-Timestamp: <unix-seconds>`** und
|
||||
**`X-HiveGrid-Signature: sha256=<hex>`**.
|
||||
- Signatur = `HMAC-SHA256(secret, "<timestamp>.<raw-body>")`, hex-kodiert, mit
|
||||
Präfix `sha256=`. Signiert wird der **rohe** Request-Body (Byte-für-Byte),
|
||||
nicht das neu serialisierte JSON.
|
||||
|
||||
Ungültige Credentials in jedem Modus → `401 unauthorized` (ohne Detail,
|
||||
welcher Teil falsch war).
|
||||
|
||||
## Rate-Limit
|
||||
|
||||
Fixed-Window-Limiter (Fenster: **1 Stunde**), zwei Ebenen gleichzeitig:
|
||||
|
||||
| Ebene | Limit / Stunde | Zähl-Schlüssel |
|
||||
|---|---|---|
|
||||
| pro Schlüssel/Endpunkt | **1.000** | API-Key-ID (`api_key`) bzw. Endpunkt-ID (`url_token`/`hmac`) |
|
||||
| pro Tenant | **10.000** | Tenant-ID |
|
||||
|
||||
Bei **jeder** Antwort (Erfolg wie Ablehnung) werden Rate-Limit-Header gesetzt:
|
||||
|
||||
| Header | Bedeutung |
|
||||
|---|---|
|
||||
| `X-RateLimit-Limit` | geltendes Limit (bei kombinierter Sicht `1000`) |
|
||||
| `X-RateLimit-Remaining` | verbleibende Anfragen im Fenster (Minimum beider Ebenen) |
|
||||
| `X-RateLimit-Reset` | Unix-Zeit (Sekunden), wann das Fenster zurücksetzt |
|
||||
| `X-RateLimit-Scope` | `key`, `tenant` oder `combined` (welche Ebene griff) |
|
||||
|
||||
Bei Überschreitung → `429 rate_limit_exceeded`, zusätzlich `Retry-After`
|
||||
(Sekunden bis Reset).
|
||||
|
||||
## Feld-Mapping (`payloadMapping`)
|
||||
|
||||
Aus dem JSON-Body werden fünf strukturierte Lead-Felder extrahiert. Für jedes
|
||||
Feld gibt es Standard-Pfade; über `payloadMapping` (JSON am Endpunkt) lässt
|
||||
sich pro Feld ein abweichender **Dot-Pfad** in den Payload setzen.
|
||||
|
||||
| Lead-Feld | Standard-Pfade (in Reihenfolge) |
|
||||
|---|---|
|
||||
| `vorname` | `vorname`, `firstName`, `first_name`, `contact.firstName` |
|
||||
| `nachname` | `nachname`, `lastName`, `last_name`, `contact.lastName` |
|
||||
| `email` | `email`, `contact.email`, `from.email` (wird auf lowercase normalisiert) |
|
||||
| `telefon` | `telefon`, `phone`, `telephone`, `contact.phone` |
|
||||
| `message` | `message`, `nachricht`, `text`, `body` |
|
||||
|
||||
- `payloadMapping`-Beispiel: `{ "email": "customer.mail", "message": "form.comment" }`
|
||||
liest `email` aus `customer.mail` und `message` aus `form.comment`; für nicht
|
||||
gemappte Felder greifen weiter die Standard-Pfade.
|
||||
- Werte werden getrimmt und auf **2.000 Zeichen** gekürzt.
|
||||
- Der **komplette** eingelieferte Payload wird zusätzlich unverändert in
|
||||
`rohdaten` gespeichert — Felder wie **Firma**, **Quelle/Kampagne** oder
|
||||
eigene **Metadaten** gehen also nicht verloren, werden aber (Stand heute)
|
||||
nicht in eigene Lead-Spalten gemappt (siehe „Bekannte Grenzen").
|
||||
|
||||
### Kontakt-Matching
|
||||
|
||||
Nach der Extraktion wird versucht, den Lead einem bestehenden Kontakt
|
||||
zuzuordnen: zuerst per **E-Mail** (`KontaktEmail`), sonst per **Telefon**
|
||||
(`KontaktTelefon`), jeweils tenant-scoped. Treffer landet als
|
||||
`matchedKontaktId` am Lead und in der Antwort.
|
||||
|
||||
## Beispiel — Demo-Endpunkt
|
||||
|
||||
Demo-Tenant `hivegrid-demo`, Endpunkt-Slug `website-kontaktformular`
|
||||
(`authMode: "api_key"`, verknüpft mit dem API-Key-Alias „Website Lead Intake").
|
||||
Den echten Schlüssel im Tenant-Dashboard erzeugen/ablesen; unten steht ein
|
||||
Platzhalter, **kein echtes Secret**.
|
||||
|
||||
```bash
|
||||
curl -sS -X POST \
|
||||
"https://api.hivegrid.de/v1/webhooks/incoming/hivegrid-demo/website-kontaktformular" \
|
||||
-H "content-type: application/json" \
|
||||
-H "x-api-key: $HIVEGRID_API_KEY" \
|
||||
-d '{
|
||||
"firstName": "Ada",
|
||||
"lastName": "Lovelace",
|
||||
"company": "Analytical Engines GmbH",
|
||||
"email": "ada@example.test",
|
||||
"phone": "+49 30 1234567",
|
||||
"message": "Bitte um ein Angebot für eine 12-kWp-Anlage.",
|
||||
"source": "website",
|
||||
"campaign": "sommer-2026",
|
||||
"meta": { "utm_medium": "cpc", "formId": "kontakt-hero" }
|
||||
}'
|
||||
```
|
||||
|
||||
- Bei `authMode: "url_token"` stattdessen `-H "x-hivegrid-webhook-token: $TOKEN"`
|
||||
(oder `?token=$TOKEN` an die URL).
|
||||
- Der API-Key muss den Scope `public_api:webhooks:incoming` besitzen (der
|
||||
reine Lese-/Schreib-Scope reicht **nicht**).
|
||||
|
||||
### Erfolgs-Antwort (`201`)
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"leadId": "clx…",
|
||||
"matchedKontaktId": null,
|
||||
"automationExecutionIds": []
|
||||
},
|
||||
"meta": {
|
||||
"requestId": "req_…",
|
||||
"endpoint": "website-kontaktformular"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Aus dem Beispiel-Payload werden `vorname=Ada`, `nachname=Lovelace`,
|
||||
`email=ada@example.test`, `telefon=+49 30 1234567`, `message=…` gesetzt;
|
||||
`company`, `source`, `campaign`, `meta` bleiben in `rohdaten` erhalten.
|
||||
|
||||
## Fehlerverhalten
|
||||
|
||||
Alle Fehler nutzen die Standard-Hülle
|
||||
`{ "error": { "code", "message", "requestId" } }` (Details bewusst knapp,
|
||||
keine Stacktraces, keine Secrets, keine internen IDs im Klartext).
|
||||
|
||||
| Status | `code` | Auslöser |
|
||||
|---|---|---|
|
||||
| `404` | `not_found` | Tenant/Slug unbekannt oder Endpunkt inaktiv |
|
||||
| `400` | `invalid_json` | Body ist kein JSON-Objekt / nicht parsebar |
|
||||
| `401` | `unauthorized` | fehlendes/ungültiges Token, HMAC oder API-Key |
|
||||
| `403` | `insufficient_scope` | API-Key ohne `public_api:webhooks:incoming` |
|
||||
| `402` | `payment_required` | Tenant read-only (Billing) oder API-Zugang aus/aufgebraucht |
|
||||
| `429` | `rate_limit_exceeded` | Rate-Limit überschritten (mit `Retry-After`) |
|
||||
| `500` | `webhook_ingestion_failed` | interner Fehler beim Anlegen |
|
||||
|
||||
## Was serverseitig passiert
|
||||
|
||||
1. Tenant + Endpunkt auflösen, Endpunkt-Status prüfen.
|
||||
2. Body als JSON-Objekt parsen.
|
||||
3. Billing-/Usage-Gate (`402` bei read-only oder deaktiviertem API-Zugang).
|
||||
4. Auth gemäß `authMode` + Rate-Limit.
|
||||
5. In **einer** Transaktion: Kontakt-Matching, `InboxLead` anlegen,
|
||||
**Audit-Event** für die Lead-Erstellung über die transaktionale Outbox
|
||||
(`audit.event.create`, Action `lead.created`, Target `lead`) — commit-atomar
|
||||
mit dem Lead; die manipulationssichere Hash-Kette wird asynchron vom
|
||||
`audit-event-persist`-Worker verkettet. Anschließend passende
|
||||
`webhook.received`-Automationen einreihen und ein `PublicWebhookIngestionLog`
|
||||
schreiben.
|
||||
|
||||
## Bekannte Grenzen (Stand dieser Doku)
|
||||
|
||||
Der Intake schreibt bewusst **nur** Lead + Audit + Ingestion-Log +
|
||||
Automation-Einreihung. Im Vergleich zum internen Service
|
||||
`leadService.createLead` fehlen (bewusst, als Folgearbeit):
|
||||
|
||||
- **Anti-Spam-Scoring** (`spamScore`, Quarantäne, Ratenanomalie) — der
|
||||
Public-Intake setzt keinen Spam-Score.
|
||||
- **`lead.created`-Outbox-Fan-out** (Workflow-Engine/Notifications über den
|
||||
Lead-Workflow-Event) — nur die Audit-Outbox wird geschrieben.
|
||||
- **Such-Projektion** (Meilisearch-Upsert des Leads).
|
||||
- **Activity-Stream-Eintrag** (`logActivity`) — siehe Hinweis unten.
|
||||
- **Firma/Quelle/Kampagne** werden nicht in eigene Lead-Felder gemappt (nur in
|
||||
`rohdaten` erhalten).
|
||||
|
||||
> Der Activity-Eintrag wird hier nicht geschrieben, weil `@hivegrid/activity`
|
||||
> von `@hivegrid/db` abhängt; ein Import in `packages/db` erzeugte einen
|
||||
> Paket-Zyklus. Der saubere Weg ist eine geteilte Lead-Ingestion-Schicht bzw.
|
||||
> ein `logActivity`-Aufruf auf Route-Ebene (`apps/api`, darf `@hivegrid/activity`
|
||||
> importieren) — nachzuziehen, wenn der Intake ohnehin angefasst wird.
|
||||
@@ -1,131 +0,0 @@
|
||||
# Architecture Migration Status
|
||||
|
||||
This document is the canonical current-state snapshot for the repository architecture migration. It describes what is present today, which boundaries are already runtime-wired, and which surfaces remain skeleton-only so later pruning and extraction work can use one repo-state contract.
|
||||
|
||||
## Workspace and package manager state
|
||||
|
||||
- The repository is a private pnpm-managed project (`packageManager: pnpm@10.33.0`) with root package name `hivegrid-cloud` and root scripts that delegate to the `apps/web` React Router runtime.
|
||||
- The root `package.json` keeps the top-level command surface: `dev`, `build`, `start`, and `typecheck` delegate into the workspace-owned web runtime and shared package boundaries.
|
||||
- Workspace dependencies are already declared for the target package boundaries through `workspace:*` imports such as `@hivegrid/config`, `@hivegrid/db`, `@hivegrid/mail`, `@hivegrid/queue`, and `@hivegrid/ui`.
|
||||
- The migration is therefore no longer root-hybrid for web source ownership: `apps/web/app` is authoritative for the current web application, while `apps/*` and `packages/*` provide conservative target boundaries for later route-by-route or category-by-category extraction.
|
||||
|
||||
## Boundary status
|
||||
|
||||
| Boundary | Status | Current state |
|
||||
| ----------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `apps/web` | runtime source home | Physical home for the React Router web app under `apps/web/app` and `apps/web/public`; root-level commands still own the top-level developer entrypoints. |
|
||||
| `apps/api` | runtime-wired API app | Dedicated Hono API app owns the canonical `/v1` route surface, route-access inventory, OpenAPI docs, health/readiness routes, and package scripts for dev/build/start/typecheck. Some `/v1` routes still proxy web-owned internal handlers until their service code is extracted, so document both the canonical API route and any temporary web implementation owner. |
|
||||
| `apps/worker` | runtime-wired foundation, disabled by default | BullMQ worker entrypoint exists and can be run directly, but exits unless `WORKER_ENABLED=true`. It owns concrete handler paths for mail, webhooks, notifications, maintenance, storage scans, exports, imports, guarded AI/browser descriptors, `worker-general` outbox dispatch, `outbox.workflow`, `outbox.plugin-hook` fanout, and isolated `worker-plugin` invocation. Live Coolify deployment proof still belongs to the deployment/workers runbooks, not this architecture snapshot. |
|
||||
| `packages/config` | partially runtime-wired catalog | Typed environment catalog and validation helpers document the current environment surface and are wired into web/API/worker runtime loaders plus env drift checks. |
|
||||
| `packages/db` | partially runtime-wired boundary | Owns the server-side Prisma client boundary through `@hivegrid/db/client.server`, the Prisma 7 generated TypeScript client boundary at `packages/db/generated/prisma/client`, and the package command surface for generate, migrate deploy and seed. The schema and migrations still physically live under `prisma/` and are reached through the root Prisma config. |
|
||||
| `packages/mail` | runtime-wired source boundary | Provides the Mailjet provider adapter and `MailProvider` contract for transactional mail. It is source-only but represents the active provider boundary that later API/worker runtime code should instantiate. |
|
||||
| `packages/queue` | runtime-wired queue contract | Defines BullMQ queue names, typed payloads, producer helpers and factory helpers consumed by web/API enqueue paths and `apps/worker` processors. |
|
||||
| `packages/shared` | skeleton-only | Intentionally empty cross-cutting package reserved for dependency-free shared types, utilities and constants once ownership is clear. |
|
||||
| `packages/ui` | skeleton-only adapter contracts | Source-only UI adapter boundary. It exposes stable adapter metadata for selected categories but does not render components, import React or replace current app imports yet. |
|
||||
|
||||
## Runtime-wired versus skeleton-only summary
|
||||
|
||||
Runtime-wired or partially runtime-wired surfaces:
|
||||
|
||||
- `apps/web`: physical React Router web app source and public asset home; root scripts delegate into this runtime.
|
||||
- `apps/api`: independent Hono API app and server scripts are present; current `/v1` routes include health/docs, auth/session, API-key validation, accounts/usage, analytics, notifications, workspaces, entities, relationships, exports, billing webhook ingress, and maintenance enqueue behavior. Widget and workflow `/v1` surfaces are plugin-disabled historical code paths, not active canonical API routes. Temporary proxy routes must be documented as API-owned entrypoints with web-owned implementation handlers until extracted.
|
||||
- `apps/worker`: executable worker boundary exists but is intentionally opt-in through `WORKER_ENABLED=true`; processors are wired for the current queue payload contracts, including the five configured worker groups (`general`, `mail`, `import`, `webhook`, `plugin`) and the worker-general outbox/Workflow/Plugin-Hook fanout paths. This is repository/runtime contract evidence; environment-specific Coolify health still comes from `docs/deployment.md`, `docs/worker.md`, and `docs/ops/worker-queues.md`.
|
||||
- `packages/db`: server-side Prisma client boundary, Prisma 7 generated TypeScript client output, and database command entrypoints exist in the package boundary; the schema and migrations still live in `prisma/` and are referenced by root Prisma config.
|
||||
- `packages/mail`: Mailjet provider contract and adapter exist as the transactional mail boundary.
|
||||
|
||||
Skeleton-only or documentation/contract surfaces:
|
||||
|
||||
- `packages/shared`: intentionally empty until clear shared ownership emerges.
|
||||
- `packages/ui`: adapter metadata and migration contracts only; current UI runtime imports remain in `apps/web/app/`.
|
||||
|
||||
## Architecture Closure final closure status
|
||||
|
||||
Architecture Closure closes the architecture snapshot as a handoff contract, not as a claim that every feature has already been deleted or extracted at runtime. API, worker and package boundaries are documented above: `apps/api`, `apps/worker`, `packages/config`, `packages/db`, `packages/mail` and `packages/queue` have concrete or partial runtime wiring, while `apps/web` owns the web source tree and `packages/shared` and `packages/ui` remain skeleton-only or contract surfaces until sequential atomic migration tasks move ownership. This preserves R001 handoff coverage and R002 sequencing by keeping the current React Router runtime authoritative until each downstream extraction replaces it directly.
|
||||
|
||||
The feature-pruning contract is now anchored in `docs/feature-manifests/` and validated by `apps/web/app/application/featureManifests.test.ts`. `docs/feature-inventory.md` remains the human-readable Core/Plugin/Removal inventory, while the manifests are the machine-readable source for `core`, `plugin-candidate`, `remove-candidate` and related pruning actions. Under R003, these classifications are removal and replacement instructions for future work; they are not a permanent legacy-support promise and should not be interpreted as runtime plugin extraction already completed.
|
||||
|
||||
S04 bundle/performance evidence is represented by the static build-boundary helpers `apps/web/app/utils/build/bundleScan.ts` and `apps/web/app/utils/build/manualChunks.ts`, which make heavy feature/dependency surfaces visible before pruning work removes or packages them. The optional manual follow-up remains `pnpm build`: use it as a human verification step for production bundle behavior when needed, but do not treat its absence here as contradicting the documented Architecture Closure closure.
|
||||
|
||||
### Portals/Sites DB Ownership
|
||||
|
||||
D006 records the DB ownership exception for Portals/Sites: do not move these persistence calls into `packages/db` as part of the current DB/Prisma ownership work. Until the feature/plugin decision determines whether Portals/Sites are extracted as optional plugins or removed from the default boilerplate, `apps/web/app/modules/portals/db/*` and `apps/web/app/modules/sites/db/sites.db.server.ts` remain the accepted temporary module-owned persistence boundaries. This is a documented deferral, not full R006 validation for Portals/Sites, and it is separate from the URL-boundary guidance below for internal tenant navigation versus public portal/site URLs.
|
||||
|
||||
## R003: clean replacement and removal rule
|
||||
|
||||
R003 is implemented as a pruning and boundary rule, not as a compatibility promise. Replaced or removed features should be either cleanly implemented in their target boundary or deleted from the active runtime; they should not be preserved through permanent legacy adapters, shadow call sites, or indefinite compatibility layers.
|
||||
|
||||
Temporary coexistence is acceptable only while a later migration task explicitly owns extraction and verification. Once a feature is marked as replaced or removed in the inventory/manifests, future implementation work should prefer direct deletion, direct replacement, or a short-lived migration step with clear removal criteria.
|
||||
|
||||
## UrlUtils migration inventory
|
||||
|
||||
This inventory tracks feature-specific URL construction that should move toward explicit `UrlUtils` helpers instead of legacy string concatenation or broad adapters. Each item records the current state, the first clean migration unit, and the scoped verification expected for that unit.
|
||||
|
||||
### Rows/Groups
|
||||
|
||||
Status: mixed `UrlUtils` adoption with concrete hard-path follow-ups.
|
||||
|
||||
- `apps/web/app/modules/rows/routes/Rows_New.server.ts` and `apps/web/app/modules/rows/routes/Rows_Edit.server.ts` already use `UrlUtils.currentTenantUrl(params, "404")` for tenant-scoped 404 redirects when autogenerated/system entity checks fail.
|
||||
- Row create/edit flows delegate row destinations through `EntitiesApi.getNoCodeRoutes(...)`, `EntityHelper.getRoutes(...)`, route-relative links such as `entity.slug + "/new"`, and existing `currentEntityUrl`-covered route contracts rather than building every row URL inline.
|
||||
- `apps/web/app/routes/app.$tenant/g.$group/index.tsx` builds group dashboard stat paths with `appPath(...)` and `adminPath(...)`; the old direct `/app/${tenantId}/...` and `/admin/...` string-concatenation wording is stale.
|
||||
- `apps/web/app/routes/app.$tenant/g.$group/all.tsx` uses route-relative creation links and `EntitiesApi.getNoCodeRoutes(...)` for row list routing, so it is a lower-risk migration candidate than the group stat path builder.
|
||||
- Rows create/edit actions accept `redirect` form/query parameters and pass them to `redirect(...)` when present. That trust boundary is intentionally only inventoried here; a later security-focused task should normalize same-origin/app-local redirects before changing behavior.
|
||||
|
||||
First atomic migration plan: keep `apps/web/app/routes/app.$tenant/g.$group/index.tsx` on `appPath(...)`/`adminPath(...)`, keep route-relative links in `all.tsx` unchanged, and extend the focused URL tests when new group dashboard destinations are introduced.
|
||||
|
||||
### Workflow Engine
|
||||
|
||||
Status: already aligned with direct tenant module URL rules.
|
||||
|
||||
- `apps/web/app/modules/workflowEngine/routes/workflow-engine.view.tsx` builds sidebar destinations through `UrlUtils.getModulePath(params, "workflow-engine...")`, matching the current direct tenant module rule for Workflow Engine sections such as workflows, variables, credentials, executions, templates, and danger.
|
||||
- The shell route files for Workflow Engine remain thin delegates into `apps/web/app/modules/workflowEngine/routes/**`; the module route file is the authoritative URL construction surface for the sidebar.
|
||||
- No legacy adapter is needed for Workflow Engine under R003 because the current call sites already target the canonical `getModulePath` behavior instead of preserving parallel hard-coded `/app/${tenant}` module strings.
|
||||
|
||||
First atomic migration plan: keep `workflow-engine.view.tsx` on `UrlUtils.getModulePath(...)` and add regression coverage only when new Workflow Engine shell routes or sidebar entries are introduced. Candidate paths are `apps/web/app/modules/workflowEngine/routes/workflow-engine.view.tsx` and the shell route delegates that import from `apps/web/app/modules/workflowEngine/routes/**`; verification is the focused UrlUtils contract asserting `workflow-engine` and nested `workflow-engine/*` paths for tenant params.
|
||||
|
||||
### Forms/FormBuilder
|
||||
|
||||
Status: active as Form Widget runtime; legacy form/survey routes remain removed.
|
||||
|
||||
- Tenant form administration lives under the direct tenant routes `/:tenant/forms` and `/:tenant/forms/:id` via `apps/web/app/routes/app.$tenant/forms.tsx` and `apps/web/app/routes/app.$tenant/forms.$id.tsx`.
|
||||
- The embeddable public runtime lives under `/embed/forms/:formKey` and the submit API uses `/api/embed/forms/:formKey/submit`; these are public/embed boundaries, not tenant module navigation paths.
|
||||
- Removed legacy surfaces stay removed: public `/f`, `/surveys`, form-based Help Desk survey routes, and `settings/forms` routing must not be reintroduced by default.
|
||||
|
||||
### Portals
|
||||
|
||||
Status: mostly aligned with `UrlUtils.getModulePath(...)` for internal tenant navigation, with a separate public portal URL boundary.
|
||||
|
||||
- The authenticated tenant shell under `apps/web/app/routes/app.$tenant/__portals/**` is the internal navigation surface for Portals. The list route uses `UrlUtils.getModulePath(params, "portals/new")` for new-portal navigation, and the portal detail shell builds paths from the canonical portal subdomain (`portal.subdomain || params.portal`) for overview, pages, users, analytics, pricing, domains, settings, and danger sections.
|
||||
- `apps/web/app/routes/app.$tenant/__portals/portals.tsx` also contains route-relative internal links such as `to="new"` and `to={item.subdomain}`. These remain React Router tenant-shell links today; they are inventory candidates for explicit contract coverage rather than immediate migration because the surrounding route already establishes the tenant module context.
|
||||
- External portal URLs are built outside the tenant-app route contract. The list loader obtains public URLs through `PortalServer.getPortalUrl(item)`, and `apps/web/app/modules/portals/utils/PortalUtils.ts` exposes `getUrl(item, path)` as a public portal URL helper based on `item.url`.
|
||||
- Public portal URLs and portal server/domain links are external navigation boundaries. They must not be normalized through `UrlUtils.getModulePath(...)`, which is reserved for internal tenant React Router destinations.
|
||||
- Under R003, Portals do not need a legacy URL adapter: current internal shell navigation already uses canonical module-path helpers, while public portal URLs should keep a separate public URL contract.
|
||||
|
||||
First atomic migration plan: add Portals contract assertions to `apps/web/app/utils/app/UrlUtils.test.ts` for tenant module paths such as `portals`, `portals/new`, `portals/:portal/pages`, and `portals/:portal/settings`; keep `PortalServer.getPortalUrl(...)` and `PortalUtils.getUrl(...)` outside `UrlUtils.getModulePath(...)`; then consider replacing route-relative list/detail links only if a later task introduces a concrete helper for portal subdomain detail paths.
|
||||
|
||||
### Sites
|
||||
|
||||
Status: helper-built internal tenant paths with a separate external site preview/deployment URL surface.
|
||||
|
||||
- `apps/web/app/routes/app.$tenant/sites/$type.tsx` builds primary new-site, detail, and settings links through `appPath(...)` via a local `tenantSitePath(...)` wrapper.
|
||||
- The same route also renders external site URLs from `buildSiteUrlFromFields(site.serverHost, site.serverResolution, site.siteId)`. Those `href={siteUrl}` links open deployed/public sites and must stay outside `UrlUtils.getModulePath(...)` because they are not internal React Router tenant destinations.
|
||||
- `apps/web/app/routes/app.$tenant/sites/new.tsx` redirects newly created sites and renders the back link through `appPath(...)`.
|
||||
- `apps/web/app/modules/sites/components/site-form.tsx` is a form and external preview surface: it slugifies `siteId`, posts create/update form state, and previews deployment URLs through `buildSiteUrlFromServer(...)`. This slice should not change its internal behavior or route paths; later URL work should treat tenant/site IDs as normalized inputs before they flow into internal UrlUtils helpers, while keeping deployment preview URLs on the Sites public URL helpers.
|
||||
|
||||
First atomic migration plan: keep `apps/web/app/routes/app.$tenant/sites/$type.tsx` and `apps/web/app/routes/app.$tenant/sites/new.tsx` on helper-built internal destinations; keep `site-form.tsx` preview/deployment URL construction unchanged and explicitly outside internal tenant-app URL helpers.
|
||||
|
||||
### First UrlUtils migration backlog
|
||||
|
||||
1. Rows/Groups contract candidate: keep `apps/web/app/routes/app.$tenant/g.$group/index.tsx` on `appPath(...)`/`adminPath(...)` and extend tests when new group dashboard destinations are introduced.
|
||||
2. Forms contract candidate: keep tenant Forms redirects and overview links on helper-built module paths while leaving public form URLs and external redirects on a separate public-form/security contract.
|
||||
3. Sites contract candidate: keep internal Sites links/redirects on `appPath(...)`; keep public and deployed site preview URLs outside internal tenant navigation helpers.
|
||||
4. Workflow Engine contract candidate: keep `apps/web/app/modules/workflowEngine/routes/workflow-engine.view.tsx` on existing `UrlUtils.getModulePath(params, "workflow-engine...")` usage and extend only contract tests when new Workflow Engine sections are introduced.
|
||||
5. Portals contract candidate: keep internal Portals shell navigation on `UrlUtils.getModulePath(...)`, keep `PortalServer.getPortalUrl(...)` and `PortalUtils.getUrl(...)` as public portal URL boundaries, and add/maintain contract assertions for portal module paths before replacing route-relative links.
|
||||
|
||||
## Next implementation inputs
|
||||
|
||||
Use these files as the concrete inputs for follow-up implementation and pruning work:
|
||||
|
||||
- `docs/feature-inventory.md` — human-readable feature inventory and keep/plugin/remove/status classification.
|
||||
- `docs/feature-manifests/*.json` — machine-readable feature manifests for boundary ownership, pruning decisions and downstream task planning.
|
||||
|
||||
This status snapshot should be updated whenever a boundary changes from skeleton-only to runtime-wired, when root runtime ownership moves into an `apps/*` or `packages/*` workspace, when feature-specific UrlUtils migration status changes, or when R003-driven pruning changes the active feature surface.
|
||||
@@ -8,12 +8,14 @@
|
||||
|
||||
Web bundle growth is silent unless we measure it. The boilerplate tracks two complementary signals:
|
||||
|
||||
1. **Group budgets** (`BUDGETS` constant in `verify-bundle-size.mjs`): coarse caps for `root` / `initial_payload_js` / `vendor` / `route` / `other` / `css` / `total_js` / `manifest_js`. Hard CI gate — failure exits 1.
|
||||
2. **Per-route + per-vendor-chunk budgets** (`scripts/bundle-budgets.json`): fine-grained gzip limits per route and per vendor chunk. **Non-blocking** — surfaces as a PR-comment with a Δ-from-main column. Reviewers decide whether growth is justified.
|
||||
1. **Group budgets** (`BUDGETS` constant in `verify-bundle-size.mjs`): coarse caps for `root` / `initial_payload_js` / `vendor` / `route` / `other` / `lazy_runtime` / `application_js` / `total_js` / `css` / `manifest_js`. Hard CI gate — failure exits 1.
|
||||
2. **Per-route, per-vendor and per-lazy-runtime budgets** (`scripts/bundle-budgets.json`): fine-grained gzip limits for routes, vendor chunks and self-hosted feature runtimes/workers. **Non-blocking** — surfaces as a PR-comment with a Δ-from-main column. Reviewers decide whether growth is justified.
|
||||
|
||||
The per-route layer was added in task #71 (Phase 10) to make day-to-day creep visible without blocking legitimate feature work.
|
||||
|
||||
`initial_payload_js` is a dedicated hard signal for the boot asset aggregate the current parser can identify without reading Rollup/Vite dependency graphs: `entry.client-*`, `root-*`, and `manifest-*`. It intentionally excludes route, vendor, and component chunks so lazy feature payloads cannot hide a shell regression in `total_js`.
|
||||
`initial_payload_js` recursively follows the static imports of the React Router entry and root modules. Dynamic imports stay outside that boot signal.
|
||||
|
||||
Self-hosted feature runtimes need a separate signal. `lazy_runtime` contains Monaco, PDF.js and emitted Web Worker entry points: these bytes replaced executable CDN downloads and are loaded only when the feature or worker is activated. `application_js` preserves the pre-self-hosting cap for the app itself, while `total_js` still caps every emitted JavaScript byte including lazy runtimes. This keeps CDN removal from weakening either critical-path or overall artifact controls.
|
||||
|
||||
## Config schema
|
||||
|
||||
@@ -24,11 +26,15 @@ The per-route layer was added in task #71 (Phase 10) to make day-to-day creep vi
|
||||
"default": { "limitKb": 200, "warningKb": 180 },
|
||||
"routes": {
|
||||
"app/$tenant/dashboard": { "limitKb": 250, "warningKb": 225 },
|
||||
"auth/magic-link": { "limitKb": 80, "warningKb": 75 }
|
||||
"auth/magic-link": { "limitKb": 80, "warningKb": 75 },
|
||||
},
|
||||
"vendorChunks": {
|
||||
"vendor-react": { "limitKb": 150, "warningKb": 135 }
|
||||
}
|
||||
"vendor-react": { "limitKb": 150, "warningKb": 135 },
|
||||
},
|
||||
"lazyRuntimeChunks": {
|
||||
"MonacoEditor.client": { "limitKb": 1000, "warningKb": 950 },
|
||||
"ts.worker": { "limitKb": 1550, "warningKb": 1520 },
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
@@ -38,6 +44,7 @@ The per-route layer was added in task #71 (Phase 10) to make day-to-day creep vi
|
||||
- Routes use React Router v7 route ids in either dot- or slash-form (`auth/magic-link` and `auth.magic-link` both match).
|
||||
- Unmatched routes fall back to `default`.
|
||||
- Unmatched vendor chunks (anything starting with `vendor-` or `chunk-`) are reported under the chunk basename and also fall back to `default`.
|
||||
- Monaco/PDF.js chunks and `*.worker-*` entry points use `lazyRuntimeChunks`; these budgets make formerly hidden CDN payloads reviewable without treating them as route modules.
|
||||
|
||||
## Local workflow
|
||||
|
||||
@@ -71,15 +78,17 @@ The visualizer is gated on `ANALYZE_BUNDLE=true` so the regular production build
|
||||
|
||||
**Security note:** `stats.html` contains source-map references and should never be deployed publicly. Treat it as a developer-only artifact.
|
||||
|
||||
## PR-comment workflow
|
||||
## Gitea workflow
|
||||
|
||||
`.github/workflows/bundle-budget.yml` (and `.gitea/workflows/bundle-budget.yml`) run on every PR that touches `apps/web/**`, `packages/**`, or the budget config / verifier. They:
|
||||
`.gitea/workflows/bundle-budget.yml` runs on every relevant Gitea pull request. The dedicated workflow keeps the expensive web build outside the default CI lane while still enforcing the aggregate budget.
|
||||
|
||||
The workflow:
|
||||
|
||||
1. Build `@hivegrid/web`.
|
||||
2. Run `verify-bundle-size.mjs --json`.
|
||||
3. Download the latest `bundle-baseline-main` artifact (captured by `bundle-budget-baseline.yml` on `main` pushes).
|
||||
4. Render a sticky markdown comment via `scripts/render-bundle-budget-comment.mjs`.
|
||||
5. Upsert the comment using its `<!-- bundle-budget-report -->` marker (GitHub: `marocchino/sticky-pull-request-comment`; Gitea: `scripts/post-bundle-budget-gitea-comment.mjs`).
|
||||
4. Render a markdown report via `scripts/render-bundle-budget-comment.mjs`.
|
||||
5. Upload the JSON and Markdown reports as Gitea Actions artifacts.
|
||||
|
||||
The comment renders rows in severity order (`[EXCEED]` → `[WARN]` → unbudgeted → ok), with columns: status / kind / route or chunk key / current gzip size / configured limit / Δ from main. Δ is `—` if no baseline is available.
|
||||
|
||||
@@ -90,20 +99,20 @@ The first PR after a fresh checkout (or after a baseline-artifact expiry) sees `
|
||||
## When to raise a limit
|
||||
|
||||
1. Confirm the growth is intentional (a new feature shipped, a dependency landed) — not a regression from accidental imports.
|
||||
2. Open the PR; the bundle-budget comment shows the Δ. Reviewers and the PR author should agree the new floor is acceptable.
|
||||
2. Open the pull request; the bundle-budget artifact shows the Δ. Reviewers and the author should agree the new floor is acceptable.
|
||||
3. Edit `scripts/bundle-budgets.json` in the **same PR** that ships the growth. Bump `warningKb` to ≈ (current gzip + 5 KB) and `limitKb` to ≈ (current gzip + 20 KB).
|
||||
4. Call the change out in the PR description so the new floor is reviewable.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- **Don't disable a budget by raising it to 9999 KB.** The point is to surface drift. If a route is legitimately huge, raise the limit to a tight new floor, not infinity.
|
||||
- **Don't lazy-load critical-path code.** Bundle splits help non-critical routes, but the initial payload (`entry.client-*` / `root-*` / `manifest-*`) still has its own `initial_payload_js` hard group budget that must stay tight.
|
||||
- **Don't lazy-load critical-path code.** Bundle splits help non-critical routes, but the recursively measured entry/root static graph still has its own `initial_payload_js` hard group budget that must stay tight.
|
||||
- **Don't bundle-split shared deps.** Splitting `react` into many chunks just shifts cost into chunk boot-up. Keep `vendor-react`, `vendor-core-utils` etc. as single chunks; the manualChunks mapping in `apps/web/app/utils/build/manualChunks.ts` is the source of truth.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **PR comment never shows up:** check the `Bundle Budget` workflow run — the `Build web` step may have failed (e.g. server-only import in a client export). The comment job only runs if all upstream steps succeed.
|
||||
- **`vendor-monaco-...` reports as `vendor-monaco-...-` with default budget:** rollup occasionally emits chunk hashes ending in `-`; the baseline normalizer skips that suffix and the asset falls back to `default`. Either rename via `manualChunks.ts` or add an explicit budget entry.
|
||||
- **Report artifact fehlt:** check the `Bundle Budget` workflow run — the `Build web` step may have failed (e.g. server-only import in a client export).
|
||||
- **A worker appears as a route:** worker filenames must match `*.worker-*` (or PDF.js's `*.worker.min-*`) so the verifier puts them in `lazy_runtime`; update the narrow matcher when adding a differently named worker entry.
|
||||
- **CI run is much slower than `pnpm typecheck`:** the workflow does a full `pnpm --filter @hivegrid/web build`. That's the expected cost. If it ever exceeds ~30 minutes, profile with `ANALYZE_BUNDLE=true` locally first.
|
||||
|
||||
## Rollback
|
||||
|
||||
@@ -7,7 +7,7 @@ and how the Web-Vitals → Sentry bridge surfaces real-user metrics.
|
||||
Companion artefacts: `.lighthouserc.staging.json`,
|
||||
`.lighthouserc.json`, `scripts/lighthouse-puppeteer-auth.cjs`,
|
||||
`scripts/rotate-lighthouse-session-cookie.mjs`,
|
||||
`.github/workflows/lighthouse.yml`, `.gitea/workflows/lighthouse.yml`,
|
||||
`.gitea/workflows/lighthouse.yml`,
|
||||
`apps/web/app/lib/observability/web-vitals.ts`,
|
||||
`apps/web/app/lib/pwa/registerServiceWorker.ts`,
|
||||
`apps/web/public/manifest.webmanifest`, `apps/web/public/sw.js`.
|
||||
@@ -21,7 +21,7 @@ CI workflow audits the **deployed staging site**
|
||||
|
||||
That makes it a **post-deploy / monitoring audit, not a per-commit merge
|
||||
gate** — staging always lags the commit under review. The workflow
|
||||
(`.gitea/workflows/lighthouse.yml`, mirrored in `.github/`) runs:
|
||||
(`.gitea/workflows/lighthouse.yml`) runs:
|
||||
|
||||
- **nightly** at 03:00 UTC (`schedule`), and
|
||||
- **on demand** (`workflow_dispatch`).
|
||||
@@ -31,18 +31,17 @@ it as a production-quality alarm, not a blocked PR.
|
||||
|
||||
The Gitea runner image (`node:20-bookworm`) ships no browser, so the
|
||||
workflow installs `chromium` via `apt-get` and points LHCI at it with
|
||||
`CHROME_PATH=/usr/bin/chromium`. The GitHub runner (`ubuntu-latest`)
|
||||
already bundles Chrome.
|
||||
`CHROME_PATH=/usr/bin/chromium`.
|
||||
|
||||
## Audit targets
|
||||
|
||||
`.lighthouserc.staging.json` audits the public staging routes — the
|
||||
surface that renders without authentication:
|
||||
|
||||
| URL |
|
||||
| -------------------------------------------- |
|
||||
| `https://boiler.saas-ctrl.com/login` |
|
||||
| `https://boiler.saas-ctrl.com/privacy-policy` |
|
||||
| URL |
|
||||
| --------------------------------------------------- |
|
||||
| `https://boiler.saas-ctrl.com/login` |
|
||||
| `https://boiler.saas-ctrl.com/privacy-policy` |
|
||||
| `https://boiler.saas-ctrl.com/terms-and-conditions` |
|
||||
|
||||
Only **Performance** is a hard gate (`error`). The product is a B2B
|
||||
@@ -52,13 +51,13 @@ not asserted at all. Accessibility and Best-Practices stay visible as
|
||||
(axe-core plus the `jsx-a11y` ESLint baseline, task #73), so a second
|
||||
blocking gate here would be redundant.
|
||||
|
||||
| Category | Threshold | Severity |
|
||||
| --------------- | --------- | ------------------------- |
|
||||
| Performance | 0.95 | error |
|
||||
| Accessibility | 0.95 | warn |
|
||||
| Best Practices | 0.95 | warn |
|
||||
| PWA | 0.90 | warn |
|
||||
| SEO | — | not asserted (irrelevant) |
|
||||
| Category | Threshold | Severity |
|
||||
| -------------- | --------- | ------------------------- |
|
||||
| Performance | 0.95 | error |
|
||||
| Accessibility | 0.95 | warn |
|
||||
| Best Practices | 0.95 | warn |
|
||||
| PWA | 0.90 | warn |
|
||||
| SEO | — | not asserted (irrelevant) |
|
||||
|
||||
Numeric audits (FCP / LCP / TBT / CLS) stay at `warn` severity so trend
|
||||
regressions remain visible without failing the run.
|
||||
@@ -74,14 +73,16 @@ the cookie or password.
|
||||
|
||||
Required workflow secrets:
|
||||
|
||||
| Secret | Purpose |
|
||||
| ------ | ------- |
|
||||
| `LIGHTHOUSE_LOGIN_EMAIL` | Email of the staging Lighthouse bot user. |
|
||||
| Secret | Purpose |
|
||||
| --------------------------- | -------------------------------------------- |
|
||||
| `LIGHTHOUSE_LOGIN_EMAIL` | Email of the staging Lighthouse bot user. |
|
||||
| `LIGHTHOUSE_LOGIN_PASSWORD` | Password of the staging Lighthouse bot user. |
|
||||
|
||||
The session cookie name is `hivegrid_session`; workflows also pass
|
||||
`LIGHTHOUSE_SESSION_COOKIE_NAME=hivegrid_session` and
|
||||
`LIGHTHOUSE_COOKIE_DOMAIN=boiler.saas-ctrl.com`.
|
||||
The app session cookie name is `__Host-hivegrid_app_session`; workflows also
|
||||
pass `LIGHTHOUSE_SESSION_COOKIE_NAME=__Host-hivegrid_app_session`. The cookie
|
||||
is injected URL-bound without a `Domain` attribute so Chromium preserves the
|
||||
`__Host-` contract. `LIGHTHOUSE_COOKIE_DOMAIN=app.hivegrid.de` remains only as
|
||||
a compatibility input for local, non-prefixed cookie names.
|
||||
|
||||
During rollout the workflow still forwards the older
|
||||
`LIGHTHOUSE_SESSION_COOKIE` secret as a fallback. If the login email or
|
||||
@@ -91,9 +92,11 @@ each run mints a fresh cookie.
|
||||
|
||||
## Authenticated routes
|
||||
|
||||
Auditing `/app/$tenant/*` and `/admin/*` needs that freshly minted
|
||||
`hivegrid_session` cookie. `scripts/lighthouse-puppeteer-auth.cjs` injects the
|
||||
cookie for protected URLs and is already wired into
|
||||
Auditing app routes needs that freshly minted `__Host-hivegrid_app_session`
|
||||
cookie. Admin routes require a separately minted
|
||||
`__Host-hivegrid_admin_session`; an app cookie is intentionally never reused
|
||||
on the admin sibling host. `scripts/lighthouse-puppeteer-auth.cjs` injects the
|
||||
configured cookie for protected URLs and is already wired into
|
||||
`.lighthouserc.staging.json`. The current staging target list still
|
||||
audits only public routes; add protected URLs once the exact tenant/admin
|
||||
coverage list is chosen. Without a protected URL in the config, the
|
||||
@@ -121,7 +124,7 @@ To reproduce a CI staging finding locally, point LHCI at the staging
|
||||
config instead — no local server needed, just a Chrome install:
|
||||
|
||||
```sh
|
||||
pnpm dlx @lhci/cli@0.13.x autorun --config=./.lighthouserc.staging.json
|
||||
pnpm dlx @lhci/cli@0.13.0 autorun --config=./.lighthouserc.staging.json
|
||||
```
|
||||
|
||||
The run prints the temporary-public-storage report URLs in its output;
|
||||
@@ -130,14 +133,18 @@ share those when debugging a regression.
|
||||
## PWA manifest + service-worker
|
||||
|
||||
`apps/web/public/manifest.webmanifest` describes the installable app.
|
||||
`apps/web/public/sw.js` is a minimal cache-first / network-first service
|
||||
`apps/web/public/sw.js` is an assets-only cache-first service
|
||||
worker registered from `root.tsx` via `registerServiceWorker`.
|
||||
|
||||
Cache strategy:
|
||||
|
||||
- `/assets/...` (hashed by React-Router build) → **cache-first**
|
||||
- `/api/...`, `/app/...`, `/admin/...` → **network-first** with cache fallback
|
||||
- everything else (marketing routes, brand assets) → **network-first**
|
||||
- HTML, loader/data, API, media and all other URLs → **not intercepted**; the
|
||||
browser HTTP cache applies the origin `Cache-Control`/`Vary` contract.
|
||||
|
||||
Session-derived responses must never enter Service Worker Cache Storage. Cache
|
||||
Storage is URL-keyed and an offline fallback could otherwise expose one user's
|
||||
cached HTML or JSON to another user of the same browser profile.
|
||||
|
||||
The `CACHE_VERSION` constant inside `sw.js` is the invalidation lever —
|
||||
bump it on any deploy that changes the asset graph in a backward-
|
||||
@@ -171,14 +178,14 @@ dev, preview, staging, and production without extra gating.
|
||||
|
||||
## Troubleshooting CI runs
|
||||
|
||||
| Symptom | Likely cause / fix |
|
||||
| -------------------------------------------------- | ----------------------------------------------------------------------------- |
|
||||
| Symptom | Likely cause / fix |
|
||||
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `Chrome installation not found` / `Healthcheck failed!` | The runner has no browser. The Gitea workflow installs `chromium`; confirm the install step ran and `CHROME_PATH` is set. |
|
||||
| Cookie rotation step fails with missing env vars | Add `LIGHTHOUSE_LOGIN_EMAIL` and `LIGHTHOUSE_LOGIN_PASSWORD` as repo Actions secrets. |
|
||||
| Audit reports the `/login` page for a protected URL | Cookie injection failed or the bot no longer belongs to the tenant/admin surface being audited. |
|
||||
| Performance score < 0.95 only on first run | Cold cache; LHCI reruns automatically (`numberOfRuns=3`). |
|
||||
| Audit times out | Lower `numberOfRuns` to 1 temporarily while iterating; restore afterwards. |
|
||||
| All URLs fail to load | Staging is down or redeploying — check the `web` container on staging. |
|
||||
| Cookie rotation step fails with missing env vars | Add `LIGHTHOUSE_LOGIN_EMAIL` and `LIGHTHOUSE_LOGIN_PASSWORD` as repo Actions secrets. |
|
||||
| Audit reports the `/login` page for a protected URL | Cookie injection failed or the bot no longer belongs to the tenant/admin surface being audited. |
|
||||
| Performance score < 0.95 only on first run | Cold cache; LHCI reruns automatically (`numberOfRuns=3`). |
|
||||
| Audit times out | Lower `numberOfRuns` to 1 temporarily while iterating; restore afterwards. |
|
||||
| All URLs fail to load | Staging is down or redeploying — check the `web` container on staging. |
|
||||
|
||||
## Updating thresholds
|
||||
|
||||
|
||||
@@ -235,7 +235,7 @@ execution later fails, stalls, or remains queued behind a missing bridge.
|
||||
|
||||
### Re-queueing failed events
|
||||
|
||||
Use `hivegrid-cli outbox requeue` after fixing the underlying receiver.
|
||||
Use `hivegrid-cli outbox requeue --tenant <tenantId>` after fixing the underlying receiver.
|
||||
The CLI supports single-row and filtered bulk requeues, `--dry-run`, JSON
|
||||
output, and guardrails that avoid replaying `PENDING` / `PROCESSING`
|
||||
rows. Prefer it over raw SQL so `processedAt`, `lastError`, retry state,
|
||||
|
||||
@@ -148,7 +148,7 @@ tenant-default subscribers remain eligible.
|
||||
### 11. Operator CLI — `packages/cli/src/commands/plugins/*`
|
||||
|
||||
```
|
||||
hivegrid-cli plugins list [--tenantId X] [--enabled true|false]
|
||||
hivegrid-cli plugins list --tenantId X [--enabled true|false]
|
||||
hivegrid-cli plugins enable --tenantId X --pluginId com.acme.slack
|
||||
hivegrid-cli plugins disable --tenantId X --pluginId com.acme.slack
|
||||
hivegrid-cli plugins uninstall --tenantId X --pluginId com.acme.slack
|
||||
|
||||
@@ -136,8 +136,11 @@ steps live with the platform operator.
|
||||
3. **App env**:
|
||||
|
||||
```sh
|
||||
DATABASE_URL=postgres://app_user:...@pgbouncer:6432/hivegrid?pgbouncer=true&connection_limit=10
|
||||
DATABASE_READ_URL=postgres://read_user:...@postgres-replica:5432/hivegrid?connection_limit=10
|
||||
DATABASE_URL=postgres://app_user:...@pgbouncer:6432/hivegrid
|
||||
DATABASE_READ_URL=postgres://read_user:...@postgres-replica:5432/hivegrid
|
||||
DATABASE_POOL_MAX=10
|
||||
DATABASE_POOL_IDLE_TIMEOUT_MS=10000
|
||||
DATABASE_POOL_CONNECTION_TIMEOUT_MS=5000
|
||||
```
|
||||
|
||||
Optionally front the replica with its own PgBouncer for connection pooling.
|
||||
@@ -193,7 +196,8 @@ steps live with the platform operator.
|
||||
(post-auth).
|
||||
- `apps/web/app/modules/sites/db/sites.db.server.ts` — read-only site
|
||||
loaders (auth-gating `getSiteByTypeAndSiteId` left on primary).
|
||||
- `apps/web/app/modules/portals/db/portals.db.server.ts` and
|
||||
- The then-existing `apps/web/app/modules/portals/db/portals.db.server.ts`
|
||||
(removed by the VA-P26a legacy recut) and the retained
|
||||
`portalPages.db.server.ts` — listings, page lookups, dashboard counts.
|
||||
|
||||
`appData.ts` was **not** migrated wholesale; only the secondary tenant
|
||||
|
||||
@@ -6,10 +6,8 @@
|
||||
This document explains how test coverage is measured, gated, and reported in the
|
||||
HiveGrid. Per-path thresholds are encoded as data in
|
||||
`scripts/coverage-targets.json` and enforced by `scripts/verify-test-coverage.mjs`.
|
||||
CI workflows run the gate on GitHub PRs and `push` to `main`, while the
|
||||
Gitea coverage workflow currently runs on pull requests. Keep
|
||||
`.github/workflows/coverage.yml`, `.gitea/workflows/coverage.yml`, and
|
||||
this policy aligned when trigger coverage changes.
|
||||
The Gitea coverage workflow runs the gate on relevant pull requests, pushes to
|
||||
`main`, and manual dispatches. The local command uses the same targets.
|
||||
|
||||
## Why
|
||||
|
||||
@@ -83,8 +81,8 @@ latest ratchet already meets or exceeds for every critical-path row (see
|
||||
3. Run `pnpm run verify:test-coverage` locally. The gate prints the actual
|
||||
coverage; set the active gate at or slightly below that number so the
|
||||
commit lands green.
|
||||
4. Open a PR. The Coverage workflow will post a sticky comment showing the
|
||||
new row in the per-path table.
|
||||
4. Open a pull request. The Coverage workflow uploads a Markdown report showing
|
||||
the new row in the per-path table.
|
||||
|
||||
## How to bump or lower a threshold
|
||||
|
||||
@@ -113,8 +111,8 @@ Bumps **down** (looser gate) — should be rare and reviewed:
|
||||
- any target's actual `statements%` < `target.statements` **or**
|
||||
actual `branches%` < `target.branches`
|
||||
|
||||
The GitHub workflow uploads `coverage/` as `coverage-report-<run_id>` even on
|
||||
failure so contributors can drill into the HTML report.
|
||||
The Gitea workflow uploads `coverage-gate/` and the rendered Markdown summary
|
||||
as `coverage-report-<run_id>` even on failure.
|
||||
|
||||
## Type-only packages
|
||||
|
||||
@@ -128,15 +126,13 @@ sprint target, then cover their contract with `expectTypeOf` tests and
|
||||
|
||||
Task #76 is completed. Keep the gate useful as a no-regression control:
|
||||
|
||||
1. Confirm `docs/testing/coverage-sprint-backlog.md` still has no
|
||||
critical-path or standard-tier positive-gap rows before release closeouts.
|
||||
2. Keep each active `statements`/`branches` gate at or above the relevant
|
||||
1. Keep each active `statements`/`branches` gate at or above the relevant
|
||||
`sprintTarget`.
|
||||
3. Treat `sprintTarget` fields as explicit release-floor annotations unless a
|
||||
2. Treat `sprintTarget` fields as explicit release-floor annotations unless a
|
||||
future cleanup removes them consistently from docs and gate data.
|
||||
4. Run `pnpm run verify:test-coverage` after threshold changes — it must pass
|
||||
3. Run `pnpm run verify:test-coverage` after threshold changes — it must pass
|
||||
with the new gates.
|
||||
5. Track additional Playwright/E2E coverage separately; it is not a blocker
|
||||
4. Track additional Playwright/E2E coverage separately; it is not a blocker
|
||||
for the completed per-module coverage gate.
|
||||
|
||||
## Out of scope (deferred to follow-up tasks)
|
||||
@@ -147,12 +143,12 @@ Task #76 is completed. Keep the gate useful as a no-regression control:
|
||||
but not delta. A future PR can add baseline-fetch + delta rendering similar
|
||||
to bundle-budget.
|
||||
- **E2E coverage via Playwright** (5 golden-path flows) — tracked separately.
|
||||
- **Additional critical-path test writing** — see
|
||||
`docs/testing/coverage-sprint-backlog.md` for the ordered backlog.
|
||||
- **Additional critical-path test writing** — create a ticket with a measured gap from the current
|
||||
`scripts/coverage-targets.json` contract.
|
||||
|
||||
## References
|
||||
|
||||
- Gate runner: `scripts/verify-test-coverage.mjs`
|
||||
- Targets data: `scripts/coverage-targets.json`
|
||||
- Summary/badge: `scripts/coverage-summary.mjs`
|
||||
- CI: `.github/workflows/coverage.yml`, `.gitea/workflows/coverage.yml`
|
||||
- CI: `.gitea/workflows/coverage.yml`
|
||||
@@ -1,69 +0,0 @@
|
||||
# Architecture Closure Handoff Summary
|
||||
|
||||
> **Archived status surface:** this document is preserved as the official
|
||||
> Architecture Closure record. It remains referenced by static closure tests,
|
||||
> but current runtime truth still comes from the canonical sources listed
|
||||
> below.
|
||||
|
||||
## Closure scope
|
||||
|
||||
Architecture Closure closes as a documentation, manifest, and static-verification handoff contract for the architecture migration state. It does not claim that every runtime feature has already been extracted, removed, or rewritten; the `@hivegrid/web` React Router runtime in `apps/web/app` remains authoritative, with root scripts delegating to it, until later sequential tasks replace specific surfaces directly. The closure package ties together current boundary status, feature pruning decisions, manifest contracts, bundle evidence, and executor entrypoints so future agents can start from one consistent contract.
|
||||
|
||||
R001 is supported by complete Architecture Closure handoff coverage across the closure documents, feature manifests, static tests, and this summary. R002 is preserved by requiring sequential follow-up order and by avoiding any assumption that downstream feature slices can run in parallel or rely on parallel runtime changes.
|
||||
|
||||
## Canonical sources
|
||||
|
||||
Future agents should treat these files as the canonical Architecture Closure coverage set:
|
||||
|
||||
- `docs/architecture-migration-status.md` — current API, worker, package, pruning, URL-boundary, and bundle/performance handoff status.
|
||||
- `docs/feature-inventory.md` — human-readable Core, Plugin, and Removal inventory for boilerplate pruning.
|
||||
- `docs/feature-manifests/README.md` — executor-facing manifest contract and update rules.
|
||||
- `docs/feature-manifests/*.json` — machine-readable ownership, dependency, configuration, provider, worker, UAT, and pruning contracts.
|
||||
- `docs/agent-entrypoints.md` — first-stop routing for future feature, MVP import, admin-managed, worker-backed, UI, and Architecture Closure closure work.
|
||||
- `apps/web/app/application/architectureClosureDocs.test.ts` — static closure assertions for Architecture Closure source alignment, closure status, pruning actions, and S04 evidence.
|
||||
- `apps/web/app/application/featureManifests.test.ts` — manifest schema, dependency, secret ownership, worker declaration, config, and queue validation.
|
||||
|
||||
## Requirement coverage
|
||||
|
||||
- R001: covered by the aligned handoff sources above, the explicit Architecture Closure final closure status in `docs/architecture-migration-status.md`, the feature inventory, manifest README, JSON manifests, agent entrypoints, and static tests that guard those references.
|
||||
- R002: covered by the sequential follow-up order below. Do not assume parallel feature-slice execution, parallel runtime ownership, or hidden migration completion outside the documented source set.
|
||||
- R003 and pruning continuity: use `docs/feature-inventory.md` plus `docs/feature-manifests/*.json` before implementing, extracting, or removing features. Manifest classifications are action contracts (`core`, `plugin-candidate`, `remove-candidate`, or `mixed`), not permanent legacy-support promises.
|
||||
- S04 bundle/performance continuity: consult the bundle evidence referenced from `docs/architecture-migration-status.md`; optional production-build verification remains manual unless explicitly approved outside Auto-Mode.
|
||||
|
||||
## Full non-E2E gate commands
|
||||
|
||||
Run these focused non-E2E gates when closing or revalidating the Architecture Closure handoff contract:
|
||||
|
||||
```sh
|
||||
pnpm exec vitest run apps/web/app/application/architectureClosureDocs.test.ts apps/web/app/application/featureManifests.test.ts
|
||||
pnpm exec eslint --ext .tsx,.ts docs apps/web/app/application --max-warnings=0
|
||||
pnpm typecheck
|
||||
```
|
||||
|
||||
No E2E, browser, Cypress, or Playwright execution is part of this Auto-Mode closure gate.
|
||||
|
||||
## Sequential follow-up order
|
||||
|
||||
Future work should proceed in this order:
|
||||
|
||||
1. Read `docs/agent-entrypoints.md` and route the work to the relevant playbook before implementation.
|
||||
2. Read `docs/architecture-migration-status.md` for current boundary status and explicit skeleton-only versus runtime-wired ownership.
|
||||
3. Read `docs/feature-inventory.md` for the human-readable Core, Plugin, and Removal decision context.
|
||||
4. Read `docs/feature-manifests/README.md` and the matching `docs/feature-manifests/*.json` files.
|
||||
5. Update or add the relevant manifest contract before changing feature code when ownership, configuration, provider, worker, UAT, or pruning behavior changes.
|
||||
6. Implement one atomic migration, extraction, removal, or replacement step at a time, keeping the root runtime authoritative until that step directly replaces it.
|
||||
7. Re-run the relevant static tests and scoped lint/test commands for the changed surface before continuing to the next step.
|
||||
|
||||
This order intentionally preserves R002 by preventing downstream agents from treating separate migration slices as parallel prerequisites.
|
||||
|
||||
## Manual build note
|
||||
|
||||
`pnpm build` remains an optional manual follow-up for production bundle behavior and deployment confidence. It is not an Auto-Mode completion gate for this handoff task, and lack of an Auto-Mode build run does not weaken the static Architecture Closure closure contract.
|
||||
|
||||
## Future-agent start points
|
||||
|
||||
- For any new or migrated feature, start at `docs/agent-entrypoints.md`, then follow `docs/agent-playbooks/feature-integration.md` and the relevant manifest.
|
||||
- For plugin extraction or pruning work, start with `docs/feature-inventory.md`, `docs/feature-manifests/README.md`, and the matching `docs/feature-manifests/*.json` contract.
|
||||
- For architecture boundary questions, start with `docs/architecture-migration-status.md` and keep runtime-wired versus skeleton-only distinctions intact.
|
||||
- For closure verification, start with `apps/web/app/application/architectureClosureDocs.test.ts` and `apps/web/app/application/featureManifests.test.ts`.
|
||||
- For optional production bundle confidence, schedule manual `pnpm build` after the static non-E2E gate instead of treating it as an Auto-Mode requirement.
|
||||
@@ -0,0 +1,273 @@
|
||||
# Pilot-Readiness-Audit — 29.07.2026
|
||||
|
||||
## Kurzurteil
|
||||
|
||||
Der Pilot-Pfad ist nach diesem Lauf deutlich sicherer, konsistenter und besser
|
||||
prüfbar. Die gefundenen, risikoarm behebbaren Code-Risiken wurden nicht nur
|
||||
dokumentiert, sondern in 66 atomaren Code-Commits behoben. Damit ist trotz
|
||||
zusätzlicher Guards und Tests netto Code entfallen.
|
||||
|
||||
Ein blindes „alles launch-ready“ wäre dennoch falsch. Der produktionsnahe Lauf
|
||||
mit erzwungenem RLS hat einen echten Blocker im alten Workflow-Engine-Modul
|
||||
sichtbar gemacht: direkte Prisma-Zugriffe laufen ohne gebundenen
|
||||
Tenant-RLS-Kontext und sehen unter `hivegrid_app` die Readiness-Workflows nicht.
|
||||
Ist die Workflow Engine Teil des Piloten, muss das vor Launch typisiert und
|
||||
transaktional behoben werden. Ist sie nicht Pilot-Scope, muss sie für
|
||||
Pilot-Tenants explizit deaktiviert bleiben. Zusätzlich ist die operative
|
||||
Ticket-Wahrheit zwischen Plane, Ticket-Docs und alter Milestone-Planung
|
||||
auseinandergelaufen. Externe Staging-/Produktionsdienste wurden bewusst weder
|
||||
belastet noch mutiert.
|
||||
|
||||
## Lauf und Grenzen
|
||||
|
||||
- Laufzeitfenster: 29.07.2026, 13:17:18 bis 21:17:18 CEST
|
||||
- Basis: frisches `origin/main` bei
|
||||
`27fbea94e94ac9bbc7ddc157e23c2d4924d12829`
|
||||
- Branch: `audit/pilot-readiness-20260729`
|
||||
- isolierter Worktree:
|
||||
`/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud-pilot-readiness-20260729`
|
||||
- kein Push, Deploy, Plane-Schreibzugriff oder Eingriff in echte Server
|
||||
- lokale Einweg-Infrastruktur: PostgreSQL unter erzwungenem RLS mit der
|
||||
eingeschränkten Rolle `hivegrid_app`, Redis und Web-Runtime
|
||||
- vollständiger dateibasierter Inventar-/Static-Scan; manuelle Tiefenprüfung
|
||||
fokussierte anschließend die Pilot-Flows, Authentifizierung, Uploads,
|
||||
Berechtigungen, RLS, Kryptografie, Worker, Deployment und Hot Paths
|
||||
|
||||
Inventar zum Prüfzeitpunkt:
|
||||
|
||||
- 7.967 Repository-Dateien
|
||||
- 6.269 TypeScript-/TSX-Dateien
|
||||
- 814 Web-Routen, davon 141 API-Routen
|
||||
- 305 Worker-Dateien
|
||||
- 60 Prisma-Schema-Dateien
|
||||
- 205 Ticket-Docs
|
||||
- 170 tatsächlich vorhandene Milestone-Verzeichnisse
|
||||
|
||||
## Was behoben wurde
|
||||
|
||||
### Sicherheit
|
||||
|
||||
- Chunked Uploads erzwingen jetzt CSRF, prüfen Chunk-Integrität und akzeptieren
|
||||
keine ungebundenen Teilstücke.
|
||||
- Portal-Uploads sind während des Streamings begrenzt; unnötige
|
||||
Base64-/Buffer-Kopien wurden entfernt.
|
||||
- Aircall-Aufzeichnungsdownloads sind auf den erwarteten Anbieter-Host gepinnt.
|
||||
- Offene TOTP-Einschreibungen laufen ab.
|
||||
- Der Tenant-DEK-Cache ist begrenzt und verworfene Schlüssel werden
|
||||
überschrieben.
|
||||
- Interne Feedback-Servicefehler werden nicht mehr an Benutzer ausgegeben.
|
||||
- Runtime-Ressourcen müssen explizite CPU-/Memory-Hardcaps besitzen.
|
||||
- Verwundbare `tar`- und Valibot-Transitivabhängigkeiten wurden gepatcht.
|
||||
- Der Produktion-Audit meldet nur noch den geprüften, nicht anwendbaren React
|
||||
Router RSC-Hinweis; HiveGrid aktiviert den betroffenen RSC-Pfad nicht.
|
||||
|
||||
### Performance und Ressourcennutzung
|
||||
|
||||
- Dashboard-Charts werden wieder als Lazy-Chunk geladen; der Chart-Chunk liegt
|
||||
bei rund 5,1 KB statt im initialen Bundle.
|
||||
- Feature-Flag-Rollouts haben eine begrenzte Tenant-Fan-out-Größe.
|
||||
- Worker-Vorschauen und Portal-Uploads vermeiden große Buffer-Kopien.
|
||||
- Eine redundante Datenbank-Statusabfrage im Migrationspfad ist entfallen.
|
||||
- Der Tenant-Schlüsselcache besitzt eine harte Obergrenze.
|
||||
|
||||
### Toter und irreführender Code
|
||||
|
||||
- ungenutzter Chart-Wrapper entfernt
|
||||
- tote TOTP-Platzhalterroute entfernt
|
||||
- pensionierte AI-Upload- und Completion-Clients/-Routen entfernt
|
||||
- veraltete Route- und Readiness-Verweise auf die entfernten Flächen bereinigt
|
||||
- keine verbotenen US-Provider-Imports gefunden
|
||||
|
||||
### Pilot-Flows und Bedienbarkeit
|
||||
|
||||
- Ein echter Routing-Konflikt bei `/select-tenant` wurde behoben: Die
|
||||
Admin-Host-Aliasroute überschattete zuvor den App-Flow und konnte Benutzer
|
||||
nach erfolgreichem Login wieder auf die Anmeldung schicken.
|
||||
- Auth-/Recovery-Flows bleiben auf dem richtigen Host und zeigen aktuelle
|
||||
Passwortanforderungen sowie semantisch zugeordnete Fehler.
|
||||
- Mobile Sidebar und Accordion verhalten sich jetzt semantisch und schließen
|
||||
nach Navigation.
|
||||
- Form-, Menü-, Switch-, Select-, Profil- und Dialog-Controls erhielten
|
||||
zugängliche Namen; mehrere Kontrastfehler wurden behoben.
|
||||
- Der A11y-Coverage-Gate prüft wieder die aktuellen Billing-, API-Key-, Audit-,
|
||||
Profil- und Readiness-Smokes statt pensionierter UI-IDs und Flow-Namen.
|
||||
- Einstellungen, Compliance, Billing, API-Keys, Plugins, Privacy und
|
||||
Notifications verlinken wieder auf die kanonischen Routen.
|
||||
- Ein Projektboard ohne Pipeline mutiert nicht länger während eines GETs,
|
||||
sondern zeigt den vorhandenen Empty-State. Die Readiness-Fixture erzeugt die
|
||||
benötigte Pipeline deterministisch.
|
||||
- Profil-Mutationen lesen den angemeldeten Benutzer jetzt im gebundenen
|
||||
User-/Tenant-RLS-Kontext statt über einen kontextlosen Prisma-Zugriff.
|
||||
- Form-Builder-Liste, Detail, Exporte und Mutationen laufen vollständig im
|
||||
authentifizierten RLS-Kontext.
|
||||
- Der Plugin-Capability-Audit bindet Plugin- und Audit-Reads an denselben
|
||||
nachgewiesenen Tenant-/User-Kontext.
|
||||
- Onboarding-, Billing- und Operator-Fixtures bilden die aktuellen
|
||||
Produktionsverträge ab und schlagen bei fehlenden Voraussetzungen geschlossen
|
||||
fehl.
|
||||
|
||||
## Verifikation
|
||||
|
||||
| Prüffeld | Ergebnis |
|
||||
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| TypeScript | final grün |
|
||||
| ESLint, keine Warnungen | final grün |
|
||||
| Core-Unit-/Komponententests | final grün; 1.144 Dateien, 7.914 grün, 60 erwartete Skips |
|
||||
| Erzwungene RLS-Verträge | 372/372 Modelle grün |
|
||||
| Release-Readiness | 253 Modelle und 25 Artefakte grün |
|
||||
| Frische Datenbank | 17 Migrationen aus leerer DB, Status sauber |
|
||||
| Route-/Sidebar-/Source-Health-Gates | grün |
|
||||
| Production-Build | grün |
|
||||
| Bundle-Budget | Initial-Payload, Kompression, Lazy-Runtime, Gesamtgröße und alle Einzelrouten grün; zwei bereits auf `main` rote Rohsummen bleiben offen |
|
||||
| Runtime-Closures | grün nach vollständigem Build |
|
||||
| Produktionsabhängigkeiten | keine anwendbare High-/Critical-Lücke |
|
||||
| Chromium-E2E, vollständiger RLS-Lauf | 185 grün, 43 erwartete Skips, 31 rot; davon 23 gebündelt auf die Workflow Engine |
|
||||
| Auth-/Account-Production-Smoke | 20 grün, 4 explizit umgebungsabhängig übersprungen |
|
||||
| Production-Service-Worker | 2/2 grün |
|
||||
| Kritischer Workflow-RLS-Recheck | 7/7 reproduzierbar rot; Redirect zum Dashboard nach DB-Fehler |
|
||||
| lokaler Production-HTTP-Lasttest | `/healthz`: 5.000/5.000 bei c=100, 0 Fehler, 10.946,52 req/s, p95 17 ms, p99 29 ms; `/login`: 1.000/1.000 bei c=50, 0 Fehler, 304,31 req/s, p95 174 ms, p99 195 ms |
|
||||
|
||||
Die produktionsgebundenen Service-Worker-Tests erkennen nun korrekt die
|
||||
Vite-Dev-Runtime und werden dort bewusst übersprungen. Sie müssen gegen den
|
||||
gebauten Stand laufen; der anschließende lokale Production-Runtime-Lauf hat
|
||||
beide Tests grün bestätigt.
|
||||
|
||||
Der Bundle-Gate-Vergleich wurde zusätzlich in einem separaten Worktree direkt
|
||||
gegen den unveränderten Basis-Commit gebaut. Bereits `main` überschreitet
|
||||
`manifest_js` um 0,4 % und `application_js` um 5,7 %. Der Audit-Branch reduziert
|
||||
gegenüber dieser Basis die rohe Anwendungssumme um 4.813 Bytes, CSS um 2.283
|
||||
Bytes sowie den initialen Gzip-/Brotli-Payload um 85/70 Bytes; das Manifest
|
||||
wächst um 598 Bytes. Budgets wurden bewusst nicht aufgeweicht. Die zwei roten
|
||||
Rohsummen sind somit ein vorbestehender CI-/Budget-Nachzug, keine neu
|
||||
eingeführte Gesamtgrößenregression.
|
||||
|
||||
## Validierte User-Flows
|
||||
|
||||
Mit realer lokaler PostgreSQL-Datenbank, eingeschränkter App-Rolle, erzwungenem
|
||||
RLS und anschließend auch dem gebauten Production-Server wurden unter anderem
|
||||
folgende Pfade ausgeführt:
|
||||
|
||||
- Passwort-Login, Recovery und Registrierungsfehler
|
||||
- Tenant-Auswahl und Single-Tenant-Einstieg
|
||||
- Admin-Login/Host-Isolation und Operator-Dashboard
|
||||
- Dashboard und mobile Hauptnavigation
|
||||
- Profil, Passwortdialog, MFA-Einstieg und Sessions
|
||||
- Billing, Abo-Übersicht, Rechnungen und Onboarding
|
||||
- Notification-Center und Notification-Einstellungen
|
||||
- API-Key-Einstellungen und Anlagevertrag ohne persistierende Mutation
|
||||
- Workspace-Governance und Compliance
|
||||
- Plugin-Katalog, Detail, Lifecycle und Audit
|
||||
- Privacy-Hub und leere Privacy-Teilflächen
|
||||
- Lead-Anlage
|
||||
- Projektboard einschließlich fehlender Pipeline
|
||||
- Production-Service-Worker einschließlich kontrollierter Übernahme
|
||||
|
||||
Der komplette Chromium-Lauf ergab 185 grüne Tests, 43 explizite Skips und 31
|
||||
Fehler. Zwei UI-Vertragsdrifts in Workspace-Governance und dem neuen
|
||||
Office-/Field-Seat-Billing wurden anschließend korrigiert und gezielt grün
|
||||
verifiziert. Vier serielle Auth-Fehler waren im isolierten Production-Recheck
|
||||
nicht reproduzierbar: dort liefen 20 Auth-/Account-Tests grün, vier
|
||||
umgebungsabhängige Mutationsfälle wurden korrekt übersprungen. Zwei alte
|
||||
Admin-Tests erwarten zwingend die Login-Seite und sind deshalb mit einem
|
||||
vor-authentifizierten Admin-State nicht kompatibel; der native
|
||||
Platform-Lead-Flow selbst lief mit diesem State unter `hivegrid_app` grün.
|
||||
|
||||
Die verbleibende belastbare Fehlergruppe ist die Workflow Engine. 23 Tests des
|
||||
Gesamtlaufs und alle sieben gezielten Production-Rechecks wurden zum Dashboard
|
||||
umgeleitet. Parallel protokollierte die Runtime
|
||||
`workflow.findFirstOrThrow`-Datenbankfehler. Die Legacy-DB-Layer unter
|
||||
`apps/web/app/modules/workflowEngine/**` verwenden direkte `db.workflow*`-
|
||||
Aufrufe, ohne `runWithRlsContext()` oder `withTenantRLS()`. Lokal mit
|
||||
`RLS_RUNTIME_MODE=off` bleibt dieser Fehler unsichtbar; genau deshalb ist er
|
||||
launchrelevant. Die statische Inventur zählt 70 direkte Zugriffsstellen in elf
|
||||
Produktionsdateien und keinen RLS-Wrapper innerhalb des Moduls. Die drei
|
||||
internen Trigger-/Execution-Endpunkte binden den RLS-Kontext bereits; der Bruch
|
||||
liegt im nachgelagerten Legacy-Modul. Ein eiliger Teil-Fix wäre riskant, weil
|
||||
Reads, Mutationen, Blocks, Variablen, Credentials und Executions gemeinsam
|
||||
transaktional nachgezogen werden müssen.
|
||||
|
||||
Eine abschließende Direktzugriffs-Heuristik über alle Route-Dateien zeigt nach
|
||||
den Profil-, Form- und Plugin-Korrekturen keinen tenant-seitigen App-Route-Read
|
||||
mehr, der `db` direkt importiert, aber keinen RLS-Kontext/-Scope referenziert.
|
||||
Die verbleibenden Treffer sind Admin-/Operator- und Health-Routen; deren
|
||||
separate Identitätsgrenzen wurden in den zugehörigen Runtime-Smokes geprüft.
|
||||
|
||||
Bewusst nicht als lokal bewiesen gelten echte Mailjet-/Mollie-/Aircall- und
|
||||
Coolify-Endpunkte sowie Provider-Webhooks. Sie wurden weder gefälscht als
|
||||
„grün“ ausgegeben noch extern belastet.
|
||||
|
||||
## Ticket- und Planungsabgleich
|
||||
|
||||
Read-only aus Plane:
|
||||
|
||||
- 208 Issues insgesamt
|
||||
- 108 offene Issues
|
||||
- 72 offene Issues über Zieldatum, 22 ohne Zieldatum
|
||||
- 8 explizit blockierte Issues:
|
||||
`AK-P19`, `EXT-13`, `VA-P23`, `VR-P22b`, `VEXT-6`, `VH-1`, `VN-1`, `VN-2`
|
||||
- Statusverteilung: 83 Done, 17 Cancelled, 61 Backlog, 8 Todo,
|
||||
15 In Progress, 5 In Review, 11 Ready for Review
|
||||
|
||||
Abweichungen:
|
||||
|
||||
- `AGENTS.md` nennt noch 157 Ticket-Docs; vorhanden sind 205.
|
||||
- 13 aktive Tickets mit Working-ID haben keinen Doc-Link; 16 Ticket-Docs haben
|
||||
keine Plane-Working-ID.
|
||||
- 21 als Done markierte Ticket-Docs wirken im Dokument noch geplant,
|
||||
in Arbeit oder statuslos.
|
||||
- 9 cancelte Tickets wirken in den Docs noch geplant oder statuslos.
|
||||
- Von 77 auswertbaren Done-Docs haben 59 vollständige DoD-Häkchen, 13 offene
|
||||
DoD-Punkte und 5 keine maschinenlesbare DoD.
|
||||
- `AK-P14b` steht in Plane auf Done, die Doc weist 6/7 DoD, also rund 86 %, aus.
|
||||
- 17 Done-Docs besitzen keine Umsetzungsnotiz.
|
||||
- 46 Docs markieren einen Design-Nachzug, aber Plane hat 39 entsprechende
|
||||
Labels; 8 sind nur in der Doc markiert, `R-P12b` nur in Plane.
|
||||
- Alle 41 aktiven Screen-Tickets sind noch nicht Done.
|
||||
- `R-UX1` ist aktiv, besitzt aber keine Ticket-Doc.
|
||||
- `R-P13` steht in Plane auf Done, obwohl AD-26 den v1-KI-Layer gestrichen hat.
|
||||
|
||||
Die Dateien damalige Planungsstatusdatei, `ROADMAP*.md`, `REQUIREMENTS.md` und
|
||||
`SPRINT-DAYPLAN.md` enthalten zusätzlich erkennbaren Zeit-/Status-Drift. Dieser
|
||||
Lauf hat die externen Statusdaten bewusst nicht eigenmächtig umgeschrieben.
|
||||
|
||||
## Infrastruktur- und Belastungsbefund
|
||||
|
||||
- Deploy-, Runtime-, Non-root-, Secret-, Pin- und Hardcap-Verträge sind statisch
|
||||
grün.
|
||||
- Eine leere lokale Datenbank lässt sich vollständig migrieren und mit der
|
||||
eingeschränkten Runtime-Rolle betreiben.
|
||||
- RLS wurde nicht durch Mocks „bewiesen“, sondern in der laufenden App mit der
|
||||
Rolle `hivegrid_app` validiert. Dadurch wurde der Workflow-Engine-Fehler
|
||||
überhaupt erst sichtbar.
|
||||
- Die Production-Konfiguration bricht bei fehlenden Pflicht-URLs, Secrets,
|
||||
Storage-Parametern und Revision fail-closed ab.
|
||||
- Der lokale Production-Load-Smoke lieferte bei 6.000 Requests und erhöhter
|
||||
Parallelität keinen HTTP-Fehler. Die Werte enthalten weder TLS noch
|
||||
Netzwerk-/Providerlatenz und sind daher nur ein Regressionssignal.
|
||||
- Externe Estate-Dienste wurden nicht belastet. Das wäre ohne abgestimmtes
|
||||
Wartungsfenster kein risikoarmer Audit-Schritt.
|
||||
- Der lokale HTTP-Lasttest dient nur als Regressionssignal; er ist keine
|
||||
Kapazitätszusage für Hetzner/Coolify.
|
||||
|
||||
## Bereinigung der alten OQ-/Milestone-Planung
|
||||
|
||||
**Erledigt am 2026-08-02.** Plane ist die operative Status-, Ownership- und
|
||||
Dependency-Quelle; `.planning/ticket-docs/<ID>.md` ist die ausführbare Bau- und
|
||||
DoD-Quelle. Die drei noch fachlich referenzierten Altverträge wurden vor dem
|
||||
Löschen übernommen: KWP nach `.planning/KWP-API-CONTRACT.md`, Plattform-Leads
|
||||
nach `R-LEADS`/`VA-P28b` und SHK-Provisionierung nach `R-CR1`/`R-P20b`.
|
||||
|
||||
## Prioritäten vor dem Piloten
|
||||
|
||||
1. Workflow Engine vollständig an den RLS-Kontext anbinden und alle 23
|
||||
betroffenen Smokes grün machen; alternativ die Funktion für Pilot-Tenants
|
||||
nachweislich deaktivieren.
|
||||
2. Einen gebauten Staging-Stand unter scharfem RLS einmal durch den
|
||||
Pilot-Smoke und die echten Provider-Callbacks führen.
|
||||
3. Die 13 Done-Docs mit offenen DoD-Punkten und die 17 Done-Docs ohne
|
||||
Umsetzungsnotiz fachlich bestätigen oder in Plane zurückstufen.
|
||||
4. Die acht blockierten Tickets mit Owner, nächster Aktion und realistischem
|
||||
Termin versehen; die 72 überfälligen offenen Tickets triagieren.
|
||||
5. Den Design-Nachzug zwischen Docs und Plane einmalig synchronisieren.
|
||||
6. Die alte Milestone-Planung nach obigem Verfahren einfrieren, statt sie als
|
||||
parallele Projektsteuerung weiterzuführen.
|
||||
@@ -44,8 +44,28 @@ does NOT run the strength policy. Enforcing 12-char + class requirements
|
||||
there would lock out every user with a pre-policy password instead of
|
||||
prompting them to rotate. The plain "is the field a non-empty 4+ char
|
||||
string" presence-check in `UserValidationUtils.validatePassword` is what
|
||||
guards the login form. The dashboard-banner soft-check from the detail-MD
|
||||
is a follow-up.
|
||||
guards the login form.
|
||||
|
||||
## Soft-banner (dashboard nudge)
|
||||
|
||||
The dashboard-banner soft-check is shipped: login runs the policy in
|
||||
non-throwing mode against the submitted plaintext and stores a
|
||||
`passwordPolicyOutdated` session flag. The tenant layout
|
||||
(`apps/web/app/routes/app.$tenant.tsx`) combines that flag with the
|
||||
`pwPolicyRemindAfter` snooze cookie via
|
||||
`apps/web/app/services/auth/password-policy-banner.server.ts` and renders
|
||||
`PasswordPolicyBanner` when the policy is not met.
|
||||
|
||||
The "Remind me in 7 days" button POSTs to
|
||||
`/auth/password-policy-remind`
|
||||
(`apps/web/app/routes/auth.password-policy-remind.tsx`), which sets the
|
||||
snooze cookie for 7 days. The route intentionally lives under `/auth/*`
|
||||
(a `publicWebRoutePrefixes` entry): the host-routing runtime
|
||||
(`server/host-routing-runtime.ts`, `isRemovedLegacyRoute`) rejects every
|
||||
other `/api/*` path on the tenant app host with 404, so an `/api/...`
|
||||
resource route would be unreachable from the banner. The snooze is a pure
|
||||
UX cookie per browser — deliberately not persisted in the database and
|
||||
not a security control.
|
||||
|
||||
## HIBP fail-open
|
||||
|
||||
|
||||
+95
@@ -0,0 +1,95 @@
|
||||
<!-- markdownlint-disable MD013 -->
|
||||
|
||||
# Workflow-Engine: Laufzeit- und Tool-Matrix
|
||||
|
||||
**Stand:** 2026-08-01
|
||||
|
||||
**Scope:** lokal testbare Phase-1-Automationen; KWP-Schreibzugriffe sind ausdrücklich ausgenommen.
|
||||
|
||||
Diese Matrix trennt drei Zustände, die im Editor nicht miteinander verwechselt werden dürfen:
|
||||
|
||||
- **Aktiv:** Der Baustein besitzt einen echten Executor und darf in aktivierbaren Regeln verwendet werden.
|
||||
- **Vorbereitet:** Der Baustein ist im Katalog sichtbar, aber `extension_slot` und damit fail-closed nicht aktivierbar.
|
||||
- **Ausgenommen:** Kein Phase-1-Tool; wird nicht still über einen Platzhalter-Executor simuliert.
|
||||
|
||||
## Ergebnis der Verifikation
|
||||
|
||||
| Ebene | Ergebnis | Beleg |
|
||||
| --- | ---: | --- |
|
||||
| Katalog/Editor/Executor/Reverse/Trigger/Worker | 316 Tests grün, 9 opt-in DB-Tests übersprungen | 21 fokussierte Vitest-Suiten |
|
||||
| Neuer Core-Executor gegen echte DB | 4/4 grün | frische PostgreSQL-DB, RLS-Rollen über `scripts/provision-rls-roles.mjs`, 30/30 Migrationen |
|
||||
| Bestehende Workflow-Outbox-Brücke gegen echte DB | 5/5 grün | dieselbe frische DB, seriell nach dem Core-Executor |
|
||||
| Aktive Core-Katalogeinträge gegen Dispatcher | vollständig | Registry-Test gleicht aktive Core-Nodes mit `AUTOMATION_CORE_EXECUTOR_NODE_TYPES` ab |
|
||||
| Aktive Portal-Katalogeinträge gegen Dispatcher | vollständig | Registry-/Worker-Tests gleichen sie mit `PORTAL_AUTOMATION_ACTION_PERMISSIONS` ab |
|
||||
| Trigger gegen Producer/Scheduler | vollständig | `AUTOMATION_TRIGGERS_WITHOUT_EMITTER` ist leer und vertraglich getestet |
|
||||
|
||||
Die DB-Tests beweisen Migration, RLS-Kontext, Persistenz, Claims, Step-Outputs, Delay/Resume und Outbox-Verarbeitung. Eine interaktive Browser-Abnahme war in dieser Agent-Oberfläche nicht verfügbar; Picker und Konfiguration sind deshalb durch Component-/Service-Tests, nicht durch behauptete Browser-Klicks belegt.
|
||||
|
||||
## Aktive Bausteine
|
||||
|
||||
### Core-Executor
|
||||
|
||||
| Bausteine | Echte Wirkung | Reverse/Output |
|
||||
| --- | --- | --- |
|
||||
| `crm.update_kontakt` | typisierte Kontaktfelder ändern | Snapshot; rückgängig |
|
||||
| `crm.add_tag`, `crm.remove_tag` | Kontakt-Tag anlegen/entfernen | vorheriger Zustand; rückgängig |
|
||||
| `crm.assign_kontakt` | Kontakt einem Tenant-User zuweisen | vorherige Zuweisung; rückgängig |
|
||||
| `crm.create_note` | Kontakt-Aktivität/Notiz anlegen | append-only; bewusst nicht rückgängig |
|
||||
| `lead.assign`, `lead.set_status` | Lead-Zuweisung bzw. Status ändern und Folge-Trigger publizieren | vorheriger Zustand; rückgängig |
|
||||
| `task.create`, `task.assign` | Aufgabe anlegen bzw. vorhandene Aufgabe zuweisen | Task-ID/Snapshot; rückgängig |
|
||||
| `notification.send` | persistente In-App-Benachrichtigung erzeugen | Empfänger dokumentiert; nicht zurückziehbar |
|
||||
| `email.send_transactional` | `mail.transactional.send` durabel in die Mail-Outbox schreiben | Empfänger dokumentiert; nicht zurückziehbar |
|
||||
| `chat.post_message` | echte Teamchat-Nachricht über den Chat-Service senden | Message-ID; nicht zurückziehbar |
|
||||
| `http.request` | SSRF- und Redirect-geschützten HTTP-Aufruf ausführen | Status/Response-Metadaten; nicht rückgängig |
|
||||
| `condition.if_else` | genau den True- oder False-Zweig freigeben | Entscheidung persistiert |
|
||||
| `delay.wait` | Lauf durabel bis zum Zielzeitpunkt pausieren und wieder aufnehmen | Waiting-/Resume-Zustand |
|
||||
| `flow.parallel`, `flow.merge` | parallele Zweige freigeben und anschließend synchronisieren | DAG-Zustand |
|
||||
|
||||
`loop.for_each` ist im Executor vollständig implementiert und mit allen Datenquellen sowie echter DB getestet. Der Baustein bleibt bis zu einer eigenen Produktfreigabe als `extension_slot` gesperrt; die Runtime-Reife allein erweitert den aktiven Ticket-Scope nicht.
|
||||
|
||||
### Portal-Executor
|
||||
|
||||
Die getrennte Portal-Familie führt `portal.invite_user`, `portal.grant_access`, `portal.revoke_access`, `portal.release_document`, `portal.send_status_mail` und `portal.disable_user` aus. Der Editor verhindert Misch-Flows aus Portal- und Core-Bausteinen; beide Worker lehnen eine falsche Familie zusätzlich fail-closed ab.
|
||||
|
||||
### Trigger
|
||||
|
||||
Alle 27 aktiven Trigger im Katalog besitzen heute einen Producer, eine öffentliche Inbound-Brücke oder einen Scheduler. Dazu gehören CRM, Lead, Projekt/Sales, Formular, E-Mail/Bounce, Booking, Kalender, Zeitplan, Deadline, Webhook und Portal. Event-Verträge, Tenant-Zuordnung, Duplikatunterdrückung und Rule-Matching werden vor dem Executor validiert.
|
||||
|
||||
## Vorbereitete Bausteine und benötigte Tools
|
||||
|
||||
Ein vorbereiteter Baustein darf erst auf `active` wechseln, wenn sein Tool alle folgenden Verträge erfüllt: Tenant-RLS, Berechtigungsprüfung, stabile Idempotenz, Domain-Invarianten, Audit/Activity, notwendige Search-/Notification-Side-Effects, typisiertes Output-Schema, Reverse-Klassifizierung und Tests gegen echte PostgreSQL-Persistenz.
|
||||
|
||||
| Priorität | Vorbereitete Bausteine | Wiederverwendbarer Bestand | Noch zu bauendes Tool / Entscheidung |
|
||||
| ---: | --- | --- | --- |
|
||||
| 1 | `lead.convert_to_project` | `createProjectFromQualifiedLead` in `projectService.server.ts`; bereits idempotent, projekt-zentrisch, mit Triggern, Suche, Chat-Sync und Aggregaten | **Worker-sicheres `ProjectCommandGateway.convertQualifiedLead`** aus der Web-Schicht extrahieren; Actor-/Permission-Kontext definieren. Kontakt wird nur explizit, über Lead-Link oder E-Mail-Match verknüpft, nicht blind neu erzeugt. |
|
||||
| 1 | `sales.create_project`, `projects.create_project`, `sales.change_stage`, `projects.change_stage`, `sales.change_volume`, `sales.assign_project`, `sales.move_pipeline`, `projects.move_pipeline` | `createProject`, `moveProjectStage`, `updateProjectStammdaten`, `moveProjectToPipeline` besitzen die fachlichen Guards und Side-Effects | **Worker-sicheres `ProjectCommandGateway`** mit Idempotenz und automation-spezifischen Outputs/Reverse-Plänen. Die vorhandenen Services dürfen nicht im Worker dupliziert oder per Direktimport aus `apps/web` verwendet werden. |
|
||||
| 1 | `sales.add_project_tag` | typisierte Projektbasis vorhanden; kein kanonischer Projekt-Tag-Writer gefunden | **`ProjectTagCommand`** mit tenant-geprüfter Tag-Registry, Add-Dedupe, Activity/Search und Reverse. |
|
||||
| 1 | `projects.add_member` | `addProjectMember` prüft Tenant-User/-Gruppe und synchronisiert den Projektchat | **Worker-Fassade plus idempotenter Membership-Key** und Output für Remove-Reverse. |
|
||||
| 1 | `projects.create_task` | `createIdempotentTaskFromSource` und Projekt-Link-Felder existieren | **`ProjectTaskCommand`** für eine idempotente, mit dem Projekt verknüpfte Aufgabe samt User-/Gruppenauflösung. |
|
||||
| 1 | `projects.create_appointment` | `createProjectAppointment` schreibt den typisierten `ProjektTermin` und Activity | **`ProjectAppointmentCommand`** mit Idempotenz, Projekt-/Kalender-Event-Vertrag und Reverse-Output. |
|
||||
| 1 | `projects.start_acceptance` | `submitAcceptanceProtocol` schließt eine Abnahme ab; kein fachlich passender Start-/Draft-Befehl vorhanden | **`AcceptanceDraftCommand.start`** definieren. Nicht den Submit-Service mit erfundenen Signaturen missbrauchen. |
|
||||
| Entscheidung | `projects.create_from_won_sales` | AD-20: Sales/Deal/Auftrag sind Typen bzw. Zustände desselben `Projekt`-Kerns; kein Won-Handoff | **Nicht als Create-Writer bauen.** Block entfernen oder in eine echte Typ-/Stage-Transition umbenennen und dafür einen dokumentierten Product-/Entity-Model-Entscheid treffen. |
|
||||
| 2 | `notification.send_push` | Web-Push-Provider und Retry-Job existieren für Telephony; Foundation-Kanäle kennen nur `IN_APP`/`EMAIL` | **Generischer PWA-Push-Kanal:** Subscription-Registrierung pro Tenant-User, `PUSH`-Preference/Delivery, Worker-Routing zum vorhandenen Provider, Invalid-Subscription-Cleanup. |
|
||||
| 2 | `webhook.send_signed` | Public-API-Webhooks besitzen HMAC-Header, Delivery-Persistenz und SSRF-Schutz | **Credential-basiertes `SignedWebhookCommand`** für frei konfigurierte Ziele. Secrets bleiben verschlüsselt und nie im Rule-JSON; benötigt Retry-/Delivery-Output und stabile Idempotenz. |
|
||||
| 2 | `calendar.create_event`, `calendar.update_event` | Provider-neutraler `CalendarAdapter` und Google-Implementierung können schreiben; Connection/Token-Refresh existiert | **`CalendarWriteService`**: schreibbare Verbindung/Kalender wählen, Tokens erneuern, lokale `CalendarEvent`-Zuordnung persistieren, ETag-Konflikte behandeln, idempotent schreiben. Provider-I/O darf nicht in einer langen DB-Transaktion liegen. |
|
||||
| 2 | `files.create_from_url` | S3-/File-Service und fail-closed ClamAV-Pipeline existieren; Billing hat nur einen spezialisierten SSRF-geschützten Download | **`RemoteFileIngestService`**: SSRF- und Redirect-geschützter Download, harte Größen-/Content-Type-Grenzen, ClamAV vor Freigabe, Storage/File-Zeile, Entity-Link, Idempotenz und Cleanup. |
|
||||
| Ausgenommen | `kwp.push_project` | Slot bleibt vorhanden | KWP-Writes sind für diesen Auftrag ausdrücklich ausgenommen. Kein Fake-Handler. |
|
||||
|
||||
## Verbleibende gemeinsame Produktionswerkzeuge
|
||||
|
||||
Diese Punkte betreffen bereits aktive Bausteine. Die Hauptwirkung ist lokal verifiziert, für vollständige Parität mit manuellen UI-Aktionen fehlen aber noch gemeinsame Domain-Werkzeuge:
|
||||
|
||||
1. **Domain-Side-Effect-Fassade für Worker-Aktionen:** Kontakt-, Lead- und Task-Mutationen müssen Search-Projektion, Activity und weitere fachliche Side-Effects über dieselben Commands wie die Web-App auslösen. Direkte Prisma-Writes funktionieren, können heute aber z. B. einen Suchindex bis zum nächsten Rebuild veralten lassen.
|
||||
2. **Tenant-Principal-Resolver:** `task.create`, `task.assign` und `notification.send` unterstützen derzeit nur die tatsächlich implementierten Owner/Creator-Pfade. Für Mitarbeiter, Teams und Gruppen braucht es einen gemeinsamen permission-geprüften Resolver statt Design-Platzhaltern.
|
||||
3. **Versionierter E-Mail-Template-Resolver:** Dynamische Platzhalter funktionieren, aber `email.send_transactional` nimmt noch Betreff/Text direkt aus der Regel. Für den vollständigen Phase-1-Vertrag fehlen Template-ID, Version, erlaubte Platzhalter und Preview/Validation.
|
||||
4. **HTTP-Credential-/Header-Resolver:** `http.request` ist funktional und SSRF-geschützt, unterstützt aber noch keine sicher gespeicherten dynamischen Header. Auth-Secrets dürfen nicht in der Flow-Konfiguration liegen.
|
||||
|
||||
## Aktivierungs-Gate für neue Tools
|
||||
|
||||
Vor dem Umschalten eines Slots auf `active` müssen mindestens folgende Nachweise im selben atomaren Change liegen:
|
||||
|
||||
1. Handler im passenden Executor und maschinenlesbarer Eintrag im Executor-Vertrag.
|
||||
2. Config- und Output-Schema inklusive Klartextfehlern.
|
||||
3. Idempotenz- und Retry-Test, Permission-/RLS-Test sowie echter PostgreSQL-Integrationstest.
|
||||
4. Reverse-Handler oder explizite, im Lauf sichtbare Kennzeichnung als nicht rückziehbar.
|
||||
5. Editor-Descriptor, i18n und Component-Test; keine Aktivierung eines nur sichtbaren Placeholders.
|
||||
@@ -1,38 +0,0 @@
|
||||
# Backlog
|
||||
|
||||
Date: 2026-05-28
|
||||
|
||||
This file captures the narrow optional product-module extraction backlog from the core-pruning slice. It is not the live global backlog. For current HiveGrid backlog truth, use `.planning/ticket-docs/`, `.planning/ROADMAP.md`, `.planning/ROADMAP-V2.md`, and Plane. For CDN rollout notes, use `docs/ops/asset-cdn.md`.
|
||||
|
||||
## Optional Product Module Extraction
|
||||
|
||||
Status: backlogged.
|
||||
|
||||
Decision: keep optional Product Core surfaces in the repository for now. Forms and Surveys are excluded because they were selected for removal, not extraction.
|
||||
|
||||
Scope parked here:
|
||||
|
||||
- Workflow Engine
|
||||
- Knowledge Base and Widgets
|
||||
- Portals and Sites
|
||||
- Email Marketing
|
||||
- Analytics and Metrics
|
||||
- Notifications UI and flows
|
||||
- AI, Prompt Builder, and MCP surfaces
|
||||
|
||||
Why this is parked: these modules are useful boilerplate surfaces, but they increase route inventory, bundle manifest size, schema surface, worker ownership, i18n surface, and agent onboarding complexity.
|
||||
|
||||
Revisit when one of these triggers happens:
|
||||
|
||||
- route manifest size becomes the main deploy or runtime cost;
|
||||
- a plugin/module registration system is ready;
|
||||
- the product decides which optional modules belong in the default starter;
|
||||
- a customer-facing template needs a smaller core distribution.
|
||||
|
||||
Acceptance criteria for future extraction:
|
||||
|
||||
- each extracted module has a feature manifest and ownership doc;
|
||||
- routes register through a module/plugin boundary instead of unconditional route discovery;
|
||||
- DB schema, queue jobs, workers, i18n keys, permissions, and seeds have clear module ownership;
|
||||
- disabled modules do not ship route or bundle surface by default;
|
||||
- verification gates cover enabled and disabled module states.
|
||||
@@ -1,135 +0,0 @@
|
||||
# Boilerplate Readiness
|
||||
|
||||
This page enumerates the verification gates that protect the boilerplate's
|
||||
"safe to fork and build on" contract. The default CI lane is asserted by
|
||||
`.gitea/workflows/ci.yml`; heavier gates such as coverage, Lighthouse,
|
||||
Storybook, a11y, and deploy verification may live in dedicated workflow files.
|
||||
Failing a required gate blocks the PR or deployment lane that owns it — there
|
||||
is no silent override mode.
|
||||
|
||||
## How to read this page
|
||||
|
||||
Each section names a gate, what it enforces, the canonical command, and the
|
||||
file(s) that contain the contract. Gates marked **anti-regression** keep the
|
||||
current floor; they only allow improvements, never regressions. Gates marked
|
||||
**hard contract** assert structural invariants that must always hold.
|
||||
|
||||
## Onboarding & branding
|
||||
|
||||
| Gate | Contract | Command |
|
||||
| --- | --- | --- |
|
||||
| Brand env layer (hard) | All user-facing brand strings are overridable via `BRAND_*` env vars in `packages/config/src/catalog.ts`. `packages/brand/src/env.ts` is the source-of-truth loader. | `pnpm --filter @hivegrid/brand test` |
|
||||
| Infra-host parametrization (hard) | Gitea runner label, registry host, image prefix, DB user/name read from `scripts/infra-config.mjs` with `HIVEGRID_*` env overrides — forks can sed-replace strings and set vars without rewriting `verify-gitea-*-workflow.mjs`. | `pnpm run verify:gitea-ci-workflow && pnpm run verify:deploy-workflow` |
|
||||
| `.env.example` drift (hard) | Every key in `.env.{example,local.example,production.example,fly.example,test}` exists in the catalog. | `pnpm exec vitest run packages/config/src/env-examples.test.ts` |
|
||||
|
||||
## Internationalization
|
||||
|
||||
| Gate | Contract | Command |
|
||||
| --- | --- | --- |
|
||||
| DE/EN namespace parity (hard) | All registered `i18nNamespaces` stay in lockstep across `de` and `en`, including app, auth, billing, CRM, settings, email marketing, mail, and error namespaces. | `pnpm run verify:i18n` |
|
||||
| Hardcoded user-facing strings (anti-regression) | `brand-literal`, `jsx-text`, `user-facing-prop-literal`, and `user-facing-response-literal` counts may only decrease over the ratcheted baseline; current zero-floor categories must stay at zero. | `node scripts/verify-hardcoded-strings.mjs` |
|
||||
| RTL/direction (hard) | `getDirection(locale)` covers known RTL languages; `isRTL` matches. | `pnpm --filter @hivegrid/i18n test` |
|
||||
| Mail templates (hard) | `renderTransactionalEmail(template, props)` (React-Email) renders subject + body for every supported template. Host-app translator hooks are reserved for a future i18n pass; templates emit English copy directly. | `pnpm --filter @hivegrid/mail test` |
|
||||
|
||||
## Security
|
||||
|
||||
| Gate | Contract | Command |
|
||||
| --- | --- | --- |
|
||||
| Secret scanning (hard) | 10 secret-shaped patterns (GitHub PAT, AWS, Legacy-Provider `sk_live_*`, Slack, PEM, JWT, generic) scanned across `apps/packages/scripts/prisma/docs/`. Allowlist for `.env.example` variants and test fixtures. | `pnpm run verify:secrets` |
|
||||
| CSRF inventory (hard) | Every mutating `POST/PATCH/DELETE` route is classified in `docs/security/csrf-inventory.md`. | `pnpm exec vitest run apps/api/src/csrf-inventory.test.ts apps/web/app/utils/session-csrf-sweep.test.ts` |
|
||||
| Route access inventory (hard) | Every API route has an access class (`tenant-api-key`, `service-token`, `public-health`, …) documented + matching OpenAPI security. | `pnpm run verify:api-inventory && pnpm run verify:openapi-security` |
|
||||
| Tenant isolation (hard) | 1115 lines of runtime tests in `apps/api/src/isolation/` + `apps/web/app/test/isolation/` exercise cross-tenant mutations and assert 403/401. | `pnpm exec vitest run apps/api/src/isolation apps/web/app/test/isolation` |
|
||||
| Permission matrix (hard) | Role/permission seed is the source-of-truth, docs and tests stay aligned. | `pnpm run verify:permission-matrix` |
|
||||
| Auth error envelope (hard) | Auth middleware throws `{ error: { code, messageKey } }` envelopes, never free strings. | `pnpm exec vitest run apps/web/app/utils/loaders.middleware.test.ts` |
|
||||
| STRIDE threat model (doc) | `docs/security/threat-model.md` lists Spoofing/Tampering/Repudiation/Information-disclosure/DoS/Elevation threats and links each to a gate. | (review) |
|
||||
|
||||
## Quality & code hygiene
|
||||
|
||||
| Gate | Contract | Command |
|
||||
| --- | --- | --- |
|
||||
| Phase-C boundaries (hard) | UI packages cannot import `@hivegrid/db`; runtime separation enforced. | `pnpm run verify:phase-c-boundaries` |
|
||||
| ESLint baseline (anti-regression) | `eslint-disable`, `@ts-ignore`, `@ts-expect-error` counts only decrease from the ratcheted baseline. | `pnpm run verify:eslint-baseline` |
|
||||
| Test density (anti-regression) | 12 workspace dirs maintain a minimum test-file-per-source-file ratio. | `pnpm run verify:test-density` |
|
||||
| Test coverage (anti-regression) | `scripts/coverage-targets.json` defines active per-path thresholds and release-floor sprint targets; `@vitest/coverage-v8` emits `coverage-summary.json` for the gate. The latest backlog has no critical-path positive gaps. | `pnpm run verify:test-coverage` |
|
||||
| Hot-swap mock visual (hard) | `verify:ui-visual` + `test:hot-swap` keep mock-driven surface stable. | `pnpm run verify:ui-visual && pnpm run test:hot-swap` |
|
||||
|
||||
## Operations & runtime
|
||||
|
||||
| Gate | Contract | Command |
|
||||
| --- | --- | --- |
|
||||
| Docker non-root (hard) | All runtime stages (`web`, `api`, `worker`) drop to `USER node` before `CMD/ENTRYPOINT`. | `pnpm run verify:docker-non-root` |
|
||||
| Docker baseline (hard) | Dockerfile stage layout + healthchecks per stage stable. | `pnpm run verify:docker-baseline` |
|
||||
| Bundle-size budget (anti-regression) | JS chunks (root/route/vendor/other) and CSS stay under the +20% headroom budget from current state. | `pnpm run verify:bundle-size` |
|
||||
| Production seed artifact (hard) | The compiled production seed bundle is present and idempotent. | `pnpm run verify:production-seed-artifact` |
|
||||
| Migration rollback drill (manual) | `scripts/drill-migration-rollback.sh` replays forward chain + seed against an ephemeral postgres and asserts a re-apply is a no-op. | `./scripts/drill-migration-rollback.sh` |
|
||||
| Health baseline (hard) | `/healthz` and `/readyz` shapes are stable. | `pnpm run verify:health-baseline` |
|
||||
|
||||
## Supply chain
|
||||
|
||||
| Mechanism | Coverage | File |
|
||||
| --- | --- | --- |
|
||||
| Dependabot | weekly npm (grouped: ai-providers / react-stack / test / lint), weekly github-actions, monthly docker | `.github/dependabot.yml` |
|
||||
| Renovate (Gitea) | same group config for self-hosted Gitea forks | `.gitea/renovate.json` |
|
||||
| SBOM | `scripts/generate-sbom.mjs` writes `sbom-pnpm.json` during the build stage; every runtime image carries the SBOM at `/myapp/sbom-pnpm.json` and labels it via `org.opencontainers.image.sbom`. | `Dockerfile`, `scripts/generate-sbom.mjs` |
|
||||
| Production seed bootstrap | `SEED_ADMIN_EMAIL`/`SEED_ADMIN_PASSWORD` required for prod seed; rejects the local default. | `packages/db/src/production-seed.server.ts` |
|
||||
|
||||
## Documentation
|
||||
|
||||
| Doc | Purpose |
|
||||
| --- | --- |
|
||||
| `docs/quickstart.md` | Install-to-first-local-run path |
|
||||
| `docs/new-project.md` | Adapting the boilerplate to a new project |
|
||||
| `docs/deployment-porting.md` | Gitea infra-string fork procedure |
|
||||
| `docs/security/threat-model.md` | STRIDE per subsystem with mitigation links |
|
||||
| `docs/operations/database-rollback.md` | Forward-only rollback runbook + drill script reference |
|
||||
| `docs/ui-inventory/hot-swap-status.md` | UI registry activation state |
|
||||
|
||||
## Optional gates (opt-in)
|
||||
|
||||
Some verification surfaces require a deployed environment or an external
|
||||
binary and are therefore not wired into the default CI lane. They SKIP
|
||||
cleanly (exit 0) when their prerequisites are missing, so they are safe to
|
||||
run locally or to enable in a downstream pipeline.
|
||||
|
||||
| Gate | Contract | Command | Prerequisites |
|
||||
| --- | --- | --- | --- |
|
||||
| Load tests (opt-in) | k6 scripts in `tests/load/` exercise login, tenant-scoped read, and tenant-scoped mutating paths against a deployed target. Thresholds: `http_req_failed: rate<0.05`, login `p(95)<400ms` / `p(99)<800ms`, read `p(99)<300ms` and `>200 req/s`, mutating `p(99)<600ms`. | `pnpm run verify:load` | `k6` binary on PATH (`brew install k6` or <https://k6.io/docs/getting-started/installation/>); reachable `K6_TARGET_URL` (default `http://localhost:3000`); `LOAD_TENANT_API_KEY` for the read/mutating scripts. See `tests/load/README.md` for the full env contract. |
|
||||
|
||||
To activate the load suite in a release lane, set `K6_TARGET_URL` and
|
||||
`LOAD_TENANT_API_KEY` for that lane and add `pnpm run verify:load` to the
|
||||
job. The runner SKIPs when k6 is missing or the target is offline — the
|
||||
gate never blocks a CI run on environments that cannot satisfy its
|
||||
prerequisites.
|
||||
|
||||
## Composite "all gates" run
|
||||
|
||||
There is no single mega-script — gates are intentionally separate so CI can
|
||||
parallelise. The canonical CI order is asserted by
|
||||
`verify:gitea-ci-workflow` against `.gitea/workflows/ci.yml`. To dry-run the
|
||||
local subset:
|
||||
|
||||
```sh
|
||||
pnpm run verify:ci-baseline
|
||||
pnpm run verify:env-drift
|
||||
pnpm run verify:health-baseline
|
||||
pnpm run verify:i18n
|
||||
pnpm run verify:hardcoded-strings
|
||||
pnpm run verify:phase-c-boundaries
|
||||
pnpm run verify:api-inventory
|
||||
pnpm run verify:openapi-security
|
||||
pnpm run verify:tenant-isolation-report
|
||||
pnpm run verify:docker-baseline
|
||||
pnpm run verify:docker-non-root
|
||||
pnpm run verify:secrets
|
||||
pnpm run verify:eslint-baseline
|
||||
pnpm run verify:test-density
|
||||
pnpm run verify:bundle-size
|
||||
pnpm run verify:test-coverage
|
||||
pnpm typecheck
|
||||
pnpm lint
|
||||
pnpm test
|
||||
```
|
||||
|
||||
Any failure here is a CI failure. Anti-regression gates lock the current
|
||||
ratchet; hard contracts assert immutable structural invariants. Adopt and
|
||||
extend gates rather than disable them.
|
||||
@@ -1,167 +0,0 @@
|
||||
# Boilerplate Version Tracking
|
||||
|
||||
## Purpose
|
||||
|
||||
This guide defines how maintainers and downstream projects record the boilerplate baseline they adopted, how they review drift from that baseline, and how they preserve upgrade evidence without inventing runtime migrations. It complements the SemVer policy in [docs/versioning.md](./versioning.md), the upgrade path in [docs/upgrade.md](./upgrade.md), release entries in [docs/releases/README.md](./releases/README.md), the migration registry in [docs/migration-registry.md](./migration-registry.md), the documentation porting guide in [docs/porting-guide.md](./porting-guide.md), post-port verification in [docs/porting-verification.md](./porting-verification.md), and the public [CHANGELOG.md](../CHANGELOG.md).
|
||||
|
||||
Version tracking is documentation evidence. It proves that a downstream project recorded a reviewed source version, release entry, drift review, and verification summary; it is not package publish proof, artifact provenance, deployment proof, or migration execution proof unless it links to immutable artifact, tag, or deployment evidence that is separately reviewed and redacted.
|
||||
|
||||
## SemVer source version
|
||||
|
||||
The source boilerplate version is the upstream boilerplate release that downstream work starts from or last reconciled against. Use the SemVer decision rules in [docs/versioning.md](./versioning.md) and the matching release note in [CHANGELOG.md](../CHANGELOG.md) before classifying a baseline as patch, minor, or major.
|
||||
|
||||
Record the source version with placeholder-only fields such as:
|
||||
|
||||
| Field | Safe placeholder format | Notes |
|
||||
| --- | --- | --- |
|
||||
| Source version label | `<source-version-label>` | Example shape only; use the released SemVer label when the record is finalized. |
|
||||
| Source release entry path | `<docs/releases/vMAJOR.MINOR.PATCH.md>` | Link to a local release entry under [docs/releases/README.md](./releases/README.md) when available. |
|
||||
| Source changelog heading | `<CHANGELOG.md#version-heading>` | The heading must match [CHANGELOG.md](../CHANGELOG.md). |
|
||||
| Source commit SHA label | `<source-commit-sha-label>` | Store a short or full SHA label only after it is public to the project and safe to disclose. |
|
||||
| Source artifact label | `<artifact-or-tag-label>` | Optional; do not imply artifact proof unless the tag, digest, or signed artifact record exists. |
|
||||
|
||||
Do not use this record to claim that a package was published, an image was pushed, a database migration ran, or a production deployment succeeded. Those claims require their own immutable evidence and manual runtime notes where applicable.
|
||||
|
||||
## Tracked fields
|
||||
|
||||
Each downstream baseline record should include these fields with redacted, placeholder-only values until the release owner fills them with safe evidence:
|
||||
|
||||
| Field | Required value | Redaction rule |
|
||||
| --- | --- | --- |
|
||||
| Downstream project label | `<downstream-project-label>` | Use a generic project label, not a tenant, customer, or private domain. |
|
||||
| Downstream baseline version | `<downstream-baseline-version>` | Name the adopted boilerplate SemVer label or reviewed release train. |
|
||||
| Adopted release entry | `<docs/releases/release-entry.md>` | Use a resolvable local Markdown link when the entry exists. |
|
||||
| Changelog alignment | `<changelog-entry-label>` | Point to the Keep a Changelog entry that describes the baseline. |
|
||||
| Commit SHA label | `<commit-sha-label>` | Record the label only; avoid private repository URLs with credentials. |
|
||||
| Migration registry IDs | `<migration-registry-id-list>` | Use IDs from [docs/migration-registry.md](./migration-registry.md); do not invent runtime database migrations for docs-only drift. |
|
||||
| Drift review status | `<drift-review-status>` | Summarize whether downstream differences are accepted, pending review, or blocked. |
|
||||
| Verification command names | `<verification-command-list>` | Name supported non-E2E commands only. |
|
||||
| Manual runtime status | `<manual-runtime-status>` | State whether manual runtime review is not required, pending, passed, failed, or separately recorded. |
|
||||
| Rollback note label | `<rollback-note-label>` | Link to release or deployment rollback notes when the baseline affects runtime behavior. |
|
||||
|
||||
Allowed values are labels, local file paths, command names, release names, registry IDs, and redacted statuses. Prohibited values include secrets, URLs with credentials, UUID-like deploy endpoints, tenant identifiers, customer identifiers, provider payloads, raw environment values, cookies, bearer tokens, private registry credentials, database connection strings, Redis connection strings, webhook secrets, and screenshots containing sensitive data.
|
||||
|
||||
## Downstream version ledger
|
||||
|
||||
Downstream projects should keep one ledger row per adopted source baseline or material drift review. The ledger belongs in downstream documentation, while this guide defines the contract it should follow.
|
||||
|
||||
Suggested ledger shape:
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Record ID | `<version-record-id>` |
|
||||
| Source version label | `<source-version-label>` |
|
||||
| Downstream baseline version | `<downstream-baseline-version>` |
|
||||
| Adopted release entry | `<docs/releases/release-entry.md>` |
|
||||
| Commit SHA label | `<commit-sha-label>` |
|
||||
| Migration registry IDs | `<migration-registry-id-list>` |
|
||||
| Drift review status | `<drift-review-status>` |
|
||||
| Verification command names | `<verification-command-list>` |
|
||||
| Manual runtime status | `<manual-runtime-status>` |
|
||||
| Rollback note label | `<rollback-note-label>` |
|
||||
|
||||
A ledger row may be marked complete only when its links resolve, its SemVer classification matches [docs/versioning.md](./versioning.md), its changelog reference matches [CHANGELOG.md](../CHANGELOG.md), and its release entry or downstream handoff notes explain any manual runtime boundary.
|
||||
|
||||
## Changelog alignment
|
||||
|
||||
Every baseline record must point back to an adopted release entry and the corresponding changelog entry. Use [docs/releases/README.md](./releases/README.md) for release-entry structure and [CHANGELOG.md](../CHANGELOG.md) for the public release summary.
|
||||
|
||||
Alignment means:
|
||||
|
||||
- Breaking changes in the baseline have migration steps, rollback limits, and verification evidence.
|
||||
- Minor and patch changes do not silently introduce downstream work outside their SemVer class.
|
||||
- Empty Keep a Changelog categories remain explicit instead of using unfinished marker text.
|
||||
- Drift review notes explain whether downstream differences are accepted local customizations or pending upgrade work.
|
||||
- Release artifact or tag references are immutable labels when they are used as proof.
|
||||
|
||||
Version records must not replace release notes. They are an index that lets downstream maintainers find the source release, compare local drift, and decide which upgrade notes apply.
|
||||
|
||||
## Update workflow
|
||||
|
||||
Use this workflow whenever a downstream project adopts a new boilerplate baseline or refreshes drift against an existing baseline:
|
||||
|
||||
1. Confirm the source release and SemVer class using [docs/versioning.md](./versioning.md) and [CHANGELOG.md](../CHANGELOG.md).
|
||||
2. Confirm the adopted release entry under [docs/releases/README.md](./releases/README.md) and capture only a local release-entry path or release label.
|
||||
3. Compare downstream documentation and runtime boundaries against [docs/porting-guide.md](./porting-guide.md) and [docs/porting-verification.md](./porting-verification.md).
|
||||
4. Review any migration or docs-only tracking IDs in [docs/migration-registry.md](./migration-registry.md).
|
||||
5. Record the drift review status, verification command names, and manual runtime status using placeholder-safe labels.
|
||||
6. Run supported automatic non-E2E checks when the files exist and the package manager is pinned through `pnpm@10.33.0`.
|
||||
7. Link rollback notes from the release entry, upgrade guide, or downstream handoff record when runtime behavior, data, deployment, or security posture can be affected.
|
||||
|
||||
Supported automatic checks for this documentation contract are:
|
||||
|
||||
```sh
|
||||
pnpm run verify:release-docs
|
||||
pnpm run verify:docs-links
|
||||
```
|
||||
|
||||
These checks are local, static, non-E2E verification. They do not drive a browser, open provider consoles, run live deployments, push registries, or prove production readiness.
|
||||
|
||||
## Downstream project handoff
|
||||
|
||||
A downstream handoff should include a short baseline summary, the ledger row, the chosen upgrade path, and the evidence boundary. The handoff should tell the next maintainer what was adopted, what drift remains, which release entry governs the change, and which checks were automatic versus manual.
|
||||
|
||||
Minimum handoff content:
|
||||
|
||||
- Source boilerplate version label and downstream baseline version.
|
||||
- Adopted release entry path and changelog entry label.
|
||||
- Migration registry ID list or a clear statement that no runtime migration registry entry applies.
|
||||
- Drift review status with accepted local differences separated from pending upgrade work.
|
||||
- Verification command names, exit status labels, and redacted diagnostic labels.
|
||||
- Manual runtime status, owner label, and date label when manual review is required.
|
||||
- Rollback note label that names whether rollback is redeploy-only, migration-sensitive, backup-dependent, or unsupported.
|
||||
|
||||
The handoff must avoid tenant names, customer names, private hostnames, provider request payloads, raw environment values, tokens, passwords, and URLs that embed credentials. If a downstream operator needs those values, reference the environment-owned secret store by role label rather than copying values into Markdown.
|
||||
|
||||
## Compatibility with SemVer/changelog/release entries
|
||||
|
||||
The version ledger is compatible with SemVer, changelog, and release-entry records because it stores references rather than redefining policy. [docs/versioning.md](./versioning.md) defines the meaning of major, minor, and patch. [CHANGELOG.md](../CHANGELOG.md) gives the public release summary. [docs/releases/README.md](./releases/README.md) defines the operator evidence expected around the release.
|
||||
|
||||
If these sources disagree, do not finalize the downstream baseline. Correct the release documentation first, then update the version record. For example, a downstream record cannot classify a breaking database behavior change as patch if the versioning policy requires a major release decision and rollback notes.
|
||||
|
||||
## Migration-registry relationship
|
||||
|
||||
Version tracking may reference migration registry IDs from [docs/migration-registry.md](./migration-registry.md), but it does not create migrations by itself. Documentation-only baseline records should stay marked as docs evidence unless a real database, deployment, configuration, API, worker, provider, or security migration exists.
|
||||
|
||||
Use migration registry IDs for ownership, status, rollback, and verification labels. Use the version ledger for adopted baseline and drift history. When a migration is runtime-affecting, the registry owns the migration detail and this guide should only link the ID and summarize the redacted status.
|
||||
|
||||
## Upgrade and rollback notes
|
||||
|
||||
Upgrade notes should point to [docs/upgrade.md](./upgrade.md), the adopted release entry, and any downstream handoff record. They should explain whether the downstream project is adopting a patch, minor, or major baseline and whether additional drift work is required before rollout.
|
||||
|
||||
Rollback notes must state the safest known path:
|
||||
|
||||
- Redeploy a prior immutable artifact or tag when no data or configuration migration changed.
|
||||
- Restore from backup or forward-fix when database state changed and downgrade is not automatic.
|
||||
- Pause or drain worker queues when queue behavior affects safe rollback.
|
||||
- Treat provider, security, and mail changes as manual runtime concerns with redacted request or status labels only.
|
||||
|
||||
Do not present a version record as rollback proof. It is a pointer to the release and upgrade evidence that defines rollback behavior.
|
||||
|
||||
## Redacted evidence
|
||||
|
||||
Record only safe, reviewable evidence:
|
||||
|
||||
- Version labels, release-entry paths, changelog labels, migration registry IDs, and command names.
|
||||
- Commit SHA labels and artifact or tag labels that are safe for the project to disclose.
|
||||
- Exit code labels, pass or fail labels, redacted diagnostic codes, and manual runtime status labels.
|
||||
- Owner role labels and date labels when downstream policy requires them.
|
||||
|
||||
Do not record secrets, URLs with credentials, UUID-like deploy endpoints, tenant identifiers, customer identifiers, customer data, provider payloads, raw environment values, cookies, bearer tokens, API keys, private registry credentials, database URLs, Redis URLs, webhook token paths, or full environment dumps.
|
||||
|
||||
If evidence arrives with sensitive values, redact it before adding it to the ledger. If redaction would remove the fact needed to prove the claim, link to an approved secure evidence store by role label and keep only the non-secret status in Markdown.
|
||||
|
||||
## Non-E2E verification
|
||||
|
||||
The verifier from the Release Docs release-documentation slice rejects missing required tracking terms, unresolved local links, forbidden placeholder markers, automatic browser or E2E command recommendations, and secret-shaped values. Documentation-only verification reads Markdown locally and does not need runtime services.
|
||||
|
||||
For this guide, use:
|
||||
|
||||
```sh
|
||||
test -s docs/boilerplate-version-tracking.md
|
||||
grep -n "^## Tracked fields" docs/boilerplate-version-tracking.md
|
||||
pnpm run verify:release-docs
|
||||
pnpm run verify:docs-links
|
||||
```
|
||||
|
||||
Browser journeys, Playwright, Cypress, provider-console checks, live Docker runs, registry pushes, Coolify execution, production deploys, and customer-impacting request paths are manual runtime evidence only unless a human explicitly approves the exact focused run. When manual review is needed, record the manual runtime status, owner role, target label, immutable tag or request label, and redacted outcome only.
|
||||
@@ -2,7 +2,10 @@
|
||||
|
||||
## Scope
|
||||
|
||||
This inventory documents the current data-protection-relevant surfaces in the boilerplate for follow-up work in Compliance Retention. It is a repository evidence map, not legal advice and not an implemented retention schedule. Entries are grounded in the current security and production evidence boundaries from `docs/security.md` and `docs/production-checklist.md`, the Compliance Retention baseline inventory report, and Prisma schema surfaces under `prisma/schema`.
|
||||
This inventory documents the current data-protection-relevant surfaces in HiveGrid for follow-up work
|
||||
in Compliance Retention. It is a repository evidence map, not legal advice and not an implemented
|
||||
retention schedule. Entries are grounded in `docs/security.md`, `docs/staging-live-uat.md` and the
|
||||
Prisma schema surfaces under `prisma/schema`.
|
||||
|
||||
The inventory covers user, tenant, authentication, API, file, entity-row, import/export, notification, billing, audit, email, analytics, worker, and optional plugin-candidate surfaces that can contain personal data or personal-data-adjacent operational evidence. Unknown retention periods are listed as implementation gaps for later Compliance Retention slices rather than invented durations.
|
||||
|
||||
@@ -81,7 +84,9 @@ Repository-level retention defaults now live in [`docs/data-retention.md`](../da
|
||||
|
||||
## Operational redaction rules
|
||||
|
||||
- Follow `docs/security.md` and `docs/production-checklist.md`: automatic evidence is local/static unless a human explicitly approves a runtime check; browser, provider-console, Docker, registry, Coolify, production traffic, Playwright, and Cypress activities remain manual records.
|
||||
- Follow `docs/security.md` and `docs/staging-live-uat.md`: automatic evidence is local/static unless
|
||||
a human explicitly approves a runtime check; browser, provider-console and production activities
|
||||
remain manual records outside the configured deploy workflow.
|
||||
- Safe evidence includes model or surface labels, route or endpoint labels, status, stable error code, request ID, job ID, queue name, counts, command name, exit code, redacted diagnostic code, and pass/fail labels.
|
||||
- Unsafe evidence includes secrets, bearer tokens, cookies, API keys, key hashes/prefixes/last-four, raw authorization headers, tenant identifiers, customer domains, customer names, email addresses, phone numbers, IP addresses, object keys, signed URLs, webhook signatures, provider payloads, queue payloads, raw logs, screenshots with personal data, import/export contents, and email/message bodies.
|
||||
- Examples in compliance docs must stay placeholder-shaped and must not include realistic personal data, tenant slugs, domains, UUID-like deploy endpoints, provider IDs, or secret-shaped strings.
|
||||
|
||||
@@ -1,190 +0,0 @@
|
||||
# i18n Audit — Baseline 2026-05-25
|
||||
|
||||
> Generated by `scripts/i18n-audit.mjs`. Counts hardcoded user-facing
|
||||
> strings in `apps/web/app/{routes,modules,routeModules,components}/**/*.{ts,tsx}`.
|
||||
> Baseline only — not yet
|
||||
> enforced. See `docs/contributing/i18n.md` for the migration playbook.
|
||||
>
|
||||
> Historical baseline note: this file is a point-in-time audit artifact from
|
||||
> 2026-05-25. Re-run the audit script before using counts as current status.
|
||||
>
|
||||
> Current re-run note: `node scripts/i18n-audit.mjs --json` on 2026-05-29
|
||||
> reports `0` hardcoded strings and `0` locale-formatting signals.
|
||||
|
||||
## Current Re-Run Snapshot
|
||||
|
||||
| Metric | Value |
|
||||
| ---------------------------------------------- | ----: |
|
||||
| Files scanned | 1774 |
|
||||
| Files with hardcoded strings | 0 |
|
||||
| Total hardcoded JSX text fragments | 0 |
|
||||
| Files with locale-sensitive formatting signals | 0 |
|
||||
| Total locale-sensitive formatting signals | 0 |
|
||||
|
||||
## Historical Baseline Summary
|
||||
|
||||
| Metric | Value |
|
||||
| ---------------------------------------------- | ----: |
|
||||
| Files scanned | 1752 |
|
||||
| Files with hardcoded strings | 4 |
|
||||
| Total hardcoded JSX text fragments | 26 |
|
||||
| Files with locale-sensitive formatting signals | 91 |
|
||||
| Total locale-sensitive formatting signals | 213 |
|
||||
|
||||
## Historical Top Offenders
|
||||
|
||||
| File | Hits |
|
||||
| ----------------------------------------------------------------------- | ---: |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts` | 22 |
|
||||
| `apps/web/app/routes/__test.client-throw.tsx` | 2 |
|
||||
| `apps/web/app/components/ai-elements/open-in-chat.tsx` | 1 |
|
||||
| `apps/web/app/modules/workflowEngine/utils/DefaultWorkflowTemplates.ts` | 1 |
|
||||
|
||||
## Historical Disposition
|
||||
|
||||
The 26 hardcoded text fragments from the 2026-05-25 baseline are no longer
|
||||
reported by the current audit. The historical dispositions below explain why
|
||||
they were not treated as active product UI debt at the time:
|
||||
|
||||
| File | Disposition |
|
||||
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts` | Seed/template article content. Migrate only if knowledge-base templates gain locale variants. |
|
||||
| `apps/web/app/routes/__test.client-throw.tsx` | Test-only Sentry smoke route. Keep diagnostic copy literal. |
|
||||
| `apps/web/app/components/ai-elements/open-in-chat.tsx` | Provider/brand name (`Scira AI`). Proper noun, do not translate. |
|
||||
| `apps/web/app/modules/workflowEngine/utils/DefaultWorkflowTemplates.ts` | English-scoped default workflow payload. Migrate only if workflow templates gain locale variants. |
|
||||
|
||||
## Detail (first 100 hits)
|
||||
|
||||
| File:Line | Hardcoded text |
|
||||
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
||||
| `apps/web/app/components/ai-elements/open-in-chat.tsx:45` | Scira AI |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:120` | Watch the demo video: |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:122` | Watch the demo video: |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:142` | Static Knowledge Base |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:142` | And the knowledge base |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:142` | Dynamic Knowledge Bases |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:142` | For all other knowledge bases, the |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:142` | You can change the hard-coded |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:144` | Static Knowledge Base |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:144` | And the knowledge base |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:144` | Dynamic Knowledge Bases |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:144` | For all other knowledge bases, the |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:144` | You can change the hard-coded |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:163` | Beispiel 2 |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:164` | Beispiel 2 |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:182` | Sample 2 |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:183` | Sample 2 |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:227` | Beispiel 1 |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:228` | Beispiel 1 |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:246` | Beispiel 3 |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:247` | Beispiel 3 |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:265` | Sample 3 |
|
||||
| `apps/web/app/modules/knowledgeBase/utils/DefaultKbsTemplate.ts:266` | Sample 3 |
|
||||
| `apps/web/app/modules/workflowEngine/utils/DefaultWorkflowTemplates.ts:760` | It works! |
|
||||
| `apps/web/app/routes/__test.client-throw.tsx:33` | Sentry client smoke test |
|
||||
| `apps/web/app/routes/__test.client-throw.tsx:34` | Triggering a synchronous client-side error. The root ErrorBoundary should pick it up and report to Sentry. |
|
||||
|
||||
## Formatting migration signals (first 100 hits)
|
||||
|
||||
| File:Line | Signal |
|
||||
| ----------------------------------------------------------------------------------------------- | ---------------------------- |
|
||||
| `apps/web/app/components/aceternity/infinite-moving-cards.tsx:214` | `DateUtils.dateYMDHMSMS` |
|
||||
| `apps/web/app/components/aceternity/infinite-moving-cards.tsx:215` | `DateUtils.dateAgo` |
|
||||
| `apps/web/app/components/analytics/AnalyticsOverview.tsx:25` | `NumberUtils.intFormat` |
|
||||
| `apps/web/app/components/analytics/AnalyticsOverview.tsx:32` | `NumberUtils.intFormat` |
|
||||
| `apps/web/app/components/analytics/AnalyticsOverview.tsx:64` | `NumberUtils.intFormat` |
|
||||
| `apps/web/app/components/analytics/AnalyticsOverview.tsx:132` | `NumberUtils.intFormat` |
|
||||
| `apps/web/app/components/analytics/AnalyticsOverviewChart.tsx:8` | `NumberUtils.intFormat` |
|
||||
| `apps/web/app/components/app/events/LogsTable.tsx:92` | `DateUtils.dateAgo` |
|
||||
| `apps/web/app/components/app/events/LogsTable.tsx:95` | `DateUtils.dateYMD` |
|
||||
| `apps/web/app/components/app/events/LogsTable.tsx:96` | `DateUtils.dateAgo` |
|
||||
| `apps/web/app/components/core/apiKeys/ApiKeyLogsTable.tsx:30` | `DateUtils.dateYMDHMS` |
|
||||
| `apps/web/app/components/core/apiKeys/ApiKeyLogsTable.tsx:31` | `DateUtils.dateYMDHMS` |
|
||||
| `apps/web/app/components/core/apiKeys/ApiKeysTable.tsx:162` | `NumberUtils.intFormat` |
|
||||
| `apps/web/app/components/core/apiKeys/ApiKeysTable.tsx:188` | `DateUtils.dateYMDHMS` |
|
||||
| `apps/web/app/components/core/apiKeys/ApiKeysTable.tsx:192` | `DateUtils.dateAgo` |
|
||||
| `apps/web/app/components/core/apiKeys/ApiKeysTable.tsx:197` | `DateUtils.dateYMDHMS` |
|
||||
| `apps/web/app/components/core/apiKeys/ApiKeysTable.tsx:198` | `DateUtils.dateYMDHMS` |
|
||||
| `apps/web/app/components/core/pricing/UsageBasedPricesUnit.tsx:109` | `NumberUtils.numberFormat` |
|
||||
| `apps/web/app/components/core/settings/members/MembersListAndTable.tsx:48` | `DateUtils.dateYMDHMS` |
|
||||
| `apps/web/app/components/core/settings/members/MembersListAndTable.tsx:49` | `DateUtils.dateAgo` |
|
||||
| `apps/web/app/components/core/settings/subscription/ChangeSubscription.tsx:51` | `NumberUtils.intFormat` |
|
||||
| `apps/web/app/components/core/settings/subscription/MyInvoices.tsx:28` | `DateUtils.dateYMD` |
|
||||
| `apps/web/app/components/core/settings/subscription/MyInvoices.tsx:31` | `DateUtils.dateYMD` |
|
||||
| `apps/web/app/components/core/settings/subscription/MyInvoices.tsx:32` | `DateUtils.dateAgo` |
|
||||
| `apps/web/app/components/core/settings/subscription/MyPayments.tsx:31` | `DateUtils.dateYMD` |
|
||||
| `apps/web/app/components/core/settings/subscription/MyPayments.tsx:32` | `DateUtils.dateAgo` |
|
||||
| `apps/web/app/components/core/settings/subscription/MyPayments.tsx:42` | `NumberUtils.decimalFormat` |
|
||||
| `apps/web/app/components/core/settings/subscription/MyPayments.tsx:60` | `DateUtils.dateYMD` |
|
||||
| `apps/web/app/components/core/settings/subscription/MyPayments.tsx:63` | `DateUtils.dateYMD` |
|
||||
| `apps/web/app/components/core/settings/subscription/MyPayments.tsx:64` | `DateUtils.dateAgo` |
|
||||
| `apps/web/app/components/core/settings/subscription/MyPlanFeatureUsage.tsx:38` | `DateUtils.dateYMD` |
|
||||
| `apps/web/app/components/core/settings/subscription/MyUpcomingInvoice.tsx:30` | `DateUtils.dateMonthDayYear` |
|
||||
| `apps/web/app/components/core/settings/subscription/Plan.tsx:138` | `NumberUtils.numberFormat` |
|
||||
| `apps/web/app/components/core/settings/subscription/PlanFeatureDescription.tsx:86` | `NumberUtils.intFormat` |
|
||||
| `apps/web/app/components/core/settings/subscription/TenantProduct.tsx:43` | `DateUtils.dateMonthDayYear` |
|
||||
| `apps/web/app/components/core/settings/subscription/TenantProduct.tsx:76` | `DateUtils.dateYMDHMSMS` |
|
||||
| `apps/web/app/components/core/settings/subscription/TenantProduct.tsx:77` | `DateUtils.dateMonthDayYear` |
|
||||
| `apps/web/app/components/core/settings/subscription/TenantProduct.tsx:78` | `DateUtils.dateMonthDayYear` |
|
||||
| `apps/web/app/components/core/settings/subscription/TenantProduct.tsx:85` | `DateUtils.dateMonthDayYear` |
|
||||
| `apps/web/app/components/core/settings/subscription/TenantProduct.tsx:89` | `DateUtils.dateMonthDayYear` |
|
||||
| `apps/web/app/components/core/tenants/TenantsTable.tsx:104` | `NumberUtils.decimalFormat` |
|
||||
| `apps/web/app/components/core/tenants/TenantsTable.tsx:115` | `DateUtils.dateMonthDayYear` |
|
||||
| `apps/web/app/components/core/tenants/TenantsTable.tsx:119` | `DateUtils.dateMonthDayYear` |
|
||||
| `apps/web/app/components/core/tenants/TenantsTable.tsx:176` | `NumberUtils.decimalFormat` |
|
||||
| `apps/web/app/components/core/tenants/TenantsTable.tsx:214` | `DateUtils.dateYMD` |
|
||||
| `apps/web/app/components/core/tenants/TenantsTable.tsx:215` | `DateUtils.dateAgo` |
|
||||
| `apps/web/app/components/core/tenants/TenantsTable.tsx:244` | `DateUtils.dateYMD` |
|
||||
| `apps/web/app/components/core/tenants/TenantsTable.tsx:246` | `NumberUtils.decimalFormat` |
|
||||
| `apps/web/app/components/core/tenants/TenantsTable.tsx:251` | `DateUtils.dateAgo` |
|
||||
| `apps/web/app/components/core/users/UsersTable.tsx:118` | `DateUtils.dateDM` |
|
||||
| `apps/web/app/components/core/users/UsersTable.tsx:120` | `DateUtils.dateYMDHMS` |
|
||||
| `apps/web/app/components/core/users/UsersTable.tsx:121` | `DateUtils.dateAgo` |
|
||||
| `apps/web/app/components/core/users/UsersTable.tsx:224` | `DateUtils.dateAgo` |
|
||||
| `apps/web/app/components/entities/properties/FormulaControl.tsx:39` | `NumberUtils.decimalFormat` |
|
||||
| `apps/web/app/components/entities/relationships/EntityRelationshipsTable.tsx:63` | `NumberUtils.intFormat` |
|
||||
| `apps/web/app/components/entities/rows/cells/RowDateCell.tsx:8` | `DateUtils.dateYMD` |
|
||||
| `apps/web/app/components/entities/rows/cells/RowDateCell.tsx:12` | `DateUtils.dateYMD` |
|
||||
| `apps/web/app/components/entities/rows/cells/RowDateCell.tsx:14` | `DateUtils.dateDMY` |
|
||||
| `apps/web/app/components/entities/rows/cells/RowDateCell.tsx:16` | `DateUtils.dateMDY` |
|
||||
| `apps/web/app/components/entities/rows/cells/RowDateCell.tsx:18` | `DateUtils.dateAgo` |
|
||||
| `apps/web/app/components/entities/rows/cells/RowDateCell.tsx:20` | `DateUtils.dateYMD` |
|
||||
| `apps/web/app/components/entities/rows/cells/RowFolioCell.tsx:6` | `NumberUtils.pad` |
|
||||
| `apps/web/app/components/entities/rows/cells/RowNumberCell.tsx:11` | `NumberUtils.intFormat` |
|
||||
| `apps/web/app/components/entities/rows/cells/RowNumberCell.tsx:13` | `NumberUtils.decimalFormat` |
|
||||
| `apps/web/app/components/entities/rows/cells/RowNumberCell.tsx:15` | `NumberUtils.decimalFormat` |
|
||||
| `apps/web/app/components/entities/rows/cells/RowNumberCell.tsx:15` | `NumberUtils.currencyFormat` |
|
||||
| `apps/web/app/components/entities/rows/cells/RowNumberCell.tsx:17` | `NumberUtils.percentFormat` |
|
||||
| `apps/web/app/components/entities/rows/RowActivity.tsx:132` | `DateUtils.dateYMDHMS` |
|
||||
| `apps/web/app/components/entities/rows/RowActivity.tsx:132` | `DateUtils.dateAgo` |
|
||||
| `apps/web/app/components/entities/rows/RowLogComment.tsx:88` | `DateUtils.dateAgo` |
|
||||
| `apps/web/app/components/entities/rows/RowLogComment.tsx:89` | `DateUtils.dateYMDHMS` |
|
||||
| `apps/web/app/components/entities/rows/RowLogComment.tsx:89` | `DateUtils.dateAgo` |
|
||||
| `apps/web/app/components/entities/rows/RowLogs.tsx:24` | `DateUtils.dateDM` |
|
||||
| `apps/web/app/components/entities/rows/RowLogs.tsx:79` | `DateUtils.dateYMDHMS` |
|
||||
| `apps/web/app/components/entities/rows/RowLogs.tsx:80` | `DateUtils.dateHMS` |
|
||||
| `apps/web/app/components/entities/views/EntityViewsTable.tsx:188` | `NumberUtils.intFormat` |
|
||||
| `apps/web/app/components/ui/input/InputDate.tsx:172` | `DateUtils.dateYMD` |
|
||||
| `apps/web/app/components/ui/multi-select.tsx:312` | `NumberUtils.intFormat` |
|
||||
| `apps/web/app/components/ui/tables/PreviewTableSimple.tsx:45` | `NumberUtils.decimalFormat` |
|
||||
| `apps/web/app/components/ui/tables/PreviewTableSimple.tsx:52` | `DateUtils.dateYMD` |
|
||||
| `apps/web/app/modules/api/components/ApiKeyLogsDetails.tsx:96` | `DateUtils.dateYMDHMS` |
|
||||
| `apps/web/app/modules/api/components/ApiKeyLogsDetails.tsx:98` | `DateUtils.dateYMDHMS` |
|
||||
| `apps/web/app/modules/api/components/ApiKeyLogsDetails.tsx:166` | `NumberUtils.custom` |
|
||||
| `apps/web/app/modules/api/components/ApiKeyLogsSummary.tsx:123` | `NumberUtils.intFormat` |
|
||||
| `apps/web/app/modules/api/components/ApiKeyLogsSummary.tsx:136` | `NumberUtils.custom` |
|
||||
| `apps/web/app/modules/chatbot/components/chat-list.tsx:52` | `DateUtils.dateAgo` |
|
||||
| `apps/web/app/modules/codeGenerator/service/CodeGeneratorService.ts:243` | `DateUtils.dateYMD` |
|
||||
| `apps/web/app/modules/codeGenerator/templates/routes/api/CodeTemplate.Routes.Edit.Api.ts:59` | `NumberUtils.pad` |
|
||||
| `apps/web/app/modules/codeGenerator/templates/routes/views/CodeTemplate.Routes.Edit.View.ts:69` | `NumberUtils.pad` |
|
||||
| `apps/web/app/modules/emailMarketing/components/EmailMarketingSummaryRoute.tsx:21` | `NumberUtils.decimalFormat` |
|
||||
| `apps/web/app/modules/emailMarketing/components/EmailMarketingSummaryRoute.tsx:27` | `NumberUtils.decimalFormat` |
|
||||
| `apps/web/app/modules/emailMarketing/components/EmailMarketingSummaryRoute.tsx:36` | `NumberUtils.numberFormat` |
|
||||
| `apps/web/app/modules/emailMarketing/components/OutboundEmailsTable.tsx:177` | `DateUtils.dateYMDHMS` |
|
||||
| `apps/web/app/modules/emailMarketing/components/OutboundEmailsTable.tsx:178` | `DateUtils.dateYMD` |
|
||||
| `apps/web/app/modules/emailMarketing/components/OutboundEmailsTable.tsx:179` | `DateUtils.dateAgo` |
|
||||
| `apps/web/app/modules/emailMarketing/components/OutboundEmailsTable.tsx:213` | `DateUtils.dateYMDHMS` |
|
||||
| `apps/web/app/modules/events/components/EventDetails.tsx:26` | `DateUtils.dateYMDHMS` |
|
||||
| `apps/web/app/modules/events/components/EventDetails.tsx:62` | `DateUtils.dateYMDHMS` |
|
||||
| `apps/web/app/modules/events/components/EventDetails.tsx:68` | `DateUtils.dateYMDHMS` |
|
||||
| `apps/web/app/modules/events/components/EventsTable.tsx:103` | `DateUtils.dateAgo` |
|
||||
@@ -36,7 +36,9 @@ apps/web/public/locales/
|
||||
│ ├── crm.json # Per-area: CRM surfaces
|
||||
│ ├── auth.json # Per-area: authentication surfaces
|
||||
│ └── emailMarketing.json # Per-area: email marketing surfaces
|
||||
└── en/ (same structure)
|
||||
├── en/ (same structure)
|
||||
├── pl/ · ru/ · uk/ · hu/ (same structure, release-gated)
|
||||
└── <locale>-formal/ (nine sparse formal-override namespace files)
|
||||
```
|
||||
|
||||
`translations.json` is the historical bag-of-keys. **New work should land
|
||||
@@ -97,6 +99,8 @@ i18next's `{{name}}` interpolation, so a gradual migration is safe.
|
||||
| en | one, other |
|
||||
| de | one, other |
|
||||
| pl | one, few, many, other |
|
||||
| ru, uk | one, few, many, other |
|
||||
| hu | one, other |
|
||||
| ar | zero, one, two, few, many, other |
|
||||
| ja, zh | other (no plural distinction) |
|
||||
|
||||
@@ -127,10 +131,15 @@ identical output on server + client.
|
||||
When a request arrives, the server picks a locale in this order:
|
||||
|
||||
1. `User.locale` (set via the profile locale-picker)
|
||||
2. `Tenant.defaultLocale`
|
||||
3. `Accept-Language` header (browser default)
|
||||
2. Tenant default locale when the tenant contract exposes one
|
||||
3. Locale cookie / `Accept-Language` header (browser default)
|
||||
4. App fallback (`de`, see `packages/i18n/src/index.ts#defaultLocale`)
|
||||
|
||||
Every candidate is filtered through `I18N_ENABLED_LOCALES`. Disabled locales
|
||||
cannot be activated by stored preferences, cookies, request parameters or
|
||||
browser headers. The checked-in default remains `de,en`; review locales are
|
||||
enabled individually on staging only after their manifest is current.
|
||||
|
||||
The resolved locale is stored in the i18n cookie (`_i18n`) and surfaced
|
||||
to React via `useTranslation().i18n.language`. The picker UI lives in
|
||||
`apps/web/app/modules/users/components/UserProfileSettings.tsx` (rendered
|
||||
@@ -164,7 +173,17 @@ calls the root `setLocale` action.
|
||||
by copying the English files
|
||||
3. Run `pnpm verify:i18n` — the parity check enforces all namespaces have
|
||||
matching keys
|
||||
4. Have the translation reviewed before merging
|
||||
4. Add all nine `<locale>-formal` namespace files; they may be sparse but must
|
||||
fall back through `<locale>-formal → <locale> → de`
|
||||
5. Update `docs/contributing/i18n/reviews/<locale>.json` with German source hashes
|
||||
6. Run `pnpm verify:i18n`
|
||||
7. Keep the locale disabled until the documented native-speaker gate passes
|
||||
|
||||
`scripts/i18n-translate-catalog.ts` is a build-time helper only. It writes
|
||||
static catalogs and is never part of a HiveGrid runtime or deployment image.
|
||||
`scripts/i18n-quality.ts` blocks stale hashes, damaged placeholders/ICU
|
||||
arguments/tags/URLs, mojibake, non-NFC text, untranslated German sentences and
|
||||
incomplete CLDR plural categories.
|
||||
|
||||
## Auditing hardcoded strings
|
||||
|
||||
@@ -179,10 +198,8 @@ node scripts/i18n-audit.mjs
|
||||
# → docs/contributing/i18n-audit-<YYYY-MM-DD>.md
|
||||
```
|
||||
|
||||
The current audit snapshot is `docs/contributing/i18n-audit-2026-05-25.md`.
|
||||
Its re-run section is the active product-UI baseline: 0 hardcoded
|
||||
route/component strings and 0 locale-formatting signals as of 2026-05-29.
|
||||
The 2026-05-25 findings remain in that file as historical disposition only.
|
||||
Audit-Reports sind lokale, datierte Arbeitsartefakte und werden nicht als dauerhafte Quelle im Repo
|
||||
gepflegt. Der ausführbare Vertrag ist `pnpm verify:i18n`.
|
||||
|
||||
The repo-wide `pnpm verify:i18n` script enforces three guards:
|
||||
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
# HiveGrid translation glossary
|
||||
|
||||
German is the semantic source. English is the context reference. Product names, provider names,
|
||||
protocol identifiers and user-authored content are never translated automatically.
|
||||
|
||||
| German | Meaning | Polish | Russian | Ukrainian | Hungarian |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| Projekt | Central commercial and operational record | projekt | проект | проєкт | projekt |
|
||||
| Auftrag | Confirmed customer order, represented by a project type | zlecenie | заказ | замовлення | megrendelés |
|
||||
| Angebot | Commercial quotation | oferta | коммерческое предложение | комерційна пропозиція | ajánlat |
|
||||
| Rechnung | Invoice | faktura | счёт | рахунок | számla |
|
||||
| Abnahme | Formal acceptance of completed work | odbiór | приёмка | приймання | műszaki átadás |
|
||||
| Mangel | Defect requiring remediation | usterka | дефект | недолік | hiba |
|
||||
| Baustelle | Physical work site | plac budowy | строительная площадка | будівельний майданчик | munkaterület |
|
||||
| Monteur | Field technician / installer | monter | монтажник | монтажник | szerelő |
|
||||
| Plantafel | Scheduling board for crews and work | tablica planowania | доска планирования | дошка планування | ütemezőtábla |
|
||||
| Pipeline | Configurable project view by stage | pipeline | воронка | воронка | folyamatnézet |
|
||||
| Automation | Automatically executed rule | automatyzacja | автоматизация | автоматизація | automatizálás |
|
||||
| Workflow | Multi-step automated process | przepływ pracy | рабочий процесс | робочий процес | munkafolyamat |
|
||||
| Mandant | Tenant/company workspace, never a customer contact | organizacja | организация | організація | szervezet |
|
||||
| Kontakt | Natural person or contact record | kontakt | контакт | контакт | kapcsolattartó |
|
||||
| Firma | Company record | firma | компания | компанія | vállalat |
|
||||
| Kunde | Customer | klient | клиент | клієнт | ügyfél |
|
||||
|
||||
## Locked terminology rules
|
||||
|
||||
- `HiveGrid`, Mollie, Mailjet, Authentik, Meilisearch and product/provider names stay unchanged.
|
||||
- `Projekt` remains the central entity. Do not reintroduce a separate Deal/Order handoff in translation.
|
||||
- Pipeline is a project view, not a second data model.
|
||||
- Keep placeholders, ICU arguments, HTML/React tags, URLs, email addresses and protocol identifiers byte-identical.
|
||||
- Translate only system copy. Names, stages, project titles and customer-authored portal templates stay untouched.
|
||||
@@ -0,0 +1,36 @@
|
||||
# Six-locale rollout and rollback
|
||||
|
||||
Polish (`pl`), Ukrainian (`uk`), Russian (`ru`) and Hungarian (`hu`) ship as static catalogs but remain disabled until their own release gate passes. The checked-in and production default for `I18N_ENABLED_LOCALES` is `de,en`.
|
||||
|
||||
## Release gate
|
||||
|
||||
Each locale must have a current `reviews/<locale>.json` manifest before activation. A native speaker reviews all Auth, error, billing, transactional-mail and formal-override copy, completes the critical App and Customer Portal journeys, and records at least 200 stratified samples from the other namespaces. The manifest records reviewer, date, sample size and corrections. A changed German source hash makes the catalog review-pending again.
|
||||
|
||||
Technical presence is not release approval. `packages/i18n/src/locales.ts` keeps every new locale in the `review` stage, so production configuration rejects it even if it is added to the environment variable. The stage may move to `production` only after the manifest gate has passed.
|
||||
|
||||
## Staged activation
|
||||
|
||||
Activate one locale at a time on staging in this order:
|
||||
|
||||
1. `pl`
|
||||
2. `uk`
|
||||
3. `ru`
|
||||
4. `hu`
|
||||
|
||||
For each locale, append only that code to `I18N_ENABLED_LOCALES`, deploy the same immutable image, and run the Du/Sie browser and mail UAT. Cover login/password reset, navigation/dashboard/search, CRM/projects/pipelines/workflows, destructive dialogs/errors/toasts, billing/checkout, settings/language changes, Customer Portal and transactional mail. Check desktop, tablet and mobile layouts, including Cyrillic, Polish `ą ć ę ł ń ó ś ź ż` and Hungarian `á é í ó ö ő ú ü ű`.
|
||||
|
||||
After corrections and a completed manifest, promote the locale release stage, add it to the production environment variable and monitor the deploy. Do not activate multiple new locales in the same rollout step.
|
||||
|
||||
## Performance gate
|
||||
|
||||
Run `pnpm verify:i18n-performance`. It measures synchronous JSON parsing and retained RSS for `de,en` versus all six base/formal bundles in isolated Node processes. A delta above 250 ms or 30 MB fails the command and requires locale-scoped cached loading before release. Record the measured result in the ticket implementation note.
|
||||
|
||||
Measurement on 2026-08-02: the median `de,en` load was 11.29 ms and 5.30 MB retained RSS; all six locales loaded in 33.17 ms and 16.59 MB. The resulting delta was **+21.88 ms and +11.29 MB**, so eager once-per-process loading remains within the release contract.
|
||||
|
||||
## Rollback
|
||||
|
||||
Remove the affected locale from `I18N_ENABLED_LOCALES`, redeploy, and if needed redeploy the previous immutable image SHA. Catalog files may remain in the image: disabled locales cannot be selected or activated through a stored preference, cookie, request parameter or `Accept-Language` header. No database rollback is required.
|
||||
|
||||
## Next candidates
|
||||
|
||||
Romanian is the next planned expansion, but this change intentionally adds no `ro` type, catalog or runtime option. Turkish and Bulgarian remain later market candidates only.
|
||||
@@ -0,0 +1,8 @@
|
||||
# Hungarian style guide (`hu`)
|
||||
|
||||
- Base bundle: direct, friendly `te`; use natural Hungarian suffixes and word order.
|
||||
- Formal bundle: consistently use `Ön` and matching verb forms.
|
||||
- Prefer `projekt`, `megrendelés`, `ajánlat`, `számla`, `műszaki átadás`, `hiba`, `szerelő` and `ütemezőtábla`.
|
||||
- Use Hungarian quotation marks „…”, double acute accents (`ő`, `ű`) and locale formatting (`hu-HU`).
|
||||
- Plurals must contain `one` and `other`; test 0, 1, 2, 5, 21 and a decimal.
|
||||
- Keep buttons short; put consequences and recovery guidance in the supporting copy.
|
||||
@@ -0,0 +1,8 @@
|
||||
# Polish style guide (`pl`)
|
||||
|
||||
- Base bundle: direct, friendly `ty`, concise verbs, natural Polish word order.
|
||||
- Formal bundle: polite, gender-neutral constructions; avoid forcing `Pan/Pani` when an impersonal form is natural.
|
||||
- Prefer `projekt`, `zlecenie`, `oferta`, `faktura`, `odbiór`, `usterka`, `monter` and `tablica planowania` per the glossary.
|
||||
- Use Polish quotation marks „…”, correct diacritics and locale formatting (`pl-PL`).
|
||||
- Plurals must contain `one`, `few`, `many`, and `other`; test 0, 1, 2, 5, 21 and a decimal.
|
||||
- Destructive actions must state the object and consequence explicitly.
|
||||
@@ -0,0 +1,44 @@
|
||||
{
|
||||
"locale": "hu",
|
||||
"sourceLocale": "de",
|
||||
"sourceHashes": {
|
||||
"translations": "16aef502ee1eaef511b434a4a92772b30043e444c9305268975df322702a3b0f",
|
||||
"errors": "0141365c27bdc7f6f65c84127ff14db2487a2e9f375e59ae4c3314aa73a40dab",
|
||||
"mail": "ef4a7dd1bff1bd89b85b2fa1b98924d3022c8a97c68ad3dc28c8fabaf72ddc88",
|
||||
"common": "cf0b6c706669d92c5435c3731c66fcacfb95e8da987f80322f76a29b124060b7",
|
||||
"settings": "2bf765820cb3413b59b07f9e317f0665c8a43d9eb572536b345731d03ec82e0f",
|
||||
"billing": "3e24655ffb2db4c20fb63fc5568a4f2b133c6399417e6a059337899d66080a3f",
|
||||
"crm": "130b45f670c483a31b19309d77abaed94aff8d649568393e33a3025fa3121dcb",
|
||||
"auth": "756c2701e4f899c1a8e355693ca147c8470efc37c53ff4ec53424998ca3f37c6",
|
||||
"emailMarketing": "585dc34b82c89d22fc70e89949083be81b9ca7fe80640f5ed4eb9d73c9f6414e"
|
||||
},
|
||||
"machineTranslation": {
|
||||
"status": "complete",
|
||||
"provider": "Google Translate static build tool",
|
||||
"completedAt": "2026-08-02T13:53:30.944Z"
|
||||
},
|
||||
"automatedReview": {
|
||||
"status": "complete",
|
||||
"checkedAt": "2026-08-02T19:26:32Z",
|
||||
"checks": [
|
||||
"key parity",
|
||||
"protected-token integrity",
|
||||
"ICU plural categories",
|
||||
"Unicode NFC and mojibake",
|
||||
"source hash freshness"
|
||||
]
|
||||
},
|
||||
"nativeReview": {
|
||||
"status": "pending",
|
||||
"reviewer": null,
|
||||
"reviewedAt": null,
|
||||
"criticalSurfaces": [],
|
||||
"sampleSize": 0,
|
||||
"corrections": [],
|
||||
"releaseBlockers": ["Native speaker must verify and correct informal base tone, formal overrides, terminology and natural phrasing."]
|
||||
},
|
||||
"release": {
|
||||
"status": "disabled",
|
||||
"enabledEnvironments": []
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,44 @@
|
||||
{
|
||||
"locale": "pl",
|
||||
"sourceLocale": "de",
|
||||
"sourceHashes": {
|
||||
"translations": "16aef502ee1eaef511b434a4a92772b30043e444c9305268975df322702a3b0f",
|
||||
"errors": "0141365c27bdc7f6f65c84127ff14db2487a2e9f375e59ae4c3314aa73a40dab",
|
||||
"mail": "ef4a7dd1bff1bd89b85b2fa1b98924d3022c8a97c68ad3dc28c8fabaf72ddc88",
|
||||
"common": "cf0b6c706669d92c5435c3731c66fcacfb95e8da987f80322f76a29b124060b7",
|
||||
"settings": "2bf765820cb3413b59b07f9e317f0665c8a43d9eb572536b345731d03ec82e0f",
|
||||
"billing": "3e24655ffb2db4c20fb63fc5568a4f2b133c6399417e6a059337899d66080a3f",
|
||||
"crm": "130b45f670c483a31b19309d77abaed94aff8d649568393e33a3025fa3121dcb",
|
||||
"auth": "756c2701e4f899c1a8e355693ca147c8470efc37c53ff4ec53424998ca3f37c6",
|
||||
"emailMarketing": "585dc34b82c89d22fc70e89949083be81b9ca7fe80640f5ed4eb9d73c9f6414e"
|
||||
},
|
||||
"machineTranslation": {
|
||||
"status": "complete",
|
||||
"provider": "Google Translate static build tool",
|
||||
"completedAt": "2026-08-02T13:51:51.924Z"
|
||||
},
|
||||
"automatedReview": {
|
||||
"status": "complete",
|
||||
"checkedAt": "2026-08-02T19:26:32Z",
|
||||
"checks": [
|
||||
"key parity",
|
||||
"protected-token integrity",
|
||||
"ICU plural categories",
|
||||
"Unicode NFC and mojibake",
|
||||
"source hash freshness"
|
||||
]
|
||||
},
|
||||
"nativeReview": {
|
||||
"status": "pending",
|
||||
"reviewer": null,
|
||||
"reviewedAt": null,
|
||||
"criticalSurfaces": [],
|
||||
"sampleSize": 0,
|
||||
"corrections": [],
|
||||
"releaseBlockers": ["Native speaker must verify and correct informal base tone, formal overrides, terminology and natural phrasing."]
|
||||
},
|
||||
"release": {
|
||||
"status": "disabled",
|
||||
"enabledEnvironments": []
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,44 @@
|
||||
{
|
||||
"locale": "ru",
|
||||
"sourceLocale": "de",
|
||||
"sourceHashes": {
|
||||
"translations": "16aef502ee1eaef511b434a4a92772b30043e444c9305268975df322702a3b0f",
|
||||
"errors": "0141365c27bdc7f6f65c84127ff14db2487a2e9f375e59ae4c3314aa73a40dab",
|
||||
"mail": "ef4a7dd1bff1bd89b85b2fa1b98924d3022c8a97c68ad3dc28c8fabaf72ddc88",
|
||||
"common": "cf0b6c706669d92c5435c3731c66fcacfb95e8da987f80322f76a29b124060b7",
|
||||
"settings": "2bf765820cb3413b59b07f9e317f0665c8a43d9eb572536b345731d03ec82e0f",
|
||||
"billing": "3e24655ffb2db4c20fb63fc5568a4f2b133c6399417e6a059337899d66080a3f",
|
||||
"crm": "130b45f670c483a31b19309d77abaed94aff8d649568393e33a3025fa3121dcb",
|
||||
"auth": "756c2701e4f899c1a8e355693ca147c8470efc37c53ff4ec53424998ca3f37c6",
|
||||
"emailMarketing": "585dc34b82c89d22fc70e89949083be81b9ca7fe80640f5ed4eb9d73c9f6414e"
|
||||
},
|
||||
"machineTranslation": {
|
||||
"status": "complete",
|
||||
"provider": "Google Translate static build tool",
|
||||
"completedAt": "2026-08-02T13:52:02.016Z"
|
||||
},
|
||||
"automatedReview": {
|
||||
"status": "complete",
|
||||
"checkedAt": "2026-08-02T19:26:32Z",
|
||||
"checks": [
|
||||
"key parity",
|
||||
"protected-token integrity",
|
||||
"ICU plural categories",
|
||||
"Unicode NFC and mojibake",
|
||||
"source hash freshness"
|
||||
]
|
||||
},
|
||||
"nativeReview": {
|
||||
"status": "pending",
|
||||
"reviewer": null,
|
||||
"reviewedAt": null,
|
||||
"criticalSurfaces": [],
|
||||
"sampleSize": 0,
|
||||
"corrections": [],
|
||||
"releaseBlockers": ["Native speaker must verify and correct informal base tone, formal overrides, terminology and natural phrasing."]
|
||||
},
|
||||
"release": {
|
||||
"status": "disabled",
|
||||
"enabledEnvironments": []
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,44 @@
|
||||
{
|
||||
"locale": "uk",
|
||||
"sourceLocale": "de",
|
||||
"sourceHashes": {
|
||||
"translations": "16aef502ee1eaef511b434a4a92772b30043e444c9305268975df322702a3b0f",
|
||||
"errors": "0141365c27bdc7f6f65c84127ff14db2487a2e9f375e59ae4c3314aa73a40dab",
|
||||
"mail": "ef4a7dd1bff1bd89b85b2fa1b98924d3022c8a97c68ad3dc28c8fabaf72ddc88",
|
||||
"common": "cf0b6c706669d92c5435c3731c66fcacfb95e8da987f80322f76a29b124060b7",
|
||||
"settings": "2bf765820cb3413b59b07f9e317f0665c8a43d9eb572536b345731d03ec82e0f",
|
||||
"billing": "3e24655ffb2db4c20fb63fc5568a4f2b133c6399417e6a059337899d66080a3f",
|
||||
"crm": "130b45f670c483a31b19309d77abaed94aff8d649568393e33a3025fa3121dcb",
|
||||
"auth": "756c2701e4f899c1a8e355693ca147c8470efc37c53ff4ec53424998ca3f37c6",
|
||||
"emailMarketing": "585dc34b82c89d22fc70e89949083be81b9ca7fe80640f5ed4eb9d73c9f6414e"
|
||||
},
|
||||
"machineTranslation": {
|
||||
"status": "complete",
|
||||
"provider": "Google Translate static build tool",
|
||||
"completedAt": "2026-08-02T13:52:24.903Z"
|
||||
},
|
||||
"automatedReview": {
|
||||
"status": "complete",
|
||||
"checkedAt": "2026-08-02T19:26:32Z",
|
||||
"checks": [
|
||||
"key parity",
|
||||
"protected-token integrity",
|
||||
"ICU plural categories",
|
||||
"Unicode NFC and mojibake",
|
||||
"source hash freshness"
|
||||
]
|
||||
},
|
||||
"nativeReview": {
|
||||
"status": "pending",
|
||||
"reviewer": null,
|
||||
"reviewedAt": null,
|
||||
"criticalSurfaces": [],
|
||||
"sampleSize": 0,
|
||||
"corrections": [],
|
||||
"releaseBlockers": ["Native speaker must verify and correct informal base tone, formal overrides, terminology and natural phrasing."]
|
||||
},
|
||||
"release": {
|
||||
"status": "disabled",
|
||||
"enabledEnvironments": []
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
# Russian style guide (`ru`)
|
||||
|
||||
- Base bundle: direct, friendly `ты`; avoid bureaucratic calques.
|
||||
- Formal bundle: consistently polite `вы`, capitalized only where natural in direct address.
|
||||
- Prefer `проект`, `заказ`, `коммерческое предложение`, `счёт`, `приёмка`, `дефект`, `монтажник` and `доска планирования`.
|
||||
- Use Russian quotation marks «…», Cyrillic text and locale formatting (`ru-RU`).
|
||||
- Plurals must contain `one`, `few`, `many`, and `other`; test 0, 1, 2, 5, 21 and a decimal.
|
||||
- Keep concise UI labels; explain irreversible outcomes in dialogs and errors.
|
||||
@@ -0,0 +1,8 @@
|
||||
# Ukrainian style guide (`uk`)
|
||||
|
||||
- Base bundle: direct, friendly `ти`, written in natural contemporary Ukrainian.
|
||||
- Formal bundle: consistently polite `ви`; avoid Russian calques.
|
||||
- Prefer `проєкт`, `замовлення`, `комерційна пропозиція`, `рахунок`, `приймання`, `недолік`, `монтажник` and `дошка планування`.
|
||||
- Use Ukrainian quotation marks «…», the letters `і`, `ї`, `є`, `ґ` correctly and locale formatting (`uk-UA`).
|
||||
- Plurals must contain `one`, `few`, `many`, and `other`; test 0, 1, 2, 5, 21 and a decimal.
|
||||
- Errors and destructive actions should be concrete, calm and actionable.
|
||||
@@ -24,7 +24,7 @@ explains:
|
||||
| Lint rules | `eslint-plugin-jsx-a11y` (`plugin:jsx-a11y/recommended`) | `pnpm lint` |
|
||||
| Brand-token contrast | `scripts/verify-color-contrast.mjs` (zero-dep, fails CI on regress) | `pnpm verify:color-contrast` |
|
||||
| Browser-level WCAG sweep | `@axe-core/playwright` | `pnpm verify:e2e-a11y` |
|
||||
| CI gate | `.github/workflows/a11y.yml` + `.gitea/workflows/a11y.yml` | every PR + push to main |
|
||||
| CI gate | `.gitea/workflows/a11y.yml` | manual deep audit; fast contracts remain in default CI |
|
||||
| Keyboard "skip to content" | `apps/web/app/components/core/SkipToContent.tsx` | rendered in `AppLayout` |
|
||||
|
||||
Browser-level mobile public coverage includes landing, legal pages, error
|
||||
@@ -234,7 +234,7 @@ requires tenant credentials plus `E2E_TENANT_DASHBOARD_PATH`,
|
||||
`E2E_WORKFLOW_RUN_MANUAL_PATH`, `E2E_WORKFLOW_WEBHOOK_RUN_MANUAL_PATH`, and
|
||||
`PLUGIN_BINARY_BASE_PATH`, and turns
|
||||
missing inputs or unavailable 400/403/404/login responses into failures.
|
||||
Scheduled GitHub/Gitea readiness workflows run this contract against staging
|
||||
The scheduled Gitea readiness workflow runs this contract against staging
|
||||
with `E2E_BROWSER_MATRIX=1`, `E2E_A11Y_STRICT=1`, and
|
||||
`E2E_ALLOW_WORKFLOW_RUN=1`.
|
||||
Legacy-Provider/provider-live paths and mutating account/workflow actions stay separately
|
||||
|
||||
@@ -42,6 +42,74 @@ The defaults apply to application data, operational evidence, generated artifact
|
||||
| Audit, impersonation, and security events | Security and audit evidence | Keep restricted audit trails needed for security investigation and accountability; minimize actor/target personal fields and apply access controls. | Add audit retention basis, impersonation review, access logging, and redacted export behavior. |
|
||||
| Plugin-candidate surfaces | Plugin-candidate review | Treat knowledge-base, workflow, app-engine, form, portal, site, prompt/AI, help-desk, analytics, feature-flag, onboarding, and similar candidate data as personal until classified. | Require per-candidate classification before migration, export, deletion, pause/resume, or provider sync work. |
|
||||
|
||||
## Tenant hard-delete: what survives (AK-P21, decided 2026-07-21)
|
||||
|
||||
The tenant hard-delete erases processor data (GDPR Art. 28(3)(g)); the tenant is
|
||||
the controller for it and secures its own retention obligations through the
|
||||
export offered before deletion. A small set of rows survives because HiveGrid is
|
||||
the controller for them under its own legal basis. Those rows are kept, but
|
||||
their free-text personal data is stripped in the `tenant.minimize-retained-pii`
|
||||
step of the deletion job.
|
||||
|
||||
| Surface | Basis for keeping it | Retention period | What is minimized |
|
||||
| --- | --- | --- | --- |
|
||||
| Support tickets and their messages | GDPR Art. 6(1)(f) — defence against claims (§ 195 BGB) | 3 years after tenant erasure, then purged | Subject, message, message bodies, sender email, source URL |
|
||||
| In-app feedback | GDPR Art. 6(1)(f) — defence against claims | 3 years after tenant erasure, then purged | Message, source URL |
|
||||
| Impersonation audit | GDPR Art. 5(2) accountability + Art. 32 security | Indefinite | Nothing to minimize — carries identifiers and timestamps only |
|
||||
| Audit events and hash-chain checkpoints | Integrity of the tamper-evident audit trail | Per audit retention policy | Tenant row is reduced to an anonymized skeleton so foreign keys stay valid |
|
||||
|
||||
These entries must be mirrored in the record of processing activities; the code
|
||||
side is enforced by `TENANT_DELETION_RETAINED_MODELS` and the lifecycle/grant
|
||||
parity test. The 3-year period is enforced by the tenant-deletion cron: each
|
||||
daily pass also erases the retained support rows of tenants whose hard delete
|
||||
completed longer ago than `GDPR_SUPPORT_RETENTION_DAYS`.
|
||||
|
||||
## Feedback attachments (AK-P21, decided 2026-07-21)
|
||||
|
||||
The in-app feedback widget originally specified a "screenshot checkbox". That
|
||||
was **deliberately not built**. Instead the reporter attaches an image
|
||||
themselves.
|
||||
|
||||
Rationale: a client-side capture of the current page routinely contains
|
||||
personal data of **third parties** (contacts, projects) that the reporter never
|
||||
consciously selected, and moves it from the tenant (controller) to the platform
|
||||
operator. Letting the reporter pick the file keeps the disclosure a conscious
|
||||
act and satisfies data minimisation (Art. 5(1)(c)).
|
||||
|
||||
Contract:
|
||||
|
||||
| Aspect | Rule |
|
||||
| --- | --- |
|
||||
| Who captures | The reporter. The client never rasterises or screen-captures on its own. |
|
||||
| Accepted | One image per feedback (PNG, JPEG, WebP, GIF), max 5 MB. |
|
||||
| Rate limit | Inherited from the feedback widget: 3 submissions per 24 h. |
|
||||
| Malware | Untrusted upload: fail-closed magic-bytes allow-list before the storage PUT, then ClamAV via the file-scan queue (`infra/STANDARDS.md` §13). The file stays `scanStatus=pending` until the worker clears it. |
|
||||
| Storage | Regular tenant-scoped `File` plus a `FileEntityLink` with `entityType=support_ticket`. Tenant-less feedback cannot carry an attachment, because `File.tenantId` is `NOT NULL`. |
|
||||
| Retention | Follows the support ticket it belongs to (3 years, see the table above). Revisit if attachments turn out to carry more third-party data than the ticket text. |
|
||||
|
||||
### Operator access to an attachment
|
||||
|
||||
The tenant media proxy (`app/:tenant/media/...`) cannot serve these files: a
|
||||
platform operator is not necessarily a member of the tenant that owns the file,
|
||||
so that route's membership check denies it. Operators therefore have their own
|
||||
route, `admin/support/attachments/:ticketId/:fileId`, which is deliberately
|
||||
narrower than a general operator file proxy.
|
||||
|
||||
| Aspect | Rule |
|
||||
| --- | --- |
|
||||
| Scope | Serves only a file that is linked to the named support ticket. It can never address an arbitrary tenant file. |
|
||||
| Identity | Platform-admin only. |
|
||||
| Scan gate | Fail-closed: only an explicit `clean` verdict is deliverable, so an operator cannot open a file ClamAV has not yet cleared. |
|
||||
| Tenant binding | `FileEntityLink` has no operator escape in its RLS policy, so the lookup binds the owning tenant via `withTenantRLS`. |
|
||||
| Delivery | 302 to a short-lived signed URL (AD-23); the bucket stays private. |
|
||||
| Audit | Every download is an `admin.support.attachmentDownloaded` AuditEvent, written **before** the URL is issued. A read that cannot be audited is refused. |
|
||||
| Denials | Always 404, never 403 (Bauprinzip A.5.3), and with an empty body, so probing ids reveals nothing. |
|
||||
|
||||
The audit entry carries no operator-typed reason: unlike the destructive
|
||||
operator actions, this is a read reached by clicking the file in the ticket the
|
||||
operator is already working. If that turns out to be too weak a control, the
|
||||
next step is a mandatory reason prompt on the link, not a change to the route.
|
||||
|
||||
## Erasure and deletion handling
|
||||
|
||||
- Deletion workflows must distinguish active product records, soft-deleted records, generated artifacts, provider-held data, and restricted audit/accounting exceptions.
|
||||
|
||||
@@ -15,11 +15,49 @@ Database operations are driven by key names only. Documentation, issues, CI logs
|
||||
|
||||
Required or relevant keys:
|
||||
|
||||
- `DATABASE_URL`: Prisma PostgreSQL connection setting used by migration status, migration deploy, runtime database access, and local development.
|
||||
- `DIRECT_URL`: optional direct Prisma connection setting for maintenance flows when the deployment environment requires a separate direct connection.
|
||||
- `DATABASE_URL`: Prisma-Verbindung der jeweiligen Runtime. Core-Web/API/MCP/Hocuspocus nutzen `hivegrid_app`, das Customer-Portal nutzt `hivegrid_portal`, Worker nutzen `hivegrid_worker`.
|
||||
- `DIRECT_URL`: direkte, ungepoolte Verbindung des kurzlebigen Migrationsprozesses als `hivegrid_migrator`; sie gehört in keine Runtime.
|
||||
- `AUTHENTIK_ADMIN_JIT_DATABASE_URL`: separate PgBouncer-Verbindung als `hivegrid_authentik_jit`; ausschließlich für den verifizierten Authentik-Callback im Web-Resource.
|
||||
- `HIVEGRID_RLS_PROVISION_DATABASE_URL`: direkte Superuser-Verbindung ausschließlich für die einmalige oder bewusst wiederholte Rollen-Provisionierung.
|
||||
- `HIVEGRID_RLS_MIGRATOR_PASSWORD`, `HIVEGRID_RLS_APP_PASSWORD`, `HIVEGRID_RLS_PORTAL_PASSWORD`, `HIVEGRID_RLS_WORKER_PASSWORD`, `HIVEGRID_RLS_AUTHENTIK_JIT_PASSWORD`: fünf unterschiedliche, mindestens 32 Zeichen lange Secrets aus dem freigegebenen Secret-Store.
|
||||
|
||||
Operators should confirm that the required key names exist in the target secret store, CI setting, or platform environment. Do not paste raw values into tickets, chat, docs, screenshots, or verifier output.
|
||||
|
||||
## PostgreSQL-Rollen und Provisionierung
|
||||
|
||||
HiveGrid verwendet sechs getrennte Rollen:
|
||||
|
||||
| Rolle | Zweck | Sicherheitsvertrag |
|
||||
| ---------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
|
||||
| `hivegrid_migrator` | Eigentümer von Datenbank, `public`-Schema und den normalen Anwendungsobjekten; führt Prisma-Migrationen aus | `LOGIN`, kein Superuser, kein `BYPASSRLS`, kein `INHERIT` |
|
||||
| `hivegrid_app` | Web-, API-, MCP- und Hocuspocus-Runtime | `LOGIN`, kein Superuser, kein `BYPASSRLS`, kein `INHERIT` |
|
||||
| `hivegrid_portal` | Isolierte Customer-Portal-Runtime mit expliziten Portal-/Projektfreigaben | `LOGIN`, kein Superuser, kein `BYPASSRLS`, kein `INHERIT`, keine Mitgliedschaften |
|
||||
| `hivegrid_worker` | Worker-Runtime | `LOGIN`, kein Superuser, kein `BYPASSRLS`, kein `INHERIT` |
|
||||
| `hivegrid_authentik_jit` | Verifizierter Authentik-Callback im Web; nur JIT-Admin-Capability | `LOGIN`, keine Tabellen-/Sequenzrechte oder Mitgliedschaft |
|
||||
| `hivegrid_rls_definer` | Eigentümer der explizit geprüften `SECURITY DEFINER`-Funktionen | `NOLOGIN`, `BYPASSRLS`, sonst keine administrativen Rechte |
|
||||
|
||||
Die einzige zulässige Mitgliedschaft ist `hivegrid_migrator` als Mitglied von `hivegrid_rls_definer`, mit `SET TRUE`, aber ohne `ADMIN` und ohne vererbte Rechte. App, Portal, Worker und Authentik-JIT dürfen weder Mitglied der Definer-Rolle noch einer anderen Rolle sein.
|
||||
|
||||
Die Rollen werden vor der ersten Migration und bei einer kontrollierten Passwortrotation idempotent provisioniert:
|
||||
|
||||
```sh
|
||||
pnpm run db:roles:provision
|
||||
```
|
||||
|
||||
Der Befehl verlangt die Provisionierungs-URL und alle fünf Passwort-Keys, gibt keine URL und kein Passwort aus und bricht ohne Superuser-Verbindung ab. Er setzt die Rollenattribute auf den exakten Vertrag zurück, entfernt unerwartete Mitgliedschaften, erzwingt SCRAM-Passwort-Hashes und prüft den Zustand vor dem Commit. Bei einem Fehler wird die Transaktion zurückgerollt.
|
||||
|
||||
Der Provisionierer überträgt die aktuelle Datenbank, das `public`-Schema und vorhandene, nicht zu einer Extension gehörende Anwendungsobjekte an `hivegrid_migrator`. Deshalb darf er nur gegen die dedizierte HiveGrid-Datenbank und bei bestehenden Installationen erst nach Backup und bestätigtem Restore-Pfad ausgeführt werden. Extension-Objekte behalten bewusst ihren bisherigen Eigentümer.
|
||||
|
||||
Sicherer Ablauf für eine neue Datenbank:
|
||||
|
||||
1. Datenbank anlegen und die sechs Rollen mit `pnpm run db:roles:provision` provisionieren.
|
||||
2. `DIRECT_URL` ausschließlich im kurzlebigen Migrationsprozess auf `hivegrid_migrator` setzen.
|
||||
3. Mit `pnpm run verify:migrator-role` den tatsächlichen Session-User, die nicht privilegierten Rollenattribute und die einzige erlaubte Definer-Mitgliedschaft prüfen.
|
||||
4. Das freigegebene, unveränderliche Web-Image einmalig im `migrate`-Modus starten (`/myapp/start.sh migrate`). Dieser Pfad führt Rollenprüfung, Prisma-Migrationen und den globalen Permission-Reconcile als eine fail-closed Deploy-Kette aus.
|
||||
5. Runtimes nur mit `hivegrid_app`, `hivegrid_portal` beziehungsweise `hivegrid_worker` starten. Die separate JIT-URL kommt ausschließlich in die Core-Web-Resource; Portal, API, MCP, Hocuspocus, Worker und Migrator erhalten keine Admin-SSO-Secrets.
|
||||
|
||||
Bei einer bestehenden Datenbank müssen vor Schritt 1 alle laufenden Schreiber angehalten oder in ein freigegebenes Cutover-Fenster gebracht werden. Nach der Migration sind Rollenattribute, Objekt-Ownership und Tenant-A/B-Isolation zu prüfen, bevor der Traffic wieder freigegeben wird.
|
||||
|
||||
## Local PostgreSQL and Prisma workflow
|
||||
|
||||
For local development, follow `docs/local-dev.md` first. Start a local PostgreSQL instance, create a disposable local database, set `DATABASE_URL` to a local placeholder value, and keep production credentials out of local files.
|
||||
@@ -51,13 +89,25 @@ A passing migration-status gate means the status command completed. It does not
|
||||
|
||||
## Production migration deployment
|
||||
|
||||
Production migration deployment uses the package-level deployment command:
|
||||
Production migration deployment uses the immutable web image's one-shot entrypoint:
|
||||
|
||||
```sh
|
||||
pnpm run db:migrate:deploy
|
||||
/myapp/start.sh migrate
|
||||
```
|
||||
|
||||
Run this only in the approved deployment path for the target environment, with the environment's secret store providing `DATABASE_URL` and any required `DIRECT_URL`. The command applies already-authored Prisma migrations; it is not a schema authoring workflow and must not be mixed with local-only commands such as `pnpm exec prisma migrate dev` or `pnpm exec prisma db push`.
|
||||
Run this only inside the approved one-shot container for the target environment. `DIRECT_URL` must be the unpooled connection that authenticates directly as `hivegrid_migrator` and must be scoped to that short-lived migration process. A superuser URL, a URL that reaches the role through `SET ROLE`, or any drift in the required role attributes and membership is forbidden. The bare package command `pnpm run db:migrate:deploy` is not an approved production path because it omits the mandatory post-migration permission reconcile.
|
||||
|
||||
The deployed web image runs `pnpm run verify:migrator-role` from `start.sh migrate` before it exposes the URL to Prisma. The probe fails closed unless both `session_user` and `current_user` are exactly `hivegrid_migrator`, the role is `LOGIN` but not superuser and cannot create databases or roles, inherit, replicate, or bypass RLS, and its only role edge is the constrained membership in `hivegrid_rls_definer`. The entrypoint then applies the migrations and reconciles the global permission catalog before it can exit successfully. None of these steps prints the connection string.
|
||||
|
||||
The one-shot migration path applies already-authored Prisma migrations; it is not a schema authoring workflow and must not be mixed with local-only commands such as `pnpm exec prisma migrate dev` or `pnpm exec prisma db push`.
|
||||
|
||||
### Globaler Permission-Reconcile nach Migrationen
|
||||
|
||||
Der freigegebene Containerpfad `start.sh migrate` führt erst nach einem erfolgreichen `prisma migrate deploy` den gebündelten Reconcile aus. Er gleicht ausschließlich den globalen `Permission`-Katalog, die globalen Defaultrollen (`tenantId IS NULL`) und deren katalogeigene Verknüpfungen ab. Der allein aufgerufene Package-Befehl `pnpm run db:migrate:deploy` enthält diesen Post-Migration-Schritt nicht.
|
||||
|
||||
Der Reconcile läuft fail-closed in einer kurzen Datenbanktransaktion. `hivegrid_rls_definer` erhält darin nur temporär die erforderlichen DML-Rechte; vor dem Commit werden sie wieder entzogen. `FORCE ROW LEVEL SECURITY` bleibt aktiv. Fehler bei Sicherheitsprüfung, Abgleich oder Daten-Postcondition rollen Daten und ACL-Änderungen dieser Transaktion zurück und stoppen den Deploy.
|
||||
|
||||
AD-29 schützt tenant-eigene Rollen und alle Rollen mit `isTemplateOrigin = true`: Sie werden im automatischen Deploy niemals angelegt, geändert, gelöscht oder mit Berechtigungen nachgezogen. Ist eine kanonische globale Rolle als Template-Ursprung markiert, bricht der Reconcile vor Rollen-DML fail-closed ab; Tenant-Rollen bleiben unberührt. Änderungen an Bestands-Tenants erfordern eine explizit freigegebene, auditierte Operator-Aktion. Allgemeines Seeding bleibt unter erzwungener RLS verboten; der globale Reconcile ist keine Seed-Freigabe.
|
||||
|
||||
Before deploying, confirm that the intended migration set has passed review and that the CI migration-status gate is healthy. After deployment, inspect the approved deployment logs and the migration-status verifier output for redacted success or failure signals. If deployment fails, do not paste connection details or table contents into the incident record; capture the command name, exit code, diagnostic phase, and sanitized Prisma excerpt only.
|
||||
|
||||
@@ -86,7 +136,7 @@ Generation does not connect to production data and must not be treated as a migr
|
||||
Use these safe inspection surfaces for database failures:
|
||||
|
||||
- CI logs from `pnpm run verify:db-migrate-status` with sanitized stdout and stderr excerpts.
|
||||
- Approved deployment logs for `pnpm run db:migrate:deploy` with secrets redacted.
|
||||
- Approved deployment logs from the immutable web image's `/myapp/start.sh migrate` one-shot path, with secrets redacted.
|
||||
- Local command output from `pnpm exec prisma migrate status` against a disposable local PostgreSQL database.
|
||||
- Package script names, exit codes, diagnostic phases, and redacted Prisma error codes.
|
||||
- `docs/db-ci.md` for the CI status verifier contract and `docs/local-dev.md` for local setup checks.
|
||||
@@ -95,8 +145,8 @@ Common failure patterns:
|
||||
|
||||
- Missing `DATABASE_URL`: confirm that the key exists in the CI secret or platform environment and is scoped only to the database operation that needs it.
|
||||
- Connection or authentication failure: confirm the secret store and database service health without copying the value, username, password, host, or database name into logs.
|
||||
- Migration drift: run the status gate, inspect the sanitized Prisma status message, and distinguish read-only status output from deploy behavior before deciding on `pnpm run db:migrate:deploy`.
|
||||
- Migration drift: run the status gate, inspect the sanitized Prisma status message, and distinguish read-only status output from deploy behavior before deciding whether to invoke the approved `/myapp/start.sh migrate` one-shot path.
|
||||
- Stale Prisma client: run `pnpm run db:generate` and re-run the focused check that reported stale generated artifacts.
|
||||
- Local schema mismatch: use local-only `pnpm exec prisma migrate status`, `pnpm exec prisma migrate dev`, or a deliberate disposable `pnpm exec prisma db push` according to `docs/local-dev.md`.
|
||||
|
||||
If any troubleshooting output reveals a connection string, credential, hostname, username, password, database name, or customer data, treat it as a secret leak. Remove the exposed material from the shared surface, rotate affected credentials, preserve only redacted evidence, and fix the logging or documentation path before continuing.
|
||||
If any troubleshooting output reveals a connection string, credential, hostname, username, password, database name, or customer data, treat it as a secret leak. Remove the exposed material from the shared surface, rotate affected credentials, preserve only redacted evidence, and fix the logging or documentation path before continuing.
|
||||
@@ -31,7 +31,55 @@ The verifier fails before spawning Prisma when `DATABASE_URL` is absent. It does
|
||||
|
||||
The Gitea workflow includes a `database` job that depends on `quality`. The job installs dependencies with the pinned pnpm setup, generates the database client through `@hivegrid/db`, and then runs the non-E2E status verifier.
|
||||
|
||||
The database job runs migration status only. It must not run `migrate deploy`, seed commands, browser automation, or E2E checks.
|
||||
The database job generates the Prisma client, verifies the generated
|
||||
tenant-policy contract and migration/schema parity, runs the ephemeral
|
||||
live-RLS gate, checks migration status outside pull requests, and executes the
|
||||
database package tests. It must not run `migrate deploy`, seed commands,
|
||||
browser automation, or browser E2E checks.
|
||||
|
||||
## Live-RLS-Gate
|
||||
|
||||
Der getrennte Gate-Befehl
|
||||
|
||||
```sh
|
||||
pnpm run verify:rls-live
|
||||
```
|
||||
|
||||
startet eine wegwerfbare PostgreSQL-16-Instanz und beweist den vollständigen
|
||||
Rollenvertrag. Er provisioniert `hivegrid_migrator`, `hivegrid_app`,
|
||||
`hivegrid_portal`, `hivegrid_worker`, `hivegrid_authentik_jit` und
|
||||
`hivegrid_rls_definer`, entzieht dem Migrator in einer
|
||||
separaten Negativ-Datenbank absichtlich die Definer-Mitgliedschaft und erwartet
|
||||
dort einen harten Migrationsfehler. Anschließend provisioniert er den korrekten
|
||||
Vertrag erneut, spielt die gesamte Migration-Historie als nicht privilegierter
|
||||
`hivegrid_migrator` auf eine frische Datenbank und führt die echten
|
||||
App-/Portal-/Worker-Isolationstests aus.
|
||||
|
||||
Damit prüft das Gate ausdrücklich nicht nur RLS zur Laufzeit, sondern auch,
|
||||
dass Migrationen keinen Superuser und kein `BYPASSRLS` auf dem Migrator
|
||||
benötigen. Die Testpasswörter sind nur lokale, kurzlebige Fixtures und werden
|
||||
nicht ausgegeben. Produktions-Secrets dürfen diesem Gate niemals übergeben
|
||||
werden.
|
||||
|
||||
Das statische Gegenstück ist:
|
||||
|
||||
```sh
|
||||
pnpm run verify:tenant-policy-contract
|
||||
pnpm run verify:rls-release-readiness
|
||||
```
|
||||
|
||||
Der erste Befehl verhindert Drift zwischen Scope-Manifest, fachlichem
|
||||
Policy-Vertrag, generiertem SQL-Artefakt und Cutover-Migration. Der zweite
|
||||
prüft, ob jedes laut Manifest RLS-pflichtige Modell in den auslieferbaren
|
||||
Migrationen `ENABLE`, `FORCE` und eine kanonische Policy besitzt. Ein grüner
|
||||
statischer Check ersetzt den Live-Test nicht; der Live-Test ersetzt wiederum
|
||||
keinen Staging-/Produktions-Cutover mit den echten Rollen, Secrets,
|
||||
Bestandsdaten und PgBouncer-/Coolify-Einstellungen.
|
||||
|
||||
Der aktuelle Implementierungs- und Operations-Handoff steht in
|
||||
[`security/RLS-HARDENING-2026-07-13.md`](security/RLS-HARDENING-2026-07-13.md).
|
||||
Dort ist der Produktions-Rollout ausdrücklich als noch nicht nachgewiesen
|
||||
markiert.
|
||||
|
||||
## Status outcomes
|
||||
|
||||
|
||||
@@ -1,54 +0,0 @@
|
||||
# DB Legacy Boundary: apps/web/app/utils/db
|
||||
|
||||
This document defines the durable legacy boundary for `apps/web/app/utils/db/` while database ownership continues to migrate into the workspace DB package. It is intended as the first stop for future slices that add, move, or review files in this directory.
|
||||
|
||||
## Scope
|
||||
|
||||
`apps/web/app/utils/db/` is a legacy server-only database helper area. Files in this tree may contain database access helpers, persistence-oriented business queries, seed-adjacent helpers, and server-side type glue needed by routes or services that have not yet moved to `@hivegrid/db`.
|
||||
|
||||
The directory is not a UI layer, component layer, route module, browser bundle entrypoint, or markup rendering boundary. Treat every file under `apps/web/app/utils/db/**/*.ts` as server-only application infrastructure until it is migrated or deleted.
|
||||
|
||||
## Allowed DB and Type Imports
|
||||
|
||||
Code in `apps/web/app/utils/db/` may import DB-safe types and helpers when they preserve the server-only boundary:
|
||||
|
||||
- Prisma browser/type boundary imports from `@hivegrid/db/prisma-browser` are allowed for type-safe model enums and generated Prisma types that are intentionally safe to reference outside the generated client runtime.
|
||||
- Server package helpers from `@hivegrid/db/* .server` modules are allowed when the importing file remains server-only and does not expose those helpers to browser code.
|
||||
- Local server utilities, validation helpers, and framework request/session types may be used when they support DB access and do not pull UI dependencies into this tree.
|
||||
|
||||
Do not restate or depend on generated-client internals here. Prefer package-level exports from `@hivegrid/db` over deep generated-client paths.
|
||||
|
||||
## Disallowed UI, React, and Markup Patterns
|
||||
|
||||
Files under `apps/web/app/utils/db/` must not introduce UI or markup responsibilities. In particular, `apps/web/app/utils/db/**/*.ts` must not contain:
|
||||
|
||||
- `.tsx` files anywhere in the directory tree.
|
||||
- React imports, including `react`, `react/jsx-runtime`, `@remix-run/react`, React component libraries, or UI package component imports.
|
||||
- JSX elements or fragments such as `<div>`, `<Component />`, `<>...</>`, or any returned JSX tree.
|
||||
- HTML/markup construction that belongs in UI code, especially `dangerouslySetInnerHTML`.
|
||||
- Browser-only DOM APIs used for rendering, hydration, or component behavior.
|
||||
|
||||
If a DB helper needs to return display content, return plain data, identifiers, or normalized strings. Route modules and UI components are responsible for rendering that data.
|
||||
|
||||
## Existing Server-Only Constraints
|
||||
|
||||
The legacy boundary assumes server execution. Keep database calls behind server-only modules, use ORM-safe or parameterized access patterns, and validate request-derived values before they reach DB filters or identifiers.
|
||||
|
||||
Do not make `apps/web/app/utils/db/` importable by client components or shared browser bundles. If a helper is required from both server and browser code, split the safe type-only contract into a package/type module and keep the DB implementation in a `.server` module.
|
||||
|
||||
## Checklist for Changes Under apps/web/app/utils/db
|
||||
|
||||
Before adding or changing a file under `apps/web/app/utils/db/`, verify the following:
|
||||
|
||||
1. The file is `.ts`, not `.tsx`.
|
||||
2. The code has no React, UI component, route-rendering, JSX, fragment, or `dangerouslySetInnerHTML` usage.
|
||||
3. Imports use accepted DB/type boundaries such as `@hivegrid/db/prisma-browser` or server helpers from `@hivegrid/db/* .server` rather than generated-client internals.
|
||||
4. Inputs from URL params, query params, request bodies, environment variables, or DB identifiers are validated or normalized before DB access.
|
||||
5. The helper returns data, not rendered markup.
|
||||
6. Any remaining migration concern is documented in the caller or follow-up plan instead of weakening this boundary.
|
||||
|
||||
## Future Migration Notes
|
||||
|
||||
Future slices should move stable DB ownership toward `@hivegrid/db` server modules and leave `apps/web/app/utils/db/` as a shrinking compatibility layer. When moving code, preserve the accepted Prisma browser/type boundary for safe types and keep runtime database clients inside server-only modules.
|
||||
|
||||
Static guards for this slice should fail loudly with the violating path and reason whenever `.tsx`, React imports, JSX/HTML indicators, or `dangerouslySetInnerHTML` appear in `apps/web/app/utils/db/`.
|
||||
@@ -0,0 +1,195 @@
|
||||
# Normale Rhein-Main-Staging-Daten für `demo-pro-crm`
|
||||
|
||||
Der Seed baut den Staging-Tenant als synthetischen SHK-Betrieb mit 50 Mitarbeitern
|
||||
(17 im Büro, 33 im Baustellen-/Kundendienst), 783 Kontakten, 537 Projekten und den
|
||||
dazugehörigen operativen Datensätzen auf. Die 33 Feldmitarbeiter arbeiten in 15
|
||||
Zweier-Kolonnen und einer Dreier-Kolonne. Das Büro besteht aus Geschäftsführung
|
||||
(1), Vertriebsleitung (1), Vertrieb (3), Backoffice (4), Marketing (1) und
|
||||
Projekt-/Bauleitung (7). Der Seed ist bewusst **nicht** an `SEED_ON_BOOT` gekoppelt.
|
||||
|
||||
Die fachlichen Datensätze werden dabei wie normale Betriebsdaten gespeichert
|
||||
(`isDemoData=false`). Der technische Slug bindet den Reset an den richtigen Tenant;
|
||||
deterministische IDs und interne Import-Metadaten halten die Herkunft nachvollziehbar.
|
||||
Kontakte, Projekte, Aufgaben und Dateien müssen deshalb ohne `demo=show` oder einen
|
||||
Demo-Schalter sichtbar sein.
|
||||
|
||||
Der Staging-Deploy setzt auf dem Web-Resource zusätzlich
|
||||
`SEED_DEMO_PRO_MANAGED=true`. Dadurch überspringt der bestehende Boot-Demo-Seed
|
||||
`demo-pro-crm` vollständig: Er verändert dort weder Mitgliedschaften noch Plan,
|
||||
ProductCore, Buchungen, Projekte oder Automationen. Starter und Business bleiben im
|
||||
bisherigen Boot-Seed. Das Flag darf nicht auf Production gesetzt werden und muss auf
|
||||
Staging aktiv bleiben, damit spätere Deploys den hier verifizierten Pro-Datensatz nicht
|
||||
wieder mit Legacy-Fixtures vermischen.
|
||||
|
||||
## Bedienung
|
||||
|
||||
```bash
|
||||
pnpm seed:demo-pro --dry-run
|
||||
|
||||
SENTRY_ENVIRONMENT=staging \
|
||||
SEED_DEMO_PRO_ALLOWED=true \
|
||||
SEED_DEMO_PRO_EXPECTED_TENANT_ID='<exakte-staging-tenant-id>' \
|
||||
SEED_DEMO_PRO_EXPECTED_DATABASE='<exakter-staging-datenbankname>' \
|
||||
SEED_DEMO_PRO_EXPECTED_DATABASE_HOST='<exakter-host:port>' \
|
||||
SEED_DEMO_PRO_EXPECTED_STORAGE_BUCKET='hivegrid-staging-media' \
|
||||
SEED_DEMO_PRO_EXPECTED_STORAGE_ENDPOINT='<exakter-staging-s3-endpoint>' \
|
||||
SEED_DEMO_PRO_WORKERS_DRAINED=true \
|
||||
SEED_DEMO_PRO_OUTBOUND_SANDBOX=true \
|
||||
SEED_DEMO_USER_PASSWORD='<starkes-zufaelliges-secret-aus-dem-secret-store>' \
|
||||
pnpm seed:staging-data --apply --confirm=demo-pro-crm
|
||||
|
||||
SENTRY_ENVIRONMENT=staging pnpm seed:demo-pro --verify
|
||||
|
||||
SENTRY_ENVIRONMENT=staging \
|
||||
SEED_DEMO_PRO_ALLOWED=true \
|
||||
SEED_DEMO_PRO_EXPECTED_TENANT_ID='<exakte-staging-tenant-id>' \
|
||||
SEED_DEMO_PRO_EXPECTED_DATABASE='<exakter-staging-datenbankname>' \
|
||||
SEED_DEMO_PRO_EXPECTED_DATABASE_HOST='<exakter-host:port>' \
|
||||
SEED_DEMO_PRO_EXPECTED_STORAGE_BUCKET='hivegrid-staging-media' \
|
||||
SEED_DEMO_PRO_EXPECTED_STORAGE_ENDPOINT='<exakter-staging-s3-endpoint>' \
|
||||
SEED_DEMO_PRO_WORKERS_DRAINED=true \
|
||||
SEED_DEMO_PRO_OUTBOUND_SANDBOX=true \
|
||||
pnpm seed:staging-data --cleanup --confirm=demo-pro-crm
|
||||
```
|
||||
|
||||
`apply` und `cleanup` verweigern jeden anderen Tenant sowie jede Umgebung außer
|
||||
Staging. Zusätzlich müssen Tenant-ID, Datenbankname, Datenbank-Host mit Port,
|
||||
S3-Provider, Bucket und Endpoint mit den im Staging-Secret-Store hinterlegten
|
||||
Bindings exakt übereinstimmen. Lokaler Storage und fremde S3-Buckets werden vor
|
||||
der ersten Mutation abgelehnt. Der
|
||||
Apply-Lauf wartet standardmäßig bis zu 300 Sekunden auf die
|
||||
Search-Outbox. `SEED_DEMO_PRO_WAIT_MS` ist nur für lokale Integrationsprüfungen
|
||||
gedacht; auf Staging bleibt der Standard bestehen.
|
||||
|
||||
Vor dem ersten Staging-Apply muss der neue Web-/Worker-Stand vollständig deployed und
|
||||
gesund sein. Erst dieser Stand versteht die Search-Batch-Aktionen und hält den
|
||||
Legacy-Boot-Seed über `SEED_DEMO_PRO_MANAGED=true` dauerhaft aus dem Pro-Tenant heraus.
|
||||
|
||||
Nach dem Outbox-Drain pollt der Lauf alle registrierten Meilisearch-Indizes mit
|
||||
Tenant-Filter. Der Tenant wird erst aktiviert, wenn CRM (976), Projekte (537),
|
||||
Aufgaben (1.684), Dateien (917) und Nutzer (50) vollständig sichtbar und alle
|
||||
anderen Tenant-Slices leer sind. Für die vollständig über die Search-API abrufbaren
|
||||
Slices bis 1.000 Dokumente wird zusätzlich die exakte ID-Menge geprüft. Der
|
||||
Aufgaben-Slice überschreitet Meilisearchs standardmäßige `maxTotalHits`-Grenze und
|
||||
wird deshalb fail-closed über die exakte Tenant-Facette und den vollständigen Count
|
||||
verifiziert.
|
||||
|
||||
Damit sich die geseedeten Demo-Konten anschließend auch anmelden können, muss auf
|
||||
der Staging-Web-Ressource `STAGING_DEMO_LOGIN_ENABLED=true` gesetzt sein (wirkt nur
|
||||
zusammen mit `SENTRY_ENVIRONMENT=staging`). Der Login-Schalter ist bewusst vom
|
||||
Seeding getrennt und trägt kein `SEED_`-Präfix: Der RLS-Deploy-Vertrag weist jeden
|
||||
`SEED_*`-Schlüssel auf Runtime-Ressourcen ab, weshalb der Login sonst nicht
|
||||
freischaltbar wäre.
|
||||
|
||||
Das gemeinsame Staging-Login-Passwort wird ausschließlich zur Laufzeit aus dem
|
||||
Secret-Store gelesen, muss mindestens 20 Zeichen lang und ausreichend zufällig
|
||||
sein und darf weder in Git noch in Deployment-Logs landen. Nur für den vom Owner
|
||||
explizit verlangten gemeinsamen Staging-Zugang akzeptiert der CLI exakt den
|
||||
vereinbarten Testwert, wenn zusätzlich
|
||||
`SEED_DEMO_PRO_ALLOW_SHARED_STAGING_PASSWORD=true` gesetzt ist. Das Flag gehört
|
||||
nicht in die Coolify-Runtime-Umgebung und erlaubt keinen anderen schwachen Wert.
|
||||
Der Seed nutzt in beiden Fällen denselben Argon2id-Hasher wie die App.
|
||||
|
||||
Vor dem Setzen von `SEED_DEMO_PRO_WORKERS_DRAINED=true` müssen Outbound- und
|
||||
Automations-Worker in Coolify pausiert und ihre aktiven Queue-Jobs vollständig
|
||||
abgearbeitet sein. `SEED_DEMO_PRO_OUTBOUND_SANDBOX=true` ist eine operative
|
||||
Nichtzustellbarkeits-Bestätigung und darf nur in einer der folgenden Lagen gesetzt
|
||||
werden:
|
||||
|
||||
1. Mail, SMS, Webhooks und Push zeigen nachweislich auf nicht zustellbare Test-Sinks.
|
||||
2. Fail-closed Isolation: Alle BullMQ-Queues außer `outbox.search-index` sind global
|
||||
pausiert, für jede pausierte Queue ist `active=0` bestätigt und die Coolify-Apps
|
||||
`worker-mail`, `worker-import`, `worker-webhook` und `worker-plugin` sind gestoppt.
|
||||
`worker-general` bleibt ausschließlich für DB-Outbox und Search-Acks aktiv; seine
|
||||
übrigen Queues bleiben ebenfalls global pausiert.
|
||||
|
||||
Die Isolation muss vor dem Apply erneut geprüft und bis zum erfolgreichen
|
||||
`--verify` gehalten werden. Der DB-Outbox-Reset kann bereits an BullMQ übergebene
|
||||
`DONE`-Jobs nicht zurückholen. Danach werden zuerst die pausierten Queues fortgesetzt
|
||||
und anschließend die vier Worker-Apps wieder gestartet. Der Search-Pfad bleibt für
|
||||
beide Search-Ack-Phasen durchgehend verfügbar.
|
||||
|
||||
Der Reset erhält Tenant, Subscription, Pro-Entitlements und globale Kataloge. Er
|
||||
ersetzt die fachlichen Projekt-, CRM-, Lead-, Aufgaben-, Datei-, Kalender-, Buchungs- und
|
||||
Search-Daten sowie die Tenant-Mitgliedschaften. Die 50 synthetischen Nutzer
|
||||
bleiben globale User-Zeilen und werden beim nächsten Lauf sicher aktualisiert. Die
|
||||
sieben SHK-Template-Rollen werden ebenfalls aus dem exakten Berechtigungskatalog
|
||||
neu aufgebaut, damit keine alte manuelle Zusatzberechtigung auf neue Testnutzer
|
||||
übergeht. Anschließend invalidiert der Lauf die Permission-Caches aller 50 Nutzer
|
||||
über den gemeinsamen Cache-Bus, bevor der Tenant wieder aktiviert werden kann.
|
||||
|
||||
Während `apply` und `cleanup` hält der Prozess eine DB-seitige Lease und setzt den
|
||||
Tenant in Wartung. Ein Heartbeat erneuert die Lease während aller Seed-,
|
||||
Outbox- und Search-Phasen; verliert der Prozess den Besitz, bricht er fail-closed
|
||||
ab. Nur ein vollständig verifizierter Apply-Lauf aktiviert den Tenant wieder.
|
||||
Nach Abbruch oder Fehler bleibt er absichtlich deaktiviert; zur Recovery denselben
|
||||
Apply-Befehl erneut ausführen. `cleanup` hinterlässt den leeren Tenant ebenfalls
|
||||
deaktiviert.
|
||||
|
||||
## Datenschutz und Zustellsicherheit
|
||||
|
||||
- Sämtliche E-Mail-Adressen liegen unter `.example.test`.
|
||||
- Sämtliche Telefonnummern liegen im offiziellen Frankfurter Drama-Number-Block
|
||||
`+49 69 90009 000–999`.
|
||||
- Orte und PLZ sind real; Straßen und Hausnummern sind synthetisch.
|
||||
- Die 917 Datei-Datensätze besitzen deterministisch erzeugte, minimale PDF-Objekte
|
||||
unter `tenants/{tenantId}/files/{fileId}/original`. Größe und SHA-256-Prüfsumme
|
||||
stammen aus den exakten Bytes. Da die PDFs ausschließlich im vertrauenswürdigen
|
||||
Seed-Prozess entstehen und nie Nutzereingaben oder Remote-Inhalte enthalten,
|
||||
werden sie als `clean` gespeichert; der AV-Gate für untrusted Uploads bleibt
|
||||
unverändert fail-closed. Vor jedem Reset löscht der Lauf den gesamten
|
||||
tenant-eigenen `files/`-Prefix, einschließlich verwaister Objekte aus älteren
|
||||
Katalogen oder abgebrochenen Läufen, in begrenzten Seiten von höchstens 1.000
|
||||
Keys. Die Abschlussprüfung verlangt die exakte erwartete Key-Menge und lehnt auch
|
||||
zusätzliche Objekte im verwalteten Prefix ab.
|
||||
- Direkte Dokumentbezüge werden nur bei eindeutiger Fachsemantik gesetzt: 81
|
||||
Rechnungen verweisen eins-zu-eins auf das gleichnamige Rechnungs-PDF und 13
|
||||
Abnahmen auf das Abnahmeprotokoll ihres Projekts. Checklisten-Fotos bleiben leer,
|
||||
weil der Katalog keine Bilddateien erzeugt. Plantafelzeilen erhalten nur dann
|
||||
`calendarEventId`/`synced`, wenn Projekt, Mitarbeiter und Zeitfenster exakt mit
|
||||
einem Kalendereintrag übereinstimmen; die getrennten Besprechungstermine des
|
||||
aktuellen Katalogs werden nicht als Montageeinsatz ausgegeben und deshalb nicht
|
||||
künstlich verknüpft.
|
||||
- Der Seed erzeugt keine E-Mails, SMS, Webhooks oder Push-Nachrichten.
|
||||
- Buchungsseiten bleiben unveröffentlicht, damit der öffentliche Staging-Tenant
|
||||
keine realen Terminanfragen oder Folge-E-Mails annimmt.
|
||||
|
||||
## Markt- und Geodaten
|
||||
|
||||
Die Verteilungen basieren auf folgenden Quellen:
|
||||
|
||||
- [ZVSHK Konjunktur Frühjahr 2026](https://www.zvshk.de/presse/medien-center/pressemitteilungen/shk-handwerk-verliert-an-dynamik): Bestandsanteil und Auftragsreichweite.
|
||||
- [VDS Kosten eines neuen Bads](https://www.sanitaerwirtschaft.de/aktuell/was-kostet-ein-neues-bad): Preis- und Laufzeitkorridore.
|
||||
- [ifeu Wärmepumpenkosten](https://www.ifeu.de/publikation/analyse-zu-kosten-fuer-material-und-einbau-von-waermepumpen-in-deutschland-und-ausgewaehlten-eu-mitgliedstaaten): Wärmepumpen-Retrofit-Korridore.
|
||||
- [Bundesnetzagentur Drama Numbers](https://www.bundesnetzagentur.de/DE/Fachthemen/Telekommunikation/Nummerierung/start.html): nicht zugeteilte Rufnummern.
|
||||
- [Geoportal Hessen, INSPIRE-Adressen](https://www.geoportal.hessen.de/spatial-objects/706): amtliche Straßennamen unter Datenlizenz Deutschland Zero 2.0.
|
||||
- [BfDI Kurzposition Testdaten](https://www.bfdi.bund.de/DE/Fachthemen/Inhalte/Technik/Kurzposition_Testdaten.html): Vorrang synthetischer Testdaten.
|
||||
|
||||
Der Geodaten-Check läuft getrennt vom Seed:
|
||||
|
||||
```bash
|
||||
pnpm seed:demo-pro:geodata
|
||||
```
|
||||
|
||||
Am 13.07.2026 wurden 92.178 amtliche hessische Straßennamen geprüft. Die 60
|
||||
generierten Straßenmuster hatten keine Kollision. Snapshot-Hash:
|
||||
`3678fccbbf62820aecc0a9c7c253e960123e2131a555aa7d4a3b0b2464a1fce3`.
|
||||
Da sich amtliche Daten ändern, ist der Check vor einem neuen Seed-Katalog erneut
|
||||
auszuführen.
|
||||
|
||||
## Verifikation
|
||||
|
||||
`--verify` prüft die vereinbarten Zielmengen einschließlich 17 Büro- und 33
|
||||
Feldmitarbeitern, die exakte Identitäts-, Rollen- und Dateimatrix in PostgreSQL,
|
||||
alle registrierten Meilisearch-Indizes sowie jedes
|
||||
der 917 realen S3-Objekte bytegenau gegen Größe und SHA-256. Dazu gehören drei
|
||||
Buchungsseiten, 35 Verfügbarkeitsregeln und 79 verknüpfte Buchungstermine. Ein erfolgreicher
|
||||
Apply-Lauf erzeugt außerdem 4.164 permission-aware Search-Projektionen und die
|
||||
entsprechenden, auf maximal 250 Dokumente gebündelten Outbox-Ereignisse für
|
||||
Meilisearch. Dadurch entstehen statt tausender Einzeljobs nur wenige Dutzend
|
||||
tenant-isolierte Batch-Jobs.
|
||||
|
||||
Zusätzlich schlägt die Verifikation fehl, sobald irgendein aktuelles tenant-bezogenes
|
||||
Modell mit `isDemoData` noch markierte Datensätze enthält, der sichtbare Tenant-Name
|
||||
nicht `RheinMain Gebäudetechnik GmbH` lautet oder die SHK-Rollen vom exakten
|
||||
Berechtigungskatalog abweichen.
|
||||
@@ -0,0 +1,523 @@
|
||||
# Customer-Portal: Erst-Rollout und Betrieb
|
||||
|
||||
Dieses Runbook beschreibt den sicheren Erst-Rollout von VA-P26a sowie die vorbereiteten
|
||||
VA-P26b-/VA-P26c-Verträge. Es enthält nur
|
||||
Schlüsselnamen und Platzhalter. Ressourcen-IDs, URLs mit Zugangsdaten, Passwörter,
|
||||
Tokens und Live-Konfiguration gehören ausschließlich in die freigegebenen Secret-
|
||||
und Betriebswerkzeuge.
|
||||
|
||||
**Stand 2026-07-22:** `VA-P26a`, `VA-P26b` und `VA-P26c` sind technisch vollständig. Der aktuelle
|
||||
Produkt- und UX-Vertrag einschließlich Tenant-Logo, Endkundenreisen und Designgrenzen steht in
|
||||
[`docs/features/customer-portal.md`](../features/customer-portal.md). PR `#212` wurde als Main-Revision
|
||||
`090e2558a6965e1c5804eb24d3eab5da8c8611a8` erfolgreich nach Staging ausgerollt. Core und Portal
|
||||
verwenden denselben Web-Digest; Health, Readiness, alle abhängigen Dienste und der revisionsgebundene
|
||||
Domain-Controller sind grün. Produktion wurde durch diesen UI-/Branding-Release nicht verändert.
|
||||
|
||||
| Ticket | Aktueller Stand | Formales Abschluss-Gate |
|
||||
| --------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
||||
| `VA-P26a` | 8/8 DoD = 100 % | technischer Handoff abgeschlossen; finaler Design-Polish bleibt `VD-P26` |
|
||||
| `VA-P26b` | 6/6 DoD = 100 % | technischer Handoff abgeschlossen; finaler Design-Polish bleibt `VD-P26` |
|
||||
| `VA-P26c` | 8/8 DoD = 100 % | technischer Handoff abgeschlossen; Produktion bleibt eine separate Freigabe |
|
||||
|
||||
## Abschlussnachweis des Basis-Deploys
|
||||
|
||||
- Feature-Merge: PR `#125`; Deploy-Hotfixes: PR `#130` und `#132`.
|
||||
- Finaler Lauf:
|
||||
[`#10300`](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/10300), exakte Revision
|
||||
`f54b04162b2823b1d2f6db0318baf1a7431c5b66`, vollständig grün für Staging und Produktion.
|
||||
- Forward-only Migration:
|
||||
`prisma/migrations/20260716123000_va_p26_customer_portal/migration.sql`, ausgeführt im
|
||||
einmaligen eingeschränkten Migrator-Container.
|
||||
- Migration-Chain-Parität, exakter Tenant-Policy-Vertrag, RLS-Release-Readiness und Live-RLS-
|
||||
Isolation waren grün. App, Worker und Portal verwenden getrennte Runtime-Rollen über PgBouncer.
|
||||
- `hivegrid-web` und `hivegrid-portal` liefen aus demselben gepinnten Image/Digest; beide bestanden
|
||||
`/healthz` und `/readyz` mit der erwarteten Revision. Hard-Caps und getrennte Pool-Limits waren
|
||||
Bestandteil des Deploy-Preflights.
|
||||
|
||||
Dieser Nachweis erfüllt das Merge-/RLS-Gate von VA-P26a/b. Er ersetzt nicht den UAT-Tenant,
|
||||
Browser-Klickpfade, Billing-Provider-Proof oder die VA-P26c-Controller-/Custom-Domain-/TLS-Gates.
|
||||
|
||||
## Zielbild
|
||||
|
||||
`hivegrid-web` und `hivegrid-portal` sind zwei getrennte Coolify-Ressourcen aus
|
||||
demselben unveränderlichen `hivegrid/web:<sha>`-Image und demselben Registry-Digest.
|
||||
Die Core-Ressource läuft als `hivegrid_app`; die Portal-Ressource ausschließlich als
|
||||
`hivegrid_portal`. Der Deploy-Workflow provisioniert weder die Portal-Ressource noch
|
||||
einen DNS-Eintrag; die bereits bestehende Worker-Reconciliation bleibt davon
|
||||
unberührt. Für den Portal-Rollout akzeptiert er nur vorab angelegte, eindeutig
|
||||
allowlistete Ressourcen und bricht bei Abweichungen vor dem Rollout ab.
|
||||
|
||||
Standardhosts:
|
||||
|
||||
- Staging: `staging-portal.hivegrid.de`
|
||||
- Produktion: `portal.hivegrid.de`
|
||||
- Kundeneigene Hosts wie `portal.geerkens.de` gehören zu VA-P26c. Claim, sichere Host-/Session-
|
||||
Auflösung und Admin-Self-Service sind lokal vorbereitet; eine Annahme im Live-Ingress erfolgt erst
|
||||
nach den unten beschriebenen Controller-, TLS-, Merge- und Staging-Gates.
|
||||
|
||||
## Harte Vorbedingungen vor dem Main-Merge
|
||||
|
||||
Der Main-Workflow prüft das Coolify-Inventar und die Runtime-Grenzen vor der
|
||||
Migration und bricht bei Abweichungen ohne Schemaänderung ab. Trotzdem müssen alle
|
||||
folgenden Punkte bereits vor dem Merge erfüllt sein:
|
||||
|
||||
1. Ein aktueller Backup-/Restore-Punkt ist bestätigt. Für Produktion ist zusätzlich
|
||||
ein dokumentierter Restore-Drill gemäß Estate-Standard erforderlich.
|
||||
2. `pnpm run db:roles:provision` wurde mit den fünf getrennten Passwort-Keys aus dem
|
||||
Secret-Store ausgeführt. `hivegrid_portal` ist danach `LOGIN`, `NOINHERIT`,
|
||||
`NOBYPASSRLS`, kein Superuser und hat keine Rollenmitgliedschaft.
|
||||
3. PgBouncer enthält einen eigenen SCRAM-Eintrag für `hivegrid_portal`, wurde neu
|
||||
geladen und akzeptiert den Portal-Login. Details stehen in
|
||||
[`docs/ops/pgbouncer.md`](../ops/pgbouncer.md).
|
||||
4. `hivegrid-portal` ist in Staging gestoppt beziehungsweise noch nicht öffentlich
|
||||
erreichbar angelegt, verwendet dasselbe Web-Image wie `hivegrid-web` und steht in
|
||||
der Staging-Ressourcen-Allowlist. Vor einer Produktion-Promotion gilt dasselbe für
|
||||
Produktion.
|
||||
5. Bestehende Runtime-Ressourcen enthalten weder `DIRECT_URL`, `MIGRATE_ON_BOOT`,
|
||||
`SEED_ON_BOOT`, `SEED_*` noch `MIGRATOR_*`. Diese Schlüssel gehören nur in den
|
||||
kurzlebigen Migrationsschritt.
|
||||
6. Core-Web und Portal haben in Coolify jeweils positive, explizite Hard-Caps in
|
||||
`limits_cpus` und `limits_memory`; Portal und Core haben getrennte
|
||||
PgBouncer-Zugangsdaten und bewusst gesetzte Pool-Limits. `0`/`unlimited`, nur
|
||||
`limits_cpu_shares` oder nur eine Memory-Reservation zählen nicht als Hard-Cap.
|
||||
Für den ersten Produktionsrollout sind Core mit 2 vCPU/2 GB und
|
||||
`DATABASE_POOL_MAX=10` sowie Portal mit 1 vCPU/1 GB und
|
||||
`DATABASE_POOL_MAX=5` je Prozess/Instanz festgelegt. Spätere Anpassungen erfolgen
|
||||
nur anhand gemessener Last und bleiben als explizite Hard-Caps dokumentiert.
|
||||
7. `worker-mail` erhält denselben `PORTAL_APP_HOST` wie die Portal-Ressource, damit
|
||||
Status-Mails keine aus `APP_BASE_DOMAIN` abgeleitete falsche URL erzeugen.
|
||||
8. `worker-mail` erhält exakt denselben `CRYPTO_SECRET` wie `hivegrid-web`. Ohne
|
||||
diesen gemeinsamen Envelope-Key müssen Worker-Start, Healthcheck und Deploy-Preflight
|
||||
fail-closed abbrechen; der Wert darf nie geloggt werden.
|
||||
9. `worker-general` erhält `LAGO_API_URL`, `LAGO_API_KEY`, `LAGO_TIMEOUT_MS`,
|
||||
`MOLLIE_API_KEY`, `MOLLIE_PROFILE_ID` und `MOLLIE_TIMEOUT_MS` aus dem
|
||||
freigegebenen Coolify-Secret-/Env-Source. Fehlende Provider-Keys oder
|
||||
ungültige gesetzte Timeouts müssen im Deploy-Preflight beziehungsweise beim
|
||||
Required-RLS-Start fail-closed abbrechen. `MOLLIE_PROFILE_ID` bleibt optional.
|
||||
10. `hivegrid-web`, `hivegrid-portal`, `worker-import` und `worker-general`
|
||||
verwenden denselben privaten Bucket sowie dieselben normalisierten Werte für
|
||||
`STORAGE_ENDPOINT`, `STORAGE_REGION`, `STORAGE_BUCKET` und
|
||||
`STORAGE_FORCE_PATH_STYLE`. Ein vorhandenes gemeinsames
|
||||
`STORAGE_ACCESS_KEY_ID`-/`STORAGE_SECRET_ACCESS_KEY`-Paar ist für alle vier
|
||||
Ressourcen zulässig und kein Rollout-Blocker; getrennte Credentials bleiben
|
||||
optional. Nur Core, Portal und Import-Worker erhalten exakt denselben
|
||||
`GDPR_EXPORT_SSE_C_KEY_BASE64`;
|
||||
der reine Lösch-Worker benötigt und erhält diesen Customer-Key nicht.
|
||||
`STORAGE_SESSION_TOKEN` wird nur gesetzt, wenn das jeweilige Credential ihn
|
||||
tatsächlich benötigt. Fehlende Pflichtwerte, ein nicht-HTTPS-Endpoint oder
|
||||
ein nicht kanonisch Base64-kodierter 32-Byte-Key brechen den
|
||||
Produktionsstart fail-closed ab.
|
||||
Die lokale Staging-Compose-Referenz bildet dieselbe Konfiguration über die
|
||||
host-seitigen Quellen `WEB_STORAGE_*`, `WORKER_IMPORT_STORAGE_*` und
|
||||
`WORKER_GENERAL_STORAGE_*`; diese Quellen dürfen auf dasselbe Credential
|
||||
zeigen. Die Portal-Ressource bleibt eine separate Coolify-Resource mit
|
||||
vollständig gesetzten `STORAGE_*`-Werten. Der Deploy-Preflight prüft
|
||||
Vollständigkeit und gemeinsame Storage-Zielwerte, vergleicht oder protokolliert
|
||||
die Credential-Werte jedoch nicht.
|
||||
`worker-import` und `worker-general` müssen für die gemeinsame
|
||||
Tenant-Export-Barriere außerdem denselben normalisierten Redis-Endpunkt und
|
||||
dieselbe Redis-Datenbank verwenden. Dafür gilt effektiv ein nichtleeres
|
||||
`REDIS_URL`, sonst `BULLMQ_REDIS_URL`; Zugangsdaten dürfen getrennt sein.
|
||||
Fehlende, ungültige oder abweichende Ziele brechen den Deploy-Preflight ab,
|
||||
ohne Redis-URLs auszugeben.
|
||||
11. `worker-general` erhält zusätzlich `MEILI_URL` und den HiveGrid-scoped
|
||||
`MEILI_API_KEY`. In Production, required-RLS sowie Staging-/Production-Sentry
|
||||
muss der Worker vor Queue-Ownership abbrechen, wenn Wert oder Search-Client
|
||||
fehlen; ein Tenant-Hard-Delete darf sonst nicht erfolgreich abschließen.
|
||||
|
||||
## Runtime-Matrix
|
||||
|
||||
| Bereich | `hivegrid-web` | `hivegrid-portal` | `worker-mail` |
|
||||
| --------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
|
||||
| Surface | `WEB_RUNTIME_SURFACE=core` | `WEB_RUNTIME_SURFACE=portal` | nicht setzen |
|
||||
| DB-Rolle | `DATABASE_RUNTIME_ROLE=hivegrid_app` | `DATABASE_RUNTIME_ROLE=hivegrid_portal` | `DATABASE_RUNTIME_ROLE=hivegrid_worker` |
|
||||
| DB-Modus | `RLS_RUNTIME_MODE=required` | `RLS_RUNTIME_MODE=required` | `RLS_RUNTIME_MODE=required` |
|
||||
| Produktions-Pool je Instanz | `DATABASE_POOL_MAX=10` | `DATABASE_POOL_MAX=5` | nach Worker-Vertrag |
|
||||
| Produktions-Hard-Cap | 2 vCPU / 2 GB RAM | 1 vCPU / 1 GB RAM | nach Worker-Vertrag |
|
||||
| Session | `SESSION_SECRET` | `PORTAL_SESSION_SECRET` | keine Web-Session |
|
||||
| Tenant-Envelope-Key | `CRYPTO_SECRET` | nicht erforderlich | exakt derselbe `CRYPTO_SECRET` wie `hivegrid-web` |
|
||||
| Portalhost | `PORTAL_APP_HOST` | `PORTAL_APP_HOST` | `PORTAL_APP_HOST` |
|
||||
| Custom-Domain-Runtime | in Staging exakt `PORTAL_CUSTOM_DOMAIN_RUNTIME_ENABLED=true`; Produktion bis zum freigegebenen Controller unset/false | identischer expliziter Staging-Opt-in; Produktion bis zur Freigabe unset/false | nicht setzen |
|
||||
| Redis | nach Core-Funktion | gültiges `REDIS_URL`; optional gültiges `BULLMQ_REDIS_URL` | Queue-Verbindung nach Worker-Vertrag |
|
||||
| GDPR-Export-Storage | gemeinsamer Endpoint/Region/Bucket, vollständiges Storage-Credential; gemeinsames Paar zulässig | gemeinsamer Endpoint/Region/Bucket, vollständiges Storage-Credential; gemeinsames Paar zulässig | nicht setzen |
|
||||
| GDPR-Export-SSE-C | `GDPR_EXPORT_SSE_C_KEY_BASE64`, exakt wie im Import-Worker | exakt derselbe Wert wie `hivegrid-web` und Import-Worker | nicht setzen |
|
||||
| CAPTCHA | Core-Konfiguration | `CAPTCHA_PROVIDER=cap` oder `mcaptcha` plus passende Login-Keys und Instanz-URL | nicht erforderlich |
|
||||
| Auth-Mail | Core-Mailkonfiguration | nur Queue-Verbindung; keine Mailjet-Provider-Credentials | Mailjet-Absender-/Provider-Keys für Auth- und Status-Mails plus Queue-Verbindung |
|
||||
| Admin SSO/OAuth/Billing | nur dort, wo der Core-Vertrag es erlaubt | verboten | nach eigenem Worker-Vertrag, nie Portal-Credentials |
|
||||
|
||||
Auf `hivegrid-portal` sind zusätzlich alle Core-Session-, Authentik-, OAuth-, Billing-,
|
||||
Coolify-, SSH-, Traefik-, Ingress-, Cloudflare-, Domain-Controller- und veralteten
|
||||
`PORTAL_SERVER_*`-Keys verboten. `APP_REVISION` wird aus dem Image gelesen und darf
|
||||
nicht als Coolify-Override existieren.
|
||||
|
||||
### GDPR-Export-Storage: Schlüssel und effektive Rechte
|
||||
|
||||
Der dedizierte Import-Worker schreibt Portal- und Privacy-Exporte mit SSE-C. Beide
|
||||
Web-Surfaces lesen sie ausschließlich serverseitig mit demselben Customer-Key; es
|
||||
gibt keinen Presigned-URL- oder Klartext-Fallback. Die S3-Zugangsdaten dürfen von
|
||||
den vier Runtimes geteilt werden; getrennte Principals sind optional und werden
|
||||
nicht vom Deploy-Preflight erzwungen. Für die Anwendungspfade gilt diese
|
||||
Funktionsmatrix:
|
||||
|
||||
| Runtime | Erlaubte Object-Actions | Erlaubte Object-ARNs/Key-Prefixe | Explizit nicht benötigt |
|
||||
| ------- | ----------------------- | -------------------------------- | ----------------------- |
|
||||
| `hivegrid-web` | `s3:GetObject` | `arn:aws:s3:::<bucket>/gdpr-exports/privacy/tenants/*/*/*` | Portal-GDPR-Prefix, `s3:PutObject`, `s3:DeleteObject`, `s3:ListBucket` |
|
||||
| `hivegrid-portal` | `s3:GetObject` | `arn:aws:s3:::<bucket>/gdpr-exports/portal/tenants/*/*/*` | Core-GDPR-Prefix, `s3:PutObject`, `s3:DeleteObject`, `s3:ListBucket` |
|
||||
| `worker-import` | `s3:PutObject`; zusätzlich `s3:DeleteObject` nur nach einem eindeutig fehlgeschlagenen Attempt, niemals bei unklarem Commit-Ausgang oder Owner-CAS-Verlust | beide oben genannten Object-Prefixe | `s3:GetObject`, `s3:ListBucket` |
|
||||
| `worker-general` | `s3:DeleteObject`; bucket-level `s3:ListBucket` nur mit `s3:prefix`-Condition auf `tenants/*`, `gdpr-exports/privacy/tenants/*` und `gdpr-exports/portal/tenants/*` | beide oben genannten Object-Prefixe sowie der bestehende Hard-Delete-Prefix `arn:aws:s3:::<bucket>/tenants/*` | Customer-Key, `s3:GetObject`, `s3:PutObject`, unbeschränktes `s3:ListBucket` |
|
||||
|
||||
Bei einem gemeinsamen Credential benötigt dessen Bucket-Policy die Vereinigungsmenge
|
||||
der in der Tabelle aufgeführten Actions und Prefixe. Die Trennung der App-Pfade
|
||||
bleibt im Code erhalten, ist dann aber keine Principal-Isolation des Providers.
|
||||
`worker-general` erhält unabhängig davon nie den SSE-C-Customer-Key und kann die
|
||||
Exportinhalte deshalb nicht entschlüsseln. Falls das Credential weitere, bereits
|
||||
freigegebene Storage-Funktionen bedient, erhalten diese eigene, explizite Statements
|
||||
auf deren Prefixe; daraus darf kein `s3:*` auf dem gesamten Bucket entstehen. Alle
|
||||
Artefakte liegen im gemeinsamen, export-first Keyspace
|
||||
`gdpr-exports/`; jeder Versuch erhält einen eigenen `attemptId`, sodass ein später
|
||||
oder parallel verlorener Versuch nicht das veröffentlichte Artefakt überschreibt.
|
||||
Der private Export-Bucket verwendet für diese Objekte weder Versioning noch Object
|
||||
Lock, weil der aktuelle `DeleteObject`-Pfad sonst nur einen Delete-Marker setzen
|
||||
beziehungsweise an einer Retention scheitern könnte. Die Bucket-Policy ist
|
||||
default-deny für andere Principals, Actions und Prefixe.
|
||||
|
||||
Als Defense-in-depth liegt auf exakt dem Prefix `gdpr-exports/` zusätzlich eine
|
||||
Provider-Lifecycle-Regel mit `Expiration.Days=3`. Sie schützt auch dann vor
|
||||
dauerhaft liegen gebliebenen Attempts, wenn App-Kompensation und beide Sweeper
|
||||
ausfallen. Sie ist kein Ersatz für den 15-Minuten-Sweep und keine Zusage einer
|
||||
minutengenauen Löschung: Hetzner verarbeitet Lifecycle-Expiration asynchron. Die
|
||||
Regel darf weder den übrigen Bucket noch andere Prefixe erfassen. Hetzner
|
||||
dokumentiert action-spezifische Bucket-Policies, SSE-C und Lifecycle-Regeln; das
|
||||
Repository kann ihre tatsächlich angewandte Provider-Konfiguration jedoch nicht
|
||||
allein beweisen ([S3-Credentials](https://docs.hetzner.com/storage/object-storage/faq/s3-credentials/),
|
||||
[SSE-C](https://docs.hetzner.com/storage/object-storage/howto-protect-objects/encrypt-with-sse-c/),
|
||||
[Lifecycle](https://docs.hetzner.com/storage/object-storage/howto-protect-objects/manage-lifecycle/),
|
||||
[unterstützte Actions](https://docs.hetzner.com/storage/object-storage/supported-actions/)).
|
||||
|
||||
Privacy-Exporte sind nach `resultExpiresAt` höchstens 72 Stunden, Portal-Exporte
|
||||
höchstens 24 Stunden über die authentifizierte App-Route abrufbar. Die Route sperrt
|
||||
den Zugriff ab diesem Zeitpunkt sofort. Der erforderliche Lösch-Scheduler läuft im
|
||||
15-Minuten-Takt; physisch gelöscht wird im ersten erfolgreichen Sweep nach Ablauf.
|
||||
Die planmäßige Löschlatenz beträgt damit bis zu 15 Minuten zuzüglich Laufzeit, ist
|
||||
bei Provider-/Queue-Störung aber ausdrücklich nicht garantiert. Fehler müssen den
|
||||
Job fehlschlagen lassen, erneut versucht werden und bis zur erfolgreichen Löschung
|
||||
als Alarm offen bleiben. Eindeutig fehlgeschlagene Attempts werden unmittelbar
|
||||
kompensiert. Bei unklarem PUT- oder Ready-CAS-Ausgang bleiben Claim und Pointer
|
||||
erhalten, damit der Retry denselben Key übernimmt; der Sweep erfasst zusätzlich
|
||||
deterministisch adressierbare verwaiste Artefakte.
|
||||
|
||||
Bei einer Rotation werden Import-Worker, Core und Portal gemeinsam umgestellt,
|
||||
nachdem alle mit dem alten Customer-Key verschlüsselten Exportobjekte erfolgreich
|
||||
gelöscht wurden. Im Dedicated-Modus setzt der Import-Worker
|
||||
`PORTAL_GDPR_EXPORT_QUEUE_ENABLED=true` und hält `IMPORT_QUEUE_ENABLED=false` sowie
|
||||
`IMPORT_QUEUE_RUNTIME_READY=false`; eine Mischkonfiguration bricht Runtime- und
|
||||
Deploy-Preflight fail-closed ab. Der alternative Full-Modus setzt beide
|
||||
`IMPORT_QUEUE_*`-Gates auf `true` und hält
|
||||
`PORTAL_GDPR_EXPORT_QUEUE_ENABLED` unset oder `false`. Auch dann bleiben der
|
||||
Storage-/SSE-C-Vertrag sowie Portal-, Privacy- und generische
|
||||
Import-/Export-Service-Wirings verpflichtend. Im Idle-Modus bleiben alle drei Gates
|
||||
unset oder `false`; dann darf der Import-Worker seinen Storage-/SSE-C-Vertrag
|
||||
weglassen und konsumiert keine Import-/Export-Queue. Core und Portal behalten ihren
|
||||
verschlüsselten Downloadvertrag unabhängig davon. `worker-general` setzt in jedem
|
||||
Staging-/Produktions-Rollout `EXPORT_RETENTION_QUEUE_ENABLED=true` und startet nicht
|
||||
bereit, wenn Scheduler, Redis oder sein Delete-only-Storage-Vertrag fehlen. Ein
|
||||
gesetzter `GDPR_EXPORT_SSE_C_KEY_BASE64` ist auf diesem Lösch-Worker ausdrücklich
|
||||
verboten und wird von Runtime- und Deploy-Preflight zurückgewiesen.
|
||||
|
||||
### Operator-Checkpoint: Provider-Vertrag
|
||||
|
||||
Unit-Tests und der Coolify-Preflight beweisen nur Key-Format, Env-Vollständigkeit,
|
||||
gemeinsamen Bucket/Endpoint und die Runtime-Verdrahtung. Sie beweisen weder die
|
||||
aktive Hetzner-Bucket-Policy noch SSE-C- oder Hard-Delete-Semantik. Vor jedem neuen
|
||||
Environment und nach jeder Policy-/Credential-Rotation führt ein Operator deshalb
|
||||
mit ausschließlich wegwerfbaren Testobjekten den folgenden redigierten Check aus:
|
||||
|
||||
1. Privaten Bucket, default-deny Policy sowie deaktiviertes Versioning/Object Lock
|
||||
bestätigen. Die aktive Lifecycle-Konfiguration muss genau ein
|
||||
`Expiration.Days=3`-Statement für `gdpr-exports/` enthalten und darf keinen
|
||||
breiteren Prefix erfassen. Policy-/Lifecycle-Hash und Prüfzeitpunkt
|
||||
dokumentieren, nie Schlüsselwerte.
|
||||
Vor dem ersten SSE-C-Rollout zusätzlich die Legacy-Keyspaces
|
||||
`tenants/*/gdpr/*.zip` und `tenants/*/portal-gdpr/*/*.json` mit einem separat
|
||||
verwahrten Operator-Credential inventarisieren, vollständig löschen und die
|
||||
dazugehörigen DB-Jobs auf `expired` setzen beziehungsweise ihre alte
|
||||
Objektadresse entfernen. Nur redigierte Counts, Policy-Hash und Prüfzeitpunkt
|
||||
dokumentieren. Der neue Reader darf diese Klartextobjekte nie als Fallback
|
||||
akzeptieren.
|
||||
2. Mit dem konfigurierten Storage-Credential je ein Lese- und ein
|
||||
Kompensations-Testobjekt mit SSE-C in beide GDPR-Prefixe schreiben und die
|
||||
Kompensationsobjekte wieder löschen. Für den GDPR-Keyspace müssen Actions und
|
||||
Prefixe außerhalb der oben beschriebenen Export-/Hard-Delete-Matrix scheitern;
|
||||
außerhalb dieses Keyspaces gilt die vollständig inventarisierte
|
||||
Vereinigungsmenge aller für das gemeinsame Credential explizit freigegebenen
|
||||
Actions und Prefixe.
|
||||
3. Über die authentifizierten App-Routen bestätigen, dass Core nur das
|
||||
Privacy-Objekt und Portal nur das Portal-Objekt mit Customer-Key ausliefert.
|
||||
Kreuz-Prefix sowie Abruf ohne oder mit falschem Customer-Key müssen scheitern.
|
||||
Ein gemeinsamer Provider-Principal wird hierbei bewusst nicht als
|
||||
Runtime-Isolation gewertet.
|
||||
4. `worker-general` muss die drei für Tenant-Hard-Delete benötigten Prefixe
|
||||
(`tenants/{tenantId}/`, Privacy-Export, Portal-Export) listen und darin
|
||||
löschen können. Der Worker darf keinen `GDPR_EXPORT_SSE_C_KEY_BASE64` erhalten
|
||||
und bietet ausschließlich den Delete-/Retention-Pfad an. Bei einem gemeinsamen
|
||||
Storage-Credential ist eine providerseitige Get-/Put-Sperre für diesen einzelnen
|
||||
Prozess nicht nachweisbar; verpflichtend bleiben die Prefix-Grenzen der
|
||||
Bucket-Policy. Danach wird bestätigt, dass die Objekte fehlen.
|
||||
5. Je ein isoliertes, kurz vor Ablauf datiertes UAT-Fixture für Privacy und Portal
|
||||
beobachten: App-Download ab Expiry abgewiesen, Artefakt im
|
||||
ersten erfolgreichen 15-Minuten-Sweep gelöscht, Alarmweg bei einem absichtlich
|
||||
fehlgeschlagenen Delete anschließend wieder resolved. Das Fenster im
|
||||
Produktvertrag bleibt 72 beziehungsweise 24 Stunden; nur dieser Live-
|
||||
Checkpoint zählt als Provider-Proof.
|
||||
6. Ein ausschließlich für den Backstop erzeugtes Attempt unter `gdpr-exports/`
|
||||
liegen lassen und nach Ablauf der dreitägigen Provider-Regel mit dem separaten
|
||||
Operator-Credential seine Entfernung bestätigen. Das Ergebnis ist ein
|
||||
zeitversetzter Provider-Nachweis und blockiert nicht den primären App-Sweep-
|
||||
Checkpoint; bis zur Bestätigung bleibt es als offener Betriebsnachweis markiert.
|
||||
|
||||
## VA-P26c: privater Domain-Controller-Vertrag
|
||||
|
||||
Die vorbereitete private Ressource heißt `hivegrid-portal-domain-controller` und verwendet das
|
||||
gleichnamige immutable Image/Target mit derselben expliziten Revision wie der freigegebene
|
||||
Portal-Release. Sie ist nicht öffentlich erreichbar und besitzt ausdrücklich **keine** Datenbank-,
|
||||
Coolify-, SSH-, Root-, Cloudflare-, allgemeine Traefik-/Ingress- oder Docker-Socket-Credentials.
|
||||
Benötigt werden ausschließlich:
|
||||
|
||||
- eine eigene Redis-Verbindung für die dedizierten signierten Command-/Result-Queues;
|
||||
- ein getrenntes Command-Secret sowie ein getrenntes Bearer-Token für `/metrics`;
|
||||
- DNS-/HTTPS-Outbound für Ownership-, CNAME-, SNI- und Health-Prüfungen;
|
||||
- Schreibrecht ausschließlich auf
|
||||
`/data/coolify/proxy/dynamic/hivegrid-portal-domains/`, nicht auf das übergeordnete
|
||||
Dynamic-Config-Verzeichnis;
|
||||
- das environment-spezifische, provider-qualifizierte Coolify-Ziel
|
||||
`https-0-<hivegrid-portal-uuid>@docker`; ein frei wählbares oder provider-loses Backend ist
|
||||
verboten.
|
||||
|
||||
Commands tragen `claimId`, `tenantId`, `generation`, `hostname` und `action` sowie Signatur und
|
||||
Content-Hash. Der Controller verwirft falsche Signaturen, alte Generationen und nicht exakte Hosts.
|
||||
Traefik-Dateien werden über Temp-Datei, `fsync` und atomaren Rename geschrieben; jede Regel matcht
|
||||
exakt `Host()` und verwendet kein offenes On-Demand-Wildcard-TLS. `active` darf erst nach realem
|
||||
SNI-/Portal-Health-Ack gesetzt werden. Dafür läuft ausschließlich der schmale
|
||||
`hivegrid_portal_resolve_custom_hostname_health`-Resolver vor dem normalen Host-Dispatch: Er akzeptiert
|
||||
nur DNS-verifizierte Claims mit aktivem Entitlement/Payment, persistiertem Controller-Command und
|
||||
Domainstatus `provisioning`, `active` oder `degraded`; pending, disabled, Kill-Switch und
|
||||
Deprovisioning liefern 404. Das ist ein Controller-Probe, keine Freigabe für pre-active Portalinhalte.
|
||||
`/healthz` bleibt ohne Secrets nutzbar, `/metrics` ist Bearer-geschützt.
|
||||
|
||||
Das Repository enthält Image-, CI-/SBOM-, Health-, Queue- und Renderer-Verträge. Das ist kein Beleg,
|
||||
dass die Ressource in Coolify angelegt, gestartet oder mit dem Estate-Traefik verbunden wurde.
|
||||
Bis dieser Beleg je Environment vorliegt, bleibt `PORTAL_CUSTOM_DOMAIN_RUNTIME_ENABLED` dort unset
|
||||
oder `false`. Nur Staging setzt den Wert aktuell auf exakt `true`, und zwar auf `hivegrid-web` sowie
|
||||
`hivegrid-portal`; der Coolify-Helper prüft beide Werte vor jeder Controller-Mutation. Das Gate
|
||||
blendet den Tenant-Admin-Link aus und liefert für Domain-Admin-Route sowie Custom-Host-Routing 404,
|
||||
ohne den Standardhost des Kundenportals abzuschalten.
|
||||
|
||||
## Merge-Migration
|
||||
|
||||
Auf dem Feature-Branch blieb `verify:migrations-parity` gemäß AD-21 absichtlich rot. Für den Merge
|
||||
wurde daraus genau eine reviewte forward-only P26-Migration für den ausgewählten gemeinsamen
|
||||
Portal-Vertragsstand aus VA-P26a/b/c erzeugt:
|
||||
`prisma/migrations/20260716123000_va_p26_customer_portal/migration.sql`. Der rohe Prisma-Diff wurde
|
||||
nicht ungeprüft übernommen; auf dem Feature-Branch gab es ausdrücklich keine eigene Migration.
|
||||
|
||||
### Bestandsdaten-Preflight
|
||||
|
||||
Die Migration muss vor jeder destruktiven Änderung fail-closed prüfen:
|
||||
|
||||
- `Portal.tenantId` ist lückenlos und verweist auf den richtigen Tenant.
|
||||
- Pro Tenant existiert höchstens ein Portal, bevor der neue Unique-Index entsteht.
|
||||
- `PortalUser.tenantId` ist lückenlos und entspricht immer dem Tenant seines Portals.
|
||||
- Portal-E-Mails sind nach `lower(trim(email))` weder leer noch innerhalb eines
|
||||
Portals doppelt.
|
||||
- Die später benötigten zusammengesetzten IDs/FKs zwischen Portal, PortalUser,
|
||||
Projekt, Stage und File sind tenant-konsistent.
|
||||
- Das freigegebene Legacy-Mapping ist anwendbar: tenant-konsistente PortalUser mit
|
||||
einem nichtleeren, vom aktuellen Passwort-Hasher akzeptierten `passwordHash`
|
||||
werden `active`; alle übrigen übernahmefähigen PortalUser werden `invited`.
|
||||
Bestehende Hashes werden byte-identisch erhalten und niemals neu gehasht oder
|
||||
durch ein Default-Passwort ersetzt. `emailVerifiedAt` wird nur aus einem vor dem
|
||||
Cutover dokumentierten, belastbaren Verifikationsbeleg übernommen. Ein fehlender
|
||||
Legacy-`verifyToken` allein zählt nicht als Beleg und führt deshalb zu `NULL`.
|
||||
|
||||
Fehlerhafte oder mehrdeutige Zeilen werden nicht geraten, automatisch gelöscht oder
|
||||
unter einem beliebigen Tenant einsortiert. Sie müssen vor dem Cutover bewusst
|
||||
bereinigt beziehungsweise zugeordnet werden.
|
||||
|
||||
### Token- und Re-Invite-Entscheidung
|
||||
|
||||
Die alten Felder `PortalUser.verifyToken` und `PortalUserRegistration.token` enthalten
|
||||
keinen mit dem neuen `PortalToken`-Vertrag kompatiblen Hash. Sie werden nicht in
|
||||
gültige neue Login-Fähigkeiten umgewandelt. Offene Registrierungen beziehungsweise
|
||||
alte Verify-Tokens werden invalidiert; betroffene Personen erhalten nach dem Cutover
|
||||
einen neuen Setup-/Magic-Link über den geprüften Flow. Dieser Re-Invite muss vor dem
|
||||
Drop fachlich freigegeben und kommuniziert sein.
|
||||
|
||||
Die Migration bricht vor jeder Mutation ab, sobald Tenant-/Portal-Zuordnung,
|
||||
normalisierte E-Mail oder Portal-Owner nicht eindeutig sind. Sie archiviert oder
|
||||
verschiebt keine Konfliktzeile automatisch. Legacy-Registrierungen und Tokens werden
|
||||
vollständig invalidiert; weder Klartext- noch Legacy-Tokenwerte dürfen in die neuen
|
||||
`PortalToken`-Zeilen gelangen.
|
||||
|
||||
### DDL- und Policy-Reihenfolge
|
||||
|
||||
Die Migration führt Preflight, Backfill, Constraints, Tabellenänderungen und RLS in
|
||||
einer atomaren Migration aus:
|
||||
|
||||
1. Fehlende `tenantId`-/`emailNormalized`-/Locale-Werte nach dem freigegebenen
|
||||
Mapping backfillen und die Preflight-Prüfungen erneut ausführen.
|
||||
2. Die sieben geprüften Legacy-Commerce-Policies sowie die Policy von
|
||||
`PortalUserRegistration` explizit entfernen.
|
||||
3. Acht Legacy-Tabellen FK-sicher child-first entfernen:
|
||||
`PortalUserSubscriptionProductPrice`, `PortalUserSubscriptionProduct`,
|
||||
`PortalSubscriptionFeature`, `PortalSubscriptionPrice`,
|
||||
`PortalUserSubscription`, `PortalSubscriptionProduct`,
|
||||
`PortalCheckoutSessionStatus` und `PortalUserRegistration`.
|
||||
4. Den vollständigen aktuellen Portal-Vertragsstand anlegen: Auth/Session/Token,
|
||||
ProjectAccess/Stage-/Dokumentfreigabe/Status-Mail, Upload/Reklamation,
|
||||
Subunternehmerzugang, Tenant-Konfiguration/Auto-Release/Notification-Präferenzen,
|
||||
Service-Inbox/Routing, DSGVO-Export/Löschung/Lifecycle sowie Domain-Claim und aktuelle
|
||||
Custom-Domain-State-Machine. Dazu gehören alle Enums, Indizes, zusammengesetzten Tenant-FKs und
|
||||
die sicheren Änderungen an `Portal`/`PortalUser`; eine fest verdrahtete Annahme von nur „sechs
|
||||
Portal-Tabellen" ist veraltet.
|
||||
5. Nur den noch nicht migrierten Portal-Delta für die normalen `hivegrid_app`-/
|
||||
`hivegrid_worker`-Tenant-Policies einbetten. Bereits migrierte Telephony-Objekte
|
||||
dürfen nicht aus einem breiten Generator-Delta dupliziert werden.
|
||||
6. Die schmalen `hivegrid_portal`-Policies, Spalten-Grants und
|
||||
`SECURITY DEFINER`-Resolver einbetten. Die Actor-Invarianten erzwingen für `File`,
|
||||
`FileUpload`, `FileEntityLink` und `portal_form`-`FormSubmission` genau den zulässigen internen
|
||||
oder Portal-Aktor. Die schmalen Domain-Controller-Capabilities bleiben vom Portal-Login getrennt.
|
||||
SQL-Dateien mit eigenem `BEGIN`/`COMMIT`
|
||||
werden nicht blind verkettet; beim Einbetten bleibt genau eine äußere Transaktion.
|
||||
|
||||
Der Inverse-SQL-Kommentar rekonstruiert Struktur, Indizes, FKs, Grants und Policies
|
||||
parent-first. Er weist ausdrücklich darauf hin, dass gelöschte Registrierungs- und
|
||||
Commerce-Zeilen nur aus dem Backup, nicht durch Inverse-DDL, wiederhergestellt werden.
|
||||
|
||||
### Pflicht-Proof der Migration
|
||||
|
||||
Vor dem Merge beziehungsweise Rollout müssen grün sein:
|
||||
|
||||
```sh
|
||||
pnpm exec prisma validate
|
||||
pnpm run verify:migrations-parity
|
||||
HIVEGRID_RLS_REQUIRE_MIGRATION_CHAIN_PARITY=1 pnpm run verify:rls-live
|
||||
pnpm run verify:tenant-policy-contract
|
||||
pnpm run verify:rls-release-readiness
|
||||
```
|
||||
|
||||
Der strikte RLS-Lauf muss eine frische leere Datenbank ausschließlich mit
|
||||
`prisma migrate deploy` aufbauen. `prisma db push`, der Feature-Branch-Recut-Helper
|
||||
und manuell nachgeladene Policy-Dateien sind in diesem Proof verboten.
|
||||
|
||||
### Lokaler Merge-Kandidaten-Proof vom 2026-07-16
|
||||
|
||||
Ein **bewusst ungetrackter lokaler Merge-Kandidaten-Proof** wurde gegen zwei wegwerfbare
|
||||
PostgreSQL-16-Datenbanken ausgeführt. Die zugehörigen Repository-Verträge liegen in `18dfd4825`;
|
||||
der temporäre Migrationskandidat selbst wurde gemäß AD-21 nicht in der Feature-Branch committed:
|
||||
|
||||
1. leere Datenbank nach vollständigem `prisma migrate deploy` der bestehenden Chain;
|
||||
2. Datenklon mit den acht Legacy-Commerce-/Registrierungstabellen und repräsentativen PortalUsern.
|
||||
|
||||
Beide Läufe verwendeten den eingeschränkten `hivegrid_migrator` und endeten schema-paritätisch zum
|
||||
aktuellen Prisma-Schema. Der Legacy-Klon bestätigt `active` für akzeptierte Hashes, `invited` für
|
||||
nicht akzeptierte/fehlende Hashes, byte-identische Hash-Erhaltung, `emailNormalized`-/Tenant-/Locale-
|
||||
Backfill und Reset nicht belastbar belegter Verifikation sowie alter Registrierung/Token-Fähigkeiten.
|
||||
Eine normalisierte Duplicate-E-Mail-Kollision bricht fail-closed vor Mutation ab. Vier Actor-Checks
|
||||
sind validiert; **22/22** eingeschränkte Portal-Live-Tests (P26a 14/14 + P26b 7/7 + schmaler
|
||||
Custom-Host-Resolver 1/1) belegen Customer/Subunternehmer, PortalUser/Tenant A/B, active/revoked,
|
||||
Frozen read/write und fail-closed Host-Auflösung. Zusammen mit App-/Worker- und Tenant-Bootstrap-
|
||||
Proofs ist der frische Feature-Overlay-Lauf **68/68** grün.
|
||||
|
||||
Dieser Probe-Lauf erlaubt weder `verify:migrations-parity` noch den migration-only Strict-Lauf grün
|
||||
zu markieren: Der Kandidat liegt bewusst nur außerhalb des Repositories. Vor Merge muss daraus die
|
||||
eine reviewte forward-only Migration mit Inverse-SQL entstehen; danach folgen frische Chain und
|
||||
Staging-RLS-Proof.
|
||||
|
||||
### Ausgeführter Merge-/RLS-Proof vom 2026-07-16
|
||||
|
||||
Die reviewte Migration wurde mit PR `#125` in `main` übernommen und im Deploy-Lauf
|
||||
[`#10300`](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/10300) als einmaliger
|
||||
Migrationsschritt ausgeführt. Der Lauf prüfte die exakte Revision
|
||||
`f54b04162b2823b1d2f6db0318baf1a7431c5b66`, Migration-Chain-Parität, Tenant-Policy-Vertrag,
|
||||
RLS-Release-Readiness und Live-RLS-Isolation. App, Worker und Portal liefen mit getrennten Rollen
|
||||
über PgBouncer; Core und Portal verwendeten denselben gepinnten Web-Digest und bestanden
|
||||
`/healthz`/`/readyz`. Damit sind die oben beschriebenen Merge-/RLS-Gates erfüllt.
|
||||
|
||||
## Staging-Rollout
|
||||
|
||||
1. Portal-Ressource und Core-Web zunächst ohne öffentlichen Portal-DNS vollständig
|
||||
nach der Runtime-Matrix konfigurieren. Alle Ressourcen-Allowlisten aktualisieren.
|
||||
2. Merge erst freigeben, wenn Migration, Rollen, PgBouncer und Coolify-Inventar
|
||||
vorbereitet sind.
|
||||
3. Der Main-Workflow migriert einmalig, pinnt Web und Portal auf denselben SHA/Digest,
|
||||
deployt beide getrennt und prüft `/healthz` sowie `/readyz` auf Service, Surface,
|
||||
Revision und echte DB-Rolle/RLS-Bereitschaft.
|
||||
4. Erst nach grüner interner Bereitschaft den DNS-Eintrag anlegen. Nach Estate-
|
||||
Standard bleibt Cloudflare zunächst `proxied=false`, bis das LE-Zertifikat gültig
|
||||
ist; anschließend kann `proxied=true` gesetzt werden.
|
||||
5. Die schreibenden Portal-RLS-Integrationstests laufen nur gegen eine wegwerfbare
|
||||
PostgreSQL-Instanz. Shared Staging erhält einen nicht destruktiven Rollen-/Policy-/
|
||||
Grant-/`readyz`-Proof und bewusst angelegte UAT-Fixtures.
|
||||
|
||||
## Staging-UAT
|
||||
|
||||
VA-P26b besitzt den vollständigen Admin-/Interaktionsflow; Merge-Migration und eingeschränkter
|
||||
Staging-RLS-Proof sind mit Lauf `#10300` grün. Für den formalen Handoff fehlt jetzt ein bewusst
|
||||
angelegter isolierter UAT-Tenant mit PortalUser, ProjectAccess, sichtbarer Stage, freigegebenem
|
||||
Testdokument sowie begrenztem Customer- und Subunternehmerzugang. Es werden keine
|
||||
`SEED_*`-Runtime-Schalter verwendet.
|
||||
|
||||
Zu prüfen sind mindestens:
|
||||
|
||||
- Magic-Link, optionales Passwort, Setup, Verifikation, Reset und Logout;
|
||||
- keine User-Enumeration bei unbekannter E-Mail;
|
||||
- PortalUser A/B, Tenant A/B und nicht freigegebene Projekte/Dokumente liefern 404;
|
||||
- Core-Host weist Portalpfade ab und Portalhost weist Core-/Admin-/API-/Rootpfade ab;
|
||||
- Frozen-Tenant verhält sich read-only;
|
||||
- Status-Mail enthält den richtigen Portalhost, respektiert Sichtbarkeit/Präferenz,
|
||||
wird debounced und tatsächlich zugestellt;
|
||||
- Multi-Upload/Reklamation schreibt erst nach AV-/Storage-Erfolg File-/Link-/Activity-/Inbox-
|
||||
Datensätze und benachrichtigt über `notify()`; Subunternehmer sehen weder Endkunden noch fremde
|
||||
Projekt-/Dokumentdaten;
|
||||
- Admin-Konfiguration, Rechtslink-Aktivierungsgate, Inbox-Routing, Export, 24-Stunden-Lösch-Widerruf
|
||||
und Lifecycle-Jobs verhalten sich unter Frozen read-only;
|
||||
- `/healthz` und `/readyz` melden den erwarteten Service, die erwartete Surface und
|
||||
die gebackene Revision, ohne DB-Rolle oder Secrets öffentlich auszugeben.
|
||||
|
||||
VA-P26c-UAT folgt separat erst nach echtem Billing-Provider-Proof und angelegter Controller-Ressource:
|
||||
TXT/CNAME-Verifikation, exakte Host-Auflösung, SNI/TLS-/Health-Ack, Retry/Revalidation, Remove/Switch,
|
||||
Kill-Switch und Standardhost-Fallback. Localhost-, Mock- oder manuell eingespielte Traefik-Dateien
|
||||
ersetzen diesen Proof nicht.
|
||||
|
||||
## Produktion und Rollback
|
||||
|
||||
Die VA-P26a-Grundlage darf vorab auf Staging verifiziert werden. Eine öffentliche
|
||||
Buchung beziehungsweise Produktfreischaltung erfolgt jedoch erst nach VA-P26b, wenn
|
||||
Workspace-Admin-Verwaltung, Upload/Reklamation und DSGVO-Flows vollständig verfügbar
|
||||
sind. VA-P26c schaltet danach Paket-Gates und Custom-Domains frei.
|
||||
|
||||
Produktion wird nur über den bestehenden `promote`-Workflow mit der exakt in Staging
|
||||
geprüften Live-Staging-SHA und einem erst nach Backup-Bereitschaft manuell
|
||||
gestarteten, input-freien Promote ausgerollt. Ressourcen-, Rollen-,
|
||||
PgBouncer-, Env-, DNS- und Zertifikatsvorbereitung werden vorher nochmals geprüft.
|
||||
|
||||
Vor der DB-Migration kann auf den vorherigen Web-Digest zurückgerollt und die Portal-
|
||||
Ressource beziehungsweise ihr DNS deaktiviert werden. Nach der Migration gilt der im
|
||||
Migration-File dokumentierte Inverse-SQL-Pfad; gelöschte Legacy-Zeilen benötigen das
|
||||
Backup. Core und Portal werden immer als Digest-Paar zurückgerollt, damit keine zwei
|
||||
unterschiedlichen Surface-Verträge gleichzeitig laufen.
|
||||
|
||||
Für VA-P26c bleibt der Standardhost der verpflichtende Fallback. Bei Controller-, DNS-, TLS- oder
|
||||
Entitlement-Störung wird zuerst der Domain-Kill-Switch gesetzt, die aktuelle Generation
|
||||
deprovisioniert und ausschließlich die exakt zu diesem Claim gehörende generierte Traefik-Datei
|
||||
entfernt. Danach wird die Controller-Ressource auf den zuvor geprüften immutable Digest zurückgesetzt
|
||||
oder gestoppt; Core-/Portal-Digests und fremde Host-Dateien bleiben unberührt. Die 30-Tage-Reclaim-
|
||||
Sperre wird durch einen Rollback nicht umgangen. Ohne erfolgreiches Deprovisioning-/Fallback-UAT
|
||||
wird kein Custom-Host öffentlich aktiviert.
|
||||
|
||||
## Folge-Tickets
|
||||
|
||||
- VA-P26b ergänzt Admin-Einladungen, Access-Matrix, Stage-/Dokumentfreigaben,
|
||||
Upload/Reklamation und DSGVO-Flows.
|
||||
- VA-P26c ergänzt Paket-Gates und den Self-Service-Custom-Domain-Flow inklusive
|
||||
DNS-Verifikation, Zertifikatsstatus und Deaktivierung.
|
||||
@@ -1,141 +1,83 @@
|
||||
# Deploying Meilisearch
|
||||
# Meilisearch in HiveGrid deployen
|
||||
|
||||
This document covers production deployment of the Meilisearch service that
|
||||
backs `packages/search` and the `search-indexer` worker job. Local
|
||||
development uses the bundled docker-compose service — see
|
||||
`docker-compose.yml` and `docs/features/search.md` for the application-side
|
||||
contract.
|
||||
HiveGrid nutzt gemäß `infra/STANDARDS.md` §4 den zentralen Meilisearch im
|
||||
Estate. Staging und Production bekommen keinen eigenen Meilisearch-Service in
|
||||
Coolify. Der zentrale Dienst ist ausschließlich über das WireGuard-Mesh
|
||||
erreichbar und wird von der Estate-Infrastruktur betrieben und gesichert.
|
||||
|
||||
## Requirements
|
||||
Lokale Entwicklung kann weiterhin den Service aus `docker-compose.yml`
|
||||
verwenden. Der Anwendungs- und Tenant-Vertrag steht in
|
||||
`docs/features/search.md`.
|
||||
|
||||
- Disk: 1–10 GiB per million indexed documents, SSD strongly recommended.
|
||||
- Memory: 1 GiB minimum; allocate ~30 % of the dataset size for hot reads.
|
||||
- Network: reachable only from `apps/web`, `apps/api` and the
|
||||
`worker-general` service. **Never** expose port 7700 to the public
|
||||
internet. The master key is the only auth boundary; if the port is open,
|
||||
the index is open.
|
||||
- TLS: terminate at the platform's ingress / load balancer; Meilisearch
|
||||
itself does not speak TLS.
|
||||
## Runtime-Vertrag
|
||||
|
||||
## Environment Variables
|
||||
| Variable | Pflicht | Zweck |
|
||||
| --------------- | ------- | ------------------------------------------------------------- |
|
||||
| `MEILI_URL` | ja | Mesh-Adresse des zentralen Dienstes: `http://10.42.0.4:7700`. |
|
||||
| `MEILI_API_KEY` | ja | Auf HiveGrid und `hivegrid-*`-Indizes beschränkter API-Key. |
|
||||
|
||||
| Variable | Required | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `MEILI_URL` | yes | URL the search wrapper and worker dial. Internal DNS only (e.g. `http://meilisearch.internal:7700`). |
|
||||
| `MEILI_MASTER_KEY` | yes | Server-side secret. Min 32 bytes of entropy. Rotate via blue/green; never log. |
|
||||
| `MEILI_ENV` | yes | `production` in production. Disables the unauthenticated dashboard. |
|
||||
| `MEILI_NO_ANALYTICS` | recommended | Set to `true` to disable upstream telemetry. |
|
||||
`MEILI_MASTER_KEY` gehört niemals in eine HiveGrid-App, einen HiveGrid-Worker
|
||||
oder eine HiveGrid-CI-Variable. Erstellung und Rotation des scoped API-Keys
|
||||
erfolgen mit dem Master-Key ausschließlich auf der Estate-Control-Ebene.
|
||||
|
||||
## Coolify (Hetzner) — recommended for the staging stack
|
||||
Die Runtime-Variablen müssen mindestens auf `hivegrid-web`, `hivegrid-api` und
|
||||
`worker-general` identisch gesetzt sein. Der Mesh-Endpunkt darf nicht über
|
||||
einen öffentlichen Port oder Proxy veröffentlicht werden.
|
||||
|
||||
Coolify ships a "custom docker-compose" service type that maps 1:1 onto
|
||||
the local layout. Paste the snippet below into the project's
|
||||
docker-compose override (Coolify → Service → Configuration → Compose).
|
||||
## Index-Namespace
|
||||
|
||||
```yaml
|
||||
services:
|
||||
meilisearch:
|
||||
image: getmeili/meilisearch:v1.8
|
||||
environment:
|
||||
- MEILI_MASTER_KEY=${MEILI_MASTER_KEY}
|
||||
- MEILI_ENV=production
|
||||
- MEILI_NO_ANALYTICS=true
|
||||
volumes:
|
||||
- meilisearch-data:/meili_data
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "wget -q -O - http://127.0.0.1:7700/health | grep -q 'available'"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 6
|
||||
start_period: 15s
|
||||
restart: unless-stopped
|
||||
networks:
|
||||
- backend
|
||||
Registry-Schemas, Outbox-Payloads, CLI-Parameter und Worker-Pager verwenden
|
||||
weiterhin logische Namen wie `projects` oder `crm-contacts`. Erst der Adapter
|
||||
in `@hivegrid/search` bildet diese zentral auf physische Meilisearch-UIDs ab:
|
||||
|
||||
volumes:
|
||||
meilisearch-data:
|
||||
|
||||
networks:
|
||||
backend:
|
||||
external: true
|
||||
```text
|
||||
logical: projects
|
||||
physical: hivegrid-projects
|
||||
```
|
||||
|
||||
Operator steps:
|
||||
Aufrufer dürfen den Prefix nicht selbst ergänzen. `SearchClient.index()`
|
||||
verwirft bereits physisch präfixierte Namen, damit weder doppelte Prefixes noch
|
||||
ein zweiter, unpräfixierter Namespace entstehen. Der scoped API-Key muss
|
||||
ausschließlich Zugriffe auf `hivegrid-*` erlauben.
|
||||
|
||||
1. Set `MEILI_MASTER_KEY` as a Coolify "secret" (Project → Variables →
|
||||
"Encrypt"). Length ≥ 32 bytes; generate with `openssl rand -hex 32`.
|
||||
2. Set `MEILI_URL=http://meilisearch:7700` on `apps/web`, `apps/api` and
|
||||
the `worker-general` service so they resolve via the internal Docker
|
||||
network. Do **not** map the port to the host.
|
||||
3. Add a backup cron that snapshots the `meilisearch-data` volume:
|
||||
## Staging-Rollout
|
||||
|
||||
```bash
|
||||
# /etc/cron.daily/meilisearch-snapshot
|
||||
docker exec meilisearch \
|
||||
curl -X POST -H "Authorization: Bearer $MEILI_MASTER_KEY" \
|
||||
http://127.0.0.1:7700/snapshots
|
||||
```
|
||||
1. Estate-Operator erstellt oder rotiert einen HiveGrid-scoped API-Key für
|
||||
`hivegrid-*`; der Master-Key bleibt außerhalb der Anwendung. Der Key braucht
|
||||
zusätzlich zu Index-, Dokument- und Settings-Rechten auch `tasks.get`, weil
|
||||
HiveGrid jede asynchrone Mutation bis zum terminalen Status bestätigt.
|
||||
2. `MEILI_URL` und `MEILI_API_KEY` auf Web, API und `worker-general` setzen.
|
||||
3. Für einen Namespace-Wechsel Web zunächst mit `SEARCH_BACKEND=sql` starten.
|
||||
Der Worker schreibt dabei weiter nach Meilisearch, aber kein bestehender
|
||||
Tenant liest aus einem unvollständig befüllten Index.
|
||||
4. Alle drei Ressourcen mit demselben geprüften Image-SHA deployen. Der
|
||||
General-Worker legt alle registrierten `hivegrid-*`-Indizes an und bestätigt
|
||||
ihre Settings, bevor er den ersten Search-Job annimmt. Schlägt das fehl,
|
||||
beendet er den Start fail-closed.
|
||||
5. `/health` beziehungsweise `/readyz` und die Worker-Logs prüfen, ohne Keys
|
||||
oder Verbindungs-URLs auszugeben.
|
||||
6. Für jeden bestehenden Tenant alle unterstützten Registry-Indizes neu
|
||||
aufbauen. Nicht durch Bulk-Pager abgedeckte Indizes müssen über ihre
|
||||
jeweiligen Source-of-Truth-Projektionen vollständig replayed werden.
|
||||
7. Dokumentanzahl und Tenant-Isolation je Index verifizieren. Erst wenn alle
|
||||
acht Indizes vollständig sind, `SEARCH_BACKEND=meilisearch` auf Web setzen
|
||||
und erneut deployen. Bis dahin bleibt SQL der explizite Read-Pfad.
|
||||
|
||||
4. Verify `/health` is `available` after deploy; the worker logs
|
||||
`meilisearch.connected` on cold start.
|
||||
|
||||
## Dedizierte VM — alternative (Hetzner Cloud)
|
||||
|
||||
For traffic spikes that outgrow the central Coolify host, run Meilisearch on
|
||||
a dedicated Hetzner Cloud VM (e.g. CX22) with a 10 GB volume:
|
||||
|
||||
```bash
|
||||
# Hetzner: attach a 10 GB volume and mount at /meili_data
|
||||
ssh root@<instance> docker run -d --name meilisearch \
|
||||
--restart unless-stopped \
|
||||
-p 7700:7700 \
|
||||
-v /meili_data:/meili_data \
|
||||
-e MEILI_MASTER_KEY="$(cat /etc/meilisearch/master-key)" \
|
||||
-e MEILI_ENV=production \
|
||||
-e MEILI_NO_ANALYTICS=true \
|
||||
getmeili/meilisearch:v1.8
|
||||
```
|
||||
|
||||
Front the instance with a private network; never expose
|
||||
port 7700 to the public internet. Apps reach it via the private DNS name
|
||||
configured in the `MEILI_URL` env.
|
||||
|
||||
## Master-Key Rotation
|
||||
|
||||
1. Generate a new key: `openssl rand -hex 32`.
|
||||
2. Set the new key as `MEILI_MASTER_KEY_NEW` in the secret store.
|
||||
3. Bring up a parallel Meilisearch container with the new key; replicate
|
||||
indexes via the snapshot/restore endpoint:
|
||||
```bash
|
||||
curl -X POST -H "Authorization: Bearer $OLD_KEY" \
|
||||
"$OLD_MEILI/snapshots"
|
||||
# copy the snapshot file, start new container pointing at it
|
||||
```
|
||||
4. Flip `MEILI_URL` on the apps to point at the new container.
|
||||
5. Decommission the old container; rotate the secret-store key (move
|
||||
`MEILI_MASTER_KEY_NEW` to `MEILI_MASTER_KEY`).
|
||||
|
||||
The wrapper's transparent SQL-LIKE fallback (`searchWithFallback`) keeps
|
||||
search degraded-but-up during the cutover.
|
||||
Der Demo-Pro-Seed verifiziert seinen eigenen Tenant vollständig in allen acht
|
||||
Indizes. Das ersetzt keinen Backfill anderer Staging-Tenants und ist daher kein
|
||||
Signal, das globale Read-Gate vorzeitig umzuschalten.
|
||||
|
||||
## Disaster Recovery
|
||||
|
||||
The Postgres database remains the source of truth. To rebuild Meilisearch
|
||||
from scratch:
|
||||
Postgres bleibt die Source of Truth. Ein Rebuild wird ausschließlich über
|
||||
logische Namen und Outbox-Events gestartet:
|
||||
|
||||
```bash
|
||||
pnpm cli search reindex --tenant=all --index=all
|
||||
pnpm exec tsx packages/cli/bin/hivegrid-cli.mjs search reindex --tenant=all --index=all
|
||||
```
|
||||
|
||||
This writes `search.index.<entity>.bulkreindex` outbox events only for the
|
||||
currently supported bulk-reindex set. Today `--index=all` expands to KB
|
||||
articles, CRM contacts, rows, and users. Entities are rejected until their
|
||||
tenant-scoped projection has an explicit pager design. The `search-indexer` job
|
||||
consumes the accepted events and pages over Postgres in 1000-row chunks.
|
||||
Expected throughput: ~10 k documents per minute per worker replica.
|
||||
|
||||
## Backup Retention
|
||||
|
||||
Snapshots are full copies of the data directory. Retain at least 7 daily
|
||||
snapshots offsite (S3 / Backblaze). The volume itself is also covered by
|
||||
the platform's nightly volume backup if you keep that enabled.
|
||||
Der `search-indexer` konsumiert die Events und schreibt über den zentralen
|
||||
Adapter in `hivegrid-*`. `--index=all` umfasst nur Indizes mit registriertem
|
||||
Bulk-Pager; nicht unterstützte Projektionen werden abgewiesen. Snapshot,
|
||||
Restore, Retention und Master-Key-Rotation des zentralen Dienstes gehören in
|
||||
die Runbooks des `infra/`-Repos und werden nicht in HiveGrid dupliziert.
|
||||
@@ -1,156 +0,0 @@
|
||||
# Deployment Porting Guide
|
||||
|
||||
## Purpose
|
||||
|
||||
Use this guide when updating boilerplate deployment and CI documentation. It keeps deployment prose aligned with the current static evidence without overstating live proof, registry state, or production runtime behavior.
|
||||
|
||||
This document is a documentation entrypoint only. It does not authorize runtime workflow changes, secret creation, live registry pushes, Coolify deployments, browser checks, Playwright runs, Cypress runs, or other E2E execution from Auto-Mode.
|
||||
|
||||
## Source Evidence
|
||||
|
||||
Use these sources as the deployment-porting baseline:
|
||||
|
||||
- `README.md` for the active Gitea CI summary, Corepack/pnpm setup, Docker smoke description, and manual E2E policy.
|
||||
- `docs/porting-guide.md` section `Deployment and CI docs` for wording rules that distinguish Gitea CI, local Docker smoke validation, static verification, and manual browser/E2E review.
|
||||
- `docs/deployment.md` for the current deploy workflow contract, Gitea Package Registry placeholder slots, Coolify runner-side triggering, and health/readiness inspection guidance.
|
||||
- `.tc/baselines/porting-docs/baseline-health.md` for the Porting Docs baseline gate evidence and documentation inventory scope.
|
||||
|
||||
When a later document claims stronger proof than these sources, it must name the later human-approved run or slice evidence that provided that proof.
|
||||
|
||||
## CI Terminology
|
||||
|
||||
Describe the active pipeline as Gitea CI on the self-hosted `toolctrl-ci` runner. The baseline CI contract starts with Corepack and the pinned pnpm version, installs dependencies with `pnpm install --frozen-lockfile`, then runs static/package gates for quality, API, worker, database, and Docker smoke validation.
|
||||
|
||||
Use these safe local verification references for CI documentation updates:
|
||||
|
||||
```sh
|
||||
pnpm run verify:ci-baseline
|
||||
pnpm run verify:gitea-ci-workflow
|
||||
pnpm run verify:production-seed-artifact
|
||||
```
|
||||
|
||||
Do not describe baseline CI as publishing images, pushing to a registry, triggering Coolify, running browser automation, or proving live deployment. Those claims require separate focused evidence.
|
||||
|
||||
## Docker Smoke Boundaries
|
||||
|
||||
Document Docker smoke as local build and configuration validation. It may prove that Dockerfile targets and Docker Compose configuration are shaped correctly, but it is not proof of a live runtime, registry publish, artifact upload, production rollout, or browser/E2E behavior.
|
||||
|
||||
Safe static/package verifier references include focused scripts and tests such as:
|
||||
|
||||
```sh
|
||||
node scripts/verify-docker-baseline.mjs
|
||||
pnpm exec vitest run scripts/verify-docker-baseline.test.mjs
|
||||
```
|
||||
|
||||
If a human later performs a live Docker build/run smoke check, record it as manual evidence and keep secrets out of commands, logs, screenshots, and summaries.
|
||||
|
||||
## Deploy Workflow Verification
|
||||
|
||||
The deploy workflow contract is static unless a later human-approved run proves otherwise. Use this command as the supported shorthand when documenting the deploy workflow verifier:
|
||||
|
||||
```sh
|
||||
pnpm run verify:deploy-workflow
|
||||
```
|
||||
|
||||
Focused verifier references may also include:
|
||||
|
||||
```sh
|
||||
node scripts/verify-gitea-deploy-workflow.mjs
|
||||
pnpm exec vitest run scripts/verify-gitea-deploy-workflow.test.mjs
|
||||
```
|
||||
|
||||
The static deploy workflow may document versioned image targets for `web`, `api`, and `worker`, immutable full-SHA tags, stage-and-promote alias behavior, and required placeholder configuration slots. Do not turn this into a claim that a registry login, image push, artifact publication, or production deployment actually happened unless the corresponding Gitea run evidence is attached separately.
|
||||
|
||||
## Placeholder-Only Secret Handling
|
||||
|
||||
Deployment docs must use placeholder names only. These names identify required CI variable or secret slots; they are not example values:
|
||||
|
||||
- `REGISTRY_USER`
|
||||
- `REGISTRY_PAT`
|
||||
- `COOLIFY_API_URL`
|
||||
- `COOLIFY_RESOURCE_UUIDS`
|
||||
- `COOLIFY_TOKEN`
|
||||
- `COOLIFY_STAGING_API_URL`
|
||||
- `COOLIFY_STAGING_RESOURCE_UUIDS`
|
||||
- `COOLIFY_STAGING_TOKEN`
|
||||
|
||||
Do not include real registry hosts, namespaces, usernames, passwords, Coolify URLs, UUIDs, tokens, webhook query strings, deploy endpoints, database URLs, Redis URLs, Supabase keys, mail provider keys, or secret-shaped sample values. Use the image placeholder form `{registry}/{namespace}/{web|api|worker}:{tag}` when explaining image naming.
|
||||
|
||||
## Coolify Runner Trigger
|
||||
|
||||
Coolify triggering is runner-side after image publication. Document staging as the push-to-`main` path and production as the `workflow_dispatch` `promote` path. Promotion must require `staged_sha` as a full 40-character staged commit SHA, require `backup_confirmed=true` after backup or restore-point readiness is confirmed, verify the requested SHA image set against the current `staging` alias, and then move production `main` aliases without rebuilding.
|
||||
|
||||
The workflow must read endpoint and resource data only from configured CI variables and secrets. Documentation must not imply Coolify triggers from pull requests, schedules, or release tags unless a later approved workflow change and verifier evidence explicitly establish that behavior.
|
||||
|
||||
## Health and Readiness Inspection
|
||||
|
||||
Health/readiness inspection is separate from deployment proof. Static verification can document repository contracts for `GET /healthz`, `GET /readyz`, API health/readiness responses, and worker health reporting, while live runtime inspection remains manual.
|
||||
|
||||
Safe verifier references include:
|
||||
|
||||
```sh
|
||||
node scripts/verify-health-baseline.mjs
|
||||
pnpm exec vitest run scripts/verify-health-baseline.test.mjs
|
||||
```
|
||||
|
||||
Manual runtime inspection may check web or API health/readiness endpoints, compare request IDs, or inspect worker health output. It must not record database connection strings, Redis URLs, stack traces, tokens, passwords, provider secrets, or other deployment-only values.
|
||||
|
||||
## Auto-Mode Exclusions
|
||||
|
||||
Auto-Mode-safe proof for deployment documentation is limited to static and package-level commands. Auto-Mode must not run live Docker builds, live Docker containers, registry pushes, Coolify dispatches, browser automation, Playwright, Cypress, or E2E commands unless a human explicitly approves that exact focused run in the current session.
|
||||
|
||||
When porting deployment docs, write manual-only language for those excluded checks. If a document needs to mention a future live deployment, phrase it as a manual verification step and keep the current static contract clear.
|
||||
|
||||
## Negative Verification Terms
|
||||
|
||||
Deployment documentation must fail review when it introduces any of these contract breaks:
|
||||
|
||||
- Real deploy endpoints, real registry hosts, real Coolify URLs, UUIDs, tokens, passwords, or secret-shaped examples.
|
||||
- Claims that baseline CI, pull requests, schedules, or static verifiers prove production deployment.
|
||||
- Claims that Coolify triggers before all deployable images are published.
|
||||
- Browser, Playwright, Cypress, or E2E commands presented as Auto-Mode defaults.
|
||||
- Unresolved marker words from the common task-note vocabulary.
|
||||
|
||||
## Forking To A Different Infra
|
||||
|
||||
When a fork runs the boilerplate on its own Gitea/registry/runner, the literal
|
||||
infra strings in `.gitea/workflows/*.yml` must change but the verify gates
|
||||
(`scripts/verify-gitea-ci-workflow.mjs`, `scripts/verify-gitea-deploy-workflow.mjs`)
|
||||
keep enforcing structural correctness. Both gates read their expected
|
||||
infra strings from `scripts/infra-config.mjs`, which honours the following
|
||||
optional env vars (fallback values shown in parentheses):
|
||||
|
||||
| Env var | Default | Used for |
|
||||
| --- | --- | --- |
|
||||
| `HIVEGRID_CI_RUNNER` | `toolctrl-ci` | `runs-on:` label asserted in every job |
|
||||
| `HIVEGRID_IMAGE_PREFIX` | `hivegrid` | Docker smoke tags `<prefix>-{web,api,worker}:smoke` |
|
||||
| `HIVEGRID_GIT_HOST` | `git.tool-ctrl.de` | `REGISTRY:` and `docker login` host pattern + `/etc/hosts` override |
|
||||
| `HIVEGRID_REGISTRY_NAMESPACE` | `toolctrl-labs` | Gitea Package Registry namespace expectations |
|
||||
| `HIVEGRID_DB_USER` | `hivegrid` | Preflight `DATABASE_URL` user component |
|
||||
| `HIVEGRID_DB_NAME` | `hivegrid` | Preflight `DATABASE_URL` database name |
|
||||
|
||||
Fork procedure:
|
||||
|
||||
1. `sed`-replace the literal `toolctrl-ci`, `hivegrid-{web,api,worker}:smoke`,
|
||||
`git.tool-ctrl.de`, `toolctrl-labs`, and DB credentials in
|
||||
`.gitea/workflows/*.yml` to match the fork's infra.
|
||||
2. Export the matching `HIVEGRID_*` env vars in CI so the verify gates assert
|
||||
against the new strings instead of the HiveGrid defaults.
|
||||
3. Run `pnpm run verify:gitea-ci-workflow` and `pnpm run verify:deploy-workflow`
|
||||
locally to confirm the fork's workflow shape still satisfies the contract.
|
||||
|
||||
No verify-gate assertions change. Forks inherit the same structural guarantees
|
||||
without rewriting the Gitea verification scripts.
|
||||
|
||||
## Static Verification
|
||||
|
||||
After editing this guide, use non-E2E checks only:
|
||||
|
||||
```sh
|
||||
test -s docs/deployment-porting.md
|
||||
grep -Eq "Gitea|Docker smoke|verify:ci-baseline|verify:gitea-ci-workflow|verify:deploy-workflow|REGISTRY_PAT|COOLIFY_TOKEN|workflow_dispatch|promote|staging|main" docs/deployment-porting.md
|
||||
pnpm run verify:production-docs
|
||||
pnpm run verify:docs-links
|
||||
```
|
||||
|
||||
These checks confirm the guide exists, keeps required deployment contract terms visible, and stays covered by the active docs gates. They do not prove live deployment.
|
||||
@@ -1,41 +0,0 @@
|
||||
# Deployment Region And Provider Pinning
|
||||
|
||||
This document records the deployment-region and provider policy for hosted environments. The historical filename is retained for link compatibility; the policy language is provider- and region-neutral. It is an operator contract: keep raw secret values, account IDs, customer data, provider payloads, and full environment dumps out of docs, tickets, logs, and CI output.
|
||||
|
||||
## Runtime Policy
|
||||
|
||||
| Surface | Required setting | Operational rule |
|
||||
| --- | --- | --- |
|
||||
| AI primary | Provider selected by `AI_PROCESSING_REGION` and deployment record | Primary generation uses the approved AI adapter for the deployment. |
|
||||
| AI fallback | Provider-specific region markers such as `SCALEWAY_REGION` | Fallback generation must use the provider endpoint and region approved in the deployment record. |
|
||||
| Additional AI fallback | Provider approved by deployment record | Production enablement requires provider/account evidence before traffic is routed. |
|
||||
| Transactional mail | Mailjet (Sinch), EU-hosted (Frankfurt/Belgium); no region env var | Outbound mail requires confirmed processing posture and approved subprocessors for the deployment. |
|
||||
| Billing engine | Lago endpoint and webhook secret | Billing integration requires a deployment-specific Lago service and approved processing posture. |
|
||||
| Payment processor | Mollie account/profile | Payment integration requires an account country approved for the deployment. |
|
||||
| Subprocessors | Approved subprocessors only | Any provider contract or add-on that routes customer data outside the approved deployment policy blocks production enablement until approved or replaced. |
|
||||
|
||||
## Required Region Variables
|
||||
|
||||
These keys are deployment-policy markers. Include the keys that apply to the selected providers in production secret/config stores and deployment review evidence:
|
||||
|
||||
```sh
|
||||
AI_PROCESSING_REGION=<deployment-region>
|
||||
SCALEWAY_REGION=<provider-region>
|
||||
MOLLIE_PROFILE_ID=<billing-account-country>
|
||||
```
|
||||
|
||||
The keys are not secrets. They are drift markers for deployment review and CI/env inventory checks. Do not treat them as runtime proof by themselves; production evidence must still come from provider account settings, contracts, and approved subprocessors.
|
||||
|
||||
## Provider Evidence
|
||||
|
||||
Provider endpoint and region settings must be reviewed against the deployment record. Do not infer data residency or processing posture from a hostname alone.
|
||||
|
||||
Mailjet remains the current transactional email provider. Production mail must not be enabled until account/contract evidence confirms the approved processing posture and subprocessor list for the deployment.
|
||||
|
||||
Lago plus Mollie is the current billing/payment path. Production billing must not be enabled until Lago production hosting, Mollie account/KYC evidence, processor subprocessors, and account-country requirements are approved for the deployment.
|
||||
|
||||
## Verification Notes
|
||||
|
||||
- Run `pnpm run verify:env-drift` after editing env examples or catalog entries.
|
||||
- Run the standard CI baseline gates before merging deployment-region/provider changes.
|
||||
- Record only pass/fail status, key names, region labels, and provider/account evidence labels. Never paste secrets, account IDs, raw provider exports, or customer data.
|
||||
@@ -8,64 +8,155 @@ The current baseline is enforced by static Docker, workflow, health, and artifac
|
||||
|
||||
The table below is the current command contract and expected result for agents/operators. It is not live-environment proof unless a dated CI or deployment run is attached separately.
|
||||
|
||||
| Command | Expected exit code | Expected result | Failure fingerprint |
|
||||
| --- | ---: | --- | --- |
|
||||
| `node scripts/verify-docker-baseline.mjs` | 0 | Pass | Enforces web, API, MCP, and worker Docker target shape, runtime start commands, healthcheck paths, and runtime `tsx` exclusions. |
|
||||
| `pnpm run lint` | 0 | Pass | ESLint runs with `--max-warnings=0`; warnings are failures. |
|
||||
| `pnpm run test` | 0 | Pass | Runs the repository non-watch Vitest/script suite configured in `package.json`. |
|
||||
| `pnpm typecheck` | 0 | Pass | Prisma client generation, React Router typegen, and `tsc -b` complete successfully. |
|
||||
| `pnpm run verify:production-seed-artifact` | 0 | Pass | Verifies the Coolify production seed artifact build contract and, after build, checks for forbidden bare `@hivegrid/*` runtime imports. |
|
||||
| Command | Expected exit code | Expected result | Failure fingerprint |
|
||||
| ------------------------------------------ | -----------------: | --------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `node scripts/verify-docker-baseline.mjs` | 0 | Pass | Enforces web, API, MCP, and worker Docker target shape, runtime start commands, healthcheck paths, and runtime `tsx` exclusions. |
|
||||
| `pnpm run verify:runtime-closures` | 0 | Pass | Confirms every bare import in the compiled web, API, MCP, and worker artifacts is declared by that target's isolated runtime manifest. |
|
||||
| `pnpm run lint` | 0 | Pass | ESLint runs with `--max-warnings=0`; warnings are failures. |
|
||||
| `pnpm run test` | 0 | Pass | Runs the repository non-watch Vitest/script suite configured in `package.json`. |
|
||||
| `pnpm typecheck` | 0 | Pass | Prisma client generation, React Router typegen, and `tsc -b` complete successfully. |
|
||||
| `pnpm run verify:production-seed-artifact` | 0 | Pass | Verifies the Coolify production seed artifact build contract and, after build, checks for forbidden bare `@hivegrid/*` runtime imports. |
|
||||
|
||||
Use focused Vitest files for narrow route, API, worker, and verifier changes; keep browser/E2E checks manual unless explicitly approved for a focused run.
|
||||
|
||||
### Platform-lead ingress rollback
|
||||
|
||||
On the API resource, `PLATFORM_LEADS_INGRESS_ENABLED=false` makes
|
||||
`POST /v1/platform/leads` return a neutral 404 before authentication or persistence. In
|
||||
the web admin, the native lead routes are always present and remain protected by
|
||||
AdminUser status, permissions and Own-/All-RLS. Disable ingress only when producers
|
||||
have been moved back during the documented drain window. The switch requires a
|
||||
redeploy and does not delete data.
|
||||
|
||||
### Current Dockerfile Targets and Runtime Commands
|
||||
|
||||
- `base`: `node:20-bookworm-slim` on `linux/amd64`, production-oriented environment variables, OpenSSL, Corepack, and `pnpm@10.33.0`.
|
||||
- `deps`: installs all workspace dependencies from `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `prisma`, and each workspace `package.json` manifest with `pnpm install --frozen-lockfile --prod=false --prefer-offline` behind a BuildKit `/pnpm/store` cache mount.
|
||||
- `production-deps`: copies the `deps` filesystem and runs `pnpm prune --prod` for the final runtime images.
|
||||
- `build`: generates Prisma client, runs the root `pnpm build` command, and runs `pnpm --filter @hivegrid/api build` plus `pnpm --filter @hivegrid/worker build`; the root build produces the React Router build and web server runtime artifact at `build/server-runtime/server.js`, while the API and worker builds produce `apps/api/dist/server.js` and `apps/worker/dist`.
|
||||
- `web`: copies production node_modules, `build`, `build/server-runtime`, `apps/web/build`, `apps/web/public`, `package.json`, `start.sh`, workspace package runtime dependencies, and `prisma`; runs `ENTRYPOINT ["./start.sh"]`.
|
||||
- `worker`: copies production node_modules, workspace manifests, `apps/worker/package.json`, `apps/worker/dist`, queue/mail/db packages, generated Prisma client artifacts, and `prisma`; sets `WORKER_ENABLED=true`; uses `CMD ["node", "apps/worker/dist/index.js"]`; healthcheck runs `node apps/worker/dist/health.js`.
|
||||
- `api`: copies production node_modules, workspace manifests, `apps/api/package.json`, `apps/api/dist`, `packages/config`, `packages/queue`, `packages/db`, `packages/db/generated/prisma/client`, and `prisma`; sets `PORT=8080`; uses `CMD ["node", "apps/api/dist/server.js"]` without `tsx`.
|
||||
- `base`: pinned `node:24.18.0-bookworm-slim` on `linux/amd64`, production-oriented environment variables, OpenSSL, Corepack, and `pnpm@11.12.0`.
|
||||
- `deps`: installs build dependencies from the frozen lockfile and every workspace manifest with an offline `pnpm install` behind the BuildKit `/pnpm/store` cache mount.
|
||||
- `build`: copies source once, generates the Prisma client and seed artifacts, and prepares shared SBOM/GeoIP inputs. `web-build`, `api-build`, `mcp-build`, `portal-domain-controller-build`, and `worker-build` compile only their own application.
|
||||
- `production-deps-bundle`: mounts the shared pnpm v2 store with `sharing=locked` and first runs all five runtime-closure deploys offline and in parallel. A complete warm-store hit skips `pnpm fetch`; only a failed wave is fully reaped, cleaned at its five exact `/prod/<target>` paths, repaired by one frozen fetch, and retried once.
|
||||
- `web-production-deps`, `api-production-deps`, `mcp-production-deps`, `portal-domain-controller-production-deps`, and `worker-production-deps`: inherit the common deployed closures, then prune and generate an SBOM for only their matching runtime target. There is no generic whole-workspace production `node_modules` stage.
|
||||
- `web`: copies only the web dependency closure, compiled web/server artifacts, locales, the reviewed migration closure, and GeoIP data; runs `ENTRYPOINT ["./start.sh"]`. It neither contains nor dispatches the separate API application; API-host traffic reaching the web runtime fails closed with 404.
|
||||
- `worker`: copies only the worker dependency closure and compiled `apps/worker/dist`; sets `WORKER_ENABLED=true`; uses `CMD ["node", "apps/worker/dist/index.js"]`; healthcheck runs `node apps/worker/dist/health.js`.
|
||||
- `api`: copies only the API dependency closure and compiled `apps/api/dist`; sets `PORT=8080`; uses `CMD ["node", "apps/api/dist/server.js"]` without `tsx`.
|
||||
- `mcp`: copies only the MCP dependency closure and compiled `apps/mcp/dist`; it remains a separate image/resource.
|
||||
- `hocuspocus`: is built from `apps/hocuspocus/Dockerfile`, runs the compiled collaboration server on port 1234, and exposes a TCP Docker healthcheck. It remains a separate image and Coolify resource.
|
||||
|
||||
Local closure measurements from `pnpm deploy --prod` (KiB from `du -sk`, excluding compiled application artifacts and base-image layers) show the impact of replacing each app package's broad production deployment with the target runtime manifests:
|
||||
|
||||
| Target | Previous app closure | Target runtime closure | Reduction |
|
||||
| ------ | --------------------------: | ----------------------: | --------: |
|
||||
| Web | 1,340,304 KiB (1,308.9 MiB) | 835,500 KiB (815.9 MiB) | 37.7% |
|
||||
| API | 1,005,816 KiB (982.2 MiB) | 355,404 KiB (347.1 MiB) | 64.7% |
|
||||
| Worker | 1,159,740 KiB (1,132.6 MiB) | 483,824 KiB (472.5 MiB) | 58.3% |
|
||||
| MCP | 884,936 KiB (864.2 MiB) | 355,012 KiB (346.7 MiB) | 59.9% |
|
||||
|
||||
These are dependency-closure measurements, not compressed registry image sizes. Repeat the same deploy and `du -sk` commands after dependency changes; `pnpm run verify:runtime-closures` remains the correctness gate.
|
||||
|
||||
Runtime start command observations:
|
||||
|
||||
- `start.sh` delegates to root `pnpm start`.
|
||||
- `start.sh migrate` is a short-lived, `DIRECT_URL`-only migration entrypoint. Before Prisma runs, it executes the semantic role probe and requires a direct `hivegrid_migrator` login with the exact non-superuser, no-`BYPASSRLS`, no-`INHERIT`, and constrained Definer-membership contract. It then adopts the [reviewed Prisma baseline](ops/prisma-baseline.md) only over the complete legacy history: canonical checksums are accepted directly, while Git-pinned historical checksums additionally require the security-sensitive PostgreSQL catalog contracts. After a successful `prisma migrate deploy`, the same one-shot process requires a drift-free live Prisma diff before it reconciles the global permission catalog and global default roles fail-closed; any error prevents rollout. The core web resource requires `DATABASE_URL` for `hivegrid_app`; the customer-portal resource requires the separate `hivegrid_portal` login. Both require `RLS_RUNTIME_MODE=required`, reject migrator/seed variables, select an explicit web surface, and directly `exec` the matching built server runtime.
|
||||
- Root `package.json` defines `start` as `pnpm --filter @hivegrid/web start`; `apps/web/package.json` owns the concrete `node ../../build/server-runtime/server.js` runtime command, so the web Docker target starts the built Production-Runtime artifact instead of `tsx`.
|
||||
- `apps/api/package.json` defines `build` as `node scripts/build.mjs` and `start` as `node dist/server.js`; the Docker `api` target depends on that built `apps/api/dist` artifact and on the package-owned Prisma client copied from `packages/db/generated/prisma/client`.
|
||||
- `node scripts/verify-docker-baseline.mjs` enforces the web Production-Runtime contract and the S03 API Docker contract, including the explicit Dockerfile `api` target, required API/package/Prisma copy paths, BuildKit pnpm-store cache usage in the `deps` target, and absence of `tsx` from the API runtime start command.
|
||||
- `apps/api/package.json` defines `build` as `node scripts/build.mjs` and `start` as `node dist/server.js`; the Docker `api` target depends only on that compiled artifact and `runtime/api/package.json`'s verified dependency closure.
|
||||
- API and worker tracing use explicit HTTP, Undici, PostgreSQL, ioredis, AWS SDK, and Pino instrumentations. This preserves the remote I/O spans used by the applications without loading the broad Node auto-instrumentation catalog.
|
||||
- `node scripts/verify-docker-baseline.mjs` enforces the locked parallel `pnpm deploy` bundle and its target-specific runtime closures, BuildKit pnpm-store caching, the web/API image boundary, and absence of `tsx` from production commands. `pnpm run verify:runtime-closures` validates each compiled import graph against its runtime manifest.
|
||||
- `apps/worker/package.json` defines production `start` as `node dist/index.js` and `health` as `node dist/health.js`; the worker Docker target depends on these compiled runtime artifacts and must not rely on `tsx` at container runtime.
|
||||
|
||||
## Registry Push Baseline Gitea Package Registry Push Contract
|
||||
|
||||
Registry Push Baseline starts from the existing Gitea CI runner baseline and hardens the S03 deploy workflow contract at `.gitea/workflows/deploy.yml`. The active workflow builds and pushes versioned `web`, `api`, `mcp`, and `worker` Docker image targets to the Gitea Package Registry on the self-hosted `toolctrl-ci` runner, then triggers configured Coolify resources. Web, API, and MCP resources must pass redacted `/healthz` service-and-revision checks where those resources expose HTTP health URLs; worker resources are separate Coolify applications for `WORKER_QUEUE_GROUP=general`, `mail`, `import`, `webhook`, and `plugin`, and each worker rollout must pass Coolify execute-based `node apps/worker/dist/health.js` readiness with matching revision, enabled worker state, expected group, and expected queue. Image alias/tag checks prove only non-HTTP resource configuration; they are not a pass-open worker health fallback. These static and workflow checks are deployment contract proof; they are still not browser-flow or manual production acceptance evidence.
|
||||
Registry Push Baseline starts from the existing Gitea CI runner baseline and hardens the S03 deploy workflow contract at `.gitea/workflows/deploy.yml`. The immutable image set is `web`, `api`, `mcp`, `worker`, `hocuspocus`, and `portal-domain-controller`; all six versioned targets are pushed to the Gitea Package Registry on the dedicated self-hosted `toolctrl-deploy` runner before configured Coolify resources are triggered. `hivegrid-web` and `hivegrid-portal` are separate Coolify resources from the same immutable web image and registry digest; each must pass its own redacted `/healthz` and `/readyz` surface/service/revision contract before the pair is accepted. API follows its own health contract. MCP must pass both its external `/readyz` dependency/service/revision gate and an enabled Coolify `cmd` healthcheck using `node apps/mcp/dist/deploy-health.js <40-character lowercase Git SHA>`. Hocuspocus must be present in the environment's explicit resource allowlist, use `hivegrid_app` with `RLS_RUNTIME_MODE=required`, report Coolify `running:healthy` through its image-baked TCP healthcheck, and retain the exact configured image revision. Worker resources are separate Coolify applications for `WORKER_QUEUE_GROUP=general`, `mail`, `import`, `webhook`, and `plugin`. Before rollout, the worker provisioner atomically configures the immutable image tag and `node apps/worker/dist/deploy-health.js <40-character lowercase Git SHA> <worker-group>`. Both command-health entrypoints compare a root-owned image-baked revision with `APP_REVISION` before probing the running process over loopback `/readyz`; the worker command additionally requires enabled processing and the exact queue group. The workflow accepts a resource only after its target-specific health contract passes. Image alias/tag checks prove only resource configuration; they are not a pass-open live-revision or readiness fallback. These static and workflow checks are deployment contract proof; they are still not browser-flow or manual production acceptance evidence.
|
||||
|
||||
Auto-Mode-safe verification commands:
|
||||
|
||||
| Command | Expected result |
|
||||
| --- | --- |
|
||||
| `node scripts/verify-gitea-ci-workflow.mjs` | Passes with every `.gitea` workflow job using `runs-on: toolctrl-ci` and with forbidden browser/E2E deploy commands absent. |
|
||||
| `node scripts/verify-gitea-deploy-workflow.mjs` | Emits deterministic PASS/FAIL lines for the `.gitea/workflows/deploy.yml` static contract, including runner, registry-login, image-target, tag-policy, and forbidden-command checks. |
|
||||
| `pnpm run verify:deploy-readiness` | Confirms the package scripts, CI workflow, deploy workflow, deployment docs, worker matrix docs, and worker-group provisioner stay consistent while distinguishing the lightweight deploy preflight from CI/readiness coverage for staging/promotion, health, i18n, hot-swap, Docker, seed, and migration gates. |
|
||||
| `pnpm exec vitest run scripts/verify-gitea-deploy-workflow.test.mjs` | Exercises verifier fixtures for missing deploy contract pieces, forbidden literal secret exposure, forbidden browser/E2E commands, required Coolify trigger coverage, and required image tag behavior. |
|
||||
| `grep -R "ubuntu-latest" .gitea` | Returns no matches; any match means the self-hosted runner baseline has regressed. |
|
||||
| `grep -n "verify:deploy-workflow" docs/deployment.md && grep -n "main" docs/deployment.md` | Confirms this deployment document keeps the deploy verifier command and tag-policy language visible. |
|
||||
| Command | Expected result |
|
||||
| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `node scripts/verify-gitea-ci-workflow.mjs` | Passes with every pull-request CI job using `runs-on: toolctrl-ci` and with forbidden browser/E2E deploy commands absent. The deploy workflow is verified separately on `toolctrl-deploy`. |
|
||||
| `node scripts/verify-gitea-deploy-workflow.mjs` | Emits deterministic PASS/FAIL lines for the `.gitea/workflows/deploy.yml` static contract, including runner, registry-login, image-target, tag-policy, and forbidden-command checks. |
|
||||
| `pnpm run verify:deploy-readiness` | Confirms the package scripts, CI workflow, deploy workflow, deployment docs, worker matrix docs, and worker-group provisioner stay consistent while distinguishing the lightweight deploy preflight from CI/readiness coverage for staging/promotion, health, i18n, hot-swap, Docker, seed, and migration gates. |
|
||||
| `pnpm run verify:tenant-policy-contract` | Regenerates the tenant-policy contract in check mode and fails on stale or missing RLS policy coverage. |
|
||||
| `pnpm run verify:rls-release-readiness` | Verifies the release-level RLS role, policy, migration, Docker, and workflow contract. |
|
||||
| `pnpm run verify:rls-live` | Proves tenant A/B isolation against an ephemeral PostgreSQL instance using the runtime roles. |
|
||||
| `pnpm exec vitest run scripts/verify-gitea-deploy-workflow.test.mjs` | Exercises verifier fixtures for missing deploy contract pieces, forbidden literal secret exposure, forbidden browser/E2E commands, required Coolify trigger coverage, and required image tag behavior. |
|
||||
| `grep -R "ubuntu-latest" .gitea` | Returns no matches; any match means the self-hosted runner baseline has regressed. |
|
||||
| `grep -n "verify:deploy-workflow" docs/deployment.md && grep -n "main" docs/deployment.md` | Confirms this deployment document keeps the deploy verifier command and tag-policy language visible. |
|
||||
|
||||
The package script `verify:deploy-workflow` is the supported shorthand for the deploy workflow verifier. The deploy workflow follows a stage-and-promote contract on the self-hosted `toolctrl-ci` runner. Every deploy job depends on `deploy-preflight`, which intentionally runs only lightweight static deploy wiring checks before any image is published or promoted: the Gitea deploy workflow verifier, deploy-readiness docs/worker/provisioner consistency verifier, Docker baseline, Docker non-root runtime verifier, Coolify helper syntax checks, worker-group provisioner syntax checks, and pre-pull script syntax checks. Broader gates such as API inventory, OpenAPI security, env drift, health baseline, i18n, Phase C boundaries, Host Aware URL baseline, Feature Manifest plugin-removal gates, hot-swap, UI visual, build, and production seed artifact verification belong to the CI/readiness contract rather than the deploy preflight job. Because `.gitea/workflows/ci.yml` intentionally does not run on `push`, production readiness requires Gitea main branch protection: direct pushes to `main` must be disabled and merges to `main` must require the pull-request CI workflow to pass. Without that repository setting, a direct `main` push can stage after only the lightweight deploy preflight. Pushes to `main` then build `web`, `api`, `mcp`, and `worker`, push immutable full-SHA tags plus the `staging` alias, trigger the staging web resource first, wait for web health/revision proof, then trigger dependent API, MCP, `worker-general`, `worker-mail`, `worker-import`, `worker-webhook`, and `worker-plugin` resources. MCP is a separate public image target and Coolify resource (`hivegrid-mcp`) with host `mcp.hivegrid.de` / `staging-mcp.hivegrid.de`; it must deploy separately from `hivegrid-api` even though it reuses API-key auth and scopes. Production promotion is a separate `workflow_dispatch` action named `promote`; operators must provide the full staged commit SHA as `staged_sha` and set `backup_confirmed=true` only after production backup or restore-point readiness is confirmed. The workflow verifies that full-SHA image set against `staging`, moves the production `main` alias without rebuilding, configures the production web migration boot flags (`MIGRATE_ON_BOOT`/`SEED_ON_BOOT`), deploys the production web resource first, waits for web health/revision proof, verifies production migration status with the database URL scoped to that step, and only then deploys dependent API, MCP, plus all five worker-group resources. These names identify required CI variable or secret slots only; documentation must not include real deploy endpoint structures, UUIDs, tokens, passwords, credentials, or secret-shaped examples.
|
||||
The package script `verify:deploy-workflow` is the supported shorthand for the deploy workflow verifier. The deploy workflow follows a stage-and-promote contract on the dedicated self-hosted `toolctrl-deploy` runner. One retained `stage-or-promote` job runs lightweight static deploy wiring checks against the workflow revision selected by Gitea before a promotion detaches to its exact staged application revision; this avoids releasing and reacquiring a runner between preflight and rollout. The fail-closed checks remain the Gitea deploy workflow verifier, deploy-readiness docs/worker/provisioner consistency verifier, Docker baseline, Docker non-root runtime verifier, Coolify helper syntax checks, worker-group provisioner syntax checks, and pre-pull script syntax checks. Broader gates such as API inventory, OpenAPI security, env drift, health baseline, i18n, Phase C boundaries, Host Aware URL baseline, removed-module and plugin-isolation gates, hot-swap, UI visual, build, and production seed artifact verification belong to the pull-request CI/readiness contract. Therefore Gitea main branch protection remains mandatory: direct pushes to `main` must be disabled and merges to `main` must require the pull-request CI workflow to pass.
|
||||
|
||||
The deploy image tag contract is static and versioned. Every staging run must publish full-SHA immutable tags for each image target and update the `staging` alias. Promotion must move the `main` alias to the exact full-SHA image set verified by that workflow run; it must not rebuild from source. Images are recorded by safe target labels such as `web`, `api`, `mcp`, and `worker`; do not paste registry URLs, project IDs, credentials, or token-shaped examples into docs or tickets. The mutable `latest` alias is not part of the deployment contract.
|
||||
The stage-or-promote job independently binds its security proof to the exact deployment SHA before any registry login, image mutation, migration, or Coolify mutation. It fetches and checks out `IMAGE_TAG`, confirms the checked-out commit and ancestry, installs that revision's frozen dependency graph, and then runs `pnpm run verify:tenant-policy-contract`, `pnpm run verify:rls-release-readiness`, and `pnpm run verify:rls-live`. A failure in any gate stops the deployment before external state changes. Pushes to `main` then build all six image targets, push immutable full-SHA tags plus the `staging` alias, run the reviewed web image once with the step-scoped staging migrator credential, verify every Coolify runtime has only its approved least-privilege capability, pair `hivegrid-web` and `hivegrid-portal` on the same web SHA/digest, and independently deploy and health-check the private portal-domain controller before triggering dependent API, MCP, Hocuspocus, `worker-general`, `worker-mail`, `worker-import`, `worker-webhook`, and `worker-plugin` resources. MCP and Hocuspocus are separate public image targets and Coolify resources; neither may be folded into `hivegrid-api`.
|
||||
|
||||
Coolify deployment is runner-side and follows successful image publication. The `.gitea/workflows/deploy.yml` stage path runs on pushes to `main`; the promote path runs only through `workflow_dispatch` with `action=promote`, `staged_sha=<full 40-character staged SHA>`, and `backup_confirmed=true`. Staging Coolify must be called only after `web`, `api`, `mcp`, and `worker` staging images publish successfully: the workflow patches the staging web resource to clear the dead `pre_deployment_command`/`post_deployment_command` hook slots and upserts the migration boot flags (`MIGRATE_ON_BOOT=true`, `SEED_ON_BOOT=true`) via `scripts/coolify-deploy.mjs set-envs`, triggers the staging web resource first, waits for web health/revision proof, then triggers and waits on dependent API, MCP, `worker-general`, `worker-mail`, `worker-import`, `worker-webhook`, and `worker-plugin` resources. Production follows the same web-first/dependent-resource order after the runner verifies the requested full-SHA image set and moves the `main` aliases; migration status is confirmed after the production web resource has completed its entrypoint boot migration and seed and before dependent API/MCP/worker deploys start. The trigger must read endpoint and resource information from configured CI variables and secrets and must not expose deploy URLs, UUIDs, bearer tokens, passwords, or registry credentials in docs, logs, tickets, or verification summaries.
|
||||
Production promotion is an input-free `workflow_dispatch`: a manual run from `main` always promotes the release that is currently live on the canonical staging core surface. Starting that production-only run is the operator's audited confirmation that production backup or restore-point readiness has been checked. The workflow reads the full staged commit SHA from staging health, validates the expected service and surface plus main ancestry, runs the same exact-revision gates, verifies the full-SHA image set against `staging`, moves the production `main` alias without rebuilding, runs the same web image as a one-shot migrator with the production migrator credential scoped to that step, verifies production runtime credentials, deploys production web first, waits for web health/revision proof, verifies migration status, and only then deploys dependent API, MCP, Hocuspocus, plus all five worker-group resources. These names identify required CI variable or secret slots only; documentation must not include real deploy endpoint structures, UUIDs, tokens, passwords, credentials, or secret-shaped examples.
|
||||
|
||||
The deploy image tag contract is static and versioned. Every staging run must publish full-SHA immutable tags for each image target and update the `staging` alias. Promotion must move the `main` alias to the exact full-SHA image set verified by that workflow run; it must not rebuild from source. Images are recorded by safe target labels such as `web`, `api`, `mcp`, `worker`, and `hocuspocus`; do not paste registry URLs, project IDs, credentials, or token-shaped examples into docs or tickets. The mutable `latest` alias is not part of the deployment contract.
|
||||
|
||||
Each staging build imports the previous target-specific `staging` image. BuildKit exports `type=inline`, so the portable cache metadata travels with the already required immutable SHA image push and remains available when a fresh deploy runner starts with an empty local cache. Legacy `build-cache:$TARGET` references are forbidden because the workflow never publishes them; removing those dead references avoids six useless registry lookups per staging build. A separate `type=registry` cache export is also forbidden: it adds another registry write after the image build and previously allowed registry-side 499/context-deadline failures to turn an otherwise successful release red.
|
||||
|
||||
Until the homeserver Docker Engine is upgraded from 29.2.1 to the fixed 29.4+
|
||||
line, staging builds must explicitly select the persistent
|
||||
`hivegrid-deploy-v0312-gc1` `docker-container` builder. Its BuildKit v0.31.2
|
||||
image is manifest-digest pinned, its history and OCI worker are bounded by
|
||||
`scripts/ci/deploy-buildkitd.toml`, and the workflow starts it only around the
|
||||
image-build window. The always-run shutdown stops the privileged builder after
|
||||
normal or failed staging builds without deleting its bounded package-cache
|
||||
mounts. Every subsequent serialized deploy first stops an orphaned host
|
||||
container, and `restart-policy=no` prevents Docker from reviving it after a
|
||||
daemon restart. A staging run validates the host container's exact image,
|
||||
restart policy, and loaded TOML independently of the fresh job container's
|
||||
Buildx client metadata before any build starts. A hard cancellation can still
|
||||
leave only this single stable builder running until that next deploy; it cannot
|
||||
create another cache volume. Bump the builder's generation suffix when its
|
||||
pinned image or daemon configuration changes. This keeps deploy builds away
|
||||
from the affected Engine-embedded BuildKit history listener without changing the
|
||||
build-once/promote-without-rebuild contract.
|
||||
|
||||
Coolify deployment is runner-side and follows successful image publication. The `.gitea/workflows/deploy.yml` stage path runs on pushes to `main`; an input-free manual `workflow_dispatch` from `main` is exclusively the promote path. It resolves the full 40-character SHA from the live staging core health response, validates it and verifies all current `staging` image aliases before any production mutation. Staging Coolify is called only after all staging images publish and the one-shot migration succeeds. The workflow then clears the dead `pre_deployment_command`/`post_deployment_command` slots, checks web/API/MCP/Hocuspocus runtime env with `scripts/coolify-deploy.mjs assert-runtime-db-env`, reconciles worker resources with `hivegrid_worker` credentials and SHA-bound `cmd` healthchecks, triggers staging web first, and then waits on every dependent resource. The explicit staging and production resource allowlists must both include the Hocuspocus application; a missing resource fails closed before rollout. Production uses the same one-shot-before-rollout and credential-verification sequence after the resolved full-SHA images have been verified and promoted. The trigger must read endpoint and resource information from configured CI variables and secrets and must not expose deploy URLs, UUIDs, bearer tokens, passwords, or registry credentials in docs, logs, tickets, or verification summaries.
|
||||
|
||||
The private portal-domain controller is an explicit Coolify resource, not a side effect of the general resource resolver. The current rollout is deliberately staging-only: configure its UUID through `COOLIFY_STAGING_PORTAL_DOMAIN_CONTROLLER_RESOURCE_UUID`, include it in the staging resource allowlist, and leave its Coolify route empty. Its only host port is the Prometheus endpoint bound to the staging WireGuard address (`10.42.0.3:19120:8080`); a wildcard, loopback-only, missing, or additional mapping is rejected. The staging workflow validates its runtime before mutation, pins the exact full-SHA image while clearing deployment hooks, and reconciles a revision-bound Node `cmd` healthcheck because Coolify's `dockerimage` build pack does not reliably expose the Dockerfile healthcheck. The command proves `/healthz`, `/readyz`, the controller service identity, and equality between the expected, baked, and runtime revision without adding `curl` or `wget` to the minimal image. The workflow requires Coolify's custom-image-health marker to remain false, triggers and waits on the exact returned deployment UUID, and accepts the release only as `running:healthy` with that exact command configuration.
|
||||
|
||||
The staging `hivegrid-web` and `hivegrid-portal` resources must both set `PORTAL_CUSTOM_DOMAIN_RUNTIME_ENABLED=true` exactly. The controller deployment helper verifies both values before any mutation. Production deliberately leaves this opt-in unset or false while no authorised production controller exists: the tenant-admin domain route, its admin link, and every custom-host request then fail closed with 404, while the standard portal host remains available. Enabling the production variable is part of the separately reviewed controller rollout and must never happen implicitly during staging promotion.
|
||||
|
||||
Production remains inactive until a separately authorised controller resource, host reachability and observability contract exist. The helper already reserves the fail-closed production CNAME and mesh binding (`10.42.0.8:19120:8080`), but the deploy workflow must not reference or require a production controller UUID before that provisioning is complete. Activating it is a separate reviewed rollout, not an implicit consequence of the staging change.
|
||||
|
||||
The controller receives exactly two writable bind mounts: the directory `/data/coolify/proxy/dynamic/hivegrid-portal-domains` and the single sentinel file `/data/coolify/proxy/dynamic/.hivegrid-portal-domains.reload`. Never mount the complete Traefik dynamic-config root. Set `PORTAL_DOMAIN_CONTROLLER_CONFIG_DIR` and `PORTAL_DOMAIN_CONTROLLER_RELOAD_TRIGGER_FILE` to those exact paths. Supply `PORTAL_DOMAIN_CONTROLLER_BACKEND_SERVICE` as the environment-specific provider-qualified Docker service name ending in `@docker`; `PORTAL_DOMAIN_CONTROLLER_ENTRYPOINT` is optional and defaults to `https`. Staging domain-flow tests use the exact expected CNAME `staging-domains.portal.hivegrid.de`; production uses `domains.portal.hivegrid.de` and remains separately configured.
|
||||
|
||||
The controller and `worker-general` share only the portal-domain command HMAC secret and the same Redis queue endpoint/database. `worker-general` must set `PORTAL_DOMAIN_ORCHESTRATION_REQUIRED=true`; it must not receive the controller metrics token. The controller additionally requires a distinct metrics token and its expected CNAME. Missing, duplicate, malformed, mismatched, or privileged runtime values fail the deployment before the controller resource is changed. Values remain CI/Coolify secrets and must never be recorded in the repository.
|
||||
If the self-hosted runner needs an internal hosts override for the Gitea registry, provide `HIVEGRID_GITEA_HOST_IP` as a CI variable. The workflows leave `/etc/hosts` untouched when that variable is absent.
|
||||
|
||||
Migrations and the seed run inside the web container entrypoint (`start.sh`), not in Coolify command slots: Coolify's `pre_deployment_command`/`post_deployment_command` never executed for docker-image applications, and a pre-deploy hook would run inside the old container without the new migration files anyway. With `MIGRATE_ON_BOOT=true` the entrypoint runs only reviewed Prisma migrations from the final image (`pnpm exec prisma migrate deploy --config prisma.config.ts`); with `SEED_ON_BOOT=true` it then runs the guarded production seed artifact (`node packages/db/dist/production-seed.server.js`). A failed migration or seed aborts the boot, so the deploy health gate fails instead of shipping a stale schema. The PR-level Docker web runtime smoke (`scripts/docker-web-runtime-smoke.sh`) boots the image through this same `MIGRATE_ON_BOOT`/`SEED_ON_BOOT` path against an empty database and asserts the boot banners, so every pull request rehearses the staging boot contract. Rollback path: set `MIGRATE_ON_BOOT=false`/`SEED_ON_BOOT=false` on the resource and redeploy, then run `pnpm exec prisma migrate deploy --config prisma.config.ts` manually inside the web container. The deploy workflow keeps both Coolify command slots cleared so the dead hook mechanism is not mistaken for an active one. Docker healthchecks use `/healthz`; `/readyz` remains the stricter readiness endpoint for manual/runtime probes after dependencies are available. The production seed path creates only the configured bootstrap admin plus roles, permissions, and entitlements, and requires `SEED_ADMIN_EMAIL` / `SEED_ADMIN_PASSWORD` in the Coolify environment.
|
||||
Staging may opt into the CRM SaaS demo seed through the guarded flags `SEED_DEMO_DATA=true` and `ALLOW_STAGING_DEMO_SEED=true` on the staging web resource; the boot seed picks them up from the container environment. That staging-only path adds demo Starter, Pro, and Business tenants, users, plan assignments, product blueprint configuration, tenant-owned roles, KB fixtures, and support tickets. The staging web runtime must also keep `SEED_DEMO_DATA=true` and `ALLOW_STAGING_DEMO_SEED=true` so those seeded demo users can log in while `NODE_ENV=production`. Do not set `SEED_DEMO_DATA=true` or `ALLOW_STAGING_DEMO_SEED=true` on production resources.
|
||||
Set `WORKER_ENABLED=true` only on worker Coolify resources. Leave it unset on web/API resources and avoid sharing a production env group that forces `WORKER_ENABLED=false` into worker containers. The deploy resource list must include separate worker applications with `WORKER_QUEUE_GROUP=general`, `mail`, `import`, `webhook`, and `plugin`; the deploy workflow identifies them by the group env marker or by resource names such as `worker-general`, `worker-mail`, `worker-import`, `worker-webhook`, and `worker-plugin`. `worker-import` is allowed to be a healthy idle topology placeholder with an empty queue list until `IMPORT_QUEUE_ENABLED=true` and `IMPORT_QUEUE_RUNTIME_READY=true` are backed by wired import, export, and scan services. Treat this deployment paragraph as a summary: `docs/ops/worker-queues.md` is the canonical worker topology and queue ownership reference.
|
||||
Migrations run in a short-lived container from the exact immutable web image being rolled out: `start.sh migrate` accepts only `DIRECT_URL`, verifies that it authenticates directly as the exact `hivegrid_migrator` role with no superuser, database-creation, role-creation, inheritance, replication, or `BYPASSRLS` capability and only the constrained `hivegrid_rls_definer` membership, runs the fail-closed Prisma-baseline adoption, aliases the URL to `DATABASE_URL` inside that process for Prisma CLI compatibility, runs `prisma migrate deploy`, verifies the resulting live schema against the current Prisma schema, runs the global permission-catalog reconcile only after both checks succeed, and then exits. It rejects runtime role markers and every `SEED_*` value. The migration step is fail-closed: a missing/unreachable credential, a semantic role mismatch, an incomplete or unknown legacy migration history, security-sensitive catalog drift behind a reviewed historical checksum, a failed migration, post-migration schema drift, a missing externally provisioned managed role, or a failed catalog reconcile stops the deployment before any Coolify resource is changed. Run `pnpm run db:roles:provision` with all five distinct login passwords (`HIVEGRID_RLS_MIGRATOR_PASSWORD`, `HIVEGRID_RLS_APP_PASSWORD`, `HIVEGRID_RLS_PORTAL_PASSWORD`, `HIVEGRID_RLS_WORKER_PASSWORD`, and `HIVEGRID_RLS_AUTHENTIK_JIT_PASSWORD`) before the cutover migration; the NOCREATEROLE migrator never creates or alters roles. Long-lived web/API/MCP/Hocuspocus containers receive only the `hivegrid_app` DSN; the customer-portal runtime receives only `hivegrid_portal`; workers receive only `hivegrid_worker`; all set `DATABASE_RUNTIME_ROLE` and `RLS_RUNTIME_MODE=required`. The core web resource additionally receives `AUTHENTIK_ADMIN_JIT_DATABASE_URL` only when Admin SSO is enabled; that URL must authenticate as the execute-only `hivegrid_authentik_jit` login and must not be copied to the portal, API, MCP, Hocuspocus, or worker resources. `DIRECT_URL`, `MIGRATOR_*`, `MIGRATE_ON_BOOT`, `SEED_ON_BOOT`, and `SEED_*` are forbidden in runtime resources. The PR Docker smokes rehearse that same boundary against an empty database. The deploy workflow keeps both Coolify command slots cleared so the dead hook mechanism is not mistaken for an active one. Docker healthchecks use `/healthz` as process liveness, except the dedicated Hocuspocus image, whose TCP healthcheck covers port 1234. MCP and workers use dependency-free Node `cmd` healthchecks against their loopback `/readyz` endpoints.
|
||||
|
||||
Der Reconcile bearbeitet ausschließlich globale `Permission`-Einträge, globale Defaultrollen (`tenantId IS NULL`) und deren katalogeigene `RolePermission`-Links. Innerhalb einer kurzen Transaktion erhält `hivegrid_rls_definer` nur die dafür nötigen DML-Rechte; sie werden vor dem Commit wieder entzogen. `FORCE ROW LEVEL SECURITY` bleibt durchgehend aktiv. Jede Abweichung der Sicherheitsgrenze oder Daten-Postcondition führt zum Rollback der gesamten Reconcile-Transaktion.
|
||||
|
||||
Nach AD-29 sind tenant-eigene Rollen und Rollen mit `isTemplateOrigin = true` von automatischen Deploy-Änderungen ausgeschlossen. Eine kanonische globale Rolle mit diesem Marker lässt den Reconcile vor Rollen-DML fail-closed abbrechen; Tenant-Rollen bleiben unberührt. Nachzüge für bestehende Tenants sind nur als ausdrücklich freigegebene und auditierte Operator-Aktion zulässig. Der Reconcile ist kein allgemeiner Seed und erteilt dafür keine Freigabe.
|
||||
Seeding is deliberately not part of the non-superuser migrator or any long-lived runtime. Existing bootstrap/demo seed tooling requires a separately reviewed, tenant-scoped operator workflow before it may be used under forced RLS. Do not set `SEED_DEMO_DATA=true`, `ALLOW_STAGING_DEMO_SEED=true`, `SEED_DEMO_PRO_MANAGED=true`, seed credentials, or seed flags on Coolify runtime resources.
|
||||
|
||||
The one-shot migrator runs on the **CI runner host**, not on the database host, so the migrator DSN must point at an address that is routable from the runner. A Coolify container hostname is not: it only resolves inside the target host's docker network. When it is unreachable, `scripts/verify-migrator-role.mjs` reports the generic `PostgreSQL migrator role verification failed` — that message is the catch-all for **connection** errors, not a role-contract violation (a real contract breach reports a specific reason), so check reachability before touching roles. On staging the database is therefore published on the WireGuard mesh address only (`10.42.0.3:5432`, never `0.0.0.0`); see `infra/LESSONS.md`. Clarify the same reachability question for production before opening the cutover window.
|
||||
|
||||
Signing in with a seeded staging demo account is a separate concern from seeding and therefore has its own runtime gate, `STAGING_DEMO_LOGIN_ENABLED=true` on the staging web resource. It only takes effect together with `SENTRY_ENVIRONMENT=staging`, so it cannot unlock a demo account in production. The gate previously rode on the `SEED_*` flags above; because `assert-runtime-db-env` rejects every `SEED_*`-prefixed key on a runtime resource, enforcing the deploy contract silently locked the staging demo accounts out until the gate was renamed.
|
||||
Set `WORKER_ENABLED=true` only on worker Coolify resources. Leave it unset on web/API resources and avoid sharing a production env group that forces `WORKER_ENABLED=false` into worker containers. The deploy resource list must include separate worker applications with `WORKER_QUEUE_GROUP=general`, `mail`, `import`, `webhook`, and `plugin`; the deploy workflow identifies them by the group env marker or by resource names such as `worker-general`, `worker-mail`, `worker-import`, `worker-webhook`, and `worker-plugin`. `worker-import` always owns `hivegrid.kwp-imports`; generic file imports remain separately gated. Full mode (`IMPORT_QUEUE_ENABLED=true` + `IMPORT_QUEUE_RUNTIME_READY=true`) adds `hivegrid.imports` and `hivegrid.exports` and requires wired import/export/scan **and** portal/privacy GDPR services plus complete HTTPS `STORAGE_*` and canonical `GDPR_EXPORT_SSE_C_KEY_BASE64`; the mutually exclusive internal `PORTAL_GDPR_EXPORT_QUEUE_ENABLED=true` mode adds only `hivegrid.exports` beside KWP and requires the same encrypted storage/GDPR services. The same SSE-C key must be provisioned on core web and portal web before that image is deployed; it is never exposed through a signed-URL redirect. The narrow mode never enables `hivegrid.imports` or the generic export service. Mixed gates, a non-import group, missing storage/encryption, or missing service wiring fail readiness/startup closed. Treat this deployment paragraph as a summary: `docs/ops/worker-queues.md` is the canonical worker topology and queue ownership reference.
|
||||
`worker-general` additionally owns the provider boundary keys `LAGO_API_URL`,
|
||||
`LAGO_API_KEY`, `LAGO_TIMEOUT_MS`, `MOLLIE_API_KEY`, `MOLLIE_PROFILE_ID`, and
|
||||
`MOLLIE_TIMEOUT_MS`, plus the environment-specific `BILLING_MOLLIE_WEBHOOK_URL`.
|
||||
`MOLLIE_PROFILE_ID` is optional and both timeouts use their
|
||||
documented defaults when unset. These keys plus
|
||||
`PRODUCT_ACQUISITION_PROVIDER_SIDE_EFFECT_REQUIRED` are exclusive to
|
||||
`worker-general`:
|
||||
the Coolify worker reconciler copies them from the approved runtime-env source
|
||||
only into that group, never into `worker-mail`, `worker-import`, `worker-webhook`,
|
||||
or `worker-plugin`. It removes provider keys left on those workers by older
|
||||
provisioning runs through their Coolify env UUID and fails closed before mutation
|
||||
when a key cannot be removed safely. Provider side effects default to required
|
||||
under `RLS_RUNTIME_MODE=required`; in that mode the reconciler rejects missing
|
||||
`LAGO_API_URL`, `LAGO_API_KEY`, `MOLLIE_API_KEY` or
|
||||
`BILLING_MOLLIE_WEBHOOK_URL` and malformed configured
|
||||
values before deploy. During an approved pre-live window,
|
||||
`PRODUCT_ACQUISITION_PROVIDER_SIDE_EFFECT_REQUIRED=false` is the only supported
|
||||
override: it disables the subscriber and waives the provider-key preflight without
|
||||
weakening RLS or any other worker dependency. Any value other than `true`, `false`
|
||||
or unset fails closed. Provider values remain in Coolify/secret storage and must
|
||||
not be printed by preflight or runbooks.
|
||||
The plugin worker belongs to the topology even while production plugin
|
||||
execution is gated: with `PLUGIN_RUNTIME_PRODUCTION_ENABLED` unset or `false`,
|
||||
`worker-plugin` is an idle service, not evidence that tenant plugin execution is
|
||||
approved.
|
||||
If `COOLIFY_STAGING_PROVISION_WORKER_GROUPS=true` or `COOLIFY_PROVISION_WORKER_GROUPS=true` is set with the matching project, server, environment, and destination UUID variables, the deploy workflow creates any missing worker-group applications through the Coolify Docker Image API before patching image tags. The provisioner copies runtime env from an existing worker source app when it creates a group resource, then overwrites the group-specific worker env, including distinct health and admin ports, so operators should keep an env-source worker app configured until all group resources have their own Coolify env.
|
||||
If `COOLIFY_STAGING_PROVISION_WORKER_GROUPS=true` or `COOLIFY_PROVISION_WORKER_GROUPS=true` is set with the matching project, server, environment, and destination UUID variables, the deploy workflow creates any missing worker-group applications through the Coolify Docker Image API before patching image tags. The provisioner copies runtime env from an existing worker source app when it creates a group resource, then overwrites the group-specific worker env, including distinct health and admin ports. It also creates or reconciles the enabled `cmd` healthcheck to the exact immutable SHA used for that deployment, so operators should keep an env-source worker app configured until all group resources have their own Coolify env.
|
||||
|
||||
B-012 is not a repository code blocker. The deploy workflow and Docker
|
||||
verifiers cover the repository contract, while the permanent fix for runner
|
||||
@@ -75,36 +166,41 @@ orphaned Gitea Actions networks.
|
||||
|
||||
Deploy secrets, registry credentials, Coolify URLs, UUIDs, personal access tokens, webhook tokens, and other deploy-only values must be supplied through CI secrets or a secret manager. Documentation, workflow logs, tickets, and verification summaries must use placeholder configuration only and must not commit, echo, or paste real URLs, UUIDs, tokens, passwords, registry credentials, or secret-shaped examples. Auto-Mode-safe proof is limited to repository/static checks and the configured CI workflow contract such as `pnpm run verify:deploy-workflow`, `node scripts/verify-gitea-deploy-workflow.mjs`, and focused verifier tests. Browser flows, Playwright, Cypress, and E2E checks remain manual exclusions unless a human explicitly approves the exact focused run.
|
||||
|
||||
## Production Docs Production Deployment Runbook
|
||||
## Release and rollback contract
|
||||
|
||||
Production Docs/S04 treats deployment proof as a layered contract. Auto-Mode may run `pnpm run verify:production-docs` to verify the production documentation set, plus existing static deploy verifiers such as `pnpm run verify:deploy-workflow`, `node scripts/verify-gitea-deploy-workflow.mjs`, `node scripts/verify-gitea-ci-workflow.mjs`, and focused verifier tests. These checks prove repository shape, documentation coverage, image-target policy, placeholder usage, and forbidden automatic browser/E2E command exclusions; they do not prove that a live Docker build, registry push, Coolify execution, or browser runtime succeeded.
|
||||
Deployment proof is layered. Static verifiers such as `pnpm run verify:deploy-workflow`,
|
||||
`node scripts/verify-gitea-deploy-workflow.mjs`, `node scripts/verify-gitea-ci-workflow.mjs` and
|
||||
focused tests prove repository shape and image policy; they do not prove a live registry push,
|
||||
Coolify rollout or browser flow.
|
||||
|
||||
The production image set is `web`, `api`, `mcp`, and `worker`. MCP uses a separate
|
||||
`mcp` target/resource for `hivegrid-mcp`; MCP must not be folded into the `api` or `web` runtime. Staging uses the same
|
||||
The production image set is `web`, `api`, `mcp`, `worker`, `hocuspocus`, and `portal-domain-controller`. MCP uses a separate
|
||||
`mcp` target/resource for `hivegrid-mcp`, and Hocuspocus uses its dedicated image/resource; neither must be folded into the `api` or `web` runtime. Staging uses the same
|
||||
target set with isolated runtime configuration in Coolify. Published image references must stay placeholder-only in docs
|
||||
and tickets, using safe target labels and tag labels rather than real registry hosts, namespaces, project IDs, UUIDs,
|
||||
credentials, or token-shaped examples. Every deployable image needs an immutable full-SHA tag; the `staging` alias
|
||||
identifies the currently staged image set, and the `main` alias is updated only by promotion. Operators should inspect
|
||||
workflow output for redacted target names, tag lists, and PASS/FAIL verifier lines only, never raw secrets.
|
||||
|
||||
Coolify execution is part of the main-branch stage path and the `workflow_dispatch` promote path. The workflow may trigger Coolify only after image publication or promotion prerequisites pass, and it deploys the migration-bearing web application first, verifies web health/revision, then deploys dependent API/worker resources by reading endpoint/resource data from configured CI variables and secrets. Documentation must not include Coolify URLs, webhook paths, UUIDs, bearer tokens, passwords, registry credentials, or derived endpoint examples. Pull requests and schedules must not invoke Coolify.
|
||||
Coolify execution is part of the main-branch stage path and the `workflow_dispatch` promote path. The workflow may trigger Coolify only after the exact-revision RLS gates and image publication or promotion prerequisites pass. It deploys the migration-bearing web application first, verifies web health/revision, then deploys dependent API, MCP, Hocuspocus, and worker resources by reading endpoint/resource data from configured CI variables and secrets. Hocuspocus acceptance requires Coolify `running:healthy` from the image TCP healthcheck plus the exact configured image SHA. Documentation must not include Coolify URLs, webhook paths, UUIDs, bearer tokens, passwords, registry credentials, or derived endpoint examples. Pull requests and schedules must not invoke Coolify.
|
||||
|
||||
Ad hoc live Docker builds, registry pushes, Coolify runs, browser flows, Playwright, Cypress, and E2E checks outside the configured Gitea deploy workflow are manual runtime activities unless a human explicitly approves the exact focused run. The Gitea deploy workflow may run Docker, registry, Coolify, migration, and web/API health steps automatically; record only redacted evidence: deployment status, image target names, immutable tag IDs, web/API service and revision health, worker execute-health status, worker group/queue summary, API `requestId` or `x-request-id` correlation, and queue/job identifiers. Worker live-revision proof is checked automatically through Coolify execute returning worker health JSON with revision data; if execute is unavailable, empty, or non-JSON, the automated rollout fails closed and operators must fix Coolify execute access before accepting the worker deploy. Do not paste database URLs, Redis URLs, Supabase keys, mail provider credentials, stack traces with secrets, webhook tokens, or container environment values.
|
||||
Ad hoc live Docker builds, registry pushes, Coolify runs, browser flows, Playwright, Cypress, and E2E checks outside the configured Gitea deploy workflow are manual runtime activities unless a human explicitly approves the exact focused run. The Gitea deploy workflow may run Docker, registry, Coolify, migration, and web/API health steps automatically; record only redacted evidence: deployment status, image target names, immutable tag IDs, web/API/MCP service and revision health, revision-bound command-health status, worker group/queue summary, API `requestId` or `x-request-id` correlation, and queue/job identifiers. Worker live-revision proof uses `node apps/worker/dist/deploy-health.js <40-character lowercase Git SHA> <worker-group>`; MCP uses `node apps/mcp/dist/deploy-health.js <40-character lowercase Git SHA>`. An absent, disabled, non-`cmd`, mismatched, or unhealthy command fails the automated rollout; operators must fix the runtime healthcheck contract before accepting the deploy. Do not paste database URLs, Redis URLs, Supabase keys, mail provider credentials, stack traces with secrets, webhook tokens, or container environment values.
|
||||
|
||||
Rollback uses immutable image tags instead of mutable guesses. Select the previous known-good SHA-derived tag for the affected target, redeploy it through the approved manual path, and confirm web/API health with `GET /healthz` and `GET /readyz` plus the documented API health endpoint while correlating request IDs across logs. For worker incidents, inspect the redacted worker health output, queue names, failed-job counts, and job/request correlation IDs; pause or drain queues through the operational tooling before replaying jobs. If readiness fails, capture the non-secret dependency diagnostic code, target name, tag, and correlation ID, then escalate with secret values omitted.
|
||||
Rollback uses immutable image tags instead of mutable guesses. Select the previous known-good full 40-character SHA for the affected target. Web and API may follow the approved manual redeploy path. Before invoking an MCP or worker rollback helper, provide the exact HiveGrid image identity through `MCP_IMAGE` / `WORKER_IMAGE` or the complete `REGISTRY` + `IMAGE_NAMESPACE` + `IMAGE_PREFIX` tuple; suffix-only target matching is intentionally rejected. For MCP and worker images built with the revision-bound deployment-health entrypoints, treat `docker_registry_image_tag` and `health_check_command` as one atomic configuration unit: changing only the image tag leaves the command bound to the newer revision and must fail closed. Reconcile MCP with `node scripts/coolify-deploy.mjs configure-mcp-healthcheck "$MCP_RESOURCE_UUID" "$OLD_FULL_SHA"`; reconcile workers with `IMAGE_TAG="$OLD_FULL_SHA" node scripts/coolify-ensure-worker-groups.mjs <staging-or-production>`, preserving each resource's exact `general`, `mail`, `import`, `webhook`, or `plugin` group. The worker reconciler is fleet-wide: after it succeeds, force-deploy all five worker resources and wait on every exact returned deployment UUID. Never reconcile the old SHA and trigger only one group, because the persisted configuration of the other groups already points at the rollback. MCP is triggered separately and likewise waited by its exact deployment UUID.
|
||||
|
||||
There is one bootstrap exception: images from before the revision-bound entrypoints existed do not contain `apps/mcp/dist/deploy-health.js`, `apps/worker/dist/deploy-health.js`, or `/myapp/.image-revision`. Never point the new command at such an image. Use `node scripts/coolify-deploy.mjs configure-legacy-rollback-healthcheck "$RESOURCE_UUID" "$OLD_FULL_SHA" [worker-group]`; the optional group is mandatory for workers. The helper validates the full SHA, rejects a Coolify `APP_REVISION` override or group drift, atomically sets the old tag, disables command health, clears the command, and rereads the resource fail-closed. Then force-deploy and wait on the exact deployment UUID. This is a degraded, emergency-only bootstrap rollback: Coolify cannot use the disabled command as its candidate gate, so brief downtime is possible. Accept the legacy MCP only after Coolify reports `running:healthy` and public `/readyz` reports `service=mcp`, the exact old revision, and successful dependency checks. Accept each legacy worker only after Coolify reports `running:healthy`, the live container digest/OCI revision resolves to the old SHA image through the approved read-only host check, `node apps/worker/dist/health.js` reports the image-baked old revision, enabled processing, exact group, and ready dependencies, and the Coolify `APP_REVISION` override remains absent. This compatibility path is for rollback only. Re-enable and verify the SHA-bound `cmd` healthcheck before the next roll-forward to a current image. All identifiers above are placeholders; never paste real UUIDs, endpoints, tokens, or credentials into documentation or logs. Confirm web/API health with `GET /healthz` and `GET /readyz` plus the documented API health endpoint. For worker incidents, inspect redacted health output, queue names, failed-job counts, and correlation IDs; pause or drain queues before replaying jobs. If readiness fails, capture only the non-secret diagnostic code, target name, tag, and correlation ID.
|
||||
|
||||
## Health Baseline Health Baseline Gate
|
||||
|
||||
S02 enforces CI-safe static contracts for the web and API liveness/readiness endpoints. The web app exposes `GET /healthz` through `apps/web/app/routes/healthz.tsx` as a lightweight liveness route with no database dependency, and `GET /readyz` through `apps/web/app/routes/readyz.tsx` as a database-backed readiness route. The API exposes unauthenticated `GET /healthz` and `GET /readyz`; successful responses include non-secret JSON with `service: "api"`, `revision`, and `requestId`, and `/readyz` returns HTTP 503 with a redacted dependency diagnostic code when readiness fails.
|
||||
S02 enforces CI-safe static contracts for the web and API liveness/readiness endpoints. The web app exposes `GET /healthz` through `apps/web/app/routes/healthz.tsx` as a lightweight liveness route with no database dependency, and `GET /readyz` through `apps/web/app/routes/readyz.tsx` as a database-backed readiness route; both return the non-secret runtime service, surface, and image-baked revision, while readiness failures remain redacted. The API exposes unauthenticated `GET /healthz` and `GET /readyz`; successful responses include non-secret JSON with `service: "api"`, `revision`, and `requestId`, and `/readyz` returns HTTP 503 with a redacted dependency diagnostic code when readiness fails.
|
||||
|
||||
Auto-Mode-safe verification commands:
|
||||
|
||||
| Command | Purpose |
|
||||
| --- | --- |
|
||||
| `pnpm exec vitest run apps/web/app/routes/healthz.test.ts apps/web/app/routes/readyz.test.ts` | Focused web route coverage for liveness/readiness response behavior. |
|
||||
| `pnpm exec vitest run apps/api/src/app.test.ts apps/api/src/openapi.test.ts` | Focused API route and OpenAPI coverage for `/healthz` and `/readyz`. |
|
||||
| `pnpm exec vitest run scripts/verify-health-baseline.test.mjs` | Static verifier fixture coverage, including missing web/API endpoint regressions and worker DB-readiness regressions. |
|
||||
| `node scripts/verify-health-baseline.mjs` | Static repository baseline check with deterministic path-specific `PASS`, `OBSERVE`, and `FAIL` lines for web, API, and worker health contracts. |
|
||||
| Command | Purpose |
|
||||
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `pnpm exec vitest run apps/web/app/routes/healthz.test.ts apps/web/app/routes/readyz.test.ts` | Focused web route coverage for liveness/readiness response behavior. |
|
||||
| `pnpm exec vitest run apps/api/src/app.test.ts apps/api/src/openapi.test.ts` | Focused API route and OpenAPI coverage for `/healthz` and `/readyz`. |
|
||||
| `pnpm exec vitest run scripts/verify-health-baseline.test.mjs` | Static verifier fixture coverage, including missing web/API endpoint regressions and worker DB-readiness regressions. |
|
||||
| `node scripts/verify-health-baseline.mjs` | Static repository baseline check with deterministic path-specific `PASS`, `OBSERVE`, and `FAIL` lines for web, API, and worker health contracts. |
|
||||
|
||||
The verifier output must no longer contain web/API observations saying `/healthz` or `/readyz` is not present, and worker DB readiness must be reported as an enforced pass/fail baseline rather than an observation. Missing web routes, missing API routes, web liveness database usage, missing web readiness database checks, missing API `/readyz` 503 dependency diagnostics, and missing worker DB readiness are all baseline failures.
|
||||
|
||||
@@ -114,12 +210,12 @@ Manual runtime inspection remains separate from Auto-Mode. A human may inspect a
|
||||
|
||||
The worker target is statically/package verified by these CI-safe commands:
|
||||
|
||||
| Command | Purpose |
|
||||
| --- | --- |
|
||||
| `pnpm --filter @hivegrid/worker build` | Confirms the worker package emits compiled runtime files for `node dist/index.js` and `node dist/health.js`. |
|
||||
| `pnpm exec vitest run apps/worker/src/index.test.ts apps/worker/src/health.test.ts scripts/verify-docker-baseline.test.mjs scripts/verify-health-baseline.test.mjs` | Exercises worker runtime/package tests and static verifier coverage, including worker `tsx` leakage and DB-readiness regressions. |
|
||||
| `node scripts/verify-docker-baseline.mjs` | Performs the static Dockerfile/package contract check and emits path-specific PASS/FAIL output for worker Docker target copy paths, start scripts, health scripts, and runtime `tsx` usage. |
|
||||
| `node scripts/verify-health-baseline.mjs` | Enforces that worker health statically reports Redis parse state and DB readiness without requiring live DB access. |
|
||||
| Command | Purpose |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `pnpm --filter @hivegrid/worker build` | Confirms the worker package emits compiled runtime files for `node dist/index.js` and `node dist/health.js`. |
|
||||
| `pnpm exec vitest run apps/worker/src/index.test.ts apps/worker/src/health.test.ts scripts/verify-docker-baseline.test.mjs scripts/verify-health-baseline.test.mjs` | Exercises worker runtime/package tests and static verifier coverage, including worker `tsx` leakage and DB-readiness regressions. |
|
||||
| `node scripts/verify-docker-baseline.mjs` | Performs the static Dockerfile/package contract check and emits path-specific PASS/FAIL output for worker Docker target copy paths, start scripts, health scripts, and runtime `tsx` usage. |
|
||||
| `node scripts/verify-health-baseline.mjs` | Enforces that worker health statically reports Redis parse state and DB readiness without requiring live DB access. |
|
||||
|
||||
Manual Docker smoke verification is intentionally separate from Auto-Mode. A human may run a focused build such as `docker build --target worker -t hivegrid-worker:smoke .`, then run the image with safe environment key names only, for example `WORKER_ENABLED`, `WORKER_QUEUE_GROUP`, `WORKER_HEALTH_PORT`, `WORKER_ADMIN_PORT`, `DATABASE_URL`, `BULLMQ_REDIS_URL`, fallback `REDIS_URL`, group-specific fail-loud keys, and mail provider keys supplied by the local shell or secret manager rather than written into docs. To inspect the worker healthcheck inside a container, run `node apps/worker/dist/health.js`; the JSON output is expected to report whether the worker is enabled/configured, whether Redis configuration parses, the DB readiness state, queue names, and redacted dependency codes, without echoing Redis URLs, passwords, database connection strings, stack traces, tokens, or other deployment secret values. Auto-Mode did not run live Docker build/run smoke checks, browser flows, Playwright, Cypress, or E2E commands for S04; the recorded proof is limited to static/package verification.
|
||||
|
||||
@@ -127,11 +223,11 @@ Manual Docker smoke verification is intentionally separate from Auto-Mode. A hum
|
||||
|
||||
The API target is statically/package verified by these task-scoped commands:
|
||||
|
||||
| Command | Purpose |
|
||||
| --- | --- |
|
||||
| `pnpm --filter @hivegrid/api build` | Confirms the API package can compile `apps/api/src` into `apps/api/dist`, including `dist/server.js` for the Docker runtime start path. |
|
||||
| Command | Purpose |
|
||||
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `pnpm --filter @hivegrid/api build` | Confirms the API package can compile `apps/api/src` into `apps/api/dist`, including `dist/server.js` for the Docker runtime start path. |
|
||||
| `pnpm exec vitest run scripts/verify-docker-baseline.test.mjs` | Exercises the Docker baseline verifier test coverage, including API-target PASS/FAIL cases for required copies and `tsx` runtime leakage. |
|
||||
| `node scripts/verify-docker-baseline.mjs` | Performs the static Dockerfile/package contract check and emits path-specific PASS/FAIL output for the API target. |
|
||||
| `node scripts/verify-docker-baseline.mjs` | Performs the static Dockerfile/package contract check and emits path-specific PASS/FAIL output for the API target. |
|
||||
|
||||
Runtime inspection for a manually run API container should use `GET /v1/health`. A healthy response is expected to identify `service: "api"` and include a `requestId`; startup logs should include the structured `API listening` message with a redacted `port` field. Safe environment keys that may be supplied by deployment automation include `PORT`, `NODE_ENV`, database connection variables, Supabase keys, and JWT/password-hash configuration keys; documentation and logs must not include secret values.
|
||||
|
||||
|
||||
@@ -1,325 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="de">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>HiveGrid Cloud – Entwicklungs-Regeln & Infrastruktur</title>
|
||||
<style>
|
||||
@page {
|
||||
size: A4;
|
||||
margin: 22mm 18mm 20mm 18mm;
|
||||
@bottom-center { content: counter(page) " / " counter(pages); font-size: 9px; color: #9a958c; }
|
||||
@bottom-left { content: "HiveGrid Cloud – Engineering Handbook"; font-size: 9px; color: #9a958c; }
|
||||
}
|
||||
@page :first { margin: 0; @bottom-center { content: ""; } @bottom-left { content: ""; } }
|
||||
* { box-sizing: border-box; }
|
||||
html { font-size: 11px; }
|
||||
body { font-family: -apple-system, "Segoe UI", "Helvetica Neue", Arial, sans-serif; color: #231F20; line-height: 1.5; margin: 0; }
|
||||
|
||||
/* Cover */
|
||||
.cover { height: 297mm; padding: 40mm 24mm 0 24mm; background: linear-gradient(158deg, #2b2521 0%, #1c1813 60%, #14110d 100%); color: #fff; page-break-after: always; position: relative; }
|
||||
.cover .logo { width: 250px; margin-bottom: 46mm; }
|
||||
.cover .kicker { font-size: 13px; letter-spacing: 3px; text-transform: uppercase; color: #F1B729; font-weight: 600; }
|
||||
.cover h1 { font-size: 39px; line-height: 1.1; margin: 14px 0 10px 0; font-weight: 700; color: #fff; }
|
||||
.cover h1 .accent { color: #F1B729; }
|
||||
.cover h2 { font-size: 17px; font-weight: 400; color: #d8d3c8; margin: 0 0 32px 0; }
|
||||
.cover .meta { font-size: 12px; color: #ddd8cd; line-height: 1.9; border-top: 2px solid #F1B729; padding-top: 18px; max-width: 122mm; }
|
||||
.cover .meta strong { color: #F1B729; }
|
||||
.cover .badge { display:inline-block; background: rgba(241,183,41,.12); border:1px solid rgba(241,183,41,.55); color:#F1B729; border-radius: 20px; padding: 4px 13px; font-size: 11px; margin: 2px 4px 2px 0; }
|
||||
|
||||
/* TOC */
|
||||
.toc { page-break-after: always; }
|
||||
.toc .logo-dark { width: 150px; display:block; margin: 4mm 0 8mm 0; }
|
||||
.toc h2 { border:none; }
|
||||
.toc ol { list-style: none; padding-left: 0; counter-reset: toc; }
|
||||
.toc > ol > li { counter-increment: toc; padding: 6px 0; border-bottom: 1px dotted #ddd6c5; font-weight: 600; color:#231F20; font-size: 12px; }
|
||||
.toc > ol > li::before { content: counter(toc) ". "; color:#c69412; font-weight:700; }
|
||||
|
||||
/* Headings */
|
||||
h2.section { font-size: 19px; color: #231F20; border-bottom: 3px solid #F1B729; padding-bottom: 5px; margin-top: 28px; break-after: avoid; }
|
||||
h3 { font-size: 14px; color: #9a720b; margin-top: 18px; break-after: avoid; }
|
||||
p { margin: 6px 0; }
|
||||
ul, ol { margin: 6px 0; padding-left: 20px; }
|
||||
li { margin: 3px 0; }
|
||||
code { font-family: "SF Mono", "Menlo", Consolas, monospace; background: #fbf1d4; padding: 1px 5px; border-radius: 3px; font-size: 9.5px; color: #82610a; }
|
||||
strong { color: #231F20; }
|
||||
.lead { font-size: 12.5px; color: #5a544a; }
|
||||
|
||||
/* Tables */
|
||||
table { width: 100%; border-collapse: collapse; margin: 10px 0; font-size: 9.7px; break-inside: avoid; }
|
||||
th { background: #231F20; color: #fff; text-align: left; padding: 6px 8px; font-weight: 600; border-bottom: 2px solid #F1B729; }
|
||||
td { border-bottom: 1px solid #e7e1d2; padding: 5px 8px; vertical-align: top; }
|
||||
tr:nth-child(even) td { background: #faf6ec; }
|
||||
|
||||
/* Callouts */
|
||||
.callout { border-left: 4px solid #F1B729; background: #fdf6e2; padding: 9px 14px; margin: 12px 0; border-radius: 0 5px 5px 0; break-inside: avoid; }
|
||||
.callout.warn { border-left-color: #c2410c; background: #fdf0e8; }
|
||||
.callout.ok { border-left-color: #15803d; background: #edf8ef; }
|
||||
.callout .t { font-weight: 700; display:block; margin-bottom: 2px; color:#231F20; }
|
||||
|
||||
.pill { display:inline-block; font-size:8.5px; font-weight:700; padding:1px 7px; border-radius:10px; vertical-align:middle; }
|
||||
.pill.block { background:#fadddd; color:#9b1c1c; }
|
||||
.pill.local { background:#fbe9b0; color:#82610a; }
|
||||
.small { font-size: 9.5px; color:#6b665c; }
|
||||
hr { border:none; border-top:1px solid #e7e1d2; margin: 18px 0; }
|
||||
|
||||
/* Page-break protection */
|
||||
section.sw { break-inside: avoid; }
|
||||
.group { break-inside: avoid; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<div class="cover">
|
||||
<img class="logo" src="assets/hivegrid-logo-white.svg" alt="HiveGrid">
|
||||
<div class="kicker">Engineering Handbook</div>
|
||||
<h1>Entwicklungs-Regeln<br>& <span class="accent">Infrastruktur</span></h1>
|
||||
<h2>Verbindliche Standards für die gemeinsame Entwicklung</h2>
|
||||
<div>
|
||||
<span class="badge">0 Warnings</span>
|
||||
<span class="badge">TypeScript strict</span>
|
||||
<span class="badge">Hohe Test-Coverage</span>
|
||||
<span class="badge">Pflicht-E2E</span>
|
||||
<span class="badge">Accessibility AA</span>
|
||||
<span class="badge">EU-Stack</span>
|
||||
<span class="badge">~80 Quality-Gates</span>
|
||||
</div>
|
||||
<div class="meta">
|
||||
<strong>Produkt:</strong> HiveGrid 2.0 – B2B-SaaS für CRM & projektbasiertes Arbeiten<br>
|
||||
<strong>Codebasis:</strong> Git-Downstream des HiveGrid-Boilerplates (pnpm-Monorepo)<br>
|
||||
<strong>Stand:</strong> 14. Juni 2026<br>
|
||||
<strong>Grundsatz:</strong> Regeln sind durch automatische Gates erzwungen, nicht durch
|
||||
guten Willen. Was rot ist, wird nicht gemerged.
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="toc">
|
||||
<img class="logo-dark" src="assets/hivegrid-logo.svg" alt="HiveGrid">
|
||||
<h2 class="section">Inhalt</h2>
|
||||
<ol>
|
||||
<li>Was HiveGrid Cloud ist (Produktkontext)</li>
|
||||
<li>Codebasis-Modell: Git-Downstream & Package-Namen</li>
|
||||
<li>Grundprinzipien</li>
|
||||
<li>Code-Qualität & Linting (0 Warnings)</li>
|
||||
<li>TypeScript & Typsicherheit</li>
|
||||
<li>Formatierung (Prettier)</li>
|
||||
<li>Unit- & Integrationstests + Coverage</li>
|
||||
<li>End-to-End-Tests (Playwright)</li>
|
||||
<li>Accessibility (a11y)</li>
|
||||
<li>Quality-Gates: Commit → Push → Merge → Deploy</li>
|
||||
<li>CI/CD-Pipeline</li>
|
||||
<li>Infrastruktur & Hosting</li>
|
||||
<li>Architektur-Konventionen (inkl. EU-Stack)</li>
|
||||
<li>Onboarding-Checkliste</li>
|
||||
</ol>
|
||||
</div>
|
||||
|
||||
<!-- 1 -->
|
||||
<section class="sw">
|
||||
<h2 class="section">1. Was HiveGrid Cloud ist</h2>
|
||||
<p class="lead">HiveGrid 2.0 ist ein B2B-SaaS für Kontaktmanagement (CRM) und projektbasiertes Arbeiten – mit konsequent europäischem Datenschutz- und Hosting-Anspruch.</p>
|
||||
<ul>
|
||||
<li><strong>Kern-Domäne:</strong> Kontakte/Leads → projektbasierte Pipelines (Vertrieb, HR-Onboarding, Kundenbetreuung) → Auftragsabwicklung.</li>
|
||||
<li><strong>Datenmodell:</strong> typisierte First-Class-Tabellen (z. B. <code>Kontakt</code>, <code>Projekt</code>) statt generischer Entity-Builder.</li>
|
||||
<li><strong>EU-Stack (nicht verhandelbar):</strong> AI über EU-Provider (Scaleway, Mistral, Aleph Alpha; keine US-Provider), EU-Hosting auf Hetzner/Coolify, Auth über E-Mail+Passwort / Magic-Link / TOTP (kein Apple/Google/Microsoft-OAuth), Per-Tenant-Envelope-Encryption, Postgres mit Row-Level-Security als Defense-in-Depth.</li>
|
||||
<li><strong>Bauweise:</strong> aufgeteilt in 176 Milestones (Pflichtenheft v1.1), Phase 0 → Fundament → Wertschöpfung.</li>
|
||||
</ul>
|
||||
<div class="callout">
|
||||
<span class="t">Begriffsklärung</span>
|
||||
<strong>HiveGrid Cloud</strong> ist die SaaS-Anwendung (dieses Repo, in aktiver Entwicklung). Die Marketing-Website <code>hivegrid.de</code> ist ein separates Projekt auf einem anderen Host – nicht zu verwechseln.
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- 2 -->
|
||||
<section class="sw">
|
||||
<h2 class="section">2. Codebasis-Modell: Git-Downstream & Package-Namen</h2>
|
||||
<p>HiveGrid Cloud ist <strong>kein klassischer Fork</strong>, sondern ein <strong>Git-Downstream</strong> des HiveGrid-Boilerplates: Verbesserungen aus dem Boilerplate werden per <code>git merge upstream/main</code> übernommen. Damit das funktioniert, bleiben Package-Namen und Konfiguration absichtlich kompatibel.</p>
|
||||
<div class="callout warn">
|
||||
<span class="t">Wichtig zu den Package-Namen (häufiges Missverständnis)</span>
|
||||
Es gibt <strong>kein flächiges Rename</strong> auf <code>@hivegrid/*</code>. Geteilte Boilerplate-Pakete behalten <code>@hivegrid/*</code> – sonst brechen Upstream-Merges. Entscheidung dokumentiert in <code>docs/ARCHITECTURE-DECISIONS.md</code> und <code>AGENTS.md</code>.
|
||||
</div>
|
||||
<table>
|
||||
<tr><th>Scope</th><th>Wofür</th><th>Beispiele</th></tr>
|
||||
<tr><td><code>@hivegrid/*</code></td><td>Alle vom Boilerplate geteilten Pakete (bleiben so, für Mergebarkeit)</td><td><code>@hivegrid/web</code>, <code>@hivegrid/api</code>, <code>@hivegrid/db</code>, <code>@hivegrid/foundation</code>, <code>@hivegrid/ui-app</code>, …</td></tr>
|
||||
<tr><td><code>@hivegrid/*</code></td><td><strong>Nur</strong> genuin neue HiveGrid-Pakete, die es upstream nie gibt</td><td><code>@hivegrid/activity</code> (Activity-Stream-Service)</td></tr>
|
||||
</table>
|
||||
<p class="small">Mapping-Hinweis: Wo ältere Docs/Pläne <code>packages/ui-hivegrid</code> oder <code>@hivegrid/foundation</code> sagen, ist real <code>packages/ui-app</code> bzw. <code>@hivegrid/foundation</code> gemeint. Ein späterer Naming-Drift-Fix ist in den ADRs als Option notiert, aber bewusst noch nicht umgesetzt.</p>
|
||||
<p><strong>Neu in HiveGrid:</strong> <code>@hivegrid/activity</code> – zentraler Activity-Stream/Änderungs-Historie, hängt nur an <code>@hivegrid/db</code>. Weitere HiveGrid-spezifische Pakete folgen demselben Muster.</p>
|
||||
<p><strong>Node-Version:</strong> HiveGrid nutzt <code>v22.12.0</code> (<code>.nvmrc</code>) – neuer als der Boilerplate. Vor der Arbeit <code>nvm use</code> ausführen.</p>
|
||||
</section>
|
||||
|
||||
<!-- 3 -->
|
||||
<section class="sw">
|
||||
<h2 class="section">3. Grundprinzipien</h2>
|
||||
<ul>
|
||||
<li><strong>Linting:</strong> Kompromisslos – <code>--max-warnings=0</code>. Eine Warning bricht den Build.</li>
|
||||
<li><strong>Typsicherheit:</strong> TypeScript <code>strict</code>. <code>any</code>/Type-Escapes nur über eine gedeckelte Baseline.</li>
|
||||
<li><strong>Tests:</strong> Sehr hohe Coverage auf kritischen Pfaden (Auth, Billing, Tenant-Isolation ~99 %), erzwungen pro Verzeichnis.</li>
|
||||
<li><strong>End-to-End:</strong> Pflicht. Kritische Flows müssen als Playwright-Specs existieren; ein Gate prüft wörtliche Test-Inhalte.</li>
|
||||
<li><strong>Accessibility:</strong> WCAG 2.2 AA als Gate (Farbkontrast, Mobile-Overflow).</li>
|
||||
<li><strong>EU-Datenschutz by design:</strong> RLS, Envelope-Encryption und EU-only-Provider sind Architektur-Vorgaben, kein Add-on.</li>
|
||||
<li><strong>Automatisierung statt Disziplin:</strong> ~80 <code>verify:*</code>-Gates erzwingen die Regeln in Pre-Commit-Hooks und CI.</li>
|
||||
</ul>
|
||||
<div class="callout"><span class="t">Leitsatz</span>Fehler nach links schieben: Was lokal in Sekunden gefangen werden kann, läuft im Pre-Commit-Hook. CI ist Sicherheitsnetz, nicht erster Prüfer.</div>
|
||||
</section>
|
||||
|
||||
<!-- 4 -->
|
||||
<section class="sw">
|
||||
<h2 class="section">4. Code-Qualität & Linting</h2>
|
||||
<p>ESLint mit <code>@typescript-eslint</code>, <code>import</code>, <code>jsx-a11y</code>, <code>react-hooks</code> (Basis <code>plugin:jsx-a11y/recommended</code>). Konfiguration identisch zum Boilerplate.</p>
|
||||
<div class="callout warn"><span class="t">Die wichtigste Regel</span><code>pnpm run lint</code> = <code>eslint --max-warnings=0 --ext .tsx,.ts .</code> — <strong>Null Warnings.</strong> Es gibt keine „gelben" Builds.</div>
|
||||
<div class="group">
|
||||
<h3>Harte Regeln (Error-Level)</h3>
|
||||
<table>
|
||||
<tr><th>Regel</th><th>Wirkung</th></tr>
|
||||
<tr><td><code>no-debugger</code></td><td>Kein <code>debugger</code>.</td></tr>
|
||||
<tr><td><code>no-console</code> (Server)</td><td>In Server-Code (<code>*.server.ts</code>, <code>apps/api</code>, <code>apps/worker</code>, <code>packages/*/src</code>, Service-/DB-Layer) verboten; in UI/Tests/Skripten erlaubt.</td></tr>
|
||||
<tr><td><code>no-restricted-imports</code></td><td>Kein direkter <code>@prisma/client</code> (nur über <code>@hivegrid/db</code>); keine direkten <code>src/*</code>-Imports zwischen Packages; <code>foundation</code>/<code>view-models</code> ohne React/UI; UI-Packages ohne DB.</td></tr>
|
||||
<tr><td><code>no-restricted-syntax</code> (Phase-C-UI)</td><td>Keine hartkodierten nutzersichtbaren Strings in <code>ui-app</code>/<code>ui-subframe</code>/<code>ui-mock</code> – alles über i18n-Keys.</td></tr>
|
||||
</table>
|
||||
</div>
|
||||
<div class="group">
|
||||
<h3>Accessibility-Lint & Escape-Hatch-Baseline</h3>
|
||||
<p>jsx-a11y-Regeln „monoton fallend": bei 0 Verstößen werden sie auf <code>error</code> hochgestuft und können nie wieder regredieren. Type-/Lint-Ausnahmen sind gedeckelt (<code>verify:eslint-baseline</code>): max. <strong>262</strong> <code>eslint-disable</code>, <strong>35</strong> <code>@ts-ignore</code>, <strong>43</strong> <code>@ts-expect-error</code>. Neue brauchen Baseline-Erhöhung + Review.</p>
|
||||
<p class="small">Datei-Limits: <code>apps/api/src/app.ts</code> ≤ 450 Zeilen, API-Route-Module ≤ 500 Zeilen (<code>verify:source-health</code>).</p>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- 5 -->
|
||||
<section class="sw">
|
||||
<h2 class="section">5. TypeScript & Typsicherheit</h2>
|
||||
<ul>
|
||||
<li><code>strict: true</code> (inkl. <code>noImplicitAny</code>, <code>strictNullChecks</code> …). <code>any</code> praktisch verboten.</li>
|
||||
<li>Typecheck ist Pflicht nach Routen-Änderungen und läuft als Pre-Push-Hook.</li>
|
||||
</ul>
|
||||
<div class="callout"><span class="t">React-Router-v7-Regel</span>Routen-Typen <strong>immer</strong> aus <code>./+types/[routeName]</code> (nie relativ). Fehlen Typen → <code>pnpm run typecheck</code>, nie den Importpfad „reparieren".</div>
|
||||
</section>
|
||||
|
||||
<!-- 6 -->
|
||||
<section class="sw">
|
||||
<h2 class="section">6. Formatierung (Prettier)</h2>
|
||||
<table>
|
||||
<tr><th>Einstellung</th><th>Wert</th><th>Einstellung</th><th>Wert</th></tr>
|
||||
<tr><td>printWidth</td><td>160</td><td>semi</td><td>true</td></tr>
|
||||
<tr><td>singleQuote</td><td>false (Double Quotes)</td><td>tabWidth</td><td>2 (Spaces)</td></tr>
|
||||
<tr><td>trailingComma</td><td>es5</td><td>arrowParens</td><td>always</td></tr>
|
||||
<tr><td>endOfLine</td><td>lf</td><td>Plugin</td><td>prettier-plugin-tailwindcss</td></tr>
|
||||
</table>
|
||||
</section>
|
||||
|
||||
<!-- 7 -->
|
||||
<section class="sw">
|
||||
<h2 class="section">7. Unit- & Integrationstests + Coverage</h2>
|
||||
<p>Vitest + Testing Library (jsdom), Coverage-Provider v8. Schwellen identisch zum Boilerplate und <strong>pro Verzeichnis</strong> erzwungen (<code>verify:test-coverage</code> gegen <code>scripts/coverage-targets.json</code>).</p>
|
||||
<table>
|
||||
<tr><th>Kritischer Pfad</th><th>Statements</th><th>Branches</th></tr>
|
||||
<tr><td>API Auth</td><td>99 %</td><td>92 %</td></tr>
|
||||
<tr><td>Billing</td><td>99 %</td><td>97 %</td></tr>
|
||||
<tr><td>Tenant-Isolation</td><td>99 %</td><td>99 %</td></tr>
|
||||
<tr><td>Session / Permissions</td><td>99 %</td><td>98 %</td></tr>
|
||||
<tr><td>Legacy-Provider</td><td>95 %</td><td>90 %</td></tr>
|
||||
<tr><td>Basis-Targets (z. B. apps/api)</td><td>70 %</td><td>60 %</td></tr>
|
||||
</table>
|
||||
<p><strong>Test-Dichte-Gate</strong> (Pre-Commit): Mindestverhältnis Tests/Quelldateien je Workspace (z. B. <code>apps/api</code> ≥ 0,18; App-Routes ≥ 0,05; <code>packages/brand</code>/<code>config</code> ≥ 0,50). Neue HiveGrid-Pakete (z. B. <code>@hivegrid/activity</code>) brauchen eigene Tests.</p>
|
||||
<p class="small">Konventionen: <code>*.test.ts(x)</code> / <code>*.spec.ts</code>; Boundary <code>*boundary.test.ts</code>; a11y <code>*.a11y.test.tsx</code> / <code>*.axe.test.tsx</code>.</p>
|
||||
</section>
|
||||
|
||||
<!-- 8 -->
|
||||
<section class="sw">
|
||||
<h2 class="section">8. End-to-End-Tests (Playwright)</h2>
|
||||
<p>Verzeichnis <code>tests/e2e</code> (~39 Specs). Chromium, optional Mobile-Matrix (Pixel 5 + iPhone 13). Seriell, Timeout 120 s, Traces bei Fehlern. E2E laufen nächtlich gegen die Live-Staging-Umgebung; Basis ist ein deterministischer Readiness-Tenant (<code>seed:e2e-readiness</code>).</p>
|
||||
<div class="group">
|
||||
<h3>a11y-Coverage-Gate (pinnt Tests wörtlich)</h3>
|
||||
<p><code>verify:a11y-coverage</code> verlangt ≥ 12 Component-a11y-Tests und ≥ 7 E2E-a11y-Specs und prüft wörtliche Snippets kritischer Flows (z. B. <code>expectNoCriticalA11yViolations(</code>, <code>expectNoHorizontalOverflow(</code>).</p>
|
||||
<div class="callout warn"><span class="t">Nach E2E-Refactors</span>Das Gate matcht <strong>literale Strings</strong>. Tests umbenennen/umbauen → <code>verify:a11y-coverage</code> erneut laufen lassen.</div>
|
||||
</div>
|
||||
<div class="group">
|
||||
<h3>RR7 Single-Fetch-Interceptor-Contract</h3>
|
||||
<p>Form-POST-Interceptoren müssen das <code>.data</code>-Ziel matchen und <strong>turbo-stream</strong> zurückgeben (kein rohes JSON), inkl. <code>X-Remix-Response: yes</code>. Helfer in <code>tests/e2e/utils/navigation.ts</code>.</p>
|
||||
<p class="small">Pflicht-Flows (Auszug): Registration/Onboarding, Golden-Path, Subscription-Smoke, Plugin-Settings/-Lifecycle, Workflow-Builder+Run, Members, Audit, Profile-Security, Privacy, API-Keys, Mobile-Shell.</p>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- 9 -->
|
||||
<section class="sw">
|
||||
<h2 class="section">9. Accessibility</h2>
|
||||
<p>jsx-a11y-Lint · <code>verify:color-contrast</code> (WCAG 2.2 AA) · axe-core-Suite (<code>test:a11y</code>) · Mobile-Overflow-/Violation-Checks in E2E · Lighthouse-a11y als Warnung.</p>
|
||||
</section>
|
||||
|
||||
<!-- 10 -->
|
||||
<section class="sw">
|
||||
<h2 class="section">10. Quality-Gates: Commit → Push → Merge → Deploy</h2>
|
||||
<div class="group">
|
||||
<h3>Beim Commit <span class="pill local">lefthook pre-commit · parallel</span></h3>
|
||||
<p>lint-staged (ESLint auf geänderten Dateien) · <code>verify-secrets</code> · <code>verify-eslint-baseline</code> · <code>verify-test-density</code>.</p>
|
||||
</div>
|
||||
<div class="group">
|
||||
<h3>Beim Push <span class="pill local">lefthook pre-push · seriell</span></h3>
|
||||
<p><code>typecheck</code> · <code>verify-hardcoded-strings</code> (i18n). Notfall-Bypass nur mit <code>LEFTHOOK=0</code>, nie auf <code>main</code>.</p>
|
||||
</div>
|
||||
<div class="group">
|
||||
<h3>Beim Merge (CI) <span class="pill block">blockiert</span></h3>
|
||||
<p>Jobs <code>quality</code> + <code>api</code> + <code>worker</code> + <code>database</code> + <code>docker-smoke</code> müssen grün sein (Typecheck, Lint, Tests, Build, Bundle-Size, a11y, ~18+ Baseline-Gates).</p>
|
||||
</div>
|
||||
<div class="group">
|
||||
<h3>Beim Deploy <span class="pill block">blockiert</span></h3>
|
||||
<p>Preflight-Gates (<code>deploy-readiness</code>, <code>docker-baseline</code>, <code>docker-non-root</code>). Produktions-Promote erfordert <code>backup_confirmed=true</code>.</p>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- 11 -->
|
||||
<section class="sw">
|
||||
<h2 class="section">11. CI/CD-Pipeline</h2>
|
||||
<p>Zwei parallele Welten mit gleichen Gates: GitHub Actions und <strong>Gitea</strong> (self-hosted Runner). Eigene Gates sichern die Parität. <code>ci.yml</code>-Jobs: <code>quality</code>, <code>api</code>, <code>worker</code>, <code>database</code>, <code>docker-smoke</code>.</p>
|
||||
<p>Die ~80 <code>verify:*</code>-Gates sind <strong>Baseline-/Anti-Regressions-Gates</strong>. Gruppen: Security/Auth · Mandantentrennung/Boundaries · Docker/Deploy · i18n/a11y · API/Specs · CI-Struktur · Docs.</p>
|
||||
<div class="callout"><span class="t">Lighthouse & SEO</span>Performance ≥ 95 % ist hart gegated; a11y/Best-Practices/PWA nur Warnung. <strong>SEO ist bewusst nicht gegated</strong> (B2B-SaaS).</div>
|
||||
</section>
|
||||
|
||||
<!-- 12 -->
|
||||
<section class="sw">
|
||||
<h2 class="section">12. Infrastruktur & Hosting</h2>
|
||||
<p>HiveGrid Cloud läuft im gemeinsamen Hetzner-Estate (EU/Deutschland), zentral über Coolify gesteuert. Detail-Inventar im separaten Dokument „Server-Struktur". Das Wesentliche:</p>
|
||||
<ul>
|
||||
<li><strong>Control-Plane:</strong> Coolify v4 auf der <code>control</code>-VM (Dashboard <code>saas-ctrl.com</code>) steuert alle Hosts per SSH.</li>
|
||||
<li><strong>Staging:</strong> Ein gemeinsamer Host <code>staging-1</code> trägt mehrere Produkt-Stagings nebeneinander – nicht eine VM pro Produkt.</li>
|
||||
<li><strong>Produktion:</strong> Laut ADR-009 erhält jedes SaaS-Produkt ein <strong>eigenes Hetzner-Projekt</strong> für Prod (eigene DB/App). Das HiveGrid-Cloud-Prod-Projekt wird bei Reife angelegt; die SaaS-App ist aktuell in Entwicklung und noch nicht deployt.</li>
|
||||
<li><strong>Zentrale Dienste (geteilt über WireGuard-Mesh, auf <code>node1</code>):</strong> Sentry (Errors), Loki (Logs), Meilisearch (Suche, per-Produkt-Scoped-Key), ClamAV (Virenscan), mCaptcha; Prometheus + Grafana auf <code>control</code>.</li>
|
||||
<li><strong>Services pro App-Stack:</strong> web (8080), api (8080), worker ×5 Queue-Gruppen (general/mail/import/webhook/plugin), Postgres 16, PgBouncer (Transaction-Pooling), Redis 7, Authentik (Admin-SSO).</li>
|
||||
<li><strong>Deploy:</strong> build-once-deploy-many über die Gitea-Registry; Coolify zieht das fertige Image und startet die Container neu (~30 s). Rollback = altes SHA-Image neu deployen.</li>
|
||||
</ul>
|
||||
<div class="callout ok"><span class="t">EU-Hosting</span>Compute, Daten und Object-Storage (S3) liegen in der EU – auf Hetzner (Deutschland), orchestriert über Coolify. Das stützt die EU-Datenschutz-Vorgaben aus Abschnitt 13.</div>
|
||||
</section>
|
||||
|
||||
<!-- 13 -->
|
||||
<section class="sw">
|
||||
<h2 class="section">13. Architektur-Konventionen</h2>
|
||||
<ul>
|
||||
<li><strong>Upstream-Disziplin:</strong> Geteilten Code so lassen, dass <code>git merge upstream/main</code> sauber bleibt. Neues HiveGrid-Verhalten in <code>@hivegrid/*</code>-Paketen oder klar abgegrenzten Modulen.</li>
|
||||
<li><strong>Package-Grenzen:</strong> Immer öffentliche Paketnamen importieren, nie fremdes <code>src/*</code>. Server-DB nur über <code>@hivegrid/db/client.server</code>, Env über <code>@hivegrid/config</code>, Queues über <code>@hivegrid/queue</code>.</li>
|
||||
<li><strong>EU-Stack erzwingen:</strong> Keine US-AI-Provider (nur EU-Provider: Scaleway, Mistral, Aleph Alpha); kein Social-OAuth (nur E-Mail/Passwort, Magic-Link, TOTP); Per-Tenant-Envelope-Encryption; Postgres-RLS als zusätzliche Mandanten-Grenze.</li>
|
||||
<li><strong>URLs:</strong> host-aware Helfer (<code>href()</code>, <code>appPath</code>/<code>adminPath</code>/<code>apiPath</code>), keine handgebauten Pfade.</li>
|
||||
<li><strong>Secrets:</strong> nie in UI-Code; nur über <code>@hivegrid/config</code> / Server-Boundaries. Tenant-Filter bei jedem Datenzugriff erhalten.</li>
|
||||
<li><strong>RR7:</strong> Typen aus <code>./+types/...</code>; <code><Outlet/></code> in Layouts; <code>typecheck</code> nach Routen-Änderungen.</li>
|
||||
<li><strong>Doku mitführen:</strong> bei Feature-/Provider-/Worker-Änderungen <code>docs/feature-manifests/*.json</code>; bei mutierenden Routen <code>docs/security/csrf-inventory.md</code>; bei Rollen/Permissions <code>docs/roles-matrix.md</code>. HiveGrid-Fortschritt in <code>docs/PROGRESS-TRACKER.md</code>, Entscheidungen in <code>docs/ARCHITECTURE-DECISIONS.md</code>.</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- 14 -->
|
||||
<section class="sw">
|
||||
<h2 class="section">14. Onboarding-Checkliste</h2>
|
||||
<div class="callout ok">
|
||||
<span class="t">Vor dem ersten Commit</span>
|
||||
<ol style="margin:4px 0 0 0;">
|
||||
<li><code>nvm use</code> (Node <code>v22.12.0</code>), dann <code>pnpm install</code> – installiert die Hooks automatisch.</li>
|
||||
<li><code>AGENTS.md</code> + <code>docs/ARCHITECTURE-DECISIONS.md</code> lesen (Package-Modell, EU-Stack, Milestone-Struktur).</li>
|
||||
<li><code>pnpm run dev</code> starten – generiert die RR7-Routen-Typen.</li>
|
||||
<li><code>pnpm run typecheck</code> & <code>pnpm run lint</code> sauber (0 Warnings); vor Push <code>pnpm test</code> grün.</li>
|
||||
<li>Für E2E: <code>seed:e2e-readiness</code>, <code>.env.e2e-readiness</code> sourcen, dann <code>verify:a11y-coverage</code> + Playwright.</li>
|
||||
</ol>
|
||||
</div>
|
||||
<p class="small">Goldene Regel: Wenn ein Gate rot ist, ist die Lösung der Code – nicht das Umgehen des Gates.</p>
|
||||
<hr>
|
||||
<p class="small">Stand 14. Juni 2026. Quellen: HiveGrid-Cloud <code>package.json</code>, <code>.eslintrc</code>, <code>.prettierrc</code>, <code>tsconfig.json</code>, <code>vitest.config.ts</code>, <code>playwright.config.ts</code>, <code>lefthook.yml</code>, <code>scripts/coverage-targets.json</code>, <code>AGENTS.md</code>, <code>docs/ARCHITECTURE-DECISIONS.md</code> sowie das <code>infra</code>-Repository. Konfiguration ist – bis auf Node-Version und HiveGrid-spezifische Pakete/Docs – identisch zum HiveGrid-Boilerplate.</p>
|
||||
</section>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -35,16 +35,20 @@ S02 wires the env catalog contract into CI with `pnpm run verify:env-drift`, imp
|
||||
|
||||
| Key or family | Active source locations | Target runtime(s) | Catalog classification | Follow-up owner | Notes |
|
||||
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `APP_NAME` | `apps/web/app/routes/**/*.tsx`, `apps/web/app/modules/**/*.ts`, `apps/api/src/app.ts`; core web loader usage adopted in `apps/web/app/utils/data/.server/rootData.ts` and `apps/web/app/utils/db/appConfiguration.db.server.ts` | web, api, worker/shared | `required-core` | S03 api, S05 docs, S06 enforcement | adopted root data/app-configuration reads through `loadWebConfig`; broad web route/module metadata reads remain direct and should be handled as later docs/enforcement cleanup rather than claimed complete here. |
|
||||
| `DATABASE_URL` | `packages/db/src/client.server.ts`, `prisma.config.ts` | shared, web, api, worker | `required-core` | web, S03 api, S04 worker | Prisma runtime and Prisma config both need catalog-backed loading. |
|
||||
| `APP_NAME` | `apps/web/app/routes/**/*.tsx`, `apps/web/app/modules/**/*.ts`, `apps/api/src/app.ts`; core web loader usage adopted in `apps/web/app/utils/data/.server/rootData.ts` and `apps/web/app/utils/db/appConfiguration.db.server.ts` | web, api, worker | `required-core` | S03 api, S05 docs, S06 enforcement | adopted root data/app-configuration reads through `loadWebConfig`; broad web route/module metadata reads remain direct and should be handled as later docs/enforcement cleanup rather than claimed complete here. |
|
||||
| `DATABASE_URL` | `packages/db/src/client.server.ts`, `prisma.config.ts`, `apps/mcp/src/config.ts` | shared, web, api, mcp, worker | `required-core` | web, S03 api, S04 worker | Prisma runtime and Prisma config both need catalog-backed loading; MCP validates the dependency before production boot. |
|
||||
| `SESSION_SECRET` | `apps/web/app/locale/i18next.server.ts`, `apps/web/app/utils/session.server.ts`, `apps/web/app/utils/analyticsCookie.server.ts` | web, api | `required-core` | web | Cookie/session signing secret; current fallback strings should be reviewed during loader migration. |
|
||||
| `APP_BASE_DOMAIN` | `packages/config/src/routing.ts`, `apps/api/src/app.test.ts` | shared, web, api, worker | `required-core` | web, S03 api | Runtime routing helper currently accepts env object and defaults to `process.env`. Test mutation is fixture-only. |
|
||||
| `WEB_RUNTIME_SURFACE` | `packages/config/src/web.ts`, `start.sh`, `server/server.ts` | web | `production-only` | web, S05 docs, S06 enforcement | Fail-closed selector for the core or customer-portal surface of the immutable web image. |
|
||||
| `PORTAL_SESSION_SECRET` | `packages/config/src/web.ts`, `start.sh`, `apps/web/app/services/customer-portal/portal-session-cookie.server.ts` | web | `production-only` | web, S05 docs, S06 enforcement | Dedicated customer-portal cookie secret; required only on the portal resource and forbidden on core web. |
|
||||
| `AUDIT_CHAIN_SECRET` | `packages/db/src/audit-hash.ts`, `apps/mcp/src/config.ts` | web, api, mcp, worker | `production-only` | S05 docs, S06 enforcement | Required in production, minimum 32 bytes; authenticates v2 audit hashes and retention checkpoints without exposing the value. |
|
||||
| `APP_BASE_DOMAIN` | `packages/config/src/routing.ts`, `apps/api/src/app.test.ts` | web, api, worker | `required-core` | web, S03 api | Runtime routing helper currently accepts env object and defaults to `process.env`. Test mutation is fixture-only. |
|
||||
| `WEB_APP_HOST` | `packages/config/src/routing.ts` via env object | web, api | `required-per-app` | web, S03 api | Canonical tenant app host. |
|
||||
| `APP_URL` | `apps/web/app/routes/app.$tenant/forms*.tsx`, `apps/worker/src/jobs/email-sequence-runtime.ts`, `apps/worker/src/jobs/workflow-trigger-http-executor.ts` | web, worker | `optional-provider` | S02 web, S04 worker | Public app origin used for embed fallback URLs, email sequence links, and the workflow-trigger execution bridge fallback. |
|
||||
| `ADMIN_APP_HOST` | `packages/config/src/routing.ts` via env object | web, api | `required-per-app` | web, S03 api | Canonical admin host. |
|
||||
| `API_HOST` | `packages/config/src/routing.ts` via env object | api, web | `required-per-app` | web, S03 api | Canonical API host. |
|
||||
| `PORTAL_APP_HOST` | `packages/config/src/routing.ts`, `packages/config/src/web.ts`, `server/server.ts`, `apps/worker/src/index.ts` | web, worker | `production-only` | web, S04 worker, S05 docs, S06 enforcement | Canonical isolated customer-portal host; production web surfaces require it, worker-mail builds status links from it, and core-host collisions are rejected. |
|
||||
| `APP_PROTOCOL` | `packages/config/src/routing.ts` via env object | shared, web, api, worker | `production-only` | web, S03 api | Defaults to `http` locally; production should provide `https`. |
|
||||
| `CRYPTO_SECRET` | `apps/web/app/utils/api/.server/CryptoApi.ts` | web, api | `required-per-app` | web, S03 api | Used for credential encryption/decryption. |
|
||||
| `CRYPTO_SECRET` | `apps/web/app/utils/api/.server/CryptoApi.ts`, `packages/db/src/crypto/tenant-envelope.server.ts`, `apps/worker/src/jobs/transactional-mail-outbox.ts` | web, api, worker | `required-per-app` | web, S03 api, S04 worker, S06 enforcement | Shared tenant-envelope master key; `worker-mail` must use the exact `hivegrid-web` value for portal setup delivery. |
|
||||
| `API_ACCESS_TOKEN` | `apps/web/app/utils/services/apiService.ts`, `apps/api/src/app.ts`, `apps/api/src/app.test.ts`, `apps/worker/src/jobs/workflow-trigger-http-executor.ts` | web, api, worker | `required-per-app` | web, S03 api, S04 worker | Service token for authenticated API calls and the worker-to-web workflow execution bridge; API tests mutate it as fixtures. |
|
||||
| `JWT_SECRET` | `apps/web/app/utils/services/apiService.ts`, `apps/api/src/app.ts`, `apps/api/src/app.test.ts` | web, api | `required-per-app` | web, S03 api | Legacy JWT signing/verification secret; API test mutations are fixtures. |
|
||||
| `NODE_ENV` | `apps/web/app/locale/i18next.server.ts`, `apps/web/app/utils/url.server.ts`, `apps/web/app/utils/loaders.middleware.ts`, `apps/web/app/utils/stream/emitter.server.ts`, `apps/web/app/utils/session.server.ts`, `apps/web/app/utils/analyticsCookie.server.ts`, `apps/web/app/utils/db/seed/SeedService.ts`, `apps/web/app/utils/data/.server/rootData.ts`, `apps/web/app/routes/admin/**/*.tsx`, `packages/db/src/client.server.ts`, `server/server.ts` | shared, web, api, worker | `production-only` | web, S03 api, S04 worker | Supplied by runtime/platform. `server/server.ts` sets a production default before creating the React Router handler. |
|
||||
@@ -66,7 +70,7 @@ S02 wires the env catalog contract into CI with `pnpm run verify:env-drift`, imp
|
||||
| `CONVERTKIT_FORM` | `apps/web/app/modules/crm/services/CrmService.ts`, examples/catalog | web | `optional-provider` | S05 docs | Optional CRM/newsletter form id; active web CRM usage. |
|
||||
| `CONVERTKIT_API_SECRET` | `apps/web/app/modules/crm/services/CrmService.ts`, examples/catalog | web | `optional-provider` | S05 docs | Optional CRM/newsletter subscriber lookup/update secret; active web CRM usage. |
|
||||
| `ANALYTICS_GA_TRACKING_ID` | `apps/web/app/utils/db/appConfiguration.db.server.ts` | web | `optional-provider` | web | Exposed through app configuration for Google Analytics. |
|
||||
| `ANALYTICS_TOKEN` | `apps/api/src/app.ts`, `apps/api/src/app.test.ts` | api | `required-per-app` | S03 api | Public analytics endpoint rejects missing/default token. Test mutations are fixtures. |
|
||||
| `ANALYTICS_TOKEN` | `apps/api/src/routes/analytics-routes.ts`, `apps/api/src/app.test.ts` | api | `required-per-app` | S03 api | Browser-facing ingest capability for anonymous events and page views only; public/admin aggregate reads use separate settings/operator boundaries. Test mutations are fixtures. |
|
||||
| `AUTH_RECAPTCHA_SITE_KEY` | `apps/web/app/utils/db/appConfiguration.db.server.ts` | web | `optional-provider` | web | Public reCAPTCHA site key exposed through app configuration. |
|
||||
| `NOTIFICATIONS_NOVU_API_KEY` | `apps/web/app/modules/notifications/services/.server/NotificationService.ts` | web | `optional-provider` | web | Optional admin diagnostics for the external notification provider; product sends use the internal queue. |
|
||||
| `AI_GENERATION_MAX_ESTIMATED_INPUT_COST_CENTS` | `apps/web/app/modules/ai-gen/services/ai-generation-guards.server.ts` | web | `optional-provider` | web | Optional guardrail for denying generation requests above the configured estimated input-cost budget. |
|
||||
@@ -91,8 +95,9 @@ S02 wires the env catalog contract into CI with `pnpm run verify:env-drift`, imp
|
||||
| `WORKFLOW_TRIGGER_OUTBOX_REQUIRED` | `apps/worker/src/jobs/workflow-trigger-bootstrap.ts`, `apps/worker/src/index.ts` | worker | `optional-provider` | S04 worker | Optional fail-loud guard for production general workers; set to `true` once the workflow trigger bridge and Redis must be present. |
|
||||
| `OUTBOX_DISPATCHER_REQUIRED` | `apps/worker/src/outbox/bootstrap.ts`, `apps/worker/src/outbox/dispatcher.ts`, `apps/worker/src/index.ts` | worker | `optional-provider` | S04 worker | Optional fail-loud guard for production general workers; set to `true` once the outbox dispatcher must be active so queued outbox rows cannot silently pile up. |
|
||||
| `IMPORT_QUEUE_ENABLED` | `apps/web/app/routes/app.$tenant/internal/imports/submit.tsx`, `apps/worker/src/queues.ts`, `apps/worker/src/health.ts` | web, worker | `optional-provider` | S03 api, S04 worker | Queued imports remain disabled unless import and scan services are wired for the worker. |
|
||||
| `PORTAL_GDPR_EXPORT_QUEUE_ENABLED` | `apps/worker/src/queues.ts`, `apps/worker/src/runtime.ts`, `apps/worker/src/index.ts`, `apps/worker/src/health.ts`, `packages/config/src/worker.ts` | worker | `optional-provider` | VA-P26b worker closeout | Internal exports-only mode for portal/privacy GDPR artifacts; valid only on `WORKER_QUEUE_GROUP=import` with both `IMPORT_QUEUE_*` gates off and complete storage/service wiring. |
|
||||
| `BULLMQ_REDIS_URL` | `packages/queue/src/connection.ts`, `apps/web/app/routes/app.$tenant/internal/imports/submit.tsx`, `apps/worker/src/health.ts` via env object | web, api, worker | `optional-provider` | web, S03 api, S04 worker, S05 docs | Primary BullMQ Redis URL for web/API enqueue and worker queues; optional unless the worker/queue path is enabled. |
|
||||
| `REDIS_URL` | `packages/queue/src/connection.ts`, `apps/web/app/routes/app.$tenant/internal/imports/submit.tsx`, `apps/worker/src/health.ts` via env object | web, api, worker | `optional-provider` | web, S03 api, S04 worker, S05 docs | BullMQ fallback only when `BULLMQ_REDIS_URL` is absent; do not document as an independent required key. |
|
||||
| `REDIS_URL` | `packages/queue/src/connection.ts`, `apps/web/app/routes/app.$tenant/internal/imports/submit.tsx`, `apps/worker/src/health.ts` via env object, `apps/mcp/src/config.ts`, `apps/mcp/src/shared-store.ts` | web, api, mcp, worker | `optional-provider` | web, S03 api, S04 worker, S05 docs | Required by MCP in production and a BullMQ fallback elsewhere; MCP readiness probes the same shared-store connection used by rate limits. |
|
||||
| `BROWSER_RUNTIME_URL` | `packages/config/src/worker.ts`, examples/catalog | api, worker | `optional-provider` | S04 worker, S05 docs | Optional browser-backed worker runtime endpoint. |
|
||||
| `BROWSER_RUNTIME_API_KEY` | `packages/config/src/worker.ts`, examples/catalog | api, worker | `optional-provider` | S04 worker, S05 docs | Optional browser runtime secret for server-side worker use. |
|
||||
| `BROWSER_SESSION_TIMEOUT_MS` | `packages/config/src/worker.ts`, examples/catalog | api, worker | `optional-provider` | S04 worker, S05 docs | Optional browser runtime timeout policy. |
|
||||
@@ -100,7 +105,6 @@ S02 wires the env catalog contract into CI with `pnpm run verify:env-drift`, imp
|
||||
| `HIVEGRID_API_MAINTENANCE_RETRY_AFTER_SECONDS` | `apps/api/src/platform/maintenance/maintenance.ts` | api | `production-only` | S03 api | Optional `Retry-After` seconds value for API maintenance responses. |
|
||||
| `IPSTACK_API_KEY` | `apps/web/app/utils/helpers/.server/IpService.ts` | api, worker | `optional-provider` | S03 api | IP enrichment provider key. |
|
||||
| `IPAPIIS_API_KEY` | examples/catalog only in targeted scan | api, worker | `optional-provider` | S05 docs | IP enrichment provider candidate. |
|
||||
| `PORTAL_SERVER_URL` | `apps/web/app/routes/app.$tenant/__portals/portals.tsx`, examples/catalog | web, api | `optional-provider` | web, S03 api | External portal server URL; current route throws when absent. |
|
||||
| `DEMO_USER` | `apps/web/app/routes/login.tsx`, `packages/config/src/web.ts` | web | `local-development-only` | web | Local login hint in `email:password` shape; ignored outside `NODE_ENV=development`. |
|
||||
| `SEED_ADMIN_EMAIL` | `apps/web/app/utils/db/seed/SeedService.ts`, examples/catalog | web | `production-only` | web | Production bootstrap admin email for guarded seed runs; local defaults are refused in production. |
|
||||
| `SEED_ADMIN_PASSWORD` | `apps/web/app/utils/db/seed/SeedService.ts`, examples/catalog | web | `production-only` | web | Production bootstrap admin password for guarded seed runs; local default password is refused in production. |
|
||||
@@ -143,7 +147,7 @@ The following keys appear in `.env.example`, `.env.local.example`, or `.env.prod
|
||||
## Assumptions and safety notes
|
||||
|
||||
- No secret values were copied from `.env*` files; this inventory includes key names and paths only.
|
||||
- `REDIS_URL` is a BullMQ fallback when `BULLMQ_REDIS_URL` is absent, not an independent required key.
|
||||
- `REDIS_URL` is the required MCP shared-store dependency in production and a BullMQ fallback only when `BULLMQ_REDIS_URL` is absent in queue-backed runtimes.
|
||||
- `SITE_KEY_*` is a dynamic API-owned key family and must be cataloged/enforced by prefix.
|
||||
- `PORT`, `HOST`, `WEB_ORIGIN`, and `ADMIN_ORIGIN` are cataloged. `PORT` and `HOST` are adopted for the web listener through `loadWebConfig`; `WEB_ORIGIN` and `ADMIN_ORIGIN` are API CORS overrides, and `WEB_ORIGIN` is also the worker workflow bridge fallback after `WORKFLOW_TRIGGER_EXECUTOR_URL` and `APP_URL`.
|
||||
- Commented source references are recorded as examples/docs follow-up, not active runtime dependencies.
|
||||
@@ -153,8 +157,8 @@ The following keys appear in `.env.example`, `.env.local.example`, or `.env.prod
|
||||
|
||||
| Slice | Owner scope | Inventory items |
|
||||
| --------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| S02 web | React Router/web loaders, sessions, root data, web route direct reads, Node server listen config | `APP_NAME`, `SESSION_SECRET`, routing host/protocol keys, `CRYPTO_SECRET`, `API_ACCESS_TOKEN`, `JWT_SECRET`, `NODE_ENV`, `HOST`, `PORT`, `WEBHOOKS_URL`, Supabase web keys, Legacy-Provider keys, OAuth keys, reCAPTCHA site key, Novu web state, `PORTAL_SERVER_URL`, `DEMO_USER`, `SEED_ADMIN_EMAIL`, `SEED_ADMIN_PASSWORD` |
|
||||
| S02 web | React Router/web loaders, sessions, root data, web route direct reads, Node server listen config | `APP_NAME`, `SESSION_SECRET`, `WEB_RUNTIME_SURFACE`, `PORTAL_SESSION_SECRET`, routing host/protocol keys including `PORTAL_APP_HOST`, `CRYPTO_SECRET`, `API_ACCESS_TOKEN`, `JWT_SECRET`, `NODE_ENV`, `HOST`, `PORT`, `WEBHOOKS_URL`, Supabase web keys, Legacy-Provider keys, OAuth keys, reCAPTCHA site key, Novu web state, `DEMO_USER`, `SEED_ADMIN_EMAIL`, `SEED_ADMIN_PASSWORD` |
|
||||
| S03 api | Hono API runtime, API auth/JWT/analytics/CORS, API storage, enqueue/provider settings | `APP_NAME`, routing host/protocol keys, `APP_REVISION`, `API_ACCESS_TOKEN`, `JWT_SECRET`, `ANALYTICS_TOKEN`, `WEB_ORIGIN`, `ADMIN_ORIGIN`, Supabase server keys, Legacy-Provider webhook secret, queue Redis keys, `MISTRAL_API_KEY`, `MISTRAL_MODEL`, `SCALEWAY_*`, `ALEPH_ALPHA_*`, `SITE_KEY_*`, API provider keys |
|
||||
| S04 worker | Standalone worker runtime, worker health, BullMQ Redis, browser runtime settings | `WORKER_ENABLED`, `APP_REVISION`, `APP_URL`, `WEB_ORIGIN`, `API_ACCESS_TOKEN`, `EMAIL_QUEUE_NAME`, `WORKFLOW_QUEUE_NAME`, `WORKFLOW_TRIGGER_EXECUTOR_MODE`, `WORKFLOW_TRIGGER_EXECUTOR_URL`, `WORKFLOW_TRIGGER_EXECUTOR_TIMEOUT_MS`, `WORKFLOW_TRIGGER_OUTBOX_ENABLED`, `WORKFLOW_TRIGGER_OUTBOX_CONCURRENCY`, `WORKFLOW_TRIGGER_OUTBOX_REQUIRED`, `OUTBOX_DISPATCHER_REQUIRED`, `BULLMQ_REDIS_URL`, `REDIS_URL`, `BROWSER_RUNTIME_URL`, `BROWSER_RUNTIME_API_KEY`, `BROWSER_SESSION_TIMEOUT_MS`, `MISTRAL_API_KEY`, `MISTRAL_MODEL`, `SCALEWAY_*`, `ALEPH_ALPHA_API_KEY`, worker-owned provider keys |
|
||||
| S05 docs | Example and documentation alignment, fallback wording, deprecated/example-only cleanup | Env examples and docs for `BULLMQ_REDIS_URL` as primary, `REDIS_URL` as fallback only when `BULLMQ_REDIS_URL` is absent, browser-runtime docs alignment, web-scoped ConvertKit CRM/newsletter keys, `DIRECT_URL`, `SERVER_URL`, `VERCEL_URL`, `AUTH_RECAPTCHA_SECRET_KEY`, dormant GitHub candidates |
|
||||
| S04 worker | Standalone worker runtime, worker health, BullMQ Redis, browser runtime settings | `WORKER_ENABLED`, `APP_REVISION`, `APP_URL`, `PORTAL_APP_HOST`, `WEB_ORIGIN`, `API_ACCESS_TOKEN`, `EMAIL_QUEUE_NAME`, `WORKFLOW_QUEUE_NAME`, `WORKFLOW_TRIGGER_EXECUTOR_MODE`, `WORKFLOW_TRIGGER_EXECUTOR_URL`, `WORKFLOW_TRIGGER_EXECUTOR_TIMEOUT_MS`, `WORKFLOW_TRIGGER_OUTBOX_ENABLED`, `WORKFLOW_TRIGGER_OUTBOX_CONCURRENCY`, `WORKFLOW_TRIGGER_OUTBOX_REQUIRED`, `OUTBOX_DISPATCHER_REQUIRED`, `BULLMQ_REDIS_URL`, `REDIS_URL`, `BROWSER_RUNTIME_URL`, `BROWSER_RUNTIME_API_KEY`, `BROWSER_SESSION_TIMEOUT_MS`, `MISTRAL_API_KEY`, `MISTRAL_MODEL`, `SCALEWAY_*`, `ALEPH_ALPHA_API_KEY`, worker-owned provider keys |
|
||||
| S05 docs | Example and documentation alignment, fallback wording, deprecated/example-only cleanup | Env examples and docs for `BULLMQ_REDIS_URL` as primary, `REDIS_URL` as the required MCP shared-store URL and queue fallback, browser-runtime docs alignment, web-scoped ConvertKit CRM/newsletter keys, `DIRECT_URL`, `SERVER_URL`, `VERCEL_URL`, `AUTH_RECAPTCHA_SECRET_KEY`, dormant GitHub candidates |
|
||||
| S06 enforcement | Future direct-read guardrails and drift tests | Prefix support for `SITE_KEY_*`, allow-list for test-only mutations, regression checks for S02-adopted web core keys (`PORT`, `HOST`, core URL/root/session/middleware reads), CORS-origin catalog drift checks for `WEB_ORIGIN` and `ADMIN_ORIGIN`, APP_REVISION catalog checks, no-value leakage checks for inventory docs |
|
||||
@@ -15,6 +15,7 @@ Use placeholder-only examples when explaining required shape:
|
||||
```sh
|
||||
DATABASE_URL=<DATABASE_URL>
|
||||
SESSION_SECRET=<SESSION_SECRET>
|
||||
AUDIT_CHAIN_SECRET=<AUDIT_CHAIN_SECRET>
|
||||
MAILJET_API_KEY=<MAILJET_API_KEY>
|
||||
```
|
||||
|
||||
@@ -34,17 +35,23 @@ These keys are required for normal production application runtime unless the dep
|
||||
| --- | --- | --- | --- |
|
||||
| `APP_NAME` | Shared web/API/worker runtime | Human-readable product name for titles, metadata, and seeded app configuration. | Key name and configured/unconfigured status. |
|
||||
| `DATABASE_URL` | Web/API runtime and Prisma operations | Primary application database connection. | Key name, missing/present status, migration status code. |
|
||||
| `SESSION_SECRET` | Web/API runtime | Session signing and verification boundary. | Key name and redacted validator code only. |
|
||||
| `SESSION_SECRET` | Core web/API runtime | Core session signing and verification boundary; forbidden on the customer-portal resource. | Key name and redacted validator code only. |
|
||||
| `WEB_RUNTIME_SURFACE` | Web runtime boundary | Selects exactly one surface, `core` or `portal`; production web resources fail closed without it. | Key name and enum-validation status only. |
|
||||
| `PORTAL_SESSION_SECRET` | Customer-portal web runtime | Dedicated portal-cookie signing boundary; required only on `hivegrid-portal` and forbidden on core web. | Key name and redacted validator code only. |
|
||||
| `AUDIT_CHAIN_SECRET` | Web/API/MCP/worker audit boundary | HMAC authentication for AuditEvent v2 hashes and retention checkpoints; minimum 32 bytes and stable across the retention lifetime. | Key name and redacted validator code only. |
|
||||
| `APP_BASE_DOMAIN` | Split-host routing boundary | Root domain used to derive canonical app, admin, and API hosts. | Key name and host-normalization status only. |
|
||||
| `WEB_APP_HOST` | Tenant web runtime | Canonical host for tenant app traffic, such as `app.<domain>`. | Key name and host-normalization status only. |
|
||||
| `ADMIN_APP_HOST` | Admin web runtime | Canonical host for admin traffic, such as `admin.<domain>`. | Key name and host-normalization status only. |
|
||||
| `API_HOST` | API runtime | Canonical host for versioned API traffic, such as `api.<domain>`. | Key name and host-normalization status only. |
|
||||
| `CRYPTO_SECRET` | Web/API runtime | Application encryption/signing boundary for protected data. | Key name and redacted validator code only. |
|
||||
| `PORTAL_APP_HOST` | Core/customer-portal web and mail-worker runtimes | Canonical host for the isolated customer portal and the origin for status-mail links; must differ from app, admin, API, and base-domain hosts. | Key name and host-normalization status only. |
|
||||
| `CRYPTO_SECRET` | Web/API and mail-worker runtime | Shared tenant-envelope master key. `worker-mail` must receive the exact `hivegrid-web` value so portal setup capabilities can be decrypted only at delivery time. | Key name and redacted validator code only; never print or compare the value in logs. |
|
||||
| `ADMIN_CONNECTION_MASTER_KEY` | Core web, API and admin-sales mail worker | Dedicated envelope-wrapping key for tenant-less AdminDataConnection credentials. Staging and production use distinct values; never reuse `CRYPTO_SECRET` or a session secret. | Key name and redacted validator code only; never print, compare or copy the value into logs or tickets. |
|
||||
| `API_ACCESS_TOKEN` | Web/API runtime | Service-token boundary for internal and API operator calls. | Key name and redacted validator code only. |
|
||||
| `JWT_SECRET` | API runtime | API session JWT signing and verification boundary. | Key name and redacted validator code only. |
|
||||
| `ANALYTICS_TOKEN` | API runtime | Analytics ingestion and public analytics API token boundary. | Key name and redacted validator code only. |
|
||||
| `ANALYTICS_TOKEN` | API runtime | Browser-facing anonymous analytics ingestion capability only; it never authorizes analytics reads or identity attribution. | Key name and redacted validator code only. |
|
||||
| `MCP_RESOURCE_URL` | MCP connector runtime | Public origin of the MCP resource server; used for RFC 9728 protected-resource metadata and OAuth audience binding. | Key name and host-normalization status only. |
|
||||
| `MCP_AUTHORIZATION_SERVER_URL` | Web/MCP runtime | Public origin of the OAuth authorization server (the web app) that issues MCP access tokens. | Key name and host-normalization status only. |
|
||||
| `WEB_PUSH_VAPID_PUBLIC_KEY` | Web and webhook-worker push boundary | Shared browser subscription key for incoming-call Web Push. Production web and webhook-worker deployments must receive the same generated key pair source. | Key name, configured/unconfigured status, and validation code only. |
|
||||
|
||||
`DIRECT_URL` is database-owned and may be required by Prisma or deployment-specific migration workflows. Treat it as secret material whenever present, and document only whether the key is configured for the workflow being run.
|
||||
|
||||
@@ -56,7 +63,8 @@ Optional integration keys are feature-gated. Missing optional keys should produc
|
||||
| --- | --- | --- | --- |
|
||||
| `WORKER_ENABLED` | Worker runtime | Queue processors should start for the deployment. | Boolean enablement status and diagnostic code. |
|
||||
| `BULLMQ_REDIS_URL` | Web/API enqueue and worker runtime | Queue-backed features are enabled and need BullMQ connectivity. | Key name, missing/present status, queue readiness code. |
|
||||
| `REDIS_URL` | Web/API enqueue and worker fallback | `BULLMQ_REDIS_URL` is absent and the deployment intentionally uses the generic Redis key. | Fallback key name and readiness code only. |
|
||||
| `REDIS_URL` | MCP shared store; web/API/worker fallback | Always required by MCP in production; elsewhere used only when `BULLMQ_REDIS_URL` is absent and the deployment intentionally uses the generic Redis key. | Key name and readiness code only. |
|
||||
| `AUTHENTIK_ADMIN_JIT_DATABASE_URL` | Authentik admin callback on the web runtime | Admin SSO is enabled and the verified callback may JIT-link or create an operator identity. The URL must authenticate as the execute-only `hivegrid_authentik_jit` role. | Key name, configured/unconfigured status, and exact-role diagnostic only; never log the URL. |
|
||||
| `MAILJET_API_KEY` | Mail provider boundary | Outbound Mailjet delivery is enabled. | Key name and redacted validator code only. |
|
||||
| `API_KEY_LEGACY_PLAINTEXT_FALLBACK` | API-key cutover boundary | Temporary plaintext API-key lookup fallback is disabled by default; enable only during a bounded hash-backfill migration window. | Boolean status only; never record API-key material. |
|
||||
| `MAILJET_FROM_EMAIL` | Mail provider boundary | Outbound Mailjet delivery is enabled. | Key name and sender-domain validation status only. |
|
||||
@@ -70,10 +78,10 @@ Optional integration keys are feature-gated. Missing optional keys should produc
|
||||
| `MOLLIE_API_KEY` | Payment provider boundary | Mollie payment checkout or webhook refetch is enabled. | Key name, mode label, and redacted validator code only. |
|
||||
| `MOLLIE_PROFILE_ID` | Payment provider boundary | Mollie payment creation requires an explicit website profile. | Key name and configured/unconfigured status. |
|
||||
| `MOLLIE_TIMEOUT_MS` | Payment provider boundary | Mollie payment gateway uses a non-default timeout. | Timeout parse status only. |
|
||||
| `PORTAL_SERVER_URL` | Portal/site-builder boundary | Portal server integration is enabled. | Key name, present/missing status, and redacted URL validation code only. |
|
||||
| `PORTAL_SERVER_FLY_TOKEN` | Portal automation boundary | Portal server automation is enabled. | Key name and redacted validator code only. |
|
||||
| `BILLING_MOLLIE_WEBHOOK_URL` | General-worker recurring billing boundary | Recurring Lago invoices may create Mollie payments. | Key name and validation status only; the value must be the environment-specific HTTPS API webhook route. |
|
||||
| `IMPORT_QUEUE_ENABLED` | Web enqueue and worker runtime | Import jobs should be sent through BullMQ. | Boolean enablement status and diagnostic code. |
|
||||
| `IMPORT_QUEUE_RUNTIME_READY` | Web enqueue and worker runtime | Import queue processors and scan/import services are wired end to end. | Boolean readiness status and diagnostic code. |
|
||||
| `PORTAL_GDPR_EXPORT_QUEUE_ENABLED` | Internal worker runtime | The import worker may consume only portal/privacy GDPR jobs from `hivegrid.exports`. | Boolean enablement status and diagnostic code only. |
|
||||
| `MISTRAL_API_KEY` | AI provider boundary | Mistral generation is enabled. | Key name and redacted provider-readiness code only. |
|
||||
| `MISTRAL_MODEL` | AI provider boundary | Mistral generation uses a non-default model. | Model label only when approved for release records. |
|
||||
| `AI_PROCESSING_REGION` | AI provider boundary | AI generation is enabled under a deployment-region policy. | Expected region label and confirmation status only. |
|
||||
@@ -91,6 +99,7 @@ Optional integration keys are feature-gated. Missing optional keys should produc
|
||||
| `STORAGE_BUCKET` | Storage provider boundary | S3-compatible upload/download operations need a default bucket. | Bucket alias or configured/unconfigured status only; avoid customer-specific bucket names in incidents. |
|
||||
| `STORAGE_ACCESS_KEY_ID` | Storage provider boundary | S3-compatible storage is enabled. | Key name and redacted validator code only. |
|
||||
| `STORAGE_SECRET_ACCESS_KEY` | Storage provider boundary | S3-compatible storage is enabled. | Key name and redacted validator code only. |
|
||||
| `GDPR_EXPORT_SSE_C_KEY_BASE64` | GDPR export storage boundary | Portal/privacy export objects are encrypted with SSE-C. Production core/portal web and the dedicated export worker must receive the same canonical Base64 value for 32 random bytes. | Key name and missing/invalid status only; never log, diff, or print the value. |
|
||||
| `STORAGE_SESSION_TOKEN` | Storage provider boundary | Temporary S3-compatible credentials are used. | Key name and redacted validator code only. |
|
||||
| `STORAGE_PUBLIC_BASE_URL` | Storage provider boundary | A CDN or public base URL is configured for storage object URLs. | Provider endpoint label or redacted URL validation code only. |
|
||||
| `STORAGE_FORCE_PATH_STYLE` | Storage provider boundary | The S3-compatible provider requires path-style bucket addressing. | Boolean status only. |
|
||||
@@ -99,9 +108,24 @@ Optional integration keys are feature-gated. Missing optional keys should produc
|
||||
|
||||
## Worker key group
|
||||
|
||||
`WORKER_ENABLED` controls whether queue processors start. Set it to `true` only in deployments that should run background jobs. When queue-backed web/API features enqueue jobs or workers process jobs, prefer `BULLMQ_REDIS_URL` for BullMQ Redis connectivity; `REDIS_URL` is a fallback only when `BULLMQ_REDIS_URL` is absent and the deployment intentionally uses the shared Redis key.
|
||||
`WORKER_ENABLED` controls whether queue processors start. Set it to `true` only in deployments that should run background jobs. MCP requires `REDIS_URL` in production for distributed abuse limits and readiness. When queue-backed web/API features enqueue jobs or workers process jobs, prefer `BULLMQ_REDIS_URL` for BullMQ Redis connectivity; those runtimes use `REDIS_URL` only as a fallback when `BULLMQ_REDIS_URL` is absent.
|
||||
|
||||
`IMPORT_QUEUE_ENABLED` and `IMPORT_QUEUE_RUNTIME_READY` must both be `true` before tenant import submissions enqueue jobs. Keep them disabled unless the worker runtime can process the import queue end to end.
|
||||
`IMPORT_QUEUE_ENABLED` and `IMPORT_QUEUE_RUNTIME_READY` must both be `true` before tenant import submissions enqueue jobs. Full mode owns `hivegrid.exports` too, so it also requires complete HTTPS `STORAGE_*`, a canonical `GDPR_EXPORT_SSE_C_KEY_BASE64`, and generic plus portal/privacy GDPR export services. Keep the gates disabled unless the worker runtime can process both queues end to end.
|
||||
|
||||
`PORTAL_GDPR_EXPORT_QUEUE_ENABLED=true` is a worker-only, internal alternative
|
||||
for `WORKER_QUEUE_GROUP=import`. Keep both `IMPORT_QUEUE_*` gates unset or
|
||||
`false`; the worker then owns only `hivegrid.exports` and requires complete
|
||||
`STORAGE_*`, `GDPR_EXPORT_SSE_C_KEY_BASE64` and portal/privacy GDPR export
|
||||
service wiring. The same key is mandatory on both production web surfaces so
|
||||
downloads remain server-proxied; it must never be placed in a URL or browser
|
||||
header. The modes are
|
||||
mutually exclusive and fail closed on mixed gates or another worker group.
|
||||
|
||||
`worker-general` requires `MEILI_URL` and the HiveGrid-scoped `MEILI_API_KEY`
|
||||
whenever tenant hard-delete runs under production, required RLS, or a
|
||||
staging/production Sentry marker. Missing values or a missing search client
|
||||
abort startup before queue ownership so a deletion request cannot complete
|
||||
while tenant documents remain indexed.
|
||||
|
||||
Staging and production `worker-general` services must also fail loud for
|
||||
outbox and workflow fanout. Set `OUTBOX_DISPATCHER_ENABLED=true`,
|
||||
@@ -137,11 +161,11 @@ Diagnostics may say that a required Mailjet key is missing, a sender domain is n
|
||||
|
||||
`AI_PROCESSING_REGION` must match the approved deployment-region policy when AI generation is enabled. The cataloged AI provider keys currently include Mistral, Scaleway, and Aleph Alpha entries; deployment records must define the allowed provider order and region labels before production traffic is routed. `SCALEWAY_REGION` and `SCALEWAY_BASE_URL` are provider-specific markers and must match the deployment record.
|
||||
|
||||
`LAGO_API_URL`, `LAGO_API_KEY`, and `LAGO_WEBHOOK_SECRET` are the AD-27 billing-engine keys. `MOLLIE_API_KEY` and `MOLLIE_PROFILE_ID` are the payment-processor keys. Keep Lago and Mollie production values separate from staging/testmode values, and never paste provider keys, webhook secrets, payment references, invoice payloads, tenant identifiers, or customer identifiers into docs or verification records.
|
||||
`LAGO_API_URL`, `LAGO_API_KEY`, and `LAGO_WEBHOOK_SECRET` are the AD-27 billing-engine keys. `MOLLIE_API_KEY`, `MOLLIE_PROFILE_ID`, and the environment-specific `BILLING_MOLLIE_WEBHOOK_URL` are the payment-processor boundary keys. Keep Lago and Mollie production values separate from staging/testmode values, and never paste provider keys, webhook secrets, payment references, invoice payloads, tenant identifiers, or customer identifiers into docs or verification records.
|
||||
|
||||
## Portal provider key group
|
||||
## Customer-portal runtime key group
|
||||
|
||||
`PORTAL_SERVER_URL` and `PORTAL_SERVER_FLY_TOKEN` belong to optional portal/site-builder automation. A missing portal key should make that feature unavailable with a redacted diagnostic rather than blocking unrelated core auth, tenant, admin, API, or worker boot.
|
||||
The core and portal containers use the same immutable web image but separate resources and secrets. Set `WEB_RUNTIME_SURFACE=core`, `SESSION_SECRET`, `DATABASE_RUNTIME_ROLE=hivegrid_app`, and `PORTAL_APP_HOST` on core web. Set `WEB_RUNTIME_SURFACE=portal`, `PORTAL_SESSION_SECRET`, `DATABASE_RUNTIME_ROLE=hivegrid_portal`, `PORTAL_APP_HOST`, `REDIS_URL`, and the selected CAPTCHA provider keys on `hivegrid-portal`. Both web resources receive the same `GDPR_EXPORT_SSE_C_KEY_BASE64` as the dedicated GDPR export worker; this export-decryption secret stays server-only. Core, portal, import worker, and general worker require complete `STORAGE_*` credentials but may use the same existing `STORAGE_ACCESS_KEY_ID`/`STORAGE_SECRET_ACCESS_KEY` pair; credential separation is optional and shared credentials are not a rollout blocker. The general worker must not receive the SSE-C key. For the tenant-export barrier only, import and general resolve SharedStore from non-empty `REDIS_URL` before `BULLMQ_REDIS_URL` and must target the same normalized Redis endpoint and database. The staging Compose reference maps storage credentials from `WEB_STORAGE_*`, `WORKER_IMPORT_STORAGE_*`, and `WORKER_GENERAL_STORAGE_*`; those sources may resolve to the same pair, while portal remains a separate Coolify resource. Never copy core session, OAuth, billing, ingress, migration, seed, or retired `PORTAL_SERVER_*` credentials into the portal resource. The exact operator matrix and rollout order live in [`docs/deploy/customer-portal.md`](./deploy/customer-portal.md).
|
||||
|
||||
## Database key group
|
||||
|
||||
|
||||
-186
@@ -1,186 +0,0 @@
|
||||
# CRM Decision Report
|
||||
|
||||
## Decision
|
||||
|
||||
Decision: `extract-plugin`.
|
||||
|
||||
CRM is an optional CRM vertical/plugin candidate, not boilerplate Core and not an immediate-removal target. The retained core should provide auth, tenancy, admin/app shell, rows/entities runtime, transactional email, and stable extension points; CRM should own its product opinion around companies, contacts, opportunities, submissions, marketing subscriber state, CRM-specific routes, icons, commands, translations, and any Email Marketing coupling that depends on contacts as campaign recipients.
|
||||
|
||||
This slice does not change runtime code. It records the canonical decision and execution order for a later extraction/removal slice.
|
||||
|
||||
## Scope
|
||||
|
||||
In scope for this decision:
|
||||
|
||||
- Classify CRM as an optional plugin/vertical with action `extract-plugin`.
|
||||
- Identify current CRM surfaces and couplings that a future extraction/removal task must audit.
|
||||
- Preserve retained CRM code, data, and docs surfaces until a dedicated implementation slice moves or removes CRM. Default core route registration disables CRM route trees.
|
||||
- Define a sequential, atomic execution plan and verification plan for later work.
|
||||
|
||||
Out of scope for this decision:
|
||||
|
||||
- Deleting CRM routes, modules, entity templates, translations, or command entries in this slice.
|
||||
- Refactoring Email Marketing, Rows/Entities, user sync, or sidebar code in this slice.
|
||||
- Deciding final packaging mechanics for a future plugin runtime beyond the extraction order and required checks.
|
||||
|
||||
Human-review notes that should not block execution:
|
||||
|
||||
- Confirm whether Email Marketing remains a plugin that depends on CRM contacts, or whether it should introduce a separate audience/list abstraction before CRM extraction.
|
||||
- Confirm whether existing installations with CRM entities should receive a migration path, export instructions, or compatibility shim before CRM is disabled by default.
|
||||
- Confirm whether `submission` remains part of CRM or is split into a generic contact-form/audience plugin.
|
||||
|
||||
## Current Code Surfaces
|
||||
|
||||
The current known CRM surfaces are retained plugin-candidate code surfaces. Route paths listed here are not active default core route registrations:
|
||||
|
||||
| Surface | Current role | Future handling |
|
||||
| --- | --- | --- |
|
||||
| `apps/web/app/modules/crm` | CRM module root; currently includes `apps/web/app/modules/crm/services/CrmService.ts`. | Move to plugin package/module or delete only after dependents are removed. |
|
||||
| `apps/web/app/modules/crm/services/CrmService.ts` | Validates CRM entity presence and reads/writes company/contact/opportunity/submission rows; handles contact form, newsletter fallback, ConvertKit fallback, user sync helpers, and CRM summaries. | Plugin-owned service; extraction must replace core callers with an interface, feature flag, or no-op path. |
|
||||
| `apps/web/app/routes/admin/crm.tsx` | Admin CRM layout route; validates CRM entities and builds CRM icon navigation including Overview, entity routes, and Sync. | Plugin admin route shell. |
|
||||
| `apps/web/app/routes/admin/crm/*` | Admin CRM nested routes for overview/entity/sync flows. The current filesystem contains `apps/web/app/routes/admin/crm` as the route directory. | Move/delete atomically with admin CRM layout and route registration. |
|
||||
| `apps/web/app/routes/app.$tenant/crm.tsx` | Tenant CRM layout route; validates tenant CRM entities and builds tenant CRM icon navigation. | Plugin tenant route shell. |
|
||||
| `apps/web/app/routes/app.$tenant/crm/*` | Tenant CRM nested routes for overview/entity flows. The current filesystem contains `apps/web/app/routes/app.$tenant/crm` as the route directory. | Move/delete atomically with tenant CRM layout and route registration. |
|
||||
| `apps/web/app/modules/templates/defaultEntityTemplates.ts` | Defines `CRM_ENTITIES_TEMPLATE` for `company`, `opportunity`, `contact`, and `submission` plus relationships. | Decide whether the template is plugin-owned, installable as optional seed data, or removed from default template loading. |
|
||||
| `apps/web/app/utils/api/.server/EntitiesApi.ts` | Provides CRM-specific entity route generation for admin CRM and tenant CRM paths. | Remove CRM branches from core or make route generation plugin-aware. |
|
||||
| `apps/web/app/services/command-registry/commandRegistry.ts` | Owns command palette actions. CRM command entries are currently absent from the generic registry. | Keep CRM commands out of core or register them through plugin command contribution. |
|
||||
| `apps/web/app/modules/emailMarketing/services/EmailMarketingService.ts` | Imports `CrmService` and `ContactDto`; campaign previews/sends require contact rows, `marketingSubscriber`, and contact variable replacement. | Must be audited before CRM extraction; Email Marketing either depends on CRM plugin or receives its own audience abstraction. |
|
||||
| `apps/web/app/utils/db/users.db.server.ts` | Imports `CrmService` and `ContactStatus`; user creation/update paths can create CRM contacts and log CRM sync. | Move CRM sync to plugin event subscriber or guard behind optional plugin availability. |
|
||||
| `apps/web/public/locales/en/translations.json` | Contains `crm.title` and `crm.settings.*` strings. | Move/remove CRM translations with plugin UI. |
|
||||
| `apps/web/public/locales/de/translations.json` | Contains `crm.title` and `crm.settings.*` strings. | Move/remove CRM translations with plugin UI. |
|
||||
| `docs/feature-manifests/plugin-candidates.json` | Lists CRM as plugin candidate with code areas `apps/web/app/modules/crm`, `apps/web/app/routes/admin/crm*`, and `apps/web/app/routes/app.$tenant/crm*`; pruning action is `extract-plugin`. | Keep consistent with this decision report and later split into a CRM-specific plugin manifest if extraction begins. |
|
||||
|
||||
Additional evidence from current inventory:
|
||||
|
||||
- `docs/feature-inventory.md` classifies CRM as Optional/Plugin because it is a strong product opinion coupled to default entities and Email Marketing.
|
||||
- The filesystem still retains `apps/web/app/routes/admin/crm`, `apps/web/app/routes/admin/crm.tsx`, `apps/web/app/routes/app.$tenant/crm`, and `apps/web/app/routes/app.$tenant/crm.tsx`, while default core route discovery excludes those plugin trees.
|
||||
- `apps/web/app/modules/crm/services/CrmService.ts` depends on Rows/Entities APIs, row relationships, row values, notifications, cache helpers, and default entity names.
|
||||
|
||||
## Couplings
|
||||
|
||||
### Rows and default entities
|
||||
|
||||
CRM is coupled to the generic rows/entities runtime through entity names and slugs rather than isolated CRM tables. `CrmService.validate()` requires `company`, `opportunity`, and `contact`, plus `submission` for admin/global CRM. The service uses rows APIs and row relationship APIs for contact, company, opportunity, and submission behavior. A future extraction must preserve rows/entities as core infrastructure while ensuring CRM entity templates are optional plugin seed data.
|
||||
|
||||
### Email Marketing
|
||||
|
||||
`apps/web/app/modules/emailMarketing/services/EmailMarketingService.ts` directly imports `CrmService` and `ContactDto`. It uses CRM contacts as campaign recipients, blocks sends to contacts without `marketingSubscriber`, replaces email variables from contact fields, and loads contacts from contact entity views. This is the most important downstream dependency: CRM cannot be removed from core unless Email Marketing is either extracted together with CRM, made dependent on the CRM plugin, or refactored to a separate audience/contact-list abstraction.
|
||||
|
||||
### User lifecycle sync
|
||||
|
||||
`apps/web/app/utils/db/users.db.server.ts` imports `CrmService` and `ContactStatus` and can create CRM contact rows for users. The future extraction must move this behavior into plugin-owned lifecycle hooks or guard it so core user persistence no longer imports CRM.
|
||||
|
||||
### Route and entity routing helpers
|
||||
|
||||
`apps/web/app/utils/api/.server/EntitiesApi.ts` contains route-generation branches for admin CRM and tenant CRM paths. These branches make CRM route paths part of shared entity routing. A future extraction must either remove those branches or replace them with plugin-provided route builders.
|
||||
|
||||
### Navigation and commands
|
||||
|
||||
`apps/web/app/services/command-registry/commandRegistry.ts` is the current command-registration surface. CRM command entries are not registered in the generic registry; the admin/app CRM layout routes still build CRM-specific local navigation with CRM icons. A future extraction must keep command registration plugin-owned and remove route/sidebar visibility unless the CRM plugin is installed.
|
||||
|
||||
### Translations and icons
|
||||
|
||||
CRM strings live in shared locale files under `crm.*`. CRM route layouts import CRM-specific icon components from `~/components/ui/icons/crm/*`. A future extraction must move translations and icon usage with the plugin or delete them when CRM is removed.
|
||||
|
||||
### Manifest and documentation
|
||||
|
||||
`docs/feature-manifests/plugin-candidates.json` already classifies CRM as a plugin candidate. This report becomes the human-readable canonical decision; T02 should verify that report references remain resolvable and consistent with the manifest.
|
||||
|
||||
## Schema and Template Impact
|
||||
|
||||
CRM does not appear as a dedicated Prisma model surface in the reviewed task inputs. Its data model is represented through the rows/entities runtime and `CRM_ENTITIES_TEMPLATE` in `apps/web/app/modules/templates/defaultEntityTemplates.ts`:
|
||||
|
||||
- `company` with slug `companies`, type `AdminOnly`, properties such as `name`, `address`, `phone`, `source`, and `logo`.
|
||||
- `opportunity` with slug `opportunities`, type `AdminOnly`, properties such as `name`, `value`, and `expectedCloseDate`.
|
||||
- `contact` with slug `contacts`, type `AdminOnly`, properties such as `firstName`, `lastName`, `email`, `jobTitle`, `status`, and `marketingSubscriber`.
|
||||
- `submission` with slug `submissions`, type `AdminOnly`, properties such as `users` and `message`.
|
||||
- Relationships: `company` to `contact`, `company` to `opportunity`, and `contact` to `submission`.
|
||||
|
||||
Future extraction decision for templates must be explicit and atomic:
|
||||
|
||||
1. If CRM becomes an installable plugin, move `CRM_ENTITIES_TEMPLATE` into plugin seed/install code and keep core template loading independent from CRM.
|
||||
2. If CRM is removed for minimal boilerplate builds, remove default availability of company/contact/opportunity/submission templates and document migration/export for existing installations.
|
||||
3. If Email Marketing still needs contacts, do not remove `contact`/`marketingSubscriber` until Email Marketing owns or imports an audience template.
|
||||
|
||||
## Sidebar Command Docs Impact
|
||||
|
||||
Sidebar and route navigation impact:
|
||||
|
||||
- Admin CRM route code is retained at `apps/web/app/routes/admin/crm.tsx` and nested `apps/web/app/routes/admin/crm/*` routes, but is disabled in default core route registration.
|
||||
- Tenant CRM route code is retained at `apps/web/app/routes/app.$tenant/crm.tsx` and nested `apps/web/app/routes/app.$tenant/crm/*` routes, but is disabled in default core route registration.
|
||||
- CRM layout routes build their own icon subnavigation for Overview, opportunities, companies, contacts, submissions, and, in admin, Sync.
|
||||
- Any global AdminSidebar/AppSidebar references discovered in a future implementation slice must be removed or made plugin-aware. Current sidebar tests already assert some optional admin routes, including canonical admin-host CRM paths, are not present in the admin sidebar serialization.
|
||||
|
||||
Command impact:
|
||||
|
||||
- `apps/web/app/services/command-registry/commandRegistry.ts` is the command registry surface and should remain free of CRM commands unless a CRM plugin contributes them.
|
||||
- Future extraction must remove this core command or move it to plugin command registration.
|
||||
|
||||
Docs and i18n impact:
|
||||
|
||||
- `apps/web/public/locales/en/translations.json` and `apps/web/public/locales/de/translations.json` contain CRM translations and should move with plugin UI.
|
||||
- `docs/feature-manifests/plugin-candidates.json` must remain aligned with this report; if CRM receives a dedicated plugin manifest later, `plugin-candidates.json` should point to it or retain a consistent summary entry.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
The future CRM extraction/removal work must run in this sequence, with each step atomic and independently verifiable:
|
||||
|
||||
1. Decision/report: land this `extract-plugin` decision report and the T02 verifier before runtime changes.
|
||||
2. Email Marketing dependency check: inspect `apps/web/app/modules/emailMarketing/services/EmailMarketingService.ts`, Email Marketing routes, campaign recipient storage, and tests to choose one of three paths: extract Email Marketing together with CRM, declare Email Marketing dependent on CRM plugin, or introduce a non-CRM audience abstraction.
|
||||
3. Route/module extraction or deletion: move or remove `apps/web/app/modules/crm`, `apps/web/app/routes/admin/crm.tsx`, `apps/web/app/routes/admin/crm/*`, `apps/web/app/routes/app.$tenant/crm.tsx`, and `apps/web/app/routes/app.$tenant/crm/*` in one implementation slice after dependencies are guarded.
|
||||
4. Default entity template decision: move `CRM_ENTITIES_TEMPLATE` from `apps/web/app/modules/templates/defaultEntityTemplates.ts` into plugin install/seed code, or remove it from default loading only after Email Marketing/user sync no longer requires it.
|
||||
5. Command/sidebar/i18n update: remove or plugin-register CRM command palette entries, CRM route/sidebar links, CRM route helpers in `apps/web/app/utils/api/.server/EntitiesApi.ts`, CRM locale keys in `apps/web/public/locales/en/translations.json` and `apps/web/public/locales/de/translations.json`, and CRM docs/manifest entries.
|
||||
6. Tests/static scans: add or update static scans and focused tests so core no longer imports `~/modules/crm`, CRM routes are absent when the plugin is disabled, Email Marketing behavior is explicit, and docs/manifests stay consistent.
|
||||
|
||||
## Verification Plan
|
||||
|
||||
T02 must add a local static verifier, expected at `scripts/verify-crm-decision-report.mjs`, that fails when this decision contract drifts. The verifier must check:
|
||||
|
||||
- Required report sections exist: Decision, Scope, Current Code Surfaces, Couplings, Schema and Template Impact, Sidebar Command Docs Impact, Execution Plan, Verification Plan, Risks.
|
||||
- The report contains the exact decision token `extract-plugin`.
|
||||
- No TODO, TBD, or unresolved placeholder text exists in the report.
|
||||
- Required referenced paths are present in the report and resolvable where they are concrete current paths: `apps/web/app/modules/crm`, `apps/web/app/routes/admin/crm.tsx`, `apps/web/app/routes/admin/crm/*`, `apps/web/app/routes/app.$tenant/crm.tsx`, `apps/web/app/routes/app.$tenant/crm/*`, `apps/web/app/modules/templates/defaultEntityTemplates.ts`, `apps/web/app/utils/api/.server/EntitiesApi.ts`, `apps/web/app/services/command-registry/commandRegistry.ts`, `apps/web/app/modules/emailMarketing/services/EmailMarketingService.ts`, `apps/web/app/utils/db/users.db.server.ts`, `apps/web/public/locales/en/translations.json`, `apps/web/public/locales/de/translations.json`, `docs/feature-manifests/plugin-candidates.json`.
|
||||
- Glob-style references such as `apps/web/app/routes/admin/crm/*` and `apps/web/app/routes/app.$tenant/crm/*` resolve to existing route directories or files.
|
||||
- `docs/feature-manifests/plugin-candidates.json` still contains a CRM component and `pruning.action` remains `extract-plugin` unless a later migration intentionally updates both manifest and report.
|
||||
|
||||
Manual verification for a future runtime extraction should cover:
|
||||
|
||||
- Core app and admin shells start without CRM installed.
|
||||
- Email Marketing either works with its declared CRM dependency or fails with a clear disabled-plugin message.
|
||||
- User creation/update no longer imports or calls CRM from core when CRM is disabled.
|
||||
- Existing CRM installations have a documented export/migration path if runtime deletion is chosen instead of plugin packaging.
|
||||
|
||||
## Risks
|
||||
|
||||
- Incomplete surface map can cause later removal to miss imports; this report therefore names all known coupling files from the slice research and the task inputs.
|
||||
- Email Marketing has direct CRM service and contact DTO coupling, so removing CRM first would break campaign preview/send flows.
|
||||
- User lifecycle CRM sync creates hidden coupling outside CRM routes and must be moved or guarded before extraction.
|
||||
- CRM entities are generic rows/entities templates, so deleting only route/module code can leave orphaned templates or data.
|
||||
- Translation, command, and route-helper leftovers can keep CRM visible or navigable after the module is removed.
|
||||
- Existing tenants may rely on CRM rows and relationships; plugin extraction should include compatibility and migration notes rather than silent data loss.
|
||||
|
||||
## Update (R-P6 typed CRM)
|
||||
|
||||
This boilerplate report classified CRM as an optional `extract-plugin` vertical and asked to preserve the entity-builder CRM surfaces until a dedicated implementation slice. HiveGrid ticket R-P6 (2026-06-29) is that slice and takes a different product direction (AD-2 "Entity-Builder raus", AD-20 project-centric pivot — pivot precedence per AGENTS.md): CRM is a typed first-class core, not a plugin candidate.
|
||||
|
||||
What R-P6 changed relative to this report:
|
||||
|
||||
- The entity-builder CRM route trees were deleted: `apps/web/app/routes/admin/crm.tsx`, `apps/web/app/routes/admin/crm/*`, `apps/web/app/routes/app.$tenant/crm.tsx`, `apps/web/app/routes/app.$tenant/crm/*`. The typed CRM now lives under `apps/web/app/routes/app.$tenant/contacts.*` with services in `apps/web/app/utils/integrations/crm/*` and view-models in `packages/view-models/src/crm/*`, backed by `prisma/schema/crm.prisma`.
|
||||
- `apps/web/app/modules/crm` is retained as a LEGACY surface: only the entity-builder contact-row readers (`getContact`, `getContactsInRowIds`, `ContactDto`) still consumed by Email Marketing (AK-P14) remain. Full removal is deferred to the Email Marketing typed-Kontakt migration (follow-up ticket) — exactly the coupling this report flagged as a human-review note.
|
||||
- The decision token remains `extract-plugin` for the residual legacy surface; the strategic target for the typed CRM core is "retain as core", not extraction. The route-existence checks in `scripts/verify-crm-decision-report.mjs` were updated accordingly.
|
||||
|
||||
## Update (R-P14C)
|
||||
|
||||
HiveGrid ticket R-P14C (2026-06-30) executes the Email Marketing typed-Kontakt
|
||||
migration the R-P6 section above flagged as a follow-up. Under **Variante A** the
|
||||
legacy Entity-Builder campaign editor is removed rather than migrated:
|
||||
|
||||
- `apps/web/app/modules/emailMarketing/services/EmailMarketingService.ts` (the
|
||||
`CrmService.getContact`/`getContactsInRowIds`/`ContactDto` consumer this report
|
||||
tracked) was deleted; its only typed survivor (the overview summary) now reads
|
||||
the typed `OutboundEmail` counters directly. The file-existence assertion for
|
||||
it was dropped from `scripts/verify-crm-decision-report.mjs`; the historical
|
||||
coupling reference is retained above.
|
||||
- The residual `apps/web/app/modules/crm` legacy reader is removed in the same
|
||||
ticket once the last consumer is gone (see the Email Marketing decision report
|
||||
update for the full removal record).
|
||||
-206
@@ -1,206 +0,0 @@
|
||||
# Email Marketing Decision Report
|
||||
|
||||
## Decision
|
||||
|
||||
Decision: `extract-plugin`.
|
||||
|
||||
Email Marketing and Newsletter are optional plugin surfaces. They are not boilerplate Core because campaign management, subscriber/audience selection, sender configuration, tracking, and marketing consent rules are product-specific. They are also not immediate-removal targets because the current implementation has real campaign, sender, outbound-email, route, schema, translation, and CRM-contact dependencies that must be unwound atomically.
|
||||
|
||||
The canonical strategy is to keep Email Marketing as a plugin candidate that currently depends on CRM contacts. A future extraction must either bundle Email Marketing with the CRM plugin, declare an explicit dependency on the CRM plugin, or introduce a plugin-owned audience/list abstraction before CRM contacts or CRM entities are removed from Core.
|
||||
|
||||
This decision is deliberately narrower than the Email Sequences and marketing-outbound foundations. Email Marketing means the CRM-contact campaign surface under `apps/web/app/modules/emailMarketing` and the `email-marketing` admin/tenant routes. Email Sequences are documented in `docs/features/email-sequences.md` as foundation/admin-preview work with production follow-ups. The generic marketing-outbound handler is documented in `docs/features/marketing-funnel.md` as an unbootstrapped general handler foundation.
|
||||
|
||||
This report is documentation-only. It records the decision and safe execution order for later extraction/removal work; it does not change runtime behavior.
|
||||
|
||||
## Scope
|
||||
|
||||
In scope for this decision:
|
||||
|
||||
- Classify Email Marketing and Newsletter as optional plugin surfaces with action `extract-plugin`.
|
||||
- Keep Email Marketing scoped to CRM-contact campaign management, not the Email Sequences foundation/admin-preview surfaces.
|
||||
- Preserve transactional mail as Core and keep marketing mail outside that Core boundary.
|
||||
- Document current Email Marketing routes, modules, database/schema surfaces, command/i18n references, and manifest/docs dependencies.
|
||||
- Record the current CRM contact/audience dependency and the required extraction choices before CRM removal.
|
||||
- Define an atomic execution plan and a static verification plan for later tasks.
|
||||
|
||||
Out of scope for this decision:
|
||||
|
||||
- Removing `apps/web/app/modules/emailMarketing`, routes, Prisma models, translations, command entries, or manifests in this slice.
|
||||
- Migrating CRM, replacing contacts with a new audience model, or changing campaign send behavior in this slice.
|
||||
- Moving provider secrets or adding runtime plugin packaging mechanics in this slice.
|
||||
- Changing transactional email behavior in `apps/web/app/modules/emails`, `apps/web/app/application/emails`, `apps/web/app/utils/services/emailService.ts`, or `packages/mail`.
|
||||
- Reclassifying Email Sequences as an Email Marketing plugin candidate or claiming production delivery before seed data, stats aggregation, E2E, Mailjet delivery evidence/reconciliation, and scheduler/deploy evidence follow-ups land.
|
||||
- Bootstrapping the generic `marketing-outbound` subscriber or treating `MARKETING_WEBHOOKS_ENABLED` as evidence that Slack, Discord, Mailchimp, HubSpot, Brevo, or custom webhook delivery is active.
|
||||
|
||||
## Current Code Surfaces
|
||||
|
||||
The current known Email Marketing surfaces are:
|
||||
|
||||
| Surface | Current role | Future handling |
|
||||
| --- | --- | --- |
|
||||
| `apps/web/app/modules/emailMarketing` | Email Marketing module root for campaign, sender, outbound-email, and send services. | Move into an Email Marketing plugin or remove after routes, schema, translations, and CRM dependency are handled. |
|
||||
| `apps/web/app/modules/emailMarketing/services/EmailMarketingService.ts` | Main campaign service. Imports `CrmService` and `ContactDto`, loads contact views, validates marketing subscribers, performs contact variable replacement, sends tests and campaigns, and writes outbound status. | Plugin-owned service. Must not remain in Core while importing CRM unless Email Marketing and CRM are bundled or dependency-gated. |
|
||||
| `apps/web/app/modules/emailMarketing/db/emailSender.ts` | Email sender persistence surface. Stores provider, stream, API key, from/reply-to fields, and optional tenant ownership through `EmailSender`. | Plugin-owned settings/storage surface; extraction must preserve secret ownership rules and migration. |
|
||||
| `apps/web/app/modules/emailMarketing/db/campaigns.db.server.ts` | Campaign persistence and campaign-recipient composition. | Plugin-owned persistence surface tied to `Campaign` and `OutboundEmail` schema. |
|
||||
| `apps/web/app/modules/emailMarketing/db/outboundEmails.db.server.ts` | Outbound email tracking persistence for previews, sends, delivery, opens, clicks, bounces, spam complaints, and unsubscribes. | Plugin-owned persistence and analytics surface. |
|
||||
| `apps/web/app/routes/admin/email-marketing.tsx` | Admin Email Marketing layout route. Validates CRM entities through `CrmService.validate(null)` and exposes Overview, Campaigns, Activity, and Senders navigation. | Plugin admin route shell; CRM validation must be replaced by declared plugin dependency or audience validation. |
|
||||
| `apps/web/app/routes/admin/email-marketing/*` | Admin nested Email Marketing routes for overview/campaign/activity/sender workflows. | Move/delete atomically with admin layout and module services. |
|
||||
| `apps/web/app/routes/app.$tenant/email-marketing.tsx` | Tenant Email Marketing layout route. Requires `tenantEmailMarketing` feature flag, validates CRM through `CrmService.validate(tenantId)`, and exposes tenant navigation. | Plugin tenant route shell; must be disabled clearly when plugin or CRM/audience dependency is unavailable. |
|
||||
| `apps/web/app/routes/app.$tenant/email-marketing/*` | Tenant nested Email Marketing routes for tenant campaign/activity/sender workflows. | Move/delete atomically with tenant layout and feature-gate behavior. |
|
||||
| `prisma/schema/email.prisma` | Defines inbound email models plus Email Marketing models `EmailSender`, `Campaign`, `OutboundEmail`, `OutboundEmailOpen`, and `OutboundEmailClick`. `OutboundEmail.contactRowId` references CRM contact rows through generic `Row`. | Split or migrate plugin-owned schema. Preserve Core transactional mail boundary and avoid deleting inbound/system mail accidentally. |
|
||||
| `apps/web/app/services/command-registry/commandRegistry.ts` | Shared command registry named by the slice contract as a possible Email Marketing/CRM command visibility surface. | Future verifier/extraction must confirm whether Email Marketing commands exist and move/remove them through plugin command registration if present. |
|
||||
| `apps/web/public/locales/en/translations.json` | Contains Email Marketing strings such as `emailMarketing.title` and sender labels used by routes. | Move plugin strings with plugin UI or remove only when UI is removed. |
|
||||
| `apps/web/public/locales/de/translations.json` | German Email Marketing translation counterpart. | Move plugin strings with plugin UI or remove only when UI is removed. |
|
||||
| `docs/feature-manifests/plugin-candidates.json` | Lists `email-marketing` as a plugin candidate with module/routes/emails code areas and broader plugin extraction rules. | Keep consistent with this report and later split into a dedicated plugin manifest if extraction begins. |
|
||||
| `docs/feature-manifests/transactional-mail.json` | Defines transactional mail as Core and explicitly says newsletter/marketing abstractions may move to plugins. | Must remain the boundary source for Core mail. This report must not reclassify marketing mail as transactional Core. |
|
||||
| `docs/feature-decisions/crm-decision-report.md` | Canonical CRM decision. It identifies Email Marketing as the most important downstream CRM dependency. | Email Marketing extraction/removal order must follow this CRM dependency contract. |
|
||||
|
||||
Additional inventory evidence:
|
||||
|
||||
- `docs/feature-inventory.md` classifies Email Marketing/Newsletter as Optional/Plugin and Core mail as Transactional Email only.
|
||||
- `docs/feature-manifests/plugin-candidates.json` includes `apps/web/app/modules/emailMarketing`, `apps/web/app/routes/admin/email-marketing*`, and `apps/web/app/routes/app.$tenant/email-marketing*` under the `email-marketing` component.
|
||||
- `docs/feature-manifests/transactional-mail.json` keeps password reset, invitation, verification, and system email in Core while allowing Email Marketing and Newsletter abstractions to move to plugins.
|
||||
- `docs/features/email-sequences.md` keeps Email Sequences separate as foundation/admin-preview work gated by `MARKETING_SEQUENCES_ENABLED`, with production delivery blocked on explicit follow-ups.
|
||||
- `docs/features/marketing-funnel.md` keeps the general `marketing-outbound` handler separate as a shipped foundation that is not bootstrapped from `apps/worker/src/index.ts`.
|
||||
|
||||
## Couplings
|
||||
|
||||
### CRM contacts and audience selection
|
||||
|
||||
`apps/web/app/modules/emailMarketing/services/EmailMarketingService.ts` directly imports `CrmService` and `ContactDto` from `~/modules/crm/services/CrmService`. Campaign drafts call `EntityViewsApi.get()` for entity name `contact`, load contact row IDs, call `CrmService.getContactsInRowIds()`, and reject campaigns when contacts are missing or not marked as `marketingSubscriber`. Contact previews and campaign sends call `CrmService.getContact()` and use contact fields for variable replacement.
|
||||
|
||||
This makes CRM the current audience provider for Email Marketing. CRM cannot be removed from Core first unless Email Marketing is also extracted with CRM, is disabled behind a clear CRM-plugin dependency, or receives a plugin-owned audience/list abstraction that replaces CRM contacts and the `marketingSubscriber` contact field.
|
||||
|
||||
### Rows/entities runtime
|
||||
|
||||
Campaign recipients use `OutboundEmail.contactRowId` in `prisma/schema/email.prisma`, and that field relates to generic `Row`. This ties marketing recipients to the rows/entities runtime and, in practice, to CRM contact rows. Future extraction may keep rows/entities as Core infrastructure, but Email Marketing must own or declare the contact/audience semantics that sit on top of rows.
|
||||
|
||||
### Routes and feature gating
|
||||
|
||||
`apps/web/app/routes/admin/email-marketing.tsx` and `apps/web/app/routes/app.$tenant/email-marketing.tsx` are layout routes with nested route directories. Both validate CRM before rendering. The tenant route also checks `appConfiguration.app.features.tenantEmailMarketing` and redirects when tenant Email Marketing is disabled. Future plugin packaging must preserve clear disabled-state behavior and avoid leaving routable pages that fail because CRM entities are missing.
|
||||
|
||||
### Sender, provider, and outbound services
|
||||
|
||||
Email Marketing owns sender configuration, campaign composition, outbound email records, tracking records, and broadcast send calls. This is a marketing-send surface, not a Core transactional mail surface. Future extraction must move these pieces together so Core password reset/invitation/system email remains independent from marketing campaign providers and tracking.
|
||||
|
||||
### Commands, navigation, and translations
|
||||
|
||||
Routes use `emailMarketing.title` and `emailMarketing.senders.plural` translation keys and email/crm icon navigation. `apps/web/app/services/command-registry/commandRegistry.ts` is the shared command-registration surface that must be audited for Email Marketing or CRM-dependent entries during extraction. Translation keys in `apps/web/public/locales/en/translations.json` and `apps/web/public/locales/de/translations.json` should move with plugin UI or be removed only when all plugin UI is removed.
|
||||
|
||||
### Documentation and manifests
|
||||
|
||||
`docs/feature-inventory.md`, `docs/feature-manifests/plugin-candidates.json`, `docs/feature-manifests/transactional-mail.json`, and `docs/feature-decisions/crm-decision-report.md` together define the boundary: Email Marketing is a plugin candidate, CRM is a plugin candidate, transactional mail remains Core, and CRM contacts currently provide the Email Marketing audience. Future implementation and verification must keep those sources consistent.
|
||||
|
||||
`docs/feature-manifests/plugin-candidates.json` must not use the `email-sequences` admin-preview foundation or the unbootstrapped `marketing-outbound` handler as evidence that Email Marketing has already been extracted. Email Sequences and marketing-outbound may interact with marketing queues, but they are separate status surfaces: Email Sequences are foundation/admin-preview with production followups, while marketing-outbound is a general handler foundation until a worker bootstrap wires its subscriber.
|
||||
|
||||
## Sender Secrets and Provider Boundary
|
||||
|
||||
Email Marketing sender credentials are plugin-owned marketing credentials, not Core transactional-mail credentials. `prisma/schema/email.prisma` defines `EmailSender.apiKey`, `provider`, `stream`, from-address, reply-to, tenant, campaign, and outbound-email relations. `docs/feature-manifests/plugin-candidates.json` states that plugin provider secrets must be admin/platform-owned unless explicitly tenant-owned, while `docs/feature-manifests/transactional-mail.json` states transactional mail provider API keys are platform/admin-owned and never tenant-owned.
|
||||
|
||||
Future extraction must therefore make ownership explicit:
|
||||
|
||||
1. Marketing sender API keys must move with the Email Marketing plugin and be encrypted/stored according to the platform's secret-storage standard.
|
||||
2. Tenant-scoped senders may exist because `EmailSender.tenantId` is optional, but tenant ownership does not imply arbitrary tenant access to raw provider secrets.
|
||||
3. Transactional mail settings for password reset, invitation, verification, and system email remain Core and must not be reused implicitly for bulk marketing campaigns.
|
||||
4. Marketing sends, campaign tracking, unsubscribe handling, opens, clicks, bounces, and spam complaints are plugin responsibilities.
|
||||
5. A future verifier must fail if the report or manifests blur transactional mail and marketing mail boundaries.
|
||||
|
||||
## Schema and Data Impact
|
||||
|
||||
`prisma/schema/email.prisma` contains both inbound/general email models and marketing campaign models. The marketing-owned schema impact is:
|
||||
|
||||
- `EmailSender` stores sender/provider configuration, API key, optional tenant ownership, and relations to campaigns/outbound emails.
|
||||
- `Campaign` stores campaign metadata, content, status, sender relation, optional tenant ownership, and recipient relation.
|
||||
- `OutboundEmail` stores each recipient/send record, optional campaign relation, `contactRowId`, email address, sender, preview flag, errors, sent/delivery/bounce/spam/unsubscribe timestamps, and open/click relations.
|
||||
- `OutboundEmailOpen` and `OutboundEmailClick` store tracking events.
|
||||
- `OutboundEmail.contactRowId` links to `Row`, which currently represents CRM contacts selected through contact entity views.
|
||||
|
||||
Future extraction must choose one data strategy before removing CRM contact rows:
|
||||
|
||||
1. Bundle with CRM: keep `contactRowId` and contact variables because CRM remains installed with Email Marketing.
|
||||
2. Depend on CRM plugin: declare the dependency and fail clearly when CRM is not enabled.
|
||||
3. Own audience/list data: introduce plugin-owned audience, subscriber, list, consent, and merge-field tables or row templates, then migrate campaigns/outbound records away from direct CRM contact assumptions.
|
||||
|
||||
Data migration must preserve campaign history, outbound delivery/tracking history, unsubscribe state, and sender configuration. Existing rows should not be silently deleted when a plugin is disabled.
|
||||
|
||||
## CRM Audience Decision
|
||||
|
||||
The current audience decision is explicit: Email Marketing depends on CRM contacts today. `EmailMarketingService.ts` uses CRM contacts as campaign recipients, enforces `marketingSubscriber`, replaces variables from CRM contact/company fields, and rejects non-contact campaign recipients. The CRM decision report also says CRM extraction must audit Email Marketing first.
|
||||
|
||||
Future extraction must pick exactly one path before CRM removal:
|
||||
|
||||
1. **Bundle path:** extract Email Marketing and CRM together as a vertical plugin where CRM contact rows remain the canonical audience.
|
||||
2. **Dependency path:** extract Email Marketing separately but declare CRM as a required plugin dependency; disabled or missing CRM must produce a clear unavailable-plugin status instead of route/runtime errors.
|
||||
3. **Audience abstraction path:** create an Email Marketing-owned audience/list/subscriber abstraction with consent fields, import/sync hooks, and merge-field support; migrate campaign creation and send flows away from `CrmService` and `contactRowId` before CRM is removed.
|
||||
|
||||
Until one path is implemented, Email Marketing must not be treated as standalone Core and CRM must not be deleted ahead of Email Marketing.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
Future Email Marketing extraction/removal work must run in this atomic sequence:
|
||||
|
||||
1. Decision/report: land this `extract-plugin` report and the static verifier before runtime changes.
|
||||
2. Manifest/docs alignment: update `docs/feature-inventory.md`, `docs/feature-manifests/plugin-candidates.json`, and any dedicated Email Marketing manifest so they point to this canonical report and agree with `docs/feature-manifests/transactional-mail.json`.
|
||||
3. CRM audience decision: choose bundle, dependency, or audience abstraction. Do not remove CRM contacts, `CrmService`, or CRM entity templates before this choice is implemented.
|
||||
4. Route/module packaging: move or remove `apps/web/app/modules/emailMarketing`, `apps/web/app/routes/admin/email-marketing.tsx`, `apps/web/app/routes/admin/email-marketing/*`, `apps/web/app/routes/app.$tenant/email-marketing.tsx`, and `apps/web/app/routes/app.$tenant/email-marketing/*` in one implementation slice.
|
||||
5. Schema migration: move or migrate plugin-owned `EmailSender`, `Campaign`, `OutboundEmail`, `OutboundEmailOpen`, and `OutboundEmailClick` ownership while preserving transactional/inbound mail models needed by Core.
|
||||
6. Sender secret boundary: migrate marketing sender provider secrets to plugin-owned settings and ensure Core transactional mail credentials remain separate.
|
||||
7. Command/navigation/i18n cleanup: remove or plugin-register Email Marketing command entries in `apps/web/app/services/command-registry/commandRegistry.ts`, route/sidebar visibility, icons, and translation keys in `apps/web/public/locales/en/translations.json` and `apps/web/public/locales/de/translations.json`.
|
||||
8. Tests/static scans: add focused tests and static checks so Core no longer imports Email Marketing when the plugin is disabled, transactional mail remains available, CRM dependency behavior is explicit, and docs/manifests stay consistent.
|
||||
|
||||
## Verification Plan
|
||||
|
||||
T03 must add a local static verifier, expected at `scripts/verify-email-marketing-decision-report.mjs`, and a focused test file, expected at `scripts/verify-email-marketing-decision-report.test.mjs`. The verifier must fail on the negative cases named in this task plan:
|
||||
|
||||
- Missing required heading: Decision, Scope, Current Code Surfaces, Couplings, Sender Secrets and Provider Boundary, Schema and Data Impact, CRM Audience Decision, Execution Plan, Verification Plan, Risks.
|
||||
- Missing exact decision token `Decision: `extract-plugin``.
|
||||
- Placeholder drift such as unresolved TODO/TBD placeholders outside explicit verifier-requirement wording.
|
||||
- Unresolved required path references for concrete current paths and route directories.
|
||||
- Manifest drift between this report, `docs/feature-inventory.md`, `docs/feature-manifests/plugin-candidates.json`, `docs/feature-manifests/transactional-mail.json`, and `docs/feature-decisions/crm-decision-report.md`.
|
||||
- Missing CRM coupling statements for `CrmService`, `ContactDto`, contact views, `marketingSubscriber`, and `OutboundEmail.contactRowId`.
|
||||
- Boundary drift that mixes transactional mail with marketing mail or omits sender API-key ownership.
|
||||
|
||||
The verifier should specifically check that this report references the current required surfaces: `apps/web/app/modules/emailMarketing`, `apps/web/app/routes/admin/email-marketing.tsx`, `apps/web/app/routes/admin/email-marketing/*`, `apps/web/app/routes/app.$tenant/email-marketing.tsx`, `apps/web/app/routes/app.$tenant/email-marketing/*`, `apps/web/app/modules/emailMarketing/services/EmailMarketingService.ts`, `apps/web/app/modules/emailMarketing/db/emailSender.ts`, `apps/web/app/modules/emailMarketing/db/campaigns.db.server.ts`, `apps/web/app/modules/emailMarketing/db/outboundEmails.db.server.ts`, `prisma/schema/email.prisma`, `apps/web/app/services/command-registry/commandRegistry.ts`, `apps/web/public/locales/en/translations.json`, `apps/web/public/locales/de/translations.json`, `docs/feature-manifests/plugin-candidates.json`, `docs/feature-manifests/transactional-mail.json`, and `docs/feature-decisions/crm-decision-report.md`.
|
||||
|
||||
Task-level smoke verification for this report is:
|
||||
|
||||
- `test -s docs/feature-decisions/email-marketing-decision-report.md`
|
||||
- `grep -q "Decision: \`extract-plugin\`" docs/feature-decisions/email-marketing-decision-report.md`
|
||||
|
||||
Manual verification for a future runtime extraction should cover:
|
||||
|
||||
- Password reset, invitation, verification, and system emails still work without Email Marketing installed.
|
||||
- Email Marketing routes are absent or show a clear disabled-plugin state when the plugin is disabled.
|
||||
- Campaign creation and sending either work with the declared CRM dependency or use the new audience/list abstraction.
|
||||
- Sender credentials are not exposed to tenants beyond intended administration workflows.
|
||||
- Existing campaigns, outbound history, tracking events, unsubscribes, and sender settings remain migratable.
|
||||
|
||||
## Risks
|
||||
|
||||
- Missing the CRM contact coupling would make later CRM extraction break campaign preview/send flows.
|
||||
- Mixing transactional mail with marketing mail would risk breaking password reset, invitation, verification, or system email while removing campaign features.
|
||||
- Omitting sender API-key ownership would make plugin extraction unsafe because marketing credentials may be tenant-scoped in data but still require platform-grade secret handling.
|
||||
- Removing Email Marketing routes without schema/data migration can leave campaigns, outbound records, tracking data, and sender secrets orphaned.
|
||||
- Removing CRM contacts before an audience decision can leave campaigns without recipients and variable replacement without data.
|
||||
- Translation, command, sidebar, and route-helper leftovers can keep a removed plugin visible or navigable.
|
||||
- Existing tenants may rely on campaign history, unsubscribes, and sender configuration; plugin extraction should include compatibility, export, or migration notes rather than silent data loss.
|
||||
|
||||
## Update (R-P14C)
|
||||
|
||||
HiveGrid ticket R-P14C (2026-06-30) removes the legacy Entity-Builder campaign
|
||||
path under **Variante A** (remove, do not migrate — the bespoke campaign editor
|
||||
is rebuilt by David/D-KAMP). The typed send engine (CampaignSendService) and
|
||||
typed recipient segments (AK-P14b) already cover sending, so no functionality is
|
||||
lost beyond the old UI shell:
|
||||
|
||||
- `apps/web/app/modules/emailMarketing/services/EmailMarketingService.ts` deleted
|
||||
(the `CrmService`/`ContactDto`/contact-views consumer). The Campaigns
|
||||
list/new/edit routes, components, and the `OutboundEmail.contactRowId` column
|
||||
rendering were removed; the typed activity log keeps opens/clicks/delivery.
|
||||
- The `OutboundEmail.contactRowId` / `Row` relation is dropped from
|
||||
`prisma/schema/email.prisma`; the typed `kontaktId` field is the recipient link.
|
||||
- `apps/web/app/modules/crm` legacy reader is removed once its last consumer is
|
||||
gone. The file-existence + manifest-code-area assertions for
|
||||
`EmailMarketingService.ts` were dropped from
|
||||
`scripts/verify-email-marketing-decision-report.mjs`; the historical coupling
|
||||
references (`CrmService`, `ContactDto`, `OutboundEmail.contactRowId`) are kept.
|
||||
-114
@@ -1,114 +0,0 @@
|
||||
# Knowledge Base, Widgets, Workflow Engine, and Public Marketing Decision Report
|
||||
|
||||
## Decision
|
||||
|
||||
Decision: `extract-plugin` for Knowledge Base, Widgets, and Workflow Engine.
|
||||
|
||||
Decision: `remove-from-core` for Public Marketing remnants, including Public Marketing, Blog, Changelog, and marketing-chatbot surfaces.
|
||||
|
||||
D009 classifies Knowledge Base, Widgets, and Workflow Engine as optional plugin candidates, not Boilerplate Core and not immediate deletion targets. D009 also classifies remaining Public Marketing/Blog/Changelog/marketing-chatbot surfaces as removal candidates because marketing content and unauthenticated marketing automation conflict with the target minimal boilerplate core. This report is the canonical Feature Decision/S05 lifecycle source for R009 while supporting R001, R002, and R003 through a deterministic, sequential decision pass.
|
||||
|
||||
No runtime routes, schema, package dependencies, API handlers, sidebar registrations, workers, queues, or data records are changed in this slice. This slice records the decision contract only so later implementation slices can extract plugins or remove marketing remnants atomically after their route, schema, API, dependency, sidebar, public-data, and worker boundaries are audited.
|
||||
|
||||
## Scope
|
||||
|
||||
The scoped feature groups are Knowledge Base, Widgets, Workflow Engine, and Public Marketing remnants. The canonical action tokens are:
|
||||
|
||||
- Knowledge Base: `extract-plugin`.
|
||||
- Widgets: `extract-plugin`.
|
||||
- Workflow Engine: `extract-plugin`.
|
||||
- Public Marketing remnants: `remove-from-core`.
|
||||
|
||||
The scoped documentation and manifest sources are `docs/feature-inventory.md`, `docs/feature-manifests/plugin-candidates.json`, and `docs/feature-manifests/remove-candidates.json`. They must keep Knowledge Base, Widgets, and Workflow Engine in the plugin-candidate boundary and keep Public Marketing/Blog/Changelog/marketing-chatbot in the removal-candidate boundary. This report does not reclassify unrelated features and does not authorize runtime pruning during Feature Decision/S05.
|
||||
|
||||
## Current Code Surfaces
|
||||
|
||||
Concrete surfaces that later work must audit before changing runtime behavior:
|
||||
|
||||
- Knowledge Base module: `apps/web/app/modules/knowledgeBase`.
|
||||
- Knowledge Base admin routes: `apps/web/app/routes/admin/knowledge-base*`.
|
||||
- Knowledge Base public docs routes: `apps/web/app/routes/docs/*`.
|
||||
- Knowledge Base plugin-disabled help route tree: `apps/web/app/routes/help/*`.
|
||||
- Knowledge Base schema: `prisma/schema/knowledgeBase.prisma`.
|
||||
- Widgets module: `apps/web/app/modules/widgets`.
|
||||
- Widgets tenant routes: `apps/web/app/routes/app.$tenant/__widgets/*`.
|
||||
- Widgets API surface: `apps/api/src/app.ts`.
|
||||
- Widgets package DB helper: `packages/db/src/widgets.server.ts`.
|
||||
- Workflow schema: `prisma/schema/workflows.prisma`.
|
||||
- Workflow Engine module: `apps/web/app/modules/workflowEngine`.
|
||||
- Workflow admin routes were removed; Workflow Engine remains tenant-scoped via `apps/web/app/routes/app.$tenant/__workflows/*`.
|
||||
- Workflow tenant routes: `apps/web/app/routes/app.$tenant/__workflows/*`.
|
||||
- Workflow API routes: `apps/web/app/routes/internal/api/__workflows/*`.
|
||||
- Blog, changelog, and brand route surfaces were removed during pruning and remain historical evidence only.
|
||||
- Public entity route: `apps/web/app/routes/public/$entity.$id.tsx`.
|
||||
- Marketing chatbot route and tool surfaces were removed during pruning and remain historical evidence only.
|
||||
|
||||
## Knowledge Base Boundary
|
||||
|
||||
Knowledge Base is a support/docs product surface and is classified by D009 as `extract-plugin`. It is useful for products that need public help centers, localized articles, and support content, but it is not required for the minimal boilerplate core.
|
||||
|
||||
Later extraction must account for `apps/web/app/modules/knowledgeBase`, `apps/web/app/routes/docs/*`, `apps/web/app/routes/admin/knowledge-base*`, `apps/web/app/routes/help/*`, and `prisma/schema/knowledgeBase.prisma` together. The public docs routes create a public-data boundary: article content may be intentionally public, but draft state, tenant ownership, author metadata, internal support content, localized variants, and any user-generated or operational metadata must not become publicly exposed during extraction.
|
||||
|
||||
Knowledge Base must remain a plugin candidate, not a Public Marketing removal candidate, even if some seed or fake article content is later removed as source-product copy. Public help content and admin knowledge-base management need their own plugin-owned route, schema, sidebar, and data-retention plan before code moves or schema is pruned.
|
||||
|
||||
## Widgets Boundary
|
||||
|
||||
Widgets are classified by D009 as `extract-plugin`. Embedded widgets are product-specific because they expose tenant-configured embed behavior, public or semi-public API access, and integration expectations that vary by product.
|
||||
|
||||
Later extraction must audit `apps/web/app/modules/widgets`, `apps/web/app/routes/app.$tenant/__widgets/*`, `apps/api/src/app.ts`, and `packages/db/src/widgets.server.ts` together. The API and package DB surfaces mean Widgets are not only a UI module: API handlers, route parameters, widget identifiers, tenant ownership, and ORM-safe data access must remain aligned.
|
||||
|
||||
Widgets include a public/API boundary because embedded widget IDs and API reads may be exposed outside the authenticated tenant shell. Later work must validate and normalize widget identifiers, keep tenant ownership checks explicit, preserve parameterized/ORM-safe filters, and avoid exposing tenant-private configuration, PII, or internal widget records through public embed endpoints.
|
||||
|
||||
## Workflow Engine Boundary
|
||||
|
||||
Workflow Engine is classified by D009 as `extract-plugin`. It is a powerful automation surface, but its dependency, schema, API, and possible worker/queue behavior make it too complex and product-specific for the minimal boilerplate core.
|
||||
|
||||
Later extraction must audit `apps/web/app/modules/workflowEngine`, `apps/web/app/routes/app.$tenant/__workflows/*`, `apps/web/app/routes/internal/api/__workflows/*`, and `prisma/schema/workflows.prisma` together. Workflow route ownership spans tenant app and API surfaces, so partial extraction would leave broken automation entry points or orphaned schema.
|
||||
|
||||
Workflow execution now has an explicit worker/outbox boundary in the current codebase: workflow event producers publish through the outbox, the `worker-general` group can route `outbox.workflow`, and the worker-native trigger runner owns idempotent execution startup. Later extraction must preserve or replace that boundary and define whether workflow definitions, runs, triggers, logs, retries, external event subscriptions, and package dependencies move into a worker-backed plugin, remain disabled unless the plugin is installed, or are removed only after data retention and audit requirements are satisfied.
|
||||
|
||||
## Public Marketing Removal Boundary
|
||||
|
||||
Public Marketing remnants are classified by D009 as `remove-from-core`. Blog, brand, playground/debug, marketing-chatbot, and public row sharing at `apps/web/app/routes/public/$entity.$id.tsx` have been pruned and remain historical evidence only. Future scans should treat any reintroduced unauthenticated marketing/public row surface as a regression.
|
||||
|
||||
These surfaces are removal candidates, not plugin candidates, because marketing sites, blog/changelog content, public entity marketing pages, and unauthenticated marketing chatbot behavior belong outside the default boilerplate. Later pruning must preserve only neutral Core public pages that are required for auth, legal, billing, or app shell behavior.
|
||||
|
||||
Marketing chatbot removal must be handled carefully because it touches AI/chatbot routes and tools. The `remove-from-core` action applies only to the marketing chatbot API route and marketing-specific tool implementations named in this report; it does not reclassify the broader AI, chatbot, prompt builder, or MCP plugin-candidate surfaces.
|
||||
|
||||
## Schema and Data Impact
|
||||
|
||||
No schema or data changes occur in Feature Decision/S05. Later Knowledge Base extraction must account for `prisma/schema/knowledgeBase.prisma`, public help article visibility, localization, draft/published state, tenant ownership, authoring metadata, and any fake/source-product article content that should be removed separately from plugin extraction.
|
||||
|
||||
Later Widgets extraction must preserve the data contract used by `packages/db/src/widgets.server.ts`, tenant-owned widget configuration, API-visible widget identifiers, public embed access, and any PII or tenant-private fields that must not leak through API handlers. Widget data should be migrated, exported, retained, or disabled through a plugin-owned lifecycle instead of silently deleted.
|
||||
|
||||
Later Workflow Engine extraction must include a schema/data plan for `prisma/schema/workflows.prisma`, including definitions, triggers, execution state, logs, retries, external subscriptions, and tenant ownership. Later Public Marketing cleanup must keep blog/changelog content, public entity pages, marketing-chatbot prompts/tools, source-product copy, and related fake data outside Core without affecting retained Core data.
|
||||
|
||||
## Sidebar API and Package Dependency Impact
|
||||
|
||||
No sidebar entries, API handlers, or package dependencies are changed in this slice. Later Knowledge Base extraction must update admin/help navigation only through an explicit plugin enablement or routing boundary, while keeping Core navigation free of support-docs product assumptions.
|
||||
|
||||
Later Widgets extraction must handle tenant sidebar visibility, `apps/api/src/app.ts` widget endpoints, `packages/db/src/widgets.server.ts`, widget route parameters, and package ownership together. Removing or moving only the UI routes would leave API/package surfaces behind; removing only API support would break embedded widgets still reachable from tenant routes.
|
||||
|
||||
Later Workflow Engine extraction must audit package dependencies such as workflow graph/automation libraries together with `apps/web/app/modules/workflowEngine`, workflow schema, admin/tenant/API routes, and any worker/queue runtime. Later Public Marketing removal may allow marketing-only chatbot, blog, changelog, visual editor, or marketing asset dependencies to be pruned, but only after consumers are proven gone.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Land this D009 report and align `docs/feature-inventory.md`, `docs/feature-manifests/plugin-candidates.json`, and `docs/feature-manifests/remove-candidates.json` so human-readable and machine-readable sources point to the same canonical decision.
|
||||
2. Add a static verifier that checks required headings, exact action tokens, D009/R001/R002/R003/R009 citations, required path references, manifest alignment, placeholder-free content, and absence of runtime-change instructions in this documentation slice.
|
||||
3. Audit Knowledge Base routes, module code, schema, admin/sidebar exposure, public help visibility, localization, source-product/fake content, and public-data boundaries before extraction.
|
||||
4. Audit Widgets tenant routes, API handlers, `packages/db/src/widgets.server.ts`, identifier validation, tenant ownership, public embed behavior, package dependencies, and sidebar visibility before extraction.
|
||||
5. Audit Workflow Engine admin/tenant/API routes, schema, dependency graph, trigger/run/log data, worker/queue expectations, retries, and API behavior before extraction.
|
||||
6. Keep `apps/web/app/routes/public/$entity.$id.tsx` and removed Blog/Brand/debug/playground/chatbot paths as historical D009 evidence rather than active code areas; any reintroduction needs an explicit plugin or product decision.
|
||||
7. Implement runtime extraction or removal only in later implementation slices after the verifier and audits prove route, schema, API, package dependency, sidebar, public-data, and worker boundaries can change atomically.
|
||||
|
||||
## Verification Plan
|
||||
|
||||
The Feature Decision/S05 verifier must fail with explicit diagnostics when required sections are missing, exact action tokens are absent, D009 or R001/R002/R003/R009 citations are missing, required paths drift, placeholders appear, manifest classification no longer matches the report, inventory references drift, Public Marketing/Blog/Changelog/marketing-chatbot are incorrectly moved to plugin candidates, or the report suggests runtime code changes in this slice.
|
||||
|
||||
Task-level verification for this report is static: the file must be non-empty, contain no unresolved placeholder markers, cite D009, and contain the exact action tokens `extract-plugin` and `remove-from-core`. Slice-level verification later runs `scripts/verify-kb-widgets-workflow-marketing-decision-report.mjs` and focused Vitest drift tests without browser, Playwright, Cypress, or other E2E execution.
|
||||
|
||||
## Risks
|
||||
|
||||
The main risk is partial implementation after this decision pass: extracting Knowledge Base without public help/data boundaries, moving Widgets UI without API and package DB ownership, changing Workflow Engine routes without schema and worker/queue planning, or removing marketing chatbot code while leaving unauthenticated public behavior reachable elsewhere.
|
||||
|
||||
A second risk is classification drift. Knowledge Base, Widgets, and Workflow Engine must remain `extract-plugin` candidates unless D009 is superseded, while Public Marketing/Blog/Changelog/marketing-chatbot must remain `remove-from-core` candidates rather than being packaged as default plugins. Downstream agents must treat this report as the decision boundary and verify documentation/manifest alignment before any runtime code changes.
|
||||
-79
@@ -1,79 +0,0 @@
|
||||
# Portals/Sites Decision Report
|
||||
|
||||
## Decision
|
||||
|
||||
Decision: `extract-plugin`
|
||||
|
||||
Portals/Sites are classified by D007 as an optional plugin candidate, not as Boilerplate Core and not as an immediate removal target. This report is the canonical Portals/Sites lifecycle source for Feature Decision/S03 and carries forward the D006 deferral that kept Portals/Sites persistence in module-owned DB files until the Feature Decision feature decision was made. The current code surfaces are retained as plugin-candidate inventory, while default core route registration disables the portal/site route trees. Later implementation work must preserve or explicitly remove the retained schema, billing provider, analytics, domains, sidebar, docs, environment, and verification boundaries atomically.
|
||||
|
||||
No runtime code is changed in this slice. This slice only records the decision report and prepares the later static verifier/execution plan so downstream agents do not blindly alter retained Portals/Sites surfaces or mistake disabled plugin routes for active core routes.
|
||||
|
||||
## Scope
|
||||
|
||||
The scoped feature group covers customer portal and site-builder functionality across tenant routes, admin routes, module services, Prisma schema, billing provider behavior, analytics filters, domains configuration, sidebar command docs, environment examples, and feature inventory/manifests.
|
||||
|
||||
The canonical inventory and manifest references are `docs/feature-inventory.md` and `docs/feature-manifests/plugin-candidates.json`. They must continue to classify Portals/Sites as a plugin candidate and should reference this report once inventory alignment lands. The decision does not reclassify Portals/Sites as Core, and it does not instruct executors to remove or change runtime code during Feature Decision/S03.
|
||||
|
||||
## Current Code Surfaces
|
||||
|
||||
Concrete Portals/Sites surfaces that later work must audit before any runtime change. Route paths listed here are retained plugin-candidate code surfaces, not active default core route registrations:
|
||||
|
||||
- Modules: `apps/web/app/modules/portals` and `apps/web/app/modules/sites`.
|
||||
- Admin route: removed from the default HiveGrid admin surface; tenant portal routes remain inventoried as plugin-candidate code.
|
||||
- Tenant portal routes: `apps/web/app/routes/app.$tenant/__portals/*`.
|
||||
- Tenant site routes: `apps/web/app/routes/app.$tenant/sites/*`.
|
||||
- Portal billing provider services: `apps/web/app/modules/portals/services/PortalPayment provider.server.ts` and `apps/web/app/modules/portals/services/Payment providerConnect.server.ts`.
|
||||
- Module-owned persistence: `apps/web/app/modules/portals/db/portals.db.server.ts` and `apps/web/app/modules/sites/db/sites.db.server.ts`.
|
||||
- Site configuration types: `apps/web/app/modules/sites/site-types.ts`.
|
||||
- Analytics coupling: `prisma/schema/analytics.prisma` powers portal analytics; the old admin analytics route was removed from the core admin surface.
|
||||
- Domains coupling: `apps/web/app/modules/domains/services/Domains.server.ts`.
|
||||
- Sidebar coverage: `apps/web/app/application/sidebar/AppSidebar.test.tsx`.
|
||||
- Prisma schema surfaces: `prisma/schema/portals.prisma` and `prisma/schema/sites.prisma`.
|
||||
- Environment documentation: `.env.example` and `.env.production.example`.
|
||||
- Documentation and manifest contracts: `docs/feature-inventory.md` and `docs/feature-manifests/plugin-candidates.json`.
|
||||
|
||||
## Couplings
|
||||
|
||||
Portals/Sites are coupled to tenant navigation, admin management, analytics reporting, domain resolution, billing provider flows, Prisma schema, and environment configuration. The retained route code spans both hidden portal paths under `apps/web/app/routes/app.$tenant/__portals/*` and visible site-builder paths under `apps/web/app/routes/app.$tenant/sites/*`, while default core route discovery excludes those plugin trees. Extraction must preserve route ownership and user-visible navigation behavior if the plugin is enabled, or remove the retained surfaces atomically.
|
||||
|
||||
Analytics portal filters and site page-view behavior must be explicitly preserved, redesigned, or removed during later implementation. Domains behavior in `apps/web/app/modules/domains/services/Domains.server.ts` must also be treated as part of the feature boundary because public site routing and domain lookup can become broken if the module is moved without corresponding domain configuration.
|
||||
|
||||
## Billing Provider Boundary
|
||||
|
||||
Portals/Sites include billing-provider behavior through the portal pricing and subscription persistence boundary. Later implementation must preserve or explicitly decide provider checkout behavior, customer billing portal behavior, provider initialization, webhook expectations, environment variables, and failure handling before moving or removing any portal billing route.
|
||||
|
||||
This report keeps Billing/Subscriptions Core separate from the Portals/Sites plugin candidate. Core subscription flows remain in HiveGrid, while portal-specific payment-connect and customer portal behavior must be isolated behind a plugin/provider boundary if Portals/Sites are extracted.
|
||||
|
||||
## Schema and Data Impact
|
||||
|
||||
D006 deferred Portals/Sites DB ownership and accepted temporary module-owned DB files at `apps/web/app/modules/portals/db/portals.db.server.ts` and `apps/web/app/modules/sites/db/sites.db.server.ts`. D007 resolves the lifecycle classification but does not move data access in this slice. Later implementation must preserve or decide the module-owned DB boundary before changing persistence.
|
||||
|
||||
The schema surfaces `prisma/schema/portals.prisma`, `prisma/schema/sites.prisma`, and `prisma/schema/analytics.prisma` must be audited together. Extraction or removal must include an explicit schema/data migration plan for portal records, site records, analytics relations, foreign keys, seeds or fixtures, and rollback behavior.
|
||||
|
||||
## Sidebar Command Docs Impact
|
||||
|
||||
The app sidebar and its tests must stay aligned with the feature classification. `apps/web/app/application/sidebar/AppSidebar.test.tsx` should continue to prove that retained navigation does not expose removed plugin surfaces and that optional plugin entries are gated or documented consistently.
|
||||
|
||||
Docs and command/playbook surfaces must point executors to this report before runtime work. Inventory and manifest alignment must update `docs/feature-inventory.md` and `docs/feature-manifests/plugin-candidates.json` so future static checks can detect drift between human-readable documentation and machine-readable plugin classification.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Land this report and a static verifier for required sections, exact decision token, D007 reference, D006 deferral, path references, manifest alignment, unresolved placeholders, and no runtime-change instructions in this slice.
|
||||
2. Audit dependencies across routes, modules, billing provider services, analytics, domains, environment examples, sidebar tests, Prisma schema, and docs/manifests.
|
||||
3. Implement route/module extraction or removal only after the dependency audit proves a safe order for `apps/web/app/modules/portals`, `apps/web/app/modules/sites`, `apps/web/app/routes/app.$tenant/__portals/*`, and `apps/web/app/routes/app.$tenant/sites/*`.
|
||||
4. Create the schema/data migration plan for `prisma/schema/portals.prisma`, `prisma/schema/sites.prisma`, `prisma/schema/analytics.prisma`, and the module-owned DB files before moving persistence or deleting data models.
|
||||
5. Define the billing/env boundary for portal-specific Payment provider Connect, customer billing portal behavior, dynamic site API keys, and `.env.example`, `.env.production.example` updates.
|
||||
6. Align analytics, domains, sidebar, docs, inventory, and plugin manifest references so retained Core behavior remains coherent after extraction.
|
||||
7. Add or update focused tests and static scans that protect route coverage, manifest classification, schema/data expectations, provider boundaries, and placeholder-free documentation without browser or E2E execution in this documentation slice.
|
||||
|
||||
## Verification Plan
|
||||
|
||||
The Feature Decision/S03 verifier must fail with explicit diagnostics when required sections are missing, the exact decision token is absent, D007 or the D006 deferral is not cited, required path references drift, placeholders appear, manifest classification no longer matches `extract-plugin`, the inventory does not reference the canonical report, or the report suggests runtime code changes in this slice.
|
||||
|
||||
Task-level verification for this report is static: the file must be non-empty and must contain `Decision: `extract-plugin``. Slice-level verification later runs `scripts/verify-portals-sites-decision-report.mjs` without browser, Playwright, Cypress, or other E2E execution.
|
||||
|
||||
## Risks
|
||||
|
||||
Missing any route, schema, provider, analytics, domains, environment, sidebar, inventory, or manifest surface would let a later implementation handle Portals/Sites incompletely. Reclassifying Portals/Sites as Core would conflict with D007, while immediate removal would conflict with the `extract-plugin` action and the D006 ownership deferral.
|
||||
|
||||
The highest implementation risk is partial extraction: moving routes without billing provider/customer portal decisions, deleting schema without data migration, or changing analytics/domains behavior without preserving public site expectations. Downstream work must therefore treat this report as the decision boundary and use static verification before runtime code changes.
|
||||
@@ -1,81 +0,0 @@
|
||||
# Feature Inventory fuer Boilerplate-Pruning
|
||||
|
||||
Last reconciled: 2026-05-28. Quelle: `apps/web/app/routes`, `apps/web/app/modules`, Sidebars, Root-`package.json` und der aktuelle Repo-State-Snapshot `docs/architecture-migration-status.md`. Ziel ist eine praktische Entscheidungshilfe, welche Produktflaechen im Standard-Boilerplate bleiben, optionalisiert oder entfernt werden sollten.
|
||||
|
||||
Statushinweis: Dieses Inventar beschreibt den Dokumentations-/Manifest-Vertrag fuer R003 und ist kein Nachweis, dass alle genannten Codeflaechen bereits geloescht oder paketiert wurden. Der aktuelle Architecture Closure-Abschluss fuer API-, Worker- und Package-Boundaries, Feature-Manifeste und Bundle-/Performance-Evidenz ist in `docs/architecture-migration-status.md` dokumentiert.
|
||||
|
||||
Maschinenlesbare Feature-Vertraege liegen in `docs/feature-manifests/`. Sie spiegeln diese Inventarentscheidung als JSON-Manifeste fuer Core-, Plugin- und Removal-Grenzen und werden durch `apps/web/app/application/featureManifests.test.ts` validiert. Die Klassifikationen sind bewusst mehrstufig: `core` bleibt die neutrale SaaS-Basis, `product-core` ist das aktuell mitgelieferte CRM-SaaS-Showcase, `plugin-candidates` beschreibt die Extraktionsgrenzen fuer produktnahe Flaechen, und `remove-candidate` beschreibt direkte Pruning-Ziele statt dauerhaft unterstuetzte Legacy-Flaechen. Ein Modul kann deshalb heute im Product Core aktiv sein und trotzdem als Plugin-Kandidat markiert bleiben, wenn die naechste saubere Grenze eine optionale Auskopplung ist.
|
||||
|
||||
## Manifest-Decision: Pruned Core statt Full-Boilerplate
|
||||
|
||||
Feature Manifest entscheidet gegen eine Full-Boilerplate-Retention als Dauerzustand: Der Standard ist ein pruned core plus versionierter Product Core fuer das CRM-SaaS-Showcase. `core` bleibt die aktive Boilerplate-Basis; `product-core` beschreibt Blueprint-, Plan-, Custom-Plan-, Tenant-Override- und Tenant-Rollen-Gates fuer CRM-SaaS-Produktmodule; `plugin-candidate` beschreibt nur noch Extraktionsvertraege fuer optionale Produktflaechen ausserhalb dieses Product Core; `remove-candidate` beschreibt Loesch- oder Review-Vertraege fuer Flaechen, die nicht als dauerhaft unterstuetztes Legacy-Verhalten fortgefuehrt werden sollen. Die Manifeste sind Planungs- und Runtime-Guardrails fuer diese naechsten Schritte, aber kein Beleg, dass jede markierte Flaeche bereits aus dem aktuellen Root-Runtime-Code entfernt oder als Plugin ausgelagert wurde.
|
||||
|
||||
## Core behalten
|
||||
|
||||
| Feature | Rationale | Wahrscheinliche Codebereiche |
|
||||
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Auth, Accounts, Tenants, Rollen/Rechte | Basis fuer jede SaaS/App-Installation; Admin- und Tenant-Flows haengen daran. | `apps/web/app/routes/login.tsx`, `register.tsx`, `forgot-password.tsx`, `reset.tsx`, `verify.$id.tsx`, `invitation.$id.tsx`, `apps/web/app/routes/admin/accounts*`, `apps/web/app/routes/app.$tenant/settings/*`, `apps/web/app/modules/users`, `apps/web/app/utils/services/authService.ts`, `rolesAndPermissionsService.ts` |
|
||||
| Tenant-App Shell, Dashboard, Settings | Kernprodukt braucht eine stabile App- und Admin-Huelle; Routing nutzt `appPath`, `adminPath` und kanonische Host-Helper. | `apps/web/app/routes/app.$tenant.tsx`, `apps/web/app/routes/app.$tenant/dashboard.tsx`, `apps/web/app/routes/app.$tenant/settings*`, `apps/web/app/application/sidebar/AppSidebar.tsx`, `apps/web/app/components/layouts/sidebars/*` |
|
||||
| Admin Shell und System Settings | Notwendig fuer Betrieb, Nutzerverwaltung, Pricing-Konfiguration und Diagnostik. | `apps/web/app/routes/admin.tsx`, `apps/web/app/routes/admin/dashboard.tsx`, `apps/web/app/routes/admin/settings*`, `apps/web/app/application/sidebar/AdminSidebar.tsx` |
|
||||
| API-Grundlage und Keys | Plan sieht API-Split vor; Auth-, Docs-, Accounts-, Key-Validation- und Usage-Endpunkte liegen in `apps/api`; Web-Routen bleiben UI/Settings-Surfaces. | `apps/api/src/app.ts`, `/v1/api-keys/validate`, `/v1/usage`, `apps/web/app/routes/admin/api/*`, `apps/web/app/routes/app.$tenant/settings/api/*`, `apps/web/app/modules/api` |
|
||||
| DB/ORM-Schicht und Rows-Basis | Viele Features bauen auf Prisma, Entities und Rows; vor Entfernung anderer Features als Datenfundament stabilisieren. | `packages/db`, `prisma`, `apps/web/app/modules/rows`, `apps/web/app/utils/db/**`, `apps/web/app/modules/templates/defaultEntityTemplates.ts` |
|
||||
| Transactional Email | Passwort-Reset, Einladungen und Systemmails sind Core; Mailjet ist der einzige Runtime-Provider. | `apps/web/app/modules/emails`, `apps/web/app/utils/services/emailService.ts`, `packages/mail`, dep `@hivegrid/mail` |
|
||||
| Billing/Subscriptions | Fuer HiveGrid Core, aber bewusst minimal halten; Lago fuer Billing/Rechnungen, Mollie fuer Payments, Admin-Pricing-Settings und Tenant-Subscription bleiben Standard; Public-Marketing-Pricing ist entfernt. | `subscribe.$tenant*`, `apps/web/app/routes/app.$tenant/settings/subscription.tsx`, `apps/web/app/routes/admin/settings/pricing*`, `apps/api/src/app.ts` `/v1/billing/mollie/webhooks`, `apps/web/app/application/pricing`, deps `@getlago/lago-js`, `@mollie/api-client` |
|
||||
| i18n | Mandatory, Deutsch Default; Runtime-Konfiguration liegt ueber `@hivegrid/i18n`, Locale-Dateien bleiben unter `apps/web/public/locales`. | `packages/i18n`, `apps/web/app/locale/*`, Translation-Dateien, `i18next*` deps |
|
||||
| UI-Primitives/Layout | Core als Adapter-Ziel (`packages/ui`), aber gemischte UI-Quellen spaeter konsolidieren. | `apps/web/app/components/ui`, `packages/ui`, `apps/web/app/components/layouts`, Radix/shadcn deps, `lucide-react` |
|
||||
|
||||
## Optional / Plugin / Admin-Preview
|
||||
|
||||
| Feature | Rationale | Wahrscheinliche Codebereiche |
|
||||
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| CRM | Aktuell Teil des versionierten `product-core` CRM-SaaS-Showcase, aber wegen default entities `company/contact/opportunity` und Email-Marketing-Kopplung zugleich ein Extraktionskandidat fuer spaetere optionale Verticals. Kanonische Feature Decision baseline-Entscheidung: `docs/feature-decisions/crm-decision-report.md`. Die Route-Codeflaechen bleiben als Plugin-Kandidaten inventarisiert, ohne zu behaupten, dass CRM aus dem heutigen Product Core entfernt ist. | `apps/web/app/modules/crm`, `apps/web/app/routes/admin/crm*`, `apps/web/app/routes/app.$tenant/crm*`, `apps/web/app/modules/templates/defaultEntityTemplates.ts`, Sidebars |
|
||||
| Email Marketing/Newsletter | Kanonische Feature Decision flow-Entscheidung: `docs/feature-decisions/email-marketing-decision-report.md`, Decision `extract-plugin`. Als Plugin halten; aktuelle Audience-Quelle sind CRM contacts oder spaeter eine Plugin-Audience. Core bleibt nur transactional mail. | `apps/web/app/modules/emailMarketing`, `apps/web/app/routes/admin/email-marketing*`, `apps/web/app/routes/app.$tenant/email-marketing*` |
|
||||
| Email Sequences | Foundation/Admin-Preview, kein Plugin-Kandidat im aktuellen Manifest-Vertrag und kein Core-Transactional-Mail-Verhalten. Delayed-Step-Scheduling, Queue-Enqueueing, bundled Template-Renderer, `@hivegrid/mail` Mailjet-Adapter und signed Mailjet bounce/rejection ingress existieren; Production-Delivery bleibt durch Seed-Daten, Stats-Aggregation-Cron/Persistenz, provider delivery/open/click reconciliation evidence beyond the in-repo tracking routes, E2E und Scheduler-/Deploy-Evidenz blockiert. Kanonischer Status: `docs/features/email-sequences.md`; Produktion bleibt mit `MARKETING_SEQUENCES_ENABLED=false` empfohlen, bis diese Follow-ups landen. | `apps/web/app/routes/admin/email-sequences*`, `packages/email-sequences`, `packages/email-templates`, `apps/worker/src/jobs/email-sequence-*`, `apps/worker/src/jobs/lead-stale-trigger.ts`, `apps/worker/src/jobs/trial-expiring-trigger.ts`, `prisma/schema/emailSequences.prisma` |
|
||||
| Workflow Engine | Tenant-Modul. Admins konfigurieren keine Workflows; der alte Host-Admin-Spiegel wurde entfernt. Langfristig bleibt Workflow Engine nach D009 (`docs/feature-decisions/kb-widgets-workflow-marketing-decision-report.md`) ein `extract-plugin`-Kandidat. Die produktionsnahe Worker/Queue-Boundary wird deshalb im Root weiter gehaertet, waehrend Schema-, API- und Worker-Grenzen extraktionsfaehig bleiben muessen. | `apps/web/app/modules/workflowEngine`, `apps/web/app/routes/app.$tenant/__workflows/*`, `apps/web/app/routes/internal/api/__workflows/*`, `prisma/schema/workflows.prisma`, direkte deps `@xyflow/react`, `dagre`; `eventsource-parser` ist nur transitiv im Lockfile sichtbar. |
|
||||
| Knowledge Base | Support-/Docs-Produktflaeche mit Public-Docs- und Daten-Sichtbarkeitsgrenze. Fuer das CRM-SaaS-Showcase kann sie Product-Core sein; nach D009 (`docs/feature-decisions/kb-widgets-workflow-marketing-decision-report.md`) bleibt sie zugleich `extract-plugin`-Kandidat. Admin-/Help-Route-Trees duerfen deshalb nur ueber dokumentierte Gates sichtbar werden; `/docs` bleibt die aktive public Docs-Flaeche. | `apps/web/app/modules/knowledgeBase`, `apps/web/app/routes/docs/*`, `apps/web/app/routes/admin/knowledge-base*`, `apps/web/app/routes/help/*`, `prisma/schema/knowledgeBase.prisma` |
|
||||
| Portals/Sites | Kanonische Feature Decision/S03-Entscheidung D007: `docs/feature-decisions/portals-sites-decision-report.md`, Decision `extract-plugin`. Mehr Produktplattform als Boilerplate-Core; als customer portal/site-builder Plugin halten. Die Admin-Portal-Route wurde aus der Default-Admin-Oberflaeche entfernt; Tenant-Route-Codeflaechen bleiben als Plugin-Kandidaten inventarisiert. | `apps/web/app/modules/portals`, `apps/web/app/modules/sites`, `apps/web/app/routes/app.$tenant/__portals/*`, `apps/web/app/routes/app.$tenant/sites/*` |
|
||||
| Analytics/Metrics | Core braucht ggf. minimale Observability, aber product analytics UI/collection sollte opt-in sein. Die alte Admin-Analytics- und Admin-Metrics-Oberfläche ist entfernt; Business-Analytics/MRR wird später neu geplant. | `apps/web/app/modules/analytics`, `apps/web/app/modules/metrics`, `apps/api/src/app.ts` `/v1/analytics/*`, dep `recharts` |
|
||||
| Events/Webhooks/Audit Trails | Domain events sind fuer Integrationen/Workers sinnvoll. Der Admin-Event-Browser ist mit Audit & Events zusammengefasst; entity webhooks koennen optional sein. Webhook-Attempt-Retry liegt in `apps/api` unter `/v1/events/webhooks/attempts/:id`; alte public Demo-ACK-Routen wurden aus dem Core entfernt. | `apps/web/app/modules/events`, `apps/web/app/routes/admin/events*`, `apps/web/app/routes/admin/audit-trails.tsx`, `apps/api/src/app.ts`, entity `webhooks.tsx` routes |
|
||||
| No-code Entity Builder/Code Generator | Sehr grosser Surface-Bereich. Fuer generische Boilerplate vermutlich optional; Core kann nur DB/Admin-Grundlagen behalten. Entity-Metadata-API liegt in `apps/api` unter `/v1/entities/:entity`. | `apps/web/app/routes/admin/entities*`, `apps/web/app/routes/app.$tenant/settings/entities*`, `apps/api/src/app.ts` `/v1/entities/:entity`, `/v1/entities/:entity/rows`, `/v1/entities/:entity/rows/:rowId`, `/v1/relationships/*`, `/v1/exports/:exportJobId/download-url`, `apps/web/app/modules/codeGenerator`, `apps/web/app/modules/formulas`, `apps/web/app/modules/jsonProperties`, `apps/web/app/modules/rows` |
|
||||
| AI, Chatbot, Prompt Builder, MCP | Provider-/Kosten-/Security-lastig; klar als Plugin. | `apps/web/app/modules/ai`, `ai-gen`, `chatbot`, `promptBuilder`, `mcp`, `apps/web/app/routes/admin/ai/*`, `apps/web/app/routes/admin/chat/*`, `apps/web/app/routes/app.$tenant/chat/*`, deps `ai`, `@ai-sdk/*`, `@modelcontextprotocol/sdk`, `tokenlens` |
|
||||
| Help Desk | Support-Produktflaeche; optional mit KB koppeln. Inbound-Email-Runtime und UI sind entfernt. | `apps/web/app/modules/helpDesk`, `apps/web/app/routes/admin/help-desk*` |
|
||||
| Onboarding Builder | Admin-Builder aus der Default-Admin-Oberflaeche entfernt. Der oeffentliche Session-/Runtime-Flow bleibt separat stehen und wird spaeter eigenstaendig bewertet. | `apps/web/app/modules/onboarding`, `apps/web/app/routes/onboarding.$id.tsx` |
|
||||
| Feature Flags | Kann Core fuer grosse Apps sein, aber fuer Boilerplate als Plugin/advanced admin Feature pruefen. | `apps/web/app/modules/featureFlags`, `apps/web/app/routes/admin/feature-flags*`, AdminSidebar |
|
||||
| Widgets | Kanonische Feature Decision/S05-Entscheidung D009: `docs/feature-decisions/kb-widgets-workflow-marketing-decision-report.md`, Decision `extract-plugin`. Eingebettete Widgets sind produktnah; alte Widget-Route-/API-Reste sind plugin-disabled und nicht Teil der aktuellen `/v1` API. | `apps/web/app/modules/widgets`, `apps/web/app/routes/app.$tenant/__widgets/*`, `apps/api/src/app.ts`, `packages/db/src/widgets.server.ts`, historische Widget-API-Evidenz |
|
||||
| Notifications | Nicht prominent in Sidebar, aber Modul/Routen und externe Provider-Diagnostik sind optional; Produktzustellung laeuft ueber interne Queue/DB-Delivery. | `apps/web/app/modules/notifications`, `apps/web/app/routes/admin/notifications*`, `apps/api/src/app.ts` `/v1/notifications/stream`, `packages/db/src/notifications.server.ts`, `apps/worker/src/handlers.ts` |
|
||||
| Storage/Supabase | Wenn File Uploads bleiben, Storage-Abstraktion behalten; Supabase als Provider optional machen. | `apps/web/app/modules/storage`, deps `@supabase/*`, upload/form/media code |
|
||||
|
||||
## Entfernen pruefen
|
||||
|
||||
| Feature/Rest | Rationale | Wahrscheinliche Codebereiche |
|
||||
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| Marketing/Public Site Reste | Kanonische Feature Decision/S05-Entscheidung D009: `docs/feature-decisions/kb-widgets-workflow-marketing-decision-report.md`, Decision `remove-from-core`. Marketing ist nicht Teil des Boilerplates; die fruehere public-row-sharing Runtime ist entfernt. | historische D009-Evidenz; deps/Assets fuer landing effects, falls in kuenftigen Scans wieder eingefuehrt |
|
||||
| Blog/Changelog Remnants | Kanonische Feature Decision/S05-Entscheidung D009: `docs/feature-decisions/kb-widgets-workflow-marketing-decision-report.md`, Decision `remove-from-core`. Blog/Changelog sind Marketing-/Content-Flaechen und nicht Standard-Boilerplate-Core; die frueheren aktiven Codeflaechen sind bereits geprunt. | historische D009-Evidenz |
|
||||
| Affiliate/Rewardful | Planentscheidung: entfernen als Standard. Sichtbare Portal-/Analytics-/Route-Reste, Portal-Schemafelder und die verwaiste App-Icon-Komponente sind entfernt. | historische Migrationen |
|
||||
| Provider-Duplikate fuer Mail | Mailjet ist der einzige Runtime-Provider; entfernte Alt-Provider sind aus Runtime-Code und Env-Katalog entfernt. | `packages/mail`, `apps/web/app/modules/emails` |
|
||||
| Playground/Demo/Debug Surfaces | Nicht produktionsreif als Boilerplate-Default; die frueheren Dev-/Debug-/Playground-Routen sind bereits historische Evidenz. | demo site API/routes, falls in kuenftigen Scans wieder eingefuehrt |
|
||||
| Marketing Chatbot | Kanonische Feature Decision/S05-Entscheidung D009: `docs/feature-decisions/kb-widgets-workflow-marketing-decision-report.md`, Decision `remove-from-core`. Die unauthenticated Marketing-Chatbot-Flaechen wurden entfernt und bleiben historische Evidenz. | historische D009-Evidenz |
|
||||
| Default source-product copy/assets/fake data | Whitelabel-Cleanup im Plan; Fake-Content-Helfer, demo Entity-Row-Route und alte Source-Produkt-Logos sind aus der aktiven Source entfernt. | historische Evidenz |
|
||||
| Heavy editor/visual deps nach Feature-Extraktion | Nach Entfernen oder Plugin-Extraktion der owning Features koennen Monaco/Tiptap/Novel/drag-drop/syntax/math deps entfallen; vorher muessen aktive Shared-UI-Imports auditiert werden. Ungenutzte particles deps sind bereits entfernt. | deps unter Review: rich-text editor, drag/drop, syntax highlighting, math rendering |
|
||||
|
||||
## Bereits entfernt
|
||||
|
||||
| Feature | Status | Evidenz | Restpruefung |
|
||||
| ----------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Public `/contact` und `/newsletter` als Default-Marketingflaechen | Entfernt | Historische Pruning-Entscheidung: Public `/contact` und `/newsletter` wurden als Default-Marketingflaechen entfernt. Keine entsprechenden Top-Level-Routen in `apps/web/app/routes` gefunden. | Newsletter-Begriff lebt in Email Marketing/Plan weiter; als Plugin-Grenze oder direkten Mailjet-Flow bewerten. |
|
||||
| Affiliate als Standardentscheidung | Entfernt | Plan sagt "remove affiliate/rewardful as standard boilerplate functionality". | Sichtbare Standardfunktion, Portal-Schemafelder und die verwaiste App-Icon-Komponente sind entfernt; nur historische Migrationen enthalten noch alte Spalten. |
|
||||
| Monorepo-Skeleton teilweise vorhanden | Review-needed | `apps/*` und `packages/*` package files existieren; Root nutzt `pnpm-lock.yaml`; Details stehen in `docs/architecture-migration-status.md`. | App-Code liegt weiterhin breit unter `apps/web/app/`; Inventar hier bewertet Feature-Surface, nicht Migrationsfortschritt. |
|
||||
|
||||
## Pruning-Reihenfolge
|
||||
|
||||
1. Zuerst harte Remove-Entscheidungen umsetzen: Affiliate/Rewardful-Reste, Marketing/Public Site, Blog/Changelog, Demo/Playground.
|
||||
2. Danach Plugin-Kandidaten extrahieren oder Product-Core-Module finalisieren: CRM, Email Marketing, KB, Help Desk, Portals/Sites, Widgets.
|
||||
3. Dann review-needed Plattformfeatures final klassifizieren: No-code Entity Builder, Workflows, AI/Chatbot/Prompt Builder, Analytics/Metrics, Notifications.
|
||||
4. Zum Schluss Dependencies bereinigen, weil viele Libraries nur nach Feature-Entfernung sicher erkennbar ungenutzt sind.
|
||||
|
||||
## Hinweise fuer Entfernung
|
||||
|
||||
- Sidebars sind nicht die einzige Wahrheit: einige Features sind nicht sichtbar oder feature-gated, haben aber aktive Routen/API/DB-Code.
|
||||
- No-code Entities, Rows, CRM und Email Marketing sind stark gekoppelt. CRM/Email Marketing nicht entfernen, ohne default entity templates und row routes mitzuauditen.
|
||||
- App-required public pages nutzen neutrale Core-Layout-Komponenten; PageBlocks/CMS ist kein Core-Feature mehr und wird durch `pnpm run verify:removed-modules` als Runtime-Regression gescannt.
|
||||
- Worker/API/Mail-Split sollte vor grossen Provider-Entfernungen beruecksichtigt werden, damit nicht dieselbe Flaeche zweimal migriert wird.
|
||||
@@ -1,80 +0,0 @@
|
||||
# Feature Manifests
|
||||
|
||||
This directory is the machine-readable contract for boilerplate core pruning. It complements `docs/feature-inventory.md`, which remains the human-readable inventory.
|
||||
|
||||
## Manifest-Decision: Pruned Core statt Full-Boilerplate
|
||||
|
||||
Feature Manifest chooses Pruned Core over a permanent Full-Boilerplate retention promise. `core` manifests define what remains in the default boilerplate; `plugin-candidate` manifests are extraction contracts for optional product surfaces; and `remove-candidate` manifests are deletion or review contracts for surfaces that should not become indefinitely supported legacy behavior. These manifests operationalize the inventory decision as planning/runtime guardrails and do not claim that every extraction or deletion has already happened in the current root runtime.
|
||||
|
||||
Architecture Closure closure aligns three canonical sources for future feature work: `docs/architecture-migration-status.md` records the current API, worker, package, pruning, and bundle handoff status; `docs/feature-inventory.md` records the human-readable Core/Plugin/Removal inventory; and `docs/feature-manifests/*.json` records the machine-readable Core/Plugin/Removal contract. Treat the manifest set as the executor-facing source of truth for ownership, dependencies, configuration, provider, worker, UAT, and pruning boundaries. Any future feature addition, migration, extraction, or removal must update the relevant manifest before implementation so code changes satisfy the declared contract instead of relying on stale roadmap assumptions.
|
||||
|
||||
Feature-specific decision reports may live under `docs/feature-decisions/`; canonical examples are the CRM decision report at `docs/feature-decisions/crm-decision-report.md` and the Email Marketing decision report at `docs/feature-decisions/email-marketing-decision-report.md`.
|
||||
|
||||
## Contract
|
||||
|
||||
Each `*.json` manifest follows `schema.json` and uses:
|
||||
|
||||
- `id`: stable feature identifier for cross-references.
|
||||
- `classification`: `core`, `plugin-candidate`, `remove-candidate`, or `mixed`.
|
||||
- `codeAreas`: likely source locations. These are planning hints, not ownership grants.
|
||||
- `dependencies`: other manifest IDs this feature needs.
|
||||
- `consumers`: features or surfaces that rely on this feature.
|
||||
- `integration.ownership`: `tenant-owned`, `admin-managed`, `hybrid`, or `system-only`.
|
||||
- `integration.surfaces`: admin, tenant, public, and API route contracts.
|
||||
- `integration.configuration`: admin settings, tenant settings, environment variables, and secret ownership.
|
||||
- `integration.workers`: queue/job requirements for async, browser-backed, or long-running work.
|
||||
- `integration.externalProviders`: provider dependencies such as billing vendors, AI providers, mail vendors, or browser runtimes.
|
||||
- `integration.permissions`, `auditEvents`, `billingImpacts`, and `uat`: implementation guardrails and operator checks.
|
||||
- `boundaries.mustKeep`: behavior that should remain in the boilerplate.
|
||||
- `boundaries.mayMoveToPlugin`: behavior safe to extract after dependency review.
|
||||
- `boundaries.mustNotTouch`: areas excluded from the current phase or owned by parallel work.
|
||||
- `pruning.action`: current intended action: `keep`, `extract-plugin`, `remove`, or `review`.
|
||||
|
||||
Route entries are source ownership hints unless they explicitly start with a runtime path such as `/v1/...`. Runtime URLs must follow the host split: admin routes live at the admin host root, tenant routes live under `/:tenant` on the app host, and API routes live under `/v1` on the API host. Implementation work must use host-aware helpers rather than reintroducing `/admin/...`, `/app/...`, or `/api/v1/...` links.
|
||||
|
||||
When a manifest change affects UI text, tenant data, or deploy behavior, include the matching verification in the plan: `pnpm run verify:i18n`, tenant-scope negative tests, `pnpm run verify:deploy-workflow`, Docker smoke checks, and production seed artifact verification as applicable.
|
||||
|
||||
## Current Manifests
|
||||
|
||||
- `core.json`: umbrella contract for the boilerplate core.
|
||||
- `product-core.json`: versioned CRM SaaS Product Core blueprint and access-gating contract.
|
||||
- `auth-tenancy.json`: authentication, accounts, tenants, roles, invitations.
|
||||
- `rows-entities-runtime.json`: Prisma/DB, rows, entity runtime foundations.
|
||||
- `billing.json`: Lago-backed subscription, invoice, and Mollie payment foundation.
|
||||
- `transactional-mail.json`: password reset, invitation, and system mail.
|
||||
- `admin-app-shell.json`: admin and tenant app shells, dashboards, settings.
|
||||
- `plugin-candidates.json`: feature groups to package or make optional.
|
||||
- `remove-candidates.json`: feature groups to remove or aggressively review.
|
||||
- `ai-chatbot-admin-managed.json`: reference pattern for admin-managed, tenant-consumed, worker/browser-backed AI features.
|
||||
|
||||
## Proprietary Feature Template
|
||||
|
||||
When importing or building a proprietary feature, create or update a manifest before code changes and fill these fields:
|
||||
|
||||
- Feature ownership: `tenant-owned`, `admin-managed`, `hybrid`, or `system-only`.
|
||||
- Admin, tenant, public and API surfaces.
|
||||
- Config ownership: admin settings, tenant settings, environment variables.
|
||||
- Secrets policy: owner, storage, and client exposure rules.
|
||||
- Worker/queue jobs: queue names and job names from `packages/queue`.
|
||||
- Permissions: admin configuration and tenant usage capabilities.
|
||||
- Audit events: configuration, enablement, job lifecycle and failure events.
|
||||
- Billing impact: plan gates, metering, provider cost exposure.
|
||||
- UAT checklist: positive, negative and secret-exposure checks.
|
||||
|
||||
To create a valid scaffold:
|
||||
|
||||
```sh
|
||||
pnpm run manifest:new -- --id my-feature --title "My Feature" --classification plugin-candidate --ownership hybrid
|
||||
```
|
||||
|
||||
The generator writes `docs/feature-manifests/my-feature.json` and refuses to overwrite unless `--force` is passed. Replace scaffold placeholders before implementation.
|
||||
|
||||
## Validation
|
||||
|
||||
Cheap syntax validation:
|
||||
|
||||
```sh
|
||||
find docs/feature-manifests -name '*.json' -print0 | xargs -0 -n1 node -e 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"))'
|
||||
```
|
||||
|
||||
The app test suite validates the manifest structure, required integration fields, dependency references, admin-managed secret ownership, and worker queue/job declarations.
|
||||
@@ -1,116 +0,0 @@
|
||||
{
|
||||
"schemaVersion": "1.0",
|
||||
"id": "admin-app-shell",
|
||||
"title": "Admin and Tenant App Shell",
|
||||
"classification": "core",
|
||||
"status": "proposed",
|
||||
"owner": "core-pruning",
|
||||
"description": "Authenticated tenant shell, admin shell, dashboards, settings layout, and core sidebar structure.",
|
||||
"rationale": [
|
||||
"The boilerplate needs stable authenticated shells even after product-specific modules are removed.",
|
||||
"Admin settings are required for operations, users, pricing configuration, and diagnostics."
|
||||
],
|
||||
"codeAreas": [
|
||||
"apps/web/app/routes/app.$tenant.tsx",
|
||||
"apps/web/app/routes/app.$tenant/dashboard.tsx",
|
||||
"apps/web/app/routes/app.$tenant/settings*",
|
||||
"apps/web/app/routes/admin.tsx",
|
||||
"apps/web/app/routes/admin/dashboard.tsx",
|
||||
"apps/web/app/routes/admin/settings*",
|
||||
"apps/web/app/application/sidebar/AppSidebar.tsx",
|
||||
"apps/web/app/application/sidebar/AdminSidebar.tsx",
|
||||
"apps/web/app/components/layouts/sidebars/*"
|
||||
],
|
||||
"dependencies": [
|
||||
"auth-tenancy",
|
||||
"billing",
|
||||
"rows-entities-runtime"
|
||||
],
|
||||
"consumers": [
|
||||
"core",
|
||||
"plugin-candidates"
|
||||
],
|
||||
"integration": {
|
||||
"ownership": "hybrid",
|
||||
"surfaces": {
|
||||
"adminRoutes": [
|
||||
"apps/web/app/routes/admin.tsx",
|
||||
"apps/web/app/routes/admin/dashboard.tsx",
|
||||
"apps/web/app/routes/admin/settings*"
|
||||
],
|
||||
"tenantRoutes": [
|
||||
"apps/web/app/routes/app.$tenant.tsx",
|
||||
"apps/web/app/routes/app.$tenant/dashboard.tsx",
|
||||
"apps/web/app/routes/app.$tenant/settings*"
|
||||
],
|
||||
"publicRoutes": [],
|
||||
"apiRoutes": []
|
||||
},
|
||||
"configuration": {
|
||||
"admin": [
|
||||
"Admin shell settings and operational defaults"
|
||||
],
|
||||
"tenant": [
|
||||
"Tenant shell navigation and tenant settings"
|
||||
],
|
||||
"environment": [],
|
||||
"secrets": []
|
||||
},
|
||||
"workers": {
|
||||
"required": false,
|
||||
"queues": [],
|
||||
"jobs": [],
|
||||
"notes": [
|
||||
"Shell features should not introduce background jobs by default."
|
||||
]
|
||||
},
|
||||
"externalProviders": [],
|
||||
"permissions": [
|
||||
"admin.*",
|
||||
"app.settings.*"
|
||||
],
|
||||
"auditEvents": [
|
||||
"admin.settings.updated",
|
||||
"tenant.settings.updated"
|
||||
],
|
||||
"billingImpacts": [
|
||||
"Shell may expose subscription status but should not own billing logic."
|
||||
],
|
||||
"uat": [
|
||||
"Admin can reach dashboard/settings.",
|
||||
"Tenant can reach dashboard/settings.",
|
||||
"Navigation only shows permitted surfaces."
|
||||
]
|
||||
},
|
||||
"boundaries": {
|
||||
"mustKeep": [
|
||||
"Tenant app layout",
|
||||
"Admin layout",
|
||||
"Dashboard entry points",
|
||||
"Core settings navigation",
|
||||
"System settings needed for operations"
|
||||
],
|
||||
"mayMoveToPlugin": [
|
||||
"Sidebar entries for optional product modules",
|
||||
"Admin pages that only manage plugin features",
|
||||
"Demo or playground shell entries"
|
||||
],
|
||||
"mustNotTouch": [
|
||||
"Route files during manifest Phase 1",
|
||||
"Sidebar and navigation code owned by parallel workers"
|
||||
]
|
||||
},
|
||||
"pruning": {
|
||||
"phase": "1",
|
||||
"action": "keep",
|
||||
"notes": [
|
||||
"Use plugin/remove manifests to decide which shell entries become optional later."
|
||||
]
|
||||
},
|
||||
"validation": {
|
||||
"source": [
|
||||
"docs/feature-inventory.md"
|
||||
],
|
||||
"lastReviewed": "2026-05-05"
|
||||
}
|
||||
}
|
||||
-178
@@ -1,178 +0,0 @@
|
||||
{
|
||||
"schemaVersion": "1.0",
|
||||
"id": "ai-chatbot-admin-managed",
|
||||
"title": "Admin-Managed AI Chatbot",
|
||||
"classification": "plugin-candidate",
|
||||
"status": "proposed",
|
||||
"owner": "feature-integration",
|
||||
"description": "Tenant-facing AI chatbot whose provider credentials, browser/runtime policy, and global availability are managed by admin/platform configuration.",
|
||||
"rationale": [
|
||||
"AI provider keys and browser automation capabilities are sensitive platform resources and should not be stored in tenant-owned settings by default.",
|
||||
"Tenant users can consume the chatbot while admin controls provider choice, budgets, allowed models, browser access, and safety policy.",
|
||||
"Browser-backed AI work is operationally different from normal request/response UI and should be declared as worker-backed before implementation."
|
||||
],
|
||||
"codeAreas": [
|
||||
"apps/web/app/modules/chatbot",
|
||||
"apps/web/app/modules/ai",
|
||||
"apps/web/app/routes/admin/ai/*",
|
||||
"apps/web/app/routes/admin/chat/*",
|
||||
"apps/web/app/routes/app.$tenant/chat/*",
|
||||
"apps/web/app/components/ai-elements/*",
|
||||
"apps/web/app/utils/html-sanitizer.ts",
|
||||
"apps/api/src/app.ts",
|
||||
"/v1/ai/upload",
|
||||
"apps/worker",
|
||||
"packages/queue"
|
||||
],
|
||||
"dependencies": [
|
||||
"core",
|
||||
"auth-tenancy",
|
||||
"admin-app-shell",
|
||||
"rows-entities-runtime"
|
||||
],
|
||||
"consumers": [
|
||||
"plugin-candidates"
|
||||
],
|
||||
"integration": {
|
||||
"ownership": "admin-managed",
|
||||
"surfaces": {
|
||||
"adminRoutes": [
|
||||
"apps/web/app/routes/admin/ai/*",
|
||||
"apps/web/app/routes/admin/chat/*",
|
||||
"admin settings for provider credentials, model policy, browser policy, and usage limits"
|
||||
],
|
||||
"tenantRoutes": [
|
||||
"apps/web/app/routes/app.$tenant/chat/*",
|
||||
"tenant chatbot launcher or embedded assistant surface"
|
||||
],
|
||||
"publicRoutes": [],
|
||||
"apiRoutes": [
|
||||
"/v1/ai/upload",
|
||||
"streaming chat endpoints",
|
||||
"worker enqueue/status endpoints if browser work is async"
|
||||
]
|
||||
},
|
||||
"configuration": {
|
||||
"admin": [
|
||||
"AI provider API key approved for the deployment region",
|
||||
"Allowed model list",
|
||||
"Default model",
|
||||
"Browser automation enablement",
|
||||
"Browser allowlist/denylist policy",
|
||||
"Per-tenant feature enablement",
|
||||
"Global budget and rate limits"
|
||||
],
|
||||
"tenant": [
|
||||
"Tenant-level enable/disable if admin allows it",
|
||||
"Tenant-facing chatbot context and display preferences",
|
||||
"Optional tenant knowledge/context selection without provider secrets"
|
||||
],
|
||||
"environment": [
|
||||
"AI_PROCESSING_REGION",
|
||||
"MISTRAL_API_KEY",
|
||||
"MISTRAL_MODEL",
|
||||
"SCALEWAY_API_KEY",
|
||||
"SCALEWAY_MODEL",
|
||||
"SCALEWAY_BASE_URL",
|
||||
"SCALEWAY_REGION",
|
||||
"ALEPH_ALPHA_API_KEY",
|
||||
"ALEPH_ALPHA_MODEL",
|
||||
"ALEPH_ALPHA_BASE_URL",
|
||||
"AI_GENERATION_MAX_ESTIMATED_INPUT_COST_CENTS",
|
||||
"AI_GENERATION_RATE_LIMIT",
|
||||
"AI_GENERATION_RATE_LIMIT_WINDOW_MS",
|
||||
"BULLMQ_REDIS_URL",
|
||||
"BROWSER_RUNTIME_URL",
|
||||
"BROWSER_RUNTIME_API_KEY",
|
||||
"BROWSER_SESSION_TIMEOUT_MS"
|
||||
],
|
||||
"secrets": [
|
||||
"AI provider API keys are admin/platform-owned.",
|
||||
"Provider keys must never be exposed in tenant routes, tenant JSON loaders, browser bundles, or client-visible config.",
|
||||
"Browser session credentials and proxy credentials are worker/platform-owned."
|
||||
]
|
||||
},
|
||||
"workers": {
|
||||
"required": true,
|
||||
"queues": [
|
||||
"hivegrid.ai-chatbot",
|
||||
"hivegrid.browser-automation"
|
||||
],
|
||||
"jobs": [
|
||||
"chat-completion",
|
||||
"browser-session-run",
|
||||
"browser-session-cleanup",
|
||||
"usage-flush"
|
||||
],
|
||||
"notes": [
|
||||
"Short text-only chat can stream in request scope, but any browser-backed task must be queue/worker-backed.",
|
||||
"Worker jobs must receive scoped tenant/user/context IDs, not raw secrets from tenant input.",
|
||||
"Browser jobs must enforce admin-owned allowlist policy before navigation."
|
||||
]
|
||||
},
|
||||
"externalProviders": [
|
||||
"deployment-region-ai-provider",
|
||||
"browser-runtime"
|
||||
],
|
||||
"permissions": [
|
||||
"admin.ai.configure",
|
||||
"admin.ai.providers.update",
|
||||
"admin.ai.usage.view",
|
||||
"app.ai.chat.use"
|
||||
],
|
||||
"auditEvents": [
|
||||
"admin.ai.provider_key.updated",
|
||||
"admin.ai.model_policy.updated",
|
||||
"admin.ai.browser_policy.updated",
|
||||
"tenant.ai_chatbot.enabled",
|
||||
"ai_chatbot.browser_job.started",
|
||||
"ai_chatbot.browser_job.completed",
|
||||
"ai_chatbot.browser_job.failed"
|
||||
],
|
||||
"billingImpacts": [
|
||||
"AI token usage may need plan gates or usage metering.",
|
||||
"Browser runtime usage may need separate metering from text-token usage.",
|
||||
"Admin-owned provider keys mean platform billing exposure unless tenant pass-through billing is explicitly designed."
|
||||
],
|
||||
"uat": [
|
||||
"Admin can save provider configuration without exposing the key to tenant responses or client bundles.",
|
||||
"Admin can enable/disable the chatbot for a tenant.",
|
||||
"Tenant can start a chat only when the feature is enabled and permission allows it.",
|
||||
"AI markdown and web-preview surfaces sanitize active HTML and restrict preview iframes to safe HTTP(S) targets.",
|
||||
"Browser-backed chat tasks run through a worker queue and enforce admin allowlist policy.",
|
||||
"Usage and key-policy changes emit audit events."
|
||||
]
|
||||
},
|
||||
"boundaries": {
|
||||
"mustKeep": [
|
||||
"Provider secrets remain admin/platform-owned.",
|
||||
"Tenant surfaces only receive non-secret feature state and allowed options.",
|
||||
"Browser-backed tasks require worker isolation and navigation policy enforcement."
|
||||
],
|
||||
"mayMoveToPlugin": [
|
||||
"All AI/chatbot/browser automation surfaces",
|
||||
"Provider-specific AI implementation",
|
||||
"Usage metering beyond core billing hooks"
|
||||
],
|
||||
"mustNotTouch": [
|
||||
"Core auth/session logic except permission checks needed by this plugin.",
|
||||
"Core billing internals except explicit usage-meter hooks."
|
||||
]
|
||||
},
|
||||
"pruning": {
|
||||
"phase": "planning",
|
||||
"action": "extract-plugin",
|
||||
"notes": [
|
||||
"Use this as the reference pattern for admin-managed tenant features that need provider secrets or workers.",
|
||||
"Do not implement browser automation in request scope."
|
||||
]
|
||||
},
|
||||
"validation": {
|
||||
"source": [
|
||||
"docs/agent-playbooks/admin-managed-features.md",
|
||||
"docs/agent-playbooks/worker-backed-features.md",
|
||||
"docs/agent-playbooks/feature-integration.md"
|
||||
],
|
||||
"lastReviewed": "2026-05-16"
|
||||
}
|
||||
}
|
||||
@@ -1,152 +0,0 @@
|
||||
{
|
||||
"schemaVersion": "1.0",
|
||||
"id": "auth-tenancy",
|
||||
"title": "Auth, Accounts, Tenancy, Roles",
|
||||
"classification": "core",
|
||||
"status": "proposed",
|
||||
"owner": "core-pruning",
|
||||
"description": "Authentication, account lifecycle, tenant membership, invitations, and authorization primitives.",
|
||||
"rationale": [
|
||||
"Every SaaS or app installation needs account access, tenant scoping, and permission enforcement.",
|
||||
"Admin and tenant flows depend on the same membership and role foundations.",
|
||||
"Operator admins need silent tenant inspection access without being seeded as tenant members."
|
||||
],
|
||||
"codeAreas": [
|
||||
"apps/web/app/routes/login.tsx",
|
||||
"apps/web/app/routes/register.tsx",
|
||||
"apps/web/app/routes/forgot-password.tsx",
|
||||
"apps/web/app/routes/reset.tsx",
|
||||
"apps/web/app/routes/oauth/github/*",
|
||||
"apps/web/app/services/auth/*",
|
||||
"apps/web/app/routes/verify.$id.tsx",
|
||||
"apps/web/app/routes/invitation.$id.tsx",
|
||||
"apps/web/app/routes/admin/accounts*",
|
||||
"apps/web/app/routes/app.$tenant/settings/*",
|
||||
"apps/web/app/modules/users",
|
||||
"apps/web/app/utils/services/apiService.ts",
|
||||
"apps/web/app/utils/services/authService.ts",
|
||||
"apps/web/app/utils/services/rolesAndPermissionsService.ts",
|
||||
"packages/db/src/permissions-seed.server.ts"
|
||||
],
|
||||
"dependencies": [
|
||||
"transactional-mail"
|
||||
],
|
||||
"consumers": [
|
||||
"admin-app-shell",
|
||||
"billing",
|
||||
"rows-entities-runtime",
|
||||
"plugin-candidates"
|
||||
],
|
||||
"integration": {
|
||||
"ownership": "system-only",
|
||||
"surfaces": {
|
||||
"adminRoutes": [
|
||||
"apps/web/app/routes/admin/accounts*"
|
||||
],
|
||||
"tenantRoutes": [
|
||||
"apps/web/app/routes/app.$tenant/settings/*"
|
||||
],
|
||||
"publicRoutes": [
|
||||
"apps/web/app/routes/login.tsx",
|
||||
"apps/web/app/routes/register.tsx",
|
||||
"apps/web/app/routes/forgot-password.tsx",
|
||||
"apps/web/app/routes/reset.tsx",
|
||||
"apps/web/app/routes/verify.$id.tsx",
|
||||
"apps/web/app/routes/invitation.$id.tsx"
|
||||
],
|
||||
"apiRoutes": [
|
||||
"apps/api/src/app.ts",
|
||||
"/v1/auth/login",
|
||||
"/v1/auth/refresh-token",
|
||||
"/v1/auth/logout",
|
||||
"/v1/session/current-user",
|
||||
"/v1/accounts",
|
||||
"/v1/accounts/:id",
|
||||
"/v1/workspaces/:tenantId/auth/providers",
|
||||
"/v1/workspaces/:tenantId/context/revalidate",
|
||||
"/v1/workspaces/:tenantId/invites",
|
||||
"/v1/workspaces/:tenantId/invites/:inviteId/accept",
|
||||
"/v1/workspaces/:tenantId/invites/:inviteId/revoke"
|
||||
]
|
||||
},
|
||||
"configuration": {
|
||||
"admin": [
|
||||
"Role and permission policy"
|
||||
],
|
||||
"tenant": [
|
||||
"Tenant membership and invitations"
|
||||
],
|
||||
"environment": [
|
||||
"CRYPTO_SECRET",
|
||||
"JWT_SECRET",
|
||||
"SESSION_SECRET",
|
||||
"API_ACCESS_TOKEN",
|
||||
"APP_BASE_DOMAIN",
|
||||
"WEB_APP_HOST",
|
||||
"ADMIN_APP_HOST",
|
||||
"APP_PROTOCOL"
|
||||
],
|
||||
"secrets": [
|
||||
"Session and auth secrets are environment-owned, never tenant-owned."
|
||||
]
|
||||
},
|
||||
"workers": {
|
||||
"required": false,
|
||||
"queues": [],
|
||||
"jobs": [],
|
||||
"notes": [
|
||||
"Auth flows may send email through transactional mail but do not own workers."
|
||||
]
|
||||
},
|
||||
"externalProviders": [],
|
||||
"permissions": [
|
||||
"admin.accounts.*",
|
||||
"admin.users.*",
|
||||
"app.settings.members.*"
|
||||
],
|
||||
"auditEvents": [
|
||||
"auth.login",
|
||||
"tenant.member.invited",
|
||||
"tenant.member.updated",
|
||||
"role.permission.updated"
|
||||
],
|
||||
"billingImpacts": [],
|
||||
"uat": [
|
||||
"User can register/login/reset password.",
|
||||
"Login, forgot-password, reset-password, and GitHub OAuth start/callback enforce CSRF or OAuth state and rate-limit policy.",
|
||||
"Service-token validation uses a timing-safe comparison and rejects mismatched tenant-scope overrides.",
|
||||
"Admin can manage accounts/users.",
|
||||
"Tenant membership scoping is enforced for regular users.",
|
||||
"Operator admins can inspect any active tenant space without explicit tenant membership."
|
||||
]
|
||||
},
|
||||
"boundaries": {
|
||||
"mustKeep": [
|
||||
"Login, registration, password reset, verification, and invitations",
|
||||
"Tenant membership and tenant-aware authorization",
|
||||
"Roles and permissions needed by app and admin surfaces",
|
||||
"Operator-admin tenant inspection bypass at server-side access boundaries only"
|
||||
],
|
||||
"mayMoveToPlugin": [
|
||||
"Advanced account CRM enrichment",
|
||||
"Optional feature-flagged role management enhancements"
|
||||
],
|
||||
"mustNotTouch": [
|
||||
"Route implementations during manifest Phase 1",
|
||||
"Sidebar/navigation ownership during parallel work"
|
||||
]
|
||||
},
|
||||
"pruning": {
|
||||
"phase": "1",
|
||||
"action": "keep",
|
||||
"notes": [
|
||||
"Treat auth-tenancy as a blocking dependency for most other manifests."
|
||||
]
|
||||
},
|
||||
"validation": {
|
||||
"source": [
|
||||
"docs/feature-inventory.md"
|
||||
],
|
||||
"lastReviewed": "2026-05-16"
|
||||
}
|
||||
}
|
||||
@@ -1,130 +0,0 @@
|
||||
{
|
||||
"schemaVersion": "1.0",
|
||||
"id": "billing",
|
||||
"title": "Billing and Subscriptions",
|
||||
"classification": "core",
|
||||
"status": "proposed",
|
||||
"owner": "core-pruning",
|
||||
"description": "Minimal Lago-backed subscription, Mollie payment, pricing settings, subscription settings, and webhook handling.",
|
||||
"rationale": [
|
||||
"A SaaS boilerplate usually needs billing as a default capability.",
|
||||
"The retained surface should be minimal and separate from marketing pricing presentation."
|
||||
],
|
||||
"codeAreas": [
|
||||
"apps/web/app/routes/subscribe.$tenant*",
|
||||
"apps/web/app/routes/app.$tenant/settings/subscription.tsx",
|
||||
"apps/web/app/routes/admin/settings/pricing*",
|
||||
"apps/api/src/app.ts",
|
||||
"/v1/billing/mollie/webhooks",
|
||||
"apps/web/app/application/pricing (admin billing-plan metadata, not public marketing pricing)",
|
||||
"apps/web/app/components/core/pricing (admin billing-plan configuration)",
|
||||
"apps/web/app/components/core/settings/subscription",
|
||||
"lago",
|
||||
"mollie"
|
||||
],
|
||||
"dependencies": [
|
||||
"auth-tenancy",
|
||||
"transactional-mail"
|
||||
],
|
||||
"consumers": [
|
||||
"core",
|
||||
"admin-app-shell"
|
||||
],
|
||||
"integration": {
|
||||
"ownership": "hybrid",
|
||||
"surfaces": {
|
||||
"adminRoutes": [
|
||||
"apps/web/app/routes/admin/settings/pricing*"
|
||||
],
|
||||
"tenantRoutes": [
|
||||
"apps/web/app/routes/app.$tenant/settings/subscription.tsx",
|
||||
"apps/web/app/routes/subscribe.$tenant*"
|
||||
],
|
||||
"publicRoutes": [],
|
||||
"apiRoutes": [
|
||||
"apps/api/src/app.ts",
|
||||
"/v1/billing/mollie/webhooks"
|
||||
]
|
||||
},
|
||||
"configuration": {
|
||||
"admin": [
|
||||
"Plans, prices, billing policy"
|
||||
],
|
||||
"tenant": [
|
||||
"Subscription selection and billing portal actions"
|
||||
],
|
||||
"environment": [
|
||||
"LAGO_API_URL",
|
||||
"LAGO_API_KEY",
|
||||
"LAGO_WEBHOOK_SECRET",
|
||||
"LAGO_TIMEOUT_MS",
|
||||
"MOLLIE_API_KEY",
|
||||
"MOLLIE_PROFILE_ID",
|
||||
"MOLLIE_TIMEOUT_MS"
|
||||
],
|
||||
"secrets": [
|
||||
"Lago and Mollie keys are platform/admin-owned, never tenant-owned."
|
||||
]
|
||||
},
|
||||
"workers": {
|
||||
"required": false,
|
||||
"queues": [],
|
||||
"jobs": [],
|
||||
"notes": [
|
||||
"Webhook handling is request-driven unless later converted to queue processing."
|
||||
]
|
||||
},
|
||||
"externalProviders": [
|
||||
"lago",
|
||||
"mollie"
|
||||
],
|
||||
"permissions": [
|
||||
"admin.pricing.*",
|
||||
"app.settings.subscription.*"
|
||||
],
|
||||
"auditEvents": [
|
||||
"billing.plan.updated",
|
||||
"billing.subscription.updated",
|
||||
"billing.webhook.received"
|
||||
],
|
||||
"billingImpacts": [
|
||||
"Owns subscription and pricing foundation."
|
||||
],
|
||||
"uat": [
|
||||
"Admin can configure pricing.",
|
||||
"Tenant can view/update subscription.",
|
||||
"Mollie webhook updates payment state and HiveGrid billing status.",
|
||||
"Lago remains the billing source for customers, plans, subscriptions, and invoices."
|
||||
]
|
||||
},
|
||||
"boundaries": {
|
||||
"mustKeep": [
|
||||
"Lago subscription and invoice foundation",
|
||||
"Mollie payment webhook foundation",
|
||||
"Admin pricing configuration",
|
||||
"Tenant subscription settings"
|
||||
],
|
||||
"mayMoveToPlugin": [
|
||||
"Portal-oriented pricing flows not required by the app shell",
|
||||
"Provider-specific billing extensions beyond Lago/Mollie",
|
||||
"Advanced billing analytics beyond subscription state"
|
||||
],
|
||||
"mustNotTouch": [
|
||||
"Tenant subscription checkout and success routes",
|
||||
"Navigation changes owned by parallel workers"
|
||||
]
|
||||
},
|
||||
"pruning": {
|
||||
"phase": "1",
|
||||
"action": "keep",
|
||||
"notes": [
|
||||
"Keep billing as core. Public marketing pricing was pruned; admin pricing and tenant subscription flows remain."
|
||||
]
|
||||
},
|
||||
"validation": {
|
||||
"source": [
|
||||
"docs/feature-inventory.md"
|
||||
],
|
||||
"lastReviewed": "2026-05-05"
|
||||
}
|
||||
}
|
||||
@@ -1,160 +0,0 @@
|
||||
{
|
||||
"schemaVersion": "1.0",
|
||||
"id": "core",
|
||||
"title": "Minimal Boilerplate Core",
|
||||
"classification": "core",
|
||||
"status": "proposed",
|
||||
"owner": "core-pruning",
|
||||
"description": "Umbrella manifest for features that remain in the default HiveGrid runtime after pruning.",
|
||||
"rationale": [
|
||||
"The boilerplate must support authenticated SaaS operation without marketing, CRM, AI, or support-product assumptions.",
|
||||
"Core should preserve web app and admin shells, auth, tenant membership, database/runtime primitives, transactional email, and minimal billing."
|
||||
],
|
||||
"codeAreas": [
|
||||
"apps/web/app/routes/login.tsx",
|
||||
"apps/web/app/routes/register.tsx",
|
||||
"apps/web/app/routes/app.$tenant*",
|
||||
"apps/web/app/routes/admin*",
|
||||
"apps/web/app/modules/users",
|
||||
"apps/web/app/modules/rows",
|
||||
"packages/db",
|
||||
"server/server.ts",
|
||||
"prisma",
|
||||
"prisma/migrations/20260527035000_04_api_key_log_tenant_scope",
|
||||
"prisma/migrations/20260527035500_04_runtime_query_indexes",
|
||||
"prisma/migrations/20260528090400_outbox_done_retention_index",
|
||||
"apps/web/app/modules/emails",
|
||||
"packages/mail",
|
||||
"scripts/verify-source-health.mjs",
|
||||
"scripts/verify-route-inventory.mjs",
|
||||
"scripts/verify-bundle-size.mjs",
|
||||
"apps/web/app/application/pricing",
|
||||
"apps/web/app/components/core/pricing",
|
||||
"packages/entitlements/src/blueprints.ts",
|
||||
"packages/entitlements/src/product-access.ts"
|
||||
],
|
||||
"dependencies": [
|
||||
"auth-tenancy",
|
||||
"rows-entities-runtime",
|
||||
"billing",
|
||||
"transactional-mail",
|
||||
"admin-app-shell",
|
||||
"product-core"
|
||||
],
|
||||
"consumers": [
|
||||
"plugin-candidates",
|
||||
"remove-candidates"
|
||||
],
|
||||
"integration": {
|
||||
"ownership": "system-only",
|
||||
"surfaces": {
|
||||
"adminRoutes": [
|
||||
"apps/web/app/routes/admin*"
|
||||
],
|
||||
"tenantRoutes": [
|
||||
"apps/web/app/routes/app.$tenant*"
|
||||
],
|
||||
"publicRoutes": [
|
||||
"apps/web/app/routes/login.tsx",
|
||||
"apps/web/app/routes/register.tsx"
|
||||
],
|
||||
"apiRoutes": [
|
||||
"apps/api/src/app.ts",
|
||||
"apps/api/src/routes/*.ts",
|
||||
"/healthz",
|
||||
"/readyz",
|
||||
"/v1/health",
|
||||
"/v1/openapi.json",
|
||||
"/v1/docs",
|
||||
"/v1/api-keys/validate",
|
||||
"/v1/usage"
|
||||
]
|
||||
},
|
||||
"configuration": {
|
||||
"admin": [
|
||||
"Platform defaults required by retained core features"
|
||||
],
|
||||
"tenant": [
|
||||
"Tenant settings required by retained app flows"
|
||||
],
|
||||
"environment": [
|
||||
"DATABASE_URL",
|
||||
"SESSION_SECRET",
|
||||
"APP_BASE_DOMAIN",
|
||||
"WEB_APP_HOST",
|
||||
"ADMIN_APP_HOST",
|
||||
"API_HOST",
|
||||
"APP_PROTOCOL"
|
||||
],
|
||||
"secrets": [
|
||||
"Core platform secrets are deployment-owned."
|
||||
]
|
||||
},
|
||||
"workers": {
|
||||
"required": false,
|
||||
"queues": [],
|
||||
"jobs": [
|
||||
"cleanup.run:outbox-done-retention",
|
||||
"cleanup.run:workflow-execution-stalled-reconcile"
|
||||
],
|
||||
"notes": [
|
||||
"Core stays worker-optional locally; staging/production worker-general owns outbox dispatch, DONE-row retention, and conservative repair of queued manual/API workflow executions whose initial outbox dispatch failed."
|
||||
]
|
||||
},
|
||||
"externalProviders": [],
|
||||
"permissions": [
|
||||
"admin.*",
|
||||
"app.*"
|
||||
],
|
||||
"auditEvents": [
|
||||
"core.configuration.updated"
|
||||
],
|
||||
"billingImpacts": [
|
||||
"Depends on billing manifest for subscription behavior."
|
||||
],
|
||||
"uat": [
|
||||
"A new project can run auth, tenant shell, admin shell, database, mail, billing, and the CRM SaaS Product Core blueprint.",
|
||||
"The local scaffold CLI can generate core, saas, and full workspace profiles without copying secrets or build artifacts.",
|
||||
"The Node web runtime emits baseline security headers, including CSP frame-ancestor/object restrictions and HTTPS HSTS.",
|
||||
"Source-health and route-inventory gates keep the API composition file and web route growth within reviewed budgets."
|
||||
]
|
||||
},
|
||||
"boundaries": {
|
||||
"mustKeep": [
|
||||
"Authentication and account recovery",
|
||||
"Tenant membership and role/permission enforcement",
|
||||
"Tenant app shell and admin shell",
|
||||
"Prisma-backed persistence foundation",
|
||||
"Transactional email required by auth and tenant operations",
|
||||
"Minimal subscription and pricing foundation"
|
||||
],
|
||||
"mayMoveToPlugin": [
|
||||
"Product-specific admin dashboards",
|
||||
"Advanced entity builder UI",
|
||||
"Provider-specific adapters beyond the selected defaults"
|
||||
],
|
||||
"mustNotTouch": [
|
||||
"Application routes and navigation during manifest Phase 1",
|
||||
"Chatbot, affiliate, and marketing code owned by parallel workers"
|
||||
]
|
||||
},
|
||||
"pruning": {
|
||||
"phase": "1",
|
||||
"action": "keep",
|
||||
"notes": [
|
||||
"This manifest defines the target default surface, not an implementation change.",
|
||||
"Use the child manifests for more precise dependency and boundary checks."
|
||||
]
|
||||
},
|
||||
"validation": {
|
||||
"source": [
|
||||
"docs/feature-inventory.md",
|
||||
"docs/architecture-migration-status.md",
|
||||
"prisma/schema/core.prisma",
|
||||
"prisma/schema/outbox.prisma",
|
||||
"prisma/schema/plugins.prisma",
|
||||
"prisma/schema/ai.prisma"
|
||||
],
|
||||
"lastReviewed": "2026-05-29"
|
||||
}
|
||||
}
|
||||
-344
@@ -1,344 +0,0 @@
|
||||
{
|
||||
"schemaVersion": "1.0",
|
||||
"id": "plugin-candidates",
|
||||
"title": "Plugin Candidate Feature Groups",
|
||||
"classification": "plugin-candidate",
|
||||
"status": "review-needed",
|
||||
"owner": "core-pruning",
|
||||
"description": "Feature groups with explicit extraction boundaries for future optional plugins or separately installable modules. Some are currently active in the versioned Product Core CRM SaaS showcase.",
|
||||
"rationale": [
|
||||
"These features are useful in some products but add product opinion, dependencies, or operational complexity beyond the neutral core.",
|
||||
"A feature can be active in product-core today and still remain a plugin-candidate when the intended next boundary is optional extraction rather than deletion.",
|
||||
"Extraction should happen after core dependency boundaries are verified.",
|
||||
"Email Marketing remains a CRM-contact campaign plugin candidate; Email Sequences are documented separately as foundation/admin-preview work with production delivery follow-ups, and marketing-outbound is only a general handler foundation until worker bootstrap is added."
|
||||
],
|
||||
"codeAreas": [
|
||||
"apps/web/app/modules/crm",
|
||||
"apps/web/app/modules/emailMarketing",
|
||||
"apps/web/app/modules/workflowEngine",
|
||||
"apps/web/app/modules/knowledgeBase",
|
||||
"apps/web/app/modules/portals",
|
||||
"apps/web/app/modules/sites",
|
||||
"apps/web/app/modules/analytics",
|
||||
"apps/web/app/modules/metrics",
|
||||
"apps/web/app/modules/events",
|
||||
"apps/web/app/modules/ai",
|
||||
"apps/web/app/modules/chatbot",
|
||||
"apps/web/app/modules/helpDesk",
|
||||
"apps/web/app/modules/onboarding",
|
||||
"apps/web/app/modules/featureFlags",
|
||||
"apps/web/app/modules/widgets",
|
||||
"apps/web/app/modules/notifications",
|
||||
"apps/web/app/modules/storage"
|
||||
],
|
||||
"dependencies": [
|
||||
"core",
|
||||
"auth-tenancy",
|
||||
"rows-entities-runtime",
|
||||
"transactional-mail",
|
||||
"admin-app-shell"
|
||||
],
|
||||
"consumers": [],
|
||||
"components": [
|
||||
{
|
||||
"id": "crm",
|
||||
"title": "CRM",
|
||||
"rationale": "Strong vertical opinion coupled to default company/contact/opportunity entities and email marketing.",
|
||||
"codeAreas": [
|
||||
"apps/web/app/modules/crm",
|
||||
"apps/web/app/routes/admin/crm*",
|
||||
"apps/web/app/routes/app.$tenant/crm*"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "email-marketing",
|
||||
"title": "Email Marketing and Newsletter",
|
||||
"rationale": "Email Marketing is an extract-plugin CRM-contact campaign plugin candidate, not Core and not the Email Sequences foundation: campaigns, sender secrets, CRM-contact audience selection, tracking, and consent are product-specific. Current audiences depend on CRM contacts, so extraction must bundle CRM, declare a CRM plugin dependency, or introduce a plugin-owned audience/list abstraction while keeping transactional mail and the separate email-sequences admin-preview foundation separate.",
|
||||
"codeAreas": [
|
||||
"apps/web/app/modules/emailMarketing",
|
||||
"apps/web/app/modules/emailMarketing/db/emailSender.ts",
|
||||
"apps/web/app/modules/emailMarketing/db/campaigns.db.server.ts",
|
||||
"apps/web/app/modules/emailMarketing/db/outboundEmails.db.server.ts",
|
||||
"apps/web/app/routes/admin/email-marketing*",
|
||||
"apps/web/app/routes/app.$tenant/email-marketing*",
|
||||
"prisma/schema/email.prisma"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "portals-sites",
|
||||
"title": "Portals and Sites",
|
||||
"rationale": "D007 canonical report: docs/feature-decisions/portals-sites-decision-report.md. Action: extract-plugin. Product-platform tenant/admin surfaces with Legacy-Provider portal billing, analytics, domains, and module-owned persistence that should not remain default Boilerplate Core.",
|
||||
"codeAreas": [
|
||||
"apps/web/app/modules/portals",
|
||||
"apps/web/app/modules/sites",
|
||||
"apps/web/app/routes/app.$tenant/__portals/*",
|
||||
"apps/web/app/routes/app.$tenant/sites/*",
|
||||
"prisma/schema/portals.prisma",
|
||||
"prisma/schema/sites.prisma"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "knowledge-base",
|
||||
"title": "Knowledge Base",
|
||||
"rationale": "D009 canonical report: docs/feature-decisions/kb-widgets-workflow-marketing-decision-report.md. Action: extract-plugin. Support/docs product surface with public docs visibility and data boundaries, not a minimum SaaS boilerplate requirement.",
|
||||
"codeAreas": [
|
||||
"apps/web/app/modules/knowledgeBase",
|
||||
"apps/web/app/routes/docs/*",
|
||||
"apps/web/app/routes/admin/knowledge-base*",
|
||||
"apps/web/app/routes/help/*",
|
||||
"prisma/schema/knowledgeBase.prisma"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "analytics-metrics",
|
||||
"title": "Analytics and Metrics",
|
||||
"rationale": "Product analytics UI and collection should be opt-in; minimal observability can remain separate.",
|
||||
"codeAreas": [
|
||||
"apps/web/app/modules/analytics",
|
||||
"apps/web/app/modules/metrics",
|
||||
"apps/api/src/app.ts",
|
||||
"/v1/analytics/*"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "events-webhooks-audit",
|
||||
"title": "Events, Webhooks, Audit Trails",
|
||||
"rationale": "Domain events may be useful for integrations, while browsers and entity webhooks can be optional.",
|
||||
"codeAreas": [
|
||||
"apps/web/app/modules/events",
|
||||
"apps/web/app/modules/events/services/.server/EventsService.ts",
|
||||
"packages/db/src/outbox.ts",
|
||||
"apps/web/app/routes/admin/events*",
|
||||
"apps/web/app/routes/admin/audit-trails.tsx",
|
||||
"apps/api/src/app.ts",
|
||||
"/v1/events/webhooks/attempts/:id"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "ai-chatbot-prompt-mcp",
|
||||
"title": "AI, Chatbot, Prompt Builder, MCP",
|
||||
"rationale": "Provider cost, security, and product behavior make this a plugin surface.",
|
||||
"codeAreas": [
|
||||
"apps/web/app/modules/ai",
|
||||
"apps/web/app/modules/chatbot",
|
||||
"apps/web/app/modules/promptBuilder",
|
||||
"apps/web/app/modules/mcp",
|
||||
"apps/web/app/routes/admin/ai/*",
|
||||
"apps/web/app/routes/admin/chat/*",
|
||||
"apps/web/app/routes/app.$tenant/chat/*",
|
||||
"apps/api/src/app.ts",
|
||||
"/v1/ai/upload"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "help-desk",
|
||||
"title": "Help Desk",
|
||||
"rationale": "Support-product surface that should couple to optional KB and ticket modules.",
|
||||
"codeAreas": [
|
||||
"apps/web/app/modules/helpDesk",
|
||||
"apps/web/app/routes/admin/help-desk*"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "onboarding-builder",
|
||||
"title": "Onboarding Builder",
|
||||
"rationale": "Useful for some SaaS products but not part of the minimum boilerplate.",
|
||||
"codeAreas": [
|
||||
"apps/web/app/modules/onboarding",
|
||||
"apps/web/app/routes/onboarding.$id.tsx"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "feature-flags",
|
||||
"title": "Feature Flags",
|
||||
"rationale": "Advanced admin capability that should be reviewed as plugin or core only if needed by retained flows.",
|
||||
"codeAreas": [
|
||||
"apps/web/app/modules/featureFlags",
|
||||
"apps/web/app/routes/admin/feature-flags*"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "widgets",
|
||||
"title": "Widgets",
|
||||
"rationale": "Embedded widgets are product-specific and should be optional.",
|
||||
"codeAreas": [
|
||||
"apps/web/app/modules/widgets",
|
||||
"apps/web/app/routes/app.$tenant/__widgets/*",
|
||||
"apps/api/src/app.ts",
|
||||
"packages/db/src/widgets.server.ts"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "workflow-engine",
|
||||
"title": "Workflow Engine",
|
||||
"rationale": "D009 canonical report: docs/feature-decisions/kb-widgets-workflow-marketing-decision-report.md. Action: extract-plugin. Automation/workflow orchestration is a product-specific capability layered on core events, not a minimum SaaS boilerplate requirement.",
|
||||
"codeAreas": [
|
||||
"apps/web/app/modules/workflowEngine",
|
||||
"apps/web/app/routes/app.$tenant/__workflows/*",
|
||||
"apps/web/app/routes/internal/api/__workflows/*",
|
||||
"prisma/schema/workflows.prisma"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "notifications",
|
||||
"title": "Notifications",
|
||||
"rationale": "Notification admin surfaces are optional; product delivery uses the internal queue and database diagnostics.",
|
||||
"codeAreas": [
|
||||
"apps/web/app/modules/notifications",
|
||||
"apps/web/app/routes/admin/notifications*",
|
||||
"packages/db/src/notifications.server.ts",
|
||||
"apps/worker/src/handlers.ts",
|
||||
"apps/api/src/app.ts",
|
||||
"/v1/notifications/stream"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "storage-supabase",
|
||||
"title": "Storage and Supabase",
|
||||
"rationale": "File storage abstraction may be core, while Supabase provider integration should be optional.",
|
||||
"codeAreas": [
|
||||
"apps/web/app/modules/storage",
|
||||
"@supabase/*"
|
||||
]
|
||||
}
|
||||
],
|
||||
"integration": {
|
||||
"ownership": "hybrid",
|
||||
"surfaces": {
|
||||
"adminRoutes": [
|
||||
"apps/web/app/routes/admin/* optional module routes"
|
||||
],
|
||||
"tenantRoutes": [
|
||||
"apps/web/app/routes/app.$tenant/* optional module routes"
|
||||
],
|
||||
"publicRoutes": [
|
||||
"optional public plugin routes"
|
||||
],
|
||||
"apiRoutes": [
|
||||
"optional plugin API routes"
|
||||
]
|
||||
},
|
||||
"configuration": {
|
||||
"admin": [
|
||||
"Plugin enablement, provider credentials, global policy"
|
||||
],
|
||||
"tenant": [
|
||||
"Tenant-level plugin settings when enabled, rendered through the sandboxed PluginSettingsFrame contract with deny-by-default CSP and unexpected-navigation remounts",
|
||||
"Manifest-declared plugin settings UI hosted from ui.settings.entry through PluginSettingsFrame; PluginUserConfig persists only caller-owned per-user settings behind app.plugins.use; lifecycle, grants and tenant-wide configuration remain behind app.plugins.manage.",
|
||||
"Plugin capability-use audit trails remain an account audit surface and require app.settings.auditTrails.view instead of broad app.plugins.use.",
|
||||
"Plugin settings HTML and per-user setting values are size-budgeted server-side; secret-like, reserved, unsafe and over-budget keys/values must be dropped or rejected before reaching iframe state or persistence.",
|
||||
"Plugin settings iframe postMessage rejects and unexpected reloads create client-deduplicated, server-rate-limited plugin.settings_frame.violation audit events with redacted metadata only."
|
||||
],
|
||||
"environment": [
|
||||
"Plugin-specific environment variables only when installed"
|
||||
],
|
||||
"secrets": [
|
||||
"Plugin provider secrets must be admin/platform-owned unless explicitly tenant-owned."
|
||||
]
|
||||
},
|
||||
"workers": {
|
||||
"required": true,
|
||||
"queues": [
|
||||
"plugin-specific queues when needed",
|
||||
"outbox.workflow",
|
||||
"outbox.plugin-hook",
|
||||
"outbox.plugin-capability-use",
|
||||
"hivegrid.plugin-invoke"
|
||||
],
|
||||
"jobs": [
|
||||
"plugin-specific jobs when needed",
|
||||
"workflow-trigger fanout",
|
||||
"workflow execution request drain",
|
||||
"workflow definition hook fanout",
|
||||
"workflow.executed hook fanout",
|
||||
"plugin-hook fanout",
|
||||
"plugin capability-use audit receiver",
|
||||
"plugin invoke"
|
||||
],
|
||||
"notes": [
|
||||
"Each extracted plugin must declare whether it is worker-backed and which queue group owns its jobs.",
|
||||
"Email-sequence trigger/scheduler/producers are not plugin-candidate jobs in this manifest; they are tracked in docs/features/email-sequences.md as foundation/admin-preview work gated by MARKETING_SEQUENCES_ENABLED and remaining production follow-ups. Signed Mailjet bounce webhook ingestion is API-owned, not a plugin worker job.",
|
||||
"The generic marketing-outbound handler foundation is documented in docs/features/marketing-funnel.md and must not be inferred as bootstrapped plugin delivery until apps/worker/src/index.ts wires a general subscriber.",
|
||||
"Workflow trigger fanout producers should use the shared @hivegrid/queue outbox payload builder instead of hand-writing workflow.trigger.event envelopes.",
|
||||
"Manual workflow runs publish workflow.execution.requested through the transactional outbox before worker-general starts the existing execution via the signed internal bridge or native executor; queued waitForInput continuations can resume natively when that wait boundary is the only native preflight gap.",
|
||||
"Default outbox queue delivery must include receiver-level BullMQ attempts/backoff and deterministic jobId=outbox:<eventId> before marking the Postgres outbox row DONE, so transient subscriber failures are retried by the target queue and dispatcher redelivery does not create duplicate receiver jobs.",
|
||||
"Plugin capability-use batches are produced by worker-owned plugin invocation and drained by worker-general through outbox.plugin-capability-use; receiver inserts must be idempotent with duplicate row ids ignored on outbox redelivery.",
|
||||
"The worker-general runtime must pass through OUTBOX_DISPATCHER_ENABLED plus WORKFLOW_TRIGGER_OUTBOX_* and WORKFLOW_TRIGGER_EXECUTOR_* settings so outbox.workflow is either actively drained or fails startup in required mode; WORKFLOW_TRIGGER_OUTBOX_REQUIRED=true also requires the outbox dispatcher to start.",
|
||||
"WORKFLOW_TRIGGER_EXECUTOR_MODE=native is opt-in and currently supports credential-free safe core event/manual/if/switch/doNothing/log/iterator/variable/alertUser/httpRequest paths plus tenant-scoped rowGet/email blocks and single-boundary waitForInput continuation resumes. Native and hybrid preflight must reject $credentials.*, lookup $credentials, and #with $credentials references before block execution; the worker-native executor must not hydrate stored workflow credentials. Iterator blocks execute the loopNext edge once per array item with context.iterator and then continue through loopEnd. httpRequest uses the shared outbound HTTP guard, email publishes mail.transactional.send through the transactional outbox for worker-mail delivery, while unsupported blocks and arbitrary conditional edges outside if/switch/iterator must persist an errored execution and fail loud instead of falling back to HTTP.",
|
||||
"WorkflowExecution keeps query-shape indexes for tenant-scoped execution lists, workflow execution histories, and status/type filtered admin views while workflow runtime remains a plugin-candidate surface."
|
||||
]
|
||||
},
|
||||
"externalProviders": [
|
||||
"plugin-specific providers"
|
||||
],
|
||||
"permissions": [
|
||||
"admin.plugins.*",
|
||||
"app.plugins.*"
|
||||
],
|
||||
"auditEvents": [
|
||||
"plugin.enabled",
|
||||
"plugin.disabled",
|
||||
"plugin.auto_disabled",
|
||||
"plugin.capabilities.revoked",
|
||||
"plugin.configuration.updated",
|
||||
"plugin.invoke.completed",
|
||||
"plugin.invoke.failed",
|
||||
"plugin.invoke.host.log",
|
||||
"plugin.invoke.host.audit"
|
||||
],
|
||||
"billingImpacts": [
|
||||
"Plugins may introduce plan gates or usage meters and must declare them before implementation."
|
||||
],
|
||||
"uat": [
|
||||
"Extraction plan defines how the plugin can be disabled without breaking core.",
|
||||
"Extraction plan defines whether plugin surfaces disappear, redirect, or show unavailable states when disabled.",
|
||||
"Plugin dependencies are explicit.",
|
||||
"Capability grants require an explicit capability-review acknowledgement and a manifest/version/scope digest across UI and API entry points.",
|
||||
"Capability grant, revoke, enable, disable, and per-user settings mutations commit atomically with their audit outbox event so plugin authorization and configuration cannot be left half-applied.",
|
||||
"Settings UIs use the sandboxed iframe contract, deny frame navigation, remount after unexpected iframe loads, and persist only non-secret per-user configuration through the reviewed PluginUserConfig path.",
|
||||
"Settings iframe messages use the SDK-exported plugin.settings.* protocol contract, bind request identifiers and keys, and persistent per-user settings writes are rate-limited per tenant/user/plugin.",
|
||||
"Plugin manifests bound and deduplicate allowedHosts, capability names and hook entrypoints so grants and fanout remain reviewable.",
|
||||
"Plugin hook payloads have SDK-level exported types matching the runtime registry; examples use canonical entity/workflow payload fields so plugin authors do not rely on stale ad-hoc shapes. Terminal workflow execution hooks include optional nullable userId for actor-aware plugins while accepting legacy payloads without userId.",
|
||||
"Tenant-scoped service-path workflow definition create/update/delete and builder graph mutations emit metadata only: tenantId, workflowId, userId, status, appliesToAllTenants, update changedFields, and occurredAt; platform-scoped definitions and template-import flows remain out of scope unless routed through the reviewed workflow service path."
|
||||
],
|
||||
"runtime": [
|
||||
"Production install, grant, and enable paths must reject capabilities without reviewed host bindings; currently only log and audit are production-available plugin sandbox host capabilities.",
|
||||
"Worker plugin invocations must enforce current TenantPluginCapabilityGrant rows before loading binaries, consuming rate-limit budget, or entering the sandbox; manifest-declared capabilities alone are not sufficient runtime authorization.",
|
||||
"Plugin invocation verifies stored install metadata (Plugin.wasmSha256 and Plugin.signaturePublicKey) still matches the manifest before signature verification, capability checks, or sandbox entry.",
|
||||
"Plugin signatures cover the canonical manifest payload plus wasmSha256 through the shared @hivegrid/plugin-runtime signing helper so manifest capability, hook, or allowedHost changes require re-signing.",
|
||||
"Plugin invocation must run inside the worker-owned sandbox boundary with memory, host-fn fuel and PLUGIN_MAX_WALL_CLOCK_MS limits; true per-instruction fuel remains a Wasmtime/runtime-upgrade concern."
|
||||
]
|
||||
},
|
||||
"boundaries": {
|
||||
"mustKeep": [
|
||||
"Core dependencies these plugins rely on",
|
||||
"Data migrations required by retained core features until plugin extraction is implemented"
|
||||
],
|
||||
"mayMoveToPlugin": [
|
||||
"All listed component feature groups after dependency review",
|
||||
"Future portal/site-builder plugins may declare affiliate integrations explicitly, but none are active by default."
|
||||
],
|
||||
"mustNotTouch": [
|
||||
"Routes, navigation, chatbot code, and historical affiliate migrations unless an owning cleanup task explicitly scopes them"
|
||||
]
|
||||
},
|
||||
"pruning": {
|
||||
"phase": "1",
|
||||
"action": "extract-plugin",
|
||||
"notes": [
|
||||
"This manifest is a planning bundle. Individual plugin manifests can split out when a candidate is actively extracted.",
|
||||
"Do not remove shared runtime dependencies until consumers are audited."
|
||||
]
|
||||
},
|
||||
"validation": {
|
||||
"source": [
|
||||
"docs/feature-inventory.md",
|
||||
"docs/architecture-migration-status.md",
|
||||
"docs/feature-decisions/crm-decision-report.md",
|
||||
"docs/feature-decisions/email-marketing-decision-report.md",
|
||||
"docs/feature-decisions/portals-sites-decision-report.md",
|
||||
"docs/feature-decisions/kb-widgets-workflow-marketing-decision-report.md"
|
||||
],
|
||||
"lastReviewed": "2026-05-27"
|
||||
}
|
||||
}
|
||||
@@ -1,151 +0,0 @@
|
||||
{
|
||||
"schemaVersion": "1.0",
|
||||
"id": "product-core",
|
||||
"title": "Product Core CRM SaaS",
|
||||
"classification": "core",
|
||||
"status": "active",
|
||||
"owner": "product-core",
|
||||
"description": "Versioned Product Core contract for the default CRM SaaS showcase and retained product modules.",
|
||||
"rationale": [
|
||||
"The default product is a CRM SaaS rather than an empty minimal shell.",
|
||||
"Product modules are governed by versioned blueprints and entitlement gates instead of undocumented plugin-candidate assumptions.",
|
||||
"Runtime access must resolve through blueprint, plan, custom plan, tenant override, and tenant-owned role permissions."
|
||||
],
|
||||
"codeAreas": [
|
||||
"packages/entitlements/src/blueprints.ts",
|
||||
"packages/entitlements/src/product-access.ts",
|
||||
"packages/entitlements/src/plans.ts",
|
||||
"apps/web/app/modules/crm",
|
||||
"apps/web/app/modules/emailMarketing",
|
||||
"apps/web/app/modules/knowledgeBase",
|
||||
"apps/web/app/modules/helpDesk",
|
||||
"apps/web/app/modules/workflowEngine",
|
||||
"apps/web/app/modules/ai-gen",
|
||||
"apps/web/app/modules/mcp",
|
||||
"apps/web/app/modules/templates/defaultEntityTemplates.ts"
|
||||
],
|
||||
"dependencies": [
|
||||
"core",
|
||||
"auth-tenancy",
|
||||
"billing",
|
||||
"transactional-mail",
|
||||
"rows-entities-runtime"
|
||||
],
|
||||
"consumers": [
|
||||
"admin-app-shell",
|
||||
"billing"
|
||||
],
|
||||
"integration": {
|
||||
"ownership": "hybrid",
|
||||
"surfaces": {
|
||||
"adminRoutes": [
|
||||
"Admin Center remains the operator toolbox for Product Core configuration and diagnostics."
|
||||
],
|
||||
"tenantRoutes": [
|
||||
"Tenant CRM, support, KB, marketing, workflow and customization surfaces are enabled only through the CRM SaaS blueprint and entitlement decision."
|
||||
],
|
||||
"publicRoutes": [
|
||||
"Public Product Core surfaces are limited to documented knowledge-base reads and auth/billing entrypoints."
|
||||
],
|
||||
"apiRoutes": [
|
||||
"/v1/usage",
|
||||
"/v1/support/inbound-email",
|
||||
"Product Core API routes must evaluate blueprint and plan gates before tenant data access."
|
||||
]
|
||||
},
|
||||
"configuration": {
|
||||
"admin": [
|
||||
"Blueprint version selection, custom plans, tenant overrides, provider diagnostics and plan catalog."
|
||||
],
|
||||
"tenant": [
|
||||
"Tenant-owned role permissions, tenant toggles where the blueprint allows them, tenant workflow and KB settings."
|
||||
],
|
||||
"environment": [
|
||||
"APP_BASE_DOMAIN",
|
||||
"WEB_APP_HOST",
|
||||
"ADMIN_APP_HOST",
|
||||
"API_HOST",
|
||||
"BULLMQ_REDIS_URL",
|
||||
"CRYPTO_SECRET",
|
||||
"MAILJET_WEBHOOK_SECRET",
|
||||
"STORAGE_PROVIDER",
|
||||
"STORAGE_ENDPOINT",
|
||||
"STORAGE_REGION",
|
||||
"STORAGE_BUCKET",
|
||||
"STORAGE_ACCESS_KEY_ID",
|
||||
"STORAGE_SECRET_ACCESS_KEY",
|
||||
"STORAGE_LOCAL_ROOT"
|
||||
],
|
||||
"secrets": [
|
||||
"Provider credentials remain platform/admin-owned unless a blueprint explicitly declares tenant-owned credentials."
|
||||
]
|
||||
},
|
||||
"workers": {
|
||||
"required": false,
|
||||
"queues": [],
|
||||
"jobs": [],
|
||||
"notes": [
|
||||
"Product Core owns entitlement and blueprint access decisions, while workflow, AI, mail, and plugin runtime queue execution is owned by the corresponding feature manifests and worker groups.",
|
||||
"Workflow and AI jobs stay behind queue/worker boundaries when the corresponding blueprint and plan gates allow access.",
|
||||
"Workflow outbound HTTP blocks must use the shared server-side outbound request guard for URL validation, redirects, timeouts and response-size limits."
|
||||
]
|
||||
},
|
||||
"externalProviders": [
|
||||
"legacyProvider",
|
||||
"deployment-region-ai-provider",
|
||||
"s3-compatible-storage"
|
||||
],
|
||||
"permissions": [
|
||||
"app.dashboard.view",
|
||||
"app.settings.roles.set",
|
||||
"app.settings.apiKeys.create",
|
||||
"admin.pricing.*"
|
||||
],
|
||||
"auditEvents": [
|
||||
"product_core.blueprint.enabled",
|
||||
"product_core.tenant_override.updated",
|
||||
"product_core.access.denied"
|
||||
],
|
||||
"billingImpacts": [
|
||||
"Starter, Pro and Business plans expose strict CRM SaaS feature limits.",
|
||||
"Custom hidden plans and tenant overrides can change effective entitlement decisions without making the plan public."
|
||||
],
|
||||
"uat": [
|
||||
"Starter can use CRM basics, support tickets and KB reads but cannot use API, email marketing, workflow engine or MCP.",
|
||||
"Pro can use email marketing, imported lists, CRM-based lists, onboarding, API and AI credits but cannot use workflow engine or MCP.",
|
||||
"Business can use workflow engine, advanced builder, high import/export limits and tenant MCP only when the blueprint enables MCP.",
|
||||
"A tenant user without the required tenant-owned role permission is denied even when blueprint and plan allow the feature."
|
||||
]
|
||||
},
|
||||
"boundaries": {
|
||||
"mustKeep": [
|
||||
"Blueprint definitions are versioned code and manifest contracts.",
|
||||
"Entitlement decisions compose blueprint, plan, tenant override and tenant-owned role checks.",
|
||||
"Admin Center remains operator-owned for configuration and diagnostics."
|
||||
],
|
||||
"mayMoveToPlugin": [
|
||||
"Provider-specific implementation adapters can become plugins after Product Core gates remain intact."
|
||||
],
|
||||
"mustNotTouch": [
|
||||
"Client/UI code must not read secrets or bypass server/package boundaries.",
|
||||
"Worker-backed features must not run synchronously in UI request handlers."
|
||||
]
|
||||
},
|
||||
"pruning": {
|
||||
"phase": "product-core",
|
||||
"action": "keep",
|
||||
"notes": [
|
||||
"This manifest supersedes the earlier assumption that CRM SaaS product modules are merely plugin candidates for the default product.",
|
||||
"Forms, Surveys and Public Forms are excluded from Product Core and covered by the removal manifest."
|
||||
]
|
||||
},
|
||||
"validation": {
|
||||
"source": [
|
||||
"packages/entitlements/src/blueprints.ts",
|
||||
"packages/entitlements/src/product-access.ts",
|
||||
"docs/feature-manifests/core.json",
|
||||
"docs/feature-manifests/remove-candidates.json"
|
||||
],
|
||||
"lastReviewed": "2026-05-27"
|
||||
}
|
||||
}
|
||||
-159
@@ -1,159 +0,0 @@
|
||||
{
|
||||
"schemaVersion": "1.0",
|
||||
"id": "remove-candidates",
|
||||
"title": "Removal Candidate Feature Groups",
|
||||
"classification": "remove-candidate",
|
||||
"status": "review-needed",
|
||||
"owner": "core-pruning",
|
||||
"description": "Feature groups that should be removed from the default boilerplate or aggressively reviewed for deletion.",
|
||||
"rationale": [
|
||||
"These surfaces conflict with the plan to remove marketing/default demo product behavior from the boilerplate.",
|
||||
"Some entries are remnants or provider duplicates that should only survive as explicit adapters."
|
||||
],
|
||||
"codeAreas": [],
|
||||
"dependencies": [
|
||||
"core"
|
||||
],
|
||||
"consumers": [],
|
||||
"components": [
|
||||
{
|
||||
"id": "forms-surveys-public-forms",
|
||||
"title": "Forms, Surveys, and Public Forms",
|
||||
"rationale": "Product Core excludes Forms, Surveys, Public Forms, and form-based Help Desk surveys. They are removal targets for runtime, active schema, navigation, seeds, docs, and gates rather than default CRM SaaS capabilities.",
|
||||
"codeAreas": [
|
||||
"apps/web/app/modules/formBuilder",
|
||||
"apps/web/app/modules/surveys",
|
||||
"apps/web/app/routes/__forms/*",
|
||||
"apps/web/app/routes/admin/forms/*",
|
||||
"apps/web/app/routes/app.$tenant/settings/forms/*",
|
||||
"apps/web/app/routes/surveys/*",
|
||||
"apps/web/app/routes/admin/help-desk/surveys/*",
|
||||
"prisma/schema/formBuilder.prisma",
|
||||
"Survey models in prisma/schema/helpDesk.prisma"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "marketing-public-site-remnants",
|
||||
"title": "Marketing and Public Site Remnants",
|
||||
"rationale": "D009 canonical report: docs/feature-decisions/kb-widgets-workflow-marketing-decision-report.md. Action: remove-from-core. Marketing belongs in a separate project; only minimal legal/auth pages should remain in boilerplate.",
|
||||
"codeAreas": []
|
||||
},
|
||||
{
|
||||
"id": "blog-changelog-remnants",
|
||||
"title": "Blog and Changelog Remnants",
|
||||
"rationale": "D009 canonical report: docs/feature-decisions/kb-widgets-workflow-marketing-decision-report.md. Action: remove-from-core. Blog/changelog are marketing/content surfaces and not default boilerplate core.",
|
||||
"codeAreas": []
|
||||
},
|
||||
{
|
||||
"id": "playground-demo-debug",
|
||||
"title": "Playground, Demo, Debug Surfaces",
|
||||
"rationale": "Demo and debug surfaces are not production-ready default boilerplate features.",
|
||||
"codeAreas": []
|
||||
},
|
||||
{
|
||||
"id": "marketing-chatbot",
|
||||
"title": "Marketing Chatbot",
|
||||
"rationale": "D009 canonical report: docs/feature-decisions/kb-widgets-workflow-marketing-decision-report.md. Action: remove-from-core. Unauthenticated marketing chatbot conflicts with removing marketing from the default boilerplate.",
|
||||
"codeAreas": []
|
||||
},
|
||||
{
|
||||
"id": "source-product-copy-assets-fake-data",
|
||||
"title": "Source Product Copy, Assets, Fake Data",
|
||||
"rationale": "Whitelabel cleanup should remove source-product-specific copy, fake content, and logos.",
|
||||
"codeAreas": []
|
||||
},
|
||||
{
|
||||
"id": "heavy-visual-editor-dependency-review",
|
||||
"title": "Heavy Visual and Editor Dependency Review",
|
||||
"rationale": "Heavy editor and drag/drop dependencies should be reviewed after their owning feature surfaces are removed or extracted. Do not delete packages that are still imported by core/shared UI or plugin-candidate code.",
|
||||
"codeAreas": [
|
||||
"shared rich-text editor dependency set",
|
||||
"shared drag/drop dependency set",
|
||||
"syntax and math rendering dependency set"
|
||||
]
|
||||
}
|
||||
],
|
||||
"integration": {
|
||||
"ownership": "system-only",
|
||||
"surfaces": {
|
||||
"adminRoutes": [
|
||||
"routes marked for deletion or review"
|
||||
],
|
||||
"tenantRoutes": [
|
||||
"tenant routes marked for deletion or review"
|
||||
],
|
||||
"publicRoutes": [
|
||||
"public demo/marketing routes marked for deletion or review"
|
||||
],
|
||||
"apiRoutes": [
|
||||
"API routes marked for deletion or review"
|
||||
]
|
||||
},
|
||||
"configuration": {
|
||||
"admin": [],
|
||||
"tenant": [],
|
||||
"environment": [
|
||||
"Environment variables tied only to removed features should be removed after dependency audit."
|
||||
],
|
||||
"secrets": [
|
||||
"Secrets tied only to removed features should be removed after dependency audit."
|
||||
]
|
||||
},
|
||||
"workers": {
|
||||
"required": false,
|
||||
"queues": [],
|
||||
"jobs": [],
|
||||
"notes": [
|
||||
"Delete or extract worker jobs only after consumers are audited."
|
||||
]
|
||||
},
|
||||
"externalProviders": [
|
||||
"provider dependencies under removal review"
|
||||
],
|
||||
"permissions": [],
|
||||
"auditEvents": [
|
||||
"removed_feature.audit_retained_if_needed"
|
||||
],
|
||||
"billingImpacts": [
|
||||
"Removal must not delete billing dependencies used by core."
|
||||
],
|
||||
"uat": [
|
||||
"Removing a candidate does not break core auth, tenant shell, admin shell, billing, mail, or rows runtime."
|
||||
]
|
||||
},
|
||||
"boundaries": {
|
||||
"mustKeep": [
|
||||
"Any dependency still required by core manifests",
|
||||
"Legal/auth public pages if retained by the app shell"
|
||||
],
|
||||
"mayMoveToPlugin": [
|
||||
"Provider adapters for non-default mail vendors",
|
||||
"Demo fixtures useful for test-only packages"
|
||||
],
|
||||
"mustNotTouch": [
|
||||
"Historical affiliate migrations and unrelated chatbot, route, and navigation code during this cleanup phase",
|
||||
"Runtime code until the owning worker or implementation phase takes over"
|
||||
]
|
||||
},
|
||||
"pruning": {
|
||||
"phase": "1",
|
||||
"action": "remove",
|
||||
"notes": [
|
||||
"This manifest captures removal intent; T04 removed the orphan Affiliate icon while preserving historical migration evidence.",
|
||||
"Feature Decision/S06 remove-from-core pruning removed the orphan BlogApi stub; public row sharing at apps/web/app/routes/public/$entity.$id.tsx is now removed from active runtime.",
|
||||
"Feature Manifest/S05 adds pnpm run verify:removed-modules as the runtime scan gate for removed-module regressions.",
|
||||
"Product Core marks Forms, Surveys, Public Forms, and form-based Help Desk surveys as removal targets rather than plugin candidates.",
|
||||
"Fake content helpers and the demo admin entity row route were removed from the active source tree.",
|
||||
"Dependency cleanup must run after feature extraction/removal and live import audits to avoid deleting shared packages prematurely.",
|
||||
"Unused landing-particle runtime code and particle dependencies were removed from active source."
|
||||
]
|
||||
},
|
||||
"validation": {
|
||||
"source": [
|
||||
"docs/feature-inventory.md",
|
||||
"docs/architecture-migration-status.md",
|
||||
"docs/feature-decisions/kb-widgets-workflow-marketing-decision-report.md"
|
||||
],
|
||||
"lastReviewed": "2026-05-13"
|
||||
}
|
||||
}
|
||||
-137
@@ -1,137 +0,0 @@
|
||||
{
|
||||
"schemaVersion": "1.0",
|
||||
"id": "rows-entities-runtime",
|
||||
"title": "Rows and Entities Runtime",
|
||||
"classification": "mixed",
|
||||
"status": "review-needed",
|
||||
"owner": "core-pruning",
|
||||
"description": "REMOVED in R-P6B-β (AD-2, 2026-06-30): the generic entity-builder (Entity/Row/RowValue, modules/rows, utils/db/entities, the *Api.server entity layer, admin/entities + settings/entities routes, the /v1/entities + /v1/relationships API, codeGenerator + formulas, and entityBuilder.prisma) was deleted; HiveGrid fachentities are typed Prisma tables (CRM Kontakt etc.). This manifest is retained as a historical record. Prisma + packages/db remain core.",
|
||||
"rationale": [
|
||||
"Many features depend on Prisma, entities, and rows as data foundations.",
|
||||
"The runtime foundation is core, while no-code builders and code generation are candidates for extraction."
|
||||
],
|
||||
"codeAreas": [
|
||||
"packages/db",
|
||||
"prisma",
|
||||
"apps/web/app/modules/rows",
|
||||
"apps/web/app/utils/db/**",
|
||||
"apps/web/app/modules/templates/defaultEntityTemplates.ts",
|
||||
"apps/web/app/routes/admin/entities*",
|
||||
"apps/web/app/routes/app.$tenant/settings/entities*",
|
||||
"apps/api/src/app.ts",
|
||||
"/v1/entities/:entity",
|
||||
"/v1/entities/:entity/rows",
|
||||
"/v1/entities/:entity/rows/:rowId",
|
||||
"/v1/relationships",
|
||||
"/v1/relationships/:id",
|
||||
"/v1/exports/:exportJobId/download-url",
|
||||
"packages/exports/src",
|
||||
"apps/web/app/modules/codeGenerator",
|
||||
"apps/web/app/modules/formulas",
|
||||
"apps/web/app/modules/jsonProperties"
|
||||
],
|
||||
"dependencies": [
|
||||
"auth-tenancy"
|
||||
],
|
||||
"consumers": [
|
||||
"core",
|
||||
"billing",
|
||||
"plugin-candidates",
|
||||
"remove-candidates"
|
||||
],
|
||||
"integration": {
|
||||
"ownership": "system-only",
|
||||
"surfaces": {
|
||||
"adminRoutes": [
|
||||
"apps/web/app/routes/admin/entities*"
|
||||
],
|
||||
"tenantRoutes": [
|
||||
"apps/web/app/routes/app.$tenant/settings/entities*"
|
||||
],
|
||||
"publicRoutes": [],
|
||||
"apiRoutes": [
|
||||
"apps/api/src/app.ts",
|
||||
"/v1/entities/:entity",
|
||||
"/v1/entities/:entity/rows",
|
||||
"/v1/entities/:entity/rows/:rowId",
|
||||
"/v1/relationships",
|
||||
"/v1/relationships/:id",
|
||||
"/v1/exports/:exportJobId/download-url"
|
||||
]
|
||||
},
|
||||
"configuration": {
|
||||
"admin": [
|
||||
"Entity schema and runtime policy"
|
||||
],
|
||||
"tenant": [
|
||||
"Tenant row/entity usage where enabled"
|
||||
],
|
||||
"environment": [
|
||||
"DATABASE_URL"
|
||||
],
|
||||
"secrets": [
|
||||
"Database credentials are deployment-owned."
|
||||
]
|
||||
},
|
||||
"workers": {
|
||||
"required": false,
|
||||
"queues": [],
|
||||
"jobs": [],
|
||||
"notes": [
|
||||
"Rows runtime should not require workers unless a feature layer adds async processing."
|
||||
]
|
||||
},
|
||||
"externalProviders": [
|
||||
"database"
|
||||
],
|
||||
"permissions": [
|
||||
"admin.entities.*",
|
||||
"app.rows.*"
|
||||
],
|
||||
"auditEvents": [
|
||||
"entity.updated",
|
||||
"row.created",
|
||||
"row.updated",
|
||||
"row.deleted"
|
||||
],
|
||||
"billingImpacts": [
|
||||
"May support plan limits or usage meters owned by billing/plugin manifests."
|
||||
],
|
||||
"uat": [
|
||||
"Rows runtime supports retained app data flows.",
|
||||
"CSV and XLSX exports neutralize spreadsheet formula injection prefixes before artifact delivery.",
|
||||
"No-code builder surfaces can be separated from runtime."
|
||||
]
|
||||
},
|
||||
"boundaries": {
|
||||
"mustKeep": [
|
||||
"Prisma schema and database package foundation",
|
||||
"Rows runtime required by retained app data flows",
|
||||
"Entity data primitives used by core features"
|
||||
],
|
||||
"mayMoveToPlugin": [
|
||||
"No-code entity builder UI",
|
||||
"Code generator",
|
||||
"Formula and JSON property authoring surfaces",
|
||||
"Default CRM-oriented entity templates"
|
||||
],
|
||||
"mustNotTouch": [
|
||||
"Runtime routes or APIs during manifest Phase 1",
|
||||
"Route and navigation edits owned by parallel workers"
|
||||
]
|
||||
},
|
||||
"pruning": {
|
||||
"phase": "1",
|
||||
"action": "remove",
|
||||
"notes": [
|
||||
"DONE (R-P6B-β, 2026-06-30): generic entity-builder fully removed; fachentities are typed Prisma tables.",
|
||||
"Prisma + packages/db foundation retained as core."
|
||||
]
|
||||
},
|
||||
"validation": {
|
||||
"source": [
|
||||
"docs/feature-inventory.md"
|
||||
],
|
||||
"lastReviewed": "2026-06-30"
|
||||
}
|
||||
}
|
||||
@@ -1,292 +0,0 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://hivegrid.local/docs/feature-manifests/schema.json",
|
||||
"title": "HiveGrid Feature Manifest",
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
"schemaVersion",
|
||||
"id",
|
||||
"title",
|
||||
"classification",
|
||||
"status",
|
||||
"owner",
|
||||
"description",
|
||||
"rationale",
|
||||
"codeAreas",
|
||||
"dependencies",
|
||||
"consumers",
|
||||
"integration",
|
||||
"boundaries",
|
||||
"pruning",
|
||||
"validation"
|
||||
],
|
||||
"properties": {
|
||||
"schemaVersion": {
|
||||
"type": "string",
|
||||
"const": "1.0"
|
||||
},
|
||||
"id": {
|
||||
"type": "string",
|
||||
"pattern": "^[a-z0-9][a-z0-9-]*$"
|
||||
},
|
||||
"title": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
},
|
||||
"classification": {
|
||||
"type": "string",
|
||||
"enum": ["core", "plugin-candidate", "remove-candidate", "mixed"]
|
||||
},
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": ["active", "proposed", "review-needed"]
|
||||
},
|
||||
"owner": {
|
||||
"type": "string",
|
||||
"description": "Planning owner or broad ownership area, not a code owner assignment."
|
||||
},
|
||||
"description": {
|
||||
"type": "string"
|
||||
},
|
||||
"rationale": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"codeAreas": {
|
||||
"type": "array",
|
||||
"description": "Likely source locations. Paths may be globs or package/module names.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"dependencies": {
|
||||
"type": "array",
|
||||
"description": "Feature manifest IDs this feature needs to function.",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"pattern": "^[a-z0-9][a-z0-9-]*$"
|
||||
}
|
||||
},
|
||||
"consumers": {
|
||||
"type": "array",
|
||||
"description": "Feature manifest IDs or feature surfaces that depend on this one.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"components": {
|
||||
"type": "array",
|
||||
"description": "Optional list for bundle manifests such as plugin or removal candidates.",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["id", "title", "rationale", "codeAreas"],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"pattern": "^[a-z0-9][a-z0-9-]*$"
|
||||
},
|
||||
"title": {
|
||||
"type": "string"
|
||||
},
|
||||
"rationale": {
|
||||
"type": "string"
|
||||
},
|
||||
"codeAreas": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"notes": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"integration": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
"ownership",
|
||||
"surfaces",
|
||||
"configuration",
|
||||
"workers",
|
||||
"externalProviders",
|
||||
"permissions",
|
||||
"auditEvents",
|
||||
"billingImpacts",
|
||||
"uat"
|
||||
],
|
||||
"properties": {
|
||||
"ownership": {
|
||||
"type": "string",
|
||||
"enum": ["tenant-owned", "admin-managed", "hybrid", "system-only"]
|
||||
},
|
||||
"surfaces": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["adminRoutes", "tenantRoutes", "publicRoutes", "apiRoutes"],
|
||||
"properties": {
|
||||
"adminRoutes": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"tenantRoutes": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"publicRoutes": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"apiRoutes": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"configuration": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["admin", "tenant", "environment", "secrets"],
|
||||
"properties": {
|
||||
"admin": {
|
||||
"type": "array",
|
||||
"description": "Admin-owned settings, provider credentials, policy, and defaults.",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"tenant": {
|
||||
"type": "array",
|
||||
"description": "Tenant-owned settings visible or editable in tenant surfaces.",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"environment": {
|
||||
"type": "array",
|
||||
"description": "Required environment variables or deployment configuration.",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"secrets": {
|
||||
"type": "array",
|
||||
"description": "Secret values and where they are owned. Do not store secret values here.",
|
||||
"items": { "type": "string" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"workers": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["required", "queues", "jobs", "notes"],
|
||||
"properties": {
|
||||
"required": { "type": "boolean" },
|
||||
"queues": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"jobs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"notes": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"externalProviders": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"permissions": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"pattern": "^[a-z][A-Za-z0-9]*(\\.(?:[A-Za-z][A-Za-z0-9]*|\\*))+$"
|
||||
}
|
||||
},
|
||||
"auditEvents": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"
|
||||
}
|
||||
},
|
||||
"billingImpacts": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"uat": {
|
||||
"type": "array",
|
||||
"description": "Operator-verifiable acceptance checks for planning and implementation.",
|
||||
"items": { "type": "string" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"boundaries": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["mustKeep", "mayMoveToPlugin", "mustNotTouch"],
|
||||
"properties": {
|
||||
"mustKeep": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"mayMoveToPlugin": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"mustNotTouch": {
|
||||
"type": "array",
|
||||
"description": "Areas excluded from the current phase or known to be owned by parallel work.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"pruning": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["phase", "action", "notes"],
|
||||
"properties": {
|
||||
"phase": {
|
||||
"type": "string"
|
||||
},
|
||||
"action": {
|
||||
"type": "string",
|
||||
"enum": ["keep", "extract-plugin", "remove", "review"]
|
||||
},
|
||||
"notes": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"validation": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["source", "lastReviewed"],
|
||||
"properties": {
|
||||
"source": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"lastReviewed": {
|
||||
"type": "string",
|
||||
"format": "date"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
-123
@@ -1,123 +0,0 @@
|
||||
{
|
||||
"schemaVersion": "1.0",
|
||||
"id": "transactional-mail",
|
||||
"title": "Transactional Mail",
|
||||
"classification": "core",
|
||||
"status": "proposed",
|
||||
"owner": "core-pruning",
|
||||
"description": "System email required for authentication, invitations, account notifications, and billing operations.",
|
||||
"rationale": [
|
||||
"Password resets, invitations, and system notifications are core operational requirements.",
|
||||
"Newsletter, inbound, and marketing email should not be bundled with transactional mail."
|
||||
],
|
||||
"codeAreas": [
|
||||
"apps/web/app/modules/emails",
|
||||
"apps/web/app/application/emails",
|
||||
"apps/web/app/utils/services/emailService.ts",
|
||||
"apps/worker/src/jobs/workflow-trigger-native-executor.ts",
|
||||
"apps/worker/src/jobs/transactional-mail-outbox.ts",
|
||||
"apps/worker/src/jobs/transactional-mail-outbox-bootstrap.ts",
|
||||
"apps/worker/src/handlers.ts",
|
||||
"packages/queue",
|
||||
"packages/mail",
|
||||
"@hivegrid/mail"
|
||||
],
|
||||
"dependencies": [],
|
||||
"consumers": [
|
||||
"auth-tenancy",
|
||||
"billing",
|
||||
"workflow-engine",
|
||||
"plugin-candidates"
|
||||
],
|
||||
"integration": {
|
||||
"ownership": "system-only",
|
||||
"surfaces": {
|
||||
"adminRoutes": [],
|
||||
"tenantRoutes": [],
|
||||
"publicRoutes": [],
|
||||
"apiRoutes": []
|
||||
},
|
||||
"configuration": {
|
||||
"admin": [
|
||||
"Transactional mail templates and Mailjet settings"
|
||||
],
|
||||
"tenant": [],
|
||||
"environment": [
|
||||
"MAILJET_API_KEY",
|
||||
"MAILJET_FROM_EMAIL",
|
||||
"MAILJET_FROM_NAME",
|
||||
"MAILJET_WEBHOOK_SECRET",
|
||||
"MAILJET_SECRET_KEY",
|
||||
"TRANSACTIONAL_MAIL_OUTBOX_REQUIRED"
|
||||
],
|
||||
"secrets": [
|
||||
"Mail provider API keys are platform/admin-owned, never tenant-owned."
|
||||
]
|
||||
},
|
||||
"workers": {
|
||||
"required": true,
|
||||
"queues": [
|
||||
"outbox.mail",
|
||||
"hivegrid.email"
|
||||
],
|
||||
"jobs": [
|
||||
"mail.transactional.* outbox bridge",
|
||||
"workflow email block mail.transactional.send producer",
|
||||
"send-transactional-email"
|
||||
],
|
||||
"notes": [
|
||||
"Transactional mail must be drained by an operator-owned permanent Coolify worker-mail resource with WORKER_QUEUE_GROUP=mail in each deployed environment.",
|
||||
"Production worker-mail resources should set TRANSACTIONAL_MAIL_OUTBOX_REQUIRED=true so startup and /readyz fail when the outbox.mail bridge cannot subscribe.",
|
||||
"This manifest records the runtime requirement; it is not live-environment proof that any specific Coolify target currently has worker-mail deployed or healthy.",
|
||||
"Web and API containers either enqueue direct transactional mail jobs or publish mail.* outbox events; they must not be treated as mail consumers. The mail worker must run as a separate worker resource alongside worker-general, worker-import, worker-webhook, and worker-plugin.",
|
||||
"Worker-native workflow email blocks publish mail.transactional.send outbox events; worker-general handles workflow execution while worker-mail remains the only transactional mail consumer.",
|
||||
"Dependent manifests must declare any additional queue use beyond the core hivegrid.email send-transactional-email job."
|
||||
]
|
||||
},
|
||||
"externalProviders": [
|
||||
"mailjet"
|
||||
],
|
||||
"permissions": [
|
||||
"admin.emails.*"
|
||||
],
|
||||
"auditEvents": [
|
||||
"mail.template.updated",
|
||||
"mail.provider.updated"
|
||||
],
|
||||
"billingImpacts": [],
|
||||
"uat": [
|
||||
"Password reset, invitation, and verification emails can be sent through the selected provider."
|
||||
]
|
||||
},
|
||||
"boundaries": {
|
||||
"mustKeep": [
|
||||
"Password reset emails",
|
||||
"Invitation emails",
|
||||
"Verification and system emails required by core flows"
|
||||
],
|
||||
"mayMoveToPlugin": [
|
||||
"Email marketing and newsletter abstractions",
|
||||
"Inbound email handling",
|
||||
"Provider adapters beyond Mailjet"
|
||||
],
|
||||
"mustNotTouch": [
|
||||
"Chatbot or marketing email surfaces owned by parallel workers"
|
||||
]
|
||||
},
|
||||
"pruning": {
|
||||
"phase": "1",
|
||||
"action": "keep",
|
||||
"notes": [
|
||||
"Mailjet is the only transactional runtime provider.",
|
||||
"Removed legacy transactional adapters are not maintained as runtime adapters."
|
||||
]
|
||||
},
|
||||
"validation": {
|
||||
"source": [
|
||||
"docs/feature-inventory.md",
|
||||
"docs/ops/worker-queues.md",
|
||||
"docs/deployment.md"
|
||||
],
|
||||
"lastReviewed": "2026-05-28"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,148 @@
|
||||
# Team-Chat: v1-Produkt- und UX-Vertrag
|
||||
|
||||
**Stand:** 2026-07-15
|
||||
|
||||
**Ticket:** `AK-P15b` / HIVEGRID-45
|
||||
|
||||
**Architektur:** Bespoke WebSocket-Chat nach AD-9, kein Hocuspocus
|
||||
|
||||
Dieses Dokument konkretisiert die bereits beauftragten Chat-Funktionen als belastbaren Produktvertrag. Es
|
||||
trennt notwendige Ausführungsqualität von späteren Erweiterungen und verhindert, dass die Interim-UI einen
|
||||
technisch vollständigen, aber im Alltag hakeligen Chat verdeckt.
|
||||
|
||||
## 1. Produktprinzipien
|
||||
|
||||
1. **Sofort reagieren, serverseitig entscheiden.** Senden, Reactions und Pins erscheinen optimistisch. Die
|
||||
Datenbank bleibt autoritativ; Fehler bleiben am betroffenen Element sichtbar und können dort erneut versucht
|
||||
werden.
|
||||
2. **Kein Verlust und keine Duplikate.** Jeder Schreibvorgang besitzt vor dem ersten Versuch eine stabile
|
||||
Client-ID. Wiederholungen mit derselben ID liefern dasselbe Resultat.
|
||||
3. **Realtime ist ein Beschleuniger, nicht die Datenbank.** Redis verteilt Events; nach Reconnect werden Lücken
|
||||
per Cursor aus PostgreSQL geschlossen.
|
||||
4. **Ruhe beim Lesen.** Neue Nachrichten reißen Nutzer nicht ans Listenende. Wer hochgescrollt hat, sieht einen
|
||||
Hinweis mit Anzahl und Sprungaktion.
|
||||
5. **Mobile und Tastatur sind Primärpfade.** Alle Aktionen funktionieren per Touch, Tastatur und Screenreader.
|
||||
|
||||
## 2. Nachrichten- und Reconnect-Vertrag
|
||||
|
||||
### Optimistisches Senden
|
||||
|
||||
- UI-Zustände: `sending → sent` oder `sending → failed`. Einen erfundenen gerätebezogenen
|
||||
`delivered`-Zustand gibt es in v1 nicht.
|
||||
- `clientMessageId` wird vor dem ersten Versuch erzeugt und bei Retry wiederverwendet. Der Server hält
|
||||
`(tenantId, authorUserId, clientMessageId)` eindeutig und antwortet bei Wiederholung mit derselben Nachricht.
|
||||
- Die Local-Echo-Nachricht erscheint sofort mit dezentem Sendestatus. Server-Antwort und WebSocket-Echo werden
|
||||
gegen die Client-ID abgeglichen und dürfen weder doppelte Zeilen noch doppelte Reaktionen erzeugen.
|
||||
- Fehler entfernen den Text nicht. Direkt an der Nachricht stehen „Erneut versuchen" und „Verwerfen"; kein
|
||||
Toast-Spam. Automatischer Retry gilt nur für Timeout, `429` mit `Retry-After` und `5xx`, mit Backoff und Jitter.
|
||||
- Innerhalb eines Channels/Threads bleibt die Reihenfolge stabil; unabhängige Channels dürfen parallel senden.
|
||||
|
||||
### Verbindung und Gap-Fill
|
||||
|
||||
- Sichtbare Zustände: `connecting`, `online`, `reconnecting`, `offline`, `blocked`.
|
||||
- Nach Reconnect sendet der Client den letzten bestätigten Cursor und erhält verpasste persistente Events in
|
||||
stabiler Reihenfolge. Erst danach gilt die Verbindung als vollständig synchronisiert.
|
||||
- Presence, Typing und Transportstatus sind flüchtig und werden nicht als Chat-Historie gespeichert.
|
||||
- Queue-Grenzen und `WebSocket.bufferedAmount` werden überwacht, weil der klassische Browser-WebSocket keine
|
||||
Backpressure bereitstellt.
|
||||
- Vollständiges Offline-Senden über Reload oder Background Sync ist nicht Teil von v1. Entwürfe bleiben lokal
|
||||
erhalten; ein offline ausgelöster Send bleibt sichtbar fehlgeschlagen und kann nach Reconnect wiederholt
|
||||
werden.
|
||||
|
||||
## 3. Lesen, Scrollen und Entwürfe
|
||||
|
||||
- History wird cursorbasiert paginiert. Beim Nachladen älterer Nachrichten bleibt der visuelle Scroll-Anker
|
||||
stabil.
|
||||
- Automatisches Scrollen ans Ende erfolgt nur, wenn der Nutzer bereits am Ende ist oder selbst sendet. Sonst
|
||||
erscheint „N neue Nachrichten".
|
||||
- Read-Cursor sind monoton. Eine Nachricht wird nur als gelesen gewertet, wenn Channel und Dokument aktiv sind
|
||||
und die Nachricht sichtbar war; Updates werden gebündelt. Eigene Nachrichten erzeugen kein Unread.
|
||||
- Channel zeigen getrennt Gesamt-Unread und Mention-Marker. Mute unterdrückt Benachrichtigungen, aber niemals
|
||||
Unread; direkte User-Mentions und DMs umgehen Mute gemäß aktivem Chat-Vertrag (`AK-P15b`).
|
||||
- Der Composer speichert Textentwürfe debounced pro `Tenant + User + Channel` lokal und tenant-isoliert. Ein
|
||||
Entwurf wird erst nach erfolgreichem Server-Ack gelöscht. Datei-Binaries landen nicht im Local Storage.
|
||||
|
||||
## 4. Composer und Nachrichten-QoL
|
||||
|
||||
- `Enter` sendet, `Shift+Enter` erzeugt eine neue Zeile. Während IME-Composition darf `Enter` nicht senden.
|
||||
- Markdown bleibt auf den freigegebenen Umfang beschränkt und wird serverseitig sanitisiert.
|
||||
- Eigene Nachrichten können innerhalb von 24 Stunden editiert werden; Änderungen tragen einen
|
||||
„bearbeitet"-Marker. Löschen erzeugt einen Tombstone, damit Threads und Antworten verständlich bleiben.
|
||||
- Hover-Aktionen sind identisch per Fokus und Mobile-Long-Press erreichbar: Reaktion, Thread, Bearbeiten,
|
||||
Löschen, Pin und Als-Aufgabe-markieren gemäß Berechtigung.
|
||||
- Mentions verwenden eine zugängliche Combobox mit Pfeiltasten, `Enter` und `Escape`. Autocomplete und
|
||||
Benachrichtigung zeigen beziehungsweise adressieren nur Nutzer, die den Channel lesen dürfen.
|
||||
- Reactions werden optimistisch gesetzt und bei Fehler zurückgerollt. Gleiche Reaktion eines Users auf dieselbe
|
||||
Nachricht ist eindeutig.
|
||||
- Voice Notes sind einfache Audio-Anhänge mit Aufnahme-/Upload-Fortschritt, Dauer, Abspielen, Abbrechen und
|
||||
Retry. Es gibt kein Transkript und keine KI-Verarbeitung.
|
||||
- Uploads nutzen die bestehende Files-Pipeline inklusive AV-Prüfung. Bilder unterstützen Vorschau und
|
||||
verständlichen Alternativtext; Mobile bietet den direkten Kamera-Input.
|
||||
|
||||
## 5. Presence, Typing, Threads und Pins
|
||||
|
||||
- Typing startet erst nach echter Eingabe, wird gedrosselt, läuft nach kurzer TTL aus und endet bei Senden,
|
||||
Leeren, Channelwechsel oder Disconnect. Die UI zeigt höchstens zwei Namen plus „N weitere".
|
||||
- Presence wird aus aktiven Sessions abgeleitet und läuft über TTL aus; sie ist kein belastbarer
|
||||
Arbeitszeitnachweis.
|
||||
- Threads haben genau eine Ebene. Desktop nutzt ein Seitenpanel, Mobile eine eigene Detailansicht. Wer erstellt,
|
||||
antwortet oder erwähnt wird, folgt dem Thread automatisch.
|
||||
- Message-Pins sind in Group- und Projekt-Channels auf 50 begrenzt. Nach bestätigtem Produktentscheid gibt es
|
||||
in DMs keine Message-Pins. Der persönliche Channel-Pin bleibt ein getrenntes Modell.
|
||||
|
||||
## 6. Benachrichtigungen und bestätigte v1-Grenzen
|
||||
|
||||
- Mentions, DMs und Thread-Antworten laufen über `notify()` und öffnen per Deep Link die exakte Nachricht.
|
||||
- Der allgemeine Browser-Web-Push inklusive Permission-Prompt bleibt bei `VA-P27a`; Chat-v1 liefert In-App-
|
||||
Notifications und Deep Links.
|
||||
- Tenant-Admin-Audit liegt unter `/settings/chat/audit`. Eine kurzlebige Audit-Session verlangt einen Grund;
|
||||
jeder fremde Lesezugriff wird auditiert und DMs zeigen den Audit-Banner.
|
||||
- `FileEntityType` wird minimal um `chat_message` erweitert, damit Anhänge die bestehende `FileEntityLink`-
|
||||
Pipeline nutzen und kein paralleles Datei-System entsteht.
|
||||
|
||||
## 7. Accessibility und Mobile
|
||||
|
||||
- Die Nachrichtenliste ist ein benanntes `role="log"` ohne pauschales Live-Announcement. Separate,
|
||||
dosierte `aria-live="polite"`-Statusbereiche melden nur neue fremde Nachrichten; initial geladene Historie
|
||||
und eigene Local Echoes werden nicht doppelt angesagt.
|
||||
- Verbindungs- und Sendestatus verwenden einen separaten Statusbereich und nie nur Farbe.
|
||||
- Fokus bleibt nach Send im Composer; Drawer/Dialog geben Fokus kontrolliert zurück. Channel-, Message- und
|
||||
Picker-Listen sind vollständig per Tastatur bedienbar.
|
||||
- Mobile verwendet Master/Detail-Navigation, mindestens 44 Pixel große Touch-Ziele, Safe-Area am sticky
|
||||
Composer und behält Draft sowie Scrollposition beim Channelwechsel.
|
||||
|
||||
## 8. Wiederverwendung des HiveGrid-UI-Baukastens
|
||||
|
||||
| Fläche | Vorhandene Bausteine | Neuer chat-spezifischer Verbund |
|
||||
|---|---|---|
|
||||
| Shell | `SubframeAppShell`, `PageShell`, `SidebarInside`, `ResizablePanel` | `ChatWorkspace` |
|
||||
| Channel-Liste | `SearchInput`, `Avatar`, `BadgeFeedback`, `DropdownMenu`, `ContextMenu`, `Tooltip` | `ChatChannelRow` |
|
||||
| Verlauf | `Avatar`, `Button`, `IconButton`, `ContextMenu`, `ScrollArea`, `Skeleton` | `ChatMessageList`, `ChatMessageRow` |
|
||||
| Composer | `TextArea`, `IconButton`, `Progress`, `BannerOffline` | `ChatComposer`, `ChatAttachmentTray` |
|
||||
| Threads | `Drawer`, `Dialog`, `Accordion` | `ThreadDrawer` |
|
||||
| Mentions/Suche | `SearchInput`, `Command`, `Avatar` | `MentionAutocomplete`, `ChatSearchResults` |
|
||||
| States | `EmptyState`, `Alert`, `BannerOffline`, `Skeleton`, `LoadingIndicatorSkeleton` | nur Chat-Kompositionen |
|
||||
| Medien | `uploadFileInChunks`, `AudioOrVideoPlayer`, `Progress` | Voice-Note- und Attachment-Steuerung |
|
||||
|
||||
Die bestehenden visuellen Primitives werden direkt genutzt. Nicht wiederverwendet werden die rein visuellen,
|
||||
nicht interaktiven `FileUpload`-/`Combobox`-Attrappen und der für Chat zu schwere Legacy-Rich-Text-Editor.
|
||||
|
||||
## 9. Bewusst später
|
||||
|
||||
- persistente Offline-Outbox und Background Sync über Reload
|
||||
- Scheduled Messages, Erinnerungen und „Für später speichern"
|
||||
- gerätebezogener `delivered`-Status und Read-Receipt-Privacy-Schalter
|
||||
- Slack-Power-Shortcuts, frei konfigurierbares Sendeverhalten und Pop-out-Threads
|
||||
- server-/geräteübergreifend synchronisierte Drafts
|
||||
- GIF-/Sticker-Apps, Huddles, Audio-/Videoanrufe und KI-Transkription
|
||||
|
||||
## Research-Quellen
|
||||
|
||||
- [React `useOptimistic`](https://react.dev/reference/react/useOptimistic)
|
||||
- [Matrix Client-Server API: Transaction IDs, Local Echo, Receipts, Typing, Threads](https://spec.matrix.org/latest/client-server-api/)
|
||||
- [MDN WebSocket API und fehlende Backpressure](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
|
||||
- [Slack: Send, read and manage drafts](https://slack.com/help/articles/201457107-Send-and-read-messages)
|
||||
- [Slack: Threads](https://slack.com/help/articles/115000769927-Use-threads-to-organize-discussions)
|
||||
- [Slack: Keyboard navigation](https://slack.com/help/articles/115003340723-Navigate-Slack-with-your-keyboard)
|
||||
- [W3C ARIA23: `role=log`](https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA23)
|
||||
- [WAI-ARIA Combobox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)
|
||||
@@ -38,9 +38,13 @@ eventHash_n = HMAC-SHA-256(AUDIT_CHAIN_SECRET, eventHash_{n-1} || canonicalJSON(
|
||||
`canonicalJSON` is the JSON encoding produced by
|
||||
`canonicalizeAuditPayload` in
|
||||
`packages/db/src/audit-hash.ts`: object keys sorted recursively,
|
||||
`undefined` dropped, arrays preserve order. Without
|
||||
`AUDIT_CHAIN_SECRET` the helper falls back to plain SHA-256 — still
|
||||
tamper-evident for read-only attackers but trivially forgeable.
|
||||
`undefined` dropped, arrays preserve order. Production fails closed unless
|
||||
`AUDIT_CHAIN_SECRET` contains at least 32 UTF-8 bytes. Local development and
|
||||
tests may use the explicit SHA-256 fallback, but it is never an accepted
|
||||
production configuration. New `v2:` hashes bind the persisted event ID and
|
||||
creation timestamp; the verifier retains dual compatibility with unversioned
|
||||
legacy hashes. Concurrent writers serialize through a per-chain PostgreSQL
|
||||
advisory transaction lock and an HMAC-authenticated O(1) chain-head row.
|
||||
|
||||
`verifyAuditChain(events, { secret })` walks the chain oldest → newest
|
||||
and returns the first break with one of:
|
||||
@@ -116,15 +120,14 @@ join with `|`; JSON metadata is stringified.
|
||||
`apps/worker/src/jobs/audit-retention.ts` exposes `runAuditRetentionJob`
|
||||
which the worker host wires to a daily cron.
|
||||
|
||||
Plan-based defaults (`resolveAuditRetentionPolicy`):
|
||||
The retention window is fixed at ten calendar years for every tenant chain and
|
||||
the platform chain. Tenant discovery uses one aggregate query. Deletes run in
|
||||
bounded, keyset-ordered batches; before each batch is deleted, the same
|
||||
transaction writes an append-only HMAC-authenticated checkpoint that binds the
|
||||
last removed event hash and the previous checkpoint MAC. Verifiers and exports
|
||||
authenticate this checkpoint before accepting the retained suffix.
|
||||
|
||||
| Regulatory scope on tenant events | Retention |
|
||||
| --------------------------------- | --------- |
|
||||
| `soc2` or `hipaa` | 7 years |
|
||||
| `gdpr` | 6 years |
|
||||
| none | 1 year |
|
||||
|
||||
Every non-empty sweep emits a meta-audit (`audit.retention.swept`) so
|
||||
Every non-empty sweep emits a meta-audit (`audit.retention.pruned`) so
|
||||
the cleanup itself is traceable.
|
||||
|
||||
## Operator Procedures
|
||||
@@ -134,8 +137,8 @@ the cleanup itself is traceable.
|
||||
1. Generate a secret: `openssl rand -base64 32`.
|
||||
2. Set `AUDIT_CHAIN_SECRET=<value>` in Coolify (platform-wide, never
|
||||
per-tenant).
|
||||
3. Apply the Prisma migration
|
||||
`20260517180000_10_audit_event_compliance`.
|
||||
3. Apply the migration that creates `AuditChainHead` and
|
||||
`AuditChainCheckpoint` before deploying the new writers.
|
||||
|
||||
### Self-service export (tenant admin)
|
||||
|
||||
|
||||
@@ -0,0 +1,143 @@
|
||||
# Customer-Portal: aktueller Produkt- und UX-Stand
|
||||
|
||||
<!-- markdownlint-disable MD013 -->
|
||||
|
||||
- **Stand:** 2026-07-22
|
||||
- **Technische Tickets:** `VA-P26a`, `VA-P26b`, `VA-P26c` jeweils 100 %
|
||||
- **Design-Nachzug:** `VD-P26` bleibt offen
|
||||
- **Staging:** `https://staging-portal.hivegrid.de`
|
||||
- **Tenant-Administration:** `https://staging-app.hivegrid.de/<tenant>/settings/customer-portal`
|
||||
|
||||
Dieses Dokument beschreibt das aktuell ausgelieferte Customer-Portal aus Sicht von Workspace-Admins
|
||||
und externen PortalUsern. Der Betriebs-, Secret- und Rollout-Vertrag steht separat in
|
||||
[`docs/deploy/customer-portal.md`](../deploy/customer-portal.md).
|
||||
|
||||
## 1. Produktgrenze
|
||||
|
||||
Das Customer-Portal ist eine eigene, extern sichtbare Oberfläche. PortalUser sind strikt von internen
|
||||
HiveGrid-Nutzern getrennt und erhalten nur Zugriff auf ausdrücklich zugewiesene Projekte, sichtbare
|
||||
Projektphasen und freigegebene Dokumente. Fehlende Berechtigungen, fremde Projekte und unbekannte Hosts
|
||||
liefern 404, damit keine Existenz fremder Daten offengelegt wird.
|
||||
|
||||
Core und Portal laufen als getrennte Runtime-Ressourcen aus demselben unveränderlichen Web-Image. Das
|
||||
Portal besitzt eigene Sessions, eine minimal berechtigte Datenbankrolle und keine internen Admin-, OAuth-,
|
||||
Billing- oder Ingress-Zugangsdaten.
|
||||
|
||||
## 2. Endkunden-Navigation und Hauptreisen
|
||||
|
||||
Die Portaloberfläche verwendet dieselbe HiveGrid-Shell wie die SaaS: gleich große Wortmarke, einklappbare
|
||||
Sidebar, Sidebar-Inset, Breadcrumbs, Seitenkopf, Avatar und mobile Navigation. Die Hauptnavigation ist
|
||||
vollständig klickbar und bewusst auf wenige Ziele reduziert:
|
||||
|
||||
- **Übersicht:** eigene Projekte, aktueller Status und sinnvolle nächste Aktionen.
|
||||
- **Projekte:** Liste der freigegebenen Projekte mit Fortschritt und letztem Update.
|
||||
- **Projekt:** kompakte Detailansicht mit den Bereichen Übersicht, Dateien und Anliegen.
|
||||
- **Upload:** projektbezogener Multi-Datei-Upload mit den konfigurierten Anzahl- und Größenlimits.
|
||||
- **Einstellungen:** Benachrichtigungen, Profildaten, DSGVO-Export und Kontolöschung; der Einstieg liegt
|
||||
getrennt von den Arbeitszielen unten in der Sidebar.
|
||||
|
||||
Projektstatus wird als verständliche Abfolge sichtbarer Phasen dargestellt. Freigegebene Dateien können
|
||||
heruntergeladen werden. PortalUser können Dateien hochladen und Anliegen beziehungsweise Reklamationen
|
||||
melden, sofern ihr Projektzugang dies erlaubt. Ein eingefrorener Workspace bleibt lesbar, verhindert aber
|
||||
Schreibaktionen mit einem Klartext-Hinweis.
|
||||
|
||||
## 3. Zugang und Einladungen
|
||||
|
||||
Ein berechtigter Workspace-Admin kann PortalUser aus drei fachlichen Einstiegen einladen:
|
||||
|
||||
1. aus der Customer-Portal-Verwaltung,
|
||||
2. aus einem Kontakt,
|
||||
3. aus einem Projekt; dabei wird der Projektzugang atomar vergeben.
|
||||
|
||||
Die Einladung verwendet einen einmaligen, gehashten Setup-Token mit sieben Tagen Laufzeit. Nach
|
||||
Datenschutzannahme und optionaler Passwortvergabe entsteht eine eigene Portal-Session. Magic-Link ist der
|
||||
primäre Login-Pfad, Passwort der sekundäre. Replays, fremde Tenant-/Projektzuordnungen und doppelte
|
||||
Einladungszustände werden fail-closed abgewiesen.
|
||||
|
||||
## 4. Tenant-Administration
|
||||
|
||||
Die zentrale Verwaltung liegt unter `/<tenant>/settings/customer-portal`. Sichtbarkeit und Aktionen werden
|
||||
über `portal.read`, `portal.manage_users`, `portal.manage_access`, `portal.activity.*`,
|
||||
`portal.delete_user` und `portal.admin` begrenzt.
|
||||
|
||||
Je nach Berechtigung kann der Workspace-Admin:
|
||||
|
||||
- Portal veröffentlichen oder einfrieren und den Lifecycle konfigurieren,
|
||||
- erlaubte Projekttypen, sichtbare Phasen und kundenseitige Phasenbezeichnungen festlegen,
|
||||
- Dokument-Auto-Freigaben und Upload-Limits verwalten,
|
||||
- Statusmails sowie Impressum-, Datenschutz- und AGB-Links konfigurieren,
|
||||
- Kunden und Subunternehmer einladen, erneut einladen oder deaktivieren,
|
||||
- projektbezogene Zugriffe, Upload-Rechte, Laufzeiten und sichtbare Inhalte festlegen,
|
||||
- Portalaktivitäten in der Service-Inbox bearbeiten,
|
||||
- Portal-Paket und optional eine Custom-Domain verwalten.
|
||||
|
||||
## 5. Tenant-Logo und Fallback
|
||||
|
||||
Ein Workspace-Admin mit `portal.admin` kann in den Portal-Einstellungen ein eigenes Portal-Logo
|
||||
hochladen, direkt als Vorschau prüfen und wieder entfernen.
|
||||
|
||||
- akzeptierte Formate: PNG, JPEG und WebP,
|
||||
- maximale Größe: 5 MB,
|
||||
- Prüfung: restriktive Bildsignatur und verpflichtender ClamAV-Scan vor Speicherung,
|
||||
- Speicherung: privates, tenant-isoliertes Objekt mit deterministischem Schlüssel,
|
||||
- Auslieferung: kurzlebige, serverseitig signierte URL; kein öffentlicher Bucket,
|
||||
- Cache-/Leak-Schutz: `private, no-store`, `no-referrer` und `nosniff`,
|
||||
- Fallback: fehlt das Tenant-Logo oder kann es nicht geladen werden, erscheint automatisch die normale
|
||||
HiveGrid-Wortmarke; in der eingeklappten Sidebar erscheint das HiveGrid-Signet.
|
||||
|
||||
Dasselbe Branding gilt auf dem Standardhost und auf einer aktivierten Custom-Domain. Es gibt aktuell kein
|
||||
frei konfigurierbares Theme, keine eigenen Fonts und kein vollständiges White-Labeling.
|
||||
|
||||
## 6. Hosts und Custom-Domain
|
||||
|
||||
Der Standardhost ist immer der Fallback:
|
||||
|
||||
- Staging: `https://staging-portal.hivegrid.de/<tenant>/...`
|
||||
- Produktion: `https://portal.hivegrid.de/<tenant>/...`
|
||||
|
||||
Auf einer verifizierten Custom-Domain entfallen Tenant-Slug und HiveGrid-Standardhost aus der sichtbaren URL;
|
||||
die fachlichen Seiten und das Tenant-Branding bleiben identisch. Workspace-Admins erhalten TXT-/CNAME-
|
||||
Anleitung, Status und Fehlerhilfe. Der Domain-Controller provisioniert ausschließlich exakte, verifizierte
|
||||
Hosts inklusive TLS. Entfernung, Entitlement-Verlust und Kill-Switch deaktivieren den Host; ein 30-tägiger
|
||||
Reclaim-Cooldown verhindert eine schnelle Fremdübernahme.
|
||||
|
||||
## 7. Bewusste UX-Entscheidungen des Rescue-Stands
|
||||
|
||||
Der UI-Nachzug aus PR `#212` reduziert visuelle Konkurrenz und richtet das Portal an der bestehenden
|
||||
HiveGrid-SaaS aus:
|
||||
|
||||
- keine doppelte Kopf- und Hauptnavigation,
|
||||
- Einstellungen getrennt von den täglichen Arbeitszielen,
|
||||
- weniger Dashboard-Karten und Wiederholungen,
|
||||
- Projektfortschritt und Tabs ohne Überlagerungen oder übergroße Leerflächen,
|
||||
- kompakter Datei-Upload mit klarer Auswahl, Aktion und Upload-Historie,
|
||||
- konsistente Abstände, Typografie, Status-Badges, Empty-/Loading-/Fehlerzustände und mobile Breakpoints.
|
||||
|
||||
Die lokale Demo-Route dient ausschließlich der visuellen Entwicklung und ist im Production-Build nicht
|
||||
registriert. Der aktuelle Screen bleibt formal die verbesserte AD-28-Interim-UI. `VD-P26` bleibt deshalb als
|
||||
finaler Subframe-/Design-Polish offen; der technische Funktionsumfang von `VA-P26a/b/c` bleibt abgeschlossen.
|
||||
|
||||
## 8. Release-Nachweis
|
||||
|
||||
- UI-/Branding-PR: [`#212`](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/pulls/212)
|
||||
- Main-Revision: `090e2558a6965e1c5804eb24d3eab5da8c8611a8`
|
||||
- Staging-Deploy: [`#11018`](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/11018)
|
||||
- CI: 13/13 PR-Jobs grün; Typecheck, Lint, Core-Tests, Visual-, A11y-, i18n-, Hot-Swap-, Bundle- und
|
||||
Docker-Gates grün.
|
||||
- Core und Portal verwenden denselben Web-Digest
|
||||
`sha256:064bd20e3e1694a1162198f772406b1aea10e3f7f7b73f877b6e4f0246c041e1`.
|
||||
- `staging-app.hivegrid.de` und `staging-portal.hivegrid.de` lieferten nach dem Rollout auf `/healthz`
|
||||
und `/readyz` HTTP 200 mit der exakten Main-Revision. Der Domain-Controller akzeptierte den Release;
|
||||
der Recovery-Pfad führte keinen Rollback aus.
|
||||
- Produktion, Plane-Tickets, DNS-Zustände, Schlüssel und Passwörter wurden durch diesen UI-Release nicht
|
||||
verändert.
|
||||
|
||||
## 9. Maßgebliche Codepfade
|
||||
|
||||
- Portal-Shell und Screens: `apps/web/app/components/screens/customer-portal/`
|
||||
- Portal-Routen: `apps/web/app/routes/customer-portal/`
|
||||
- Tenant-Verwaltung: `apps/web/app/routes/app.$tenant/settings/customer-portal.tsx`
|
||||
- Branding-Service: `apps/web/app/services/customer-portal/portal-branding.server.ts`
|
||||
- Portal-Domain-Controller: `apps/portal-domain-controller/`
|
||||
- View-Models: `packages/view-models/src/customer-portal/`
|
||||
- Visual-Baselines: `packages/ui-mock/visual-baseline/va-p26*-customer-portal-*`
|
||||
@@ -1,11 +1,13 @@
|
||||
# DSGVO Bulk-Ops (Self-Service Export, Deletion, Pseudonymisation)
|
||||
|
||||
**Phase:** 10 — Compliance Polish
|
||||
**Status:** active
|
||||
**Status:** legacy / dormant
|
||||
|
||||
This document describes the runtime architecture of the DSGVO bulk-ops
|
||||
pipeline that delivers the user-facing rights under GDPR Art. 15, 17
|
||||
and 20.
|
||||
This document describes a legacy bulk-ops implementation that is not wired into
|
||||
the current worker runtime. The active user-facing export paths are the P21
|
||||
privacy export and customer-portal export services: they store bounded objects
|
||||
with SSE-C and deliver them only through authenticated `200` app routes. Do not
|
||||
use this document as deployment evidence for those paths.
|
||||
|
||||
## Schema
|
||||
|
||||
@@ -62,8 +64,8 @@ interface identifier (/48) for `AuditEvent.actorIp` rewrites.
|
||||
|
||||
## Worker Pipeline
|
||||
|
||||
Three worker jobs (`apps/worker/src/jobs/dsgvo-*.ts`) execute the
|
||||
heavy lifting:
|
||||
Three dormant worker jobs (`apps/worker/src/jobs/dsgvo-*.ts`) describe the
|
||||
legacy implementation:
|
||||
|
||||
### 1. `dsgvo-export.ts`
|
||||
|
||||
@@ -86,9 +88,10 @@ Bundle layout:
|
||||
}
|
||||
```
|
||||
|
||||
After completion a presigned URL is minted (7-day validity), emailed
|
||||
to the user and audited as `EXPORT_PERSONAL_DATA` with
|
||||
`regulatoryScope=["gdpr"]`, `dataSensitivity="pii"`.
|
||||
The legacy code mints a presigned URL with seven-day validity and emails it to
|
||||
the user. It is not runtime-wired and must not be enabled as a fallback for the
|
||||
active SSE-C P21/portal export contract. Any future reactivation requires a
|
||||
separate security review and migration to the current authenticated proxy.
|
||||
|
||||
### 2. `dsgvo-deletion.ts`
|
||||
|
||||
|
||||
@@ -18,12 +18,8 @@
|
||||
| Local readiness seed | `scripts/seed-e2e-readiness.ts` | deterministic welcome / trial-expiring / stale-lead / customer-welcome definitions for local E2E fixtures |
|
||||
|
||||
This page claims active ownership of the email-sequence subscriber on
|
||||
`outbox.marketing`.
|
||||
It does not classify Email Sequences as the `email-marketing` CRM-contact
|
||||
campaign plugin candidate from
|
||||
`docs/feature-decisions/email-marketing-decision-report.md` or
|
||||
`docs/feature-manifests/plugin-candidates.json`. Treat Email Sequences as
|
||||
foundation/admin-preview work until the production follow-ups below land.
|
||||
`outbox.marketing`. It does not implement the tenant Email Marketing scope from `AK-P14*`.
|
||||
Treat Email Sequences as foundation/admin-preview work until the production follow-ups below land.
|
||||
The generic marketing integration handler/adapters for Slack, Discord,
|
||||
Mailchimp, HubSpot, Brevo, and custom webhooks are documented in
|
||||
`docs/features/marketing-funnel.md`; as of this status reconciliation that
|
||||
|
||||
@@ -227,7 +227,7 @@ they're allowed to save (SSRF defense).
|
||||
```
|
||||
hivegrid-cli forms list --tenant <tenantId>
|
||||
hivegrid-cli forms create --tenant <tenantId> --name "Contact" --origin https://www.example.com
|
||||
hivegrid-cli forms delete --id <formId>
|
||||
hivegrid-cli forms delete --tenant <tenantId> --id <formId>
|
||||
```
|
||||
|
||||
## Environment variables
|
||||
|
||||
@@ -1,404 +1,108 @@
|
||||
# Marketing-Funnel Overview
|
||||
# Plattform-Lead-Eingang und historischer Marketing-Funnel
|
||||
|
||||
This page is the canonical overview for the shipped lead-capture and
|
||||
self-service conversion foundation. Email sequences are covered separately in
|
||||
`docs/features/email-sequences.md`.
|
||||
Seit R-LEADS (`HIVEGRID-73`, AD-31) ist der native Plattform-Lead-Eingang die
|
||||
einzige aktive Zielarchitektur für HiveGrid-eigene Vertriebsanfragen. Diese Datei
|
||||
dokumentiert den aktuellen Vertrag und die während des Cutovers bewusst noch
|
||||
vorhandenen Legacy-Kompatibilitätspfade.
|
||||
|
||||
## Aktive Architektur
|
||||
|
||||
| Ebene | Aktiver Vertrag |
|
||||
| ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
||||
| Datenmodell | `AdminLead`, `AdminLeadActivity`, `AdminLeadSource` und gehashte Source-Credentials in `prisma/schema/adminLeads.prisma` |
|
||||
| Eingang | `POST /v1/platform/leads` auf dem API-Host |
|
||||
| Producer | ausschließlich serverseitig; ein Source-Credential pro freigeschalteter Website/Partnerquelle |
|
||||
| Admin-Inbox | `/leads`, `/leads/new`, `/leads/:id` und `/leads/sources` auf dem Admin-Host |
|
||||
| Benachrichtigung | tenantlose, PII-minimierte M011-Outbox mit Worker-Retry und aktueller Empfänger-Revalidierung |
|
||||
|
||||
Das Source-Credential bestimmt die Quelle. Ein Request darf die Source nicht
|
||||
selbst autoritativ wählen. `Idempotency-Key` ist Pflicht und muss von einem
|
||||
Producer für dieselbe Submission bis zur bestätigten Antwort stabil
|
||||
wiederverwendet werden. Kontakt-, Nachrichten- und Attributionsfelder werden
|
||||
schema- und größenvalidiert; Logs, Outbox und Queue enthalten keine Lead-PII.
|
||||
|
||||
Der API-Eingang kann im Notfall mit `PLATFORM_LEADS_INGRESS_ENABLED=false`
|
||||
neutral als 404 abgeschaltet werden. Die Admin-Oberfläche ist davon unabhängig
|
||||
standardmäßig aktiv und wird über AdminUser, Permissions und Own-/All-RLS geschützt.
|
||||
|
||||
Details zu Source-Bootstrap, Backfill, Canary, Rollback und Decommission stehen in
|
||||
`docs/ops/platform-leads-cutover.md`. Der vollständige Bauvertrag steht in
|
||||
`.planning/ticket-docs/R-LEADS.md`.
|
||||
|
||||
## Aktiver API-Vertrag
|
||||
|
||||
`POST /v1/platform/leads` erwartet:
|
||||
|
||||
- `Authorization: Bearer <source credential>`
|
||||
- `Idempotency-Key: <stabile submission id>`
|
||||
- JSON mit mindestens einem nutzbaren Kontakt- oder Inhaltsfeld
|
||||
- optionale, begrenzte UTM-, Referrer-, Landing-Page- und Metadatenfelder
|
||||
|
||||
Relevante Antworten sind `201` für Create und identischen Replay, `400` für
|
||||
Validierung, `401` für ein ungültiges oder revoktes Credential, `409` für einen
|
||||
Idempotency-Hash-Konflikt, `413` für einen zu großen Body und `429` für das
|
||||
Source-/Ingress-Limit. OpenAPI ist die kanonische Feldreferenz.
|
||||
|
||||
Browser und statische Marketing-Sites erhalten niemals das Source-Credential.
|
||||
Die HiveGrid-Website besitzt deshalb einen serverseitigen Proxy/Action-Handler.
|
||||
Ein fehlgeschlagener API-Request darf dort
|
||||
nicht als erfolgreicher Lead angezeigt oder in eine Container-SQLite-Datei
|
||||
zurückgefallen werden.
|
||||
|
||||
## Retired: Browser-Capture und Embed-SDK
|
||||
|
||||
Die folgenden Komponenten sind kein aktiver Lead-Eingang mehr:
|
||||
|
||||
- `POST /api/leads/capture` liefert während des Drain-Fensters bewusst `410 Gone`
|
||||
und verweist auf `/v1/platform/leads`; `OPTIONS` bleibt nur für eine saubere
|
||||
CORS-Fehlermeldung verfügbar.
|
||||
- `apps/web/public/embed/marketing.js` ist entfernt. Es gibt kein öffentliches
|
||||
`window.hivegridMarketing`-SDK und keinen `data-hivegrid-lead`-Hook mehr.
|
||||
- `/marketing-leads`, `/incoming-leads-board` und `/marketing-funnels` leiten auf
|
||||
die native `/leads`-Inbox um.
|
||||
- Die Legacy-Tabellen `Lead`/`LeadEvent` sind bis zum Ende des Rollback-/Drain-
|
||||
Fensters read-only. Verbleibende CLI-Reads dienen ausschließlich Export und
|
||||
Rollback; sie sind kein zweites aktives Produkt-Frontend und werden nach dem
|
||||
bestätigten Sieben-Tage-Drain entfernt.
|
||||
|
||||
`MARKETING_ALLOWED_ORIGINS` beeinflusst nur noch die CORS-Header der
|
||||
`410 Gone`-Antwort. `MARKETING_RATE_LIMIT_PER_MIN` ist für den retired Endpoint
|
||||
wirkungslos und bleibt vorübergehend nur als kompatibler, deprecated Env-Key im
|
||||
Konfigurationskatalog.
|
||||
|
||||
## Historische Conversion-Kompatibilität
|
||||
|
||||
Die signierte Self-Service-Conversion bestehender Legacy-Leads bleibt während
|
||||
des Rollback-Fensters bewusst separat erhalten. Sie darf keine neuen
|
||||
`Lead`/`LeadEvent`-Captures erzeugen. Die SECURITY-DEFINER-Funktion
|
||||
`hivegrid_convert_self_service_lead` ist nur für den signierten Registrierungsweg
|
||||
freigegeben; direkte Runtime-Schreibrechte auf Legacy-Tabellen bleiben entzogen.
|
||||
|
||||
`LEAD_CONVERSION_SECRET` und `LEAD_CONVERSION_ENABLED` gehören zu diesem
|
||||
Kompatibilitätspfad. Eine Überführung dieser Conversion in die spätere
|
||||
`AdminDeal`-/M040b-Welt ist nicht Teil von R-LEADS.
|
||||
|
||||
## Outbound- und E-Mail-Marketing-Abgrenzung
|
||||
|
||||
Die vorhandenen Marketing-Webhook-Adapter und die E-Mail-Sequenz-Engine sind
|
||||
eigenständige Foundations. Sie machen den retired Browser-Capture nicht wieder
|
||||
aktiv und dürfen nicht automatisch von einem AdminLead-Import ausgelöst werden.
|
||||
Die jeweiligen Runtime-Schalter und Betriebsgrenzen stehen in
|
||||
`docs/features/email-sequences.md` und den zugehörigen Worker-Dokumenten.
|
||||
|
||||
This page also keeps the marketing-outbound boundary explicit: the
|
||||
`packages/marketing-outbound` adapters and
|
||||
`apps/worker/src/jobs/marketing-outbound.ts` handler are a shipped general
|
||||
handler foundation, but the general subscriber is not bootstrapped from
|
||||
`apps/worker/src/index.ts`. That foundation is separate from the
|
||||
`email-marketing` CRM-contact campaign plugin candidate in
|
||||
`docs/feature-decisions/email-marketing-decision-report.md`.
|
||||
|
||||
The marketing-funnel ships a four-layer pipeline that lets external landing
|
||||
pages, ads, and blog CTAs feed structured leads into the operator-side admin
|
||||
inbox without an external CRM.
|
||||
|
||||
| Layer | Component |
|
||||
|------------------|------------------------------------------------------------|
|
||||
| 1. Data model | `Lead` + `LeadEvent` Prisma tables (`prisma/schema/marketingLeads.prisma`) |
|
||||
| 2. Ingestion API | `POST /api/leads/capture` (`apps/web/app/routes/api.leads.capture.tsx`) |
|
||||
| 3. SDK | `apps/web/public/embed/marketing.js` (origin-served mini-snippet; CDN-ready while A7/B2 remains backlog) |
|
||||
| 4. Admin UI | `/admin/marketing-leads` (list) + `/admin/marketing-leads/:id` (detail) |
|
||||
|
||||
## Status machine
|
||||
|
||||
Leads move through seven states:
|
||||
|
||||
```
|
||||
new → contacted → qualified → trial → customer
|
||||
↘ churned
|
||||
↘ disqualified
|
||||
```
|
||||
|
||||
Transitions are recorded as `LeadEvent` rows of type `status-changed` for the
|
||||
activity-timeline in the detail-view. Operators move leads forward (or to a
|
||||
terminal state) from the detail page. The `score`, `notes`, and `convertedAt`
|
||||
columns are operator-managed.
|
||||
|
||||
## Attribution
|
||||
|
||||
Every Lead carries first-touch attribution columns populated by the SDK on
|
||||
the initial visit and persisted in localStorage so subsequent page visits
|
||||
attribute to the same source:
|
||||
|
||||
| Column | Source |
|
||||
|---------------|-----------------------------------------------------|
|
||||
| `utmSource` | `?utm_source=…` |
|
||||
| `utmMedium` | `?utm_medium=…` |
|
||||
| `utmCampaign` | `?utm_campaign=…` |
|
||||
| `utmTerm` | `?utm_term=…` |
|
||||
| `utmContent` | `?utm_content=…` |
|
||||
| `gclid` | `?gclid=…` (Google Ads click identifier) |
|
||||
| `fbclid` | `?fbclid=…` (Meta Ads click identifier) |
|
||||
| `referrer` | `document.referrer` |
|
||||
| `landingPage` | `location.href` at the first visit |
|
||||
| `firstSeenAt` | `new Date()` on initial insert (never overwritten) |
|
||||
| `lastTouchAt` | `new Date()` on every re-capture |
|
||||
|
||||
`source` is operator-supplied (via the form's `data-source` attribute or the
|
||||
SDK call's `source` field) and identifies the surface — `"landing-pro"`,
|
||||
`"blog-cta"`, `"webinar-form"` — distinct from the paid-channel `utmSource`.
|
||||
|
||||
## Anti-spam (defence in depth)
|
||||
|
||||
The capture endpoint stacks four layers, each weakening different bot
|
||||
classes; none of them is sufficient alone.
|
||||
|
||||
1. **Origin allowlist** — `MARKETING_ALLOWED_ORIGINS` (CSV with `*.host`
|
||||
wildcards). 403 on miss. Defeats browser-based form-spam from
|
||||
non-whitelisted pages; can be spoofed by server-to-server bots.
|
||||
2. **Honeypot** — the SDK injects a hidden `website_url` field. When the
|
||||
server sees it filled, it responds with a silent 204 and inserts nothing.
|
||||
80%+ of crude form-fillers fall here.
|
||||
3. **Sliding-window rate-limit** — 5/min per IP (configurable via
|
||||
`MARKETING_RATE_LIMIT_PER_MIN`) and 1/min per email. The per-email limit
|
||||
doubles as a re-capture dedupe so the LeadEvent timeline doesn't flood.
|
||||
4. **Cloudflare Turnstile** (optional) — gated behind the
|
||||
`marketing-funnel-turnstile` feature flag. When enabled, callers must
|
||||
include a valid `turnstileToken`; verification hits the Cloudflare API.
|
||||
|
||||
Successful responses are intentionally identical for new and duplicate
|
||||
emails (empty body, 200 OK) so bots cannot enumerate the customer list.
|
||||
|
||||
## API contract
|
||||
|
||||
### `POST /api/leads/capture`
|
||||
|
||||
Public, CORS-enabled. Accepts `application/json` or
|
||||
`application/x-www-form-urlencoded`. Body:
|
||||
|
||||
```json
|
||||
{
|
||||
"email": "alice@example.com",
|
||||
"firstName": "Alice",
|
||||
"lastName": "Liddell",
|
||||
"phone": "+44 …",
|
||||
"company": "Acme",
|
||||
"source": "landing-pro",
|
||||
"attribution": {
|
||||
"utmSource": "google",
|
||||
"utmCampaign": "spring-launch",
|
||||
"gclid": "EAIaIQ…",
|
||||
"referrer": "https://google.com/",
|
||||
"landingPage": "https://example.com/landing"
|
||||
},
|
||||
"turnstileToken": "0.OOOO…",
|
||||
"website_url": ""
|
||||
}
|
||||
```
|
||||
|
||||
Responses:
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|--------------------------------------------------|
|
||||
| 200 | Captured (or silently de-duplicated). Empty body.|
|
||||
| 204 | Honeypot triggered or per-email rate-limit hit. |
|
||||
| 400 | Invalid payload shape. |
|
||||
| 403 | Origin not allowlisted or Turnstile failed. |
|
||||
| 413 | Body exceeds 32 KiB. |
|
||||
| 429 | Per-IP rate-limit exceeded. |
|
||||
|
||||
### `OPTIONS /api/leads/capture`
|
||||
|
||||
CORS preflight. Echoes the matched origin in `Access-Control-Allow-Origin`.
|
||||
|
||||
## SDK (`marketing.js`)
|
||||
|
||||
Drop the script tag onto every marketing page:
|
||||
|
||||
```html
|
||||
<script src="https://cdn.example.com/embed/marketing.js"
|
||||
data-api-url="https://app.example.com" defer></script>
|
||||
```
|
||||
|
||||
The script self-bootstraps on `DOMContentLoaded`:
|
||||
|
||||
- Reads `?utm_source/medium/campaign/term/content`, `?gclid`, `?fbclid` from
|
||||
the URL and merges them with the stored first-touch attribution.
|
||||
- Persists merged attribution to `localStorage["__tcm_attr"]` so multi-page
|
||||
flows hit the same lead source.
|
||||
- Auto-binds any `<form data-hivegrid-lead>` on the page — submitting
|
||||
POSTs to `/api/leads/capture` instead of the form's action.
|
||||
|
||||
Imperative API exposed as `window.hivegridMarketing`:
|
||||
|
||||
```js
|
||||
hivegridMarketing.captureLead({
|
||||
email: "alice@example.com",
|
||||
firstName: "Alice",
|
||||
source: "blog-cta",
|
||||
});
|
||||
|
||||
hivegridMarketing.bindFormById("lead-form");
|
||||
hivegridMarketing.bindFormsByAttr();
|
||||
hivegridMarketing.getAttribution(); // → merged first-touch object
|
||||
hivegridMarketing.resetAttribution(); // wipes localStorage cache
|
||||
```
|
||||
|
||||
Custom events on bound forms:
|
||||
|
||||
- `tcm:captured` — `{ ok: boolean, status: number }`
|
||||
- `tcm:error` — `{ error: string }`
|
||||
|
||||
The SDK is hand-minified to stay under the 3 KB gzipped budget (currently
|
||||
~2 KB) and ships from `apps/web/public/embed/marketing.js`.
|
||||
|
||||
## Admin UI
|
||||
|
||||
- **List** at `/admin/marketing-leads` — filter by status (seven badge
|
||||
shortcuts), source, or search by email/name/company. Paginated 25 per
|
||||
page. Permission: `admin.marketing.leads.view`.
|
||||
- **Detail** at `/admin/marketing-leads/:id` — profile + attribution
|
||||
panels, status transition buttons (every state reachable via one click),
|
||||
inline notes editor with history, convert-to-tenant action, and the
|
||||
LeadEvent activity timeline. Permission: `admin.marketing.leads.manage`.
|
||||
|
||||
## CLI
|
||||
|
||||
```
|
||||
hivegrid-cli leads list [--status new] [--limit 50]
|
||||
hivegrid-cli leads export [--out leads.csv] [--status qualified]
|
||||
hivegrid-cli leads delete --id <leadId> # DSGVO right-to-be-forgotten
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
| Env | Default | Purpose |
|
||||
|--------------------------------|---------|-------------------------------------------------------------|
|
||||
| `MARKETING_ALLOWED_ORIGINS` | (empty) | CSV of allowed origins for capture endpoint. Fail-closed. |
|
||||
| `MARKETING_RATE_LIMIT_PER_MIN` | 5 | Per-IP sliding-window submission limit. |
|
||||
| `TURNSTILE_SITE_KEY` | — | Cloudflare Turnstile site key (shared with form-widget). |
|
||||
| `TURNSTILE_SECRET_KEY` | — | Cloudflare Turnstile secret (shared with form-widget). |
|
||||
|
||||
The `marketing-funnel-turnstile` feature flag must be enabled for Turnstile
|
||||
to actually gate submissions; the secret alone is not enough.
|
||||
tenant Email Marketing scope in `.planning/ticket-docs/AK-P14a.md` and proves neither an active
|
||||
subscriber nor production delivery.
|
||||
|
||||
## Rollback
|
||||
|
||||
- `MARKETING_ALLOWED_ORIGINS=` empties the allowlist → all browser captures
|
||||
are rejected with 403 while leaving the admin UI usable for triage.
|
||||
- Drop the `Lead` + `LeadEvent` tables to wipe captured data (no other
|
||||
tables reference them today). Export with `hivegrid-cli leads export`
|
||||
first.
|
||||
|
||||
---
|
||||
|
||||
# Phase 2 — Self-Service Conversion + Outbound Webhooks + Attribution
|
||||
|
||||
Phase 2 (task #79) extends Phase 1's inbox with three independently-shippable
|
||||
layers:
|
||||
|
||||
1. **Self-service conversion deep-links** — a signed lead-token in the URL
|
||||
pre-fills the registration form. The normal registration service creates
|
||||
the User + Tenant, then records the Lead conversion against that Tenant:
|
||||
`Lead.convertedToTenantId`, a `TenantAcquisition` snapshot, and the
|
||||
marketing outbox event are written in one transaction.
|
||||
2. **Outbound webhook foundation** — six pluggable adapters (Slack, Discord,
|
||||
Mailchimp, HubSpot, Brevo, custom HTTPS) plus the
|
||||
`apps/worker/src/jobs/marketing-outbound.ts` handler contract. General
|
||||
marketing integration delivery is still a production follow-up because
|
||||
that handler is not currently bootstrapped from `apps/worker/src/index.ts`.
|
||||
3. **Attribution reports** — `/admin/marketing-funnels` aggregates leads
|
||||
+ acquisitions by source, campaign, utm_source, conversionPath. Mirror
|
||||
via `hivegrid-cli marketing funnel|attribution`.
|
||||
|
||||
## Signed lead-token
|
||||
|
||||
`signLeadToken({ leadId, planId, expiresInDays = 7 })` produces a token of
|
||||
the shape `v1.<base64url(payload)>.<base64url(hmac-sha256)>`. The HMAC
|
||||
key is `LEAD_CONVERSION_SECRET` (min 32 bytes). `verifyLeadToken(token)`
|
||||
returns the payload when the signature matches AND the token has not
|
||||
expired — otherwise `null`. Both functions fail-closed when the secret
|
||||
env is missing.
|
||||
|
||||
Email pre-filled from a Lead is rendered read-only on the register form
|
||||
to prevent lead-hijacking ("I use your token but with my email"). The signed
|
||||
token is also submitted as a hidden field and verified again in the register
|
||||
action. If email verification is enabled, the verified conversion context is
|
||||
stored on the pending `Registration` row and replayed from `/verify/:token`
|
||||
after the visitor sets a password. To change the email the visitor must
|
||||
abandon the link and start a fresh signup.
|
||||
|
||||
## Atomic conversion service
|
||||
|
||||
`convertLeadToTenant({ leadId, tenant: { name, slug, inboundAddress }, ... })`
|
||||
runs inside a single Prisma `$transaction`:
|
||||
|
||||
1. `tenant.create` (slug + inbound address pre-resolved by caller).
|
||||
2. `lead.update` → `status` advances to `trial`/`customer`,
|
||||
`convertedToTenantId` + `convertedAt` populated.
|
||||
3. `leadEvent.create` of type `converted` with full conversion payload.
|
||||
4. `tenantAcquisition.create` snapshot copying UTM/referrer/landingPage
|
||||
from the Lead.
|
||||
5. `publishOutboxEvent` with type `marketing.lead.convertedtotrial` or
|
||||
`marketing.lead.convertedtocustomer` and dispatchKey
|
||||
`lead-convert:<leadId>` (idempotent on retry).
|
||||
|
||||
Already-converted leads (`convertedToTenantId !== null`) short-circuit
|
||||
and return the existing tenant.
|
||||
|
||||
For the self-service register flow, the already-created Tenant is linked via
|
||||
`recordExistingTenantLeadConversion({ leadId, tenantId, ... })`. It reuses the
|
||||
same conversion event/outbox payload and upserts the `TenantAcquisition` row
|
||||
instead of creating a second Tenant.
|
||||
|
||||
## Admin manual override
|
||||
|
||||
`/admin/marketing-leads/<id>` exposes a "Create Tenant" form. Operator
|
||||
can override the tenant name + supply an optional planId. The action
|
||||
calls `convertLeadToTenant({ conversionPath: "admin-override", actorId })`.
|
||||
A native confirm dialog guards accidental clicks.
|
||||
|
||||
## Outbound webhook adapters
|
||||
|
||||
`packages/marketing-outbound` ships six adapters under
|
||||
`src/adapters/*.ts`:
|
||||
|
||||
| Adapter | Config keys (encrypted at rest) | Notes |
|
||||
|---------|----------------------------------------------------------------|-------|
|
||||
| slack | `webhookUrl`, `channel?` | Block-Kit message. |
|
||||
| discord | `webhookUrl`, `username?` | Embed with color-coded event. |
|
||||
| mailchimp | `apiKey`, `listId`, `status?`, `tags?` | PUT to lists/{id}/members/{md5(email)}. |
|
||||
| hubspot | `accessToken` | POST /crm/v3/objects/contacts; 409 = idempotent. |
|
||||
| brevo | `apiKey`, `listIds?` | POST /v3/contacts with `updateEnabled: true`. |
|
||||
| webhook | `url`, `signingSecret?`, `headers?` | POSTs canonical envelope; optional HMAC-SHA256 sig. |
|
||||
|
||||
All adapters share a single `adapterFetch` helper that enforces:
|
||||
|
||||
- HTTPS only (rejects http: / localhost / RFC1918 / 169.254.* /
|
||||
`metadata.google.internal` / `.internal` / `.local` / `.lan`).
|
||||
- 10 s default timeout (AbortController).
|
||||
- Returns structured `AdapterResult { ok, status?, errorTag? }` so the
|
||||
worker can categorise failures consistently.
|
||||
|
||||
The `ctx.maskPii.email` toggle masks the local part of the email
|
||||
(`patrick@example.com → ***@example.com`) before any payload leaves the
|
||||
host. Use it for data-egress-restricted tenants.
|
||||
|
||||
## Apps/worker handler status
|
||||
|
||||
`apps/worker/src/jobs/marketing-outbound.ts` defines a pure handler contract
|
||||
for marketing integration delivery, but it does not own or subscribe to
|
||||
`outbox.marketing`. That queue is currently used by the email-sequence trigger
|
||||
subscriber when `MARKETING_SEQUENCES_ENABLED=true`; this does not imply
|
||||
Slack/Discord/Mailchimp/HubSpot/Brevo/custom webhook delivery is active.
|
||||
Treat the adapters, handler, admin UI, and env flag as a shipped foundation
|
||||
until a bootstrap module wires a distinct general marketing integration
|
||||
subscriber into the worker runtime with explicit ownership tests.
|
||||
|
||||
The handler accepts only these event types today:
|
||||
`marketing.lead.captured`, `marketing.lead.qualified`,
|
||||
`marketing.lead.convertedtotrial`, and
|
||||
`marketing.lead.convertedtocustomer`. New `marketing.lead.*` events require
|
||||
an update to `MARKETING_LEAD_EVENT_TYPES` plus tests. For each accepted event:
|
||||
|
||||
1. Parse + validate envelope (`parseMarketingOutboundJob`).
|
||||
2. Bail out when `MARKETING_WEBHOOKS_ENABLED=false`.
|
||||
3. Fetch every enabled `MarketingIntegration` whose `triggerEvents`
|
||||
includes the eventType.
|
||||
4. For each integration: decrypt config, resolve adapter via
|
||||
`resolveAdapter(type)`, call `adapter.send`. One integration's
|
||||
failure does not affect siblings.
|
||||
5. Persist diagnostics (`lastDeliveredAt`, `lastError`) on the
|
||||
integration row so the admin UI can surface them.
|
||||
|
||||
## Admin integrations UI
|
||||
|
||||
`/admin/marketing-integrations` (Phase 05 #79). CRUD list with:
|
||||
|
||||
- Add form (type picker + name + trigger-events multi-select + config
|
||||
JSON textarea).
|
||||
- Per-integration enable/disable toggle.
|
||||
- Delete with native confirm dialog.
|
||||
- Last-delivered / last-error display.
|
||||
- Config display masked (`***` for `webhookUrl`, `apiKey`,
|
||||
`accessToken`, `signingSecret`).
|
||||
|
||||
Secrets are encrypted with the existing AES-256-GCM CryptoApi helper
|
||||
(`apps/web/app/utils/api/.server/CryptoApi.ts`) keyed off `CRYPTO_SECRET`.
|
||||
|
||||
## Attribution reports
|
||||
|
||||
`/admin/marketing-funnels` (Phase 05 #79). Top-line cards (leads
|
||||
captured, conversions, conversion rate) plus four breakdowns: campaign,
|
||||
utm_source, source-label, conversionPath. Reads via `dbRead`
|
||||
(replica-routed). CLI mirror:
|
||||
|
||||
- `hivegrid-cli marketing funnel --days 30`
|
||||
- `hivegrid-cli marketing attribution --dimension campaign --days 30 --limit 25`
|
||||
|
||||
## Configuration (Phase 2)
|
||||
|
||||
| Env | Default | Purpose |
|
||||
|------------------------------|---------|------------------------------------------------------------|
|
||||
| `LEAD_CONVERSION_SECRET` | — | HMAC key for signed lead-tokens (min 32 bytes). |
|
||||
| `LEAD_CONVERSION_ENABLED` | `true` | Set `false` to disable the conversion flow without DB rollback. |
|
||||
| `MARKETING_WEBHOOKS_ENABLED` | `true` | Handler-level kill switch once the general marketing integration subscriber is bootstrapped. It does not start that subscriber by itself. |
|
||||
|
||||
## Webhook payload (custom adapter)
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "marketing.lead.v1",
|
||||
"eventType": "marketing.lead.convertedtotrial",
|
||||
"occurredAt": "2026-05-17T00:00:00.000Z",
|
||||
"lead": {
|
||||
"id": "lead_abc",
|
||||
"email": "patrick@example.com",
|
||||
"firstName": "Patrick",
|
||||
"lastName": "Doe",
|
||||
"company": "Acme",
|
||||
"source": "landing-pro",
|
||||
"utm": { "source": "google", "medium": "cpc", "campaign": "q2-launch" },
|
||||
"referrer": "https://google.com",
|
||||
"landingPage": "/pricing"
|
||||
},
|
||||
"conversion": {
|
||||
"tenantId": "tenant_xyz",
|
||||
"targetStatus": "trial",
|
||||
"conversionPath": "self-service",
|
||||
"planId": "plan_pro"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When `signingSecret` is set, the receiver verifies
|
||||
`x-marketing-signature: sha256=<hex>` against
|
||||
`hmac_sha256(body, signingSecret)`.
|
||||
|
||||
## Rollback (Phase 2)
|
||||
|
||||
- `LEAD_CONVERSION_ENABLED=false` — register loader ignores the token
|
||||
query params; admin override button hidden.
|
||||
- `MARKETING_WEBHOOKS_ENABLED=false` — once the general marketing
|
||||
integration subscriber is bootstrapped, the worker handler short-circuits.
|
||||
Today it is only a handler-level kill switch for the shipped foundation.
|
||||
Outbox events accumulate; raise outbox retention if you plan a long
|
||||
pause.
|
||||
- Per-integration disable toggle in the admin UI — faulty integrations
|
||||
can be parked without a deploy.
|
||||
- `TenantAcquisition` + `MarketingIntegration` tables can be dropped
|
||||
(no FK in to them from Tenant), but you'd lose attribution history.
|
||||
Während des dokumentierten Drain-Fensters können Producer auf den gesicherten
|
||||
externen Legacy-Dienst zurückgestellt werden. Der HiveGrid-Cloud-Browserendpoint
|
||||
bleibt auch im Rollback `410`; eine Reaktivierung wäre eine neue Architektur- und
|
||||
Security-Entscheidung. Native Importe sind idempotent und löschen keine
|
||||
Quellbestände. Das letzte verschlüsselte, restore-geprüfte Backup wird bis zu
|
||||
einem separaten Retention-Entscheid behalten.
|
||||
@@ -135,7 +135,6 @@ For documentation-only changes:
|
||||
|
||||
```sh
|
||||
pnpm run verify:docs-links
|
||||
pnpm run verify:production-docs
|
||||
```
|
||||
|
||||
For runtime/plugin changes:
|
||||
|
||||
@@ -139,6 +139,8 @@ Rollback: dropping `CollabDoc` is safe — no other code path reads from it.
|
||||
|
||||
All entries are also documented in `packages/config/src/catalog.ts` so the env-drift verifier accepts them.
|
||||
|
||||
`VITE_HOCUSPOCUS_URL` ist öffentliche Konfiguration und kein Secret. Die gleichnamige Gitea-Repository-Variable wird ausschließlich an das Docker-Target `web-build` übergeben und sowohl in das Browser-Bundle als auch in dessen authentifizierte CSP eingebettet. Da die Production-Promotion exakt denselben bereits gestagten Image-Digest verwendet, muss der konfigurierte öffentliche WebSocket-Endpunkt für beide Deployments gültig sein; bei einem geteilten Image ist dafür ein umgebungsneutraler Gateway-Hostname zu verwenden.
|
||||
|
||||
## Out of scope / deferred
|
||||
|
||||
- **Snapshot + cleanup cron** — a planned follow-up will land `apps/worker/src/cron/collab-cleanup.ts` plus the `CollabDocArchive` table referenced in the spec.
|
||||
|
||||
@@ -29,21 +29,37 @@ in phase 04 (#48). It is the user-facing complement to
|
||||
- **Source of truth** is Postgres. Meilisearch is a projected read-side
|
||||
populated asynchronously through the outbox pattern (#42).
|
||||
- **Tenant isolation** is enforced inside `@hivegrid/search`. Every read
|
||||
and write goes through `searchInIndex / bulkIndex / deleteFromIndex`
|
||||
with an explicit `tenantId`. The wrapper injects
|
||||
and write goes through the tenant-scoped package helpers with an explicit
|
||||
`tenantId`. The wrapper injects
|
||||
`tenantId = "<id>"` into the Meilisearch filter expression and
|
||||
escapes the value to defeat filter injection. Raw Meilisearch SDK
|
||||
access is not re-exported.
|
||||
- **Estate namespace:** schemas, outbox payloads and worker pagers use logical
|
||||
names such as `projects`. The `SearchClient` adapter is the only boundary
|
||||
that maps them to physical Meilisearch UIDs (`hivegrid-projects`). Callers
|
||||
never add the prefix themselves, and the adapter rejects already-prefixed
|
||||
input so no unprefixed or double-prefixed namespace can be touched.
|
||||
- **Graceful degradation:** every hot-path is wrapped in
|
||||
`searchWithFallback`, which routes to the legacy SQL `LIKE`
|
||||
implementation when Meilisearch raises a connectivity error. The
|
||||
search stays degraded-but-up instead of returning 500s.
|
||||
|
||||
## User-Facing Contract
|
||||
|
||||
Since the 2026-07-12 scope cut, global search is exposed only as a Spotlight
|
||||
overlay. On desktop it opens through Cmd+K/Ctrl+K or the header search trigger;
|
||||
on mobile the header trigger opens a viewport-filling overlay. There is no
|
||||
user-facing `/search` page, shareable search URL, or full-page filter/pagination
|
||||
surface in v1. `/search/api` remains the protected, tenant-scoped internal
|
||||
resource used by the overlay. `R-P11b` continues to consume the same index and
|
||||
search contracts.
|
||||
|
||||
## Index Schema Reference
|
||||
|
||||
The current schemas live in `packages/search/src/schemas/`. Each is a
|
||||
whitelist — only fields listed in `allowedDocumentFields` reach
|
||||
Meilisearch.
|
||||
Meilisearch. Names in this table are logical contract names; the physical UID
|
||||
always has the estate prefix `hivegrid-`.
|
||||
|
||||
| Index | Searchable | Filterable | Sortable |
|
||||
| -------------- | --------------------------------------------------- | ------------------------------------------------------ | --------------------------------------- |
|
||||
@@ -73,13 +89,13 @@ one otherwise).
|
||||
|
||||
## Hot-Path Migrations
|
||||
|
||||
| Path | Migrated | Notes |
|
||||
| ------------------------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| KB public search (`KnowledgeBaseService.search`) | yes (#48) | wraps `findKnowledgeBaseArticles` via `searchKnowledgeBaseArticles` helper with `searchWithFallback`. Tenant id resolved from KB record. |
|
||||
| CRM contact helper | shipped | `apps/web/app/modules/crm/services/crmContactSearch.server.ts` wraps `crm-contacts` with `searchWithFallback` and a tenant-scoped SQL fallback. |
|
||||
| Rows helper | shipped | `apps/web/app/modules/rows/services/rowSearch.server.ts` wraps the `rows` index with an `entityId` filter and tenant-scoped SQL fallback. |
|
||||
| CRM/Rows producer and callsite integration | yes | `RowsApi.getAll` calls `searchCrmContacts` for tenant-scoped CRM contact-list free-text filters and `searchRows` for other tenant-scoped row filters. `RowsApi.create / createSimple / update / del` emit `search.index.*` events through `rowSearchOutbox.server.ts`. Contact rows fan out to both `crm-contacts` and `rows`. |
|
||||
| HiveGrid global-search producers | yes | `apps/web/app/services/search/searchIndexProjection.server.ts` publishes `search.index.*` events and mirrors `SearchIndexEntry` for Kontakt/Firma/Lead/Projekt/File/Task/User lifecycle mutations. Cmd+K and `/search` read through tenant- and permission-aware SQL+Meili search. |
|
||||
| Path | Migrated | Notes |
|
||||
| ------------------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| KB public search (`KnowledgeBaseService.search`) | yes (#48) | wraps `findKnowledgeBaseArticles` via `searchKnowledgeBaseArticles` helper with `searchWithFallback`. Tenant id resolved from KB record. |
|
||||
| CRM contact helper | shipped | `apps/web/app/modules/crm/services/crmContactSearch.server.ts` wraps `crm-contacts` with `searchWithFallback` and a tenant-scoped SQL fallback. |
|
||||
| Rows helper | shipped | `apps/web/app/modules/rows/services/rowSearch.server.ts` wraps the `rows` index with an `entityId` filter and tenant-scoped SQL fallback. |
|
||||
| CRM/Rows producer and callsite integration | yes | `RowsApi.getAll` calls `searchCrmContacts` for tenant-scoped CRM contact-list free-text filters and `searchRows` for other tenant-scoped row filters. `RowsApi.create / createSimple / update / del` emit `search.index.*` events through `rowSearchOutbox.server.ts`. Contact rows fan out to both `crm-contacts` and `rows`. |
|
||||
| HiveGrid global-search producers | yes | `apps/web/app/services/search/searchIndexProjection.server.ts` publishes `search.index.*` events and mirrors `SearchIndexEntry` for Kontakt/Firma/Lead/Projekt/File/Task/User lifecycle mutations. The Spotlight overlay reads through `/search/api` using tenant- and permission-aware SQL+Meili search. |
|
||||
| Bulk reindex pagers | partial | `apps/worker/src/index.ts` registers `createSearchIndexerBulkPagers({ prisma })`; `BULK_REINDEX_SUPPORTED_INDEX_NAMES` exposes `kb-articles`, `crm-contacts`, `users`, and `projects`. File/task live producers are wired, but their disaster-recovery bulk pagers still need explicit coverage before `--index=all` can rebuild every projected index. |
|
||||
|
||||
Open hot-path gaps still serve from the legacy SQL path. Until a specific
|
||||
@@ -98,10 +114,10 @@ post-write rather than inside the row mutation transaction.
|
||||
```bash
|
||||
# Reindex every supported bulk-reindex index for every tenant via outbox events.
|
||||
# Today this means KB articles, CRM contacts, users, and projects; unsupported names are rejected.
|
||||
pnpm cli search reindex --tenant=all --index=all
|
||||
pnpm exec tsx packages/cli/bin/hivegrid-cli.mjs search reindex --tenant=all --index=all
|
||||
|
||||
# Reindex one tenant's KB articles.
|
||||
pnpm cli search reindex --tenant=tnt_abc123 --index=kb-articles
|
||||
pnpm exec tsx packages/cli/bin/hivegrid-cli.mjs search reindex --tenant=tnt_abc123 --index=kb-articles
|
||||
```
|
||||
|
||||
The CLI never writes to Meilisearch directly. It produces
|
||||
@@ -142,7 +158,7 @@ The Meilisearch volume is treated as cache. To rebuild from scratch:
|
||||
|
||||
1. `docker volume rm meilisearch-data` (after stopping the container).
|
||||
2. Restart the container.
|
||||
3. `pnpm cli search reindex --tenant=all --index=all`.
|
||||
3. `pnpm exec tsx packages/cli/bin/hivegrid-cli.mjs search reindex --tenant=all --index=all`.
|
||||
|
||||
This rebuild currently covers the supported bulk-reindex set only:
|
||||
`kb-articles`, `crm-contacts`, `users`, and `projects`. Entities require a
|
||||
|
||||
@@ -1,432 +0,0 @@
|
||||
<!doctype html>
|
||||
<html lang="de">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>HiveGrid Pricing-Entwurf</title>
|
||||
<style>
|
||||
@page {
|
||||
size: A4;
|
||||
margin: 18mm 16mm 18mm 16mm;
|
||||
}
|
||||
|
||||
* {
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
body {
|
||||
margin: 0;
|
||||
color: #1f2933;
|
||||
font-family: Inter, Arial, Helvetica, sans-serif;
|
||||
font-size: 10.2pt;
|
||||
line-height: 1.45;
|
||||
background: #ffffff;
|
||||
}
|
||||
|
||||
h1,
|
||||
h2,
|
||||
h3 {
|
||||
margin: 0;
|
||||
color: #111827;
|
||||
letter-spacing: 0;
|
||||
page-break-after: avoid;
|
||||
}
|
||||
|
||||
h1 {
|
||||
font-size: 26pt;
|
||||
line-height: 1.05;
|
||||
margin-bottom: 8px;
|
||||
}
|
||||
|
||||
h2 {
|
||||
font-size: 15pt;
|
||||
margin-top: 22px;
|
||||
margin-bottom: 9px;
|
||||
padding-top: 2px;
|
||||
border-top: 1px solid #d8dee8;
|
||||
}
|
||||
|
||||
h3 {
|
||||
font-size: 11.5pt;
|
||||
margin-top: 14px;
|
||||
margin-bottom: 6px;
|
||||
}
|
||||
|
||||
p {
|
||||
margin: 0 0 8px;
|
||||
}
|
||||
|
||||
ul {
|
||||
margin: 6px 0 10px 18px;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
li {
|
||||
margin: 2px 0;
|
||||
}
|
||||
|
||||
table {
|
||||
width: 100%;
|
||||
border-collapse: collapse;
|
||||
margin: 7px 0 13px;
|
||||
page-break-inside: avoid;
|
||||
}
|
||||
|
||||
th,
|
||||
td {
|
||||
padding: 7px 8px;
|
||||
border: 1px solid #d8dee8;
|
||||
vertical-align: top;
|
||||
}
|
||||
|
||||
th {
|
||||
color: #111827;
|
||||
background: #eef3f8;
|
||||
font-weight: 700;
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
td.num,
|
||||
th.num {
|
||||
text-align: right;
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
.cover {
|
||||
min-height: 265px;
|
||||
padding: 28px 30px;
|
||||
color: #ffffff;
|
||||
background: linear-gradient(135deg, #12313f 0%, #1d5b63 58%, #7a5a20 100%);
|
||||
border-radius: 14px;
|
||||
margin-bottom: 18px;
|
||||
}
|
||||
|
||||
.cover h1,
|
||||
.cover p {
|
||||
color: #ffffff;
|
||||
}
|
||||
|
||||
.eyebrow {
|
||||
margin-bottom: 42px;
|
||||
font-size: 9pt;
|
||||
font-weight: 700;
|
||||
letter-spacing: .08em;
|
||||
text-transform: uppercase;
|
||||
opacity: .88;
|
||||
}
|
||||
|
||||
.subtitle {
|
||||
max-width: 560px;
|
||||
font-size: 12.5pt;
|
||||
line-height: 1.45;
|
||||
opacity: .94;
|
||||
}
|
||||
|
||||
.meta {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(3, 1fr);
|
||||
gap: 10px;
|
||||
margin-top: 26px;
|
||||
}
|
||||
|
||||
.meta div {
|
||||
padding: 10px 12px;
|
||||
background: rgba(255, 255, 255, .12);
|
||||
border: 1px solid rgba(255, 255, 255, .22);
|
||||
border-radius: 8px;
|
||||
}
|
||||
|
||||
.meta strong {
|
||||
display: block;
|
||||
margin-bottom: 3px;
|
||||
font-size: 8.5pt;
|
||||
text-transform: uppercase;
|
||||
opacity: .8;
|
||||
}
|
||||
|
||||
.lead {
|
||||
padding: 13px 15px;
|
||||
margin: 12px 0 16px;
|
||||
background: #f5f8fb;
|
||||
border: 1px solid #d8dee8;
|
||||
border-left: 4px solid #1d5b63;
|
||||
border-radius: 8px;
|
||||
}
|
||||
|
||||
.grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(2, 1fr);
|
||||
gap: 12px;
|
||||
margin: 8px 0 14px;
|
||||
}
|
||||
|
||||
.card {
|
||||
padding: 12px 13px;
|
||||
border: 1px solid #d8dee8;
|
||||
border-radius: 8px;
|
||||
background: #ffffff;
|
||||
page-break-inside: avoid;
|
||||
}
|
||||
|
||||
.card h3 {
|
||||
margin-top: 0;
|
||||
}
|
||||
|
||||
.pill {
|
||||
display: inline-block;
|
||||
padding: 2px 7px;
|
||||
border-radius: 999px;
|
||||
color: #174047;
|
||||
background: #dff1f1;
|
||||
font-size: 8.5pt;
|
||||
font-weight: 700;
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
.note {
|
||||
color: #435263;
|
||||
font-size: 9pt;
|
||||
}
|
||||
|
||||
.page-break {
|
||||
page-break-before: always;
|
||||
}
|
||||
|
||||
.source {
|
||||
color: #435263;
|
||||
font-size: 8.8pt;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<section class="cover">
|
||||
<div class="eyebrow">Arbeitsnotiz · Stand 04.07.2026</div>
|
||||
<h1>HiveGrid Pricing-Entwurf</h1>
|
||||
<p class="subtitle">Paketlogik, Zusatznutzer, Speicher, Email Marketing und Enterprise-Onboarding als aktuelle Preisrichtung. Alle Preise netto.</p>
|
||||
<div class="meta">
|
||||
<div><strong>Core</strong>in allen Paketen gleich</div>
|
||||
<div><strong>Sweet Spot</strong>Team-Paket</div>
|
||||
<div><strong>Add-ons</strong>nur für echten Mehrwert</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<div class="lead">
|
||||
<strong>Grundsatz:</strong> HiveGrid Core bleibt in allen Paketen gleich. Die Pakete unterscheiden sich durch inkludierte Nutzer, Skalierungslogik, Speicherpool und Enterprise-Service. Funktions-Upgrades laufen über optionale Add-ons wie Email Marketing, Speicher, Automationen, Kundenportal oder Premium Onboarding.
|
||||
</div>
|
||||
|
||||
<h2>Core-Pakete</h2>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Paket</th>
|
||||
<th class="num">Monatlich netto</th>
|
||||
<th class="num">Jahres-SEPA effektiv</th>
|
||||
<th>Inklusive Nutzer</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><strong>Starter</strong></td>
|
||||
<td class="num">199 €</td>
|
||||
<td class="num">179 € / Monat</td>
|
||||
<td>2 Büro + 5 Baustelle</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Team</strong> <span class="pill">Sweet Spot</span></td>
|
||||
<td class="num">499 €</td>
|
||||
<td class="num">449 € / Monat</td>
|
||||
<td>5 Büro + 15 Baustelle</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Business</strong></td>
|
||||
<td class="num">999 €</td>
|
||||
<td class="num">899 € / Monat</td>
|
||||
<td>10 Büro + 30 Baustelle</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Enterprise</strong></td>
|
||||
<td class="num">individuell</td>
|
||||
<td class="num">individuell</td>
|
||||
<td>ab ca. 50 Mitarbeitenden</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h2>Zusatznutzer</h2>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Zusatznutzer</th>
|
||||
<th class="num">Starter</th>
|
||||
<th class="num">Team</th>
|
||||
<th class="num">Business</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Büro</td>
|
||||
<td class="num">59 €</td>
|
||||
<td class="num">39 €</td>
|
||||
<td class="num">35 €</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Baustelle</td>
|
||||
<td class="num">25 €</td>
|
||||
<td class="num">19 €</td>
|
||||
<td class="num">15 €</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<div class="grid">
|
||||
<div class="card">
|
||||
<h3>Upsell-Logik</h3>
|
||||
<p>Starter ist fair zum Einstieg, aber teuer beim Skalieren. Team ist bei wachsendem Betrieb deutlich attraktiver.</p>
|
||||
<p class="note">Starter auf Team-Größe: 199 + 3 x 59 + 10 x 25 = 626 € / Monat. Team direkt: 499 € / Monat. Team-Vorteil: 127 € / Monat.</p>
|
||||
</div>
|
||||
<div class="card">
|
||||
<h3>Zahlungslogik</h3>
|
||||
<p>Monatliche Zahlung ist der Listenpreis. Jahreszahlung per SEPA-Lastschrift ist der beste sichtbare Preis.</p>
|
||||
<p class="note">Kommunikation: "Pakete ab 179 € / Monat bei Jahreszahlung per SEPA."</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<h2>Speicher-Modell</h2>
|
||||
<p>Speicher wird als Paket-Speicherpool verkauft. Zusätzliche Nutzer vergrößern den Pool automatisch. Das ist einfacher als ein reiner Preis pro GB oder pro User, bleibt aber fair für größere Betriebe.</p>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Paket</th>
|
||||
<th class="num">Inklusiv-Speicherpool</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr><td>Starter</td><td class="num">100 GB</td></tr>
|
||||
<tr><td>Team</td><td class="num">250 GB</td></tr>
|
||||
<tr><td>Business</td><td class="num">500 GB</td></tr>
|
||||
<tr><td>Enterprise</td><td class="num">ab 1 TB individuell</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Zusätzlicher Nutzer</th>
|
||||
<th class="num">Extra Speicherpool</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr><td>Büro</td><td class="num">+20 GB</td></tr>
|
||||
<tr><td>Baustelle</td><td class="num">+10 GB</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Speicher-Add-on</th>
|
||||
<th class="num">Preis netto</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr><td>+100 GB</td><td class="num">5 € / Monat</td></tr>
|
||||
<tr><td>+500 GB</td><td class="num">15 € / Monat</td></tr>
|
||||
<tr><td>+1 TB</td><td class="num">25 € / Monat</td></tr>
|
||||
<tr><td>+5 TB</td><td class="num">99 € / Monat</td></tr>
|
||||
<tr><td>+10 TB</td><td class="num">179 € / Monat</td></tr>
|
||||
<tr><td>>10 TB</td><td class="num">individuell</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<p class="source">Technische Basis: Hetzner Object Storage. Aktuelle Basis: 6,49 € / Monat inkl. ca. 1 TB Storage und ca. 1 TB Egress. Zusätzlicher Storage ca. 6,30-6,50 € pro TB/Monat, zusätzlicher Traffic 1 €/TB. Quellen: hetzner.com/storage/object-storage und docs.hetzner.com/storage/object-storage/overview.</p>
|
||||
|
||||
<h2 class="page-break">Email Marketing Add-on</h2>
|
||||
<p>Transaktionale Systemmails bleiben Core-Betriebskosten. Marketing-Mails werden separat verkauft. Nach aussen gibt es klare Von-bis-Staffeln, intern wird gegen Mailjet Premium kalkuliert.</p>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Add-on</th>
|
||||
<th>Volumen</th>
|
||||
<th class="num">Preis netto</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr><td>Email Marketing S</td><td>bis 10.000 Mails / Monat</td><td class="num">59 €</td></tr>
|
||||
<tr><td>Email Marketing M</td><td>10.001 bis 50.000 Mails / Monat</td><td class="num">149 €</td></tr>
|
||||
<tr><td>Email Marketing L</td><td>50.001 bis 100.000 Mails / Monat</td><td class="num">249 €</td></tr>
|
||||
<tr><td>Email Marketing XL</td><td>100.001 bis 250.000 Mails / Monat</td><td class="num">499 €</td></tr>
|
||||
<tr><td>Email Marketing XXL</td><td>250.001 bis 500.000 Mails / Monat</td><td class="num">899 €</td></tr>
|
||||
<tr><td>Enterprise Volume</td><td>>500.000 Mails / Monat</td><td class="num">individuell</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>HiveGrid Staffel</th>
|
||||
<th class="num">Umsatz</th>
|
||||
<th class="num">Mailjet-Kosten</th>
|
||||
<th class="num">Rohertrag</th>
|
||||
<th class="num">Rohertragsmarge</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr><td>bis 10.000</td><td class="num">59 €</td><td class="num">25 €</td><td class="num">34 €</td><td class="num">57,6 %</td></tr>
|
||||
<tr><td>bis 50.000</td><td class="num">149 €</td><td class="num">50 €</td><td class="num">99 €</td><td class="num">66,4 %</td></tr>
|
||||
<tr><td>bis 100.000</td><td class="num">249 €</td><td class="num">95 €</td><td class="num">154 €</td><td class="num">61,8 %</td></tr>
|
||||
<tr><td>bis 250.000</td><td class="num">499 €</td><td class="num">230 €</td><td class="num">269 €</td><td class="num">53,9 %</td></tr>
|
||||
<tr><td>bis 500.000</td><td class="num">899 €</td><td class="num">430 €</td><td class="num">469 €</td><td class="num">52,2 %</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<p class="note">Overage-Regel: keine kleinteilige Pro-Mail-Abrechnung nach außen. Bei dauerhafter Überschreitung Wechsel in die nächste Staffel. Optional einmalig: 10 € je zusätzliche 1.000 Marketing-Mails oder Kulanz im ersten Monat.</p>
|
||||
<p class="source">Quelle für Kostenbasis: mailjet.com/pricing, geprüft am 04.07.2026. Premium-Plan in EUR: 15k 25 €, 50k 50 €, 100k 95 €, 250k 230 €, 500k 430 € monatlich.</p>
|
||||
|
||||
<h2 class="page-break">Enterprise</h2>
|
||||
<div class="lead">
|
||||
<strong>Enterprise ist kein billigeres großes Paket.</strong> Enterprise wird über betreute Einführung, Sicherheit, Verbindlichkeit und individuelles Setup verkauft.
|
||||
</div>
|
||||
|
||||
<h3>Pflichtbestandteil</h3>
|
||||
<ul>
|
||||
<li>Premium Onboarding, einmalig oder im ersten Vertragsjahr eingepreist</li>
|
||||
</ul>
|
||||
|
||||
<h3>Moegliche Bestandteile</h3>
|
||||
<ul>
|
||||
<li>Kickoff und Prozessaufnahme</li>
|
||||
<li>Datenimport / Datenmigration</li>
|
||||
<li>Rollen- und Rechte-Setup</li>
|
||||
<li>Schulung für Büro-Team</li>
|
||||
<li>Schulung für Bauleiter / Baustelle</li>
|
||||
<li>Go-live-Begleitung</li>
|
||||
<li>fester Ansprechpartner in der Einführungsphase</li>
|
||||
<li>größerer Speicherpool, individuelles E-Mail-Volumen, SLA oder priorisierter Support</li>
|
||||
</ul>
|
||||
|
||||
<h2>Weitere Add-ons</h2>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Add-on</th>
|
||||
<th>Preislogik</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr><td>Kundenportal</td><td>monatlich pro Betrieb</td></tr>
|
||||
<tr><td>Erweiterte Automationen</td><td>monatlich pro Betrieb</td></tr>
|
||||
<tr><td>Dokumenten-/Angebotsautomation</td><td>monatlich pro Betrieb</td></tr>
|
||||
<tr><td>Controlling / BI</td><td>monatlich pro Betrieb</td></tr>
|
||||
<tr><td>API / Integrationen</td><td>monatlich oder nach Nutzung</td></tr>
|
||||
<tr><td>Datenmigration</td><td>einmalig</td></tr>
|
||||
<tr><td>Schulung</td><td>einmalig oder Paketpreis</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h2>Empfohlene Kommunikation</h2>
|
||||
<div class="lead">
|
||||
Alle Pakete enthalten den vollständigen HiveGrid Core. Starte ab 179 € / Monat bei jährlicher Zahlung per SEPA. Büro- und Baustellen-Nutzer können flexibel ergänzt werden. Zusatzmodule wie Email Marketing, Cloud-Speicher oder Premium Onboarding buchst du nur dazu, wenn du sie brauchst.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
Binary file not shown.
@@ -0,0 +1,151 @@
|
||||
# KWP API: lizenzierter HiveGrid-Scope
|
||||
|
||||
> Generiert aus der am 2026-07-24 secretsicher gelesenen Tenant-OpenAPI. Die kundenspezifische
|
||||
> Roh-Spezifikation, Server-URL und Credentials werden nicht eingecheckt.
|
||||
|
||||
## Inventur
|
||||
|
||||
- OpenAPI-Operationen gesamt: **554**
|
||||
- Über die fünf HiveGrid-`*-extern`-Scopes erreichbar: **113**
|
||||
- Semantisch lesend und runtime-allowlisted: **77**
|
||||
- Mutierend, nur Contract/Fixture und runtime-gesperrt: **36**
|
||||
- Außerhalb des lizenzierten HiveGrid-Scopes: **441**
|
||||
|
||||
| Capability | Gesamt | Read | Mutation |
|
||||
| ---------- | -----: | ---: | -------: |
|
||||
| activity | 30 | 14 | 16 |
|
||||
| address | 23 | 15 | 8 |
|
||||
| archive | 14 | 11 | 3 |
|
||||
| project | 32 | 27 | 5 |
|
||||
| schedule | 14 | 10 | 4 |
|
||||
|
||||
Die OpenAPI-Security-Arrays nennen mehrere alternative KWP-Produkte und die fünf externen Scopes, obwohl
|
||||
die OAuth-Flow-Scope-Liste diese externen Namen nicht aufführt. HiveGrid klassifiziert eine Operation nur
|
||||
dann als scoped, wenn mindestens einer der fünf tatsächlich angeforderten externen Scopes am Endpoint steht.
|
||||
|
||||
## Sicherheitsvertrag
|
||||
|
||||
- Fachcode übergibt nur eine feste Operation-ID plus deren typisierten Input, niemals URL, Pfad, Token,
|
||||
Mandant oder Kundenkürzel.
|
||||
- `Search`, `Load`, `Count`, `Get` und `Check` können trotz `POST` read-only sein.
|
||||
- `Save`, `Add`, `Delete`, `Remove`, `Import`, `Publish` und `Reset` sind Mutation.
|
||||
- Mutation wird vor Rate-Budget, Relay-Auflösung und HTTP blockiert.
|
||||
- Der Scoped-Contract enthält nur rekursiv benötigte Schemas und keine tenant-spezifische Server-URL.
|
||||
|
||||
## Operationen
|
||||
|
||||
| ID | Capability | Modus | Methode | Pfad | KWP-Zusammenfassung |
|
||||
| ---------------------------------------------------------- | ---------- | -------- | -------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `aktivitaetAddAktivitaet` | activity | mutation | `POST` | `/api/Aktivitaet/AddAktivitaet` | Fuegt eine neue Aktivitaet mit allen Eigenschaften hinzu. |
|
||||
| `aktivitaetAddAktivitaetBase` | activity | mutation | `POST` | `/api/Aktivitaet/AddAktivitaetBase` | Fuegt eine neue Aktivitaet mit eingeschraenkten Eigenschaften hinzu. |
|
||||
| `aktivitaetAddHilfreich` | activity | mutation | `POST` | `/api/Aktivitaet/AddHilfreich` | Setzt eine Aktivitaet fuer den aktuellen Benutzer auf hilfreich |
|
||||
| `aktivitaetAddInfoEintrag` | activity | mutation | `POST` | `/api/Aktivitaet/AddInfoEintrag` | Fuegt einer bestehenden Aktivitaet einen neuen Info-Eintrag hinzu und gibt die Id des Datensatzes zurueck. |
|
||||
| `aktivitaetAddVerknuepfung` | activity | mutation | `POST` | `/api/Aktivitaet/AddVerknuepfung` | Legt eine neue Verknuepfung zwischen zwei Aktivitaeten (Parent und Child) an |
|
||||
| `aktivitaetAddZusatzadresse` | activity | mutation | `POST` | `/api/Aktivitaet/AddZusatzadresse` | Legt eine neue Zusatzadresse zu einer Aktivitaet an |
|
||||
| `aktivitaetDeleteHilfreich` | activity | mutation | `POST` | `/api/Aktivitaet/DeleteHilfreich` | Loescht einen vorhandenen Hilfreich-Eintrag |
|
||||
| `aktivitaetDeleteInfoEintrag` | activity | mutation | `DELETE` | `/api/Aktivitaet/DeleteInfoEintrag` | Loescht einen bestehenden Infoeintrag |
|
||||
| `aktivitaetDeleteVerknuepfung` | activity | mutation | `POST` | `/api/Aktivitaet/DeleteVerknuepfung` | Loescht eine Verknuepfung zwischen zwei Aktivitaeten |
|
||||
| `aktivitaetDeleteZusatzadresse` | activity | mutation | `POST` | `/api/Aktivitaet/DeleteZusatzadresse` | Loescht eine vorhandene Zusatzadresse |
|
||||
| `aktivitaetLoadAktivitaetTerminIdGet` | activity | read | `GET` | `/api/Aktivitaet/LoadAktivitaetTerminId` | Laedt die TerminId eines Termins anhand einer AktivitaetenId |
|
||||
| `aktivitaetLoadAktivitaetTerminIdPost` | activity | read | `POST` | `/api/Aktivitaet/LoadAktivitaetTerminId` | Laedt die TerminId eines Termins anhand einer AktivitaetenId |
|
||||
| `aktivitaetLoadArten` | activity | read | `GET` | `/api/Aktivitaet/LoadArten` | Gibt eine Auflistung von Aktivitaetenarten zurueck. |
|
||||
| `aktivitaetLoadKennzeichen` | activity | read | `GET` | `/api/Aktivitaet/LoadKennzeichen` | Gibt eine Auflistung von Aktivitaetenkennzeichen zurueck. |
|
||||
| `aktivitaetSaveAktivitaetProperties` | activity | mutation | `POST` | `/api/Aktivitaet/SaveAktivitaetProperties` | Speichert eine oder mehrere Properties der Aktivitaet. |
|
||||
| `aktivitaetSaveInfoEintrag` | activity | mutation | `POST` | `/api/Aktivitaet/SaveInfoEintrag` | Speichert einen bestehenden Infoeintrag ab. |
|
||||
| `aktivitaetSaveInformierteBenutzer` | activity | mutation | `POST` | `/api/Aktivitaet/SaveInformierteBenutzer` | Speichert die Liste der zu informierenden Benutzer |
|
||||
| `aktivitaetSaveInformierteBenutzerProperties` | activity | mutation | `POST` | `/api/Aktivitaet/SaveInformierteBenutzerProperties` | Speichert eine oder mehrere Properties des zu informierenden Benutzers. |
|
||||
| `aktivitaetSaveZusatzadresse` | activity | mutation | `POST` | `/api/Aktivitaet/SaveZusatzadresse` | Speichert die Bemerkung zu einer vorhandenen Zusatzadresse |
|
||||
| `aktivitaetenverwaltungCount` | activity | read | `POST` | `/api/Aktivitaetenverwaltung/Count` | Zaehlt Aktivitaeten anhand eines oder mehrerer Suchbegriffe |
|
||||
| `aktivitaetenverwaltungGetSetup` | activity | read | `GET` | `/api/Aktivitaetenverwaltung/GetSetup` | Liefert die Setup-Konfiguration zur initialen Anzeige der Aktivitaetenverwaltung-PWA |
|
||||
| `aktivitaetenverwaltungLoadAdressen` | activity | read | `GET` | `/api/Aktivitaetenverwaltung/LoadAdressen` | Liefert die zur Aktivitaet verknuepften Adressen |
|
||||
| `aktivitaetenverwaltungLoadAktivitaet` | activity | read | `GET` | `/api/Aktivitaetenverwaltung/LoadAktivitaet` | Liefert die Aktivitaet zur uebergebenen Id |
|
||||
| `aktivitaetenverwaltungLoadAktivitaeten` | activity | read | `GET` | `/api/Aktivitaetenverwaltung/LoadAktivitaeten` | Liefert die Aktivaeten gemaess den Parametern |
|
||||
| `aktivitaetenverwaltungLoadAktivitaetenByAdresskuerzel` | activity | read | `GET` | `/api/Aktivitaetenverwaltung/LoadAktivitaetenByAdresskuerzel` | Liefert die vom Parameter Count spezifizierte Anzahl vom Offset an Aktivaeten zu einer bestimmten Adresse |
|
||||
| `aktivitaetenverwaltungLoadAktivitaetenByVorgang` | activity | read | `GET` | `/api/Aktivitaetenverwaltung/LoadAktivitaetenByVorgang` | Liefert die vom Parameter Count spezifizierte Anzahl vom Offset an Aktivaeten zu einem bestimmten Vorgang |
|
||||
| `aktivitaetenverwaltungLoadEinstellungen` | activity | read | `GET` | `/api/Aktivitaetenverwaltung/LoadEinstellungen` | Laedt die Einstellungen zur Aktivitaetenverwaltung |
|
||||
| `aktivitaetenverwaltungLoadVerknuepfungen` | activity | read | `GET` | `/api/Aktivitaetenverwaltung/LoadVerknuepfungen` | Liefert den Baum aller verknuepften Aktivitaeten ausgehend der Aktivitaeten-Id |
|
||||
| `aktivitaetenverwaltungSaveEinstellungen` | activity | mutation | `POST` | `/api/Aktivitaetenverwaltung/SaveEinstellungen` | Speichert die uebergebenen Einstellungen |
|
||||
| `aktivitaetenverwaltungSearch` | activity | read | `POST` | `/api/Aktivitaetenverwaltung/Search` | Sucht Aktivitaeten anhand eines oder mehrerer Suchbegriffe |
|
||||
| `adresseAddAdresse` | address | mutation | `POST` | `/api/Adresse/AddAdresse` | Legt eine neue Adresse an |
|
||||
| `adresseAddAnsprechpartner` | address | mutation | `POST` | `/api/Adresse/AddAnsprechpartner` | Fuegt einer Adresse einen neuen Ansprechpartner hinzu |
|
||||
| `adresseAddKontakt` | address | mutation | `POST` | `/api/Adresse/AddKontakt` | Fuegt einer Adresse einen neuen Kontakt hinzu |
|
||||
| `adresseCheckDebitKreditNummerVergeben` | address | read | `POST` | `/api/Adresse/CheckDebitKreditNummerVergeben` | Ueberprueft die eingegebene DebitKreditNummer |
|
||||
| `adresseGetDebitKreditNummer` | address | read | `POST` | `/api/Adresse/GetDebitKreditNummer` | Ermittelt die naechste DebitKreditNummer |
|
||||
| `adresseGetGeoLocation` | address | read | `POST` | `/api/Adresse/GetGeoLocation` | Laedt die Geo Koordinaten zu einer Adresse |
|
||||
| `adresseGetSetup` | address | read | `GET` | `/api/Adresse/GetSetup` | Liefert die Setup-Konfiguration zur initialen Anzeige der Adress-APP |
|
||||
| `adresseLoadAdressDetails` | address | read | `GET` | `/api/Adresse/LoadAdressDetails` | Laedt eine Adresse anhand des Adresskuerzels |
|
||||
| `adresseLoadAdressKomplett` | address | read | `GET` | `/api/Adresse/LoadAdressKomplett` | Laedt eine komplette Adresse anhand des Adresskuerzels inkl. Kontakte und Ansprechpartner |
|
||||
| `adresseLoadAnreden` | address | read | `GET` | `/api/Adresse/LoadAnreden` | Liefert verwendeten Anreden |
|
||||
| `adresseLoadAnruferInformation` | address | read | `GET` | `/api/Adresse/LoadAnruferInformation` | Laedt zu einer uebergebenen Telefonnummer die potentiellen Adressen |
|
||||
| `adresseLoadAnsprechpartnerById` | address | read | `GET` | `/api/Adresse/LoadAnsprechpartnerById` | Laedt einen Ansprechpartner via ID |
|
||||
| `adresseLoadBriefanreden` | address | read | `GET` | `/api/Adresse/LoadBriefanreden` | Liefert angelegte Briefanreden |
|
||||
| `adresseLoadSelekts` | address | read | `GET` | `/api/Adresse/LoadSelekts` | Laedt alle verwendeten Selekts |
|
||||
| `adresseLoadWunschtermine` | address | read | `GET` | `/api/Adresse/LoadWunschtermine` | Liefert die Wunschtermine zu einer Adresse |
|
||||
| `adresseRemoveAnsprechpartner` | address | mutation | `POST` | `/api/Adresse/RemoveAnsprechpartner` | Entfernt einen Ansprechpartner |
|
||||
| `adresseRemoveKontakt` | address | mutation | `POST` | `/api/Adresse/RemoveKontakt` | Entfernt einen Kontakt |
|
||||
| `adresseSaveAdresse` | address | mutation | `POST` | `/api/Adresse/SaveAdresse` | Aendert eine bestehende Adresse |
|
||||
| `adresseSaveAnsprechpartner` | address | mutation | `POST` | `/api/Adresse/SaveAnsprechpartner` | Aendert einen bestehenden Kontakt |
|
||||
| `adresseSaveKontakt` | address | mutation | `POST` | `/api/Adresse/SaveKontakt` | Aendert einen bestehenden Kontakt |
|
||||
| `adresseSearch` | address | read | `POST` | `/api/Adresse/Search` | Sucht Adressen, Kontakte und Ansprechpartner anhand eines Suchbegriffs |
|
||||
| `adresseSearchBenutzerfeldInhalt` | address | read | `POST` | `/api/Adresse/SearchBenutzerfeldInhalt` | Sucht fuer den uebergebenen Benutzerfeldindex (1-5) zum Suchbegriff passende Benutzerfeldinhalte |
|
||||
| `adresseSearchKontakt` | address | read | `POST` | `/api/Adresse/SearchKontakt` | Sucht Adressen anhand eines oder mehrerer Suchbegriffe. Dabei wird das Ergebnis auf die uebergebenen Kontaktarten gefiltert |
|
||||
| `archivExternalCountHeader` | archive | read | `GET` | `/api/archiv-extern/CountHeader` | Ermittelt fuer die uebergebene Bezugsart/-Nummer die Anzahl der Archiv-Eintraege (nur Header, nicht Dateien) |
|
||||
| `archivExternalDeleteEintrag` | archive | mutation | `DELETE` | `/api/archiv-extern/DeleteEintrag` | Loescht einen bestehenden ArchivEintrag samt Dateien |
|
||||
| `archivExternalExportDatei` | archive | read | `GET` | `/api/archiv-extern/ExportDatei` | Fordert die Bereitstellung der gewuenschten Datei an |
|
||||
| `archivExternalGetBezug` | archive | read | `GET` | `/api/archiv-extern/GetBezug` | Liefert fuer einen Bezug die standardmaessigen Archiv-Bezuege |
|
||||
| `archivExternalGetSetup` | archive | read | `GET` | `/api/archiv-extern/GetSetup` | Liefert die Setup-Konfiguration zur initialen Anzeige der Archiv-APP |
|
||||
| `archivExternalImportAdditionalDatei` | archive | mutation | `POST` | `/api/archiv-extern/ImportAdditionalDatei` | Fuegt einem bestehenden Archiveintrag eine weitere Datei hinzu |
|
||||
| `archivExternalImportDatei` | archive | mutation | `POST` | `/api/archiv-extern/ImportDatei` | Importiert aus einem Azure-Storage eine Datei |
|
||||
| `archivExternalLoadDateienByVerzeichnisId` | archive | read | `GET` | `/api/archiv-extern/LoadDateienByVerzeichnisId` | Laedt Datei-Informationen fuer das optionale angegebene Verzeichnis mit Paging |
|
||||
| `archivExternalLoadEinstellungen` | archive | read | `GET` | `/api/archiv-extern/LoadEinstellungen` | Laedt die benutzerbezogenen Einstellungen zum Archiv |
|
||||
| `archivExternalLoadEintragDetails` | archive | read | `GET` | `/api/archiv-extern/LoadEintragDetails` | Laedt die Archiveintragdetails zurueck |
|
||||
| `archivExternalLoadLetzteRevisionArchivEintragFilesForIds` | archive | read | `POST` | `/api/archiv-extern/LoadLetzteRevisionArchivEintragFilesForIds` | Laedt die letzten ArchivEintragFiles fuer die uebergebenen ArchivfilesIds |
|
||||
| `archivExternalLoadVerzeichnisse` | archive | read | `GET` | `/api/archiv-extern/LoadVerzeichnisse` | Laedt Verzeichnisse und die Anzahl der darin enthaltenen Dateien (gemaess Filter) |
|
||||
| `archivExternalSearchDateienByVerzeichnisId` | archive | read | `GET` | `/api/archiv-extern/SearchDateienByVerzeichnisId` | Sucht Datei-Informationen fuer das optionale angegebene Verzeichnis mit Paging und Suchbegriffen |
|
||||
| `archivExternalSearchVorgaenge` | archive | read | `POST` | `/api/archiv-extern/SearchVorgaenge` | Sucht die Top 10 Vorgaenge anhand eines Suchbegriffs des jeweilig moeglichen Bezugs |
|
||||
| `projektLoad` | project | read | `GET` | `/api/Projekt/Load` | Laedt Projektbezeichnung und Projektnummer zu einer uebergebenen Projektnummer, sofern der Anwender zm lesen berechtigt ist |
|
||||
| `projektLoadKategorien` | project | read | `GET` | `/api/Projekt/LoadKategorien` | Laedt die verwendeten Projekt-Kategorien |
|
||||
| `projektLoadSachbearbeiter` | project | read | `GET` | `/api/Projekt/LoadSachbearbeiter` | Laedt die verwendenten Projekt-Sachbearbeiter |
|
||||
| `projektSave` | project | mutation | `POST` | `/api/Projekt/Save` | Speichert fuer ein Projekt eine neue Bezeichnung |
|
||||
| `projektSearch` | project | read | `POST` | `/api/Projekt/Search` | Sucht ein Projekt anhand eines Suchbegriffs und liefert lesbaren Projekte |
|
||||
| `projektampelGetSetup` | project | read | `GET` | `/api/Projektampel/GetSetup` | Liefert die Setup-Konfiguration zur initialen Anzeige der Projektampel-PWA |
|
||||
| `projektampelLoadBenutzerDetails` | project | read | `GET` | `/api/Projektampel/LoadBenutzerDetails` | Laedt die Projektampelspezifischen Details zu einem Benutzer |
|
||||
| `projektampelLoadBenutzerNachFilter` | project | read | `GET` | `/api/Projektampel/LoadBenutzerNachFilter` | Laedt eine Liste von Benutzerplatzhaltern gemaeß den gesetzten Einstellungen |
|
||||
| `projektampelLoadEinstellungen` | project | read | `GET` | `/api/Projektampel/LoadEinstellungen` | Laedt die benutzerbezogenen Einstellungen zur Projektampel |
|
||||
| `projektampelLoadProjektDetailsGet` | project | read | `GET` | `/api/Projektampel/LoadProjektDetails` | Laedt die projektampelspezifischen Details zu einer Projektnummer |
|
||||
| `projektampelLoadProjektDetailsPost` | project | read | `POST` | `/api/Projektampel/LoadProjektDetails` | Laedt die projektampelspezifischen Details zu einer Projektnummer |
|
||||
| `projektampelLoadProjekteNachFilter` | project | read | `GET` | `/api/Projektampel/LoadProjekteNachFilter` | Laedt eine Liste von Projektplatzhaltern gemaeß den gesetzten Einstellungen |
|
||||
| `projektampelResetBenutzergruppenFilter` | project | mutation | `POST` | `/api/Projektampel/ResetBenutzergruppenFilter` | Setzt die Einstellungen fuer den benutzergruppenbezogenen Filter zurueck |
|
||||
| `projektampelResetProjektFilter` | project | mutation | `POST` | `/api/Projektampel/ResetProjektFilter` | Setzt die benutzerbezogenen Einstellungen fuer den projektbezogenen Filter zurueck |
|
||||
| `projektampelSaveEinstellungen` | project | mutation | `POST` | `/api/Projektampel/SaveEinstellungen` | Speichert die uebergebenen benutzerbezogenen Einstellungen |
|
||||
| `projektampelSearch` | project | read | `POST` | `/api/Projektampel/Search` | Sucht ein Projekt anhand eines Suchbegriffs |
|
||||
| `vorgangAnzeigeGetSetup` | project | read | `GET` | `/api/VorgangAnzeige/GetSetup` | Liefert das Setup fuer die Vorgangsanzeige |
|
||||
| `vorgangAnzeigeLoadAdressen` | project | read | `GET` | `/api/VorgangAnzeige/LoadAdressen` | Laedt die Adressen zum Vorgang |
|
||||
| `vorgangAnzeigeLoadAngebote` | project | read | `POST` | `/api/VorgangAnzeige/LoadAngebote` | Laedt die Angebote zum Vorgang |
|
||||
| `vorgangAnzeigeLoadAnzahlen` | project | read | `GET` | `/api/VorgangAnzeige/LoadAnzahlen` | Laedt die Anzahlen der verkuepften Vorgaenge |
|
||||
| `vorgangAnzeigeLoadBestellungen` | project | read | `POST` | `/api/VorgangAnzeige/LoadBestellungen` | Laedt die Bestellungen zum Vorgang |
|
||||
| `vorgangAnzeigeLoadDetails` | project | read | `GET` | `/api/VorgangAnzeige/LoadDetails` | Laedt die Details zum Vorgang |
|
||||
| `vorgangAnzeigeLoadEingangsrechnungen` | project | read | `POST` | `/api/VorgangAnzeige/LoadEingangsrechnungen` | Laedt die Eingangsrechnungen zum Vorgang |
|
||||
| `vorgangAnzeigeLoadMontageauftraege` | project | read | `POST` | `/api/VorgangAnzeige/LoadMontageauftraege` | Laedt die Montageauftraege zum Vorgang |
|
||||
| `vorgangAnzeigeLoadNachtraege` | project | read | `POST` | `/api/VorgangAnzeige/LoadNachtraege` | Laedt die Nachtraege zum Projekt |
|
||||
| `vorgangAnzeigeLoadPositionen` | project | read | `POST` | `/api/VorgangAnzeige/LoadPositionen` | Laedt die Positionen zum Vorgang |
|
||||
| `vorgangAnzeigeLoadRechnungen` | project | read | `POST` | `/api/VorgangAnzeige/LoadRechnungen` | Laedt die Rechnungen zum Vorgang |
|
||||
| `vorgangAnzeigeLoadRegieauftraege` | project | read | `POST` | `/api/VorgangAnzeige/LoadRegieauftraege` | Laedt die Regieauftraege zum Projekt |
|
||||
| `vorgangAnzeigeLoadTableMeta` | project | read | `GET` | `/api/VorgangAnzeige/LoadTableMeta` | Laedt den benutzerdefinierten Tabellenaufbau |
|
||||
| `vorgangAnzeigeLoadVorgaenge` | project | read | `GET` | `/api/VorgangAnzeige/LoadVorgaenge` | Laedt dem Benutzer zugewiesene Auftraege und die Favoriten des Benutzers |
|
||||
| `vorgangAnzeigeSaveTableMeta` | project | mutation | `POST` | `/api/VorgangAnzeige/SaveTableMeta` | Speichert den benutzerdefinierten Tabellenaufbau |
|
||||
| `vorgangInfoLoadVorgangInfo` | project | read | `GET` | `/api/VorgangInfo/LoadVorgangInfo` | Laedt zu einem uebergebenen Vorgang die zum Stempeln noetigen Informationenen |
|
||||
| `monteursteuerungGetSetup` | schedule | read | `GET` | `/api/Monteursteuerung/GetSetup` | Liefert die Setup-Konfiguration zur initialen Anzeige der Monteutsteuerung-APP |
|
||||
| `monteursteuerungLoadTermine` | schedule | read | `POST` | `/api/Monteursteuerung/LoadTermine` | Laedt alle Termine des uebergebenen Filters im Zeitraum |
|
||||
| `monteursteuerungLoadTermineProjektplanung` | schedule | read | `POST` | `/api/Monteursteuerung/LoadTermineProjektplanung` | Laedt alle Projekt-Termine des uebergebenen Filters im Zeitraum |
|
||||
| `terminDeleteTermin` | schedule | mutation | `POST` | `/api/Termin/DeleteTermin` | Loescht einen bestehenden Termin |
|
||||
| `terminGetTeilnehmerverfuegbargeit` | schedule | read | `POST` | `/api/Termin/GetTeilnehmerverfuegbargeit` | prueft ob die Terminteilnehmer im angegebenen Zeitraum verfuegbar sind |
|
||||
| `terminGetTerminUeberschneidungen` | schedule | read | `POST` | `/api/Termin/GetTerminUeberschneidungen` | prueft einen Termin auf Terminueberschneidungen |
|
||||
| `terminLoadEigeneTermine` | schedule | read | `GET` | `/api/Termin/LoadEigeneTermine` | Laedt alle eigene Termine des aktuellen Benutzers (inkl. des korrespondierenden Monteures) im Zeitraum |
|
||||
| `terminLoadFeiertage` | schedule | read | `GET` | `/api/Termin/LoadFeiertage` | Laedt die Feiertage im Zeitraum |
|
||||
| `terminLoadLastWartungAuftragTerminIntervall` | schedule | read | `GET` | `/api/Termin/LoadLastWartungAuftragTerminIntervall` | Liefert den letzten Termin der automatisch im WW durch ein Intervall erzeugt wurde |
|
||||
| `terminLoadTerminById` | schedule | read | `GET` | `/api/Termin/LoadTerminById` | Laedt einen Termin zur uebergebenen TerminId |
|
||||
| `terminLoadTermine` | schedule | read | `GET` | `/api/Termin/LoadTermine` | Laedt alle Termine des uebergebenen Teilnehmers im Zeitraum |
|
||||
| `terminPublishTermin` | schedule | mutation | `POST` | `/api/Termin/PublishTermin` | Veroeffentlicht einen Termin |
|
||||
| `terminSaveTermin` | schedule | mutation | `POST` | `/api/Termin/SaveTermin` | speichert einen Termin |
|
||||
| `terminSaveTerminAktivitaet` | schedule | mutation | `POST` | `/api/Termin/SaveTerminAktivitaet` | speichert eine Termin-Aktivitaet, dabei wird einem neuen oder bestehenden Termin eine dazugehoerige Terminaktivitaet erzeugt |
|
||||
@@ -7,7 +7,7 @@ Use this guide after the first quickstart bootstrap when you are working in the
|
||||
Install and run these local services before starting the application:
|
||||
|
||||
- Node.js compatible with the repository runtime expectation.
|
||||
- Corepack with the pinned package manager, `pnpm@10.33.0`.
|
||||
- Corepack with the pinned package manager, `pnpm@11.12.0`.
|
||||
- PostgreSQL for the Prisma-backed application database.
|
||||
- Optional Redis only when queue or worker behavior is in scope.
|
||||
|
||||
@@ -15,7 +15,7 @@ Activate the pinned package manager from the repository root:
|
||||
|
||||
```sh
|
||||
corepack enable
|
||||
corepack prepare pnpm@10.33.0 --activate
|
||||
corepack prepare pnpm@11.12.0 --activate
|
||||
pnpm install
|
||||
```
|
||||
|
||||
@@ -79,10 +79,10 @@ pnpm run permissions:sync
|
||||
Start the `@hivegrid/web` React Router runtime from the root script; source lives in `apps/web/app`:
|
||||
|
||||
```sh
|
||||
pnpm dev
|
||||
pnpm dev:local
|
||||
```
|
||||
|
||||
Open `http://app.localhost:3000` for the tenant app and `http://admin.localhost:3000` for admin. The root `pnpm dev` command starts only the `@hivegrid/web` runtime; when API work is in scope, run `pnpm --filter @hivegrid/api dev` separately and open `http://api.localhost:3001`. Seeded accounts and placeholder credentials are development conveniences only and must not be reused in production.
|
||||
Open `http://app.localhost:3000` for the tenant app and `http://admin.localhost:3000` for admin. The canonical local admin login is always `admin@email.com` / `password`. Before starting the web runtime, `pnpm dev:local` restores that sole local platform admin with the `SuperAdmin` role and normalizes every password-backed platform or portal user in the disposable local database to `password`; passwordless identities remain passwordless. The command fails closed for CI, deployed environments, RLS-required runtimes, non-loopback databases, connection-string query parameters, and databases without the disposable-local marker. Fresh `pnpm dev:services` databases get the marker during initialization; for an existing local Compose volume, run `pnpm dev:services:mark-local` once. The raw `pnpm dev` command skips this local credential contract. Local placeholder credentials must never be reused in staging or production.
|
||||
|
||||
## Optional API and worker notes
|
||||
|
||||
|
||||
@@ -1,81 +0,0 @@
|
||||
# Migration Registry
|
||||
|
||||
## Purpose
|
||||
|
||||
This registry is the release-facing index for migrations that need explicit ownership, deadlines, rollback notes, and verification evidence before a release is cut. It covers documentation, operational, configuration, and database-affecting migration contracts, but each entry must state its real surface and must not imply that a documentation-only change is a runtime database migration.
|
||||
|
||||
Use this registry with the existing runbooks:
|
||||
|
||||
- [`docs/database.md`](./database.md) for PostgreSQL, Prisma, backup, restore, migration-status, and redacted database diagnostics.
|
||||
- [`docs/upgrades.md`](./upgrades.md) for the deeper upgrade workflow and manual runtime boundaries.
|
||||
- [`docs/deployment.md`](./deployment.md) for image, tag, Coolify, health, rollback, and manual deployment evidence.
|
||||
- [`docs/security.md`](./security.md) for secret redaction, incident evidence, provider boundaries, and data-handling prohibitions.
|
||||
- [`docs/versioning.md`](./versioning.md) for SemVer, changelog, breaking-change, deprecation, rollback, and verification expectations.
|
||||
|
||||
## Entry schema
|
||||
|
||||
Each registry row must include:
|
||||
|
||||
- **ID:** stable migration identifier, usually milestone/slice/task or release-entry scoped.
|
||||
- **Surface:** affected documentation, database, deployment, configuration, API, worker, provider, or security surface.
|
||||
- **Risk:** `docs-only`, `low`, `medium`, `high`, or `critical` based on rollback complexity, data impact, security sensitivity, and operator coordination.
|
||||
- **Owner:** accountable maintainer, release role, or owning team. Do not leave owner blank.
|
||||
- **Status:** one value from the status vocabulary below.
|
||||
- **Deadline:** release, date, or explicit release window by which the migration must be resolved.
|
||||
- **Rollback:** safest rollback or revert path, including whether backup restore or prior artifact redeploy is required.
|
||||
- **Verification evidence:** non-secret command output summary, checklist result, artifact/tag identifier, or manual-runtime note.
|
||||
- **Redaction notes:** specific data that must stay out of the registry and linked release evidence.
|
||||
|
||||
Optional extended fields for detailed entries include dependencies, reviewer, affected tenants or customers described only as generic labels, and links to release notes or runbooks.
|
||||
|
||||
## Status vocabulary
|
||||
|
||||
| Status | Meaning |
|
||||
| --- | --- |
|
||||
| `proposed` | Identified but not yet accepted for the release. |
|
||||
| `planned` | Accepted for the release with an owner and deadline. |
|
||||
| `in-progress` | Implementation or documentation work is active. |
|
||||
| `blocked` | Cannot proceed without an explicit dependency or decision. |
|
||||
| `verified` | Implementation is complete and the stated non-secret verification evidence exists. |
|
||||
| `rolled-back` | Reverted or restored through the documented rollback path. |
|
||||
| `superseded` | Replaced by a newer registry entry or release decision. |
|
||||
|
||||
Rows must not use vague placeholders such as unresolved markers. If a deadline or owner is unknown, keep the row in `proposed` status and add a concrete decision needed in the redaction or notes field without using placeholder marker text.
|
||||
|
||||
## Risk classification
|
||||
|
||||
- `docs-only`: documentation roots, release templates, checklists, or registry entries that do not change runtime behavior or persisted data.
|
||||
- `low`: reversible configuration or packaging changes with no stored-data impact and clear static verification.
|
||||
- `medium`: deployment, runtime, or provider-boundary changes that require coordinated rollout or manual runtime inspection.
|
||||
- `high`: database, queue, authentication, authorization, or security changes where rollback may require prior artifacts, queue controls, or backup/restore confirmation.
|
||||
- `critical`: destructive or externally visible changes where rollback is not automatic, requires production incident coordination, or can expose sensitive data if mishandled.
|
||||
|
||||
Database-affecting entries must link back to [`docs/database.md`](./database.md), use parameterized or ORM-safe migration paths where applicable, and record only redacted migration-status or deployment evidence.
|
||||
|
||||
## Registry table
|
||||
|
||||
| ID | Migration entry | Surface | Risk | Affected surfaces | Owner | Status | Deadline | Rollback | Verification evidence | Redaction notes |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| Release Docs-S03-T01 | Canonical upgrade-guide root at [`docs/upgrade.md`](./upgrade.md). | Documentation | docs-only | Upgrade entrypoint, release-upgrade checklist, links to deeper runbooks. | Release docs maintainer | verified | Release Docs/S03 baseline close | Revert the `docs/upgrade.md` addition if it misstates the upgrade contract, then restore the prior release-doc inventory expectation. | `test -s docs/upgrade.md` and `pnpm run verify:docs-links` passed in T01. | No credentials, connection strings, tenant identifiers, customer data, provider payloads, screenshots, or browser/E2E evidence. |
|
||||
| Release Docs-S03-T02 | Release documentation root and initial release entry at [`docs/releases/`](./releases/). | Documentation | docs-only | Release checklist, changelog alignment, artifact/tag evidence, pre-release and post-release boundaries. | Release docs maintainer | verified | Release Docs/S03 baseline close | Revert the `docs/releases/README.md` and initial release entry additions, then keep release notes in [`CHANGELOG.md`](../CHANGELOG.md) until the root is corrected. | `pnpm run verify:docs-links` passed in T02. | Keep registry hosts, namespaces, Coolify URLs, UUIDs, tokens, provider-console details, and browser/E2E recordings out of release evidence. |
|
||||
| Release Docs-S03-T03 | Migration registry root at [`docs/migration-registry.md`](./migration-registry.md). | Documentation | docs-only | Migration ownership, status, deadlines, rollback, verification, redaction, and release-facing migration index. | Release docs maintainer | in-progress | Release Docs/S03 baseline close | Revert this file if the schema mixes docs-only migrations with real database migrations or weakens redaction rules. | `test -s docs/migration-registry.md` and `pnpm run verify:docs-links` are required for this task. | Registry rows must exclude secrets, raw connection strings, tenant identifiers, customer data, provider payloads, and browser/E2E evidence. |
|
||||
| Release Docs-future-release-doc-roots | Future release-upgrade documentation roots discovered by baseline inventory. | Documentation | docs-only | Future release entries, migration-contract docs, changelog-adjacent runbooks, and baseline documentation inventory. | Release docs maintainer | planned | Next release-documentation slice that introduces the root | Do not create runtime migrations for missing documentation roots; revert or rename the documentation root and update this registry if the future path changes. | Future rows must use focused docs-link verification and the applicable baseline inventory verifier before being marked `verified`. | Future entries may reference command names, artifact labels, and generic statuses only; no live provider payloads or sensitive runtime evidence. |
|
||||
|
||||
## Verification and evidence rules
|
||||
|
||||
Acceptable registry evidence includes focused non-E2E commands, static verifier PASS/FAIL summaries, reviewed release checklist status, immutable image tag labels, migration-status phase and exit code, backup or restore-point confirmation labels, and manual-runtime notes that contain only redacted facts.
|
||||
|
||||
Unacceptable evidence includes raw database URLs, Redis URLs, registry credentials, Coolify webhook URLs, bearer tokens, API keys, cookies, tenant identifiers, customer domains, customer data, provider payloads, raw job payloads, database dumps, screenshots with secrets, browser recordings, Playwright traces, Cypress artifacts, and full environment dumps.
|
||||
|
||||
Browser, Playwright, Cypress, live Docker, live registry, Coolify, provider-console, and production traffic checks remain manual runtime boundaries unless a human explicitly approves the exact focused run. When such checks are required for a release, record only the manual check label, operator, status, target name, immutable tag or request ID, and redacted failure code.
|
||||
|
||||
## Negative checks
|
||||
|
||||
Before marking this registry healthy for a release baseline, verification must reject these conditions:
|
||||
|
||||
- `docs/migration-registry.md` is missing or empty.
|
||||
- Any local markdown link in this file is unresolved.
|
||||
- The registry table omits owner, status, or deadline fields.
|
||||
- A docs-only migration is represented as a real database migration.
|
||||
- A registry row stores sensitive evidence instead of redacted summaries.
|
||||
- Unresolved marker text is present in the file.
|
||||
-88
@@ -1,88 +0,0 @@
|
||||
# M001 — Audit-Log default
|
||||
|
||||
**Block:** Querschnitt-Hülle Teil 1 (Bauprinzipien)
|
||||
**Bauprinzip:** A.6 — Audit-Log als Default
|
||||
**Pflichtenheft-Quelle:** `_bmad-output/pflichtenheft/03-architektur.md` Sektion A.6
|
||||
|
||||
## Ziel
|
||||
Eine Schreib-Aktion durch ein beliebiges Modul erzeugt automatisch einen Audit-Eintrag — ohne dass das Modul den Audit-Service aktiv aufrufen muss.
|
||||
|
||||
## Pflichtenheft-Bezug
|
||||
- A.6.1 — Jede schreibende Aktion (Anlegen, Ändern, Löschen, Status-Wechsel) wird mit Wer/Wann/Was/Vor-Nach-Wert protokolliert
|
||||
- A.6.2 — Auch Aktionen durch Automatisierungen oder externe Sync-Vorgänge; Auslöser wird mit-protokolliert
|
||||
|
||||
## Abhängigkeiten
|
||||
- **Vorbedingung:** EU-Sterilisation + RR7-Migration der Boilerplate abgeschlossen
|
||||
- **Wird benötigt von:** M004, M005, M006, M075-M082 (Automation), M151-M152 (Audit-UI/Export), alle schreibenden Module
|
||||
|
||||
## Out of Scope
|
||||
- Audit-Anzeige-UI → M151
|
||||
- Audit-Export für Compliance → M152
|
||||
|
||||
## Erfolgskriterium
|
||||
Test-Modul ruft `kontakt.create({...})` → ohne expliziten Audit-Code-Aufruf erscheint ein Eintrag in `audit_events` mit korrektem actor, tenant, before/after, timestamp.
|
||||
|
||||
## Hinweise für Slice-Planung
|
||||
- Schema-Design separat von Hook-Implementierung
|
||||
- Akteur-Resolution unterscheidet User / Auto / Sync / System
|
||||
- Performance: Bulk-Update von 1000 Datensätzen darf nicht > 2x normale Latenz erzeugen
|
||||
- Audit-Writes sind unveränderlich (keine UPDATE/DELETE-Pfade)
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done — verbindlich (siehe `AGENTS.md` + `docs/INTEGRATION-CONTRACTS.md`)
|
||||
|
||||
Dieses Milestone gilt **nur dann als erledigt**, wenn alle Punkte wahr sind. Bei Verstoß: PR-Block.
|
||||
|
||||
### Erreichbarkeit
|
||||
- [ ] **Sidebar-Eintrag** in `apps/web/app/application/sidebar/` mit Permission-Gate (oder explizit dokumentiert, warum nur Inline-Verlinkung) — Gruppe gemäß `docs/INTEGRATION-CONTRACTS.md` §1
|
||||
- [ ] **Route** unter korrektem URL-Pattern (INTEGRATION-CONTRACTS §3)
|
||||
- [ ] **Breadcrumb** für Detail-Routes (§4)
|
||||
- [ ] **Mobile-Tab-Bar-Eintrag** falls mobile-relevant (§13)
|
||||
- [ ] **Customer-Portal-Sichtbarkeit** explizit konfiguriert (§14)
|
||||
|
||||
### Querschnitt-Wiring
|
||||
- [ ] **Audit** läuft (auto via M001 oder manuell)
|
||||
- [ ] **Activity-Stream** via `logActivity` bei relevanter Aktion (M045)
|
||||
- [ ] **Notifications** via `notify()` (M011), nicht direkt
|
||||
- [ ] **Search-Index** registriert in `indexed-entities.ts`, falls suchbar
|
||||
- [ ] **Permission-Filter** via `withTenantScope()` + `withPermission()` (M004)
|
||||
- [ ] **Feature-Flag-fähig** (M006) — Modul ohne Deploy abschaltbar
|
||||
|
||||
### Code-Layer-Disziplin (PR-Block)
|
||||
- [ ] Loader baut View-Model; UI-Component empfängt nur VM + Actions
|
||||
- [ ] Keine Prisma-/Server-Imports in `packages/ui-app/**`
|
||||
- [ ] Subframe-Output via Adapter, nicht direkt importiert
|
||||
- [ ] Alle UI-Texte als i18n-Keys (M003-Build-Lint blockt sonst)
|
||||
|
||||
### Tests
|
||||
- [ ] **Unit-Test** für VM-Builder mit Zod-Schema-Validierung
|
||||
- [ ] **Smoke-Test** `e2e/smoke/<modul>.spec.ts` (Login → Route → Hauptaktion → erwartetes UI)
|
||||
- [ ] **Hot-Swap-Drill** grün (Smoke-Test gegen `packages/ui-mock` aus M017)
|
||||
- [ ] **Visual-Regression-Snapshot** der Hauptansicht (M016)
|
||||
|
||||
### Klartext (User-facing)
|
||||
- [ ] Fehler-Texte aus M002-Catalog (kein HTTP-Code im UI)
|
||||
- [ ] Empty-State mit Klartext + nächster Aktion
|
||||
- [ ] Loading-State mit Klartext (kein leerer Spinner)
|
||||
- [ ] Permission-Denied → 404, nicht 403 (Bauprinzip A.5.3)
|
||||
|
||||
### Rollback-Pfad
|
||||
- [ ] **Forward-Only-DB-Migration** mit Inverse-SQL als Kommentar
|
||||
- [ ] **Atomic-Slice-Commits** (TC-Default)
|
||||
- [ ] **Feature-Flag** vorhanden, um das Modul ohne Deploy auszuschalten
|
||||
|
||||
---
|
||||
|
||||
## Klick-Pfad zum Prüfen (für User)
|
||||
|
||||
Wenn dieses Milestone fertig ist, prüft der User die Funktion über folgenden Pfad:
|
||||
|
||||
1. Login als geeigneter User-Typ (siehe Erfolgskriterium oben)
|
||||
2. Sidebar-Gruppe + Eintrag öffnen (gemäß INTEGRATION-CONTRACTS.md §1)
|
||||
3. Hauptaktion ausführen
|
||||
4. Erwartetes Ergebnis sichtbar (siehe Erfolgskriterium)
|
||||
|
||||
**Falls etwas nicht erreichbar ist:** Milestone ist trotz „grüner Tests" nicht fertig — siehe Erreichbarkeits-Checkliste oben.
|
||||
|
||||
-89
@@ -1,89 +0,0 @@
|
||||
# M002 — Klartext-Diagnostik
|
||||
|
||||
**Block:** Querschnitt-Hülle Teil 1 (Bauprinzipien)
|
||||
**Bauprinzip:** A.1 — Klartext-Diagnostik in jedem Feature
|
||||
**Pflichtenheft-Quelle:** `_bmad-output/pflichtenheft/03-architektur.md` Sektion A.1
|
||||
|
||||
## Ziel
|
||||
Jeder erkennbare Fehler-Zustand in HiveGrid hat einen vorformulierten Klartext-Text und (wo sinnvoll) einen Lösungs-Knopf — kein nackter HTTP-Code, kein kryptisches Log.
|
||||
|
||||
## Pflichtenheft-Bezug
|
||||
- A.1.1 — Fester Klartext-Text + optional Lösungs-Knopf pro Fehler-Zustand
|
||||
- A.1.2 — Keine KI-on-the-fly-Übersetzung in Phase 1; Texte sind redaktionell vorgefertigt
|
||||
- A.1.3 — Kein Feature-Release ohne definierte Klartext-Texte
|
||||
|
||||
## Abhängigkeiten
|
||||
- **Wird benötigt von:** allen folgenden Modulen
|
||||
- **Hängt zusammen mit:** M003 (i18n), weil Klartext mehrsprach-fähig sein muss
|
||||
|
||||
## Out of Scope
|
||||
- KI-Live-Übersetzung von Fehlern → Backlog/v3 nach AD-26
|
||||
- Auto-Generierung von Texten
|
||||
|
||||
## Erfolgskriterium
|
||||
Geworfener Catalog-Fehler erscheint als deutscher Klartext-Hinweis im UI mit korrektem Lösungs-Knopf-Verhalten; ESLint-Rule lehnt nackte `throw new Error("...")` außerhalb des Catalogs ab.
|
||||
|
||||
## Hinweise für Slice-Planung
|
||||
- Catalog-Format als TypeScript-Modul + i18n-Keys
|
||||
- Error-Boundary (RR7-kompatibel)
|
||||
- Logger-Bridge zu Pino
|
||||
- Migrations-Lint für bestehende Boilerplate-Fehler
|
||||
- Klartext-Beispiele aus Pflichtenheft-Modulen übernehmen (z.B. M27.15)
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done — verbindlich (siehe `AGENTS.md` + `docs/INTEGRATION-CONTRACTS.md`)
|
||||
|
||||
Dieses Milestone gilt **nur dann als erledigt**, wenn alle Punkte wahr sind. Bei Verstoß: PR-Block.
|
||||
|
||||
### Erreichbarkeit
|
||||
- [ ] **Sidebar-Eintrag** in `apps/web/app/application/sidebar/` mit Permission-Gate (oder explizit dokumentiert, warum nur Inline-Verlinkung) — Gruppe gemäß `docs/INTEGRATION-CONTRACTS.md` §1
|
||||
- [ ] **Route** unter korrektem URL-Pattern (INTEGRATION-CONTRACTS §3)
|
||||
- [ ] **Breadcrumb** für Detail-Routes (§4)
|
||||
- [ ] **Mobile-Tab-Bar-Eintrag** falls mobile-relevant (§13)
|
||||
- [ ] **Customer-Portal-Sichtbarkeit** explizit konfiguriert (§14)
|
||||
|
||||
### Querschnitt-Wiring
|
||||
- [ ] **Audit** läuft (auto via M001 oder manuell)
|
||||
- [ ] **Activity-Stream** via `logActivity` bei relevanter Aktion (M045)
|
||||
- [ ] **Notifications** via `notify()` (M011), nicht direkt
|
||||
- [ ] **Search-Index** registriert in `indexed-entities.ts`, falls suchbar
|
||||
- [ ] **Permission-Filter** via `withTenantScope()` + `withPermission()` (M004)
|
||||
- [ ] **Feature-Flag-fähig** (M006) — Modul ohne Deploy abschaltbar
|
||||
|
||||
### Code-Layer-Disziplin (PR-Block)
|
||||
- [ ] Loader baut View-Model; UI-Component empfängt nur VM + Actions
|
||||
- [ ] Keine Prisma-/Server-Imports in `packages/ui-app/**`
|
||||
- [ ] Subframe-Output via Adapter, nicht direkt importiert
|
||||
- [ ] Alle UI-Texte als i18n-Keys (M003-Build-Lint blockt sonst)
|
||||
|
||||
### Tests
|
||||
- [ ] **Unit-Test** für VM-Builder mit Zod-Schema-Validierung
|
||||
- [ ] **Smoke-Test** `e2e/smoke/<modul>.spec.ts` (Login → Route → Hauptaktion → erwartetes UI)
|
||||
- [ ] **Hot-Swap-Drill** grün (Smoke-Test gegen `packages/ui-mock` aus M017)
|
||||
- [ ] **Visual-Regression-Snapshot** der Hauptansicht (M016)
|
||||
|
||||
### Klartext (User-facing)
|
||||
- [ ] Fehler-Texte aus M002-Catalog (kein HTTP-Code im UI)
|
||||
- [ ] Empty-State mit Klartext + nächster Aktion
|
||||
- [ ] Loading-State mit Klartext (kein leerer Spinner)
|
||||
- [ ] Permission-Denied → 404, nicht 403 (Bauprinzip A.5.3)
|
||||
|
||||
### Rollback-Pfad
|
||||
- [ ] **Forward-Only-DB-Migration** mit Inverse-SQL als Kommentar
|
||||
- [ ] **Atomic-Slice-Commits** (TC-Default)
|
||||
- [ ] **Feature-Flag** vorhanden, um das Modul ohne Deploy auszuschalten
|
||||
|
||||
---
|
||||
|
||||
## Klick-Pfad zum Prüfen (für User)
|
||||
|
||||
Wenn dieses Milestone fertig ist, prüft der User die Funktion über folgenden Pfad:
|
||||
|
||||
1. Login als geeigneter User-Typ (siehe Erfolgskriterium oben)
|
||||
2. Sidebar-Gruppe + Eintrag öffnen (gemäß INTEGRATION-CONTRACTS.md §1)
|
||||
3. Hauptaktion ausführen
|
||||
4. Erwartetes Ergebnis sichtbar (siehe Erfolgskriterium)
|
||||
|
||||
**Falls etwas nicht erreichbar ist:** Milestone ist trotz „grüner Tests" nicht fertig — siehe Erreichbarkeits-Checkliste oben.
|
||||
-89
@@ -1,89 +0,0 @@
|
||||
# M003 — i18n-Pflicht-Wiring
|
||||
|
||||
**Block:** Querschnitt-Hülle Teil 1 (Bauprinzipien)
|
||||
**Bauprinzip:** A.4 — Mehrsprachigkeit von Anfang an sauber vorbereitet
|
||||
**Pflichtenheft-Quelle:** `_bmad-output/pflichtenheft/03-architektur.md` Sektion A.4
|
||||
|
||||
## Ziel
|
||||
Kein einziger UI-Text wird hartkodiert. Build schlägt fehl, wenn ein nicht-erlaubter harter Text gefunden wird.
|
||||
|
||||
## Pflichtenheft-Bezug
|
||||
- A.4.1 — Alle Texte aus Sprach-Dateien (Locale-Files), keine Hardcoding
|
||||
- A.4.2 — DE Phase 1 befüllt; EN/TR/PL als Ziel-Sprachen vorbereitet, nicht befüllt
|
||||
- A.4.3 — Sprach-Wechsel pro Nutzer (siehe M028, M029)
|
||||
|
||||
## Abhängigkeiten
|
||||
- **Wird benötigt von:** allen folgenden Modulen mit UI
|
||||
- **Verwendet:** Boilerplate-`packages/i18n` (i18next + remix-i18next)
|
||||
|
||||
## Out of Scope
|
||||
- DeepL-Pipeline für DE → EN/TR/PL (Phase 2)
|
||||
- Sprach-Pflege-UI für Mandanten (gibt es nicht — Mandanten-Inhalte sind 1-sprachig)
|
||||
|
||||
## Erfolgskriterium
|
||||
Hartcodierter String im UI-Code (`packages/ui-app/**`) → Build schlägt fehl mit Klartext-Verstoß-Meldung. Pluralisierung (DE-Form) und Datums/Zahlen-Format funktionieren.
|
||||
|
||||
## Hinweise für Slice-Planung
|
||||
- i18next-Setup als Querschnitt-Service, einzig DE als Quelle
|
||||
- ESLint-Rule gegen JSX-Text-Nodes ohne `t()`
|
||||
- CI-Wiring (`pnpm verify:i18n` im baseline)
|
||||
- Pluralisierung: ICU MessageFormat (Polnisch hat 3 Formen — Phase 2 nicht brechen)
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done — verbindlich (siehe `AGENTS.md` + `docs/INTEGRATION-CONTRACTS.md`)
|
||||
|
||||
Dieses Milestone gilt **nur dann als erledigt**, wenn alle Punkte wahr sind. Bei Verstoß: PR-Block.
|
||||
|
||||
### Erreichbarkeit
|
||||
- [ ] **Sidebar-Eintrag** in `apps/web/app/application/sidebar/` mit Permission-Gate (oder explizit dokumentiert, warum nur Inline-Verlinkung) — Gruppe gemäß `docs/INTEGRATION-CONTRACTS.md` §1
|
||||
- [ ] **Route** unter korrektem URL-Pattern (INTEGRATION-CONTRACTS §3)
|
||||
- [ ] **Breadcrumb** für Detail-Routes (§4)
|
||||
- [ ] **Mobile-Tab-Bar-Eintrag** falls mobile-relevant (§13)
|
||||
- [ ] **Customer-Portal-Sichtbarkeit** explizit konfiguriert (§14)
|
||||
|
||||
### Querschnitt-Wiring
|
||||
- [ ] **Audit** läuft (auto via M001 oder manuell)
|
||||
- [ ] **Activity-Stream** via `logActivity` bei relevanter Aktion (M045)
|
||||
- [ ] **Notifications** via `notify()` (M011), nicht direkt
|
||||
- [ ] **Search-Index** registriert in `indexed-entities.ts`, falls suchbar
|
||||
- [ ] **Permission-Filter** via `withTenantScope()` + `withPermission()` (M004)
|
||||
- [ ] **Feature-Flag-fähig** (M006) — Modul ohne Deploy abschaltbar
|
||||
|
||||
### Code-Layer-Disziplin (PR-Block)
|
||||
- [ ] Loader baut View-Model; UI-Component empfängt nur VM + Actions
|
||||
- [ ] Keine Prisma-/Server-Imports in `packages/ui-app/**`
|
||||
- [ ] Subframe-Output via Adapter, nicht direkt importiert
|
||||
- [ ] Alle UI-Texte als i18n-Keys (M003-Build-Lint blockt sonst)
|
||||
|
||||
### Tests
|
||||
- [ ] **Unit-Test** für VM-Builder mit Zod-Schema-Validierung
|
||||
- [ ] **Smoke-Test** `e2e/smoke/<modul>.spec.ts` (Login → Route → Hauptaktion → erwartetes UI)
|
||||
- [ ] **Hot-Swap-Drill** grün (Smoke-Test gegen `packages/ui-mock` aus M017)
|
||||
- [ ] **Visual-Regression-Snapshot** der Hauptansicht (M016)
|
||||
|
||||
### Klartext (User-facing)
|
||||
- [ ] Fehler-Texte aus M002-Catalog (kein HTTP-Code im UI)
|
||||
- [ ] Empty-State mit Klartext + nächster Aktion
|
||||
- [ ] Loading-State mit Klartext (kein leerer Spinner)
|
||||
- [ ] Permission-Denied → 404, nicht 403 (Bauprinzip A.5.3)
|
||||
|
||||
### Rollback-Pfad
|
||||
- [ ] **Forward-Only-DB-Migration** mit Inverse-SQL als Kommentar
|
||||
- [ ] **Atomic-Slice-Commits** (TC-Default)
|
||||
- [ ] **Feature-Flag** vorhanden, um das Modul ohne Deploy auszuschalten
|
||||
|
||||
---
|
||||
|
||||
## Klick-Pfad zum Prüfen (für User)
|
||||
|
||||
Wenn dieses Milestone fertig ist, prüft der User die Funktion über folgenden Pfad:
|
||||
|
||||
1. Login als geeigneter User-Typ (siehe Erfolgskriterium oben)
|
||||
2. Sidebar-Gruppe + Eintrag öffnen (gemäß INTEGRATION-CONTRACTS.md §1)
|
||||
3. Hauptaktion ausführen
|
||||
4. Erwartetes Ergebnis sichtbar (siehe Erfolgskriterium)
|
||||
|
||||
**Falls etwas nicht erreichbar ist:** Milestone ist trotz „grüner Tests" nicht fertig — siehe Erreichbarkeits-Checkliste oben.
|
||||
|
||||
-87
@@ -1,87 +0,0 @@
|
||||
# M004 — Tenant-Scope-Wrapper + Owner-Check
|
||||
|
||||
**Block:** Querschnitt-Hülle Teil 1 (Bauprinzipien)
|
||||
**Bauprinzip:** A.5 Teil 1 — Berechtigungs-Logik als Standard
|
||||
**Pflichtenheft-Quelle:** `_bmad-output/pflichtenheft/03-architektur.md` Sektion A.5
|
||||
|
||||
## Ziel
|
||||
Jede Liste, Suche, Detail-Ansicht filtert automatisch nach Mandant + Berechtigungen. Owner-Check für „eigene Daten" zentral implementiert.
|
||||
|
||||
## Pflichtenheft-Bezug
|
||||
- A.5.1 — Auto-Filter nach angemeldetem Nutzer; ohne Recht: nicht im Menü, nicht aufrufbar, nicht in Suche
|
||||
- A.5.2 — Owner-Check zentral, nicht pro Modul nachgebaut
|
||||
- A.5.3 — Keine versteckten URL-Tricks zum Umgehen
|
||||
|
||||
## Abhängigkeiten
|
||||
- **Vorbedingung:** M001 (Permission-Verstöße werden geauditet)
|
||||
- **Wird benötigt von:** allen Modulen, die Daten anzeigen
|
||||
|
||||
## Out of Scope
|
||||
- URL-Tampering-Probes + Mass-Action-Hardening → M005
|
||||
|
||||
## Erfolgskriterium
|
||||
Test-Modul vergisst den Filter → Wrapper greift trotzdem; Cross-Tenant-ID-Lookup liefert 404 (nicht 403).
|
||||
|
||||
## Hinweise für Slice-Planung
|
||||
- Wrapper für Prisma-Queries (`withTenantScope`, `withPermission`, `withOwnerCheck`)
|
||||
- Permission-Definition als Feingranular (siehe M27.6.2 — Stufen pro Funktionsbereich)
|
||||
- Test-Suite mit Cross-Tenant-Probe + Negative-Path
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done — verbindlich (siehe `AGENTS.md` + `docs/INTEGRATION-CONTRACTS.md`)
|
||||
|
||||
Dieses Milestone gilt **nur dann als erledigt**, wenn alle Punkte wahr sind. Bei Verstoß: PR-Block.
|
||||
|
||||
### Erreichbarkeit
|
||||
- [ ] **Sidebar-Eintrag** in `apps/web/app/application/sidebar/` mit Permission-Gate (oder explizit dokumentiert, warum nur Inline-Verlinkung) — Gruppe gemäß `docs/INTEGRATION-CONTRACTS.md` §1
|
||||
- [ ] **Route** unter korrektem URL-Pattern (INTEGRATION-CONTRACTS §3)
|
||||
- [ ] **Breadcrumb** für Detail-Routes (§4)
|
||||
- [ ] **Mobile-Tab-Bar-Eintrag** falls mobile-relevant (§13)
|
||||
- [ ] **Customer-Portal-Sichtbarkeit** explizit konfiguriert (§14)
|
||||
|
||||
### Querschnitt-Wiring
|
||||
- [ ] **Audit** läuft (auto via M001 oder manuell)
|
||||
- [ ] **Activity-Stream** via `logActivity` bei relevanter Aktion (M045)
|
||||
- [ ] **Notifications** via `notify()` (M011), nicht direkt
|
||||
- [ ] **Search-Index** registriert in `indexed-entities.ts`, falls suchbar
|
||||
- [ ] **Permission-Filter** via `withTenantScope()` + `withPermission()` (M004)
|
||||
- [ ] **Feature-Flag-fähig** (M006) — Modul ohne Deploy abschaltbar
|
||||
|
||||
### Code-Layer-Disziplin (PR-Block)
|
||||
- [ ] Loader baut View-Model; UI-Component empfängt nur VM + Actions
|
||||
- [ ] Keine Prisma-/Server-Imports in `packages/ui-app/**`
|
||||
- [ ] Subframe-Output via Adapter, nicht direkt importiert
|
||||
- [ ] Alle UI-Texte als i18n-Keys (M003-Build-Lint blockt sonst)
|
||||
|
||||
### Tests
|
||||
- [ ] **Unit-Test** für VM-Builder mit Zod-Schema-Validierung
|
||||
- [ ] **Smoke-Test** `e2e/smoke/<modul>.spec.ts` (Login → Route → Hauptaktion → erwartetes UI)
|
||||
- [ ] **Hot-Swap-Drill** grün (Smoke-Test gegen `packages/ui-mock` aus M017)
|
||||
- [ ] **Visual-Regression-Snapshot** der Hauptansicht (M016)
|
||||
|
||||
### Klartext (User-facing)
|
||||
- [ ] Fehler-Texte aus M002-Catalog (kein HTTP-Code im UI)
|
||||
- [ ] Empty-State mit Klartext + nächster Aktion
|
||||
- [ ] Loading-State mit Klartext (kein leerer Spinner)
|
||||
- [ ] Permission-Denied → 404, nicht 403 (Bauprinzip A.5.3)
|
||||
|
||||
### Rollback-Pfad
|
||||
- [ ] **Forward-Only-DB-Migration** mit Inverse-SQL als Kommentar
|
||||
- [ ] **Atomic-Slice-Commits** (TC-Default)
|
||||
- [ ] **Feature-Flag** vorhanden, um das Modul ohne Deploy auszuschalten
|
||||
|
||||
---
|
||||
|
||||
## Klick-Pfad zum Prüfen (für User)
|
||||
|
||||
Wenn dieses Milestone fertig ist, prüft der User die Funktion über folgenden Pfad:
|
||||
|
||||
1. Login als geeigneter User-Typ (siehe Erfolgskriterium oben)
|
||||
2. Sidebar-Gruppe + Eintrag öffnen (gemäß INTEGRATION-CONTRACTS.md §1)
|
||||
3. Hauptaktion ausführen
|
||||
4. Erwartetes Ergebnis sichtbar (siehe Erfolgskriterium)
|
||||
|
||||
**Falls etwas nicht erreichbar ist:** Milestone ist trotz „grüner Tests" nicht fertig — siehe Erreichbarkeits-Checkliste oben.
|
||||
|
||||
-87
@@ -1,87 +0,0 @@
|
||||
# M005 — URL-Tampering Hardening + Mass-Action-Schutz
|
||||
|
||||
**Block:** Querschnitt-Hülle Teil 1 (Bauprinzipien)
|
||||
**Bauprinzip:** A.5 Teil 2
|
||||
**Pflichtenheft-Quelle:** `_bmad-output/pflichtenheft/03-architektur.md` Sektion A.5.3 + 27.2
|
||||
|
||||
## Ziel
|
||||
URL-Manipulation, Bulk-Operationen, kreative Query-Strings können Mandanten-Trennung nicht umgehen.
|
||||
|
||||
## Pflichtenheft-Bezug
|
||||
- A.5.3 — Keine versteckten URL-Tricks
|
||||
- 27.2.1 — System verhindert durchgehend Cross-Tenant-Datenzugriff
|
||||
- 27.2.3 — Auch Hintergrund-Prozesse setzen Mandanten-Bezug explizit
|
||||
|
||||
## Abhängigkeiten
|
||||
- **Vorbedingung:** M004 (Wrapper steht)
|
||||
- **Wird benötigt von:** allen Modulen mit ID-basierten Routen
|
||||
|
||||
## Out of Scope
|
||||
- Cache/CDN-Layer Probes (separat falls relevant)
|
||||
|
||||
## Erfolgskriterium
|
||||
Pen-Test-Suite mit URL-Tampering-Probes (fremde IDs, Cross-Tenant-Slug, Mass-DELETE-Versuche) liefert konsistent 404; Audit-Log erfasst alle Probe-Versuche.
|
||||
|
||||
## Hinweise für Slice-Planung
|
||||
- Probe-Test-Suite als CI-Pflicht (Playwright)
|
||||
- Mass-Action-Validation (Bulk-Updates müssen IDs einzeln gegen Tenant prüfen)
|
||||
- Background-Job-Wrapper (BullMQ-Jobs setzen Tenant explizit)
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done — verbindlich (siehe `AGENTS.md` + `docs/INTEGRATION-CONTRACTS.md`)
|
||||
|
||||
Dieses Milestone gilt **nur dann als erledigt**, wenn alle Punkte wahr sind. Bei Verstoß: PR-Block.
|
||||
|
||||
### Erreichbarkeit
|
||||
- [ ] **Sidebar-Eintrag** in `apps/web/app/application/sidebar/` mit Permission-Gate (oder explizit dokumentiert, warum nur Inline-Verlinkung) — Gruppe gemäß `docs/INTEGRATION-CONTRACTS.md` §1
|
||||
- [ ] **Route** unter korrektem URL-Pattern (INTEGRATION-CONTRACTS §3)
|
||||
- [ ] **Breadcrumb** für Detail-Routes (§4)
|
||||
- [ ] **Mobile-Tab-Bar-Eintrag** falls mobile-relevant (§13)
|
||||
- [ ] **Customer-Portal-Sichtbarkeit** explizit konfiguriert (§14)
|
||||
|
||||
### Querschnitt-Wiring
|
||||
- [ ] **Audit** läuft (auto via M001 oder manuell)
|
||||
- [ ] **Activity-Stream** via `logActivity` bei relevanter Aktion (M045)
|
||||
- [ ] **Notifications** via `notify()` (M011), nicht direkt
|
||||
- [ ] **Search-Index** registriert in `indexed-entities.ts`, falls suchbar
|
||||
- [ ] **Permission-Filter** via `withTenantScope()` + `withPermission()` (M004)
|
||||
- [ ] **Feature-Flag-fähig** (M006) — Modul ohne Deploy abschaltbar
|
||||
|
||||
### Code-Layer-Disziplin (PR-Block)
|
||||
- [ ] Loader baut View-Model; UI-Component empfängt nur VM + Actions
|
||||
- [ ] Keine Prisma-/Server-Imports in `packages/ui-app/**`
|
||||
- [ ] Subframe-Output via Adapter, nicht direkt importiert
|
||||
- [ ] Alle UI-Texte als i18n-Keys (M003-Build-Lint blockt sonst)
|
||||
|
||||
### Tests
|
||||
- [ ] **Unit-Test** für VM-Builder mit Zod-Schema-Validierung
|
||||
- [ ] **Smoke-Test** `e2e/smoke/<modul>.spec.ts` (Login → Route → Hauptaktion → erwartetes UI)
|
||||
- [ ] **Hot-Swap-Drill** grün (Smoke-Test gegen `packages/ui-mock` aus M017)
|
||||
- [ ] **Visual-Regression-Snapshot** der Hauptansicht (M016)
|
||||
|
||||
### Klartext (User-facing)
|
||||
- [ ] Fehler-Texte aus M002-Catalog (kein HTTP-Code im UI)
|
||||
- [ ] Empty-State mit Klartext + nächster Aktion
|
||||
- [ ] Loading-State mit Klartext (kein leerer Spinner)
|
||||
- [ ] Permission-Denied → 404, nicht 403 (Bauprinzip A.5.3)
|
||||
|
||||
### Rollback-Pfad
|
||||
- [ ] **Forward-Only-DB-Migration** mit Inverse-SQL als Kommentar
|
||||
- [ ] **Atomic-Slice-Commits** (TC-Default)
|
||||
- [ ] **Feature-Flag** vorhanden, um das Modul ohne Deploy auszuschalten
|
||||
|
||||
---
|
||||
|
||||
## Klick-Pfad zum Prüfen (für User)
|
||||
|
||||
Wenn dieses Milestone fertig ist, prüft der User die Funktion über folgenden Pfad:
|
||||
|
||||
1. Login als geeigneter User-Typ (siehe Erfolgskriterium oben)
|
||||
2. Sidebar-Gruppe + Eintrag öffnen (gemäß INTEGRATION-CONTRACTS.md §1)
|
||||
3. Hauptaktion ausführen
|
||||
4. Erwartetes Ergebnis sichtbar (siehe Erfolgskriterium)
|
||||
|
||||
**Falls etwas nicht erreichbar ist:** Milestone ist trotz „grüner Tests" nicht fertig — siehe Erreichbarkeits-Checkliste oben.
|
||||
|
||||
-90
@@ -1,90 +0,0 @@
|
||||
# M006 — Feature-Flag-Engine (Code-Layer)
|
||||
|
||||
**Block:** Querschnitt-Hülle Teil 1 (Bauprinzipien)
|
||||
**Bauprinzip:** A.7 — Feature-Flags als Standard-Einführungs-Hülle
|
||||
**Pflichtenheft-Quelle:** `_bmad-output/pflichtenheft/03-architektur.md` Sektion A.7 + Modul 32
|
||||
|
||||
## Ziel
|
||||
Flag-Auswertung mit korrekter Priorität (direkte Ausnahme → Filter → Default). Code-Layer steht; Admin-UI später (M031-M033).
|
||||
|
||||
## Pflichtenheft-Bezug
|
||||
- A.7.1 — Neue Features hinter Flag, intern → ausgewählte → breit
|
||||
- A.7.2 — Plattform-Admin schaltet ohne Deploy
|
||||
- 32.4 — Auswertungs-Reihenfolge
|
||||
|
||||
## Abhängigkeiten
|
||||
- **Vorbedingung:** M001 (Flag-Änderungen werden geauditet)
|
||||
- **Wird benötigt von:** allen folgenden Modulen mit gestaffeltem Roll-out
|
||||
|
||||
## Out of Scope
|
||||
- Admin-UI für Flag-Verwaltung → M031-M033
|
||||
- Mandanten-Selbstbedienungs-Flags (Phase 2)
|
||||
- Prozentualer Roll-out (Phase 2)
|
||||
- A/B-/C-Tests (Phase 2)
|
||||
|
||||
## Erfolgskriterium
|
||||
`featureFlag('foo', tenant)` returns korrekten Wert nach Priorität; Test-Mode mit forced overrides; im Code referenzierter aber nicht definierter Flag → Klartext-Build-Warnung.
|
||||
|
||||
## Hinweise für Slice-Planung
|
||||
- Flag-Schema mit Lifecycle (Beta/Roll-out/GA/Abgekündigt)
|
||||
- Resolver mit Caching
|
||||
- Test-Mode für CI (forced overrides)
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done — verbindlich (siehe `AGENTS.md` + `docs/INTEGRATION-CONTRACTS.md`)
|
||||
|
||||
Dieses Milestone gilt **nur dann als erledigt**, wenn alle Punkte wahr sind. Bei Verstoß: PR-Block.
|
||||
|
||||
### Erreichbarkeit
|
||||
- [ ] **Sidebar-Eintrag** in `apps/web/app/application/sidebar/` mit Permission-Gate (oder explizit dokumentiert, warum nur Inline-Verlinkung) — Gruppe gemäß `docs/INTEGRATION-CONTRACTS.md` §1
|
||||
- [ ] **Route** unter korrektem URL-Pattern (INTEGRATION-CONTRACTS §3)
|
||||
- [ ] **Breadcrumb** für Detail-Routes (§4)
|
||||
- [ ] **Mobile-Tab-Bar-Eintrag** falls mobile-relevant (§13)
|
||||
- [ ] **Customer-Portal-Sichtbarkeit** explizit konfiguriert (§14)
|
||||
|
||||
### Querschnitt-Wiring
|
||||
- [ ] **Audit** läuft (auto via M001 oder manuell)
|
||||
- [ ] **Activity-Stream** via `logActivity` bei relevanter Aktion (M045)
|
||||
- [ ] **Notifications** via `notify()` (M011), nicht direkt
|
||||
- [ ] **Search-Index** registriert in `indexed-entities.ts`, falls suchbar
|
||||
- [ ] **Permission-Filter** via `withTenantScope()` + `withPermission()` (M004)
|
||||
- [ ] **Feature-Flag-fähig** (M006) — Modul ohne Deploy abschaltbar
|
||||
|
||||
### Code-Layer-Disziplin (PR-Block)
|
||||
- [ ] Loader baut View-Model; UI-Component empfängt nur VM + Actions
|
||||
- [ ] Keine Prisma-/Server-Imports in `packages/ui-app/**`
|
||||
- [ ] Subframe-Output via Adapter, nicht direkt importiert
|
||||
- [ ] Alle UI-Texte als i18n-Keys (M003-Build-Lint blockt sonst)
|
||||
|
||||
### Tests
|
||||
- [ ] **Unit-Test** für VM-Builder mit Zod-Schema-Validierung
|
||||
- [ ] **Smoke-Test** `e2e/smoke/<modul>.spec.ts` (Login → Route → Hauptaktion → erwartetes UI)
|
||||
- [ ] **Hot-Swap-Drill** grün (Smoke-Test gegen `packages/ui-mock` aus M017)
|
||||
- [ ] **Visual-Regression-Snapshot** der Hauptansicht (M016)
|
||||
|
||||
### Klartext (User-facing)
|
||||
- [ ] Fehler-Texte aus M002-Catalog (kein HTTP-Code im UI)
|
||||
- [ ] Empty-State mit Klartext + nächster Aktion
|
||||
- [ ] Loading-State mit Klartext (kein leerer Spinner)
|
||||
- [ ] Permission-Denied → 404, nicht 403 (Bauprinzip A.5.3)
|
||||
|
||||
### Rollback-Pfad
|
||||
- [ ] **Forward-Only-DB-Migration** mit Inverse-SQL als Kommentar
|
||||
- [ ] **Atomic-Slice-Commits** (TC-Default)
|
||||
- [ ] **Feature-Flag** vorhanden, um das Modul ohne Deploy auszuschalten
|
||||
|
||||
---
|
||||
|
||||
## Klick-Pfad zum Prüfen (für User)
|
||||
|
||||
Wenn dieses Milestone fertig ist, prüft der User die Funktion über folgenden Pfad:
|
||||
|
||||
1. Login als geeigneter User-Typ (siehe Erfolgskriterium oben)
|
||||
2. Sidebar-Gruppe + Eintrag öffnen (gemäß INTEGRATION-CONTRACTS.md §1)
|
||||
3. Hauptaktion ausführen
|
||||
4. Erwartetes Ergebnis sichtbar (siehe Erfolgskriterium)
|
||||
|
||||
**Falls etwas nicht erreichbar ist:** Milestone ist trotz „grüner Tests" nicht fertig — siehe Erreichbarkeits-Checkliste oben.
|
||||
|
||||
-86
@@ -1,86 +0,0 @@
|
||||
# M007 — Idempotenz-Wrapper für BullMQ-Steps
|
||||
|
||||
**Block:** Querschnitt-Hülle Teil 1 (Bauprinzipien)
|
||||
**Bauprinzip:** A.8 — Idempotenz pro Automatisierungs-Aktion
|
||||
**Pflichtenheft-Quelle:** `_bmad-output/pflichtenheft/03-architektur.md` Sektion A.8
|
||||
|
||||
## Ziel
|
||||
Jeder BullMQ-Step hat einen Idempotenz-Schlüssel; bei Re-Run wird die Aktion nicht doppelt ausgeführt.
|
||||
|
||||
## Pflichtenheft-Bezug
|
||||
- A.8.1 — Idempotenz-Schlüssel pro Step
|
||||
- A.8.2 — Konkret: keine doppelten Mails, Datensätze, KWP-Push-Operationen
|
||||
|
||||
## Abhängigkeiten
|
||||
- **Vorbedingung:** M001 (Idempotenz-Skip wird geauditet), M004
|
||||
- **Wird benötigt von:** M075-M082 (Automation), M089-M095 (KWP-Sync), Mail-/Notification-Worker
|
||||
|
||||
## Out of Scope
|
||||
- Distributed-Lock-Service (BullMQ atomic ops reichen)
|
||||
|
||||
## Erfolgskriterium
|
||||
Job zweimal mit gleichem Key gequeued → läuft einmal, zweite Ausführung schreibt Audit-Skip-Eintrag.
|
||||
|
||||
## Hinweise für Slice-Planung
|
||||
- Idempotency-Key-Store mit TTL
|
||||
- BullMQ-Wrapper als Higher-Order-Function
|
||||
- Replay-Tests mit Job-Crash-Szenarien
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done — verbindlich (siehe `AGENTS.md` + `docs/INTEGRATION-CONTRACTS.md`)
|
||||
|
||||
Dieses Milestone gilt **nur dann als erledigt**, wenn alle Punkte wahr sind. Bei Verstoß: PR-Block.
|
||||
|
||||
### Erreichbarkeit
|
||||
- [ ] **Sidebar-Eintrag** in `apps/web/app/application/sidebar/` mit Permission-Gate (oder explizit dokumentiert, warum nur Inline-Verlinkung) — Gruppe gemäß `docs/INTEGRATION-CONTRACTS.md` §1
|
||||
- [ ] **Route** unter korrektem URL-Pattern (INTEGRATION-CONTRACTS §3)
|
||||
- [ ] **Breadcrumb** für Detail-Routes (§4)
|
||||
- [ ] **Mobile-Tab-Bar-Eintrag** falls mobile-relevant (§13)
|
||||
- [ ] **Customer-Portal-Sichtbarkeit** explizit konfiguriert (§14)
|
||||
|
||||
### Querschnitt-Wiring
|
||||
- [ ] **Audit** läuft (auto via M001 oder manuell)
|
||||
- [ ] **Activity-Stream** via `logActivity` bei relevanter Aktion (M045)
|
||||
- [ ] **Notifications** via `notify()` (M011), nicht direkt
|
||||
- [ ] **Search-Index** registriert in `indexed-entities.ts`, falls suchbar
|
||||
- [ ] **Permission-Filter** via `withTenantScope()` + `withPermission()` (M004)
|
||||
- [ ] **Feature-Flag-fähig** (M006) — Modul ohne Deploy abschaltbar
|
||||
|
||||
### Code-Layer-Disziplin (PR-Block)
|
||||
- [ ] Loader baut View-Model; UI-Component empfängt nur VM + Actions
|
||||
- [ ] Keine Prisma-/Server-Imports in `packages/ui-app/**`
|
||||
- [ ] Subframe-Output via Adapter, nicht direkt importiert
|
||||
- [ ] Alle UI-Texte als i18n-Keys (M003-Build-Lint blockt sonst)
|
||||
|
||||
### Tests
|
||||
- [ ] **Unit-Test** für VM-Builder mit Zod-Schema-Validierung
|
||||
- [ ] **Smoke-Test** `e2e/smoke/<modul>.spec.ts` (Login → Route → Hauptaktion → erwartetes UI)
|
||||
- [ ] **Hot-Swap-Drill** grün (Smoke-Test gegen `packages/ui-mock` aus M017)
|
||||
- [ ] **Visual-Regression-Snapshot** der Hauptansicht (M016)
|
||||
|
||||
### Klartext (User-facing)
|
||||
- [ ] Fehler-Texte aus M002-Catalog (kein HTTP-Code im UI)
|
||||
- [ ] Empty-State mit Klartext + nächster Aktion
|
||||
- [ ] Loading-State mit Klartext (kein leerer Spinner)
|
||||
- [ ] Permission-Denied → 404, nicht 403 (Bauprinzip A.5.3)
|
||||
|
||||
### Rollback-Pfad
|
||||
- [ ] **Forward-Only-DB-Migration** mit Inverse-SQL als Kommentar
|
||||
- [ ] **Atomic-Slice-Commits** (TC-Default)
|
||||
- [ ] **Feature-Flag** vorhanden, um das Modul ohne Deploy auszuschalten
|
||||
|
||||
---
|
||||
|
||||
## Klick-Pfad zum Prüfen (für User)
|
||||
|
||||
Wenn dieses Milestone fertig ist, prüft der User die Funktion über folgenden Pfad:
|
||||
|
||||
1. Login als geeigneter User-Typ (siehe Erfolgskriterium oben)
|
||||
2. Sidebar-Gruppe + Eintrag öffnen (gemäß INTEGRATION-CONTRACTS.md §1)
|
||||
3. Hauptaktion ausführen
|
||||
4. Erwartetes Ergebnis sichtbar (siehe Erfolgskriterium)
|
||||
|
||||
**Falls etwas nicht erreichbar ist:** Milestone ist trotz „grüner Tests" nicht fertig — siehe Erreichbarkeits-Checkliste oben.
|
||||
|
||||
-90
@@ -1,90 +0,0 @@
|
||||
# M008 — Apps-Engine: Adapter-Interface + State-Machine
|
||||
|
||||
**Block:** Querschnitt-Hülle Teil 1 (Bauprinzipien)
|
||||
**Bauprinzip:** A.2 Teil 1 — Adapter-Schicht für jede Integration
|
||||
**Pflichtenheft-Quelle:** `_bmad-output/pflichtenheft/03-architektur.md` A.2 + Modul 33a (Block 4)
|
||||
|
||||
## Ziel
|
||||
Abstrakte Adapter-Klasse + 5-Status-State-Machine (wartet/aktiv/eingeschränkt/defekt/getrennt). Eine Dummy-App zum Beweis.
|
||||
|
||||
## Pflichtenheft-Bezug
|
||||
- A.2.1 — Externe Systeme nur über Apps-Engine
|
||||
- A.2.2 — Adapter-Interface so gebaut, dass weitere Implementierungen ohne Engine-Umbau dazu kommen
|
||||
- 33a.3 — 5-Status mit Klartext-Hinweis pro Status
|
||||
|
||||
## Abhängigkeiten
|
||||
- **Vorbedingung:** M002, M001
|
||||
- **Wird benötigt von:** M009, M010 (Apps-Engine), alle Module mit externer Integration (M19, M9, M12, M25, M125, M131, M153)
|
||||
|
||||
## Out of Scope
|
||||
- Konkrete Adapter (KWP, Gmail, AirCall, Legacy-Provider, PandaDoc, Calendar) — eigene Module
|
||||
- Setup-Wizard → M009
|
||||
- Probe-Scheduler → M010
|
||||
- Drittanbieter-Marketplace (Phase 2)
|
||||
|
||||
## Erfolgskriterium
|
||||
Dummy-App durchläuft Lifecycle (wartet → aktiv → eingeschränkt → defekt → getrennt), Klartext-Hinweis pro Übergang sichtbar im Test-UI.
|
||||
|
||||
## Hinweise für Slice-Planung
|
||||
- Adapter-Interface als TypeScript-Interface mit klaren Hooks (connect, probe, sync, disconnect)
|
||||
- State-Machine als XState oder einfache Enum-Transitions mit Audit-Eintrag pro Wechsel
|
||||
- Dummy-App als Referenz-Implementation
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done — verbindlich (siehe `AGENTS.md` + `docs/INTEGRATION-CONTRACTS.md`)
|
||||
|
||||
Dieses Milestone gilt **nur dann als erledigt**, wenn alle Punkte wahr sind. Bei Verstoß: PR-Block.
|
||||
|
||||
### Erreichbarkeit
|
||||
- [ ] **Sidebar-Eintrag** in `apps/web/app/application/sidebar/` mit Permission-Gate (oder explizit dokumentiert, warum nur Inline-Verlinkung) — Gruppe gemäß `docs/INTEGRATION-CONTRACTS.md` §1
|
||||
- [ ] **Route** unter korrektem URL-Pattern (INTEGRATION-CONTRACTS §3)
|
||||
- [ ] **Breadcrumb** für Detail-Routes (§4)
|
||||
- [ ] **Mobile-Tab-Bar-Eintrag** falls mobile-relevant (§13)
|
||||
- [ ] **Customer-Portal-Sichtbarkeit** explizit konfiguriert (§14)
|
||||
|
||||
### Querschnitt-Wiring
|
||||
- [ ] **Audit** läuft (auto via M001 oder manuell)
|
||||
- [ ] **Activity-Stream** via `logActivity` bei relevanter Aktion (M045)
|
||||
- [ ] **Notifications** via `notify()` (M011), nicht direkt
|
||||
- [ ] **Search-Index** registriert in `indexed-entities.ts`, falls suchbar
|
||||
- [ ] **Permission-Filter** via `withTenantScope()` + `withPermission()` (M004)
|
||||
- [ ] **Feature-Flag-fähig** (M006) — Modul ohne Deploy abschaltbar
|
||||
|
||||
### Code-Layer-Disziplin (PR-Block)
|
||||
- [ ] Loader baut View-Model; UI-Component empfängt nur VM + Actions
|
||||
- [ ] Keine Prisma-/Server-Imports in `packages/ui-app/**`
|
||||
- [ ] Subframe-Output via Adapter, nicht direkt importiert
|
||||
- [ ] Alle UI-Texte als i18n-Keys (M003-Build-Lint blockt sonst)
|
||||
|
||||
### Tests
|
||||
- [ ] **Unit-Test** für VM-Builder mit Zod-Schema-Validierung
|
||||
- [ ] **Smoke-Test** `e2e/smoke/<modul>.spec.ts` (Login → Route → Hauptaktion → erwartetes UI)
|
||||
- [ ] **Hot-Swap-Drill** grün (Smoke-Test gegen `packages/ui-mock` aus M017)
|
||||
- [ ] **Visual-Regression-Snapshot** der Hauptansicht (M016)
|
||||
|
||||
### Klartext (User-facing)
|
||||
- [ ] Fehler-Texte aus M002-Catalog (kein HTTP-Code im UI)
|
||||
- [ ] Empty-State mit Klartext + nächster Aktion
|
||||
- [ ] Loading-State mit Klartext (kein leerer Spinner)
|
||||
- [ ] Permission-Denied → 404, nicht 403 (Bauprinzip A.5.3)
|
||||
|
||||
### Rollback-Pfad
|
||||
- [ ] **Forward-Only-DB-Migration** mit Inverse-SQL als Kommentar
|
||||
- [ ] **Atomic-Slice-Commits** (TC-Default)
|
||||
- [ ] **Feature-Flag** vorhanden, um das Modul ohne Deploy auszuschalten
|
||||
|
||||
---
|
||||
|
||||
## Klick-Pfad zum Prüfen (für User)
|
||||
|
||||
Wenn dieses Milestone fertig ist, prüft der User die Funktion über folgenden Pfad:
|
||||
|
||||
1. Login als geeigneter User-Typ (siehe Erfolgskriterium oben)
|
||||
2. Sidebar-Gruppe + Eintrag öffnen (gemäß INTEGRATION-CONTRACTS.md §1)
|
||||
3. Hauptaktion ausführen
|
||||
4. Erwartetes Ergebnis sichtbar (siehe Erfolgskriterium)
|
||||
|
||||
**Falls etwas nicht erreichbar ist:** Milestone ist trotz „grüner Tests" nicht fertig — siehe Erreichbarkeits-Checkliste oben.
|
||||
|
||||
Loaded 100 of 5955 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user