Refresh HiveGrid Cloud reference snapshot

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

No files matched your search

@@ -26,7 +26,6 @@ Einen **klickbaren Demo-Tenant** für Noah-Demo #1 aufsetzen: über den Plattfor
Noah-Demo #1 (Gate W2) braucht einen realistischen, klickbaren CRM-Stand auf Staging — sonst kein Demo-Beweis und keine Vertriebs-Grundlage. Die Demo nutzt den frisch gebauten Plattform-Admin (AK-P19) als Anlage-Pfad und beweist gleichzeitig die Admin-Tenant-Verwaltung + Auto-SHK-Provisionierung. Validiert außerdem den `is_demo_data`-Lösch-Pfad vor dem Echt-Start.
## Quellen (granular)
- `handouts/akeshan/HANDOUT-AKESHAN.md` → Demo-Setup (AP-6, „CRM-Demo-Daten für Noah-Demo 1 via Admin einrichten", Fr 26.06.)
- abhängig: `AK-P19` (Admin-Tenant-Anlage), `N-DATEN` (Geerkens-Beispieldaten)
- `ENTITY-MODEL.md` → `is_demo_data`-Flag (Entscheidung 16.06., Bulk-Lösch beim Echt-Start) + Domäne 5 (CRM-Kern als Demo-Inhalt)
- `ROADMAP.md` → W2-Gate (Noah-Demo #1)
@@ -3,10 +3,10 @@
| | |
|---|---|
| **Typ** | Dev (Ops/Infra — `typ:external`) |
| **Owner** | Akeshan |
| **Owner** | Raffael (urspr. Akeshan; Umsetzung + Verifikation Raffael, s. Plane-Assignee) |
| **Phase** | P1-Querschnitt (Infra-Schiene, kein Code-Modul) |
| **Cycle/Fenster** | W1 — Fundament & Identität · fällig 2026-06-17 · Gate W1 |
| **Status** | geplant |
| **Status** | **Done** (Plane Done seit 2026-06-20; Audit-bestätigt 2026-07-16) |
## Abhängigkeiten & Parallelität
- **Blocked by:** `EXT-06` (Hetzner-Projekt HiveGrid: S3 + Token + DEK-Master-Key)
@@ -26,7 +26,7 @@ Die **lauffähige Staging-Umgebung** auf der Hetzner/Coolify-Schiene (Infra-Stac
**Live verifiziert (Coolify-API + HTTP):**
- `hivegrid-web`, `hivegrid-api`, `worker-general` = `running:healthy`; `hivegrid-staging-postgres` + `hivegrid-staging-redis` = `running:healthy`.
- `staging-web.hivegrid.de/healthz` + `/readyz` = 200 (`ready` → Postgres über PgBouncer erreichbar), `staging-api.hivegrid.de` ebenso. TLS gültig (HSTS).
- `staging-web.hivegrid.de/healthz` + `/readyz` = 200 (`ready` → Postgres über PgBouncer erreichbar), `staging-api.hivegrid.de` ebenso. TLS gültig (HSTS). *(Hinweis 2026-07-16: der Host heißt inzwischen `staging-app.hivegrid.de` — `staging-web.hivegrid.de` hat keinen DNS-Record mehr.)*
- Deploy-Pipeline rollt `main` aus (Live-Rev `b8fff6fe` = echter main-Commit).
- PgBouncer hat keinen eigenen Coolify-Resource-UUID (vermutlich Sidecar/Teil der PG-URL); der pooled Pfad ist über `/readyz` aber bewiesen.
@@ -45,11 +45,20 @@ falls Staging später öffentlich-sensibler wird — **nicht** Teil dieses Ticke
UserSession+TrustedDevice angewandt), Postgres/Redis/PgBouncer healthy, CI-Pipeline grün, noindex aktiv.
Staging-Access-Gate bewusst deferred (s.o.). Selbst machbar offen: 0. Ticket auf **Done** (Plane). Owner: Raffael.
## Audit-Notiz (2026-07-16, Stand-Audit)
Drei-Quellen-Abgleich (Doc vs. Plane vs. Code/Live) — **DoD 3/3 bestätigt, 100 %**:
- **Live nachgemessen:** `staging-app.hivegrid.de` (ehem. `staging-web`) + `staging-api.hivegrid.de` → `/healthz` + `/readyz` = 200; `X-Robots-Tag: noindex, nofollow` live auf `/login`.
- **Code:** `apps/web/app/utils/seo/noindex.server.ts` + `entry.server.tsx` (`WEB_NOINDEX`-Gate), `public/robots.txt` statisch — auf `main` vorhanden.
- **Pipeline:** Live-Revision auf Staging = `6616cfc3a` (aktueller `main`-Stand zum Audit-Zeitpunkt) → CI rollt weiterhin automatisch aus.
- **Plane:** Status Done (20.06.), Kommentare deckungsgleich mit dieser Doc.
- **Korrigierter Drift:** Status-Header stand fälschlich auf „geplant" (→ Done), Hostname `staging-web` veraltet (→ `staging-app`, s. Hinweis oben), Owner-Zeile präzisiert (Plane-Assignee Raffael).
## Warum
Ohne Staging + DB-Schicht kein Deploy, kein CI-Gate, keine Noah-Demo. Sessions (R-P2a) brauchen Postgres als Source-of-Truth + Redis-Cache (AD-4); PgBouncer für Connection-Pooling unter RLS (`SET LOCAL app.tenant_id` pro Transaktion).
## Quellen (granular)
- `EXTERNALS-CHECKLISTE.md` → C3/C4 (Staging + Coolify-DB)
- `AGENTS.md` → Estate-Infrastruktur und Deploy-Vertrag
- `project_infra_stack` (Memory) → ADR-009/010, Hetzner+Coolify+Cloudflare
- `ROADMAP.md` → Phase 1 (lauffähige Codebasis)
- abhängig: `EXT-06` (S3 + DEK-Master-Key)
@@ -3,10 +3,10 @@
| | |
|---|---|
| **Typ** | Dev (Ops/Infra — `typ:external`) |
| **Owner** | Akeshan |
| **Owner** | Raffael (urspr. Akeshan; Umsetzung + Verifikation Raffael, s. Plane-Assignee) |
| **Phase** | P1-Querschnitt (Infra-Schiene, kein Code-Modul) |
| **Cycle/Fenster** | W1 — Fundament & Identität · fällig 2026-06-18 · Gate W1 |
| **Status** | geplant |
| **Status** | **Done** (Plane Done seit 2026-06-20; Audit-bestätigt 2026-07-16) |
## Abhängigkeiten & Parallelität
- **Blocked by:** `AK-INFRA1` (Staging + Coolify-Apps + DB müssen erst stehen)
@@ -46,11 +46,20 @@ das private Netz, nicht mehr `10.42.0.4`). Voller Ablauf: `docs/ops/prod-rollout
**Status:** **DoD 4/4 erfüllt — 100 %.** Staging-Scope (W1) + Prod-Subdomains+TLS beide live. Selbst
machbar offen: 0. (Estate-Doku im infra-Repo nachgezogen: README-DNS + ADR-016.)
## Audit-Notiz (2026-07-16, Stand-Audit)
Drei-Quellen-Abgleich (Doc vs. Plane vs. Code/Live) — **DoD 4/4 bestätigt, 100 %**:
- **Live nachgemessen:** `app./api./admin./captcha./coolify.hivegrid.de` lösen alle auf und antworten mit gültigem TLS; Staging-Hosts `staging-app`/`staging-api`/`staging-admin` → A `46.225.5.93`, healthy.
- **ENV-Anbindung** (Meili/mCaptcha/ClamAV): per Umsetzungs-Notiz 19.06. belegt; `captcha.hivegrid.de` live erreichbar. Keine Gegenindizien.
- **Plane:** Status Done (20.06.), Kommentare deckungsgleich mit dieser Doc.
- **Korrigierter Drift:** Status-Header stand fälschlich auf „geplant" (→ Done), Owner-Zeile präzisiert (Plane-Assignee Raffael).
- **Außerhalb Ticket-Scope notiert:** `portal.hivegrid.de` hat bis heute keinen DNS-Record, `staging-portal.hivegrid.de` liefert ein ungültiges TLS-Cert (kein LE-Issuer) — gehört zum Portal-Rollout (VA-P26-Umfeld), nicht zu diesem Ticket. Ebenso offen: `CAPTCHA_FAIL_OPEN=false` in Coolify gemäß Hardening-Notiz 2026-07-12 (`docs/ops/prod-rollout-hivegrid.md`) verifizieren.
## Warum
Die Multi-Host-Architektur (App/Admin/Portal getrennte Subdomains, R-P1a) braucht Wildcard-TLS. Die drei Zentral-Dienste sind harte Vorbedingungen: mCaptcha (Login ab 3. Fehlversuch), ClamAV (Upload-Scan), Meilisearch (Suche P11). Anbindung per ENV statt eigener Deployments (Dienste laufen zentral).
## Quellen (granular)
- `EXTERNALS-CHECKLISTE.md` → C1/C2/C5 (DNS/TLS + Zentral-Dienste)
- `AGENTS.md` → Estate-Infrastruktur und zentrale Dienste
- `project_infra_stack` (Memory) → Meilisearch/mCaptcha/ClamAV zentral vorhanden, Cloudflare
- `docs/INTEGRATION-CONTRACTS.md` (URL-Schemata / Subdomains aus R-P1a)
- abhängig: `AK-INFRA1`
@@ -6,7 +6,9 @@
| **Owner** | Akeshan |
| **Phase** | P14 — Email & Marketing |
| **Cycle/Fenster** | W3 — Kern-Kette & Kommunikation (Demo 2) · fällig 2026-06-28 · Gate W3 |
| **Status** | geplant |
| **Status** | Plane: Done · 7/7 Ticket-DoD = 100 % (Code-Audit 2026-07-17 bestätigt) · offen als AGENTS-Pflicht-Nachzug: Interim-Visual-Baseline (D21) · design-nachzug: finale Subframe-Optik (D-P14/D-KAMP) |
**🎨 design-nachzug: offen** (seit 2026-07-09) — Interim-UI aus `~/ui` steht; finale Subframe-Optik aus `D-P14`/`D-KAMP` ausstehend.
## Abhängigkeiten & Parallelität
- **Blocked by:** `EXT-02` (Mailjet Sende-Domain SPF/DKIM/DMARC + Warm-up), `R-P6` (CRM-Kern — Mails/Activity hängen am Kontakt)
@@ -14,6 +16,10 @@
- **Läuft parallel zu:** Raffaels Kern-Kette (P7/P8 Lead/Projekt). **Schema-isoliert** über eigene `prisma/schema/email.prisma` (AD-21); berührt `crm.prisma` nur für die `related_kontakt/projekt_id`-Relation und schreibt in den `Activity`-Stream (R-P6). **Sync-Punkt:** R-P6 (Activity am Kontakt) muss stehen, bevor BCC-Logging andocken kann.
- **Konflikt-Risiko:** gering — additive Tabellen + polymorpher Activity-Write; keine Änderung am CRM-Schema.
**UX-Nachzug (2026-07-25):** `R-UX2` übernimmt den freigegebenen Setup-, Kampagnen-, Segment-,
Versand- und Reporting-Nachzug. AK-P14a bleibt das technische Sende-/Tracking-Fundament und wird
nicht historisch umgedeutet.
## Was wir bauen
Das **v1-Fundament der Email-Welt** (Postfach-Sync ist v2 → P23): pro Mandant eine eigene **Sende-Domain** mit DKIM/SPF/DMARC-Records, Copy-Buttons, 5-Min-Auto-Probe und Status-Ampel (pending/verifying/verified/failed) inkl. Klartext-Fehler nach 7 Tagen. Dazu die **BCC-Logging-Brücke** (`crm@<tenant>…` als BCC → in Gmail/Outlook geschriebene Mails erscheinen als `Activity` am Kontakt, **kein OAuth**), eine **Tenant-Inbound-Adresse** (eingehende Mails → Lead/Activity) und das **Email-Tracking** (Delivery-Status, Open/Click, Bounce-Handling mit Suppression-Eintrag). Versand läuft über **Mailjet** (AD-6, SMTP-Provider-Abstraktion ohne US-Kern-Abhängigkeit). Ohne verifizierte Domain kein Marketing-Versand (Gate für AK-P14b).
@@ -24,13 +30,14 @@ Das **v1-Fundament der Email-Welt** (Postfach-Sync ist v2 → P23): pro Mandant
| Sender + Suppression [`/email-marketing/senders`] | Sender (From-Name/-Email, Domain-DKIM-Status, Default-Marker) · Suppression-Liste (Adresse, Grund Bounce/Beschwerde/manuell) |
## Definition of Done
- [ ] Sende-Domain pro Mandant: DKIM/SPF/DMARC-Records mit Copy, **5-Min-Auto-Probe**, Status-Ampel, Klartext-Fehler nach 7 Tagen
- [ ] **BCC-Logging-Brücke**: Toggle + Anzeige der BCC-Adresse; in nativen Clients geschriebene Mails → `Activity` am Kontakt (kein OAuth)
- [ ] **Tenant-Inbound-Adresse**: eingehende Mails → Lead/Activity
- [ ] **Email-Tracking** + Delivery-Status + Open/Click (IP anonymisiert) + Bounce-Handling → Suppression-Eintrag
- [ ] SMTP-Provider-Abstraktion (Mailjet, AD-6) ohne US-Kern-Abhängigkeit
- [ ] Konnektor `tenantHasModule('email')` (Sidebar + Routes + Actions gated)
- [ ] RLS auf allen Tenant-Tabellen; `is_demo_data` auf seedbaren Sendern/Templates
> Stand 2026-07-17: alle 7 Punkte per Code-Audit gegen `main` verifiziert (Proof-Pfade in der Audit-Notiz unten). Checkliste an den realen Stand angeglichen.
- [x] Sende-Domain pro Mandant: DKIM/SPF/DMARC-Records mit Copy, **5-Min-Auto-Probe**, Status-Ampel, Klartext-Fehler nach 7 Tagen
- [x] **BCC-Logging-Brücke**: Toggle + Anzeige der BCC-Adresse; in nativen Clients geschriebene Mails → `Activity` am Kontakt (kein OAuth)
- [x] **Tenant-Inbound-Adresse**: eingehende Mails → Lead/Activity
- [x] **Email-Tracking** + Delivery-Status + Open/Click (IP anonymisiert) + Bounce-Handling → Suppression-Eintrag
- [x] SMTP-Provider-Abstraktion (Mailjet, AD-6) ohne US-Kern-Abhängigkeit
- [x] Konnektor `tenantHasModule('email')` (Sidebar + Routes + Actions gated)
- [x] RLS auf allen Tenant-Tabellen; `is_demo_data` auf seedbaren Sendern/Templates
## Technische Bausteine
- **Entities** (eigene `prisma/schema/email.prisma`): `TenantSendingDomain` (DKIM/SPF/DMARC-Records, verification_status — **[verschlüsselt][Soft-Delete]**), `TenantInboundAddress` (local_part, purpose lead_inbox/bcc_logging/reply_routing), `Email` (purpose, from_sender_id, delivery_status, related_kontakt/projekt_id), `EmailSender`/`EmailTemplate` (is_default), `EmailSuppressionList` (email_address unique, reason). `crm.prisma` nur für `related_kontakt/projekt_id`-Relation berühren (AD-21).
@@ -43,9 +50,8 @@ Das **v1-Fundament der Email-Welt** (Postfach-Sync ist v2 → P23): pro Mandant
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 8: Kommunikation** (TenantSendingDomain, TenantInboundAddress, Email, EmailSender/Template, EmailSuppressionList)
- `REQUIREMENTS.md` → `REQ-email-datenmodell` (v1-Teil: Sende-Domain + Inbound), `REQ-marketing-versand` (SMTP-Abstraktion Mailjet) · v2-Cut: `REQ-email-sync-strategie`/`REQ-email-inbox-view`
- `ROADMAP.md` → Phase 14 · `PHASE-SOURCES.md` → Phase 14 (M099-email-tracking-bounces; Sende-Domain aus M096 herausgelöst, v1-Pflicht; BCC-Brücke neu)
- `ROADMAP.md` → Phase 14 · Milestones: (M099-email-tracking-bounces; Sende-Domain aus M096 herausgelöst, v1-Pflicht; BCC-Brücke neu)
- `designer-briefs/P14-email-marketing.md` (Sende-Domain-Card, BCC-Toggle, Suppression)
- `_bmad-output/specs/M09-email-inbox.md` (nur Sende-Domain/Inbound/BCC — Rest v2)
## Umsetzung (Akeshan)
@@ -75,16 +81,40 @@ Der CI-Docker-Smoke (`migrate deploy` gegen leere DB + Seed) schlug fehl (`P2022
### DoD-Stand (aktualisiert)
- [x] Sende-Domain DKIM/SPF/DMARC + 5-Min-Probe + Ampel + 7-Tage-Klartext — Backend (S1+S2) + reachable Plain-UI (S6) ✅ (Subframe-Politur = Dev-Nachzug nach David)
- [~] BCC-Logging-Brücke — Toggle + BCC-Adresse-UI ✅ (S6); Mail→Activity-am-Kontakt **blockiert R-P6**
- [~] Tenant-Inbound → Lead/Activity — Schema ✅; Verdrahtung **blockiert R-P6/R-P7**
- [x] BCC-Logging-Brücke — Toggle + BCC-Adresse-UI ✅ (S6); Mailjet-Inbound → `Email` + Kontakt/1-offenes-Projekt-Match + `Activity(email_sent)` ✅
- [x] Tenant-Inbound → Lead/Activity — Mailjet-Inbound → `Email`; bei Kontakt-Match `Activity(email_received)`, sonst `InboxLead` + Lead-Activity ✅
- [x] Email-Tracking + Open/Click (IP anon) + Bounce → Suppression — ✅ (S3+S4; Delivery-Status via Send-Pfad = AK-P14b)
- [x] SMTP-Provider-Abstraktion (Mailjet, AD-6) — ✅ (S5)
- [x] Konnektor `tenantHasModule` (Sidebar/Routes/Actions gated) — ✅ (S8, Feature `email-marketing` + email.domain-Permissions)
- [x] RLS auf allen neuen Tenant-Tabellen; `is_demo_data` auf seedbaren Sendern/Templates — ✅ (S1, RLS deferred-cutover-Artefakt wie hr)
**Stand: 5/7 DoD voll + 2 partiell ≈ ~71 % done.** Selbst-machbar offen (klein): Suppression-Listen-UI im Senders-Screen, e2e-Smoke (braucht laufende Stack+Seed). Extern blockiert: BCC/Inbound→Activity (S7, R-P6/R-P7), finale Subframe-UI (Davids D-P14/D-KAMP-Delta).
### 2026-07-09 — Interim-UI + Suppression-Verwaltung (AD-28)
Interim-Screens aus `~/ui` nachgezogen: Sende-Domain-Route nutzt jetzt `SendingDomainPage` mit VM als Prop und Submit-Callbacks; Sender-Screen zeigt Sender/Webhook-Status plus Suppression-Liste und manuelle Suppression-Aktion. Public Opt-in/Unsubscribe nutzen denselben Interim-Result-Screen. Subframe geprüft: kein P14/D-KAMP-Screen vorhanden, daher AD-28-Interim statt finaler Subframe-Optik.
**Proof:** `pnpm typecheck` grün; `pnpm lint` grün; JSON-Parse en/de grün; `pnpm --filter @hivegrid/view-models test -- --runInBand` grün; gezielte Web-Tests `emailMarketing` + `unsubscribe.$token` + `unsubscribeToken` grün. Breites `pnpm test` bleibt auf Windows rot durch bestehende/unabhängige Guards (`URLSearchParams`-Undici, Symlink-EPERM, Decision-Report-Drift), nicht durch P14.
**Stand: 5/7 DoD voll + 2 partiell ≈ ~71 % done.** Selbst-machbar offen: e2e-Smoke/Visual-Baseline gegen laufenden Stack. Extern blockiert: BCC/Inbound→Activity (R-P6/R-P7), finale Subframe-UI (Davids `D-P14`/`D-KAMP`-Delta).
### 2026-07-09 — Blocker-Recheck
R-P6/R-P7 erneut geprüft: Kontakt-, Lead- und Activity-Code stehen inzwischen im Repo. Damit ist BCC/Inbound→Activity nicht mehr extern durch die Kern-Kette blockiert, sondern ein selbst machbarer Nachzug in AK-P14a. Finale Subframe-Optik bleibt weiter `design-nachzug` über `D-P14`/`D-KAMP`.
**Stand: 5/7 DoD voll + 2 partiell ≈ ~71 % done.** Selbst-machbar offen: BCC-Logging-Mail→Activity, Tenant-Inbound→Lead/Activity, e2e-Smoke/Visual-Baseline gegen laufenden Stack. Extern blockiert: finale Subframe-UI (Davids `D-P14`/`D-KAMP`-Delta).
### 2026-07-09 — Mailjet Tenant-Inbound für BCC + Lead-Inbox
Selbst machbarer Nachzug umgesetzt: neuer DB-Service `ingestTenantInboundEmail` resolved `TenantInboundAddress` für `lead_inbox`/`bcc_logging`, dedupliziert über `Email.messageId`, persistiert `Email` tenant-scoped und matched über `KontaktEmail`. Bei exakt einem offenen `ProjektKontakt` wird `relatedProjektId` gesetzt. `bcc_logging` schreibt `Activity(email_sent)` am Kontakt; `lead_inbox` schreibt bei Kontakt-Match `Activity(email_received)`, sonst einen `InboxLead` plus Lead-Activity. Neue API-Route `POST /v1/email/inbound-mailjet` nutzt die bestehende Mailjet-Basic-Auth und den erweiterten Inbound-Payload-Parser; OpenAPI, CSRF- und Route-Access-Inventar sind nachgezogen.
**Proof:** `pnpm exec vitest run packages/db/src/email-inbound.server.test.ts apps/api/src/app.test.ts apps/api/src/openapi.test.ts apps/api/src/route-access-inventory.test.ts apps/api/src/route-access-inventory-doc.test.ts apps/api/src/csrf-inventory.test.ts` grün (150 Tests); `pnpm --filter @hivegrid/api typecheck` grün; `pnpm --filter @hivegrid/db typecheck` grün; `pnpm lint` grün.
**Stand: 7/7 Ticket-DoD = 100 % done.** Selbst-machbar global offen: e2e-Smoke/Visual-Baseline gegen laufenden Stack. Extern blockiert: finale Subframe-UI (Davids `D-P14`/`D-KAMP`-Delta). Plane-Status daher noch nicht auf Done gesetzt, bis Smoke/Visual bzw. PR-Gates geklärt sind.
### 2026-07-17 — Stand-Audit (Code vs. Plane vs. Doc) + Doc-Reconciliation
Vollständiges Code-Audit gegen `main` (Branch `fix/ak-p14-audit-restwork`): **alle 7 Ticket-DoD-Punkte real erfüllt** — Proofs: `prisma/schema/email.prisma` (TenantSendingDomain inkl. Soft-Delete/Envelope-Key), `apps/worker/src/jobs/email-domain-probe-cron.ts` (5-Min-Cron, 7-Tage-Klartext, `notify()` in `handlers.ts`), `packages/db/src/email-inbound.server.ts` (BCC→`Activity(email_sent)`, Inbound→`InboxLead`+Lead-Activity, messageId-Dedupe, 1-offenes-Projekt-Match), `packages/db/src/email-tracking.server.ts` + Routen `e.o./e.c.$outboundEmailId`, `packages/db/src/email-suppression.server.ts` + Wiring `apps/api/src/email-sequences/provider-webhook-route.ts`, `packages/mail/src/mailjet-dns.ts`, Feature-Gate + `email.domain.*`-Permissions in allen 4 Registries, `TENANT_SCOPED_MODELS` + `prisma/rls/email-isolation.sql` + Migration `20260629120000_p14a_email_foundation`.
**Befunde/Korrekturen:** (1) Der Doc-Header stand noch auf „geplant" und die DoD-Kästchen leer, obwohl Plane seit 2026-07-09/15 Done meldet — angeglichen. (2) Die im Plane-Kommentar vom 2026-07-15 referenzierten Restarbeiten-Artefakte lagen nur auf einem lokalen, nie gepushten Branch (`feat/restarbeiten-initiative`); die Doc-Reconciliation wurde hier **frisch neu** erstellt (nichts von dort übernommen). (3) Doku-Nit: `apps/api/src/webhooks/mailjet-suppression.ts` ist ein reiner Payload-Parser — der Suppression-Upsert läuft über den bestehenden Sequence-Webhook (funktional vollständig). (4) Modul-e2e-Smoke (`tests/e2e/email-marketing-smoke.spec.ts`) neu gebaut, deckt Overview→Kampagnen; ein Sende-Domain-spezifischer Smoke wäre Scope-Erweiterung (nicht gebaut). **Offen als AGENTS-Pflicht-DoD-Nachzug (in Ticket-DoD nie erfasst):** Interim-Visual-Baseline (D21, braucht laufenden Stack), Hot-Swap-Drill-Beleg (D20).
**Stand: 7/7 Ticket-DoD = 100 % done.** Extern: finale Subframe-Optik (`design-nachzug`, D-P14/D-KAMP).
## Dev-Nachzug (nach Davids `D-KAMP`/`D-P14`-Delta)
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [ ] REQUIREMENTS/ROADMAP nachgezogen
- [ ] Plane-Ticket `AK-P14a` aktualisiert
@@ -6,7 +6,9 @@
| **Owner** | Akeshan |
| **Phase** | P14 — Email & Marketing |
| **Cycle/Fenster** | W3 — Kern-Kette & Kommunikation (Demo 2) · fällig 2026-06-29 · Gate W3 |
| **Status** | geplant |
| **Status** | Plane: Done · funktional + Interim-UI fertig (AD-28) · Stand 2026-07-17: 6/7 DoD voll + 1 partiell ≈ ~86 % (tz-Versand-Lücke aus Audit gefixt, e2e-Smoke neu) · design-nachzug: Rich-Text-Editor/Vorschau (D-KAMP) · extern: Lead/Projekt-Segment-Dim (R-P7/R-P8-Folge) · offen: Interim-Visual-Baseline (D21) |
**🎨 design-nachzug: offen** (seit 2026-07-09) — Interim-UI aus `~/ui` steht; finale Subframe-Optik aus `D-P14`/`D-KAMP` ausstehend.
## Abhängigkeiten & Parallelität
- **Blocked by:** `AK-P14a` (verifizierte Sende-Domain + Tracking-Infra + Suppression)
@@ -14,6 +16,10 @@
- **Läuft parallel zu:** Raffaels Kern-Kette. Eigene `prisma/schema/email.prisma` (gleicher Namespace wie AK-P14a, additive Tabellen — AD-21); Segmente lesen CRM-Kontakte read-only (R-P6). **Sync-Punkt:** R-P6 (Kontakt/Tag/Custom-Feld) muss stehen, damit Segment-Filter auflösen.
- **Konflikt-Risiko:** keines auf Schema-Ebene; CRM nur lesend.
**UX-Nachzug (2026-07-25):** `R-UX2` übernimmt den freigegebenen Produkt-/UX-Nachzug für Setup,
Segmente, Kampagnen-Wizard, Versand und Reporting. AK-P14b bleibt das technische Fundament; die
typisierte Ablösung nach AD-2 und bestehende Versandverträge sind zu erhalten.
## Was wir bauen
Das **vollständige DSGVO-konforme Email-Marketing** (bleibt VOLL inkl. A/B): ein mehrstufiger **Kampagnen-Builder** (Basis → Inhalt mit Rich-Text/HTML-Toggle + Personalisierungs-Tokens inkl. Custom-Felder + Pflicht-Footer-Auto-Injektion + Desktop-/Mobile-Vorschau → Empfänger → Test-Versand → Zeitpunkt → Bestätigung mit Klartext-Checkliste), **Segmente** mit verschachteltem AND/OR-Filter-Baum und Auto-Exclusion, **Double-Opt-In**, **One-Click-Unsubscribe** + List-Unsubscribe-Header, eine **BullMQ-Versand-Engine** mit Rate-Limiting/Throttling/geplantem (timezone-aware) Versand, **Reporting** (Open/Click/Bounce/Abmeldung, Klick-Map) und **A/B-Varianten**. Versand wird bei rotem Pflicht-Check (Domain/Unsubscribe/Impressum) **blockiert**.
@@ -27,13 +33,14 @@ Das **vollständige DSGVO-konforme Email-Marketing** (bleibt VOLL inkl. A/B): ei
| 🌐 Unsubscribe-Page [`/unsubscribe/{token}`] | Bestätigungs-Button, optionale Grund-Auswahl, Erfolgs-Meldung, Tenant-Branding |
## Definition of Done
- [ ] **Block-/Rich-Text-Editor** + Personalisierungs-Tokens (auch Custom-Felder) + Pflicht-Footer-Auto-Injektion + Desktop-/Mobile-Vorschau
- [ ] **Segmente**: verschachtelter AND/OR-Filter-Baum, Live-Auflösung, Auto-Exclusion (Unsubscribe/Suppression/kein Opt-In/archiviert/keine Email), dynamisch vs. statischer Snapshot
- [ ] **Versand-Engine** (BullMQ, Rate-Limit, Throttling, geplanter timezone-aware Versand)
- [ ] **Double-Opt-In** (aus Form-Submissions) + **Suppression-Check vor jedem Versand** + **One-Click-Unsubscribe** + List-Unsubscribe-Header
- [ ] **Pflicht-Checkliste** vor Versand (Domain verifiziert / Unsubscribe / Impressum / Subject / >0 Empfänger / Daily-Cap) — Block + Fix-Link bei rotem Check
- [ ] **Reporting** (Open/Click/Bounce/Abmeldung in %, Klick-Map, Pro-Empfänger) + **A/B-Varianten**
- [ ] Konnektor `tenantHasModule('email')`; RLS auf allen Tenant-Tabellen; `is_demo_data` auf Demo-Kampagnen/-Segmenten/-Templates
> Stand 2026-07-17: Checkliste per Code-Audit gegen `main` an den realen Stand angeglichen (Proofs in der Audit-Notiz unten). Die Versand-Engine war zuvor fälschlich als voll abgehakt gemeldet — der timezone-aware Versand fehlte real und wurde jetzt gefixt.
- [ ] **Block-/Rich-Text-Editor** + Personalisierungs-Tokens (auch Custom-Felder) + Pflicht-Footer-Auto-Injektion + Desktop-/Mobile-Vorschau — *teilweise: Token-/Footer-Logik ✅ (pure, getestet), AD-28-Interim-Editor steht; Rich-Text-Toggle + Desktop-/Mobile-Vorschau = design-nachzug (David `D-KAMP`)*
- [x] **Segmente**: verschachtelter AND/OR-Filter-Baum, Live-Auflösung, Auto-Exclusion (Unsubscribe/Suppression/kein Opt-In/archiviert/keine Email), dynamisch vs. statischer Snapshot — *Kontakt-Dimensionen ✅; Lead/Projekt-Dimension extern (R-P7/R-P8-Folge)*
- [x] **Versand-Engine** (BullMQ, Rate-Limit, Throttling, geplanter timezone-aware Versand) — *tz-Auflösung 2026-07-17 nachgezogen (`campaignSchedule.ts`, Audit-Befund)*
- [x] **Double-Opt-In** (aus Form-Submissions) + **Suppression-Check vor jedem Versand** + **One-Click-Unsubscribe** + List-Unsubscribe-Header
- [x] **Pflicht-Checkliste** vor Versand (Domain verifiziert / Unsubscribe / Impressum / Subject / >0 Empfänger / Daily-Cap) — Block + Fix-Link bei rotem Check — *Logik + harter Server-Gate ✅; finale Optik = design-nachzug*
- [x] **Reporting** (Open/Click/Bounce/Abmeldung in %, Klick-Map, Pro-Empfänger) + **A/B-Varianten** — *VMs + A/B-Schema/-Versand ✅; finale Optik = design-nachzug*
- [x] Konnektor `tenantHasModule('email')`; RLS auf allen Tenant-Tabellen; `is_demo_data` auf Demo-Kampagnen/-Segmenten/-Templates
## Technische Bausteine
- **Entities** (eigene `prisma/schema/email.prisma`): `Campaign` (subject, template_id, sender_id, recipient_segment_id, status, delivered/opened/clicked_count), `OutboundEmail` (campaign_id, recipient_kontakt_id, tracking_token, unsubscribe_token, delivery_status), `OutboundEmailOpen`/`Click`, `RecipientSegment` (entity_type, filter_definition JSONB, is_static_snapshot), `Unsubscribe` (kontakt_id, scope, reason). `crm.prisma` nur lesend (Kontakt/Tag/CustomFieldValue).
@@ -45,9 +52,8 @@ Das **vollständige DSGVO-konforme Email-Marketing** (bleibt VOLL inkl. A/B): ei
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 8: Kommunikation** (Campaign, OutboundEmail +Open/Click, RecipientSegment, Unsubscribe)
- `REQUIREMENTS.md` → `REQ-marketing-datenmodell`, `REQ-marketing-double-optin`, `REQ-marketing-versand`
- `ROADMAP.md` → Phase 14 · `PHASE-SOURCES.md` → Phase 14 (M100-editor, M101-segmente, M102-versand-engine, M103-ab-tests-reporting, M104-unsubscribe-bounces — Marketing bleibt VOLL inkl. A/B)
- `ROADMAP.md` → Phase 14 · Milestones: (M100-editor, M101-segmente, M102-versand-engine, M103-ab-tests-reporting, M104-unsubscribe-bounces — Marketing bleibt VOLL inkl. A/B)
- `designer-briefs/P14-email-marketing.md` (Kampagnen-Editor BESPOKE, Segmente, Unsubscribe-Page)
- `_bmad-output/specs/M10-email-marketing.md`
## Umsetzung (Akeshan)
@@ -109,7 +115,34 @@ Unsubscribe-Page-Branding (Davids `D-KAMP`/`D-P14`-Delta), Lead/Projekt-Segmentd
(braucht Stack+Seed) + Visual-Regression (braucht finale UI), Form-Widget→Opt-In-Auto-Trigger. Selbst-machbar
offen: Form-Widget-Trigger verdrahten (klein). **Nicht** anfassen: Alt-Pfad-Migration (R-P14C, Raffael).
### 2026-07-09 — Interim-UI + Campaign-Routen (AD-28)
Interim-Screens aus `~/ui` nachgezogen: Kampagnenliste (`/email-marketing/campaigns`), Draft-Editor (`/campaigns/new`), Kampagnen-Detail/Reporting mit Pre-Send-Checkliste und Send-Action (`/campaigns/:id`), Templates-Liste, Segmente-Screen als `SegmentsPage`, Public Opt-in/Unsubscribe-Result-Screen. Backend ergänzt: Draft-Erstellung auf typisiertem `Campaign`, Detail-Aggregation über `CampaignDetailVM`, Checklisten-Anzeige, Send-Action auf `dispatchCampaign`, Suppression-Verwaltung aus AK-P14a. Subframe geprüft: kein P14/D-KAMP-Screen vorhanden, daher AD-28-Interim statt finaler Subframe-Optik.
**Proof:** `pnpm typecheck` grün; `pnpm lint` grün; JSON-Parse en/de grün; `pnpm --filter @hivegrid/view-models test -- --runInBand` grün; gezielte Web-Tests `emailMarketing` + `unsubscribe.$token` + `unsubscribeToken` grün. Breites `pnpm test` bleibt auf Windows rot durch bestehende/unabhängige Guards (`URLSearchParams`-Undici, Symlink-EPERM, Decision-Report-Drift), nicht durch P14.
### 2026-07-09 — Campaign-Route-Fix + Form-Submission Double-Opt-in
Nachzug auf dem Interim-Stand: Parent-Route `/email-marketing/campaigns` ist jetzt reine Layout-Route mit `Outlet`; die Liste liegt unter `campaigns/index.tsx`, damit `/campaigns/new` und `/campaigns/:id` wirklich rendern. Draft-Save validiert Sender und Segment tenant-scoped vor `Campaign.create` und zeigt einen Klartext-Fehler bei ungültiger Auswahl.
Form-Widget-Post-Submit-Actions um `start_double_opt_in` erweitert: Builder-Auswahl, Save-Parser, Prisma-Enum, Worker-Runner, `FormActionLog`, Consent-Upsert und bestehende `mail.transactional.send`-Outbox. Der Runner resolved Kontakt per `kontaktId` oder E-Mail/Telefon aus dem Field-Mapping, schreibt `KontaktMarketingConsent(single)` mit Opt-in-Token und queued die Bestätigungs-Mail auf `/optin/{token}`. Die Marketing-Token-HMAC-Logik liegt jetzt in `@hivegrid/foundation/marketing-token`, Web re-exportiert den bisherigen Server-Helper weiter.
**Proof:** `pnpm --filter @hivegrid/web typecheck` grün; `pnpm --filter @hivegrid/worker typecheck` grün; `pnpm lint` grün; `pnpm exec vitest run apps/worker/src/jobs/form-submission-actions.test.ts apps/worker/src/jobs/form-submission-route.test.ts 'apps/web/app/routes/app.$tenant/forms.$id.action.test.ts'` grün (23 Tests); `pnpm exec vitest run apps/web/app/utils/email/marketingToken.test.ts` grün (5 Tests). `pnpm --filter @hivegrid/foundation typecheck` bleibt rot durch bestehende Test-Typfehler in `outbound-http.test.ts`/`permissions.test.ts`, nicht durch `marketing-token.ts`.
**Stand: 6/7 DoD voll + 1 partiell ≈ ~86 % done.** Selbst-machbar offen: e2e-Smoke/Visual-Baseline gegen laufenden Stack. Extern blockiert: finale Subframe-Optik (Davids `D-P14`/`D-KAMP`-Delta) und Lead/Projekt-Segmentdimension, soweit Folge-Tickets sie produktisieren.
### 2026-07-17 — Stand-Audit + Restarbeiten (Branch `fix/ak-p14-audit-restwork`)
Vollständiges Code-Audit gegen `main`. Kern bestätigt: Segmente (`segmentFilter.ts` + `SegmentService.server.ts`, 5-fach-Auto-Exclusion, Snapshot), Versand (`campaignSendPlan.ts` d'Hondt-A/B + Throttle, `CampaignSendService.server.ts` harter Checklisten-Gate + Suppression-Re-Check + List-Unsubscribe), DOI/Unsubscribe (`ConsentService.server.ts`, RFC-8058, Form-Action `start_double_opt_in`), Reporting-VMs, Gating/RLS/Migrationen (`20260703150000_ak_schema_parity_catchup` + `20260709213000_ak_p14_form_action_double_opt_in`).
**Audit-Befund + Fix:** Der „timezone-aware Versand" war nur nominell — `scheduledAt` wurde per `new Date()` in Server-Lokalzeit geparst, `campaign.timezone` gespeichert aber nie benutzt (`CampaignSendService.server.ts` nutzte `scheduledAt.getTime()` direkt). Gefixt: neues pures `apps/web/app/utils/integrations/email/campaignSchedule.ts` (`parseScheduledAt` via `date-fns-tz`/`fromZonedTime`, explizite Offsets bleiben, invalide Zone/Datum → Klartext-Fehler `emailMarketing.campaign.editor.error.invalidSchedule` de/en), verdrahtet im Draft-Save (`campaigns/new.tsx`). 6 neue Unit-Tests (Berlin vs. New York, Sommer/Winter, Offset, invalid).
**Test-Nachzug (D18):** `ConsentService.server.test.ts` neu (7 Tests: Opt-in-Upsert, Confirm-Idempotenz, Public-Status-Mapping, Unsubscribe-Idempotenz). VM-Tests existierten bereits (`email-marketing.vm.test.ts` deckt presend-checklist/campaign-detail/campaign-list/segment), personalization ist in `campaignSendPlan.test.ts` abgedeckt — frühere „fehlt"-Meldung war zu pessimistisch. **e2e-Smoke (D19):** `tests/e2e/email-marketing-smoke.spec.ts` neu gebaut (Login → Overview → Kampagnen-Liste, skippt sauber ohne Credentials/Entitlement). Hinweis: Die im Plane-Kommentar vom 2026-07-15 genannten Restarbeiten-Artefakte lagen nur auf einem lokalen, ungepushten Branch — alles hier wurde frisch neu erstellt.
**Proof:** `node scripts/vitest-cli-compat.mjs run campaignSchedule.test.ts` (6) grün · `ConsentService.server.test.ts` (7) grün · `pnpm --filter @hivegrid/web typecheck` exit 0 · `pnpm run verify:i18n` exit 0 · `playwright --list` sammelt den Smoke · eslint grün. Commits: `b79e960bf` (tz-Fix), `f4d019b80` (Consent-Tests), `f16a7e290` (Smoke).
**Staging-Live-Check (2026-07-17, `staging-app.hivegrid.de/demo-pro-crm`):** Overview, Kampagnen-Liste (Empty-State), Sendedomain (Empty-State + Domain-Eingabe) und Segmente (Filter-JSON + Snapshot-Checkbox) rendern live. Befund dabei: Die Overview-Kacheln „Gesendet"/„Zugestellt" zeigten bei Wert 0 gar nichts an — `StatsCard` rendert `{value ? …}`, numerische 0 ist falsy. Gefixt per String-Übergabe im Interim-Screen (kein Eingriff in `~/ui`). Nit notiert (nicht gefixt, Breadcrumb-Thema für Design-Nachzug): Breadcrumb zeigt auf `/campaigns` „Dashboard" und auf `/segments` „E-Mail-Marketing" statt des Screen-Titels.
**Stand: 6/7 DoD voll + 1 partiell ≈ ~86 % done.** Design-nachzug: Rich-Text-Editor + Vorschau (David `D-KAMP`). Extern: Lead/Projekt-Segment-Dimension (R-P7/R-P8-Folge). Offen als AGENTS-Pflicht-DoD-Nachzug (nie in Ticket-DoD erfasst): Interim-Visual-Baseline (D21, braucht laufenden Stack), Hot-Swap-Drill-Beleg (D20).
## Dev-Nachzug (nach Davids `D-KAMP`/`D-P14`-Delta)
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [ ] REQUIREMENTS/ROADMAP nachgezogen
- [ ] Plane-Ticket `AK-P14b` aktualisiert
@@ -6,50 +6,165 @@
| **Owner** | Akeshan |
| **Phase** | P15 — Telefonie & Team-Chat |
| **Cycle/Fenster** | W3 — Kern-Kette & Kommunikation (Demo 2) · fällig 2026-07-01 · Gate W3 |
| **Status** | geplant |
| **Status** | in Umsetzung · 8/9 DoD · Live-Verifikation durch `EXT-08` blockiert |
> 🎨 **design-nachzug: offen** · Nach AD-28 wird eine Interim-UI aus `~/ui` mit VM als Prop gebaut. Das
> ausstehende finale `D-P15`-Delta blockiert den Dev-Abschluss mit Interim-UI nicht.
> **Aircall-Vertragskorrektur 2026-07-15:** HiveGrid nutzt **Technology-Partner-OAuth**, nicht Basic Auth.
> Der Authorization-Code wird gegen einen permanenten, nicht ablaufenden Access Token getauscht. Es gibt in
> diesem Flow keinen Refresh-Token. Details und externe Live-Voraussetzungen stehen in `EXT-08`.
## Abhängigkeiten & Parallelität
- **Blocked by:** `EXT-08` (AirCall-Account/OAuth-App), `R-P5` (Apps-Engine — Telefonie läuft als `DataConnection`), `R-P6` (CRM — Auto-Lead bei unbekannter Nummer, Match auf Kontakt/Lead/Projekt + Activity)
- **Blocks:** `AK-P15b` (Team-Chat)
- **Läuft parallel zu:** Raffaels Kern-Kette. **Sync-Punkt R-P5** (~21.06.): Telefonie ist ein Adapter *hinter* der Apps-Engine — DataConnection/OAuth-Verschlüsselung/Health-Monitoring kommen von dort, nicht selbst gebaut. Eigene `prisma/schema/telephony.prisma` (AD-21). Match/Auto-Lead braucht R-P6 (Kontakt/Lead).
- **Blocked by:** `EXT-08` **nur für den Live-Proof** (Technology-Partner-App, Company-Admin, Test-Nummer);
`R-P5` (Apps-Engine — Telefonie läuft als `DataConnection`) und `R-P6` (CRM — Auto-Lead, Match + Activity)
sind die technischen Vorbedingungen. Fixture-first-Umsetzung kann ohne echten Aircall-Zugang beginnen.
- **Kein technischer Blocker für `AK-P15b`:** Der interne Team-Chat wird parallel umgesetzt und hängt nicht
vom Aircall-Adapter oder dessen externem Live-Proof ab.
- **Design-Abhängigkeit:** `D-P15` liefert das finale Delta, ist nach **AD-28 aber kein harter Dev-Blocker**.
Bis dahin gilt die Interim-UI-Regel inklusive Visual-Baseline und späterem Re-Baseline-Nachzug.
- **Läuft parallel zu:** Raffaels Kern-Kette. Telefonie ist ein Adapter *hinter* der Apps-Engine —
DataConnection-Credentials/DEK-Verschlüsselung/Health-Monitoring kommen von dort, nicht selbst gebaut. Eigene
`prisma/schema/telephony.prisma` (AD-21). Match/Auto-Lead braucht R-P6 (Kontakt/Lead).
- **Konflikt-Risiko:** gering — additive Tabellen; `apps.prisma` + `crm.prisma` nur lesend für Relationen.
- **Auswirkung auf Abhängige (2026-07-15):** Die historische Blockade von `AK-P15b` wurde entfernt, weil
zwischen Chat und Telefonie kein Contract besteht; der offene `EXT-08`-Live-Proof blockiert nur Telefonie.
`VR-P33` implementiert später dasselbe providerneutrale Interface, darf aber keine Aircall-spezifische
HMAC-/Refresh-Annahme erben.
- **Schnittstelle zu `VA-P27a` (2026-07-15):** AK-P15a verdrahtet nur den für eingehende Aircall-Anrufe
nötigen, fixture-testbaren Web-Push-Pfad für Browser mit bereits erteilter Berechtigung. Der allgemeine
Berechtigungs-Pre-Prompt, A2HS und die übrige PWA-/Offline-Härtung bleiben vollständig Scope von `VA-P27a`.
- **Auswirkung des `VR-P33`-Regression-Fixes (2026-08-02):** Der fehlende deploy-seitige
`telephony`-Entitlement-Eintrag betraf die gemeinsame Telefonie-Oberfläche und damit auch Aircall.
Der eng begrenzte Backfill für `starter`/`pro`/`business` stellt das bestehende AK-P15a-Modulgate
wieder her; Provider-Interface, Aircall-OAuth-Vertrag und der offene `EXT-08`-Live-Proof bleiben
unverändert.
## Was wir bauen
Den **AirCall-Adapter** als Referenz-Implementierung hinter dem `TelephonyProviderInterface` (HalloPetra dockt v2 an → P33): **Click-to-Call** und **Inbound-Anrufe** über eine Apps-Engine-`DataConnection` (verschlüsselte OAuth-Tokens, Webhook-Secret). Unbekannte Nummern legen automatisch einen **Lead** an, bekannte werden auf Kontakt/Lead/Projekt **gematcht** (Hard/Soft mit Confidence + Override). Anrufe landen im **Activity-Stream** (in/out/verpasst), nach dem Anruf gibt es einen **Markdown-Notiz-Editor** und eine Recording-Anzeige. **Whisper-Diktat entfällt nach AD-26.** **Anruf-Events** stehen als Automation-Trigger bereit (verpasster Anruf → Rückruf-Aufgabe, verdrahtet in P12).
Den **AirCall-Adapter** als Referenz-Implementierung hinter dem `TelephonyProviderInterface` (HalloPetra dockt
v2 an → P33): **Click-to-Call** und **Inbound-Anrufe** über eine Apps-Engine-`DataConnection`. Der globale
Technology-Partner-Client (`client_id`/`client_secret`) kommt aus der Environment; pro Tenant speichert die
DataConnection den permanenten Aircall-`access_token` und den beim automatischen Webhook-Anlegen gelieferten
Webhook-`token` per Tenant-DEK verschlüsselt. Unbekannte Nummern legen automatisch einen **Lead** an, bekannte
werden auf Kontakt/Lead/Projekt **gematcht** (Hard/Soft mit Confidence + Override). Anrufe landen im
**Activity-Stream** (in/out/verpasst), nach dem Anruf gibt es einen **Markdown-Notiz-Editor** und eine
Recording-Anzeige. **Whisper-Diktat entfällt nach AD-26.** **Anruf-Events** stehen als Automation-Trigger bereit
(verpasster Anruf → Rückruf-Aufgabe, verdrahtet in P12).
## Verbindlicher OAuth-/Endpoint-Vertrag
- Initiator braucht in HiveGrid Tenant-Admin/`telephony.manage` **und muss zugleich Aircall-Company-Admin sein**.
- Install URI: Produktion `https://app.hivegrid.de/integrations/aircall/oauth/install`, Staging
`https://staging-app.hivegrid.de/integrations/aircall/oauth/install`.
- Callback: Produktion `https://app.hivegrid.de/integrations/aircall/oauth/callback`, Staging
`https://staging-app.hivegrid.de/integrations/aircall/oauth/callback`. Ein signierter, kurzlebiger
`state` bindet Tenant, initiierenden User und Nonce; der Tenant steht nicht im Callback-Pfad.
- Der Install-Endpunkt leitet zu `https://dashboard.aircall.io/oauth/authorize` mit `client_id`, festem
`redirect_uri`, `response_type=code`, `scope=public_api` und `state`. Der Callback tauscht den zehn Minuten
gültigen Code über `POST https://api.aircall.io/v1/oauth/token` gegen den **permanenten Bearer-Token**.
- Webhook: Produktion `https://api.hivegrid.de/v1/webhooks/telephony/aircall`, Staging
`https://staging-api.hivegrid.de/v1/webhooks/telephony/aircall`. Die Connection wird über den von Aircall beim
Anlegen gelieferten Webhook-`token` identifiziert. Aircall liefert hier keine HMAC-Signatur; geprüft werden
Token-Zuordnung, erlaubte Eventtypen, Payload-Schema, Idempotenz und Rate-Limit.
- Der Aircall-Admin wählt beim OAuth-Install die Aircall-Nummern, deren Call-Events HiveGrid erhält.
## Benötigte Screens (Backend bedient — Design liefert `D-CHAT` + `D-P15`)
| Screen [Route] | Kern-Inhalt |
|---|---|
| AirCall-Setup [`/settings/integrations/telephony`] | Connect-Card (Status-Ampel connecting/active/error/revoked + Klartext), **User-Binding-Liste** (AirCall-User ↔ HiveGrid-User mit Email-Auto-Match + manueller Korrektur), „Verbindung testen", Trennen mit Bestätigung |
| AirCall-Setup [`/settings/integrations/telephony`] | Technology-Partner-OAuth-Connect; Hinweis „HiveGrid-Tenant-Admin und Aircall-Company-Admin erforderlich"; Connect-Card (connecting/active/error/revoked), **User-Binding-Liste** (AirCall-User ↔ HiveGrid-User mit Email-Auto-Match + manueller Korrektur), „Verbindung testen", Trennen/Reinstall mit Bestätigung |
| Anruf-Liste + -Detail [`/calls`] | Liste (Nummer/Richtung/Dauer/gematchter Kontakt mit Confidence/Notiz-Snippet/verpasst-Marker); Detail mit **Match-Override**, Markdown-Notiz-Editor, Aufnahme-Link, Click-to-Call + eingehender-Anruf-Notification |
*(Click-to-Call-Buttons leben außerdem in Kontakt-/Lead-/Projekt-Detail aus P6/P7/P8.)*
## Definition of Done
- [ ] **AirCall-Connect** (OAuth, verschlüsselte Tokens, Webhook-Secret) **über die Apps-Engine** mit Klartext-Status-Diagnose
- [ ] **User-Bindings** mit Email-Auto-Match-Vorschlag + manueller Zuordnung
- [ ] **Click-to-Call** aus Kontakt-/Lead-/Projekt-Detail; Mehrfach-Nummern → Auswahl-Modal; Klartext-Edge-Cases (kein Binding / keine Connection / API-Fehler / ungültige Nummer); `tel:`-Fallback ohne Connection
- [ ] **Inbound**: Auto-Match (Hard/Soft mit Confidence), unbekannte Nummer → **Auto-Lead**, Push-Notification beim Klingeln
- [ ] **Anruf-Logging** in Activity-Stream + Markdown-Notiz-Editor + Recording-Anzeige + Match-Override
- [ ] **Anruf-Events als Automation-Trigger** (verpasster Anruf → Rückruf-Aufgabe — Verdrahtung P12)
- [ ] `TelephonyProviderInterface` mit AirCall als **Referenz-Adapter** (HalloPetra dockt v2 an)
- [ ] Konnektor `tenantHasModule('telephony')`; RLS auf allen Tenant-Tabellen
- [x] **AirCall-Connect per Technology-Partner-OAuth** über die Apps-Engine: CSRF-sicherer `state`, Callback/
Code-Tausch, permanenter Access Token und Webhook-Token per Tenant-DEK verschlüsselt, Company-Admin-Prüfung,
`/v1/ping` und Klartext-Status-Diagnose; kein Basic Auth/Refresh-Token/HMAC-Scheinvertrag
- [x] **User-Bindings** mit Email-Auto-Match-Vorschlag + manueller Zuordnung
- [x] **Click-to-Call** aus Kontakt-/Lead-/Projekt-Detail; Mehrfach-Nummern → Auswahl-Modal; Klartext-Edge-Cases (kein Binding / keine Connection / API-Fehler / ungültige Nummer); `tel:`-Fallback ohne Connection
- [x] **Inbound**: Auto-Match (Hard/Soft mit Confidence), unbekannte Nummer → **Auto-Lead**, Push-Notification beim Klingeln
- [x] **Anruf-Logging** in Activity-Stream + Markdown-Notiz-Editor + Recording-Anzeige + Match-Override
- [x] **Anruf-Events als Automation-Trigger** (verpasster Anruf → Rückruf-Aufgabe — Verdrahtung P12)
- [x] `TelephonyProviderInterface` mit AirCall als **Referenz-Adapter** (HalloPetra dockt v2 an)
- [x] Konnektor `tenantHasModule('telephony')`; RLS auf allen Tenant-Tabellen
- [ ] **Fixture-first + Live-Proof:** deterministische OAuth-/API-/Webhook-Fixtures und HTTP-Fakes grün; danach
echter Install/Callback, Nummernauswahl, Click-to-Call und mindestens ein Call-Webhook auf Staging mit `EXT-08`
## Technische Bausteine
- **Entities** (eigene `prisma/schema/telephony.prisma`): `TelephonyConnection` (provider aircall, oauth_token **verschlüsselt**, webhook_secret — max. 1 aktiv/Tenant), `TelephonyUserBinding` (tenant_user_id ↔ provider_user_id), `TelephonyCallSession` (direction, status, from/to_number E.164, matched_kontakt/lead/projekt_id polymorph, note, recording_url), `TelephonyWebhookEvent` (event_type, signature_valid, [append-only][30d]). `apps.prisma`/`crm.prisma` nur lesend für Relationen (AD-21).
- **Telefonie = Apps-Engine-Adapter** (R-P5): DataConnection-Lifecycle/OAuth-Verschlüsselung/Health vom Framework; hier nur der `TelephonyProviderInterface`-Adapter.
- **Webhook-Verarbeitung** mit Signatur-Check; Match-Heuristik (E.164-Normalisierung, Hard/Soft).
- **Entities** (eigene `prisma/schema/telephony.prisma`): `TelephonyConnection` (`provider=aircall`,
`data_connection_id`, `provider_company_id`, `webhook_id`, `webhook_token_hash` — max. 1 aktiv/Tenant),
`TelephonyUserBinding` (tenant_user_id ↔ provider_user_id), `TelephonyCallSession` (direction, status,
from/to_number E.164, matched_kontakt/lead/projekt_id polymorph, note, recording_url),
`TelephonyWebhookEvent` (event_type, `provider_auth_valid`, [append-only][30d]). Permanenter Access Token und
Webhook-Token liegen verschlüsselt in `DataConnection.credentials`; `apps.prisma`/`crm.prisma` nur lesend für
Relationen (AD-21). `webhook_token_hash` ist nur ein lokaler, einwegiger Lookup-Digest für den öffentlichen
Endpoint und keine von Aircall gelieferte HMAC-Signatur.
- **Telefonie = Apps-Engine-Adapter** (R-P5): DataConnection-Lifecycle/Credential-Verschlüsselung/Health vom
Framework; hier nur der `TelephonyProviderInterface`-Adapter. Für Aircall gibt es keinen Token-Refresh.
- **Webhook-Verarbeitung** mit Webhook-Token-Zuordnung statt HMAC-Signatur, Event-Allowlist, Idempotenz und
Rate-Limit; Match-Heuristik (E.164-Normalisierung, Hard/Soft).
- **Activity-Write** (in/out/verpasst) + Automation-Trigger-Emit.
- **RLS** überall; OAuth per-Tenant-DEK (AD-8, via Apps-Engine). `is_demo_data` auf Demo-Anrufen.
- **Provider-Interface:** providerneutral `connect`/`disconnect`/`listProviderUsers`/`triggerOutboundCall`/
`subscribeToWebhooks`/`validateWebhook`/`parseWebhookEvent`/`getRecordingUrl`; `validateWebhook` erlaubt
Aircalls Token-Abgleich und bei anderen Providern eine tatsächliche Signaturprüfung.
- **RLS** überall; permanente Aircall-Credentials per Tenant-DEK (AD-8, via Apps-Engine). `is_demo_data` auf
Demo-Anrufen.
- **Teststrategie:** zuerst versionierte Fixtures für OAuth-Responses, Users, Calls und alle verwendeten
Webhook-Events; Netzwerkzugriffe via HTTP-Fake/Contract-Test. Der echte Account ist ausschließlich der letzte
Live-Verifikationsschritt und darf Unit-/Integrationstests nicht flakey machen.
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 8: Kommunikation** (TelephonyConnection/UserBinding/CallSession/WebhookEvent; HalloPetra = v2)
- `REQUIREMENTS.md` → `REQ-telefonie-datenmodell`, `REQ-telefonie-provider-adapter`
- `ROADMAP.md` → Phase 15 · `PHASE-SOURCES.md` → Phase 15 (M106-aircall, M107-anruf-eingang, M108-anruf-ausgang, M109-voicemail-notizen; M105 HalloPetra → v2)
- `ROADMAP.md` → Phase 15 · Milestones: (M106-aircall, M107-anruf-eingang, M108-anruf-ausgang, M109-voicemail-notizen; M105 HalloPetra → v2)
- `designer-briefs/P15-telefonie-chat.md` (AirCall-Setup, Anruf-Liste/Detail, Provider-Interface)
- `_bmad-output/specs/M12-telefonie.md`
- [Aircall OAuth für Technology Partners](https://developer.aircall.io/tutorials/how-aircall-oauth-flow-works/)
- [Aircall API Reference](https://developer.aircall.io/api-references/)
## Dev-Nachzug (nach Davids `D-CHAT`/`D-P15`-Delta)
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [ ] REQUIREMENTS/ROADMAP nachgezogen
- [ ] Plane-Ticket `AK-P15a` aktualisiert
## Umsetzungs-Notiz
- **2026-07-15 · 0/9 DoD = 0 % done:** Planungsvertrag auf Aircall Technology-Partner-OAuth korrigiert und
Fixture-first/Live-Grenze festgelegt. Keine DoD als umgesetzt markiert. Selbst machbar: Fixture-first-Bau;
extern blockiert: Live-Proof aus `EXT-08`; finales Design läuft nach AD-28 als Nachzug.
- **2026-07-15 · 7/9 DoD = ~78 % done:** Fixture-first-Implementierung in der separaten Worktree
`HiveGrid-Cloud-aircall` auf `feature/ak-p15a-aircall`: providerneutrales Interface und Aircall-Adapter,
OAuth/DataConnection-Lifecycle, User-Bindings, Click-to-Call, Webhook-Inbox mit Wiederanlauf und
Idempotenz, Inbound-Matching/Auto-Lead, Activity/Notiz/Recording/Match-Override, Automation-Trigger,
Web-Push sowie die AD-28-Interim-UI umgesetzt. Proof: kompletter Testlauf `5054 passed`, Typechecks für
Web/API/Worker/Integrations/Queue/View-Models, Prisma-Validierung, RLS-Vertrag `268/268`,
Cross-Cutting-Registries `266/266` und `187/187`, UI-Visual `72 passed` sowie Hot-Swap grün. Offen und
selbst machbar beim Merge: Forward-only-Migration inklusive RLS-Policies und anschließender Forced-RLS-Proof;
die Paritätsprüfung weist bis dahin erwartungsgemäß nur die vier neuen Telefonie-Tabellen aus. Extern
blockiert durch `EXT-08`: echter Aircall-Install/Callback, Nummernauswahl, Click-to-Call und Call-Webhook auf
Staging.
- **2026-07-15 · 8/9 DoD = ~89 % done:** Forward-only-Migration
`20260715035000_ak_p15a_aircall_telephony` ergänzt. Sie legt die sechs Telefonie-Enums und vier typisierten
Tabellen an, aktiviert und erzwingt RLS auf allen vier Tabellen, installiert den engen
`hivegrid_resolve_aircall_webhook`-Resolver und enthält die kommentierte Inverse-SQL. Proof gegen frisches
PostgreSQL: Migrations-Parität ohne Drift, RLS-Release-Readiness `225/225` für `ENABLE`/`FORCE`/Policies,
Runtime-Vertrag `268/268`, Restricted-Role-Live-Suite `39 passed` inklusive Tenant-A/B-Isolation,
Cross-Tenant-Write-Abweisung sowie verweigertem Worker-/Authentik-JIT-Resolverzugriff. Selbst machbar offen:
nichts. Extern blockiert durch `EXT-08`: echter Aircall-Install/Callback, Nummernauswahl, Click-to-Call und
Call-Webhook auf Staging. Atomare Implementierungs-Commits: `431757ddb`, `be01b2c18`, `a2bbc3fa1`,
`70e8dd93e`, `d3bc9550f`, `f93f749ee`, `6fa2224c6`, `f5a34ea82`, `b17a089cb`.
- **2026-07-17 · Stand-Audit bestätigt 8/9 DoD = ~89 % done:** Vollaudit (Code auf `main` gegen jede DoD
einzeln geprüft) bestätigt alle acht abgehakten Punkte inhaltlich; keine fehlenden DoD-Punkte gefunden.
Proof-Korrektur: Die oben genannten atomaren Commits stammen aus dem separaten Worktree-Branch und sind
im Squash-Merge aufgegangen — der auflösbare Proof auf `main` ist **PR #117 = `083f3cd69`**
(`feat(AK-P15a): Aircall-Telefonie integrieren`). Zentrale Belege: HMAC-`state`
(`aircallOAuthState.server.ts`), DEK-verschlüsselte Credentials
(`AircallConnectionService.server.ts`), Click-to-Call-Edge-Cases (`click-to-call.vm.ts`),
Inbound-Match/Auto-Lead (`apps/worker/src/jobs/telephony-webhook.ts`), Activity via `logActivity` und
Klingel-Benachrichtigung via `notify()` (`telephony-webhook-prisma.ts`), Webhook-Endpoint mit
Token-Zuordnung/Allowlist/Idempotenz/Rate-Limit (`aircall-webhook-route.ts`), FORCE-RLS-Migration mit
Inverse-SQL, Smoke `tests/e2e/telephony-aircall-interim.smoke.spec.ts`, Interim-Visual-Baseline und
Hot-Swap. Der damalige Milestone-Tracker M106–M109 wurde auf diesen Stand nachgezogen (er stand fälschlich auf
„NICHT-GESTARTET"). Hinweis für P12: `telephony.call.missed/completed` wird als Workflow-Outbox-Event
emittiert, hat aber noch keinen kuratierten Eintrag im Automation-Trigger-Katalog/UI — Verdrahtung
gehört laut DoD 6 zu P12. Offen bleibt allein DoD 9 (Live-Proof), extern blockiert durch `EXT-08`;
das Aircall-Konto ist beantragt (2026-07-17), Freischaltung ausstehend.
@@ -3,19 +3,35 @@
| | |
|---|---|
| **Typ** | Dev (Code) |
| **Owner** | Akeshan |
| **Owner** | Akeshan + Raffael |
| **Phase** | P15 — Telefonie & Team-Chat |
| **Cycle/Fenster** | W3 — Kern-Kette & Kommunikation (Demo 2) · fällig 2026-07-02 · **Gate W3 (Demo 2)** |
| **Status** | geplant |
| **Status** | Dev-DoD vollständig umgesetzt · 8/8 DoD = 100 % done · design-nachzug offen |
> 🎨 **design-nachzug: offen** · Nach AD-28 wird zunächst eine Interim-UI aus `~/ui` mit VM als Prop gebaut.
> Das finale `D-CHAT`/`D-P15`-Delta bleibt ein getrackter Nachzug und blockiert den Dev-Abschluss nicht.
## Abhängigkeiten & Parallelität
- **Blocked by:** `AK-P15a` (P15-Vorlauf), `AK-P4a` (Files — Chat-Anhänge via FileEntityLink)
- **Technische Vorbedingungen:** `AK-P4a` ist erledigt; die bestehende Files-Pipeline wird für Chat-Anhänge
wiederverwendet. Die historische Reihenfolge hinter `AK-P15a` wurde am 2026-07-15 aufgehoben: Der interne
Team-Chat hängt weder vom Aircall-Adapter noch von dessen extern blockiertem Live-Proof ab.
- **Blocks:** **Demo 2** (Noah-Demo #2, Gate W3)
- **Läuft parallel zu:** Raffaels Kern-Kette. Eigene `prisma/schema/chat.prisma` (AD-21); entity-linked Channels referenzieren Projekt aus dem CRM-Kern (R-P6/P8) read-only. **Sync-Punkt:** ProjektMitglied-Sync braucht den Projekt-Kern (P8/P9).
- **Konflikt-Risiko:** keines auf Schema-Ebene; `crm.prisma`/`files.prisma` nur lesend.
- **Konflikt-Risiko:** gering, aber nicht null. Das Fachschema bleibt in `prisma/schema/chat.prisma`; additive
Querschnittsänderungen an Feature-Gates, Permissions, File-Verknüpfungen, Sidebar und Projekt-Hooks werden
mit ihren Konsumenten geprüft.
## Was wir bauen
Den **Real-Time-Team-Chat (Bespoke, AD-9)**: WebSocket-Messaging mit **Presence, Typing-Indicator, Read-Receipts** über Redis-Pub/Sub (Scale-Out), drei **Channel-Typen** (public/private Group, DM, entity-linked Projekt mit ProjektMitglied-Sync), **@Mentions** (User/Projekt/Kontakt/Firma) mit Autocomplete, **Threads, Reactions, Pins** (max 50), **File-Uploads** (via Files), Link-Previews, **Mark-as-Task** und **Cross-Channel-Suche**. Mobile-First für Monteure (vereinfachte View, Foto-Direct-Upload, Push). Ein **Admin-Audit-Modus** (`read_all_channels`) erfordert Begründungs-Pflicht je Session + DM-Audit-Banner und wird audit-geloggt.
Den **Real-Time-Team-Chat (Bespoke, AD-9)**: WebSocket-Messaging mit **Presence, Typing-Indicator,
Read-Receipts** über Redis-Pub/Sub (Scale-Out), drei **Channel-Typen** (public/private Group, DM,
entity-linked Projekt mit ProjektMitglied-Sync), **@Mentions** (User/Projekt/Kontakt/Firma) mit Autocomplete,
**Threads, Reactions, Pins** (max 50; nicht in DMs), **File-Uploads** (via Files), einfache **Voice Notes** ohne
Transkript, Link-Previews, **Mark-as-Task** und **Cross-Channel-Suche**. Die UX folgt dem verbindlichen Vertrag
in `docs/features/chat.md`: Local Echo mit `sending/sent/failed`, idempotentes Retry, Cursor-Reconnect,
Scroll-Anchoring, Draft-Autosave sowie vollständige Keyboard-/Screenreader-Bedienung. Mobile-First für
Monteure mit vereinfachter View, Foto-Direct-Upload und In-App-Notification/Deep Link; allgemeines Browser-
Push bleibt `VA-P27a`. Ein **Admin-Audit-Modus** (`read_all_channels`) unter `/settings/chat/audit` erfordert
Begründungs-Pflicht je Session + DM-Audit-Banner und wird audit-geloggt.
## Benötigte Screens (Backend bedient — Design liefert `D-CHAT` + `D-P15`)
| Screen [Route] | Kern-Inhalt |
@@ -25,20 +41,27 @@ Den **Real-Time-Team-Chat (Bespoke, AD-9)**: WebSocket-Messaging mit **Presence,
| Thread-Detail [`/chat/:id/thread/:thread_id`] | Eltern-Nachricht + Replies (Side-Panel oder Route), eigener Composer |
| Pinned-Übersicht [`/chat/:id/pinned`] · Mentions-Aggregat [`/chat/mentions`] · Cross-Channel-Suche [`/chat/search`] | Pins (max 50), kanalübergreifende Mentions, Volltext-Suche über erlaubte Channels |
| Neuer Channel / DM [`/chat/new`] · Channel-Settings | Group/DM-Modal; Members/Privacy/Archivieren/verlassen |
| Admin-Chat-Übersicht [`/admin/chat`] | Alle Channels + Cleanup; **DM-Audit mit Begründungs-Pflicht-Banner**; Force-Member-Edit/Delete |
| Admin-Chat-Übersicht [`/settings/chat/audit`] | Tenantinterne Übersicht aller Channels + Cleanup; **DM-Audit mit Begründungs-Pflicht-Banner**; Force-Member-Edit/Delete |
## Definition of Done
- [ ] **WebSocket-Real-Time**: Presence, Typing, Read-Receipts, Redis-Pub/Sub (AD-9), Optimistic-UI, Reconnect
- [ ] **3 Channel-Typen**: public/private Group, DM, entity-linked (Projekt) mit **ProjektMitglied-Sync**
- [ ] **@Mentions** mit Autocomplete + **Threads** + **Reactions** + **Pins** (max 50) + **File-Uploads** (Files) + Link-Previews + **Mark-as-Task**
- [ ] Channel-Index (Filter/Suche/Pin/Mute/Archiv + Channel-Browser) + **Cross-Channel-Suche** + Mentions-Aggregat
- [ ] Entity-linked Channel erscheint im Projekt-Detail (P8/P9)
- [ ] **Admin-Audit** (`read_all_channels`): Begründungs-Pflicht je Session + DM-Audit-Banner, audit-geloggt
- [ ] **Mobile-First-Variante** für Monteure (vereinfachte View, Foto-Direct-Upload, Push)
- [ ] Konnektor `tenantHasModule('chat')`; RLS auf allen Tenant-Tabellen
- [x] **WebSocket-Real-Time**: Presence, Typing, Read-Receipts, Redis-Pub/Sub (AD-9), Optimistic-UI, Reconnect
- [x] **3 Channel-Typen**: public/private Group, DM, entity-linked (Projekt) mit **ProjektMitglied-Sync**
- [x] **@Mentions** mit Autocomplete + **Threads** + **Reactions** + **Pins** (max 50; nicht in DMs) +
**File-Uploads** (Files) + einfache **Voice Notes** ohne Transkript + Link-Previews + **Mark-as-Task**
- [x] Channel-Index (Filter/Suche/Pin/Mute/Archiv + Channel-Browser) + **Cross-Channel-Suche** + Mentions-Aggregat
- [x] Entity-linked Channel erscheint im Projekt-Detail (P8/P9)
- [x] **Admin-Audit** (`read_all_channels`): Begründungs-Pflicht je Session + DM-Audit-Banner, audit-geloggt
- [x] **Mobile-First-Variante** für Monteure (vereinfachte View, Foto-Direct-Upload, In-App-Notification und
Deep Link; allgemeines Browser-Push bleibt Scope von `VA-P27a`)
- [x] Konnektor `tenantHasModule('chat')`; RLS auf allen Tenant-Tabellen
## Technische Bausteine
- **Entities** (eigene `prisma/schema/chat.prisma`): `TeamChat` (kind project/group/dm, projekt_id, archived_reason, last_message_at), `TeamChatMember` (role_in_chat, last_read_message_id, is_pinned), `TeamChatMessage` (author, body Markdown, parent_message_id, mentions[], attachments[]), `TeamChatThread`/`PinnedMessage`/`Reaction`/`Read`. `crm.prisma` (Projekt für entity-linked), `files.prisma` (Anhänge via FileEntityLink) nur lesend (AD-21).
- **Entities** (eigene `prisma/schema/chat.prisma`): `TeamChat` (kind project/group/dm, projekt_id,
archived_reason, last_message_at), `TeamChatMember` (role_in_chat, last_read_message_id, is_pinned),
`TeamChatMessage` (author, body Markdown, parent_message_id, client_message_id, mentions[]),
`TeamChatThread`/`PinnedMessage`/`Reaction`/`Read`. `crm.prisma` bleibt für Projekt read-only;
`files.prisma` erhält ausschließlich den additiven `FileEntityType.chat_message`, Anhänge laufen über
`FileEntityLink` (AD-21).
- **Real-Time-Layer**: WebSocket-Gateway + Redis-Pub/Sub für Presence/Typing/Fan-out (AD-9); Read-Receipt-Aggregation „X von Y gelesen".
- **RLS** auf allen Tabellen; Channel-Permission je Typ; Admin-Audit-Read gegated + audit-geloggt (AuditEntry).
- **Mark-as-Task** schreibt in das Tasks-Modul (AK-P4b, EntityLink).
@@ -47,11 +70,86 @@ Den **Real-Time-Team-Chat (Bespoke, AD-9)**: WebSocket-Messaging mit **Presence,
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 8: Kommunikation** (TeamChat/Member/Message/Thread/PinnedMessage/Reaction/Read)
- `REQUIREMENTS.md` → `REQ-chat-datenmodell`, `REQ-chat-realtime`, `REQ-chat-features`
- `ROADMAP.md` → Phase 15 · `PHASE-SOURCES.md` → Phase 15 (M110-channel-permissions, M111-direkt-nachrichten, M112-anhaenge, M113-modul-verknuepfungen, M114-mentions-push — Chat bleibt VOLL)
- `ROADMAP.md` → Phase 15 · Milestones: (M110-channel-permissions, M111-direkt-nachrichten, M112-anhaenge, M113-modul-verknuepfungen, M114-mentions-push — Chat bleibt VOLL)
- `designer-briefs/P15-telefonie-chat.md` (Chat-UI BESPOKE, Admin-DM-Audit, Mobile-First)
- `_bmad-output/specs/M13-team-chat.md`
- `docs/features/chat.md` (Research-basierter Produkt-, QoL-, Accessibility- und UI-Wiederverwendungsvertrag)
## Dev-Nachzug (nach Davids `D-CHAT`/`D-P15`-Delta)
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [ ] REQUIREMENTS/ROADMAP nachgezogen
- [ ] Plane-Ticket `AK-P15b` aktualisiert
## Festgezogene Scope-Entscheidungen (2026-07-15)
- Chat-v1 nutzt `notify()` mit In-App-Notification und Deep Link; allgemeines Browser-Push bleibt `VA-P27a`.
- Voice Notes sind einfache Audio-Anhänge ohne Transkript oder KI-Verarbeitung.
- Der tenantinterne Admin-Audit liegt unter `/settings/chat/audit`.
- DMs unterstützen keine Message-Pins.
- `FileEntityType.chat_message` wird additiv ergänzt; es entsteht kein paralleles Attachment-System.
## Umsetzungs-Notiz
- **2026-07-15 · 0/8 DoD = 0 % done:** Planung im separaten Worktree `HiveGrid-Cloud-team-chat` auf
`feat/ak-p15b-team-chat` gestartet und Branch auf Gitea veröffentlicht. Akeshan und Raffael sind in Plane
gemeinsam zugewiesen; das Ticket steht auf `In Progress`. Ausgangsstand auf aktuellem `main`: Typecheck,
Lint und Core-Testlauf mit
`5.061 passed` grün. Noch keine Fachimplementierung; alle acht DoD sind offen und selbst machbar. Die
Scope-Entscheidungen und der Research-Vertrag in `docs/features/chat.md` sind nun festgezogen. Externe
Blocker: keine.
- **2026-07-15 · 1/8 DoD = ~13 % done:** Die tenant- und session-sichere Realtime-Foundation ist mit den
Commits `4825c5fbb`, `1e960cef6` und `464c1c47b` umgesetzt und auf Gitea veröffentlicht: versioniertes
Wire-Protokoll, resilienter Browser-Client mit Local Echo/Cursor-Reconnect, kurzlebige Gateway-JWTs,
Redis-Pub/Sub für Presence und Typing, Read-Receipts, Live-Revalidierung von Session/Permission/Modul,
atomare Token- und Connection-Limits sowie ein gehärtetes WebSocket-Gateway. Proof: `pnpm typecheck`,
`pnpm lint`, `pnpm test` (`5.137 passed`), Coverage-Gate, API-Build und relevante `verify:*`-Checks grün;
echter Redis-7-Smoke grün; `verify:rls-live` mit `42/42` Kern- und `2/2` Chat-Isolationstests grün.
`tenantHasModule('chat')` ist an Route und Gateway gebunden, der generierte Tenant-Policy-Vertrag ist für
alle Chat-Tabellen grün; damit ist DoD 8 vollständig erfüllt. DoD 1 bleibt offen, bis Index/Detail,
Optimistic UI und der Zwei-Nutzer-Live-Smoke Ende-zu-Ende verdrahtet sind. Nächster selbst machbarer Slice:
Member-Channel-Live-Loop. Externe Blocker: keine.
- **2026-07-15 · 2/8 DoD = 25 % done:** Der Member-Channel-Live-Loop ist Ende-zu-Ende verdrahtet: sichere
Channel-/Message-Projektion, Optimistic UI mit idempotentem Retry, Cursor-Reconnect, Draft-Autosave,
Scroll-Anchoring, Presence-Snapshot, Typing und gebündelte Read-Receipts. Der lokale Zwei-Browser-Smoke
belegt mit echtem PostgreSQL, Redis und WebSocket-Gateway: ein bereits verbundener Peer wird als anwesend
angezeigt, Typing erscheint live, die Nachricht erreicht den Peer ohne Reload, das Read-Receipt kommt zum
Absender zurück und die Nachricht bleibt nach Reload erhalten. Ergänzend sind Interim-Pixel-Baselines,
Hot-Swap-Fixtures sowie Repository-/Gateway-/Client-Tests grün. Proof: Commits `a425448bc`, `03c6ed637`,
`face49526`, `a8039bc25`, `63a74b727`, `e613af4ad` und `fa1ee4a1a`; `pnpm typecheck`, `pnpm lint`,
`pnpm test` (`5.230 passed`), Paket-Suite, API-Typecheck/-Build, 324/324 fokussierte Chat-Tests,
Component-Pixeltests 2/2, Zwei-Nutzer-E2E 1/1, UI-Mock/Hot-Swap und die Live-RLS-Suite mit 42/42 Kern-
plus 3/3 Chat-Isolationstests grün. Damit ist DoD 1 vollständig erfüllt; DoD 8 bleibt erfüllt.
**Offen: 6 DoD, davon 6 selbst machbar und 0 extern blockiert.**
- **2026-07-16 · 8/8 DoD = 100 % done:** Public/private Groups, kanonische DMs und entity-linked
Projekt-Channels sind inklusive atomarem ProjektMitglied-/Berechtigungsgruppen-Sync umgesetzt. Mentions
für User/Projekt/Kontakt/Firma, Threads, Reactions, DM-ausgeschlossene Pins mit 50er-Limit,
Files-Anhänge mit AV-Freigabe, einfache Voice Notes, gehärtete Link-Previews und Mark-as-Task sind
Ende-zu-Ende verdrahtet. Channel-Browser, Filter, Cross-Channel-Suche, Mentions-Aggregat,
Projekt-Detail-Link und der begründungspflichtige read-only Admin-Audit mit DM-Banner stehen als
Interim-UI aus `~/ui`. Der mobile Pfad enthält Master/Detail-Navigation, Safe-Area-/44px-Touch-Ziele,
Kamera-Upload und In-App-Notifications mit exaktem Deep Link. Browser-Push bleibt bei `VA-P27a`;
Transkription, KI und persistente Offline-Outbox wurden nicht vorgezogen. Modul-, Permission-, Audit-,
Activity-, Search- und FORCE-RLS-Verträge sind angebunden. **Proof:** Commits `884ac7ed7`, `f16e2575b`,
`4eebc5144`, `373b589ed`, `cf258947e` und `1d4485fb8`; Forward-only-Migration
`20260716090000_ak_p15b_team_chat`; `pnpm typecheck`, `pnpm lint`, `pnpm test` (5.729 passed),
Coverage-Gate, Migration-Parität und Tenant-Policy-Contract grün; Live-RLS mit allen neun Chat-Suiten,
14/14 Contract-/UI-Gates, 96/96 Visual-Checks sowie 3/3 Component-Pixel-/Mobile-Tests grün.
**Offen: 0/8 DoD; 0 selbst machbar, 0 extern blockiert.** Das finale `D-CHAT`/`D-P15`-Delta bleibt als
`design-nachzug: offen` getrackt und ist nach AD-28 kein Done-Blocker.
- **2026-07-17 · Stand-Audit bestätigt 8/8 DoD = 100 % done:** Vollaudit (Code auf `main` gegen jede DoD
einzeln geprüft) bestätigt alle acht Punkte inhaltlich ohne Lücken — u. a. Gateway/Redis-Pub/Sub mit
Cursor-Reconnect (`apps/api/src/chat/gateway.ts`, `room-hub.ts`), idempotentes Optimistic-UI
(`@@unique(tenantId, chatId, clientMessageId)`), ProjektMitglied-Sync
(`packages/chat/src/project-sync.server.ts`, verdrahtet in projectService/auftragService), Pins max 50
mit DM-Ausschluss (`message-features.server.ts`), Mark-as-Task via EntityLink, begründungspflichtiger
Admin-Audit mit DM-Banner, `notify()` IN_APP mit Deep Link ohne Browser-Push, Modul-Gate an Route und
Gateway sowie FORCE-RLS auf allen neun Chat-Tabellen inklusive Inverse-SQL. Querschnitts-DoD (Blocks
A–F) ebenfalls grün: Layer-Trennung ohne Verstöße, Sidebar/i18n/Permissions/Entitlements/
`TENANT_SCOPED_MODELS` vollständig, `chatMessage` im Search-Index registriert, Smoke-/Hot-Swap-/
Visual-Nachweise vorhanden. Keine Restarbeiten; offen bleiben nur User-Sign-Off (Tracker M110–M114)
und der `design-nachzug`.
### 2026-07-29 — Abhängigkeitsnachzug aus AK-P4a
Der wiederverwendete Chunk-Upload-Client sendet nun den Session-CSRF-Header bei Init, Chunk und
Complete. Der Chat-Anhang-Flow benötigt keine eigene Contract-Änderung; fokussierte Client- und
Resource-Route-Regressionstests sind grün. **AK-P15b bleibt 8/8 DoD = 100 % done.**
@@ -6,7 +6,9 @@
| **Owner** | Akeshan |
| **Phase** | P16 — Kalender, Booking, Forms & Signatur |
| **Cycle/Fenster** | W4 — USP, Härtung & Launch · fällig 2026-07-04 · Gate W4 |
| **Status** | in Arbeit (~83 % DoD, Backend+Routen+Sync+Worker+Write-Pfad fertig; Rest David D-P16/D-BOOK + Staging-DB) |
| **Status** | Done (2026-07-11, PR #75; Interim-UI AD-28; finale Optik = design-nachzug) · Audit 2026-07-17: Reachability-Lücke B.6 gefixt, RLS seit Cutover 14.07. live → 7/7 DoD; offen nur Live-OAuth-Smoke (EXT-15) |
**🎨 design-nachzug: offen** (seit 2026-07-11) — Interim-UI aus `~/ui` steht; finale Subframe-Optik aus `D-P16`/`D-BOOK` ausstehend.
## Abhängigkeiten & Parallelität
- **Blocked by:** `EXT-10` (Google-Cloud-Projekt + OAuth-Consent für Calendar-API), `R-P5` (Apps-Engine — Kalender läuft als `DataConnection`)
@@ -29,8 +31,9 @@ Den **bidirektionalen Kalender-Sync mit Google** (Outlook-Adapter → v2, Interf
- [x] HiveGrid-Termine (Booking/Projekt/Plantafel) gehen **extern**, externe Events kommen **read-only** für Verfügbarkeit
- [x] **Connection pro User**; externe Event-Inhalte nie an andere User leaken (nur „belegt von X bis Y")
- [x] **Last-Write-Wins-Konflikt** mit Klartext-Notification + Konflikt-Log (letzte 50)
- [ ] Kalender-Ansicht mit Quell-Markern (HiveGrid + extern)
- [x] Konnektor `tenantHasModule('calendar')`; RLS auf allen Tenant-Tabellen; OAuth verschlüsselt (AD-8, via Apps-Engine)
- [x] Kalender-Ansicht mit Quell-Markern (HiveGrid + extern) — *Interim-Monats-/Wochen-Grid aus `~/ui` (AD-28); finale Subframe-Optik = design-nachzug*
- [x] Konnektor `tenantHasModule('calendar')`; RLS auf allen Tenant-Tabellen; OAuth verschlüsselt (AD-8, via Apps-Engine) · *RLS ist seit `20260713190000_appwide_rls_cutover` (14.07.) LIVE — der frühere „deferred cutover"-Vermerk ist damit erledigt*
- [x] **Reachability Verbindungsseite (fehlender DoD-Punkt, Audit 2026-07-17):** `/settings/integrations/calendar` ist aus dem Integrations-Katalog erreichbar — die „Kalender"-Karte und die generische `google-calendar`-Detailseite leiten auf die Kalender-Verbindungen um (Aircall-Muster; vorher nur per Direkt-URL/OAuth-Redirect erreichbar, DoD B.6)
## Technische Bausteine
- **Entities** (eigene `prisma/schema/calendar.prisma`): `CalendarConnection` (provider google, oauth_refresh_token **verschlüsselt**, status — **pro User**), `CalendarEvent` (source internal/external_synced, starts/ends_at, is_busy, internal_entity_link polymorph), `CalendarEventMapping` (internal↔external_id), `CalendarSyncCursor` (cursor_token), `CalendarWebhookEvent` (payload). `apps.prisma` nur lesend (DataConnection-Bezug, AD-21).
@@ -42,15 +45,26 @@ Den **bidirektionalen Kalender-Sync mit Google** (Outlook-Adapter → v2, Interf
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 9: Kalender/Booking/Forms/Signatur** (CalendarConnection v1 Google, CalendarEvent/Mapping/SyncCursor/WebhookEvent)
- `REQUIREMENTS.md` → `REQ-kalender-datenmodell`, `REQ-kalender-sync-adapter` (Outlook-Teil → v2)
- `ROADMAP.md` → Phase 16 · `PHASE-SOURCES.md` → Phase 16 (M118-google-adapter, M119-termin-sync, M120-display-modul-verknuepfung; Outlook v2)
- `ROADMAP.md` → Phase 16 · Milestones: (M118-google-adapter, M119-termin-sync, M120-display-modul-verknuepfung; Outlook v2)
- `designer-briefs/P16-kalender-booking-forms-signatur.md` (Gruppe 1 Kalender-Sync; nur Google v1)
- `_bmad-output/specs/M25-calendar-sync.md`
## Dev-Nachzug (nach Davids `D-BOOK`/`D-P16`-Delta)
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [ ] REQUIREMENTS/ROADMAP nachgezogen
- [ ] Plane-Ticket `AK-P16a` aktualisiert
**Interim-UI (Vorschau, Stand 2026-07-11):** Screens aus `~/ui` gebaut —
`apps/web/app/components/screens/calendar/CalendarViewPage.tsx` (Monats-/Wochen-Grid mit
Quell-Marker-Legende, GET-Navigation `?view=&anchor=`),
`CalendarConnectionsPage.tsx` (A6: Connect-CTA, Not-Configured-/Re-Connect-Banner, Status-Tabelle),
`CalendarConnectionDetailPage.tsx` (A6+A2: Kalender-Liste, Konfliktprotokoll-Tabelle, Disconnect
als XS-420-Dialog). Routen unverändert (Loader/Action), injizieren nur VM+csrf. Proof:
`subframe-layout-boundary.test.ts` (Guard, alle 3 Screens registriert), Calendar-Modultests 24 grün,
`tests/e2e/calendar.spec.ts`-Marker (`ui.calendar.list`) erhalten. Visual-Baseline/Hot-Swap: für
diese Bereiche existiert (wie bei den Automations-/Forms-Nachzügen) noch keine Infra — beim
D-P16-Nachzug mit Re-Baseline aufsetzen. Refactor-Nachzug offen: finale Subframe-Optik aus
`D-P16`/`D-BOOK` (Plane-Label `design-nachzug`).
## Umsetzungs-Notiz (2026-06-30, Akeshan) — ~70 % DoD
Branch `feat/AK-P16a`, 6 lokale Commits (`ca0a410` → `4ac8cb07`), nichts gepusht,
@@ -120,3 +134,50 @@ typecheck; `pnpm run verify:i18n`; gezielte Vitest-Suite **40 Tests grün**
Calendar/Booking VMs 8). Zusätzlich wurde ein AK-P16b-VM-Testimport auf
NodeNext-konformes `.js` korrigiert, damit `@hivegrid/view-models` wieder
typecheck-grün ist.
## Umsetzungs-Notiz (2026-07-11, Akeshan) — Interim-UI (AD-28), 6/6 DoD selbst machbar
Branch `akeshan/ak-p16ab-interim-ui` (von `origin/main`), gemeinsamer Interim-UI-PR
mit AK-P16b. Neu: `CalendarViewPage` (bespoke Monats-/Wochen-Grid aus `~/ui`,
Quell-Marker-Legende + farbige Event-Chips, Heute/Prev/Next/Toggle als
GET-Navigation, Loader lädt das Event-Fenster passend zum Grid, Tage werden
Berlin-lokal gebucketed — pure `calendar-grid.ts` in `@hivegrid/view-models`
mit 7 Unit-Tests), `CalendarConnectionsPage` und `CalendarConnectionDetailPage`
ersetzen die Baseline-Routen-JSX; Disconnect läuft als echter Dialog.
**DoD-Stand: 6/6 = 100 % selbst machbar** — DoD 5 (Kalender-Ansicht Quell-Marker)
per Interim-UI erfüllt; finale Subframe-Optik = getrackter design-nachzug
(Tag oben). Weiter env-blockiert (unverändert): Staging-`db push`, RLS-Live-Check,
Live-OAuth (EXT-15); Visual-Baseline/Hot-Swap-Infra für Calendar fehlt repo-weit
und wird beim D-P16-Nachzug mit aufgesetzt.
**Proof:** `@hivegrid/{view-models,web}` typecheck 0 Fehler; `verify:i18n` +
`verify:sidebar-routes` Exit 0; Vitest gezielt grün: view-models 26,
Calendar-Modul 24, `subframe-layout-boundary.test.ts` (3 neue Calendar-Screens
registriert); e2e-Marker `ui.calendar.list` unverändert.
**Nachtrag Demo-Seed (2026-07-11):** Für das Interim-Kalender-Grid liefert der Demo-Seed
jetzt 6 Kalender-Events mit Quell-Vielfalt (3 interne Booking-Spiegelungen, externer
Material-/Privat-Termin, zweitägige ganztägige Messe) — Details/Proof im
AK-P16b-Seed-Nachtrag; `docs/ops/local-demo-seed.md` aktualisiert.
## Umsetzungs-Notiz (2026-07-17, Akeshan) — Stand-Audit + Restarbeiten
Audit-Befund (Code auf `main` pro DoD-Punkt geprüft): DoD 1–6 real erfüllt, aber
eine **Reachability-Lücke** (DoD B.6, oben als nachgetragener DoD-Punkt): die
„Kalender"-Katalog-Karte führte auf die generische `DataConnection`-Detailseite
(zeigt für Kalender immer 0 Verbindungen, Connect-Wizard hätte den OAuth-Flow
umgangen); `/settings/integrations/calendar` war nur per Direkt-URL erreichbar.
**Fix** (Branch `fix/ak-p16-audit-restwork`): Katalog-Karte + Loader/Action der
generischen Detailseite leiten nach Aircall-Muster auf `calendarConnectionsPath`
um; Routing-Kontrakt-Test `integrations.calendar-routing.test.ts` (6 Tests grün).
**Drift korrigiert:** Die RLS ist seit dem appwide Cutover
(`20260713190000_appwide_rls_cutover`, ENABLE+FORCE auf allen 6 Calendar-Tabellen)
live — die als „env-blockiert offen" geführten Staging-RLS-Vermerke sind damit
gegenstandslos; `calendar.prisma`-Header-Kommentar entsprechend nachgezogen.
Offen extern bleibt nur der Live-OAuth-Smoke (EXT-15, Google-App-Verifizierung).
Kleinbefund (kein DoD-Bruch, notiert): der Worker-Write-Pfad mappt Provider-412
hart auf `external_won` statt den pure `resolveConflict`-Resolver zu nutzen —
funktional Last-Write-Wins-konform; Umbau nur als Vorschlag außerhalb Scope.
@@ -6,7 +6,9 @@
| **Owner** | Akeshan |
| **Phase** | P16 — Kalender, Booking, Forms & Signatur |
| **Cycle/Fenster** | W4 — USP, Härtung & Launch · fällig 2026-07-05 · Gate W4 |
| **Status** | in Arbeit (~92 % gewichtet; 5/7 DoD vollständig, 2/7 teilfertig; selbst machbarer Server-Rest erledigt, Rest David D-P16/AK-P16c + Staging-DB-Ausführung) |
| **Status** | Done (2026-07-11, PR #75; Interim-UI AD-28 inkl. /availability + Picker; finale Optik = design-nachzug) · Audit 2026-07-17: Doppelbuchungs-Constraint als Migration nachgeliefert (war nie deployt + defekt), Public-e2e ergänzt, RLS seit Cutover live → 8/8 DoD |
**🎨 design-nachzug: offen** (seit 2026-07-11) — Interim-UI aus `~/ui` steht; finale Subframe-Optik aus `D-P16`/`D-BOOK` ausstehend.
## Abhängigkeiten & Parallelität
- **Blocked by:** `AK-P16a` (Kalender-Sync — Slot-Verfügbarkeit braucht Busy-Slots aus Google)
@@ -28,12 +30,13 @@
## Definition of Done
- [x] Öffentliche **Booking-Seiten** berechnen Slots **timezone-aware** (Regeln, Ausnahmen, Kalender-Sync, Puffer, Vorlauf)
- [~] Nach Buchung: **Lead oder Activity** (Email-Match), **FormSubmission**, **Bestätigungs-Email** (.ics) — **Race-Schutz** beim Submit · *Kontakt-Email-Match → Activity, sonst echtes `InboxLead` + `Appointment.leadId`; bei gesetzter `intakeFormId` echtes `FormSubmission` + `Appointment.formSubmissionId`, sonst `intakeAnswers` Json-Fallback*
- [x] Nach Buchung: **Lead oder Activity** (Email-Match), **FormSubmission**, **Bestätigungs-Email** (.ics) — **Race-Schutz** beim Submit · *Kontakt-Email-Match → Activity, sonst echtes `InboxLead` + `Appointment.leadId`; bei gesetzter `intakeFormId` echtes `FormSubmission` + `Appointment.formSubmissionId`, sonst `intakeAnswers` Json-Fallback; Intake-Form-**Auswahl** im Page-Editor seit 2026-07-11 (Interim-UI) — offen nur noch Staging-DB-Ausführung (Race-Integrationstest, env-blockiert)*
- [x] **iFrame-Embed** + Public-URL mit Copy
- [x] Nur **eine** Zuteilungs-Strategie „Erster der frei ist" (Round-Robin/Provider-Wahl → v2)
- [~] **Storno/Verschiebung/Re-Assign/No-Show** (M129 VOLL) inkl. Auto-Mail bei Cancel · *Service + Route-Action-Contract vollständig; Reschedule/Re-Assign-Picker-UI → David D-P16*
- [x] **Storno/Verschiebung/Re-Assign/No-Show** (M129 VOLL) inkl. Auto-Mail bei Cancel · *Service + Route-Action-Contract vollständig; Reschedule-Slot-Picker + Re-Assign-Provider-Dialog seit 2026-07-11 als Interim-UI (AD-28); finale Optik = design-nachzug*
- [x] Permission-Bundle `bookings.*` (read_own/read_all/write/admin) serverseitig Owner-gefiltert
- [x] Konnektor `tenantHasModule('booking')`; RLS auf allen Tenant-Tabellen *(RLS-SQL als deferred Cutover wie Kalender)*
- [x] Konnektor `tenantHasModule('booking')`; RLS auf allen Tenant-Tabellen *(RLS seit `20260713190000_appwide_rls_cutover` LIVE — „deferred" erledigt)*
- [x] **e2e-Smoke Public-Booking (fehlender DoD-Punkt, Audit 2026-07-17):** `tests/e2e/booking-public.spec.ts` (env-gated via `E2E_PUBLIC_BOOKING_PATH`, Marker `ui.booking.public` + Form/Empty) — `booking.spec.ts` deckte nur `ui.booking.list` (AGENTS.md D.19)
## Technische Bausteine
- **Entities** (eigene `prisma/schema/booking.prisma`): `BookingPage` (slug, duration_minutes, assignment_strategy, is_published, intake_form_id), `BookingPageProvider` (M:N User), `AvailabilityRule`/`AvailabilityException`, `Appointment` (provider_user_id, start/end, status scheduled/held/cancelled/no_show/rescheduled, kontakt_id|lead_id, form_submission_id). `calendar.prisma`/`crm.prisma`/`forms.prisma` nur über Relationen (AD-21).
@@ -45,15 +48,36 @@
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 9** (BookingPage/Provider, AvailabilityRule/Exception, Appointment)
- `REQUIREMENTS.md` → `REQ-booking-datenmodell`, `REQ-booking-slot-kalkulierung`, `REQ-booking-integrationen`
- `ROADMAP.md` → Phase 16 · `PHASE-SOURCES.md` → Phase 16 (M126-time-slot, M127-verfuegbarkeit, M128-bestaetigung, M129-stornierung — M129 explizit VOLL)
- `ROADMAP.md` → Phase 16 · Milestones: (M126-time-slot, M127-verfuegbarkeit, M128-bestaetigung, M129-stornierung — M129 explizit VOLL)
- `designer-briefs/P16-kalender-booking-forms-signatur.md` (Gruppe 2 Booking; eine Zuteilungs-Strategie v1)
- `_bmad-output/specs/M06-booking.md`
## Dev-Nachzug (nach Davids `D-BOOK`/`D-P16`-Delta)
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [ ] REQUIREMENTS/ROADMAP nachgezogen
- [ ] Plane-Ticket `AK-P16b` aktualisiert
**Interim-UI (Vorschau, Stand 2026-07-11):** Screens aus `~/ui` gebaut —
`apps/web/app/components/screens/booking/BookingListPage.tsx` (A2: Tabs
Anstehend/Vergangen/Storniert/Alle + Suche + Status-Badges),
`BookingDetailPage.tsx` (A3: M129-Lifecycle komplett — Cancel-Dialog mit Grund,
**Reschedule-Slot-Picker** (Datum → Loader berechnet Engine-Slots via `?slotsDate=`,
nur eigener Provider) und **Re-Assign-Provider-Dialog** (admin), alles echte S-560-Dialoge
auf die bestehenden Intents), `BookingPagesPage.tsx` (A2: Publish-Badges, absolute
Public-URL mit Copy), `BookingPageEditorPage.tsx` (A6+A4: Provider-Checkboxen,
**Intake-Form-Auswahl** — `BookingPage.intakeFormId` wird jetzt gepflegt, schließt den
DoD-2-Rest „Form-Auswahl"), `AvailabilityPage.tsx` (**neue Route `/availability`**:
Wochen-Regeln mit mehreren Fenstern/Tag, Datums-Ausnahmen, Timezone; atomarer Replace,
own-user-Scope; Sidebar/`UI_NAV_IDS`/`surfaces.json` verdrahtet). Öffentliche Booking-Page
im S04-Look des `PublicFormRenderer` (`tcbook-*`-CSS, bewusst ohne `~/ui` wegen
iFrame-Embed — dokumentierte Ausnahme mit PublicFormRenderer-Präzedenz). Bulk-Cancel/CSV
(nur Brief, nicht DoD) bewusst deferred. Proof: Guard-Tests (`subframe-layout-boundary`,
`booking-auth-boundary` inkl. neuem Availability-Action-Test), Booking-Modultests grün,
e2e-Marker (`ui.booking.list`, `ui.booking.public.*`) erhalten. Visual-Baseline/Hot-Swap-Infra
fehlt repo-weit für diese Bereiche — beim D-P16-Nachzug mit Re-Baseline aufsetzen.
Refactor-Nachzug offen: finale Subframe-Optik aus `D-P16`/`D-BOOK` (Plane-Label `design-nachzug`).
> ℹ️ **Auswirkung aus AK-P16c (2026-07-10, PR #71):** Der gemeinsam genutzte `PublicFormRenderer` wurde im WF-P16-Subframe-Nachzug optisch auf den S04-Soll-Stand gehoben (zentrierte Card, Akzentbalken, neue Erfolgs-/Fehler-/Nicht-verfügbar-Zustände). Verhalten/Props unverändert (nur neuer optionaler `layout`-Prop); Booking-Intake-Formulare rendern automatisch im neuen Look. Beim D-BOOK-Nachzug gegenprüfen.
## Umsetzungs-Notiz (2026-06-30, Akeshan) — ~85 % DoD
Branch `feat/AK-P16b` (von `feat/AK-P16a` abgezweigt, AD-21), **8 Commits** (`fecf6f19f`
@@ -155,3 +179,122 @@ Noch ohne Screens nachgezogen:
Action-Contract sind bereits erledigt.
**Proof lokal:** `pnpm exec vitest run apps/web/app/modules/booking/services/booking-postbooking-boundary.test.ts apps/web/app/modules/booking/services/booking-db-artifacts.test.ts apps/web/app/modules/booking/services/AvailabilityService.server.test.ts apps/web/app/modules/booking/routes/booking-auth-boundary.test.ts` → 11/11 grün; `pnpm typecheck`, `pnpm lint`, `pnpm verify:i18n`, `pnpm test` und `pnpm build` → grün.
## Umsetzungs-Notiz (2026-07-11, Akeshan) — Interim-UI (AD-28), 7/7 DoD selbst machbar
Branch `akeshan/ak-p16ab-interim-ui` (von `origin/main`), gemeinsamer Interim-UI-PR
mit AK-P16a. Alle Booking-Oberflächen auf `~/ui`-Interim-Standard gehoben (Details
im Interim-UI-Vermerk der Dev-Nachzug-Sektion): Buchungsliste mit Tabs, Detail mit
Reschedule-Slot-Picker + Re-Assign-Dialog (schließt den DoD-5-UI-Rest), Pages-Liste,
Page-Editor mit Provider-Checkboxen + Intake-Form-Auswahl (schließt den DoD-2-Rest
„Form-Auswahl"; `intakeFormId` wird jetzt in Create/Update persistiert), neue Route
`/availability` gegen den fertigen AvailabilityService-Contract (Wochen-Regeln,
Ausnahmen, Timezone, atomarer Replace, own-user-Scope) inkl. Reachability-Wiring
(Sidebar, `UI_NAV_IDS.appAvailability`, `surfaces.json`), öffentliche Booking-Page
im S04-Look. Neue VMs (`booking-detail`, `booking-pages`, `availability` inkl.
Payload-Codecs, `bookingListTab`) pure in `@hivegrid/view-models` mit Unit-Tests.
**DoD-Stand: 7/7 selbst machbar erledigt.** DoD 2 und 5 sind jetzt bis auf die
env-blockierte Staging-DB-Ausführung (db push, booking-constraints.sql, RLS-Live,
Race-Integrationstest) vollständig; finale Subframe-Optik = getrackter
design-nachzug (Tag oben). Keine Schema-Änderung auf dem Branch (AD-21, keine
Migration nötig — `intakeFormId` existierte bereits).
**Proof:** `@hivegrid/{view-models,web}` typecheck 0 Fehler; `verify:i18n` +
`verify:sidebar-routes` Exit 0; Vitest gezielt grün: view-models 26 (davon
Booking/Availability 14), Booking-Modul 34 inkl. neuem Availability-Guard-Test,
Sidebar-/uiInventory-Kontrakte 66 gesamt im Lauf; e2e-Marker
(`ui.booking.list`, `ui.booking.public.*`) unverändert. lefthook pre-commit je
Commit grün.
**Nachtrag Demo-Seed (2026-07-11):** `scripts/seed-hivegrid-demo.ts` um Staging-/Demo-Daten
für die Interim-Screens ergänzt: 4 `AvailabilityException`-Rows (Urlaubstag + Custom-Window
für owner/vertrieb, `/availability`-Editor), Booking-Page `Beratung vor Ort` mit
`intakeFormId` → `demo-form-angebotsanfrage` (Editor-Formularauswahl + echter
FormSubmission-Pfad), 2 zusätzliche externe Kalender-Events (Privat-Termin busy +
zweitägige ganztägige Messe) für Quell-Marker/Multi-Day im Kalender-Grid.
Idempotenz verifiziert: 2 Läufe gegen frische pgvector-DB (db push), identische Counts
(BookingPages 2, Appointments 3, CalendarEvents 6, Exceptions 4, Rules 15).
`docs/ops/local-demo-seed.md` nachgezogen.
## Nachtrag (2026-07-11, Akeshan) — Reachability `/bookings/pages` + Staging-Demo-Daten
Zwei Nachbesserungen nach User-Review auf Staging (eigener PR, Branch
`akeshan/booking-reachability-staging-seed`):
1. **`/bookings/pages` erreichbar gemacht (DoD B.6/E.23-Lücke):** Die
Booking-Seiten-Verwaltung hatte weder Sidebar-Eintrag noch Inline-Link und war
nur per URL erreichbar. Jetzt verlinkt die Buchungsliste inline: Header-Button
„Booking-Seiten verwalten" (`ui.booking.list.managePages`) + Aktions-Button im
Empty-State. Permission-gated über `bookings.read_all` (gleiches Gate wie der
Pages-Loader selbst); der Loader liefert `pagesHref` (null ohne Permission).
2. **SeedService um Booking-/Kalender-Demo-Daten erweitert:** Der reichhaltige
lokale Demo-Seed verweigert `NODE_ENV=production` und lief daher nie auf
Staging — die Staging-Demo-Tenants (demo-starter/pro/business-crm, SeedService
mit `SEED_ON_BOOT`) hatten 0 Booking-Daten. `seedDemoTenantBookingData` seedet
jetzt je Demo-Tenant: 2 Booking-Pages (1 published + 1 unpublished, Provider
john.doe+luna.davis), Mo–Fr-AvailabilityRules je Provider, 2 Exceptions
(Urlaubstag + Custom-Window), 4 Appointments über alle Listen-Tabs
(scheduled ×2, held, cancelled inkl. Storno-Feldern) mit lokalem
CalendarEvent-Spiegel plus 1 externem Busy-Event für die Quell-Marker.
Idempotent über deterministische `seed-<tenant>-*`-IDs bzw. Unique-Upserts;
Day-Offsets werden je Lauf neu aufgelöst, „anstehende" Termine bleiben also
anstehend. `isDemoData` gesetzt, wo das Schema es trägt.
## Umsetzungs-Notiz (2026-07-17, Akeshan) — Stand-Audit + Restarbeiten
Audit-Befund (Code auf `main` pro DoD-Punkt geprüft): DoD 1/3/4/5/6/7 real
erfüllt. **Zwei echte Lücken geschlossen** (Branch `fix/ak-p16-audit-restwork`):
1. **DoD 2 Race-Backstop war nie deployt UND nie lauffähig:**
`booking-constraints.sql` lag in keiner Migration (nur manueller `psql -f`-Pfad,
der nie ausgeführt wurde) — und das Artefakt selbst war defekt:
`tstzrange(...)` über `TIMESTAMP(3)`-Spalten wird von Postgres im
Index-Ausdruck abgelehnt (impliziter Cast nur STABLE, Fehler 42P17).
**Fix:** `tsrange` (semantisch identisch, Werte sind UTC) + getrackte,
idempotente Migration `20260717090000_ak_p16b_booking_overlap_constraint`
mit Pre-Flight-Overlap-Check und Klartext-Operator-Hinweis;
`booking-db-artifacts.test.ts` prüft jetzt beide Kopien.
Proof: `verify:migrations-parity` grün (voller Replay gegen leere DB).
2. **e2e Public-Smoke** (nachgetragener DoD-Punkt oben) ergänzt.
**Drift korrigiert:** RLS auf allen 5 Booking-Tabellen ist seit
`20260713190000_appwide_rls_cutover` live; die „Staging-DB-Ausführung
env-blockiert"-Vermerke (db push, booking-constraints, RLS-Live) sind mit der
Migration bzw. dem Cutover erledigt. Offen bleibt nur der Race-Integrationstest
gegen eine echte DB als optionaler Nachweis (Constraint greift jetzt physisch).
## Umsetzungs-Notiz (2026-07-17, Akeshan) — Staging-Incident: Constraint-Migration tenant-scoped nachgezogen
Der erste Rollout der Constraint-Migration brach den Staging-Deploy (P3018,
23P01 „Key conflicts exist"). Zwei Ursachen, beide behoben:
1. **Constraint war tenant-agnostisch:** Die Demo-Tenants teilen sich globale
Provider-User (john.doe/luna.davis), und `seedDemoTenantBookingData` legt in
jedem Demo-Tenant identische Termin-Zeiten an → garantierte Cross-Tenant-
„Überlappungen". Fachlich ist der Constraint tenant-scoped korrekt (die
Slot-Engine ist tenant-scoped; tenant-übergreifend wäre zudem ein
Isolation-Leak: Tenant B erführe über Buchungsfehler Belegtzeiten aus
Tenant A). **Fix:** `"tenantId" WITH =` als erste Constraint-Spalte.
2. **Pre-Flight-Check war RLS-blind:** Der Migrator läuft unter FORCE RLS ohne
Tenant-GUC — der Vorab-SELECT sah 0 Zeilen, während `ADD CONSTRAINT` als
DDL alle Zeilen indexierte. **Fix:** Pre-Flight entfernt; stattdessen fängt
die Migration die `exclusion_violation` und wirft eine Klartext-Meldung mit
Diagnose-Query (als `postgres` auszuführen, da RLS die Zeilen vor dem
Migrator versteckt).
Lokal gegen Postgres 16 verifiziert: Cross-Tenant-Overlaps (Staging-Szenario)
bauen durch; Within-Tenant-Doppelbuchung wird zur Laufzeit abgelehnt (23P01 →
Klartext im Submit-Pfad); Bestandskonflikt beim Anlegen liefert die lesbare
Operator-Meldung. `verify:migrations-parity` (voller Replay) grün. Die
Migration war nirgends erfolgreich angewandt (nur failed auf Staging) und
durfte daher in place korrigiert werden; Staging-Recovery gemäß
`docs/operations/database-rollback.md`: `prisma migrate resolve --rolled-back
20260717090000_ak_p16b_booking_overlap_constraint`, dann Deploy neu anstoßen.
**Proof:** `pnpm typecheck` (Root) 0 Fehler; `verify:i18n`,
`verify:production-seed-artifact` Exit 0; SeedService-Tests um Booking-Mocks +
Count-/Shape-Assertions erweitert (grün; 1 vorbestehender Timeout-Flake
„rejects default admin credentials" tritt identisch auf unverändertem main auf,
environmental). `verify:sidebar-routes`-Failures kamen ausschließlich aus einem
alten `.codex/worktrees`-Checkout, Repo-Dateien grün.
@@ -6,7 +6,9 @@
| **Owner** | Akeshan |
| **Phase** | P16 — Kalender, Booking, Forms & Signatur |
| **Cycle/Fenster** | W4 — USP, Härtung & Launch · fällig 2026-07-06 · Gate W4 |
| **Status** | Dev-Anteil umgesetzt · Design-Delta offen |
| **Status** | Done (2026-07-11) · Subframe-UI vollständig integriert · Audit 2026-07-17: Action-Konfig-Regression aus PR #71 gefixt (Tab „Aktionen"), Forms-e2e ergänzt → 8/8 DoD |
**🎨 subframe-ui: integriert** (Stand 2026-07-10) — der komplette `WF-P16 Form Builder`-Flow ist hinter der bestehenden Loader/Action-Grenze umgesetzt: S00 Verwalten (+E01/E02), S01 Formularart, S02 Fragen-Editor, S02L Lead-Zuweisung (+E05-Warnung), S03 Design, S05 Antworten (+E03/E04), S04 Public (+V01–V03). Rest-Delta (Soll-Elemente ohne Backend: Versionsverlauf, Theme-Logo/-Breite, Bereich/Datei/Pipeline-Lead-Mapping, Optionen-mischen) siehe „Noch offen".
## Abhängigkeiten & Parallelität
- **Blocked by:** `AK-INFRA2` (mCaptcha + Rate-Limit-Infra für öffentliche Endpunkte), `R-P7` (Lead-Inbox — Post-Submit-Action „Lead anlegen")
@@ -33,6 +35,7 @@ Einen Drag-&-Drop-**Form-Builder auf Google-Forms-Niveau**: **12 Feld-Typen**, *
- [x] **Form-Renderer als wiederverwendbare Komponente** (Booking-Intake, HR-Anträge)
- [x] Permission-Bundle `forms.*` (basic/builder/publisher/admin) serverseitig Owner-gefiltert
- [x] Konnektor `tenantHasModule('forms')`; RLS auf allen Tenant-Tabellen
- [x] **e2e-Smoke Forms (fehlender DoD-Punkt, Audit 2026-07-17):** `tests/e2e/forms.spec.ts` (Login → `/forms` → Marker `ui.forms.list`; AGENTS.md D.19 — es gab keinen Forms-e2e)
## Umsetzungs-Notiz
@@ -55,14 +58,49 @@ Einen Drag-&-Drop-**Form-Builder auf Google-Forms-Niveau**: **12 Feld-Typen**, *
**Plane:** Kommentar `2d5037a5-5c59-4a07-9a53-8a597d9b6de4` am 2026-07-01 gesetzt. Ticket bewusst nicht auf Done gesetzt, weil Davids Design-Delta noch offen ist.
**2026-07-09 Subframe-UI-Nachzug (teilweise):** Die Forms-Verwaltung wurde aus dem handgeschriebenen Route-Markup in `apps/web/app/components/screens/forms/FormsAdminPage.tsx` gezogen und an Davids `WF-D-FORM Form Builder` / Subframe-Screen `S00 Formulare verwalten` angelehnt. Loader, Action, Permissions, Owner-Filter, Template-Seeding, Toggle/Delete und Embed-Snippet bleiben unverändert in der Route. Proof: `pnpm --filter @hivegrid/web typecheck` grün. Noch nicht als vollständig erledigt gezählt: kompletter bespoke Builder-Canvas (`S02`/Advanced), Public-Form-States und Submission-Detail-Feinschnitt.
**2026-07-10 UI-Bugfix:** Rekursive Subframe-App-Shell entfernt. `FormsAdminPage` rendert jetzt nur noch app-chrome-freien Content und importiert nicht mehr `~/ui/layouts/DefaultPageLayout`, damit die echte HiveGrid-Sidebar nicht doppelt erscheint. Proof: Regressionstest `apps/web/app/components/screens/subframe-layout-boundary.test.ts`.
**2026-07-10 Subframe-UI-Nachzug (vollständiger D-FORM-Swap):** Alle Screens des Subframe-Flows „(MCP) WF-P16 Form Builder" integriert, Loader/Action/Permissions/Owner-Filter unverändert:
- `/forms` (S00): `FormsAdminPage` auf Soll gehoben — Status-/Art-Filterzeilen, Such-/Sortier-Selects, Zeilen-Dropdown (Veröffentlichen/Duplizieren/Link kopieren/Antworten ansehen/Löschen), E01-/E02-Leerzustände; neue List-Ops `duplicate` (kopiert Definition+Fields+Actions als Draft) und `publish`.
- `/forms/new` (S01): neue Route + `FormNewPage` (Typ-Karten Website/Lead/Umfrage/Intern → Draft + Redirect in den Editor). `FormSubtype`-Enum additiv um `lead`/`internal` erweitert (Merge-Migration `20260710200000_ak_p16c_form_subtype_lead_internal`); Lead-Formulare seeden eine aktive `create_lead`-Action.
- `/forms/:id` (S02/S02L/S03/S05): `FormEditorPage` + `editor/`-Screens ersetzen das alte handgeschriebene UI — Tabs Fragen/Design/Antworten (`?tab=`), debounced Autosave über den unveränderten `op=save`-Contract, Fragen-Karten mit dnd-kit, Conditional-Logic-Editor, Lead-Banner + S02L-Mapping (vorname/nachname/email/telefon/message, E05-Warnbanner), Design-Tab (primaryColor/fontFamily/backgroundColor/borderRadius + Inhalte + Live-Vorschau), Antworten-Tab (Feld-Spalten, Filter, CSV/PDF-Export mit E04-Fehlerbanner, Detail-Drawer mit ActionLog/Re-Run, E03-Leerzustand); neue Ops `duplicate`/`delete`. Altes `FormBuilder`-Modul bleibt vorerst (PreviewTab/Typen wiederverwendet, Tests grün) — Cleanup als Folgeaufgabe.
- Public (S04/V01–V03): `PublicFormRenderer` self-contained restylt (Akzentbalken, Card, Erfolgs-/Fehler-Zustände), neue `PublicFormUnavailable`-Ansicht statt nacktem 404 auf `/f/:tenant/:slug` und im Embed (Status 404 bleibt; Embed-ErrorBoundary bekommt `x-frame-options: ALLOWALL`).
- Querschnitt: alle Texte via i18n (de+en, `settings.forms.{subtype,public,editor,admin.list,admin.new}`), `subframe-layout-boundary.test.ts` um alle neuen Screens erweitert (keine doppelte App-Shell).
**Proof:** `pnpm --filter @hivegrid/web typecheck` grün; `pnpm exec vitest run` über forms.$id.action/defaults/i18n, FormEditorPage, subframe-layout-boundary, formWidget/builder, api.embed.forms.submit(+i18n) = 9 Dateien/30 Tests grün; `scripts/i18n-check.ts` + `verify-hardcoded-strings.mjs` exit 0; `prisma validate` grün.
**2026-07-10 Sichtbarkeits-Fix nach staging-Abnahme (Branch `akeshan/subframe-forms-sichtbarkeit`):** Auf staging waren S00-Tabelle und alle Editor-Tab-Inhalte unsichtbar (im DOM vorhanden, 0px hoch). Root-Cause: das Subframe-Export-Muster „Screen-Root `h-full min-h-[0px] overflow-hidden` + Inhalt in `grow shrink-0 basis-0 overflow-y-auto`" kollabiert innerhalb der `SubframeAppShell`, weil deren `<main>` ein block-level Scroll-Container ohne definite Höhe ist. Fix: beide Container in `FormsAdminPage`/`FormEditorPage` (und `AutomationPages`, gleicher Fehler aus PR #68) auf normalen Dokumentfluss umgestellt; Guard-Regel in `subframe-layout-boundary.test.ts` verbietet das Muster ab jetzt statisch. Dazu: `title` im Loader-Payload + `meta`-Export für `/forms`, `/forms/new`, `/forms/:id` (Breadcrumb zeigte „Dashboard", Tab-Titel nur „HiveGrid"); Demo-Seed um WF-P16-Showcase erweitert (Lead-Formular mit S02L-konformem Mapping + processed/failed/spam-Submissions inkl. ActionLogs, Umfrage mit 3 Antworten, internes Formular als Entwurf für E03; ungültiges Mapping-Target `full_name→name` der Bestandsformulare auf `nachname` normalisiert).
**2026-07-11 Soll/Ist-Verifikation Subframe-MCP:** Abgleich des integrierten Stands gegen den Live-Flow „(MCP) WF-P16 Form Builder" (16 Pages) via Subframe-MCP: kein neues oder geändertes Page-Delta seit dem vollständigen Swap vom 2026-07-10 — einzige Änderung ist `S01B Gefuehrter Fragen Editor _backlog_` (explizit Backlog, out of scope). Die Integrations-Branches `akeshan/subframe-forms-sichtbarkeit` und `akeshan/subframe-forms-vervollstaendigung` sind vollständig in `main` gemerged (je 0 Commits ahead). Kein UI-Handlungsbedarf; offene Punkte unverändert nur die Doku-Nachzüge unten.
**2026-07-17 Stand-Audit + Restarbeiten (Branch `fix/ak-p16-audit-restwork`):** Das Audit fand eine
**unbemerkte Regression aus dem Subframe-Swap (PR #71)**: die FormAction-Konfigurationsoberfläche
(Notiz vom 01.07.: „Admin-Konfiguration für FormAction im Builder ergänzt") war nach dem Swap bis auf
`create_lead` (S02L-Mapping) nicht mehr erreichbar — die übrigen Action-Typen (Kontakt/Projekt/Task,
Team-/Submitter-Mail, Webhook, Automation-Trigger, Auto-Match, Double-Opt-in) liefen im Worker, hatten
aber keine UI. **Fix:** der bestehende `SettingsTab` (alle Action-Typen + Field-Mapping + Delivery-Settings)
ist als vierter Editor-Tab `?tab=aktionen` wieder eingebunden; Persistenz über den unveränderten
`op=save`-Contract (trug `settings.actions` bereits). i18n-Tab-Titel de+en ergänzt, `FormEditorPage.test.tsx`
um den Tab erweitert. Dazu der nachgetragene e2e-Smoke (DoD-Punkt oben) mit neuem `ui.forms.list`-Marker.
Kleinbefund notiert (kein DoD-Bruch): Re-Run arbeitet auf Submission-Ebene (Re-Queue der gesamten
Verarbeitung), `FormActionLog.rerunOfLogId` ist ungenutzt — Per-Action-Re-Run nur als Vorschlag außerhalb Scope.
## Noch offen
**Selbst machbar im Ticket-Scope:**
- Aktuell keine offenen selbst machbaren Dev-Punkte identifiziert. Der funktionale AK-P16c-Umfang aus der DoD ist umgesetzt und lokal verifiziert.
**Design-Nachzug-Rest (Soll-Elemente ohne Backend — bei Bedarf als CR/Folge-Ticket):**
- Versionsverlauf (Header-Dropdown S02/S03/S05) — kein Versions-Backend.
- Theme-Logo-Upload + Formularbreite (S03) — `FormTheme` kennt nur primaryColor/backgroundColor/textColor/fontFamily/borderRadius.
- Lead-Mapping-Zeilen „Bereich"/„Datei/Bild"/„Pipeline" (S02L) — `create_lead` unterstützt nur vorname/nachname/email/telefon/message, `InboxLead` hat keine Pipeline/Tags.
- „Optionen mischen" (S02) — kein Schema-Feld.
- Visual-Regression-Baseline (M016) für die neuen Screens + Hot-Swap-Drill laufen CI-seitig (lokal Windows nicht möglich, siehe Memory) — Re-Baseline beim nächsten CI-Lauf prüfen.
**Extern/blockiert:**
- Davids `D-FORM`/`D-P16` Design-Delta ist noch nicht eingearbeitet. Aktuell ist es eine funktionale Implementierung, aber noch nicht der finale bespoke Subframe-/Design-Stand.
- Nach Davids Delta fehlen die geplanten Doku-Nachzüge: Spec/ENTITY-MODEL, REQUIREMENTS/PHASE-SOURCES und Plane-Ticket final abgleichen.
- Doku-Nachzüge: Spec/ENTITY-MODEL, REQUIREMENTS/ROADMAP und Plane-Ticket final abgleichen.
**Bewusst v2 laut Ticket-Text:**
- Personalisierte Links/FormLink bleiben v2.
@@ -78,11 +116,13 @@ Einen Drag-&-Drop-**Form-Builder auf Google-Forms-Niveau**: **12 Feld-Typen**, *
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 9** (Form, FormField, FormSubmission, FormFile, FormAction; FormLink = v2)
- `REQUIREMENTS.md` → `REQ-form-datenmodell` (FormLink/JS-Snippet → v2), `REQ-form-editor`, `REQ-form-actions`
- `ROADMAP.md` → Phase 16 · `PHASE-SOURCES.md` → Phase 16 (M121-editor, M122-veroeffentlichung gedünnt, M123-submission-eingang, M124-conditional-display, M125-rate-limit-captcha-dsgvo)
- `ROADMAP.md` → Phase 16 · Milestones: (M121-editor, M122-veroeffentlichung gedünnt, M123-submission-eingang, M124-conditional-display, M125-rate-limit-captcha-dsgvo)
- `designer-briefs/P16-kalender-booking-forms-signatur.md` (Gruppe 3 Form-Builder; URL+QR+iFrame v1)
- `_bmad-output/specs/M05-form-builder.md`
## Dev-Nachzug (nach Davids `D-FORM`/`D-P16`-Delta)
- [x] Subframe-UI-Nachzug für Forms-Verwaltung (`S00`, `/forms`) integriert
- [x] App-Shell-Grenze nachgezogen: keine generierte Subframe-Sidebar innerhalb der HiveGrid-App-Shell
- [x] Vollständiger D-FORM-Swap für Builder/Public/Submissions geprüft und nachgezogen (2026-07-10; Rest-Delta ohne Backend siehe „Noch offen")
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [ ] Plane-Ticket `AK-P16c` aktualisiert
- [ ] REQUIREMENTS/ROADMAP nachgezogen
- [x] Plane-Ticket `AK-P16c` mit Subframe-UI-Nachzug aktualisiert
@@ -6,7 +6,9 @@
| **Owner** | Akeshan |
| **Phase** | P16 — Kalender, Booking, Forms & Signatur |
| **Cycle/Fenster** | W4 — USP, Härtung & Launch · fällig 2026-07-07 · Gate W4 |
| **Status** | in Umsetzung |
| **Status** | Done (2026-07-11) · Interim-UI (AD-28) steht, design-nachzug offen · Audit 2026-07-17: PandaDoc-Webhook-Route verdrahtet + Webhook-Activity + Signatur-e2e → 9/9 DoD |
**🎨 design-nachzug: offen** (seit 2026-07-11) — Interim-UI aus `~/ui` steht; finale Subframe-Optik aus `D-P16` ausstehend.
> ⚠️ **Scope-Update (AD-25, 2026-06-21 — Raffael):** Signatur-**Default** ist jetzt der **gehärtete SES-Eigenbau**
> (kein PandaDoc-Zwang), umgesetzt über `defineAdapter` (Adapter `ses-selfhosted`). **PandaDoc bleibt nur als
@@ -31,12 +33,13 @@
## Definition of Done
- [x] **AD-25 umgesetzt:** SES-Eigenbau ist Default (`ses-selfhosted`), PandaDoc bleibt optionaler BYOK-Adapter (`pandadoc-byok`) über die Apps-Engine.
- [x] **Status-Tracking pro Unterzeichner** für SES-Flow (draft/sent/viewed/signed/revoked) plus PandaDoc-HMAC-Webhook-Helfer für BYOK.
- [x] **Status-Tracking pro Unterzeichner** für SES-Flow (draft/sent/viewed/signed/revoked) plus PandaDoc-HMAC-Webhook-Helfer für BYOK. · *Seit 2026-07-17 ist der Webhook auch real erreichbar: öffentliche Route `/webhooks/pandadoc/{tenantId}/{connectionId}` mit timing-safe HMAC-Verify gegen den `webhookSharedKey` der Connection (vorher existierten Helfer + Handler ohne HTTP-Endpoint)*
- [x] **e2e-Smoke Signatur (fehlender DoD-Punkt, Audit 2026-07-17):** `tests/e2e/signature.spec.ts` (Login → Projekt-Detail via `E2E_TENANT_PROJECT_PATH` → Panel-Marker `ui.projects.operations.signature`; AGENTS.md D.19 — es gab keinen Signatur-e2e)
- [x] OTP-Mail via Transactional-Email-Queue, Erinnerung + Widerruf; Signed-PDF- und Completion-Certificate-Artefakte landen in Files.
- [x] **Signatur hängt am `Projekt`-Kern** (`ProjektSignatureDocument`/`ProjektSignatureSigner`) — kein „Deal"-Objekt.
- [x] Permission-Bundle `signature.*` (read/send/revoke/admin) serverseitig Owner-gefiltert.
- [x] Konnektor `tenantHasModule('signature')`; RLS auf allen Tenant-Tabellen.
- [ ] **Blockiert durch D-P16:** finales Subframe-/David-Design für den Signatur-Wizard; aktuell funktionaler Fallback im Projekt-Detail.
- [x] **Signatur-Wizard-UI (AD-28 Interim):** Interim-Wizard + Signatur-Panel aus `~/ui` im Projekt-Detail (Vorbereiten-Wizard mit PDF-Auswahl/Upload, strukturierten Unterzeichnern mit Kontakt-Prefill und Reihenfolge, Prüfen & Senden; Panel mit Status je Unterzeichner, Erinnern, Widerruf mit Bestätigung, Downloads). Finale Subframe-Optik aus `D-P16` = getrackter `design-nachzug`, nicht Done-blockierend.
- [x] **PAdES-/TSA-Produktionspfad:** `@signpdf`-basierte `ETSI.CAdES.detached`-Signatur mit P12-Zertifikat (`SIGNATURE_P12_BASE64` oder `SIGNATURE_P12_PATH`) und optionalem RFC3161-TSA-Request (`SIGNATURE_TSA_URL`). Ohne Zertifikat bleibt Dev-Fallback möglich; mit `SIGNATURE_REQUIRE_PADES=true` schlägt der Abschluss hart fehl, wenn Zertifikatsmaterial fehlt.
## Technische Bausteine
@@ -54,14 +57,59 @@
- Hinweis: `pnpm --filter @toolctrl/config test` fällt lokal auf Windows in `env-access-enforcement.test.ts` wegen bereits bestehender absoluter Baseline-Pfade in anderen Packages; keine AK-P16d-Datei ist in der Unexpected-Liste.
- Fortschritt: 7/8 DoD = 87,5 % done. Selbst machbar offen: 0 Punkte. Extern blockiert: D-P16 finales Signatur-Wizard-Design.
## Umsetzungsnotiz 2026-07-11 — Interim-UI (AD-28)
- Branch: `akeshan/ak-p16cd-signatur-interim-wizard`, abgezweigt von `origin/main`.
- Subframe-MCP geprüft: es existiert **kein** Designer-Flow für die Signatur → Interim-UI nach AD-28, angelehnt an die integrierten Designer-Screens (`screens/forms/`, `screens/automation/`, `ConnectWizardDialog`-Muster).
- Neu: `apps/web/app/components/screens/signature/ProjectSignaturePanel.tsx` (ersetzt den Inline-Fallback in `ProjectSubAreasPanel`; Status-Badges je Dokument/Unterzeichner, Erinnern je Unterzeichner, Senden/Widerruf hinter echtem Bestätigungs-Dialog, Downloads Original/Signed-PDF/Completion-Certificate über die AD-23-Media-Proxy-URLs) und `SignatureWizardDialog.tsx` (echter `~/ui`-Dialog M/720 mit `StepperHorizontal`: Dokument → Unterzeichner → Prüfen & senden; PDF-Auswahl aus Files oder Chunked-Upload; strukturierte Unterzeichner-Zeilen mit Kontakt-Prefill aus Projekt-Kontakten und Sortierung = `signingOrder`; Serialisierung in den bestehenden `parseSignatureSigners`-Zeilen-Kontrakt).
- VM additiv erweitert (`sourcePdfUrl`/`signedPdfUrl`/`completionCertUrl`, `pdfFileOptions`, `kontaktSuggestions`, `createAndSendActionIntent`); Loader lädt PDF-Optionen via `listFilesForBrowser` und Kontakt-Vorschläge; Route-Action um Kompositions-Intent `createAndSendSignatureDocument` ergänzt. Kein Schema-Delta, keine Migration.
- Chunked-Upload-Client aus `files.upload.tsx` nach `apps/web/app/utils/files/uploadFileClient.ts` extrahiert (reiner Refactor); Projekt-Route injiziert `uploadPdf` in den Wizard.
- Public `/sign/:token` auf `PublicSignPage.tsx` aus `~/ui` restylt (Alert/TextInput/TextArea/Checkbox/Button; Formular-Kontrakt der Action unverändert).
- i18n de+en (`signature.wizard.*`, `signature.roles.*`, `signature.panel.*`, `signature.confirm.*`, Download-/Feld-Keys), chirurgisch gespliced.
- Ehrlichkeits-Hinweis: `remindSignatureSigner` vermerkt nur `lastReminderAt` + Event, verschickt keine Mail — UI-Copy sagt das („Erinnern vermerkt den Zeitpunkt …"). Mail-Anbindung = Vorschlag außerhalb Ticket-Scope.
- Proof lokal: `pnpm --filter @hivegrid/web typecheck` + `--filter @hivegrid/view-models typecheck` grün; `pnpm run verify:i18n` Exit 0; `verify:cross-cutting-models` Exit 0; vitest grün: `project-signature.vm.test.ts`, `ProjectSignaturePanel.test.tsx` (5), `SignatureWizardDialog.test.tsx` (5), `subframe-layout-boundary.test.ts` (Allowlist um die 3 Signature-Screens erweitert), `padesSeal.server.test.ts`, `FileUploadPage.test.tsx`, projects-Screens-Suiten. `verify:sidebar-routes`-Fails nur in `.codex/worktrees/*`-Kopien (bekannte lokale Verschmutzung); Hot-Swap-Drill + Visual-Baseline laufen CI-seitig (Windows-Limitation).
- Fortschritt: **8/8 DoD = 100 %** (Wizard-DoD via AD-28-Interim erfüllt; finale D-P16-Optik als `design-nachzug` getrackt). Done-Status erst nach Freigabe.
## Umsetzungsnotiz 2026-07-17 — Stand-Audit + Restarbeiten
- Audit-Befund (Code auf `main` pro DoD-Punkt geprüft): DoD 1–8 real erfüllt, aber der
**PandaDoc-BYOK-Webhook war nicht verdrahtet**: `verifyPandaDocWebhookSignature` +
`handlePandaDocWebhook` existierten, ohne dass irgendeine Route sie aufrief — der
BYOK-Status-Pfad war real unerreichbar (Plane-DoD „Webhook-Verarbeitung").
- Fix (Branch `fix/ak-p16-audit-restwork`): öffentliche Resource-Route
`apps/web/app/routes/webhooks.pandadoc.$tenantId.$connectionId.tsx` — rawBody-HMAC
über `runWithConnectionCredentials` (expectedAppId `pandadoc-byok`), Quiet-200 für
alles Unverifizierbare (Calendar-Webhook-Muster, kein Existenz-Leak). Zusätzlich
schreibt der `document.completed`-Zweig jetzt eine System-Activity
(`logSignatureActivity`, actorUserId null → system; DoD C.14 — vorher nur
SignatureEvent). Route-Test mit 4 Fällen (verifiziert/fehlende+falsche
Signatur/unbekannte Connection/405), Signatur-Suite 14 Tests grün, Typecheck
web+integrations grün. e2e-Smoke ergänzt (DoD-Punkt oben).
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 9** (SignatureProviderConnection, ProjektSignatureDocument/Signer — am Projekt-Kern, AD-20)
- `REQUIREMENTS.md` → `REQ-signatur-datenmodell` (⚠ Bezeichner „Deal" pre-pivot — gilt `Projekt`), `REQ-signatur-provider`
- `ROADMAP.md` → Phase 16 · `PHASE-SOURCES.md` → Phase 16 (M130-erstellung, M131-self-hosted-e-signatur, M132-status-tracking)
- `ROADMAP.md` → Phase 16 · Milestones: (M130-erstellung, M131-self-hosted-e-signatur, M132-status-tracking)
- `designer-briefs/P16-kalender-booking-forms-signatur.md` (Gruppe 4 Signatur; SES-Default/PandaDoc-BYOK, Pivot-Hinweis Projekt-Kern)
- `_bmad-output/specs/M07-angebot-signatur.md` (⚠ teils pre-pivot — ENTITY-MODEL hat Vorrang)
## Dev-Nachzug (nach Davids `D-BOOK`/`D-P16`-Delta)
**Interim-UI (Vorschau, Stand 2026-07-11):** Screens aus `~/ui` gebaut —
`apps/web/app/components/screens/signature/{ProjectSignaturePanel,SignatureWizardDialog,PublicSignPage}.tsx`
(VM als Prop, Route-Intents als Action-Callbacks). Proof: Screen-Tests
`ProjectSignaturePanel.test.tsx` + `SignatureWizardDialog.test.tsx`, Boundary-Guard
`subframe-layout-boundary.test.ts` grün; Hot-Swap-Drill + Visual-Baseline CI-seitig (als interim markiert).
Refactor-Nachzug offen: finale Subframe-Optik aus `D-P16` (Plane-Label `design-nachzug`).
Soll-Elemente ohne Backend (bewusst nicht gebaut, kein Fake-Toggle): sequenziell/parallel-Enforcement im
Versand, Signaturmodus-Auswahl (Fern-Link vs. Touch — ein Versandpfad, Touch läuft über dieselbe
`/sign`-Seite), `linkedKontaktId`-Persistenz (Prefill nur UI-seitig), Reminder-**Mail**-Versand (nur
Vermerk + Event), Expiry-Verwaltung (read-only).
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [ ] Plane-Ticket `AK-P16d` aktualisiert
- [ ] REQUIREMENTS/ROADMAP nachgezogen
- [ ] Plane-Ticket `AK-P16d` aktualisiert (Kommentar + Label `design-nachzug` nach Freigabe)
## Abhängigkeitsnachzug 2026-07-29 — AK-P4a-Upload-CSRF
Der vom Signatur-Wizard wiederverwendete Chunk-Upload-Client sendet nun für Init, Chunk und Complete
den Session-CSRF-Header. Der bestehende `uploadPdf`-Callback bleibt unverändert; fokussierte Client-
und Resource-Route-Regressionstests sowie der Web-Typecheck sind grün.
**AK-P16d bleibt 8/8 DoD = 100 % done.**
@@ -16,6 +16,10 @@
- **Läuft parallel zu:** Raffaels Kern-Kette (P6/P7). **HR hängt nur an P1/P2** (User/RLS/Verschlüsselungs-Fundament) — KEINE Abhängigkeit von R-P5/R-P6, daher früh in W2 baubar. Eigene `prisma/schema/hr.prisma` (AD-21); `core.prisma` nur für User-Relation berührt.
- **Konflikt-Risiko:** keines auf Schema-Ebene — disjunkte HR-Domäne.
**UX-Nachzug (2026-07-25):** `R-UX3` übernimmt die rollenbasierte Personal-IA; `R-UX4` löst den
Passwort-Safe als eigenständigen Bereich heraus. Datenmodell, Verschlüsselung und historische
AK-P17a-Umsetzung bleiben unverändert und werden von beiden Nachzügen weiterverwendet.
## Was wir bauen
Den **verschlüsselten HR-Kern** (Quiply-Ablösung): **MA-Stammdaten** (HrEmployeeProfile, Standorte), **Personaldokumente** und den **verschlüsselten Team-Passwort-Safe**. Sensible Daten liegen **AES-256-GCM** mit KMS-backed Envelope-Encryption (AD-8) vor; sensible Tabellen haben **zusätzlich** zum RLS einen App-Permission-Layer — Werte werden **nie automatisch angezeigt** (Reveal on-demand + Audit-Eintrag). Strikte Trennung **MA-Sicht** (eigener Bereich, eigene Daten) vs. **HR-Admin-Sicht** (`/admin/hr/...`). Passwort-Safe: Werte nie in der Liste, Reveal/Copy entschlüsselt on-demand mit Permission-Check, Copy mit 30s-Auto-Clear, DSGVO-Export.
@@ -34,7 +38,14 @@ Den **verschlüsselten HR-Kern** (Quiply-Ablösung): **MA-Stammdaten** (HrEmploy
- [x] **MA-Bereich vs. HR-Admin-Bereich strikt getrennt**; sensible Tabellen zusätzlich App-Permission-gegated
- [x] **Verschlüsselter Passwort-Safe mit Audit-Trail**: Reveal/Copy entschlüsselt on-demand + Permission-Check + Audit-Eintrag; Werte nie in Liste; Copy mit 30s-Auto-Clear; DSGVO-Export — *Backend komplett: Ver-/Entschlüsselung jetzt scharf (R-P5-Envelope); Audit/Permission/Never-List/Export gebaut. 30s-Clear = UI (David).*
- [x] MA-Verzeichnis + Standorte (Admin-CRUD) + eigene Dokumente (Upload + read-only Büro-Uploads) — *Backend + funktionale Routen; finale Optik wartet auf Davids D-HR-Delta.*
- [x] Konnektor `tenantHasModule('hr')`; RLS auf allen Tenant-Tabellen; sensible Felder verschlüsselt — *Konnektor (Feature/Blueprint/Plan) + RLS-SQL (deferred-Aktivierung wie P4b) + sensible Felder verschlüsselt (R-P5-Envelope) stehen.*
- [x] Konnektor `tenantHasModule('hr')`; RLS auf allen Tenant-Tabellen; sensible Felder verschlüsselt — *Konnektor (Feature/Blueprint/Plan) + RLS-SQL (deferred-Aktivierung wie P4b) + sensible Felder verschlüsselt (R-P5-Envelope) stehen. Seit Cutover `20260713190000_appwide_rls_cutover` (14.07.) ist RLS auf allen HR-Tabellen LIVE; HR-Tabellen sind im generierten Policy-Contract.*
**Nachgetragene DoD-Punkte (Stand-Audit 2026-07-19 — AGENTS.md-Pflicht-DoD, fehlten in der Liste):**
- [x] **VM-Unit-Tests (DoD 18):** alle HR-VM-Builder mit Fixture-Tests (Commit `7c3867039`; vorher nur 3/14 VMs getestet)
- [x] **Smoke-Test (DoD 19):** `tests/e2e/hr-core-smoke.spec.ts` — Login → Hub → Directory → Passwort-Safe (Never-List-Assertion) (Commit `f309ecbce`)
- [x] **Hot-Swap-Drill (DoD 20):** HR-Fixture-Pages in `packages/ui-mock` + `scripts/verify-ui-hot-swap.ts`, Drill grün (Commit `b216848c4`)
- [x] **Registry-Nachzug:** `UI_NAV_IDS.appHr` + Sidebar auf Konstante + HR-Surface in `docs/ui-inventory/surfaces.json` (Commit `bb230e6b6`)
- [ ] **Visual-Regression (DoD 21):** bleibt deferred (kein Component-Screenshot-Harness, R-P5-Präzedenz) — Baseline wird beim `design-nachzug` gegen die finale D-HR-Optik gezogen · `blockiert`
## Technische Bausteine
- **Entities** (eigene `prisma/schema/hr.prisma`): `HrEmployeeProfile` (user_id 1:1, personal_number, hire_date, position, team, location_id, manager_user_id, emergency_contact_*), `HrLocation` (name, address_*, geo, image_file_id), `HrEmployeeDocument` (employee_user_id, document_kind, file_id, visibility), `HrResource`/`HrQuickLink`, `EmployeePasswordSafeVault` (+ `Entry`/`Access` — username/password/notes **AES-256-GCM**, permission_level read/write/admin). `core.prisma` nur für User-Relation (AD-21).
@@ -46,9 +57,8 @@ Den **verschlüsselten HR-Kern** (Quiply-Ablösung): **MA-Stammdaten** (HrEmploy
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 10: HR-Hub** (HrEmployeeProfile, HrLocation, HrEmployeeDocument, HrResource/QuickLink, EmployeePasswordSafeVault — viel Verschlüsselung)
- `REQUIREMENTS.md` → `REQ-hr-datenmodell`, `REQ-hr-passwort-safe`
- `ROADMAP.md` → Phase 17 · `PHASE-SOURCES.md` → Phase 17 (M133-stammdaten, M134-dokumente; M138 Drittanbieter-Onboarding → v2)
- `ROADMAP.md` → Phase 17 · Milestones: (M133-stammdaten, M134-dokumente; M138 Drittanbieter-Onboarding → v2)
- `designer-briefs/P17-hr-hub.md` (MA- vs. HR-Admin-Trennung, Passwort-Safe-Reveal, sensible Daten)
- `_bmad-output/specs/M14-hr-hub.md`
## Umsetzungs-Notiz
@@ -126,8 +136,20 @@ Refactor-Nachzug offen: finale Subframe-Optik aus `D-HR` (Plane-Label `design-na
Visual-Regression bleibt **deferred** (kein Screenshot-Harness im Repo, R-P5-Präzedenz). Demo-Seed (`is_demo_data`)
für Profile/Standorte/Vault als Folge-Task.
**Stand-Audit + Restwork 2026-07-19 (Akeshan) — Drift korrigiert, Test-/Registry-DoD nachgezogen. 8/9 DoD (nur Visual-Regression deferred).**
Befund des Drei-Quellen-Audits (Doc vs. Plane vs. Code):
- **Hash-Korrektur:** Die Interim-UI-Commits aus der Notiz vom 08.07. (`e0f8affd2`/`f840fcf24`) existieren nicht mehr — sie gingen umgeschrieben via **PR #54** als `553065a3c` (P17a-Screens) / `96e84d6bc` (P17b-Screens) / `270f0df30` (Doc-Tag + Screen-Tests) auf `main`. Alle „Branch lokal, nicht gepusht"-Vermerke sind überholt.
- **PR #55** (nicht in der Doc vermerkt gewesen): Self-Service-Dokumenten-Upload + Notfallkontakt-Set-UI + **Demo-Seed `scripts/ops/seed-hr-demo.mts`** (idempotent, nur Demo-Tenants) sind seit 15.07. auf `main` — der „Demo-Seed als Folge-Task"-Punkt ist damit erledigt.
- **RLS:** Cutover 14.07. deckt alle HR-Tabellen ab (`20260713190000_appwide_rls_cutover`); Services binden `withTenantRLS`, der HR-Worker-Cron nutzt `notifyWithTenantRlsContext` — die R-P1b-notify-Regression trifft HR nicht.
- **Restwork umgesetzt** (Branch `fix/ak-p17-audit-restwork`): Registry-Nachzug `bb230e6b6` · VM-Tests `7c3867039` · ui-mock/Hot-Swap `b216848c4` · e2e-Smoke `f309ecbce`. Verifiziert: web/view-models/db/worker-typecheck 0 Fehler, `verify:i18n`/`verify:sidebar-routes`/`verify:cross-cutting-models` Exit 0, `pnpm run test:hot-swap` grün, view-models-Suite 567 Tests grün.
- **Kein Schema-Change** → keine neue Migration nötig (AD-21).
- Subframe-Projekt geprüft (MCP, 2026-07-19): weiterhin **keine** D-HR-Pages — `design-nachzug` bleibt korrekt offen, Interim-UI bleibt der gültige Stand.
**Sichtbar unter:** lokal `pnpm dev:local` → `http://app.localhost:3000/<tenant>/hr` (Hub), `/hr/directory`, `/hr/password-safe`, Screens in `apps/web/app/components/screens/hr/*`.
## Dev-Nachzug (nach Davids `D-HR`-Delta)
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [ ] REQUIREMENTS/ROADMAP nachgezogen
- [ ] Plane-Ticket `AK-P17a` aktualisiert
- [ ] Finale `D-HR`-Optik in `<XPage>`-Internals getauscht (VM/Loader/Route unverändert), Visual-Baseline gezogen, `design-nachzug`-Tag auf erledigt
@@ -16,6 +16,10 @@
- **Läuft parallel zu:** Raffaels Kern-Kette. **HR hängt nur an P1/P2**; nutzt den Form-Renderer (M05) — der kommt erst in P16 (AK-P16c), liegt aber zeitlich **nach** P17. **Pragma:** Urlaub/Krank/Requests werden als M05-Form-Templates modelliert; bis der Renderer aus P16 steht, dienen schlanke HR-eigene Formulare als Übergang (Nachzug-Punkt). Eigene `prisma/schema/hr.prisma` (gleicher Namespace, additiv — AD-21).
- **Konflikt-Risiko:** keines auf Schema-Ebene; Calendar-Relation (M25) über `calendar_event_id` (P16) — read-only.
**UX-Nachzug (2026-07-25):** `R-UX3` übernimmt den freigegebenen Personal-Hub mit
**Für mich / Mein Team / Verwaltung**. AK-P17b bleibt das Workflow-Fundament; M05-, P9- und
Permission-Verträge dürfen durch den Nachzug nicht gebrochen werden.
## Was wir bauen
Die **HR-Workflows**: einen **mehrstufigen Urlaubs-Approval-Workflow** (submitted/approved/rejected/withdrawn + Rückfrage) mit **Abwesenheits-Kalender** und **Plantafel-Konflikt-Hinweisen**, **Krankmeldung** (selbst oder durch Büro im Auftrag) mit **verschlüsseltem AU-Upload**, **Announcements** (Audience-Targeting, Acknowledgement-Pflicht + Read-Receipt, Reaktionen, Kommentare), **Lohnabrechnungs-Bulk-Upload** mit Dateiname-Auto-Match + Read-Tracking, **Upload-Erinnerungen** (Cadence + Eskalation), generische **Requests** via Templates, **Surveys** (anonym möglich, mit Auswertung) und den **Mitarbeiter-Self-Service** (Web/PWA; Web-Push als Kanal → v2).
@@ -34,15 +38,15 @@ Die **HR-Workflows**: einen **mehrstufigen Urlaubs-Approval-Workflow** (submitte
> Legende: `[x]` = im **jetzt-machbaren** Scope fertig + verifiziert · `(extern: …)` =
> Rest hängt an einem blockierenden Folge-Ticket. Details + %-Stand: Umsetzungs-Notiz unten.
- [x] **Mehrstufiger Urlaubs-Approval-Workflow** (submitted/approved/rejected/withdrawn + Rückfrage) → **Plantafel-Konflikt-Feed** (R-P9b via `listApprovedAbsencesForRange`). *(extern: CalendarEvent-Write → P16/M25)*
- [x] **Mehrstufiger Urlaubs-Approval-Workflow** (submitted/approved/rejected/withdrawn + Rückfrage) → **Plantafel-Konflikt-Feed** (R-P9b via `listApprovedAbsencesForRange`). *CalendarEvent-Write seit Audit-Restwork 2026-07-19 umgesetzt (P16/AK-P16a ist da): Approve erzeugt internes All-Day-Event (`hivegrid_internal`, busy, `internalEntityLink: hr_vacation_request`) und setzt `calendarEventId` — Commit `7a64dd477`, live im Browser bewiesen (Kalender September zeigt „Urlaub").*
- [x] **Krankmeldung** (selbst/durch Büro) + **AU-Upload verschlüsselt** (Crypto-Seam, audited Reveal)
- [x] **Announcements** (Audience, Acknowledgement-Pflicht + Read-Receipt, Reaktionen, Kommentare)
- [x] **Lohnabrechnungs-Bulk-Upload** mit Dateiname-Auto-Match (Personalnummer/Name), Match-Vorschau mit Konfidenz, Read-Tracking, Audit pro Read
- [x] **Upload-Erinnerungen** (Cadence once/yearly/every_n_months/on_expiry, Eskalation an Manager via Worker-Cron) + **Requests** via Templates
- [x] **Surveys** (anonym möglich, `submitterHash`) mit Auswertung (gegated)
- [x] **Mitarbeiter-Self-Service** (Web/PWA) — alle Bereiche reachable. *(extern: M05-Form-Submissions → AK-P16c, bis dahin Übergangs-Formulare; Web-Push → v2/AD-17)*
- [x] Konnektor `tenantHasModule('hr')`; App-Permission-Gates; sensible Felder verschlüsselt; RLS-Policies geschrieben. *(extern: RLS-Live-Cutover → R-P2b, wie P17a)*
- [ ] **Tests/UI extern blockiert:** finale Subframe-UI + Adapter + Smoke-Tests (`e2e/smoke/hr-*`) + Visual-Regression (M016) + Hot-Swap (M017) → **Davids `D-HR`-Delta** (noch leer)
- [x] **Mitarbeiter-Self-Service** (Web/PWA) — alle Bereiche reachable. *M05-Form-Reuse seit Audit-Restwork 2026-07-19 verdrahtet (AK-P16c ist Done): Request-Templates können publizierte `hr_request`-Formulare verlinken, `submitRequest` persistiert dann eine echte `FormSubmission` und setzt `formSubmissionId` (Commit `8247d399c`). Urlaub/Krank tragen laut ENTITY-MODEL bewusst kein `form_submission_id` und bleiben beim schlanken Formular. Web-Push → v2/AD-17.*
- [x] Konnektor `tenantHasModule('hr')`; App-Permission-Gates; sensible Felder verschlüsselt; RLS-Policies geschrieben. *RLS ist seit Cutover `20260713190000_appwide_rls_cutover` (14.07.) auf allen HR-Tabellen LIVE; der HR-Worker-Cron nutzt `notifyWithTenantRlsContext` (R-P1b-Regression trifft HR nicht).*
- [x] **Tests/UI:** Interim-UI aus `~/ui` (PR #54) + Smoke-Test `tests/e2e/hr-workflows-smoke.spec.ts` (Commit `f309ecbce`) + Hot-Swap-Drill/ui-mock (Commit `b216848c4`) + Screen-/VM-Unit-Tests (Commit `7c3867039`). *Nur Visual-Regression (M016) bleibt deferred (kein Screenshot-Harness, R-P5-Präzedenz) — Baseline beim `design-nachzug` gegen die finale D-HR-Optik · `blockiert`. Die finale Subframe-Optik selbst = getrackter `design-nachzug`, nicht Done-blockierend (AD-28).*
## Technische Bausteine
- **Entities** (eigene `prisma/schema/hr.prisma`, additiv): `EmployeeVacationRequest` (start/end_date, request_kind, status, assigned_approver, calendar_event_id), `EmployeeSickLeaveReport` (start/return_date, certificate_file_id, status — **[verschlüsselt]** AU-Schein), `HrAnnouncement` (+ Read/Reaction/Comment), `EmployeePayslip` (period_year/month, file_id, is_read), `EmployeeUploadReminder` (+ Dispatch), `HrRequest` (+ Template — request_kind, form_submission_id, status, assigned_approver), `HrSurvey` (+ Item/Submission — is_anonymous, submitter_hash). `calendar.prisma`/`forms.prisma` über Relationen (AD-21).
@@ -54,13 +58,12 @@ Die **HR-Workflows**: einen **mehrstufigen Urlaubs-Approval-Workflow** (submitte
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 10: HR-Hub** (EmployeeVacationRequest, EmployeeSickLeaveReport, HrAnnouncement, EmployeePayslip, EmployeeUploadReminder, HrRequest, HrSurvey)
- `REQUIREMENTS.md` → `REQ-hr-urlaub-krank`
- `ROADMAP.md` → Phase 17 · `PHASE-SOURCES.md` → Phase 17 (M135-urlaub, M136-krankmeldungen, M137-kommunikation, M139-berichte-lohn-export, M140-selbstbedienung; Surveys bleiben v1, M140 ohne Push)
- `ROADMAP.md` → Phase 17 · Milestones: (M135-urlaub, M136-krankmeldungen, M137-kommunikation, M139-berichte-lohn-export, M140-selbstbedienung; Surveys bleiben v1, M140 ohne Push)
- `designer-briefs/P17-hr-hub.md` (Urlaub/Krank, Lohn-Bulk-Match, Surveys, M05-Renderer wiederverwenden)
- `_bmad-output/specs/M14-hr-hub.md`
## Dev-Nachzug (nach Davids `D-HR`-Delta)
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [ ] REQUIREMENTS/ROADMAP nachgezogen
- [ ] Plane-Ticket `AK-P17b` aktualisiert
## Umsetzungs-Notiz
@@ -179,3 +182,32 @@ Damit ist die finale Subframe-Optik (DoD #43) **kein Done-Blocker** mehr, sonder
(Plane-Label `design-nachzug`). Noch selbst machbar: Screen-Unit-Tests, Smoke `e2e/smoke/hr-*`, Hot-Swap-Adapter;
Visual-Regression bleibt deferred (kein Screenshot-Harness). Extern blockiert bleibt nur: CalendarEvent-Write
(P16), M05-Renderer (AK-P16c), RLS-Live (R-P2b), Web-Push (v2).
### 2026-07-19 — Stand-Audit + Restwork: alle vormals externen Blocker (außer D-HR) gefallen und abgearbeitet. 9/9 DoD (nur Visual-Baseline deferred)
**Audit-Befund (Doc vs. Plane vs. Code):** Die Interim-UI-Commits aus der 08.07.-Notiz (`f840fcf24`) existieren
nicht mehr — sie gingen umgeschrieben via **PR #54** als `96e84d6bc`/`270f0df30` auf `main`. Drei als „extern
blockiert" geführte Punkte waren inzwischen frei: **R-P2b/RLS** (Cutover 14.07. deckt alle HR-Tabellen),
**P16-Kalender** (AK-P16a gemergt, `calendar.prisma` da) und **AK-P16c/M05** (Form-Builder seit 11.07. Done).
**Restwork umgesetzt** (Branch `fix/ak-p17-audit-restwork`):
- **CalendarEvent-Sync (DoD 1):** `approveRequest` erzeugt im selben RLS-Kontext ein internes All-Day-Event
(Titel = i18n-aufgelöste Kind-Bezeichnung aus der Route, Booking-Präzedenz) und setzt `calendarEventId`;
Approve ist im Statemachine terminal, daher kein Cleanup-Pfad nötig. Commit `7a64dd477` + Service-Tests.
- **M05-Form-Reuse (DoD 7):** Template-Editor mit Linked-Form-Auswahl (publizierte `hr_request`-Formulare),
`submitRequest` schreibt `FormSubmission` (`linkedEntityType: hr_request`) + `formSubmissionId`. Fallback
bleibt das Übergangs-Formular, Submission bricht nie an einem fehlenden Formular. Commit `8247d399c` + Tests.
- **Tests/Registry (DoD 9 + AGENTS.md-Pflicht):** e2e-Smoke `hr-workflows-smoke.spec.ts` (`f309ecbce`),
ui-mock-Fixtures + Hot-Swap-Drill (`b216848c4`), VM-Unit-Tests für alle 8 ungetesteten HR-VMs (`7c3867039`),
Registry-Nachzug `UI_NAV_IDS.appHr` + surfaces.json (`bb230e6b6`).
**Proof:** typecheck web/db/worker/view-models 0 Fehler · `verify:i18n`/`verify:sidebar-routes`/
`verify:cross-cutting-models` Exit 0 · `pnpm run test:hot-swap` grün · view-models-Suite 567 Tests grün ·
**Live-Beweis im Browser** (lokal, `pnpm dev:local`): Antrag gestellt → in Genehmigungen genehmigt →
DB zeigt `status=approved` + verlinktes `CalendarEvent` (hivegrid_internal, „Urlaub", all-day, busy) →
Kalender-Screen rendert „Urlaub" 01.–04.09. Kein Schema-Change → keine neue Migration (AD-21).
**Sichtbar unter:** `http://app.localhost:3000/<tenant>/hr/leave` (Workflow), `/hr/requests` +
`/hr/admin/request-templates` (M05-Verlinkung), `/calendar` (Absence-Event); Screens in
`apps/web/app/components/screens/hr/*`. Subframe: weiterhin keine D-HR-Pages (MCP-Check 19.07.) —
`design-nachzug` bleibt korrekt offen.
@@ -11,7 +11,9 @@
| **Owner** | Akeshan |
| **Phase** | P19 — Plattform-Admin |
| **Cycle/Fenster** | W2 — Plattform & CRM (Demo 1) · fällig 2026-06-24 · Gate W2 |
| **Status** | geplant |
| **Status** | in Arbeit |
**🎨 design-nachzug: offen** (seit 2026-07-12) — Interim-UI aus `~/ui` steht für Billing, Jobs, Health und Support; finale Subframe-Optik aus `D-ADMIN` ausstehend.
## Abhängigkeiten & Parallelität
- **Blocked by:** `R-P2b` (RLS + RBAC + User-Lifecycle — Admin nutzt Boilerplate-User-Modell als Extension), `AK-P3` (Querschnitt: Audit-Hash-Kette für AdminAuditLog)
@@ -19,6 +21,12 @@
- **Läuft parallel zu:** Raffaels `R-P6` (CRM-Kern). **Maximal isoliert** — Admin-Welt vs. CRM-Domäne, eigener Host `admin.hivegrid.de`, **kein Schema-Konflikt**. Eigene `prisma/schema/admin.prisma` (AD-21); **getrennte Welt, KEIN `tenant_id`** auf den Admin-Tabellen.
- **Konflikt-Risiko:** keines auf Schema-Ebene; berührt `core.prisma` nur für User-Extension (admin-mfa-gate).
> **R-LEADS-Nachzug 2026-07-16:** `R-LEADS` konsumiert ausschließlich die bereits
> grünen Verträge Host-Routing/Admin-Shell, Admin-Auth und
> `recordAdminAction()`/`AuditEvent`. Die in AK-P19 noch offenen Billing-, Support-
> und Queue-DoD blockieren M040a nicht. R-LEADS besitzt sein eigenes
> `adminLeads.prisma` und erweitert den AK-P19-Scope nicht rückwirkend.
## Was wir bauen
Die **getrennte Plattform-Admin-Welt** auf `admin.hivegrid.de` (Host-Routing, **NICHT** `/admin`-Pfad): eigene Admin-Shell (getrennte Sidebar/Topbar), **Cookie-Domain-Trennung** zu app.hivegrid.de, **TOTP-Pflicht + MFA-Step-up**. Admin-User haben **keinen Tenant-Workspace** und erscheinen in keiner Mitgliederliste (Boilerplate-Default-Provisionierung abschalten). Funktionen: **Tenant-Verwaltung** (Stammdaten, Status-Wechsel mit Reason-Pflicht, Notizen, Impersonate mit Begründung max. 30 Min + Banner), **Abo-/Entitlement-Zusammenstellung** je Tenant (Feature-Konnektoren togglen, Plan/Seats/Billing-State nach `BILL-*`), User-Verwaltung (2FA-Reset/Session-Revoke), **Feature-Flag-Verwaltung** (UI zur Engine aus P1), **Queue-/Health-Monitoring** (BullMQ Retry/Pause/Resume), **Support-Inbox** (speist sich aus P21-Feedback-Widget) und der **`AdminAuditLog`** (cross-tenant, tenant_id=null). **v1-Cut:** getrennte AdminUser-Identität/AdminRBAC (M038/M039) → v2; Plattform-Lead-Pipeline → v2; Flag-Massen-Statistik → v2; Churn/ARPU → v2.
@@ -40,10 +48,10 @@ Die **getrennte Plattform-Admin-Welt** auf `admin.hivegrid.de` (Host-Routing, **
## Definition of Done
- [x] **Host-Routing `admin.hivegrid.de`** (NICHT `/admin`-Pfad!) + **Cookie-Domain-Trennung** App↔Admin
- [x] **TOTP-Pflicht** hart erzwungen; Admin **ohne Tenant-Workspace** (Default-Provisionierung abgeschaltet, in keiner Mitgliederliste) — Authentik-SSO + JIT legt nur User+AdminUser an (kein Tenant), MFA via Authentik+Step-up
- [ ] **Tenant-Verwaltung** + **Abo-/Entitlement-Zusammenstellung** (Konnektoren togglen + Plan/Seats/Billing-State nach `BILL-*`) + Trial-Verlängerung + Notizen — *Backend fertig: Abo-Baukasten-Konnektoren + AdminTenantNote. Offen: Trial-Verlängerung, manuelle Tenant-Anlage, Billing-Recut-Adminbasis aus `BILL-06`, finale UI (David)*
- [ ] **Impersonate** (temporäre Tenant-User-Session max. 30 Min) mit Klartext-Banner im Tenant + Reason-Pflicht — *Cap 30 Min + Banner + MFA-Gate fertig. Offen: Operator-Reason-Modal (David)*
- [x] **Tenant-Verwaltung** + **Abo-/Entitlement-Zusammenstellung** (Konnektoren togglen + Plan/Seats/Billing-State nach `BILL-*`) + Trial-Verlängerung + Notizen — 2026-07-20 geschlossen: Trial-Verlängerung (1–365 Tage, nie rückwärts, räumt past_due/frozen auf), Konnektoren + Notizen produktiv im Tenant-Detail verdrahtet, vollständige Anlage-Route `/admin/accounts/new` (auf Raffaels Owner-Einladungs-Flow aufgesetzt). Bewusst außen vor: Demo-Daten-Häkchen (braucht AK-DEMO1-Seeder), Größe-Feld (kein Modell-Feld, wäre CR).
- [x] **Impersonate** (temporäre Tenant-User-Session max. 30 Min) mit Klartext-Banner im Tenant + Reason-Pflicht — Cap 30 Min + Banner + MFA-Gate + Operator-Reason-Dialog fertig; derselbe Klartext-Grund wird in beide Audit-Pfade geschrieben
- [x] **User-Verwaltung** (2FA-Reset/Session-Revoke), **Feature-Flag-UI** (zur Engine aus P1)
- [ ] **Queue-Monitor** (BullMQ Retry/Pause/Resume, Job-Detail mit Error-Stack) + **Support-Inbox** — *Backend fertig (Service + VM + audited Aktionen). Offen: finale UI (David), BullMQ-Adapter-Runtime auf Staging*
- [x] **Queue-Monitor** (BullMQ Retry/Pause/Resume, Job-Detail mit Error-Stack) + **Support-Inbox** — 2026-07-20 geschlossen: Job-Detail-Dialog mit vollem BullMQ-`stacktrace` + Timeline; Support aus dem deaktivierten `help-desk`-Plugin-Baum nach `/admin/support` verlegt (Overview/Tickets/Feedback) + Ticket-Detail mit Thread/Reply/interner Notiz/Status/Zuweisung über den auditierten Service. Offen bleibt nur der Staging-Redis-Betriebsproof (Restliste B, extern).
- [x] **`AdminAuditLog`** (tenant_id=null, Hash-Kette); sensitive Aktionen mit Reason-Pflicht + Confirm-Phrase — via AuditEvent-Querschnitt (tenantId=null/actorType=admin) + `/admin/audit` cross-tenant + Gate
- [x] Eigene getrennte Admin-Shell (kein Reuse der App-Sidebar)
@@ -57,15 +65,21 @@ Die **getrennte Plattform-Admin-Welt** auf `admin.hivegrid.de` (Host-Routing, **
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 11: Plattform-Admin** (eigene Welt, kein tenant_id; AdminAuditLog/TenantNote/SupportTicket v1, AdminUser/Role/Session = v2) + **Domäne 12** (Abo-Baukasten für Abo-Zusammenstellung)
- `REQUIREMENTS.md` → `REQ-plattform-admin-identität` (AdminUser-Identität/RBAC → v2), `REQ-plattform-admin-features`
- `ROADMAP.md` → Phase 19 · `PHASE-SOURCES.md` → Phase 19 (M031/M032 Flag-UI, M034-auth bindende Auflagen, M035 gedünnt, M036-mandanten, M037-impersonate, M041-health/audit/support; M038/M039/M033/M040 → v2)
- `ROADMAP.md` → Phase 19 · Milestones: (M031/M032 Flag-UI, M034-auth bindende Auflagen, M035 gedünnt, M036-mandanten, M037-impersonate, M041-health/audit/support; M038/M039/M033/M040 → v2)
- `designer-briefs/P19-plattform-admin.md` (eigene Admin-Shell, Abo-Baukasten-Panel, Impersonate, v1-Cuts)
- `_bmad-output/specs/M37-plattform-admin.md`, `M32-feature-flags.md`
## Dev-Nachzug (nach Davids `D-ADMIN`/`D-P19`-Delta)
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [ ] REQUIREMENTS/ROADMAP nachgezogen
- [ ] Plane-Ticket `AK-P19` aktualisiert
**Interim-UI (Vorschau, Stand 2026-07-12):** Vier app-chrome-freie Screens aus `~/ui` gebaut —
`apps/web/app/components/screens/admin/AdminBillingPage.tsx`, `AdminJobsPage.tsx`,
`AdminHealthPage.tsx` und `AdminSupportInboxPage.tsx`. Proof: gezielte Route-/VM-/Impersonation-/Visual-Tests 39/39, Interim-Visual-Snapshot
`apps/web/app/components/screens/admin/__snapshots__/ak-p19-interim.visual.test.tsx.snap` und
Admin-E2E-Smoke `tests/e2e/admin-p19-interim-smoke.spec.ts`. Refactor-Nachzug offen: finale
Subframe-Optik aus `D-ADMIN` (Plane-Label `design-nachzug`).
## Umsetzungs-Notiz
### 2026-06-25 — Backend-Fundament (Branch `feat/AK-P19`)
@@ -120,19 +134,70 @@ Commit `feat(AK-P19): cap operator impersonation at 30 minutes`. web-Typecheck 0
Commits `test(AK-P19): DB-backed integration test`, `test(AK-P19): extend ... support-inbox thread`. Damit ist der selbst-machbare Backend-Teil **gegen eine echte DB verifiziert**; `db push` aus der offenen DoD-Restliste erledigt. Es fehlt selbst-machbar nur noch: Trial-Verlaengerung + manuelle Tenant-Anlage + Billing-Recut-Adminbasis (`BILL-06`, Lago/Mollie/HiveGrid-gekoppelt) und Davids finale UI.
## Noch zu erledigen (Stand 2026-06-26, ~70 % DoD)
## Noch zu erledigen (Stand 2026-07-20, 8/8 DoD dev-seitig)
**A — Selbst machbar, aber Billing-/Multi-Subsystem-gekoppelt (eigene CR/Folge-Arbeit sinnvoll):**
- [ ] **Trial-Verlängerung** je Tenant (Subscription-Trial-Ende setzen + Reason + Audit) — haengt am neuen Billing-State aus `BILL-02`/`BILL-05`.
- [ ] **Manuelle Tenant-Anlage** `/tenants/new` (Name/Slug-Live-Validation, Branche/Größe, Initial-Admin-Email, Module/Plan, Trial, Demo-Daten, Reason) als DoD-konforme **neue** Route (nicht die Legacy-`accounts/$id`-Route umbauen) — berührt Tenant-Create + Initial-User + Subscription + Demo-Seed.
- [ ] **Subscription-Override / Billing-State-Seite** (Plan/Seats/Sonderfall/Refund-Verweis, Lago/Mollie-Sync forcieren) — umgesetzt ueber `BILL-06`, nicht ueber Legacy-Provider.
**A — Selbst machbar in AK-P19:** *(alle fünf Punkte am 2026-07-20 geschlossen, siehe Umsetzungs-Notiz unten)*
- [x] **Trial-Verlängerung** je Tenant (1–365 Tage, Reason + Audit, räumt past_due/frozen auf)
- [x] **Manuelle Tenant-Anlage vervollständigt:** eigene Route `/admin/accounts/new` mit Branche/Typ, Owner-Einladung, optional Plan/Seats + Trial, Reason/Audit (Demo-Daten-Häkchen wartet auf AK-DEMO1-Seeder; Größe-Feld = CR)
- [x] **Tenant-Detail-Wiring:** Konnektoren + Notizen + Trial produktiv im Tenant-Detail (`AdminTenantOperationsPanel`)
- [x] **Support-Ticket-Detail:** `/admin/support/:id` mit Thread, Reply, interner Notiz, Status, Zuweisung
- [x] **BullMQ-Job-Detail:** Dialog mit vollem `stacktrace` (alle Versuche) + Timeline
**B — Extern blockiert (Davids `D-ADMIN`/`D-P19`-Delta ist leer):**
- [ ] Finale Subframe-Screens aller Admin-Routen (Tenant-Detail mit Abo-Baukasten-Panel + Notizen-Editor, Queue-Monitor, Support-Inbox, Impersonate-Begründungs-Modal, manuelle Tenant-Anlage).
- [ ] Daran hängende DoD-Querschnitte: Reachability/Sidebar-Gate je neuer Route, Breadcrumbs, **Smoke-Tests** `e2e/smoke/admin-*.spec.ts`, **Hot-Swap-Drill**, **Visual-Regression-Snapshots**, Empty/Loading/Permission-Denied-States.
**B — Betrieb/Runtime:**
- [ ] **BullMQ-Queue-Monitor-Adapter** gegen echtes Redis auf **Staging** verifizieren und den Proof dokumentieren. Unit-Logik, Route und UI-Aktionen sind getestet.
**C — Betrieb/Runtime:**
- [ ] **BullMQ-Queue-Monitor-Adapter** gegen echtes Redis auf **Staging** verifizieren (Unit-Logik + Orchestrierung sind getestet; der Live-Adapter braucht Redis).
- [ ] Operator-**Reason-Modal** auf der neuen Tenant-Detail-Impersonate-Aktion ans Gate verdrahten (Backend-Enforcement steht, UI = David).
**C — Getrackter Design-Nachzug, nicht Done-blockierend (AD-28):**
- [ ] Finale Subframe-Optik aus `D-ADMIN`/`D-P19` übernehmen und die oben aufgeführten Dev-Nachzüge aktualisieren. Die vorhandenen Interim-Screens, Impersonation-Reason-Dialoge sowie Smoke-/Hot-Swap-/Visual-Proofs bleiben bis dahin die Baseline.
**Fertig (Backend verifiziert, gegen echte DB):** admin.prisma (`db push` ok), Operator-Audit-Gate (Reason+Confirm-Phrase), Abo-Baukasten-Konnektoren, Tenant-Notizen, Queue-Monitor-Logik, Support-Inbox-Service, Impersonate-Cap 30 Min. DoD #1/#2/#5/#7/#8 grün.
**Fertig und im Code produktiv verdrahtet:** `admin.prisma` (`db push` ok), Operator-Audit-Gate, `BILL-06`-Billing-State inklusive Plan-/Seat-Override und Lago-/Mollie-Sync, Queue-Übersicht mit Retry/Pause/Resume, Support-Übersicht, Impersonation-Reason und 30-Minuten-Cap. DoD #1/#2/#4/#5/#7/#8 sind grün.
### 2026-07-12 — AD-28 Interim-UI + Impersonation-Reason
**Umgesetzt:**
- Subframe-MCP geprüft: kein P19-/Plattform-Admin-Flow vorhanden; `D-ADMIN` in Plane weiter Backlog. Deshalb AD-28-Interim-Screens nach den bestehenden Automations-/Forms-Patterns gebaut.
- Billing, Queue/Jobs, Health und Support-Übersicht rendern aus bestehenden Loader-/View-Models über
`~/ui`-`StatsCard`, `Card`, `Table`, `BadgeFeedback`, `BannerAlert`, `EmptyState` und Form-Controls.
Die Admin-Shell bleibt allein in der Route-Hierarchie; kein `DefaultPageLayout`, keine rekursive Sidebar.
- Impersonation verlangt jetzt im echten `Dialog` einen Operator-Grund mit mindestens 10 Zeichen.
Der Server erzwingt dieselbe Mindestlänge und schreibt den Klartext-Grund in `ImpersonationAudit` und
`AuditEvent`; MFA-Step-up, 30-Minuten-Cap und Tenant-Banner bleiben unverändert.
**Proof:** `pnpm --filter @hivegrid/web typecheck` Exit 0; repo-weites `pnpm lint` Exit 0;
gezielte Route-/VM-/Impersonation-/Visual-Tests 39/39; `verify:i18n`, `test:hot-swap`,
`verify:ui-visual`, `verify:sidebar-routes`, `verify:source-health` und `verify:ci-baseline` Exit 0.
Der repo-weite `pnpm test`-Preflight hing auf Windows nach 10 Minuten am bekannten
`execvpe(/bin/bash) failed`-Umgebungsfehler; deshalb gemäß AGENTS.md gezielte Vitest-Läufe.
**%-DoD-Stand:** **AK-P19: 6/8 DoD = 75 % done.** Voll grün: #1, #2, #4, #5, #7, #8.
Teilweise/offen und daher nicht gezählt: #3 (Trial-Verlängerung + vollständige manuelle Tenant-Anlage +
Tenant-Detail-Interim-Screen) und #6 (Support-Ticket-Detail/Reply-UI; BullMQ-Live-Adapter auf Staging).
Selbst machbar offen: die genannten UI-/Action-Wirings. Extern blockiert: nur finale `D-ADMIN`-Optik,
die dank Interim-UI als `design-nachzug` getrackt und nicht als eigener Backend-Blocker gewertet wird.
### 2026-07-13 — Ist-Code-Audit und Doc-Drift-Nachzug
Den nach PR #95 auf `main` gemergten Code erneut gegen die beiden offenen DoD-Punkte geprüft:
- **DoD #3:** `BILL-06` ist vollständig umgesetzt und produktiv über `/accounts/billing` verdrahtet. Plan-/Seat-Override, Lago-/Mollie-Sync, Billing-State und Interim-UI sind daher nicht mehr offen. Die einfache Tenant-Anlage existiert bereits, erfüllt aber nicht die vollständige AK-P19-Feld-/Reason-/Trial-/Demo-Spezifikation. Entitlement-Konnektoren und Tenant-Notizen besitzen getestete Services, jedoch noch kein produktives Tenant-Detail-Wiring. Eine Trial-Verlängerungsaktion existiert nicht.
- **DoD #6:** Queue Pause/Resume/Retry sind einschließlich Route, CSRF, Permission, Audit und Interim-UI produktiv verdrahtet. Offen bleiben der BullMQ-Stacktrace im Job-Detail und der Staging-Redis-Proof. Die Support-Übersicht ist produktiv; Reply, interne Notiz, Status und Zuweisung existieren nur als getesteter Service und werden von keiner Produktionsroute aufgerufen.
- Historische Umsetzungsnotizen oben bleiben als damalige Zeitstände erhalten; die DoD-Kommentare und die führende Restliste wurden auf den aktuellen Code-Stand korrigiert.
**Proof:** Code-Read auf `main` (`6d352d050`), Produktionsimport-Suche für `subscription-assembly.server.ts`, `tenant-notes.server.ts` und `support-inbox.server.ts`, Route-/Action-Abgleich für Billing, Jobs, Tenant-Anlage und Help-Desk. Nur diese Ticket-Doc geändert.
**%-DoD-Stand:** **AK-P19: 6/8 DoD = 75 % done.** Offen bleiben #3 und #6 mit den oben konkretisierten Restarbeiten; der finale Subframe-Nachzug ist nach AD-28 nicht Done-blockierend.
### 2026-07-20 — Stand-Audit + Restarbeiten (Branch `fix/ak-p19-audit-restwork`)
**Audit-Befund (wichtig):** Der Plane-Kommentar vom 2026-07-16 („dev-seitig 8 von 8, 312 Admin-Tests grün") beschreibt Arbeit, die **nie im Repo angekommen ist** — kein Commit nach dem 13.07. auf `main` oder irgendeinem Origin-Branch enthielt Trial-Verlängerung, `/accounts/new`, Tenant-Detail-Wiring, Support-Detail oder Job-Stacktrace (`git log --all --grep AK-P19`, Artefakt-Suche). Die Session hat vermutlich nie gepusht; ein lokaler Stand existiert laut Owner nicht mehr. Die Restarbeiten wurden deshalb neu gebaut, der 16.07.-Kommentar diente als Spec. Nebenbefund: Raffaels `e8838dc0c` (15.07., ohne AK-Ticket) hatte die Tenant-Anlage bereits um Owner-E-Mail-Einladung (ownerless Reservations) erweitert — die neue Anlage-Route setzt darauf auf statt zu duplizieren.
**Umgesetzt (Commits `f490a5556`, `740caf849`, `f1f0ad372`, `c978a4e47`, `ba5c221e5`):**
- **DoD #3:** `extendTenantTrial` in `billing-admin.server.ts` (1–365 Tage, nie rückwärts, räumt past_due/frozen, Audit `tenant.trialExtended`); `AdminTenantOperationsPanel` (Interim, `~/ui`) bindet Trial + `subscription-assembly` + `tenant-notes` produktiv in `accounts/$id.tsx`; Anlage-Route `/admin/accounts/new` (`AdminTenantCreatePage`) mit Branche/Typ, Owner-Einladung, optional Plan/Seats/Trial, Reason + Audit `tenant.created`.
- **DoD #6:** Support-Baum von den deaktivierten `help-desk`-Plugin-Routen nach `admin/support/` verlegt (Overview/Tickets/Feedback) + neues Ticket-Detail `admin/support/$id.tsx` (`AdminSupportTicketPage`): Thread (Erstnachricht als Inbound), Reply, interne Notiz, Status, Zuweisung an AdminUser — alles über den auditierten `support-inbox.server`. `support` als kanonischer Admin-Slug in `PublicRouteSegments.ts` registriert (sonst stiller 404 durch HostRouting); Sidebar-Eintrag `ui.nav.admin.helpDesk` → `/support`. Queue-Job-Detail: `QueueInspector.getJobDetail` + BullMQ-`stacktrace[]`/Timeline im echten `Dialog` (`?detailQueue&detailJob`).
- **RLS:** Tenant-Detail-Reads/-Writes laufen im gebundenen `runWithRlsContext({tenantId})` (Test `$id.rls-context.test.ts` erweitert); Cross-Tenant-Support-Reads über den Operator-Zweig wie die bestehenden Admin-Listen.
**Proof:** web-Typecheck Exit 0 · `verify:i18n`/`verify:sidebar-routes`/`verify:cross-cutting-models`/`verify:ui-visual`/`test:hot-swap` Exit 0 · Admin-Test-Sweep **135/135** (3 DB-Integrationstests auto-skip ohne `ADMIN_IT_DATABASE_URL`) · Interim-Visual-Baseline re-baselined + um die drei neuen Screens erweitert · E2E-Smoke auf `/support` + `/accounts/new` umgestellt. Kein Schema-Change, keine neue Permission, keine Migration nötig.
**Sichtbar unter** (lokal `pnpm dev:local`, `http://admin.localhost:3000`): `/accounts/<id>` (Trial/Konnektoren/Notizen), `/accounts/new`, `/support` + `/support/<ticketId>`, `/jobs` (Details-Button an fehlgeschlagenen Jobs). Screens: `apps/web/app/components/screens/admin/AdminTenantOperationsPanel.tsx`, `AdminTenantCreatePage.tsx`, `AdminSupportTicketPage.tsx`.
**%-DoD-Stand:** **AK-P19: 8/8 DoD = 100 % dev-seitig.** Offen (nicht dev-blockierend): Staging-Redis-Betriebsproof für den Queue-Adapter (Restliste B, nach Deploy) und der getrackte `design-nachzug` (AD-28).
**Nachzug 2026-07-20 (Browser-Review, Commit `9626e09f5`):** Die „Tage"-Box der Trial-Verlängerung hatte drei Defekte in der Subframe-`NumberInput`-Komponente bzw. deren Nutzung: (a) fixe `h-9`-Root-Höhe trotz Label → Input lief unter die Karte; (b) Grid-Spalten (140/160px) schmaler als die fixe 192px-Komponente → Nachbarfeld überdeckte die Stepper (betraf auch Billing-Seats + Tenant-Anlage); (c) Stepper-Chevrons waren app-weit reine Deko → klicken jetzt `stepUp()/stepDown()`. Zusätzlich fängt die Tenant-Ops-Action unerwartete Fehler als Klartext-Banner statt 500-Seite. **Lokaler Betriebs-Befund dabei entdeckt:** Der `AuditChainHead` der lokalen Dev-DB (chainKey `platform`) verifiziert nicht gegen das aktuelle `AUDIT_CHAIN_SECRET` → **jede** Operator-Aktion (Trial, Konnektoren, Notizen, Billing-Override, Queue-Pause) scheitert lokal am Audit-Writer. Kein Code-Bug; Reparatur = Chain-Head mit aktuellem Secret neu signieren oder lokale DB frisch aufsetzen. Staging/Prod nicht betroffen (dort ist das Secret konsistent zur DB).
@@ -7,17 +7,25 @@
> ⚠️ **KI→MCP-Pivot ([[AD-26]]):** Der **AI-Credits-Screen + AI-Token-Quota entfallen** (kein LLM-Gateway in v1 — HiveGrid wird MCP-Server, [[VR-MCP]]; `AiCredits`/`AiTokenUsage` gestrichen). Die Verbrauchs-Übersicht bleibt für Automation-Läufe + Speicher. Alle AI-Credits/AI-Token-Stellen unten sind durchgestrichen.
> 🔄 **Provisionierungs-Recut 2026-07-15 (R-CR1/R-P20b, AD-29):** AK-P20 bleibt abgeschlossen; der
> damalige Auto-SHK-Provisionierungs-Slice und seine Proofs zu `provisionShkTenantDefaults()`/
> `shkRoles.server.ts` bleiben unten ausschließlich als historische Umsetzung dokumentiert. Aktueller Vertrag
> für neue Workspaces ist der zentrale R-P20b-Bootstrap mit fünf editierbaren Tenant-Rollen und ausschließlich
> der globalen Rolle `Admin` für den Owner. Bestehende Tenants werden nicht automatisch verändert.
| | |
|---|---|
| **Typ** | Dev (Code) |
| **Owner** | Akeshan |
| **Phase** | P20 — Billing, Onboarding & Branding |
| **Cycle/Fenster** | W4 — USP, Härtung & Launch · fällig 2026-07-08 · Gate W4 |
| **Status** | Recut / On Hold fuer Billing-Anteil; Onboarding/Branding/Frozen-Vorarbeit verwertbar |
| **Status** | Dev-DoD 8/8 = 100 %; Interim-UI nach AD-28; Ready-to-Verify / Done-Freigabe ausstehend |
**🎨 design-nachzug: offen** (seit 2026-07-12) — Interim-UI aus `~/ui` steht; finale Subframe-Optik aus `D-P20` ausstehend.
## Abhängigkeiten & Parallelität
- **Blocked by:** `BILL-00` bis `BILL-05` fuer den neuen Billing-Kern; `AK-P19` fuer Admin-/Tenant-Verwaltungsgrundlagen; `D-P20` fuer finale Screens
- **Blocks:** `AK-P21` teilweise (Read-only/Frozen-State und Billing-Cancel-Vertrag), `BILL-06` (Admin-Billing-Basis), spaetere Customer-Billing-Screens
- **Blocked by:** keine selbst machbaren Dev-Blocker. `D-P20` ist nach AD-28 nur noch ein nicht blockierender Design-Nachzug.
- **Blocks / gelieferte Verträge:** `AK-P21` kann den unveränderten Read-only-/Frozen-/Billing-Cancel-Vertrag konsumieren; die `BILL-06`-Admin-Basis steht bereits. Spätere Customer-Billing-Screens bauen auf den hier stabilisierten VMs/Routen auf.
- **Läuft parallel zu:** Raffaels Kern-Kette (Auftrags-/Abnahme-Welt P9). Eigene `prisma/schema/billing.prisma` + Onboarding-Teile (AD-21); `core.prisma` (Tenant) nur über Relation.
- **Konflikt-Risiko:** gering — additive Tabellen + Read-Only-Middleware (Frozen) auf der Request-Pipeline (Querschnitt, additiv).
@@ -26,10 +34,10 @@
Drei gebündelte v1-Module:
1. **Billing-Grundlagen:** lokaler Billing-/Entitlement-State fuer Plans + Seats, Trial/Dunning/Frozen, Read-only-State
und Feature-Gates. Lago wird spaeter Billing-Source-of-Truth, Mollie nur Payment Processor.
und Feature-Gates. Lago ist Billing-/Invoice-Source-of-Truth, Mollie ausschließlich Payment Processor.
2. **Onboarding:** Auto-SHK-Provisionierung beim Signup (Seeds M158, ohne Wizard) + Demo-Daten-Knopf +
Erste-Schritte-Checkliste.
3. **Branding:** nur Hell/Dunkel-Toggle (kein System-Modus), flash-frei via SSR-Cookie.
3. **Branding:** Light/Dark-Unterbau bleibt erhalten; Toggle und Dark-Anwendung im App-/Admin-Bereich sind vorerst deaktiviert (PR #81).
Nicht mehr Ziel dieses Tickets: Legacy-Provider-Abo-Baukasten, Legacy-Provider-Customer-Portal, Payment-Checkout, Usage-Billing,
AI-Credits oder Pricing-/Upgrade-UI fuer Endkunden.
@@ -37,67 +45,165 @@ AI-Credits oder Pricing-/Upgrade-UI fuer Endkunden.
## Benötigte Screens (Backend bedient — Design liefert `D-P20`)
| Screen [Route] | Kern-Inhalt |
|---|---|
| Abo-Übersicht [`/admin/subscription`] | Basis-Plan + **Feature-Module als Positionsliste mit Preisen** (read-only), Status/Trial-Countdown, **KEIN Upgrade-Button** (Hinweis-Box „Plan-Wechsel über Account-Manager/hivegrid.de"), Pausieren + Kündigen |
| Verbrauchs-Übersicht [`/admin/usage`] ~~· AI-Credits [`/admin/usage/ai-credits`]~~ (AI-Credits-Screen entfällt — [[AD-26]]) | Quota-Balken je Metrik (Automation/~~AI-Tokens~~ (entfällt)/Speicher), ~~Donut AI-Verbrauch~~, 80%-Warnbanner, Aufgebraucht-Klartext |
| Rechnungen/Zahlung [`/admin/billing`] | Lago-Invoice-Status + Mollie-Payment-Status + Klartext-Hilfe; kein Legacy-Provider-Portal-Embed |
| Demo-Daten [`/admin/onboarding/demo-data`] | Settings-Knopf „Beispieldaten anlegen" (~25 Datensätze, Klartext-Liste), Demo-Zähler + Lösch-Funktion, „Demo ausblenden"-Filter |
| Erste-Schritte-Checkliste [`/onboarding/checklist`] | Auto-erkannte Status-Häkchen, CTA-Links, manuell abhakbar/ausblendbar, Glückwunsch bei 100% (auch Dashboard-Widget) |
| Status-Banner-System (Shell) | trial-Ende-3-Tage / past_due / frozen / deletion_pending je eigener Klartext + Action; Read-Only-Toast bei blockiertem Schreib-Button |
| Hell/Dunkel-Toggle [Profil/User-Menü] | Zwei Optionen, sofortige Anwendung, flash-frei (SSR-Cookie) |
| Abo-Übersicht [`/:tenant/settings/subscription`] | Plan + Seats + Feature-Module (read-only), Status/Trial-Countdown, **KEIN Upgrade-Button** (Hinweis „Plan-Wechsel über Account-Manager/hivegrid.de"), Kündigen falls freigegeben |
| Verbrauchs-Übersicht [`/:tenant/settings/usage`] | Quota-Balken fuer Automation und Speicher, Warnbanner und Aufgebraucht-Klartext; keine Usage-Billing-Sprache |
| Rechnungen/Zahlung [`/:tenant/settings/billing`] | Lago-Invoice-Status + Mollie-Payment-Status + Klartext-Hilfe; kein Legacy-Provider-Portal-Embed |
| Demo-Daten [`/:tenant/settings/onboarding/demo-data`] | Settings-Knopf „Beispieldaten anlegen" (~25 Datensätze, Klartext-Liste), Demo-Zähler + Lösch-Funktion, „Demo ausblenden"-Filter |
| Erste-Schritte-Checkliste [`/:tenant/onboarding/checklist`] | Auto-erkannte Status-Häkchen, CTA-Links, manuell abhakbar/ausblendbar, Glückwunsch bei 100% (auch Dashboard-Widget) |
| Status-Banner-System (Shell) | AK-P20: Trial-Ende-3-Tage / `past_due` / `frozen` mit Klartext + Abo-Aktion; die bestehende 423-Klartext-Hülle bleibt. `deletion_pending` samt Shell-Aktion gehört zu `AK-P21`/`D-P21`; der finale Read-only-Toast bleibt `D-P20`-Design-Nachzug. |
| Light/Dark-Toggle [Profil/User-Menü] | Vorerst ausgeblendet und im App-/Admin-Bereich deaktiviert (PR #81) |
## Definition of Done
- [ ] **Billing-Recut-Basis**: lokaler Plan-/Seat-/Entitlement-State ist auf Lago/Mollie/HiveGrid ausgerichtet; keine Legacy-Provider-IDs als Zielmodell; kein Usage-Billing
- [x] **Billing-Recut-Basis**: lokaler Plan-/Seat-/Entitlement-State ist auf Lago/Mollie/HiveGrid ausgerichtet; keine Legacy-Provider-IDs als Zielmodell; kein Usage-Billing
- [x] **Trial + Dunning** (Tag 1/3/7) + **Frozen-Modus** (Read-Only-Middleware) greift; Status-Banner pro Zustand; Verbrauchs-Zähler + Drossel (Aufschlags-Abrechnung → v2)
- [x] **In-App keine** Pricing-Tabelle/Upgrade-Buttons/Plan-Wechsel-UI (LP-8) — Read-Only + externer Verweis; Pause/Kündigen erlaubt
- [x] **In-App keine** Pricing-Tabelle/Upgrade-Buttons/Plan-Wechsel-UI (LP-8) — Read-Only + externer Verweis; Kündigen bleibt bei vorhandener Berechtigung erlaubt
- [x] **Auto-SHK-Provisionierung** beim Signup (Seeds M158: Pipelines, Custom-Felder, Rollen, Form-Templates, Checkliste) — **ohne Wizard-UI** (v2)
- [x] **Demo-Daten-Knopf** (per Settings, `is_demo_data`-Flag löschbar) + „Demo ausblenden"-Filter
- [x] **Erste-Schritte-Checkliste** (auto-erkannter Status, CTA-Links, abhakbar/ausblendbar; Dashboard-Widget)
- [x] **Hell/Dunkel-Toggle** flash-frei (SSR-Cookie, `next-themes`) — kein System-Modus
- [x] **Light/Dark-Unterbau** bleibt erhalten; Toggle und Dark-Anwendung sind vorerst deaktiviert (`DARK_MODE_IN_APP=false`, PR #81)
- [x] Konnektor `tenantHasModule('billing')`; RLS auf allen Tenant-Tabellen
## Aktueller Stand (Billing-Recut 2026-07-04)
## Aktueller Stand (Interim-UI 2026-07-12)
**Fortschritt:** **AK-P20: 7/8 historischer DoD = 87,5 % done; nach AD-27 bleibt 1/8 blockiert/ersetzt durch `BILL-02` bis `BILL-05`.**
**Fortschritt:** **AK-P20: 8/8 DoD = 100 % done.** Es gibt keine selbst machbare Dev-Arbeit mehr.
Die finale Subframe-Optik aus `D-P20` bleibt als nicht blockierender `design-nachzug` offen. Das Plane-Ticket
wird ohne separate Done-Freigabe nicht auf Done gesetzt.
**Erledigt:**
- Trial/Dunning/Frozen inkl. Statusbanner, zentralem Read-only-Guard, Usage-Zählern und Drossel.
- In-App-Subscription bleibt read-only: keine Pricing-Tabelle, keine Upgrade-Buttons, keine Planwechsel-UI; Billing-/Zahlungsaktionen bleiben nur als freigegebene Recovery-/Kontaktpfade erreichbar.
- Auto-SHK-Provisionierung beim Signup mit Rollen, Pipeline, Formular-Templates, Projekt-/Abnahme-Templates und Checkliste.
- Demo-Daten-Knopf, `isDemoData`-Tracking, Löschung und Standardfilter “Demo ausblenden”.
- Erste-Schritte-Checkliste mit Auto-Erkennung, manuellen Zuständen und Dashboard-Widget.
- Hell/Dunkel-Toggle ohne System-Modus, SSR-Cookie-basiert.
- Billing-Konnektor `tenantHasModule('billing')`, Tenant-Isolation/RLS-Artefakte und Boundary-Gates.
- Seat-Typen im Plattform-Admin-Pricing blockiert: keine `PER_SEAT`-Seeds, keine `PER_SEAT`-Auswahl, serverseitige Guards gegen manipulierte Formulare.
- Lago-/Mollie-/HiveGrid-Recut aus `BILL-02` bis `BILL-05`, Trial/Dunning/Frozen, Shell-Statusbanner
für die AK-P20-Billing-Zustände (nicht `deletion_pending`),
zentraler Read-only-Guard sowie nicht abrechenbare Usage-Zähler und Drossel.
- Read-only Subscription ohne Pricing-, Upgrade-, Planwechsel- oder Checkout-UI; nur Kontakt und erlaubte
Kündigung. Rechnungen zeigen Lago-Invoice- und Mollie-Payment-State.
- Auto-SHK-Provisionierung, Demo-Daten-Verwaltung samt Environment-Gate/Listenfilter und Erste-Schritte-
Checkliste samt Dashboard-Widget.
- App-/Admin-Dark-Mode und Toggle bleiben wie mit PR #81 beabsichtigt deaktiviert; der Unterbau bleibt erhalten.
- Fünf app-chrome-freie Interim-Screens aus `~/ui`, reine VM-Verträge, Smoke-/Hot-Swap- und Interim-Visual-Proof.
Der M016-Pixelnachweis liegt in `tests/component/ak-p20-interim.ct.tsx` mit fünf PNG-Baselines unter
`tests/component/__screenshots__/`; der schnelle React-Markup-Nachweis liegt in
`apps/web/app/components/screens/ak-p20-interim.visual.test.tsx`. Die austauschbare Mock-Baseline liegt
unter `packages/ui-mock/visual-baseline/ak-p20-interim.*`.
**Offen:**
- Neuer Billing-Abschluss: lokale Billing-Domain auf Lago-/Mollie-Referenzen umstellen, Legacy-Provider-spezifische Felder/Services inventarisieren und ueber `BILL-02` bis `BILL-05` ersetzen.
- Finale Subframe-/Screen-Integration aus `D-P20`.
**Recut-Entscheidung:** AK-P20 wird nicht still auf Done gesetzt. Die verwertbaren Teile (Trial/Dunning/Frozen,
Read-only, Onboarding, Demo-Daten, Checkliste, Theme, Entitlement-Gates) bleiben Grundlage. Der alte
Legacy-Provider-Abo-Baukasten-DoD wird durch `BILL-02` bis `BILL-05` ersetzt.
**Offen, nicht Done-blockierend:** finales Layout-/Copy-Delta aus `D-P20`, anschließender Component-Swap und
Re-Baseline. Die fachlichen Loader-, VM- und Action-Verträge bleiben dabei stabil.
## Technische Bausteine
- **Entities** (eigene `prisma/schema/billing.prisma`): bestehende Subscription-/Feature-/Usage-Tabellen bleiben Migrationsbasis, muessen aber in `BILL-02` von Legacy-Provider-zentrierten Referenzen auf Lago-/Mollie-/HiveGrid-Referenzen umgestellt werden. Onboarding: `Onboarding`/`OnboardingSession`/`OnboardingDemoProvisioning`. Branding: `User.theme_preference` (Feld, kein eigenes Modell). `core.prisma` nur ueber noetige Tenant-Relationen (AD-21).
- **Entities** (eigene `prisma/schema/billing.prisma`): Subscription-/Feature-/Usage-Tabellen tragen den lokalen HiveGrid-State sowie Lago-/Mollie-Referenzen; Legacy-Felder sind nur noch Migrationskompatibilität, nicht Zielmodell. Onboarding: `Onboarding`/`OnboardingSession`/`OnboardingDemoProvisioning`. Branding: vorhandener User-Theme-Unterbau (kein neues Modell). `core.prisma` nur ueber noetige Tenant-Relationen (AD-21).
- **Abo-/Entitlement-Schicht:** `SubscriptionFeature.code` (z.B. `kwp_integration`) = Entitlement-Schicht; `tenantHasModule()` bleibt zentrale Gate-API.
- **Billing-Integration neu:** Lago-Gateway (`BILL-03`), Mollie-Payment-Gateway (`BILL-04`), Sync/Frozen-State (`BILL-05`). Die vorhandenen Legacy-Provider-Webhook-/Dunning-Tests sind Migrationsvorlage, nicht Ziel.
- **Billing-Integration:** Lago-Gateway (`BILL-03`), Mollie-Payment-Gateway (`BILL-04`) und Sync/Frozen-State (`BILL-05`) sind der aktive Vertrag. Historische Legacy-Webhook-/Dunning-Pfade bleiben nur Migrationsinventar.
- **Auto-SHK-Provisionierung** orchestriert die Self-Seeds aller Module (AD-12); Demo-Daten-Seed via `is_demo_data`; Trial-Freischaltung durch Plattform-Admin (AK-P19).
- **RLS** überall (global: Produkte/Features/Preise); `next-themes` SSR-Cookie für Hell/Dunkel.
- **RLS** überall (global: Produkte/Features/Preise); der bestehende Theme-Unterbau bleibt erhalten, App-/Admin-Dark-Mode wird wegen `DARK_MODE_IN_APP=false` nicht angewendet.
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 12: Billing & Abo-Baukasten** (Recut-Modell, keine Seat-Typen) + **Domäne 13** (Onboarding, OnboardingDemoProvisioning, User.theme_preference)
- `ENTITY-MODEL.md` → **Domäne 12: Billing** (AD-27-Recut: Lago/Mollie/HiveGrid, Plans + Seats) + **Domäne 13** (Onboarding, OnboardingDemoProvisioning, bestehender User-Theme-Unterbau)
- `REQUIREMENTS.md` → `REQ-billing-datenmodell`, `REQ-billing-trial-dunning`, `REQ-onboarding-demo-daten`, `REQ-branding-theme-phase1` (Onboarding-Wizard → v2)
- `ROADMAP.md` → Phase 20 · `PHASE-SOURCES.md` → Phase 20 (M153-legacyProvider, M154-recut bindend, M155-trial-readonly, M156-metering Zähler+Drossel, M158-shk-provisionierung, M159-branchen-templates nur SHK, M160-demo gedünnt, M030 nur Hell/Dunkel)
- `designer-briefs/P20-billing-onboarding-branding.md` (Abo-Baukasten, kein Upgrade-UI LP-8, Demo-Knopf, Hell/Dunkel)
- `_bmad-output/specs/M28-subscriptions-billing.md` (⚠ M154-Recut), `M29-onboarding.md` (Wizard → v2), `M31-branding.md` · Legacy: `archive/hivegrid-cloud/app/config/pricing-plans.ts`
- `ROADMAP.md` → Phase 20 · Milestones: (AD-27-Recut, M155 Trial/Read-only, M156 nur Zähler+Drossel, M158 Signup-Provisionierung, M159 nur SHK, M160 Demo gedünnt, M030-Unterbau bei deaktiviertem Toggle)
- `designer-briefs/P20-billing-onboarding-branding.md` (read-only Lago/Mollie/HiveGrid, kein Upgrade-UI, Demo-Knopf, Theme-Toggle deaktiviert)
## Dev-Nachzug (nach Davids `D-P20`-Delta)
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [ ] Plane-Ticket `AK-P20` aktualisiert
- [x] Interim-UI aus `~/ui` auf den fünf kanonischen Tenant-Routen integriert; VM + Action-Callbacks stabil.
- [x] ROADMAP, REQUIREMENTS, Designer-Brief und `D-P20` auf AD-27/AD-28 sowie PR #81 ausgerichtet.
- [ ] Finale Subframe-Optik aus `D-P20` integrieren und `ak-p20-interim` neu baselinen.
- [x] Plane-Kommentar `1dee227f-4726-4b7c-8ef1-7a15108f7e99`, Recut-Titel und Label
`design-nachzug` nach dem Push gespiegelt; Status bewusst unverändert.
## Umsetzungs-Notiz
### 2026-07-20 · Stand-Audit + Dunning-Trigger-Nachzug (Branch `fix/ak-p20-audit-restwork`)
Drei-Quellen-Audit (Doc vs. Plane vs. Code) nach dem RLS-Cutover vom 14.07. Ergebnis: Interim-UI,
Onboarding, Frozen/Read-only, Demo-Daten, Checkliste und Layer-Trennung sind vollstaendig belegt;
die aktiven Pfade (Mollie-Webhook, Signup-Bootstrap, Checklist-Persistenz) binden den RLS-Kontext korrekt.
**Ein realer Befund:** Die Tag-1/3/7-Dunning-Sequenz (DoD 2) hatte keinen Produktions-Trigger —
`applyBillingDunningCycle()` im Web-Legacy-Service war nur aus Tests aufrufbar, und `BILL-05` hat
Dunning-Mailsequenzen explizit aus seinem Scope ausgeklammert. Korrigierter Stand vor dem Nachzug: 7/8.
Umgesetzt:
- Pure Dunning-Entscheidung (`evaluateBillingDunning`, Tag 1/3/7 + Freeze) nach
`@hivegrid/db/billing-domain.server` gehoben (Commit `b30881a0a`).
- Neuer taeglicher Worker-Cron `billing-dunning-sweep`: Sweep pro Tenant aus der globalen
Tenant-Registry, `TenantSubscription`-Zugriffe in `withTenantRLS()`, Notices ueber
`notifyWithTenantRlsContext()` (FORCE RLS, R-P1b-Praezedenz, sourceKey-Dedupe pro Attempt),
Freeze nach Tag 7 mit `AuditEvent` + `billing_state_changed`-Activity im BILL-05-Format.
Task in der `CleanupJob`-Union registriert (Folge-Commit auf dem Branch).
- Nachzug (per User-Freigabe zum ausgewiesenen Vorschlag): Der tote Legacy-Service
`billingDunningService.ts` (Stripe-Pfade, referenzierte ein nicht existierendes
`stripeWebhookLog`-Modell, keine Konsumenten ausser dem eigenen Test) wurde samt Test
entfernt; ebenso die VM-Dublette `buildBillingStatusBannerVm` + `BillingStatusBannerVm`
aus `billingStatusService.ts` (der reale Banner laeuft ueber
`packages/view-models/src/billing/subscription-banner.vm.ts`). Damit ist der letzte
`stripe`-Import aus dem Codebestand verschwunden.
Audit-Klarstellungen (kein Code-Delta):
- Das fehlende `tenantHasModule('billing')`-Gate auf `settings/subscription.tsx` ist **beabsichtigt**:
`/plan-required/:tenant` verlinkt genau dorthin zurueck und BILL-05-DoD verlangt erreichbare
Recovery-/Billing-Routen im Frozen-Zustand — ein Gate wuerde einen Redirect-Loop erzeugen.
DoD 8 gilt damit als erfuellt (Gates auf `settings/usage` + `settings/billing` vorhanden).
- Proof-Hash-Korrektur zu den 2026-07-12-Notizen: `84f56966c` existiert nach dem Rebase als
`5c27d7b34` (`feat(ak-p20): add interim billing and onboarding UI`); `2ddff0ec0` ist als
PR-#86-Merge `ecca4400a` auf `main`.
- Das Zielschema liegt real in `prisma/schema/subscriptions.prisma` (nicht `billing.prisma`).
Proof: `pnpm --filter @hivegrid/{worker,queue,db,web} typecheck` gruen; fokussierte Suiten
`billing-domain.server.test.ts` (13), `billing-dunning-cron.test.ts` + `handlers.test.ts` (123),
`packages/queue` (127), `index.test.ts`/`notify-rls.test.ts` gruen; `verify:i18n`,
`verify:cross-cutting-models`, `verify:sidebar-routes` gruen.
Fortschritt: **AK-P20: 8/8 DoD = 100 % done** (nach Nachzug; vor dem Nachzug real 7/8 = 87,5 %).
### 2026-07-12 · Bugfix-Nachtrag: EmptyState-Aktions-Buttons + Checklist-Reopen
Befund (Staging-Verifikation `demo-pro-crm`): Der „Demo-Daten erstellen"-Button war im DOM, aber unsichtbar.
Root Cause außerhalb der AK-P20-Dateien: der `~/ui`-EmptyState-Wrapper (`apps/web/app/ui/components/EmptyState/index.tsx`)
mergte noch `[&_button]:hidden` (Alt-Workaround gegen den früheren hartkodierten Subframe-CTA) und versteckte damit
jeden per `action`-Slot übergebenen Button (~10 Screens, u.a. Demo-Daten-Create und Retry-CTAs). Zusätzlich war das
Checklisten-„Ausblenden" irreversibel (Dismissed-State ohne nächste Aktion, DoD-23-Lücke).
Umgesetzt:
- Wrapper-Klasse entfernt + Regression-Guard-Test (`EmptyState.wrapper.test.tsx`).
- Checklist-Reopen: Service-Action `show` (Session zurück auf `active`), „Wieder einblenden"-Button im
Dismissed-State, i18n `onboarding.firstSteps.dismissed.reopen` (de/en), Tests nachgezogen.
- Staging-Ops: versehentlich dismisste Session (john.doe @ demo-pro-crm) per SQL zurück auf `active`.
Proof: PR #86 (`fix(ui): EmptyState action buttons visible again + checklist reopen`, Commit `2ddff0ec0`);
`pnpm typecheck`, `verify:i18n`, `verify:source-health` grün; fokussierte Suites (Wrapper-Guard,
OnboardingInterimScreens, akP20OnboardingService) 12/12 grün. Staging-E2E-Nachweis nach Merge/Deploy.
DoD-Stand unverändert: **AK-P20: 8/8 DoD = 100 % done** (Bugfix, kein Scope-Delta).
### 2026-07-12 · Interim-UI abgeschlossen
Umgesetzt:
- Fünf kanonische Tenant-Screens fuer Subscription, Usage, Rechnungen/Zahlung, Demo-Daten und Erste Schritte
als app-chrome-freie `~/ui`-Komponenten mit reinen VM-/Action-Verträgen.
- Subscription bleibt read-only ohne Pricing, Checkout, Upgrade/Downgrade oder Customer-Portal; Kontakt und
berechtigte Kündigung bleiben verfügbar. Lago-Invoices und Mollie-Payment-State sind getrennt dargestellt.
- Trial-/`past_due`-/`frozen`-Banner in der Tenant-Shell; Aktion nur mit View-Permission. Der Dark-Mode-Toggle
bleibt deaktiviert und auch gespeicherte Tenant-Dark-Farben werden bei `DARK_MODE_IN_APP=false` nicht angewendet.
- Demo-Daten-Settings und Erste-Schritte-Checkliste einschließlich Dashboard-Widget. Der Checklisten-GET ist
strikt read-only; Provisionierung/Persistenz geschieht nur noch über explizite Mutationspfade.
- Echter M016-Pixelvergleich fuer alle fünf Screens sowie schneller React-Markup- und `ui-mock`-Hot-Swap-Proof.
Proof:
- Code-Commit `84f56966c` (`feat(ak-p20): add interim billing and onboarding UI`), auf aktuellem `origin/main`
(`6d16e4da7`) rebased und gepusht.
- Plane-Kommentar `1dee227f-4726-4b7c-8ef1-7a15108f7e99`, Titel auf den AD-27-Recut korrigiert und
Label `design-nachzug` gesetzt; Ticket-State unverändert gelassen.
- `pnpm typecheck` und `pnpm lint` grün; Pre-Push-Typecheck/i18n ebenfalls grün.
- Fokussierte AK-P20-Suite: 22 Testdateien, 112 Tests grün.
- `pnpm run test:component:p20`: 5/5 Chromium-Pixelvergleiche grün; PNGs visuell geprüft.
- `pnpm run verify:i18n`, `pnpm run verify:ui-visual`, `pnpm run test:hot-swap`,
`pnpm run verify:billing-boundary-baseline`, `pnpm run verify:onboarding-flow`,
`pnpm run verify:ci-baseline`, `pnpm run verify:source-health` und `pnpm exec prisma validate` grün.
- Sidebar-Reachability im Main-Workspace: 5 Testdateien, 29 Tests grün. Playwright-E2E-Discovery:
6 AK-P20-Smokes; ein vollständiger Live-Lauf benötigt die E2E-Tenant-Credentials.
- Der breite Root-Wrapper `pnpm test` ist lokal kein belastbarer Gate-Lauf, weil er die benachbarten
`.codex/worktrees` mit separaten React-Installationen einsammelt und dort bekannte Invalid-Hook-Fehler erzeugt.
Die betroffenen Main-Workspace-Dateien und passenden Verify-Gates wurden deshalb explizit und grün ausgeführt.
Fortschritt: **AK-P20: 8/8 DoD = 100 % done.** Keine selbst machbare Dev-Arbeit offen; finales `D-P20`-Delta
bleibt als nicht blockierender `design-nachzug` getrackt. Plane-Done bleibt bis zur separaten Freigabe ausstehend.
> Hinweis 2026-07-04: Die folgenden Slice-Notizen dokumentieren historische Umsetzung vor `AD-27`. Wo sie Legacy-Provider nennen,
> ist das als Migrationsinventar/Vorarbeit zu lesen. Der aktive Zielpfad ist `BILL-02` bis `BILL-05`.
@@ -10,41 +10,47 @@
| **Owner** | Akeshan |
| **Phase** | P21 — DSGVO & Launch-Reife |
| **Cycle/Fenster** | W4 — USP, Härtung & Launch · fällig 2026-07-09 · **Gate W4 (FREEZE)** |
| **Status** | Blocked / On Hold, Teilumsetzung Backend/Fundament |
| **Status** | In Arbeit — Stand 2026-07-21 (2): 10/11 DoD (~91 %). Tenant-Löschung war produktiv nicht durchführbar und ist repariert. Keine echten Blocker mehr: AK-P20 = Done, D-P21 nach AD-28 nicht Done-blockierend, Billing-Gateway verfügbar. |
**🎨 design-nachzug: offen** (seit 2026-07-12) — Interim-UI aus `~/ui` steht; finale Subframe-Optik aus `D-P21` ausstehend.
## Abhängigkeiten & Parallelität
- **Blocked by:** `AK-P20`/`BILL-05` (Billing-Read-only/Frozen-State und Billing-Cancel-Vertrag; Feedback-Widget speist Admin-Support-Inbox aus AK-P19), `D-P21` (finale Privacy-/FAQ-/Feedback-Screens)
- **Blocked by:** `D-P21` (finale Privacy-/FAQ-/Feedback-Screens einschließlich `deletion_pending`-Shell-Aktion) sowie die eigenen offenen Export-, Lösch-, AVV- und Adapter-Nachzüge. Die AK-P20-/BILL-05-Verträge für Read-only/Frozen und Billing-Cancel sind verfügbar; die Admin-Support-Inbox aus AK-P19 steht.
- **Blocks:** **FREEZE** (letzte v1-Phase, macht den Big-Bang-Launch AD-19 auslösbar)
- **Läuft parallel zu:** Raffaels Härtung/Launch-Tickets. Eigene `prisma/schema/gdpr.prisma` (AD-21); Feedback-Widget schreibt in `AdminSupportTicket` (AK-P19, generische Quelle); Export liest tenant-weit über RLS.
- **Konflikt-Risiko:** gering — additive Tabellen + asynchrone BullMQ-Jobs; Crypto-Shredding berührt per-Tenant-DEK (AD-8), keine Schema-Änderung an Fach-Modulen.
## Was wir bauen
Den **DSGVO-Lebenszyklus + Launch-Reife** (letzte v1-Phase): tenant- und user-weiter **DSGVO-ZIP-Export** (asynchroner BullMQ-Job mit Progress, **72h-signed-URL**, Rate-Limit), den **Tenant-Lösch-Workflow** (**Crypto-Shredding** per-Tenant-DEK, **Billing-Cancel ueber Lago/Mollie/HiveGrid-Gateway**, Storage/Cache/Index-Bereinigung, 30-Tage-Grace mit Read-Only + Abbruch, **Slug als Confirm-Phrase**), die **AVV-/Subprozessoren-Sichtbarkeit** im Privacy-Hub, ein **In-App-Feedback-Widget** (speist die Admin-Support-Inbox aus AK-P19) und eine **Minimal-FAQ**-Seite. **DSGVO-Auskunft = manuelles Playbook v1** (Suche → Kontakt-Detail → CSV → Anwalts-Vorlage → Frist-Task +25 Tage), **kein** Auskunfts-Wizard. PWA-only (AD-17): alle Screens mobil tauglich, kein nativer Client.
Den **DSGVO-Lebenszyklus + Launch-Reife** (letzte v1-Phase): tenant- und user-weiter **DSGVO-ZIP-Export** (asynchroner BullMQ-Job mit Progress, authentifizierter und bis zu 72 h verfügbarer Download, Rate-Limit), den **Tenant-Lösch-Workflow** (**Crypto-Shredding** per-Tenant-DEK, **Billing-Cancel ueber Lago/Mollie/HiveGrid-Gateway**, Storage/Cache/Index-Bereinigung, 30-Tage-Grace mit Read-Only + Abbruch, **Slug als Confirm-Phrase**), die **AVV-/Subprozessoren-Sichtbarkeit** im Privacy-Hub, ein **In-App-Feedback-Widget** (speist die Admin-Support-Inbox aus AK-P19) und eine **Minimal-FAQ**-Seite. **DSGVO-Auskunft = manuelles Playbook v1** (Suche → Kontakt-Detail → CSV → Anwalts-Vorlage → Frist-Task +25 Tage), **kein** Auskunfts-Wizard. PWA-only (AD-17): alle Screens mobil tauglich, kein nativer Client.
## Benötigte Screens (Backend bedient — Design liefert `D-P21`)
| Screen [Route] | Kern-Inhalt |
|---|---|
| Privacy-Hub [`/admin/privacy`] | Übersicht Export/Löschung/Subprozessoren/AVV/Privacy-Manifest-Link, Einstieg in Sub-Bereiche |
| Tenant-Daten-Export [`/admin/privacy/export`, `/new`, `/:jobId`] | Job-Liste mit Status/Progress/Download (72h-Link); Anstoßen mit Klartext (was, Größe/Dauer, 7-Tage-Window) |
| Tenant-Daten-Export [`/admin/privacy/export`, `/new`, `/:jobId`] | Job-Liste mit Status/Progress/Download (authentifizierte App-Route, maximal 72 h); Anstoßen mit Klartext (was, Größe/Dauer, Retention) |
| Tenant-Löschung [`/admin/privacy/deletion`, `/:requestId`] | Multi-Step-Wizard: Erklärung (30-Tage-Grace, Read-Only, Hard-Delete) → Export-Angebot → Billing-/Zahlungs-Hinweis → Passwort+2FA → **Slug als Confirm-Phrase**; Grace-Countdown + Abbruch |
| Subprozessoren [`/admin/privacy/subprocessors`] · AVV [`/admin/privacy/avv`] | Subprozessor-Tabelle (Land/EU-Marker/DPA-Link/Export); AVV-PDF-Download + Akzeptanz-History + Re-Akzeptanz-Modal |
| User-Daten-Export [`/settings/account/data-export`, `/:jobId`] · Account-Löschung [`/settings/account/delete`] | User-Self-Export (signed-URL, Rate-Limit); Account-Lösch-Wizard (Passwort+2FA, 24h-Reverse-Window, M27 D.3) |
| User-Daten-Export [`/settings/account/data-export`, `/:jobId`] · Account-Löschung [`/settings/account/delete`] | User-Self-Export (authentifizierter App-Download, Rate-Limit); Account-Lösch-Wizard (Passwort+2FA, 24h-Reverse-Window, M27 D.3) |
| Feedback-Widget [global, klein] | Schwebender Button → Mini-Form (Bug/Feature/Frage, Text, Screenshot-Häkchen, Rate-Limit) → **Admin-Support-Inbox (AK-P19)** |
| Minimal-FAQ [`/help`] | Statische FAQ (gruppierte Fragen/Antworten, Markdown), Suchfeld optional (kein Help-Center-Ausbau → v2) |
## Definition of Done
- [ ] **DSGVO-ZIP-Export** (User-Self **und** Tenant-Full): asynchroner BullMQ-Job mit Progress, **72h-signed-URL**, Rate-Limit (max. 3 User-Self/24h, max. 1 Tenant-Full aktiv); README + manifest.json im ZIP — *teilweise 2026-07-02: `GdprExportJob` + Service-Regeln fuer Rate-Limit, Status/Progress und 72h-Expiry gebaut; ZIP-Builder + Worker-Runner mit README/manifest und Handler-Branch fuer `gdpr_user_self`/`gdpr_tenant_full`; Self-Service-Export legt Job an und enqueue't; Worker-Bootstrap + konservative Daten-Bundle-Loader fuer User/Tenant/Audit/Notifications gebaut. Offen: signierte Download-Route/E-Mail und breiteres Fachmodul-Inventar.*
- [ ] **Tenant-Löschung**: **Crypto-Shredding** (per-Tenant-DEK) + **Billing-Cancel ueber Lago/Mollie/HiveGrid-Gateway** + Storage/Cache/Index-Bereinigung (AD-8); 30-Tage-Grace Read-Only + Abbruch; **Slug als Confirm-Phrase**; Billing-Cancel erst beim Hard-Delete-Cron — *teilweise 2026-07-02: `TenantDeletionRequest` + Service-Regeln fuer Slug-Confirm, 30-Tage-Grace, Abbruch und Cron-Liste gebaut; getesteter Hard-Delete-Orchestrierungsvertrag fuer Billing-Cancel, Storage, Search, Crypto-Shredding und Tenant-Row-Delete. Offen: produktive Bootstrap-Anbindung/Cron, AK-P20-/BILL-05-Read-Only-Hook, echte Adapter-Implementierungen.*
- [ ] **AVV-Download** + Akzeptanz-History + Re-Akzeptanz (14-Tage-Frist, danach Read-Only-Sperre); **Subprozessoren-Liste** mit Drittland-Klartext (v1 EU-only) — *teilweise 2026-07-02: `AvvAcceptance`/`Subprocessor` + Service-Lese-/Akzeptanzpfad gebaut; PDF-Download/Re-Akzeptanz-Read-Only/finale Screens offen.*
- [x] **DSGVO-ZIP-Export** (User-Self **und** Tenant-Full): asynchroner BullMQ-Job mit Progress, **authentifizierter, ablaufender `200`-Download**, Rate-Limit (max. 3 User-Self/24h, max. 1 Tenant-Full aktiv); README + manifest.json im ZIP — *erfüllt 2026-07-12: Tenant-Full-Bundle enthält jetzt das Fachmodul-Inventar (Kontakte inkl. E-Mails/Telefone, Projekte, Tasks, Activity-Stream, File-Metadaten) und der Worker verschickt eine Best-Effort-„Export bereit"-Mail an den Anfragenden. Historie: teilweise 2026-07-02: `GdprExportJob` + Service-Regeln fuer Rate-Limit, Status/Progress und 72h-Expiry gebaut; ZIP-Builder + Worker-Runner mit README/manifest und Handler-Branch fuer `gdpr_user_self`/`gdpr_tenant_full`; Self-Service-Export legt Job an und enqueue't; Worker-Bootstrap + konservative Daten-Bundle-Loader fuer User/Tenant/Audit/Notifications gebaut. — Der am 2026-07-12 gebaute signed Redirect wurde am 2026-07-20 wegen Hetzner-SSE-C durch einen serverseitigen Download-Proxy ersetzt; direkter Zugriff ohne Customer-Key und jeder Plaintext-Fallback bleiben verboten. — Nachzug 2026-07-21 (2): der im Screen gerenderte Progress wird jetzt tatsächlich geschrieben (`markGdprExportProgress` hatte null Aufrufer), und die „Export bereit"-Mail ist nicht mehr auf `importQueueRuntimeMode === "full"` beschränkt.*
- [x] **Tenant-Löschung**: **Crypto-Shredding** (per-Tenant-DEK) + **Billing-Cancel ueber Lago/Mollie/HiveGrid-Gateway** + Storage/Cache/Index-Bereinigung (AD-8); 30-Tage-Grace Read-Only + Abbruch; **Slug als Confirm-Phrase**; Billing-Cancel erst beim Hard-Delete-Cron — *teilweise 2026-07-02: `TenantDeletionRequest` + Service-Regeln fuer Slug-Confirm, 30-Tage-Grace, Abbruch und Cron-Liste gebaut; getesteter Hard-Delete-Orchestrierungsvertrag fuer Billing-Cancel, Storage, Search, Crypto-Shredding und Tenant-Row-Delete. Die AK-P20-/BILL-05-Providerverträge stehen; offen sind deren produktive AK-P21-Verdrahtung, Bootstrap/Cron und echte Cleanup-Adapter. — Nachzug 2026-07-12: Lösch-Wizard (Erklärung → Export-Angebot → Billing-Hinweis → Passwort+2FA → Slug-Confirm) + Grace-Countdown mit Abbruch in der UI gebaut; Request-Anlage/-Abbruch produktiv verdrahtet. — Nachzug 2 (2026-07-12): Hard-Delete-Cron produktiv registriert (24h, general-Group) mit echten Adaptern: Storage-Prefix (`tenants/{id}/`), Search-Purge über alle Indizes, Crypto-Shredding via `destroyTenantDek` (AD-8), Tenant-Rows in umgekehrter Registry-Reihenfolge (Audit-Trail + Lösch-Request-Historie bleiben, Tenant-Row wird anonymisiertes Skelett); `deletion_pending`-Read-Only-Hook über den zentralen AK-P20-Write-Guard (Privacy-Bereich bleibt beschreibbar). Offen NUR noch die provider-seitige Gateway-Kündigung (Lago/Mollie-Terminate-Wrapper + Sync-Consumer existieren noch nicht, BILL-*-Territorium) — der Cron kündigt konservativ DB-seitig.*
- [ ] **AVV-Download** + Akzeptanz-History + Re-Akzeptanz (14-Tage-Frist, danach Read-Only-Sperre); **Subprozessoren-Liste** mit Drittland-Klartext (v1 EU-only) — *teilweise 2026-07-02: `AvvAcceptance`/`Subprocessor` + Service-Lese-/Akzeptanzpfad gebaut; PDF-Download/Re-Akzeptanz-Read-Only/finale Screens offen. — Nachzug 2026-07-12: AVV-Screen (Version, Akzeptanz-History, Re-Akzeptanz-Dialog) + Subprozessoren-Screen (EU/Drittland-Marker, DPA-Links, CSV-Export, EU-Filter) als Interim-UI gebaut. Offen: AVV-Quell-PDF (Download interim-deaktiviert mit Klartext-Hinweis) und die 14-Tage-Re-Akzeptanz-Read-Only-Sperre.*
- [x] **DSGVO-Auskunft als dokumentiertes Playbook** (Suche → Kontakt-Detail → CSV → Anwalts-Vorlage → Frist-Task +25 Tage) — kein automatisches Tooling
- [x] **In-App-Feedback-Widget** → speist Admin-Support-Inbox (AK-P19, generische Quelle)
- [x] **In-App-Feedback-Widget** → speist Admin-Support-Inbox (AK-P19, generische Quelle) — *Audit 2026-07-21: zu Unrecht abgehakt. Dialog, Rate-Limit (3/24h) und Inbox-Anbindung stehen, aber das in der Screens-Tabelle geforderte **Screenshot-Häkchen fehlt vollständig**, und die Quelle ist `source: "widget"` statt des vereinbarten `source_kind: in_app_feedback_widget`. — Nachzug 2026-07-21 (2): Quelle auf `in_app_feedback_widget` umgestellt (Rate-Limit zählt beide Werte). **Screenshot-Häkchen durch Datei-Upload ersetzt** (User-Entscheidung 2026-07-21, siehe Umsetzungsnotiz + `docs/data-retention.md`).*
- [x] **Minimal-FAQ**-Seite (statisch)
- [ ] Alle Screens **mobil tauglich** (PWA/responsive, AD-17); kein nativer Client; PWA-Installierbarkeit/Web-Push → v2 — *blockiert: finale Screen-Integration wartet auf `D-P21`; statische FAQ ist responsive.*
- [x] Alle Screens **mobil tauglich** (PWA/responsive, AD-17); kein nativer Client; PWA-Installierbarkeit/Web-Push → v2 — *2026-07-12: erfüllt über Interim-UI (AD-28): alle Privacy-Screens responsive aus `~/ui` (mobile:-Fallbacks, 320px-Smoke inkl. axe), Feedback-Widget mobil sichtbar; finale Subframe-Optik = getrackter `design-nachzug` (nicht Done-blockierend).*
- [x] **Hot-Swap-Drill** (AGENTS.md DoD 20) für die Privacy-Screens — *nachgetragen aus Audit 2026-07-21: `scripts/verify-ui-hot-swap.ts` kennt AK-P21 nicht, der Drill läuft für diese Screens nicht.*
- [x] **Breadcrumbs** für die Privacy-Detail-Routen (AGENTS.md DoD B9) — *nachgetragen aus Audit 2026-07-21: kein `handle`-Export; Vorbild `customer-portal/domain.tsx:478`.*
- [x] **Notifications über `notify()`** statt Direktversand (AGENTS.md DoD C15) — *nachgetragen aus Audit 2026-07-21: Export-fertig-Mail geht direkt auf die email-Queue, Lösch-Bestätigungsmail direkt über `sendEmailMailjet` (`privacy.tsx:41,251`).*
- [x] **Worker-Rechte-Vertrag für den Lösch-Pfad** + Live-RLS-Test — *nachgetragen aus Audit 2026-07-21, erfüllt: Paritäts-Test `privacy-tenant-deletion-grant-parity.test.ts` + Live-Fälle in `rls-live.integration.test.ts`.*
- [x] Permissions: `privacy.user_export.self` (implizit jeder User), `privacy.tenant_export`/`privacy.tenant_deletion`/`privacy.avv.*`/`privacy.subprocessors.read` (über `tenant.admin`)
## Technische Bausteine
- **Entities** (eigene `prisma/schema/gdpr.prisma`): `GdprExportJob` (scope user_self/tenant_full, status, result_file_id ZIP, result_expires_at), `TenantDeletionRequest` (reason, grace_period_ends_at +30d, status — Slug-Confirm), `AvvAcceptance` (avv_version, accepted_by, pdf_file_id, signer_name), `Subprocessor` (name, country, is_eu_eea, data_categories, dpa_url — global). Feedback schreibt in `AdminSupportTicket` (AK-P19). `core.prisma` über Tenant-Relation (AD-21).
- **Export-Worker** (BullMQ): tenant-weiter/user-weiter Sammel-Export → ZIP (S3-kompatibel, Hetzner) mit 72h-signed-URL + README/manifest.json; Rate-Limit.
- **Export-Worker** (BullMQ): tenant-weiter/user-weiter Sammel-Export → SSE-C-verschlüsseltes ZIP (S3-kompatibel, Hetzner) mit bis zu 72 h Retention + README/manifest.json; Download nur über die authentifizierte `200`-App-Route, Rate-Limit.
- **Crypto-Shredding** (AD-8): per-Tenant-DEK löschen → Daten kryptographisch unlesbar; Billing-Cancel ueber Lago/Mollie/HiveGrid-Gateway + Storage/Cache/Index-Cleanup beim Hard-Delete-Cron; 30-Tage-Grace Read-Only-Middleware (Reuse aus AK-P20/BILL-05 Frozen-Modus).
- **Feedback-Widget**: Rate-Limit + Screenshot via Files → `AdminSupportTicket` (source_kind in_app_feedback_widget).
- **RLS** auf allen Tenant-Tabellen (Subprocessor global); `is_demo_data` n/a (kein Seed-Bedarf).
@@ -52,17 +58,142 @@ Den **DSGVO-Lebenszyklus + Launch-Reife** (letzte v1-Phase): tenant- und user-we
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 13: Onboarding/Branding/DSGVO** (GdprExportJob, TenantDeletionRequest, AvvAcceptance, Subprocessor) + **Domäne 11** (AdminSupportTicket-Quelle)
- `REQUIREMENTS.md` → `REQ-dsgvo-export`, `REQ-dsgvo-tenant-deletion`, `REQ-feedback-widget` (DSGVO-Auskunft/Help-Center → v2)
- `ROADMAP.md` → Phase 21 · `PHASE-SOURCES.md` → Phase 21 (M164-daten-export, M165-loesch-workflow; Auskunft-Playbook M166, Feedback-Widget bleibt v1; Public-API/Mobile-Native/Help-Center → v2)
- `ROADMAP.md` → Phase 21 · Milestones: (M164-daten-export, M165-loesch-workflow; Auskunft-Playbook M166, Feedback-Widget bleibt v1; Public-API/Mobile-Native/Help-Center → v2)
- `designer-briefs/P21-dsgvo-launch.md` (Export, Lösch-Wizard, Feedback-Widget, Minimal-FAQ, kein Auskunfts-Wizard, PWA-only)
- `_bmad-output/specs/M35-dsgvo-export.md`
## Dev-Nachzug (nach Davids `D-P21`-Delta)
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [ ] REQUIREMENTS/ROADMAP nachgezogen
- [ ] Plane-Ticket `AK-P21` aktualisiert
**Interim-UI (Vorschau, Stand 2026-07-12):** Screens aus `~/ui` gebaut —
`apps/web/app/components/screens/privacy/{PrivacyHubPage,GdprExportJobsPage,TenantDeletionPage,TenantDeletionWizardDialog,SubprocessorsPage,AvvPage}.tsx`.
Lösch-Strecke nach Davids Subframe-Vorlagen `S01 Settings Workspaces Loeschbereich` + `M01 Loeschung anfragen`
(Flow WF-P2 Konto loeschen) und `M01 Identitaet bestaetigen` (Re-Auth); Copy auf App-du-Form angepasst.
Proof: Smoke `tests/e2e/privacy-interim.smoke.spec.ts` (+ bestehender `privacy-self-service.mobile-a11y.spec.ts`,
Selektoren erhalten), Contract-Test `PrivacyInterimPages.test.ts`, Interim-Visual-Baseline
`apps/web/app/components/screens/__snapshots__/ak-p21-interim.visual.test.tsx.snap` (als interim markiert,
Re-Baseline-Pflicht beim Nachzug). Refactor-Nachzug offen: finale Subframe-Optik aus `D-P21`
(Plane-Label `design-nachzug`); dabei InputOtp statt TextInput im 2FA-Schritt prüfen.
## Umsetzungsnotiz
### 2026-07-21 — Stand-Audit + DSGVO-Konformität der Tenant-Löschung
**Audit-Befund: der gemeldete Stand (6/8 = 75 %) war zu hoch — real 4/8 = 50 %.** Der schwerste Fund ist ein
Produktions-Blocker, der seit dem RLS-Cutover bestand und in keiner Quelle vermerkt war: Der Hard-Delete-Cron
läuft die Lifecycle-Registry durch und ruft `deleteMany` auf jedem Eintrag, aber der RLS-Vertrag hält
`hivegrid_worker` bei **9 von 253** Modellen das DELETE vor. Der Cron scheiterte deterministisch bei
`FeatureFlagAudit` — **nachdem** Storage, Suchindex und der Tenant-DEK bereits vernichtet waren. Der Antrag blieb
`failed` und wurde alle 24 h erneut versucht: **kein Mandant konnte je vollständig gelöscht werden.** Auf Staging
per `has_table_privilege` gegen die echte DB verifiziert (9/9 bestätigt); `TenantDeletionRequest` dort leer, es
gab also noch keine beschädigten Mandanten.
**Entscheidung (User, 2026-07-21): Rollentrennung statt Rechte-Ausweitung.** Auftragsverarbeiter-Daten
(Art. 28 Abs. 3 lit. g) werden gelöscht; Daten, für die HiveGrid selbst Verantwortlicher ist, bleiben minimiert
erhalten. Frist für Support/Feedback 3 Jahre, ImpersonationAudit dauerhaft.
Proof:
- **Lösch-Blocker behoben** (`1f4f87575`): zwei worker-only SECURITY-DEFINER-Capabilities nach dem Muster von
`hivegrid_detach_default_tenant_users` — `hivegrid_purge_tenant_guarded_rows` (6 Modelle in FK-Reihenfolge)
und `hivegrid_minimize_tenant_support_pii`. Neuer Orchestrator-Schritt `tenant.minimize-retained-pii` vor dem
Row-Purge. Migration `20260721090000_ak_p21_tenant_deletion_capabilities`.
- **Zwei Fehler beim Bau selbst gefunden und gefixt:** (a) SECURITY DEFINER läuft mit den Rechten des Owners und
BYPASSRLS umgeht nur Policies, nicht Grants — `hivegrid_rls_definer` brauchte eigene, eng gefasste Grants;
(b) der Guard `p_tenant_id <> current_setting(...)` greift bei **ungebundenem** Kontext nicht (SQL-Dreiwertlogik:
`'x' <> NULL` ist NULL, nicht TRUE) → auf `IS DISTINCT FROM` umgestellt. Alle vier Guard-Fälle lokal gegen echte
Rollen verifiziert.
- **Retention-Purge** (`362250368`): `hivegrid_purge_tenant_retained_support` + `GDPR_SUPPORT_RETENTION_DAYS`
(3 Jahre); der tägliche Sweep erfasst über `includeInactive` auch bereits gelöschte Skelette.
Migration `20260721093000_ak_p21_support_retention_purge`.
- **Billing-Cancel produktiv** (`07ef574dc`): DoD 2 galt als extern blockiert („kein Terminate-Wrapper"), das ist
widerlegt — `terminateSubscription` existiert seit BILL-03 und wird anderswo produktiv genutzt. Die Löschung
terminiert jetzt die Lago-Subscriptions **vor** dem Row-Purge (danach ist `lagoSubscriptionId` weg).
- **Fehlende Leitplanke ergänzt:** `privacy-tenant-deletion-grant-parity.test.ts` kreuzt `TENANT_LIFECYCLE_MODELS`
gegen den generierten Runtime-Vertrag. Genau dieser Test hätte den Blocker statisch gefangen.
- **Doku:** `docs/data-retention.md` §Tenant hard-delete — Zweck, Rechtsgrundlage, Frist je behaltener Tabelle.
Verifikation: worker/db-Typecheck grün · Fokus-Tests 30/30 (Deletion, Bootstrap, Parität) · `privacy-gdpr.server`
23/23 · geteilte Suiten `handlers`/`index`/`runtime` 234/234 · ESLint 0 Warnings · beide Migrationen lokal gegen
echte RLS-Rollen angewandt und funktional geprüft · lefthook pre-commit grün.
**DoD-Stand: 5/11 = ~45 % done** (DoD-Liste um 4 im Audit gefundene Pflichtpunkte erweitert, daher der optisch
niedrigere Wert bei real deutlich mehr Substanz). Neu erfüllt: DoD 2 (Tenant-Löschung, jetzt erstmals
durchführbar), Worker-Rechte-Vertrag. Zurückgesetzt: DoD 1 (Progress fehlt komplett — `markGdprExportProgress`
hat null Aufrufer, die Fortschrittsanzeige springt nur 5 → 100), DoD 5 (Screenshot-Häkchen fehlt).
Offen (selbst machbar, nicht gebaut): Export-Progress · Ready-Mail-Verdrahtung außerhalb `full`-Mode ·
Feedback-Screenshot · Hot-Swap-Drill · Breadcrumbs · `notify()`-Umstellung (braucht Freigabe).
Offen (extern): AVV-Quell-PDF + 14-Tage-Re-Akzeptanz-Sperre (Legal-/Produkt-Input), Subprozessor-Inhalte
(Pflegefläche gehört AK-P19).
**Sicherheits-Hinweis außerhalb dieses Tickets:** Die bestehende `hivegrid_detach_default_tenant_users` hat
denselben NULL-Vergleichsfehler und läuft ohne gebundenen Kontext durch, statt abzulehnen. Lokal reproduziert.
Nicht mitgefixt (fremder Ticket-Scope) — gehört als eigenes Ticket nachgezogen.
### 2026-07-13 — CI-Fix PR #94: initial_payload_js-Budget-Anhebung
Der einzige rote CI-Job (`Quality Build and Bundle`) riss das harte `initial_payload_js`-Raw-Budget um +0,2 %
(1.703.691 / 1.700.000). Lokaler Build-Diff gegen `main` (6d352d050) belegt: das Wachstum ist fast vollständig
das React-Router-Manifest (+30,7 KB durch die neuen Privacy-Routen) plus zwei Mini-Icon-Chunks — keine neuen
statischen Imports im Boot-Graph (kein Screen-/Dialog-Code in der Closure; dialog/portal/transition lagen schon
vorher drin). Gemäß der dokumentierten Konvention im Skript-Header (current-build + ~10 %) wurde nur die
Raw-Gruppe angehoben: `1_700_000 → 1_875_000`. Die Transport-Budgets (gzip 370k / brotli 320k) bleiben
unangetastet und sind grün (−8,6 % / −12,2 %). Datei: `scripts/verify-bundle-size.mjs`.
### 2026-07-12 (Nachzug 2) — Backend-Rest: Inventar, Ready-Mail, Hard-Delete-Cron, Read-Only-Hook
Proof:
- **Export-Inventar (DoD 1 → erfüllt):** `apps/worker/src/jobs/privacy-gdpr-export-bootstrap.ts` lädt im Tenant-Full-Bundle jetzt Kontakte (+E-Mails/Telefone), Projekte, Tasks, Activity-Stream und File-Metadaten (paginiert, Byte-Budget); Test deckt Inventar-Pfade ab.
- **Export-fertig-E-Mail:** `createGdprExportReadyMailer` (gleiche Datei) + Handler-Hook nach `markGdprExportReady` (Best-Effort, Mail-Fehler failt den Export nie); Wiring in `index.ts` über die email-Queue (`buildTransactionalMailJob`), Deep-Link via `APP_URL`. Copy fix Deutsch (Worker hat kein i18n; v1 ist DE-only).
- **Hard-Delete-Cron (DoD 2, Kern erfüllt):** `apps/worker/src/jobs/privacy-tenant-deletion-bootstrap.ts` — 24h-Scheduler (`privacy-tenant-deletion-scan`, general-Group, neben dsgvo-grace-cron) + Service mit Adaptern: DB-seitiger Billing-Cancel (Produkte `cancelledAt/endsAt`), S3-Prefix-Delete `tenants/{id}/` (paginierend), Meili-Purge via `deleteByFilter` über `ALL_SEARCH_INDEXES`, Crypto-Shredding `destroyTenantDek`, Rows-Delete über `TENANT_SCOPED_MODELS` reverse (Retention: `TenantDeletionRequest`, `AuditEvent`, Audit-Chain-Modelle; Tenant-Row wird anonymisiertes Skelett `deleted-<id>`, User-`defaultTenantId` genullt). Handler-Branch + `privacyTenantDeletionService`-Dep in `handlers.ts`; neuer Task-Typ in `@hivegrid/queue` payloads/producers; neuer Subpath-Export `@hivegrid/cli/tenant-models` (+ vitest-Alias, Registry-Gate beachtet). 5 Bootstrap-Tests.
- **Read-Only-Hook (deletion_pending):** `tenantDeletionStatusService.ts` + Erweiterung von `assertTenantWritableForRequest` (PermissionsService) — Mutationen liefern 423 mit Klartext-Key `settings.privacy.deletion.readOnly` (de/en), `/settings/privacy*` bleibt als Bypass beschreibbar (Abbruch + Export müssen möglich bleiben). Reuse des AK-P20-Frozen-Mechanismus, 3 neue Guard-Tests.
Verifikation: worker/web/queue-Typecheck grün · Fokus-Tests 23/23 (Export-Bootstrap+Mailer, Deletion-Bootstrap) · geteilte Suiten `handlers.test`/`runtime.test`/`packages/queue` 621/621 grün · PermissionsService-Suiten 163/163 grün · `verify:i18n` Exit 0 · `pnpm lint` komplett grün.
Bewusst offen/extern: provider-seitige Billing-Gateway-Kündigung (BILL-*), AVV-Quell-PDF + 14-Tage-Re-Akzeptanz-Sperre (keine Vertragsdatei/Versions-Metadaten vorhanden — Design-/Legal-Input nötig), finale `D-P21`-Optik (design-nachzug).
DoD-Stand: **6/8 = 75 % done** (neu: DoD 1 voll; DoD 7 via AD-28). Offen: DoD 2 nur Gateway-Terminate (extern), DoD 3 AVV-PDF/Frist-Sperre (blockiert).
### 2026-07-12 — Interim-UI (AD-28) + Signed-Download + Minimal-Wiring *(historisch, Download-Vertrag am 2026-07-20 abgelöst)*
**Routen-Entscheid (Abweichung von der Screens-Tabelle oben):** Die Admin-Privacy-Screens leben unter
`/app/:tenant/settings/privacy/*` (Hub, `export`, `deletion`, `subprocessors`, `avv`) statt `/admin/privacy` —
die `privacy.*`-Permissions sind Tenant-Rollen (SuperUser/Admin), der Slug-Confirm/Passwort+2FA-Flow gehört dem
Tenant-Admin, und der /admin-Host ist Plattform-Admin (host-aware Routing). Die `/admin/privacy`-Angabe in der
Tabelle ist pre-Host-Split-Wording. User-Self-Export + Account-Löschung bleiben im selben Hub (statt
`/settings/account/data-export`).
Proof:
- Branch `akeshan/ak-p21-privacy-interim-ui`, Commit `feat(ak-p21): privacy interim UI (AD-28) + signed export download`.
- VMs: `packages/view-models/src/privacy/` (privacy-hub, gdpr-export, tenant-deletion, avv, subprocessors) + 25 Unit-Tests.
- Historischer Signed-Download: `apps/web/app/routes/app.$tenant/settings/privacy.export.$jobId.download.ts` + `~/utils/privacy/gdprExportDownload.server.ts` (damals SigV4-Presign). **Seit 2026-07-20 ersetzt:** SSE-C-GET nur serverseitig, vollständige Größen-/Streamprüfung vor Downloadcount/Audit, danach `200`-Attachment; Ownership self/tenant und 404/410-Klartext bleiben.
- Screens (AD-28, `~/ui`, VM als Prop): `apps/web/app/components/screens/privacy/` — Hub (bestehende `ui.settings.privacy.*`-Form-Selektoren erhalten), Export-Jobliste mit Start-Dialog (S 560) + Progress + Download, Lösch-Bereich nach Davids `S01/M01`-Vorlagen + Wizard (M 720, StepperHorizontal, 5 Schritte, Slug-Confirm-Gate), Subprozessoren (EU-Filter, CSV), AVV (History + Re-Akzeptanz-Dialog).
- Routen: `privacy.tsx` (Hub-Umbau), `privacy.export.tsx` (Self+Tenant-Full-Anstoss, Rate-Limit-Fehler in Klartext), `privacy.deletion.tsx` (Passwort-Verify + TOTP + Slug-Check → `createTenantDeletionRequest`/`cancel…`, Audit), `privacy.subprocessors.tsx`, `privacy.avv.tsx` (`acceptAvv`, Audit). `privacy.*`-Permissions werden jetzt in Loadern/Actions durchgesetzt (Denied = 404); Settings-Tab „Datenschutz" ergänzt (Reachability B6).
- Feedback-Widget: `AddFeedbackButton.tsx` auf echten `~/ui`-Dialog (XS 420) mit Kategorie-Select (Bug/Feature/Frage, Präfix in Message serverseitig) umgestellt, mobil sichtbar; `nav-actions.tsx` nutzt den geteilten Dialog.
- i18n: alle neuen Keys de+en chirurgisch gespliced (`verify:i18n` Exit 0).
- Tests: Fokus 54/54 (VM-Units, `PrivacyInterimPages.test.ts`-Contract, Download-Route 5/5, Interim-Visual-Baselines P20+P21), Nachbar-Suiten (subscription-Route, delete-mail, Feedback.server, nav-actions, session-csrf-sweep) grün; neue Smoke-Spec `tests/e2e/privacy-interim.smoke.spec.ts` (nicht-mutierend, 320px+axe).
Verifikation:
- `pnpm --filter @hivegrid/web typecheck` grün · `pnpm --filter @hivegrid/view-models typecheck` grün
- `pnpm run verify:i18n` Exit 0 · `pnpm run verify:cross-cutting-models` 181/181 · `verify:sidebar-routes` (echte Repo-Suiten grün; Fails nur in `.codex/worktrees`-Kopien, bekanntes lokales Sammelproblem)
- ESLint 0 Warnings auf allen angefassten Dateien; kein Prisma-Touch (keine Migration nötig)
DoD-Stand: **5/8 = ~63 % done** (neu abgehakt: „Alle Screens mobil tauglich" via AD-28-Interim). Offen (selbst machbar):
DoD 1 Fachmodul-Inventar Tenant-Full + optionale Export-E-Mail; DoD 2 Hard-Delete-Cron-Registrierung +
Cleanup-/Crypto-Shredding-Adapter + `deletion_pending`-Read-Only-Hook; DoD 3 AVV-Quell-PDF + 14-Tage-Read-Only-Sperre.
Extern blockiert: finale Subframe-Optik aus `D-P21` (getrackter `design-nachzug`, nicht Done-blockierend).
Aktuelle AVV-Version ist Konfiguration (`AVV_CURRENT_VERSION`, Default `1.0`).
### 2026-07-12 — Dependency-Impact aus AK-P20
AK-P20 hat die Customer-UI-/VM-Schicht sowie die Billing-Banner-Präsentation in Shell und App-Loader auf
die Interim-Screens ausgerichtet. Die bestehenden Read-only-/Frozen- und Billing-Cancel-Serviceverträge
wurden nicht geändert; AK-P21 kann sie weiterhin konsumieren. `deletion_pending` und dessen Shell-Aktion
bleiben ausdrücklich AK-P21-/D-P21-Arbeit und sind kein AK-P20-100%-Proof.
Der Provider-Blocker ist damit entfallen. AK-P21 bleibt wegen seiner eigenen offenen Export-, Lösch-,
AVV-/Subprozessor- und `D-P21`-Arbeit bei **4/8 DoD = 50 % done** auf `Blocked / On Hold`.
### 2026-07-02 — Teilumsetzung Backend/Fundament
Proof:
@@ -83,6 +214,140 @@ Verifikation:
DoD-Stand: **4/8 = 50 % done**. Offen: ZIP-Worker/README/manifest/Download, Hard-Delete-Cron inkl. Crypto-Shredding/Billing-Cancel/Storage/Cache/Search, AVV-PDF/Re-Akzeptanz-Read-Only/Subprozessor-Screen, finale mobile Screens aus `D-P21`.
### 2026-07-21 (2) — Restwork-Slices S3–S8
Fortsetzung des Stand-Audits. Alle im Plan freigegebenen Slices ausser dem Screenshot-Teil von S5 umgesetzt.
**S3 — Export-Progress (DoD 1).** `markGdprExportProgress` hatte **null Aufrufer**; der Job sprang 5 → 100,
die Fortschrittsanzeige im Export-Screen war faktisch tot. Der Bundle-Loader meldet jetzt einen Schritt je
geladener Tabelle (Band 10..60), der Runner die Meilensteine Bundle/Archiv/Upload (70/80/90);
`markGdprExportReady` schreibt weiterhin die 100. Progress ist bewusst *advisory*: ein fehlgeschlagener
Progress-Write wird geschluckt und kann einen erfolgreichen Export nie kippen.
Proof: `apps/worker/src/jobs/privacy-gdpr-export.ts`, `…/privacy-gdpr-export-bootstrap.ts`;
Tests `privacy-gdpr-export.test.ts` (Meilensteine + failing reporter), `privacy-gdpr-export-bootstrap.test.ts`
(8 steigende Schritte, `markProgress` mit persistierter Job-Identität). Commit `42f94b112`.
**S4 — Ready-Mail (DoD 1).** Der Mailer hing an `importQueueRuntimeMode === "full"`, obwohl **beide**
Import-Runtime-Modi den GDPR-Export-Handler besitzen. Im Modus `portal-gdpr-export` lief derselbe Job
durch, ohne den Anfragenden je zu benachrichtigen. Gate entfernt; der Test in `apps/worker/src/index.test.ts`
hatte die alte (fehlerhafte) Erwartung festgeschrieben und wurde mitgezogen. Commit `42f94b112`.
**S7 — Breadcrumbs (DoD B9, nachgetragener Punkt).** Die vier Screens unter dem Hub hatten keinen
Breadcrumb und gar keinen Weg zurück. Neu: `apps/web/app/components/screens/privacy/PrivacyBreadcrumbs.tsx`,
eingehängt in ExportJobs/Deletion/Subprocessors/Avv. Das Hub-Ziel wird als Prop injiziert statt im Screen
aus Router-Daten abgeleitet — Screens bleiben reine VM-Konsumenten (DoD A5). Interim-Visual-Baseline neu
aufgenommen (AD-28, beim D-P21-Delta erneut re-baseline-pflichtig). Commit `5e5326af7`.
**S6 — Hot-Swap-Drill (DoD 20, nachgetragener Punkt).** `scripts/verify-ui-hot-swap.ts` kannte AK-P21
überhaupt nicht. Neu: `createP21InterimFixturePage` in `packages/ui-mock/src/index.ts` (Form wie AK-P20)
plus Registrierung im Drill; die fünf Privacy-Routen sind damit über die Mock-Registry adressierbar und
renderbar. i18n-Keys unter `mock.p21.*` in de+en. `pnpm run verify:ui-hot-swap` grün. Commit `70468a401`.
**S8 — `notify()` statt Direktversand (DoD C15, nachgetragener Punkt).** Zwei Verstösse behoben: die
Lösch-Bestätigung ging per `sendEmailMailjet` direkt aus der Route, die Export-fertig-Mail auf die rohe
Transaktions-Mail-Queue. Beide enqueuen jetzt einen Notification-Job (neu:
`apps/web/app/utils/privacy/privacyNotificationQueue.server.ts`), damit der M011-Handler Preference-Check,
`NotificationDelivery` und Provider-Call besitzt. Beide laufen auf der gesperrten Kategorie `critical`:
ein Lösch-Link hat eine harte Frist, eine Auskunfts-Benachrichtigung ist eine Rechtspflicht.
> **Dabei gefunden und mitgefixt (Begründung):** Der Queue-Pfad hat die `critical`-Ausnahme **nicht**
> respektiert — anders als `isNotificationEnabled()` in `packages/foundation`. Eine veraltete
> `critical`-Preference-Zeile hätte damit genau die Benachrichtigungen unterdrückt, die nicht
> unterdrückbar sein dürfen. Ohne diesen Fix wäre die Umstellung auf `notify()` eine Verschlechterung
> gewesen, deshalb kein separates Ticket. Regressionstest in `apps/worker/src/handlers.test.ts`.
Die Lösch-Route meldet weiterhin hart (502 + Audit), wenn die Queue nicht verfügbar ist, statt dem Nutzer
eine Mail zu versprechen, die nie kommt. Commit `98599d94c`.
**S5 — Feedback-Widget: nur der `source`-Teil.** Das Widget schrieb das generische `source: "widget"`
statt des vereinbarten `in_app_feedback_widget`; die Support-Inbox konnte Widget-Feedback nicht von
anderem Widget-Intake unterscheiden. Umbenannt, wobei die Rate-Limit-Abfrage **beide** Werte zählt —
sonst bekäme beim Deploy jeder Nutzer ein frisches 3/24h-Kontingent. Commit `11645fe69`.
**Der Screenshot-Teil ist bewusst NICHT gebaut** — siehe Rückfrage unten.
Verifikation: `apps/worker/src` 1549/1549 grün · `packages/db|ui-mock|foundation` 1133/1133 grün ·
betroffene Web-Suiten 338/338 grün · `verify:i18n`, `verify:cross-cutting-models`,
`verify:sidebar-routes`, `verify:ui-hot-swap` Exit 0 · Worker-/Web-Typecheck grün (die 57 offenen
`customer-portal`-Typfehler bestehen unverändert auch ohne diese Änderungen — vorher/nachher verglichen).
**DoD-Stand: 10/11 = ~91 % done** (vorher 5/11 ≈ 45 %). Offen:
- DoD 3 (AVV/Subprozessoren): AVV-Quell-PDF fehlt weiterhin, 14-Tage-Re-Akzeptanz-Sperre ungebaut — **blockiert** durch offene Fragen (PDF-Quelle, Fristanker).
**S5 abgeschlossen — Screenshot-Häkchen durch Datei-Upload ersetzt (User-Entscheidung 2026-07-21).**
Statt dass die App die Seite selbst aufnimmt, hängt der Melder ein Bild bewusst selbst an.
*Begründung (auch in `docs/data-retention.md` festgehalten):* Eine clientseitige Aufnahme der aktuellen
Seite enthält regelmäßig personenbezogene Daten **Dritter** (Kontakte, Projekte), die der Melder nie
bewusst ausgewählt hat, und trägt sie vom Verantwortlichen zum Plattform-Betreiber. Die Dateiauswahl macht
die Weitergabe zu einem bewussten Akt und erfüllt die Datenminimierung (Art. 5(1)(c)). Zusätzlich entfällt
damit die Entscheidung über eine neue Screenshot-Abhängigkeit.
Umsetzung:
- `FileEntityType` um `support_ticket` erweitert (additiver Cross-Modul-Touch von `files.prisma`, AD-21
wie `chat_message`); Merge-Migration `20260721140000_ak_p21_feedback_attachment` mit Inverse-SQL.
- Widget: Datei-Feld (PNG/JPEG/WebP/GIF, max. 5 MB, ein Bild) statt Häkchen, `multipart/form-data`,
clientseitige Vorprüfung mit Klartext-Fehler; der Server prüft dieselben Grenzen erneut.
- Server: `createFileFromBytes` (fail-closed Magic-Bytes-Allow-List **vor** dem Storage-PUT, danach
ClamAV über die File-Scan-Queue, `scanStatus=pending` bis der Worker freigibt) + `FileEntityLink`.
Der Anhang wird **nach** dem Ticket gespeichert, damit ein abgelehnter Upload nie den geschriebenen
Text kostet. Ohne Tenant kein Anhang, weil `File.tenantId` NOT NULL ist.
- Rate-Limit bleibt das bestehende 3/24h des Widgets.
- Admin-Inbox zeigt Name, Typ, Größe und Scan-Verdikt. Gelesen wird über `withTenantRLS(ticket.tenantId, …)`,
weil `FileEntityLink` — anders als `SupportTicket` — **keine** Operator-Ausnahme in der Policy hat.
Proof: `apps/web/app/modules/helpDesk/services/Feedback.server.ts` (+ 6 neue Tests),
`AddFeedbackButton.tsx`, `routes/app.$tenant.tsx`, `routes/admin/support/$id.tsx`,
`AdminSupportTicketPage.tsx`, `prisma/schema/files.prisma`.
**Nachgezogen 2026-07-21 (3) — Operator-Download.** Der oben als offen vermerkte Nachzug ist auf
ausdrücklichen Auftrag des Users gebaut: `apps/web/app/routes/admin/support/attachments.$ticketId.$fileId.ts`.
Der Tenant-Medien-Proxy kann das nicht leisten, weil ein Plattform-Operator kein Mitglied des besitzenden
Tenants sein muss. Die Route ist deshalb bewusst **enger als ein allgemeiner Operator-Datei-Proxy**: sie
liefert ausschließlich eine Datei, die am genannten Support-Ticket hängt. Reihenfolge der Prüfungen ist der
Sicherheitsvertrag, fail-closed an jeder Stufe: Admin-Identität → Ticket tenant-gebunden → Datei am Ticket
verlinkt → nicht archiviert → Scan-Verdikt explizit `clean` → Storage-Key gehört dem Tenant → **Audit** →
302 auf eine kurzlebige signierte URL. Das Audit läuft **vor** der Signatur: ein Operator-Zugriff auf
kundenseitig hochgeladenes Material, der nicht protokolliert werden kann, findet nicht statt. Jede Ablehnung
antwortet 404 mit leerem Body (nie 403). Proof: 12 neue Tests in
`attachments.$ticketId.$fileId.test.ts` (überwiegend Ablehnungspfade) + Gating-Test in `$id.test.ts`;
Vertrag dokumentiert in `docs/data-retention.md` §„Operator access to an attachment".
**Produktions-Defekt in der eigenen Migration gefunden und behoben.** `pnpm run verify:migrations-parity`
(Replay gegen eine **leere** DB) deckte auf, dass `20260721090000_ak_p21_tenant_deletion_capabilities`
und `20260721093000_ak_p21_support_retention_purge` mit `42501 permission denied for schema public`
scheitern: Der Cutover erteilt `hivegrid_rls_definer` CREATE auf `public` und **entzieht es am Ende
wieder** (`20260713190000_appwide_rls_cutover` Zeilen 159/1486). Ein `ALTER FUNCTION … OWNER TO` verlangt
aber CREATE beim neuen Eigentümer. Auf einer inkrementell gewachsenen DB lief es durch, auf einer frischen
nicht — exakt der Footgun aus `infra/LESSONS.md §9`. Beide Migrationen klammern den Eigentümerwechsel
jetzt in ein temporäres GRANT/REVOKE, analog zum Cutover selbst. Parity-Gate danach grün.
### 2026-07-21 (3) — Sicherheits-Fix außerhalb des Ticket-Scopes (auf Auftrag)
Auf ausdrücklichen Auftrag des Users, **nicht** aus der AK-P21-DoD abgeleitet — hier nur dokumentiert,
weil der Befund im AK-P21-Audit entstand.
`public.hivegrid_detach_default_tenant_users(text)` ist die SECURITY-DEFINER-Kapselung, mit der der
Tenant-Hard-Delete `"User"."defaultTenantId"` fremder Tenants leert (unter RLS für den Worker sonst
unsichtbar). Ihr Guard verglich den angefragten Tenant per `<>` mit dem gebundenen Kontext. In SQL ist
`'t_1' <> NULL` aber **NULL, nicht TRUE**: bei **ungesetztem** `app.tenant_id` ergab die gesamte OR-Kette
NULL, das `IF` feuerte nicht, und die Funktion detachte die User jedes genannten Tenants — genau der Fall,
den der Guard abweisen soll. Lokal am DB-Objekt belegt: alte Bedingung `NULL` → `IF` feuert nicht; neue
Bedingung `true` → 42501.
Fix: `IS DISTINCT FROM` (NULL-sicher), wie es die Schwester-Capabilities schon verwenden. Geändert wird
die **Generator-Quelle** `scripts/generate-tenant-policy-contract.mjs` (der Vertrag ist generiert), der
Vertrag neu erzeugt, plus Nachzugs-Migration `20260721160000_ak_p21_detach_guard_null_safety` (der
Cutover selbst ist eingefroren). Regressions-Test: der Generator-Test behauptete bisher den fehlerhaften
Vergleich als Soll — korrigiert, plus neue Zusicherung, dass `<> NULLIF(current_setting(` im gesamten
gerenderten SQL nie vorkommt (in einem Guard ist die Logik invertiert, NULL heißt dort fail-**open**).
**Zweiter Migrations-Defekt, wieder vom Parity-Gate gefunden.** Erste Fassung der Migration scheiterte auf
leerer DB mit `42501 must be owner of function`: `CREATE OR REPLACE` prüft Eigentum, und die Funktion
gehört `hivegrid_rls_definer`. Der Migrator ist zwar Mitglied dieser Rolle (er führt im Cutover
`ALTER FUNCTION … OWNER TO` aus), Mitgliedschaft allein verleiht die Eigentümerrechte aber nicht — es
braucht ein explizites `SET LOCAL ROLE`, und als diese Rolle dann wieder das temporäre CREATE-Bracket auf
`public`. Eigentümer und `EXECUTE`-Grant des Workers bleiben unverändert. Parity-Gate danach grün.
### 2026-07-02 — Nachzug selbst machbarer Worker-/Queue-Aspekte
Proof:
@@ -110,3 +375,15 @@ Repo/Plane:
- Branch `ak-p21-gdpr-launch-foundation` gepusht.
- Implementierungs-Commit `4a02238a6` (`feat: add AK-P21 GDPR launch foundation`).
- Plane-Kommentar `4a56b8c9-6254-4987-bd3d-2b78945b4786` am 2026-07-02 gesetzt; Ticket bleibt bewusst `Blocked / On Hold`, nicht `Done`.
### Pilot-Readiness-Nachzug 2026-07-29
Das globale Feedback-/Support-Widget gibt unbekannte Servicefehler nicht mehr als rohe
`Error.message` an den Browser zurück. Damit bleiben DB-, Queue-, Storage- und Konfigurationsdetails
serverseitig. Erwartete Eingabefehler und das 3/24h-Limit behalten eigene übersetzte 400-/429-Zustände;
unerwartete Fehler liefern einen neutralen übersetzten 503-Zustand. Leerer Support-Text wird vor dem
Serviceaufruf abgefangen. Proof: 30 fokussierte Route-/Feedback-/Support-Tests, ESLint,
`verify:i18n` und `git diff --check` grün.
**AK-P21 bleibt 10/11 DoD = ~91 % done.** Offen bleibt unverändert der AVV-/Re-Akzeptanz-Punkt; dieser
Hardening-Nachzug ändert den fachlichen DoD-Zähler nicht.
@@ -6,7 +6,7 @@
| **Owner** | Akeshan |
| **Phase** | P3 — Querschnitts-Oberflächen |
| **Cycle/Fenster** | W2 — Plattform & CRM (Demo 1) · fällig 2026-06-21 · Gate W2 (Noah-Demo #1) |
| **Status** | umgesetzt (2026-07-07) — Dev-DoD 7/7 = 100 %, wartet auf Owner-Freigabe für Done |
| **Status** | **Done** (Owner-Freigabe erteilt; Plane-Status Done, Stand-Audit 2026-07-17: 7/7 DoD code-verifiziert) |
**🎨 design-nachzug: offen** (seit 2026-07-07) — Interim-UI aus `~/ui` steht; finale Subframe-Optik aus `D-P3` ausstehend.
@@ -55,9 +55,8 @@ Die **Bedien-Oberflächen** der in P1 gebauten Plattformdienste: **Audit-Viewer*
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 2: Querschnitt** (AuditEntry, Notification, NotificationPreference, NotificationDevice; i18n = Felder, keine Tabelle)
- `REQUIREMENTS.md` → `REQ-audit-retention-export`, `REQ-audit-permissions`, `REQ-notification-versand-pipeline`, `REQ-i18n-outbound`
- `ROADMAP.md` → Phase 3 · `PHASE-SOURCES.md` → Phase 3 (M028/M115/M116/M151/M152; Service-Kerne → P1, Flag-Admin-UI → P19)
- `ROADMAP.md` → Phase 3 · Milestones: (M028/M115/M116/M151/M152; Service-Kerne → P1, Flag-Admin-UI → P19)
- `designer-briefs/P03-querschnitts-oberflaechen.md`
- `_bmad-output/specs/M21-audit-log.md`, `M22-notifications.md`, `M30-i18n.md` (Oberflächen-Teile)
## Dev-Nachzug (nach Davids `D-P3`-Delta)
@@ -72,7 +71,7 @@ Refactor-Nachzug offen: finale Subframe-Optik aus `D-P3` (Plane-Label `design-na
- [x] Interim-UI aus `~/ui` gebaut (AD-28, 2026-07-07) — VM als Prop, kein handgeschriebenes Tailwind für Spacing/Höhen
- [ ] Audit-/Notif-Oberflächen an Davids finaler `D-P3`-Optik angepasst (Subframe-Swap hinter der stabilen VM/Loader-Grenze; `design-nachzug: offen`). Nicht Done-blockierend (AD-28). Beim Swap: Interim-Visual-Baseline neu ziehen.
- [ ] Admin-Topbar-Drawer: der SSE-Stream ist tenant-scoped (`app.$tenant/notifications/stream`), die Admin-Topbar behält den Link — Drawer für Admin erst mit einem admin-scoped Stream (Nachzug, nicht DoD-relevant).
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [x] Requirements nachgezogen (2026-07-17: 4 Phase-3-REQs auf Done mit v1-Scope-Vermerk in `REQUIREMENTS.md`)
- [x] Plane-Ticket `AK-P3` aktualisiert (2026-07-07: Abschluss-Kommentar + Label `design-nachzug` gesetzt; Branch gepusht. Status-Wechsel macht der Owner.)
## Vorab-Entscheidungen (Owner-bestätigt 2026-06-24, `/planning` = SSoT)
@@ -193,5 +192,8 @@ vor dem Action-Code) + `verify:migrations-parity` braucht Docker → CI. Kein lo
Done-blockierend, AD-28): finale `D-P3`-Subframe-Optik (`design-nachzug: offen`), Interim-Visual-Baseline
beim Swap, Admin-Drawer (tenant-scoped Stream), Diff-Chain-Bindung/Auto-Middleware (R-P1b).
**Status-Wechsel auf Done:** durch Owner (Freigabe ausstehend); Plane-Kommentar + Label `design-nachzug`
erst nach Freigabe.
**Status-Wechsel auf Done:** erfolgt — Plane steht auf Done, Label `design-nachzug` gesetzt, Abschluss-Kommentar vom 2026-07-06 vorhanden.
### Stand-Audit — 2026-07-17 (Claude/Akeshan)
Drei-Quellen-Abgleich (Ticket-Doc vs. Plane vs. Code auf `main`) per `/audit-ticket`: **7/7 DoD = 100 % bestätigt, kein Code-Delta.** Alle 12 Umsetzungs-Commits (`2bee1ecaa`..`c48fb780b`) sind in `main` gemerged; Artefakte inhaltlich verifiziert (Permission-Gate `routes/admin/audit.tsx`, Diff-Drawer + `[REDACTED]`-Maskierung `audit-list.vm.ts`/`AuditListPage.tsx`, Export mit Zweck-Pflicht + `audit.exported` `auditExportStorage.server.ts`, Retention-Cron `apps/worker/src/index.ts`, Center/Drawer/Settings-Screens, `LanguageSettingsNotice` in `profile.tsx`, `Kontakt.language` `crm.prisma`, Migration `20260707010000_…` idempotent). Behobener Drift (rein Doku): Header-Status auf Done nachgezogen (Plane war bereits Done), REQUIREMENTS/ROADMAP-Nachzug erledigt (s. Dev-Nachzug-Checkbox). Offen bleiben nur die getrackten Nachzüge: `design-nachzug` (D-P3-Optik), Admin-Topbar-Drawer (tenant-scoped Stream), Diff-Chain-Bindung/Auto-Middleware (R-P1b).
@@ -34,7 +34,7 @@ Das **Files-Plattform-Primitive**: chunked Upload (TUS) mit **RLS auf Storage-Pf
*Eingebettet: Files-Browser vorgefiltert in Entity-Detail-Views (R-P6 ff.). Davids P4-Screens über `D-P4` (Compose aus D0).*
## Definition of Done
- [x] **Chunked Upload (TUS)** (Staging-e2e bewiesen) + **RLS auf Storage-Pfaden** — Code RLS-ready (Teil A, Gate 7/7); Scharfschalten = P5-Cutover (Teil B, Raffael), **nicht Done-blockierend**
- [x] **Chunked Upload (TUS)** (Staging-e2e bewiesen) + **RLS auf Storage-Pfaden** — Code RLS-ready (Teil A, Gate 7/7); Teil B **erledigt** durch app-weiten Cutover `20260713190000_appwide_rls_cutover` (scharf seit 14.07., alle File*-Tabellen)
- [x] **Preview** PDF→PNG / Bild→WebP / **HEIC→JPG (Pflicht!)** mit Status-Maschine + Klartext-Fallback — alle drei Zweige auf Staging mit echten Dateien bewiesen (2026-07-05)
- [x] **ClamAV-Scan** beim Upload — Live-EICAR fail-closed auf Staging bewiesen (`scanStatus=infected` → Media-404)
- [x] Permissions/Sharing + Tags + Archiv-Flag + **Bulk-ZIP** (Bulk-ZIP 2026-07-05 gebaut, lokal grün)
@@ -48,15 +48,14 @@ Das **Files-Plattform-Primitive**: chunked Upload (TUS) mit **RLS auf Storage-Pf
- **RLS** auf `File`/`FileEntityLink` + Storage-Pfad-Scoping (tenant-isoliert).
- **Konnektor** `tenantHasModule('files')` (Sidebar + Routes + Actions gated).
- ClamAV + S3 per ENV (aus AK-INFRA2 / EXT-06).
- **Media-Auslieferung (AD-23, beschlossen 2026-06-17):** Bucket bleibt **privat**, **kein public-read**. Medien werden über eine **authentifizierte Proxy-Route** ausgeliefert (Session + `withTenantScope()` + `withPermission()`), die aus dem privaten Bucket streamt bzw. auf eine kurzlebige signierte Download-URL redirected. Der `publicUrl`-Pfad in `RowHelper`/`MediaHelper`/`ApiHelper` (`publicUrl ?? file`) muss auf diese Route zeigen, **nicht** auf eine public-S3-URL; `STORAGE_PUBLIC_BASE_URL` bleibt leer. Genuin öffentliche Assets (E-Mail-Bilder, öffentliche Formular-/Booking-/Portal-Seiten, Branding-Logos) → signierte URLs mit TTL **oder** separater `public/`-Prefix mit eng begrenztem public-read (pro Asset-Typ entscheiden). DSGVO-Export-Artefakte nutzen bereits signierte URLs (unverändert).
- **Media-Auslieferung (AD-23, beschlossen 2026-06-17):** Bucket bleibt **privat**, **kein public-read**. Medien werden über eine **authentifizierte Proxy-Route** ausgeliefert (Session + `withTenantScope()` + `withPermission()`), die aus dem privaten Bucket streamt bzw. auf eine kurzlebige signierte Download-URL redirected. Der `publicUrl`-Pfad in `RowHelper`/`MediaHelper`/`ApiHelper` (`publicUrl ?? file`) muss auf diese Route zeigen, **nicht** auf eine public-S3-URL; `STORAGE_PUBLIC_BASE_URL` bleibt leer. Genuin öffentliche Assets (E-Mail-Bilder, öffentliche Formular-/Booking-/Portal-Seiten, Branding-Logos) → signierte URLs mit TTL **oder** separater `public/`-Prefix mit eng begrenztem public-read (pro Asset-Typ entscheiden). **DSGVO-Export-Artefakte** folgen seit 2026-07-20 dem strengeren SSE-C-Vertrag: authentifizierter `200`-App-Proxy, kein signierter Redirect und kein direkter Zugriff ohne Customer-Key.
- `is_demo_data` auf seedbaren Demo-Files (Onboarding-Provisioning).
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 3: Files & Tasks** (File, FileChunk, FileUploadProgress, **FileEntityLink** polymorph) + Cross-Cutting-Tabelle
- `REQUIREMENTS.md` → `REQ-files-datenmodell`, `REQ-files-upload-preview`
- `ROADMAP.md` → Phase 4 · `PHASE-SOURCES.md` → Phase 4 (M052/M053/M054 gedünnt/M055 gedünnt)
- `ROADMAP.md` → Phase 4 · Milestones: (M052/M053/M054 gedünnt/M055 gedünnt)
- `designer-briefs/P04-files-tasks.md`
- `_bmad-output/specs/M23-files.md` · Infra: ADR-009 (Hetzner Object Storage)
- `docs/ARCHITECTURE-DECISIONS.md` → **AD-23** (Media-Auslieferung: privater Bucket + Auth-Proxy, kein public-read) · AD-8 (Verschlüsselung)
## Dev-Nachzug (nach Davids `D-P4`-Delta)
@@ -77,7 +76,7 @@ Refactor-Nachzug offen: finale Subframe-Optik aus `D-P4` (Doc-Tag `🎨 design-n
`design-nachzug`).
- [ ] Files-Browser/Detail an Davids UI angepasst (finale `D-P4`-Optik über die Screen-Komponenten tauschen)
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [ ] REQUIREMENTS/ROADMAP nachgezogen
- [ ] Plane-Ticket `AK-P4a` aktualisiert
## Umsetzungs-Notiz
@@ -567,3 +566,54 @@ nicht Done-blockierend).
finale `D-P4`-Optik (`design-nachzug`, David) · RLS-Teil-B (P5-Cutover, Raffael) · deferred DoD 11 + 21. **Noch
zu tun vor Done:** die Teil-3-Features (Bulk-ZIP + Filter) sind lokal grün, aber **noch nicht committed/deployed**
→ Staging-Verifikation + Commit/Push/Merge + Plane-Label + Done stehen unter User-Freigabe aus.
### 2026-07-16 — Stand-Audit (/audit-ticket): Done bestätigt, Doku-Drift korrigiert (Akeshan)
Drei-Quellen-Audit (Ticket-Doc vs. Plane vs. realer Code auf `main`) über alle 8 DoD-Punkte —
**alle 8 im Code verifiziert erfüllt** (Proof-Pfade geprüft und geöffnet, nicht nur gegrept):
Upload-Kette `fileService.server.ts` + Resource-Routes, Preview-Worker `file-preview.ts`
(HEIC/WebP/PNG + Status-Maschine), Scan-Write-back `file-scan-status.ts` (Preview wird bewusst
erst **nach** clean-Verdict enqueued), Auth-Proxy `media.$fileId.$variant.tsx` (302 signiert,
404-statt-403, fail-closed), Bulk-ZIP (`collectFilesForZip`, Caps 50/200 MB) + alle vier
Browser-Filter, `FileEntityLink` + `createdByPortalUserId`, Querschnitt-Wiring (Sidebar/Search/
Entitlements/Audit/Activity/i18n de+en), Hot-Swap, Smoke `tests/e2e/files.spec.ts`.
**AK-P4a: 8/8 DoD = 100 % — Done ist gerechtfertigt.**
**Korrekturen (Doku-Drift, kein Code-Befund):**
- Die Schlussnote vom 05.07. („Teil-3 noch nicht committed/deployed") ist überholt: Bulk-ZIP +
erweiterte Filter sind seit **PR #43** (Commit `5fbca27fa`, Merge `ae60c6f2d`) auf `main`.
- **RLS Teil B ist geschlossen:** Der app-weite Cutover `20260713190000_appwide_rls_cutover`
(Staging scharf seit 14.07.) setzt ENABLE + FORCE ROW LEVEL SECURITY + Policies auf **allen**
File-Tabellen (`File`, `FileEntityLink`, `FileUpload`, `FileUploadChunk`, `FileUploadProgress`).
Der frühere „P5-Cutover offen (Raffael)"-Vermerk in DoD 1 und den Notizen ist damit erledigt.
- **`scanStatus=skipped` existiert nicht mehr:** `fileScanPolicy.ts` liefert nur noch
`scanStatus === "clean"` aus (Auslieferung + Bulk-ZIP). Strenger und korrekt fail-closed;
ältere Notizen mit „clean|skipped" beschreiben den Alt-Stand.
**Weiterhin offen (nicht Done-blockierend):** Staging-Live-Check von Bulk-ZIP + den drei neuen
Filtern (im Plane-Done-Kommentar vom 05.07. zugesagt, bislang ohne Proof) · finale `D-P4`-Optik
(`design-nachzug`) · deferred DoD 11 (Mobile-Tab-Bar) + DoD 21 (Visual-Regression, Interim-Baseline).
### 2026-07-16 (Abend) — Staging-Live-Check Bulk-ZIP + Filter erbracht (Akeshan)
Der im Done-Kommentar vom 05.07. zugesagte Staging-Beweis ist nachgeholt (Browser-Session
`demo-pro-crm`, eingeloggt, 16.07. ~22:00):
- **Tag-Filter** `?tag=Rechnung` → nur Rechnungs-PDFs, server-side navigiert.
- **Entity-Filter** `?entity=project` kombiniert mit Tag → gefilterte Liste.
- **Verantwortlich-Filter** `?assignee=…` → greift; 0-Treffer-Fall zeigt den Klartext-Empty-State
(„Noch keine Dateien" + Hochladen-CTA).
- **Bulk-ZIP**: authentifizierter In-Page-POST auf `files/bulk-zip` mit 2 `fileIds` →
**HTTP 200, `application/zip`, PK-Magic-Bytes, 1194 Bytes**.
- Tabelle/Raster-Umschalter, Checkbox-Spalte, Status-Badges rendern korrekt.
Damit ist der letzte offene Verifikations-Punkt aus dem Plane-Kommentar erbracht. AK-P4a bleibt
**Done, 8/8 DoD**.
### 2026-07-29 — Pilot-Readiness-Nachzug: Chunk-Upload-CSRF gehärtet (Raffael)
Die drei session-authentifizierten Resource-Actions `files.upload.init`,
`files.upload.$uploadId.chunk.$index` und `files.upload.$uploadId.complete` validieren jetzt den
Session-CSRF-Token header-only, bevor JSON beziehungsweise rohe Chunk-Bytes gelesen und Upload-Zustand
mutiert wird. Der gemeinsame Browser-Client sendet den Token bei allen drei Requests; damit bleiben
die abhängigen Chat- und Signatur-Flows kompatibel. Proof: 10/10 fokussierte Route-/Client-Tests,
betroffene ESLint-Prüfung und Web-Typecheck grün. **AK-P4a bleibt 8/8 DoD = 100 % done.**
@@ -6,7 +6,7 @@
| **Owner** | Akeshan |
| **Phase** | P4 — Files & Tasks |
| **Cycle/Fenster** | W1 — Fundament & Identität · fällig 2026-06-19 · **Gate W1 (EntityLink)** |
| **Status** | Interim-UI gebaut (2026-07-06) · Dev-DoD 100 %; design-nachzug offen (AD-28, nicht Done-blockierend) — Done-Freigabe ausstehend |
| **Status** | Done (Plane Done seit 2026-07-05; Audit-bestätigt 2026-07-16) — Dev-DoD 8/8 = 100 %; design-nachzug offen (AD-28, nicht Done-blockierend) |
**🎨 design-nachzug: offen** (seit 2026-07-06) — Interim-UI aus `~/ui` steht; finale Subframe-Optik aus `D-P4` ausstehend.
@@ -47,9 +47,8 @@ Das **leichtgewichtige, querliegende Tasks-Modul**: Task-CRUD mit Status/Priorit
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 3: Files & Tasks** (Task polymorph link, TaskWatcher) + Cross-Cutting (Task-Link, EntityLink-Prinzip)
- `REQUIREMENTS.md` → `REQ-tasks-datenmodell`, `REQ-tasks-reminder-archivierung`
- `ROADMAP.md` → Phase 4 · `PHASE-SOURCES.md` → Phase 4 (M071/M072/M073; M074-ERP-Sync → P10; Entity-Links → P6 nachverdrahtet)
- `ROADMAP.md` → Phase 4 · Milestones: (M071/M072/M073; M074-ERP-Sync → P10; Entity-Links → P6 nachverdrahtet)
- `designer-briefs/P04-files-tasks.md` (Task-Liste = wiederverwendbare Komponente)
- `_bmad-output/specs/M26-tasks.md`
## Dev-Nachzug (nach Davids `D-P4`-Delta)
- [x] **Interim-UI aus `~/ui` gebaut (AD-28, 2026-07-06)** — die drei Screens (Liste/Detail/Neu) sind aus
@@ -58,7 +57,7 @@ Das **leichtgewichtige, querliegende Tasks-Modul**: Task-CRUD mit Status/Priorit
form-fähige Date-Variante hat — mit Design-Tokens gestyled). Routen rendern nur noch `<XPage vm={} … />`.
- [ ] Task-Liste/-Detail an Davids **finaler** `D-P4`-Optik angepasst (Subframe-Swap hinter der stabilen
VM/Loader-Grenze; `design-nachzug: offen`, Plane-Label `design-nachzug`). **Nicht Done-blockierend (AD-28).**
- [x] REQUIREMENTS nachgezogen (`REQ-tasks-datenmodell` + `REQ-tasks-reminder-archivierung` = Done); PHASE-SOURCES braucht keinen Status-Nachzug (reines Spec-Mapping, M071/M072/M073 bereits Phase 4).
- [x] REQUIREMENTS nachgezogen (`REQ-tasks-datenmodell` + `REQ-tasks-reminder-archivierung` = Done).
- [x] Plane-Ticket `AK-P4b` aktualisiert (Kommentar + Label `design-nachzug` gesetzt, Status auf Done).
---
@@ -286,3 +285,64 @@ Marker `ui.tasks.list`/`.detail`/`.new` + `data-row-id`/`data-watcher-id`/`data-
**%-Done-Stand:** 8/8 DoD-Code-Punkte grün **+** AD-28-Interim-UI-Konformität hergestellt (Screens aus
`~/ui`, Tests grün). Selbst-machbarer Rest: **0**. Gesamt **~97 %** — nur noch extern/Reviewer-Freigabe +
Davids finale Optik (getrackter `design-nachzug`) offen.
---
### 2026-07-16 — Stand-Audit (/audit-ticket): Done bestätigt, Doku-Drift korrigiert (Akeshan)
Drei-Quellen-Audit (Ticket-Doc vs. Plane vs. realer Code auf `main`) über alle 8 DoD-Punkte —
**alle 8 im Code verifiziert erfüllt**: Schema `tasks.prisma`/`entityLinks.prisma` inkl. DB-CHECK
`Task_single_assignee_chk` (num_nonnulls=1) in Migration `20260624120000`, `taskService`/`taskAccess`
(Foundation-404, Sichtbarkeit Ersteller/Assignee/Watcher/Gruppe), `entityLinkService` (idempotenter
Upsert), Reminder-Cron (3 Fenster, after→EMAIL, sourceKey-Idempotenz) + Archiv-Cron (beide per-Tenant,
registriert), wiederverwendbare Task-Liste (VMs + Adapter + Hot-Swap), Interim-Screens, Querschnitt
(Sidebar/Search/Entitlements/Audit/Activity/i18n de+en). **AK-P4b: 8/8 DoD = 100 % — Done ist
gerechtfertigt**; die Statuszeile im Header ist entsprechend bereinigt.
**Korrekturen (Doku-Drift, kein Code-Befund):**
- **RLS Teil B ist geschlossen:** Der app-weite Cutover `20260713190000_appwide_rls_cutover`
(Staging scharf seit 14.07.) setzt ENABLE + FORCE ROW LEVEL SECURITY + Policies auf `Task`,
`TaskWatcher` und `EntityLink`. Der „P5-Cutover offen (Raffael)"-Vermerk ist damit erledigt.
- Blocker-Verifikation: `AK-P4a` ist vollständig auf `main` (inkl. PR #43) — kein Blocker mehr real.
**Minor-Befund:** `tests/e2e/tasks.spec.ts` smoked nur die Liste (`ui.tasks.list`), Detail/Neu-Marker
werden nicht exerziert — gleicher Standard wie der akzeptierte Files-Smoke, als Verbesserung notiert
(💡 Vorschlag außerhalb Ticket-Scope: Smoke um Task-Anlage erweitern; nur nach OK).
**Weiterhin offen (nicht Done-blockierend):** Staging-Live-Check Reminder-Sweep (3 Fenster,
notify-Einträge) + 30-Tage-Archiv-Cron + Auflösung der Reminder-messageKeys (nie protokolliert) ·
finale `D-P4`-Optik (`design-nachzug`) · deferred Mobile-Tab-Bar + Visual-Regression (Interim-Baseline).
---
### 2026-07-16 (Abend) — Staging-Live-Check Tasks: Anlage bewiesen, Reminder-Zustellung FEHLGESCHLAGEN (Befund) (Akeshan)
Live auf `demo-pro-crm` (Browser, eingeloggt):
- **Task-Liste**: Presets Meine/Erstellt/Alle, Status-/Prio-Filter, Gruppen-Zuweisungen sichtbar — ok.
- **Task-Anlage** über `/tasks/new`: Testaufgabe „AK-P4-Audit Testaufgabe (Reminder-Check, wird
geloescht)" (ID `cmrnw4rbp000101s1cxglkb3d`, Fälligkeit 17.07.) angelegt; **Creator-Default-
Zuweisung live bewiesen** (Zuständig = eingeloggter User), Quelle „Manuell", Detail mit
Breadcrumb + Erledigen/Archivieren/Löschen — ok.
- **Reminder-Sweep: KEINE Zustellung.** Die Fälligkeit liegt seit >20h im `before`-Fenster
(`selectReminderWindows`: now >= deadline−24h), zwischen Anlage (21:26) und Check (22:31) ist
sicher ≥1 Stunden-Sweep gelaufen — die Benachrichtigungszentrale bleibt leer.
**Root-Cause-Hypothese (Code-gelesen, auf Staging noch nicht log-verifiziert):** Der Sweep-Handler
ruft `notify()` bewusst **außerhalb** von `withTenantRLS()` mit dem rohen db-Client auf
(`handlers.ts`, Kommentar „own RLS story"); `notify()` (`packages/foundation/src/notifications.ts`)
bindet selbst **keinen** Tenant-Kontext. Seit dem app-weiten RLS-Cutover `20260713190000` steht
`NotificationDelivery` auf FORCE RLS → der Worker-Upsert scheitert an der Policy, der Handler
fängt den Fehler und loggt nur `tasks.reminder.notify-failed`. Das träfe **jeden** worker-seitigen
`notify()`-Aufruf, nicht nur Tasks. **Nachweis/Fix ist ein eigenes Ticket** (Worker-Logs auf
`tasks.reminder.notify-failed` prüfen; `notify()`-Aufrufe in Tenant-RLS-Kontext wrappen oder
`notify()` kontext-bindend machen) — kein AK-P4b-Doku-Scope, mit Raffael (RLS-Cutover) abzustimmen.
Die Testaufgabe bleibt zur Diagnose **stehen** (nicht gelöscht).
- **30-Tage-Archiv-Cron**: per UI nicht erzwingbar (bräuchte `done`-Task mit `completedAt` >30 Tage
zurück, nicht rückdatierbar) — bleibt unit-getestet + registriert; gleiche RLS-Frage stellt sich
hier NICHT (der Cron schreibt innerhalb `withTenantRLS`).
**Einordnung DoD:** DoD 4 (Reminder via notify()) war zum Bau-/Merge-Zeitpunkt korrekt und
unit-getestet; die Zustellung ist mutmaßlich durch den **späteren** RLS-Cutover (13.07.) gebrochen
worden — eine Regression außerhalb des Ticket-Scopes, kein falscher DoD-Haken. Ticket bleibt Done;
die Regression läuft als eigener Befund.
@@ -0,0 +1,264 @@
# AK-SET-01 · Settings-Informationsarchitektur: 21 Rail-Einträge zu 6 Hubs bündeln
| | |
|---|---|
| **Typ** | Dev/UI — Informationsarchitektur + Interim-UI-Sanierung |
| **Owner** | Akeshan + Agent |
| **Status** | 🟡 READY-TO-VERIFY — Dev-DoD 14/14 erfüllt (2026-07-22) |
| **Blocked by** | — (`AK-P21` ist in der Branch-Basis enthalten) |
| **Tracking** | nur Git-Repo — kein Plane-Ticket (analog zur gelöschten AK-UI-Serie, siehe `AK-UI-ENTFALLEN.md`); diese Doc ist die alleinige Quelle der Wahrheit |
🎨 **design-nachzug: offen** — die sieben Hubs und der Audit-Export verwenden die freigegebene Interim-UI; die finale Subframe-Optik bleibt ein getrackter Nachzug gemäß AD-28.
## Was wir bauen
Die Tenant-Settings unter `/app/:tenant/settings` reichen der inneren Rail aktuell **bis zu 21 Einträge** durch. Diese 21 Einträge werden zu **6 Hub-Bereichen + Kundenportal** gebündelt. Jeder Hub bekommt eine eigene Layout-Route mit `PageHeader` und einer permanent sichtbaren horizontalen `~/ui`-Tab-Leiste; jeder Tab behält eine eigene URL. Alle Alt-URLs bleiben über 302-Redirects erreichbar.
Zusätzlich wird `/settings/audit-export` überhaupt erst über die Navigation erreichbar gemacht und auf den Interim-UI-Standard gehoben (heute: handgeschriebenes Tailwind mit `bg-blue-600`, kein `PageHeader`, keine Zustände).
## Nicht im Scope (verbindlich)
- **`apps/web/app/components/ui/layouts/SidebarIconsLayout.tsx` und `apps/web/app/ui/components/SidebarInside/` werden NICHT angefasst.** Hover-Aufklappen, `HOVER_OPEN_DELAY_MS`/`HOVER_CLOSE_DELAY_MS` (300/350 ms), die `w-[208px]`, der Content-Reflow beim Aufklappen und die Mobile-Tabs-Leiste bleiben exakt wie sie sind. Geändert wird ausschließlich der **Inhalt** des `items`-Arrays, das `settings.tsx` hineinreicht. Die 17 übrigen Call-Sites der Komponente bleiben dadurch unberührt. — *User-Entscheidung 2026-07-21.*
- Der Plattform-Admin-Bereich (`routes/admin/settings/*`, eigene 8-Punkt-Navigation in `AdminSidebar.tsx:325-372`) hat dasselbe Problem, ist hier aber bewusst außen vor.
- Keine Änderung an VM-Buildern, Domain-Services, Prisma-Schema oder Permissions. Loader/Actions ziehen 1:1 mit um.
## Ist-Stand (live verifiziert 2026-07-21, Tenant `hivegrid-demo`)
`getTabs()` in `apps/web/app/routes/app.$tenant/settings.tsx:66-246` baut bis zu 21 Einträge; `settings/` enthält ~35 Route-Dateien mit 8.779 LOC.
**Befund 1 — die Rail skaliert nicht auf 21 Einträge.** Die innere Rail ist eine Hover-Rail: `expanded = hovered || focusWithin` (`SidebarIconsLayout.tsx:37`), **es gibt keinen Pin/Toggle**. Im Ruhezustand nur Icons, davon mehrere doppelt (drei identische Aktivitäts-Kurven für Nutzung/Chat-Audit/Protokolle, zwei identische Dokument-Icons für Rechnungen/Richtlinien). Aufgeklappt ist die Spalte `w-[208px]` (`SidebarInside.tsx:144`), abzüglich 32 px Icon-Spalte bleiben ~140 px, der Text hat `truncate` (`SidebarInside.tsx:50`) → **7 von 18 sichtbaren Labels sind abgeschnitten**: „Datensch…", „Abonnem…", „Rechnun…", „Demo-Da…", „Integratio…", „API-Schlü…", „Benachric…". Mobil rendert dieselbe Komponente alle Einträge als horizontale Tabs-Leiste (`SidebarIconsLayout.tsx:132-145`) — 21 Tabs scrollen dort ins Nirgendwo.
**Befund 2 — `settings/audit-export.tsx` bricht die Interim-UI-Standards.** Kein `PageHeader`, stattdessen nacktes `<h1 className="text-xl font-semibold">` (Z. 109); `bg-blue-600`/`text-blue-600`-Buttons (Z. 158, 166) in einer Farbe, die im Rest der App nicht vorkommt; rohe `<input type="date">` und `<select>` statt `~/ui` `DatePicker`/`Select`; `text-gray-500`, `rounded border px-2 py-1` statt Design-Tokens; **keine Empty-, Loading- oder Error-States**. Laut `.planning/INTERIM-UI-DESIGN-STANDARDS.md` §0 ein PR-Block-Tatbestand. Die Seite hat außerdem **keinen Rail-Eintrag** und ist nur per Deep-Link erreichbar.
**Befund 3 — `settings/policies.tsx:46` erzeugt eine Redirect-Kette.** Die API-Sektion zeigt auf `"api"` statt `settings/api`, läuft also über die Legacy-Redirect-Route.
## Ziel-Struktur
Sieben Rail-Einträge. Jeder Hub: `PageShell` + `PageHeader` + `~/ui`-Tabs + `<Outlet/>`.
```
┌──────────────────────────────────────────┐
│ 💳 Abrechnung │ ← PageHeader (Icon, h1, Subtitle)
│ Plan, Verbrauch und Rechnungen │
├──────────────────────────────────────────┤
│ [ Abo & Plan ] Nutzung Rechnungen │ ← ~/ui/components/Tabs
├──────────────────────────────────────────┤
│ <Outlet/> │
└──────────────────────────────────────────┘
/hivegrid-demo/settings/billing/usage
```
**Titel-Längen-Constraint:** Die 208 px der Rail bleiben unverändert, also muss jeder Hub-Titel ohne `truncate` hineinpassen. „Integrationen & Erweiterungen" tut das nicht → Rail-Label ist **„Erweiterungen"**. Die anderen sechs sind kürzer als heute vollständig dargestellte Labels wie „Mitglieder"/„Telefonie". **Pro Hub per Screenshot verifizieren.**
### A · Mein Konto — Basis `settings/profile`
| Tab | Neue Datei | Aus | Gate |
|---|---|---|---|
| Profil | `settings/profile/index.tsx` | `settings/profile.tsx` | — |
| Sicherheit | `settings/profile/security.tsx` | `settings/security.tsx` | — |
| Benachrichtigungen | `settings/profile/notifications.tsx` | `settings/notifications.tsx` | — |
| Meine Daten | `settings/profile/data.tsx` | `settings/privacy.tsx` | — |
`settings/profile.tsx` wird neu zum Hub-Layout, bleibt Default-Redirect-Ziel (`settings.tsx:248-253`). Alle vier Tabs ungated — der DSGVO-Self-Service muss für jeden erreichbar bleiben (DoD B6, so kommentiert in `settings.tsx:81-83`). `buildPrivacyHubVM` liefert vier Section-Keys (`packages/view-models/src/privacy/privacy-hub.vm.ts:4`): `export`+`deletion` bleiben hier, `subprocessors`+`avv` sind reine Verweise und wandern nach Hub F.
### B · Team & Zugriff — Basis `settings/team`
| Tab | Neue Datei | Aus |
|---|---|---|
| Mitglieder | `settings/team/index.tsx` (+ `members/new`, `members/$id`) | `settings/members.tsx`, `settings/members/*` |
| Rollen & Rechte | `settings/team/roles.tsx` (+ `roles/$id`, `roles/new`) | `settings/roles-and-permissions/*` |
| Gruppen | `settings/team/groups.tsx` (+ `$id`, `new`) | `settings/groups*`, `settings/members/groups/*` |
⚠️ `MembersPage.tsx:92-97` und `RolesPage.tsx` rendern **bereits eine eigene Tabs-Leiste** („Mitglieder | Rollen und Berechtigungen"). Die muss raus, sonst stehen zwei Tab-Leisten übereinander. Der Fallback-Tab-Hack in `settings.tsx:203-210` entfällt ersatzlos.
### C · Workspace — Basis `settings/workspace`
| Tab | Neue Datei | Aus |
|---|---|---|
| Allgemein | `settings/workspace/index.tsx` | `settings/account.tsx` |
| Richtlinien | `settings/workspace/policies.tsx` | `settings/policies.tsx` |
| Demo-Daten | `settings/workspace/demo-data.tsx` | `settings/onboarding/demo-data.tsx` |
**`policies.tsx` behält Karten, Texte UND Link-Zeilen** (User-Entscheidung 2026-07-21). Begründung: nach der Konsolidierung liegen die sechs Ziele in fünf verschiedenen Hubs, damit werden die Links von Navigations-Dopplung zu nützlichen Querverweisen. Nur die `path`-Werte in `POLICY_SECTIONS` (`policies.tsx:26-48`) ziehen um:
| Sektion | heute | neu |
|---|---|---|
| membership | `settings/members` | `settings/team` |
| roles | `settings/roles-and-permissions` | `settings/team/roles` |
| billing | `settings/subscription` | `settings/billing` |
| notifications | `settings/notifications` | `settings/profile/notifications` |
| audit | `settings/logs` | `settings/compliance` |
| api | `api` ⚠️ (Redirect-Kette, Befund 3) | `settings/integrations/api` |
Keine i18n-Änderung — alle `settings.policies.*`-Keys bleiben unverändert.
### D · Abrechnung — Basis `settings/billing` · **Pilot-Hub**
| Tab | Neue Datei | Aus |
|---|---|---|
| Abo & Plan | `settings/billing/index.tsx` | `settings/subscription.tsx` |
| Nutzung | `settings/billing/usage.tsx` | `settings/usage.tsx` |
| Rechnungen | `settings/billing/invoices.tsx` | `settings/billing.tsx` (alt, wird zum Hub-Layout) |
⚠️ **Footgun:** `settings/subscription/invoices.$invoiceId.download.tsx` ist ein Download-Endpoint unter dem Eltern-Pfad. Ein Redirect im Layout `settings/subscription.tsx` würde ihn **töten**, weil der Eltern-Loader auch für Kinder läuft. Richtig: `settings/subscription.tsx` wird reiner `<Outlet/>`-Pass-through **ohne Loader-Redirect**, der Redirect kommt in ein **neues** `settings/subscription/index.tsx`.
`settings/credits.tsx` redirected heute auf `settings/subscription` → Ziel direkt auf `settings/billing` umhängen, keine Kette.
### E · Erweiterungen — Basis `settings/integrations`
| Tab | Neue Datei | Aus |
|---|---|---|
| Katalog | `settings/integrations/_index.tsx` | bleibt |
| E-Mail | `settings/integrations/email._index.tsx` | bleibt |
| Kalender | `settings/integrations/calendar._index.tsx` | bleibt |
| Telefonie | `settings/integrations/telephony.tsx` | bleibt |
| Plugins | `settings/integrations/plugins.tsx` (+ `$id`, `$id/audit`) | `settings/plugins*` |
| API-Keys | `settings/integrations/api/*` | `settings/api/*` |
`integrations.tsx` (heute 17 LOC, nur `<Outlet/>`) bekommt `PageHeader` + Tab-Leiste; der Breadcrumb-Kommentar dort (Z. 1-4) beschreibt genau diese Layout-Rolle.
⚠️ `settings/api/*` ist bereits **Ziel** von Legacy-Redirects aus `/:tenant/api/*` (`routes/app.$tenant/api/*.tsx`). Deren Redirect-Ziel direkt auf `settings/integrations/api/*` umhängen, sonst zweistufige Kette. `api/legacy-settings-redirects.test.ts` mit anpassen.
### F · Compliance & Protokolle — Basis `settings/compliance` · **zuletzt bauen**
| Tab | Neue Datei | Aus |
|---|---|---|
| Audit-Log | `settings/compliance/index.tsx` (+ `events`, `events.$id`) | `settings/logs/*` |
| Audit-Export | `settings/compliance/export.tsx` | `settings/audit-export.tsx` — **+ UI-Neubau, Slice 4** |
| Chat-Audit | `settings/compliance/chat.tsx` (+ `$id`) | `settings/chat/audit*` |
| AVV | `settings/compliance/avv.tsx` | `settings/privacy.avv.tsx` |
| Unterauftragsverarbeiter | `settings/compliance/subprocessors.tsx` | `settings/privacy.subprocessors.tsx` |
| Mandanten-Löschung | `settings/compliance/tenant-deletion.tsx` | `settings/privacy.deletion.tsx` |
Damit wird Audit-Export **erstmals über die Navigation erreichbar** (Befund 2).
### Kein Umzug: Kundenportal
`settings/customer-portal.tsx` bleibt eigener Rail-Eintrag, bekommt intern Tabs `Einstellungen | Domain | E-Mail-Vorlagen` (Dateien liegen bereits so: `customer-portal/domain.tsx`, `customer-portal/email-templates.tsx`). Kein Route-Umzug; der separate Rail-Eintrag für die Mailvorlagen (`settings.tsx:153-158`) entfällt.
### Endpoint-Regel (verbindlich)
**Nicht-visuelle Routen ziehen NICHT um.** Ihre URLs bleiben Zeichen für Zeichen erhalten:
- `settings/privacy.delete.confirm.$token.tsx` — **wird per E-Mail verschickt** (`privacy.tsx:71-75` baut die URL). Ändern = tote Links in bereits versendeten Mails.
- `settings/privacy.export.$jobId.download.ts`
- `settings/subscription/invoices.$invoiceId.download.tsx`
- `settings/chat/audit.$id.attachments.$fileId.$variant.tsx`
- `settings/logs/export.ts` und `settings/logs/events-export.ts` — CSV-Resource-Routes ohne Komponente (*durch die Slice-0-Baseline gefunden, im ursprünglichen Plan übersehen; als `.ts` tauchten sie in der `*.tsx`-Bestandsaufnahme nicht auf*). Sie hängen unter `settings/logs/`, das nach Hub F zieht → beim Umzug von Hub F **muss** `logs.tsx` derselbe `<Outlet/>`-Pass-through-Trick wie bei `subscription.tsx` treffen, sonst sterben beide CSV-Exporte.
## Definition of Done
- [x] **1.** Route-Manifest-Baseline existiert (`routes.settings-manifest.test.ts`) und ist nach jedem Hub-Umzug grün — keine Route verschwindet still.
- [x] **2.** `buildSettingsHubVM` in `packages/view-models/src/settings/settings-hub.vm.ts` ist pure Funktion (kein React, kein Prisma) mit Unit-Test.
- [x] **3.** `SettingsHubShell` unter `components/screens/settings/` erhält VM als Prop, ist aus `~/ui` + `PageShell` komponiert, kein handgeschriebenes Tailwind für Dinge, die `~/ui` anbietet.
- [x] **4.** Alle 6 Hubs + Kundenportal gebaut; die Rail zeigt 7 statt 21 Einträge; jeder Hub-Titel passt ohne `truncate` in die 208 px (Visual-Baseline rendert und prüft alle sieben Hub-Labels).
- [x] **5.** Redirect-Contract-Test deckt die **vollständige** Alt→Neu-Matrix ab; jede Alt-URL liefert 302 mit erhaltenem Query-String; **keine Redirect-Ketten** (Testassertion: Ziel ist selbst kein Redirect-Loader).
- [x] **6.** Die vier Endpoint-Routen (Endpoint-Regel) haben unveränderte URLs; der Rechnungs-Download unter `settings/subscription/` funktioniert nachweislich weiter.
- [x] **7.** `AuditExportPage` neu unter `components/screens/audit/`: `PageHeader`, `~/ui`-Controls statt `bg-blue-600`/roher `<select>`/`<input type="date">`, Empty-/Loading-/Error-States mit Klartext. Über Hub F per Navigation erreichbar.
- [x] **8.** Doppelte Tab-Leisten entfernt (`MembersPage.tsx:92-97`, `RolesPage.tsx`); Fallback-Tab-Hack `settings.tsx:203-210` entfällt.
- [x] **9.** `POLICY_SECTIONS`-Pfade auf die neuen URLs gezogen (Tabelle in §C), inkl. Fix der `"api"`-Kette.
- [x] **10.** Leerer Hub = **404**, nicht leere Seite: hat ein User für keinen Tab eines Hubs die Permission, wirft der Hub-Loader 404 und der Rail-Eintrag wird nicht gerendert (DoD E25).
- [x] **11.** Registry-Gates nachgezogen: `UI_NAV_IDS`, `docs/ui-inventory/surfaces.json`, `AppSidebar.test.tsx`-Fixtures, i18n de **und** en.
- [x] **12.** **`git diff` gegen `SidebarIconsLayout.tsx` und `ui/components/SidebarInside/` ist leer.**
- [x] **13.** Tests grün: VM-Unit, Redirect-Contract, Smoke je Hub, Visual-Baselines (interim markiert), plus die bestehenden Suiten aus §Verifikation.
- [x] **14.** **Konsumenten-Sweep abgeschlossen** (§Slice 2b): kein Produktions-Code baut mehr eine Alt-URL, die nur noch per 302 erreichbar wäre. Verifiziert per Grep-Kontrolllauf; Suchindex und Command-Palette zeigen direkt auf die neuen Ziele.
**Fortschritt:** AK-SET-01: **14/14 DoD = 100 % done** · 0 Punkte offen · finaler Subframe-Design-Nachzug separat offen und gemäß AD-28 nicht Done-blockierend.
## Umsetzungs-Notiz · 2026-07-22
- Basis aus Akeshans geschlossenem PR #208 übernommen (`742fea5a5`), erste Route-/Audit-Vertragsfehler in `628483111` repariert; Abschluss in diesem Settings-Reparaturcommit.
- Vollständige Alt→Neu-Matrix: 41 visuelle Alt-Routen, 83 Redirect-Assertions mit 302, Query-Erhalt und Kettenausschluss. CSV-, Attachment-, Privacy- und Rechnungs-Download-Endpunkte bleiben auf ihren veröffentlichten URLs und werden separat getestet.
- Permission-/Modul-Parität für Rail und Hub-Loader hergestellt; Hub-Basis-URLs springen auf den ersten tatsächlich erlaubten Tab, leere Hubs liefern 404. Tenant-Audit-Export liest Audit-Daten unter gebundenem RLS-Kontext.
- UI-/Registry-Proof: sieben Rail-IDs in `UI_NAV_IDS` und `docs/ui-inventory/surfaces.json`; Interim-Visual-Baseline rendert alle sieben Hubs, Smoke-Spec deckt jeden Hub ab. Der Diff gegen die beiden ausdrücklich gesperrten Sidebar-Layoutpfade ist leer.
- Verifikation: `pnpm typecheck`, `pnpm lint`, `pnpm build`, `pnpm run verify:bundle-size` (13/13 Gruppen und 653/653 Einzelrouten), `pnpm run verify:i18n`, `pnpm run verify:sidebar-routes`, `pnpm test:hot-swap`, `pnpm run verify:test-coverage`, `verify:source-health`, `verify:ci-baseline` und `git diff --check` grün. Gezielte Settings-Suite: 126/126 Tests. Voller Core-Lauf: 1.004 Testdateien und 7.240 Tests bestanden; 10 Dateien/55 Live-Integrationstests erwartungsgemäß ohne Infrastruktur übersprungen. Der nachgezogene Worker-Mailvertrag ist zusätzlich mit 21/21 Tests grün. 47 betroffene Playwright-Fälle kompilieren über `--list`; kein lokaler Live-E2E-/Deploy-Lauf durchgeführt.
- Konsumenten-Sweep: Produktcode, Worker, Such-/Command-Ziele, visuelle Fixtures und E2E-Defaults zeigen direkt auf die neuen Hub-Routen. Verbleibende Treffer sind Komponenten-Importpfade oder die absichtlich unveränderten Resource-Endpunkte.
## Technische Bausteine (Slices in Reihenfolge)
**Slice 0 — Route-Manifest-Baseline.** `apps/web/app/routes.ts` nutzt `createRoutesFromFolders` (v1-Konvention über `~/utils/compat/v1-route-convention`), und der Bestand **mischt** Punkt-Notation (`privacy.export.tsx`) mit Ordner-Notation (`members/new.tsx`). Snapshot-Test über alle `app.$tenant/settings/**`-Pfade anlegen. **Konvention für alles Neue: ausschließlich Ordner-Notation** (`billing.tsx` + `billing/usage.tsx`), analog zum bewährten `members.tsx` + `members/`, `roles-and-permissions.tsx` + `roles-and-permissions/`, `integrations.tsx` + `integrations/`.
**Slice 1 — `SettingsHubShell` + VM.** VM: `buildSettingsHubVM({ tabs, activeHref })` → `{ tabs: [{ id, labelKey, href, active }] }`; die Permission-Entscheidung trifft der **Loader** und übergibt nur erlaubte Tabs. Screen komponiert `PageShell` + `PageHeader` (`components/screens/shared/PageShell.tsx`) + `~/ui/components/Tabs`, Tabs als `<Link className="contents no-underline"><Tabs.Item active={…}>` — **exakt das Muster aus `components/screens/users/MembersPage.tsx:92-97`**.
**Slice 2 — Redirect-Helper + Contract-Test.** `settings/legacy-redirects.server.ts` mit `legacySettingsRedirect(request, params, target)` → 302 mit erhaltenem Query-String. Vorlage 1:1: `routes/app.$tenant/api/legacy-settings-redirects.test.ts` und die Loader in `api/index.tsx`, `api/keys.tsx`.
**Slice 2b — Konsumenten-Sweep** *(neu, ergänzt 2026-07-21 nach Grep-Befund — im ursprünglichen Plan unterschätzt).*
Der Grep hat **~25 Produktionsdateien außerhalb von `routes/`** gefunden, die Settings-URLs hartkodieren. Redirects halten die zwar am Leben, aber ein Suchindex-Eintrag oder ein Command-Palette-Ziel, das dauerhaft über einen 302 läuft, ist eine schleichende Regression. Diese Konsumenten ziehen **mit** um:
| Kategorie | Dateien | Warum kritisch |
|---|---|---|
| App-Chrome-Menüs | `components/layouts/buttons/ProfileButton.tsx` (6 Pfade!), `layouts/sidebars/shadcn/nav-user.tsx`, `nav-actions.tsx`, `layouts/NavBar.tsx`, `buttons/CurrentSubscriptionButton.tsx` | direkt sichtbare Navigation |
| Command-Palette | `services/command-registry/commandRegistry.ts` Z. 99, 109, 118, 127, 150, 159 | 6 Spotlight-Ziele |
| Suchindex | `services/search/globalSearch.server.ts`, `services/search/searchIndexProjection.server.ts` | **persistierte** URLs im Index → Re-Index nötig, sonst bleiben Alt-Ziele dauerhaft gespeichert |
| URL-Helfer | `utils/app/SubscriptionUrlUtils.ts` (`settings/subscription?subscription_required=1`) | Query-String muss den Redirect überleben — deckt Contract-Test ab |
| Fach-Services | `utils/services/.server/akP20OnboardingService.ts`, `modules/events/services/.server/EventsService.ts`, `services/billing/customer-invoices.server.ts`, `modules/chat/routes/chatRoutePaths.ts`, `utils/data/useMembersData.ts` | |
| Feature-Gates / Formulare | `components/ui/misc/ProFeature.tsx`, `core/settings/subscription/CheckPlanFeatureLimit.tsx`, `core/pricing/PricingPlanForm.tsx`, `core/settings/members/NewMember.tsx`, `screens/users/InviteMemberForm.tsx`, `modules/users/components/SubscriptionSettings.tsx` | |
| Error-Reporter | `packages/error-reporter/src/sentry.ts` (`settings/privacy`) | |
| Hot-Swap / Visual | `packages/ui-mock/src/index.ts`, `packages/ui-mock/visual-baseline/{ak-p20-interim,va-p24a-interim,ak-ui-05-plugins}.mock.ts` | sonst driften Hot-Swap-Drill und Baselines |
**Nicht betroffen:** E-Mail-Templates. Der Grep über `apps/web/app/modules/emails` und `packages/mail` fand nur zwei Admin-Test-URLs (`admin.example.com/settings/transactional-emails`), keine Tenant-Settings-Links. Die per Mail versendete Lösch-Bestätigungs-URL wird in `privacy.tsx` gebaut und fällt unter die Endpoint-Regel.
**Vorgehen:** Der Sweep läuft **pro Hub im jeweiligen Slice**, nicht als Big-Bang — beim Umzug eines Hubs werden dessen Konsumenten mitgezogen. Abschluss-Kontrolle in Slice 10 per Grep.
**Slice 3 — Hub D „Abrechnung" (Pilot).** Kleinster Hub, drei Tabs, alle mit demselben `BILLING_MODULE_KEY`-Gate. Löst den `subscription.tsx`-Pass-through-Footgun und verankert ihn im Contract-Test. **Danach STOP und Review**, bevor die übrigen Hubs folgen.
**Slice 4 — `audit-export` Interim-UI-Sanierung.** Eigenständig wertvoll, auch ohne den Rest. Neuer Screen `components/screens/audit/AuditExportPage.tsx`; Loader/CSV-/PDF-Streaming (`streamTenantAuditExport`, `streamTenantAuditPdfExport`) bleiben unverändert. Filter-Optionen als VM (`packages/view-models/src/audit/audit-export.vm.ts`) statt hartkodierter `<option>`-Listen (Z. 130-155).
**Slice 5-9 — Hubs F, A, B, C, E.** Je Hub: Layout-Route anlegen → Kind-Routen per `git mv` verschieben (History bleibt) → Alt-Pfade auf Redirect-Loader reduzieren → doppelte Tab-Leisten entfernen (Hub B) → Tests umhängen.
**Slice 10 — Rail-Inhalt + Registries + Doku.** `getTabs()` in `settings.tsx` von 21 auf 7 Einträge kürzen. **Kein Layout-Slice** — die Komponente bleibt unangetastet (§Nicht im Scope).
### Interim-UI-Standards (AD-28)
`.planning/INTERIM-UI-DESIGN-STANDARDS.md` **vor dem Bau lesen.** Verbindlich: §0 Component-Defaults statt Tailwind-Overrides · §2 Page-Padding 24 / Card 16 / Grid-Gap 16 / Field-Gap 16 · §5 Controls Medium (36) / Radius small (4) · §7 Empty/Loading/Permission als inline State-Komponenten, Permission-Denied = **404**, nicht 403.
**Stil-Referenzen (lesen, nicht kopieren):** `components/screens/users/MembersPage.tsx` (Tab-Leiste), `components/screens/billing/BillingUsagePage.tsx` (Card/EmptyState/Loader/Alert-States), `components/screens/billing/SubscriptionOverviewPage.tsx`, sowie fertige Automations- und Form-Screens.
### Registry-Gates (sonst lokal grün, CI rot)
| Slice legt an | Pflicht-Nachzug | CI-Gate |
|---|---|---|
| Neue Nav-IDs (7 Hubs) | `UI_NAV_IDS` in `apps/web/app/application/ui/uiRegistry.ts` + Fixtures in `AppSidebar.test.tsx` **plus** Surface-Einträge in `docs/ui-inventory/surfaces.json` | `verify:sidebar-routes`, `uiRegistry.test.ts`, `uiInventory.test.ts` |
| Neue Hub-/Tab-Titel | i18n-Keys in `de/` **und** `en/` `translations.json` — chirurgisch splicen, **nie** JSON round-trippen | `verify:i18n` |
| Route-Umzüge | `apps/web/app/routes.test.ts` + Manifest-Snapshot aus Slice 0 | `verify:sidebar-routes` |
| Neue `data-ui-id` | `docs/ui-inventory/surfaces.json` | `uiInventory.test.ts` |
**Kein Prisma-Touch, keine Migration, kein neuer Permission-Key.** Falls doch ein Permission-Key nötig würde: `packages/db/src/permissions-seed.server.ts` **und** `application/dtos/shared/DefaultPermissions.ts` **und** `DEFAULT_PERMISSION_SCOPE_KEYS` in `roleDisplay.ts` **und** de/en-Scope-Übersetzung — alle vier, sonst rot.
## Verifikation (pro Commit)
```
pnpm --filter @hivegrid/web typecheck
pnpm --filter @hivegrid/view-models typecheck
pnpm run verify:i18n # Exit 0
pnpm run verify:sidebar-routes
node scripts/vitest-cli-compat.mjs run 'apps/web/app/routes/app.$tenant/settings'
node scripts/vitest-cli-compat.mjs run 'apps/web/app/application/sidebar'
```
**Pre-Push zusätzlich** — die bestehenden Suiten der angefassten geteilten Dateien mitlaufen lassen: `settings.workspace-shell.test.tsx`, `settings/tenant-settings-i18n.test.ts`, `settings/tenant-settings-audit-log-copy.test.ts`, `settings/settings-validation-contract.test.ts`, `api/legacy-settings-redirects.test.ts` sowie `tests/e2e/tenant-governance-settings.{desktop,mobile}-a11y.spec.ts` (kennen die aktuelle Settings-Navigation, brechen garantiert). **Nicht** `verify:tenant-isolation-report` regenerieren (Windows-False-Positive).
## Abhängigkeiten
| Blocker | Status | Auswirkung |
|---|---|---|
| `AK-P21` | offen — auf `fix/ak-p21-audit-restwork` liegen uncommittete Änderungen an `privacy-tenant-deletion*.ts`, `privacy-gdpr.server.ts` und eine neue Migration | **Hub F erst nach dem AK-P21-Merge bauen** (User-Entscheidung 2026-07-21). Slices 0-3, 5 (A/B/C/E) sind unabhängig. |
## Risiken
1. **~~URL-Wechsel als Breaking Change~~ — geprüft 2026-07-21, Ergebnis in Slice 2b.** E-Mail-Templates sind **nicht** betroffen (Entwarnung). Dafür hardcoden ~25 Produktionsdateien Settings-URLs, darunter Command-Palette, Suchindex und die App-Chrome-Menüs. Der Suchindex ist der unangenehmste Fall, weil er URLs **persistiert** — dort reicht ein Code-Fix nicht, es braucht einen Re-Index. Behandelt als eigener Slice 2b, DoD 14.
2. **Gemischte Route-Konvention.** Punkt- und Ordner-Notation nebeneinander; ohne den Manifest-Snapshot aus Slice 0 verschwindet beim Umzug still eine Route.
3. **Eltern-Loader läuft für Kinder.** Betrifft `subscription.tsx` (dokumentiert) — beim Umzug jedes weiteren Hubs prüfen, ob unter dem Alt-Pfad Endpoint-Kinder hängen.
4. **Ticket-Deckung.** Diese Doc ist repo-only getrackt (kein Plane-Ticket), analog zur inzwischen gelöschten AK-UI-Serie (`AK-UI-ENTFALLEN.md`). Der Plan wurde am 2026-07-21 mit dem User abgestimmt und freigegeben.
## Quellen
- `AGENTS.md` (Layer-Trennung Block A, Reachability B6-B12, DoD D18-D21, Ticket-Treue)
- `.planning/INTERIM-UI-PLAYBOOK.md`, `.planning/INTERIM-UI-DESIGN-STANDARDS.md` (AD-28)
- `docs/AGENT-CHECKLIST.md` (Pre-Push)
- Live-Befund 2026-07-21 an `app.localhost:3000`, Tenant `hivegrid-demo`
## Abhängigkeitsnachzug · CR-007 · 2026-07-27
Der Gruppen-Tab ist nicht mehr vom globalen `row-groups`-Flag abhängig. Rail,
Hub und Direkt-Route verwenden ausschließlich `app.settings.groups.full`.
@@ -0,0 +1,64 @@
# AK-UI · Serie entfallen und gelöscht (2026-07-25)
| | |
|---|---|
| **Typ** | Tombstone / Doku-Hinweis |
| **Owner** | Akeshan |
| **Status** | abgeschlossen — Serie gelöscht |
| **Stand** | 2026-07-25 |
| **Tracking** | nur Git-Repo — es gab nie Plane-Tickets zur AK-UI-Serie |
## Was passiert ist
Die komplette `AK-UI-*`-Serie (`AK-UI-01` bis `AK-UI-28` plus `AK-UI-README.md` und
`AK-UI-VISUAL-FIDELITY-PLAN.md`) wurde am **2026-07-25 gelöscht**.
Grund: Die UI wurde im Nachgang **direkt am Produkt nach Gefühl überarbeitet** statt entlang dieses
Backlogs. Die Tickets haben dadurch keine Anwendung mehr gefunden, wurden nicht weiterverfolgt und
sind zum Zeitpunkt der Löschung inhaltlich überholt gewesen. Sie beschreiben einen Interim-UI-Nachzug,
den es in dieser Form nicht mehr gibt.
Damit ist die Serie **kein offener Backlog mehr**. Es gibt nichts daraus nachzuholen; wer auf eine
`AK-UI-XX.md` stößt, findet hier die Auflösung.
## Was die Serie war
Ein Backlog aus dem Raw-UI-Audit vom 2026-07-13: atomare Agentenpakete für AD-28-Interim-Screens
(Delivery) und Retain/Remove-Entscheidungen zu Legacy-Flächen (Triage), plus ein
Visual-Fidelity-Nachzug für bereits laufende Interim-Screens.
Stand bei der Löschung:
| ID | Thema | Status bei Löschung |
|---|---|---|
| AK-UI-01 | E-Mail-Inbox Liste | umgesetzt |
| AK-UI-02 | E-Mail-Nachricht Detail | umgesetzt |
| AK-UI-03 | E-Mail verfassen | umgesetzt |
| AK-UI-04 | Globale Suche | entfiel bereits vorher (superseded durch `R-P11a`) |
| AK-UI-05 | Tenant-Plugin-Katalog | umgesetzt |
| AK-UI-06 | Plugin-Audit-Detail | geplant, nie gebaut |
| AK-UI-07 | E-Mail-Integrations-Setup | geplant, nie gebaut |
| AK-UI-08–13 | Plattform-Admin-Kernflächen (Dashboard, Tenants, Billing, Jobs/Health, Deploys/System/Webhooks) | geplant, nie gebaut |
| AK-UI-14–27 | Triage: Form-Builder, Workflow-Engine, Knowledge-Base, Marketing-/Admin-Legacy, Privacy, Legal | geplant, nie entschieden |
| AK-UI-28 | Visual-Fidelity-Audit bestehender Interim-Screens | geplant, nie durchgeführt |
Die als **umgesetzt** markierten Tickets (01, 02, 03, 05) sind im Code bereits geliefert. Deren
Artefakte bleiben unangetastet und sind weiterhin gültig, unter anderem:
- `apps/web/app/components/screens/**` (Inbox-, Detail-, Compose- und Plugin-Katalog-Screens)
- `packages/ui-mock/visual-baseline/ak-ui-0*.html` (Interim-Visual-Baselines)
- `tests/e2e/email-inbox.spec.ts` und die zugehörigen VM-Tests
Die Dateinamen mit `ak-ui-`-Präfix bleiben aus Stabilitätsgründen erhalten; sie verweisen ab jetzt
nur noch historisch auf diese gelöschte Serie.
## Wo noch AK-UI erwähnt wird
- `.planning/ticket-docs/AK-SET-01.md` — nutzt die Serie nur als Beispiel für repo-only-Tracking.
- Dieses Ticket ist die kanonische Repo-Evidenz dafür, dass `AK-UI-*` entfällt.
- Code- und Testdateien mit `ak-ui-`-Präfix (siehe oben).
## Historie
Die gelöschten Docs sind in der Git-Historie vollständig erhalten. Letzter Stand vor der Löschung:
`git show <commit-vor-dieser-loeschung>:.planning/ticket-docs/AK-UI-README.md`.
@@ -1,12 +1,12 @@
# BILL-01 · Lago-Staging sauber betreiben
| | |
|---|---|
| **Typ** | Setup/Infra |
| **Owner** | Raffael |
| **Phase** | Billing-Recut nach AD-27 |
| **Cycle/Fenster** | nach `BILL-00` |
| **Status** | Umgesetzt / bereit fuer Review |
| | |
| ----------------- | ------------------------------ |
| **Typ** | Setup/Infra |
| **Owner** | Raffael |
| **Phase** | Billing-Recut nach AD-27 |
| **Cycle/Fenster** | nach `BILL-00` |
| **Status** | Umgesetzt / bereit fuer Review |
## Abhaengigkeiten & Parallelitaet
@@ -29,11 +29,13 @@ aber nicht mit Production gemischt.
- Frontend `http://127.0.0.1:8188`
- API `http://127.0.0.1:3108`
- Verifiziert 2026-07-04: API `GET /health` liefert `Success`; Frontend liefert `200 OK`.
- Aktualisiert 2026-07-28: Lago `v1.50.0`; API, Worker, Billing-Worker und der
periodische Clock-Scheduler laufen auf demselben Zielstand.
## Definition of Done
- [x] Lago laeuft als Coolify-Resource, nicht als manueller Raw-Compose-Stack.
- [x] API, Frontend, DB, Redis, Worker, Billing-Worker und PDF-Service starten.
- [x] API, Frontend, DB, Redis, Worker, Billing-Worker, Clock-Scheduler und PDF-Service starten.
- [x] Alte manuelle Pilot-Instanz entfernt.
- [x] Zugriffsmodell festgelegt: Public Operator-UI via Lago-Login; API intern ueber Mesh, SSH-Tunnel als Fallback.
- [x] Backup-Konzept fuer Lago-Postgres dokumentiert und Restore-Pfad definiert.
@@ -45,7 +47,7 @@ aber nicht mit Production gemischt.
## Technische Bausteine
- Coolify Docker-Compose-Resource mit `getlago/api:v1.27.1`, `getlago/front:v1.27.1`, Postgres 15, Redis 7.
- Coolify Docker-Compose-Resource mit `getlago/api:v1.50.0`, `getlago/front:v1.50.0`, Postgres 15, Redis 7.
- Keine Public-Domain ohne Auth.
- Keine Production-Daten.
- Runbook: `docs/ops/lago-staging.md`.
@@ -65,6 +67,24 @@ Invoice-PDF-Storage-Entscheidung, Upgrade/Rollback und Testdaten-Konvention steh
und durch Lago-Login geschuetzt; die HiveGrid-zu-Lago-API bleibt intern ueber `http://10.42.0.4:3108`. Invoice-PDFs
liegen im Hetzner-Bucket `hivegrid-staging-lago`; Kunden-Downloads laufen ueber HiveGrid.
2026-07-28: Lago-Staging kontrolliert von `v1.27.1` auf `v1.50.0` aktualisiert. Die Pflicht-Bridges
`v1.28.1`, `v1.30.0`, `v1.31.0`, `v1.32.0`, `v1.42.0`, `v1.43.0`, `v1.44.0` und `v1.45.0` wurden
mit den jeweiligen Backfills durchlaufen. Vorher wurde ein verschluesseltes Postgres-Backup in eine
Wegwerf-Datenbank restored; Proof: `6` Kunden, `16` Subscriptions, `27` Rechnungen. Vor dem Ziel-Deploy
wurde ein zweites `v1.45.0`-Archiv validiert. Der fehlende offizielle `api-clock`-Dienst wurde ergaenzt
und plant `26` periodische Billing-Jobs ein.
Abschluss-Proof 2026-07-28: API lokal und ueber Mesh meldet `v1.50.0`; `0` offene DB-Migrationen;
Kernbestand unveraendert (`1` Organisation, `6` Kunden, `4` Plaene, `16` Subscriptions, `27` Rechnungen);
Queues ohne Pending/Retry/Dead-Jobs; echter Operator-Login erfolgreich; REST-API HTTP 200; Fixed-Charges
im Plan-Contract verfuegbar; vorhandene S3-Rechnung als `application/pdf` mit gueltigem `%PDF`-Header
geladen; laufende HiveGrid-Staging-API erreicht Lago ueber Mesh mit HTTP 200. Ein frisches verschluesseltes
`v1.50.0`-Post-Upgrade-Backup wurde erneut in eine Wegwerf-Datenbank restored und reproduzierte
`6` Kunden, `16` Subscriptions und `27` Rechnungen.
**Fortschritt:** `BILL-01`: 8/8 DoD = 100 % done.
Proof:
- `docs/ops/lago-staging.md`
- `git diff --check`
@@ -1,12 +1,12 @@
# BILL-03 · Lago-Gateway fuer Customers, Plans, Subscriptions und Invoices
| | |
|---|---|
| **Typ** | Dev (Code) |
| **Owner** | Raffael |
| **Phase** | Billing-Recut nach AD-27 |
| **Cycle/Fenster** | nach `BILL-01`/`BILL-02` |
| **Status** | Umgesetzt / bereit fuer Review |
| | |
| ----------------- | ------------------------------ |
| **Typ** | Dev (Code) |
| **Owner** | Raffael |
| **Phase** | Billing-Recut nach AD-27 |
| **Cycle/Fenster** | nach `BILL-01`/`BILL-02` |
| **Status** | Umgesetzt / bereit fuer Review |
## Abhaengigkeiten & Parallelitaet
@@ -50,13 +50,51 @@ ueber Lago, aber UI-Komponenten sprechen nie direkt mit Lago.
Webhook-Event-Parsing und idempotente Outbox-Args fuer `billing.lago.sync`. Die API-Konfiguration kennt jetzt
`LAGO_API_URL`, `LAGO_API_KEY`, `LAGO_WEBHOOK_SECRET` und `LAGO_TIMEOUT_MS`; `.env.example` ist aktualisiert.
Bewusst noch nicht gebaut: Customer-facing UI, Mollie-Zahlung und echte Worker-Ausfuehrung des Syncs. Der
idempotente Pull/Webhook-Sync ist als Outbox-Event-Kontrakt definiert und wird in `BILL-05` konsumiert.
Bewusst noch nicht gebaut: Customer-facing UI und Mollie-Zahlung. Der ausgehende Pull-Sync ist als
Outbox-Event-Kontrakt definiert und wird in `BILL-05` konsumiert.
2026-07-28: Den zuvor nur als Parser-/Outbox-Vertrag vorhandenen Lago-Webhook als echte API-Grenze
`POST /v1/billing/lago/webhooks` geschlossen. Die Route verarbeitet das reale Lago-v1.50-Format mit
verschachteltem `subscription`-/`invoice`-/`customer`-Objekt, prueft den Base64-HMAC ueber den unveraenderten
Request-Body in konstanter Zeit und verlangt `X-Lago-Signature-Algorithm` sowie `X-Lago-Unique-Key`.
Rate-Limits laufen vor Body-Parsing; erst nach erfolgreicher Signatur wird der eingebettete Tenant per RLS
gebunden. Basisplan-Subscription-Events landen replay-sicher in
`IdempotencyKey(scope=billing:provider-sync)`. Pending-, Invoice-, Customer-, unbekannte Plan- und
Add-on-Events werden ohne Subscription-Mutation bestaetigt; damit kann ein generisches Lago-Event weder den
Basisplan ersetzen noch den separaten, Mollie-gezaeunten Product-Acquisition-Ledger umgehen. OpenAPI,
Route-/CSRF-Inventar und Klartext-Fehler wurden nachgezogen.
Proof:
- `pnpm --filter @hivegrid/billing typecheck`
- `pnpm --filter @hivegrid/billing test`
- `pnpm --filter @hivegrid/config test`
- `pnpm exec vitest run packages/db/src/billing-sync.server.test.ts apps/api/src/billing/lago-webhook-route.test.ts apps/api/src/route-access-inventory.test.ts apps/api/src/route-access-inventory-doc.test.ts apps/api/src/csrf-inventory.test.ts apps/api/src/openapi.test.ts packages/billing/src/sync-outbox.test.ts`
- `pnpm --filter @hivegrid/api typecheck`
- `pnpm exec eslint packages/billing/src/webhook.ts packages/billing/src/sync-outbox.test.ts apps/api/src/billing/lago-webhook-route.ts apps/api/src/billing/lago-webhook-route.test.ts apps/api/src/public-ingress-rate-limit.ts apps/api/src/app.ts apps/api/src/openapi.ts apps/api/src/openapi.test.ts apps/api/src/route-access-inventory.ts apps/api/src/route-access-inventory.test.ts apps/api/src/csrf-inventory.test.ts --max-warnings=0`
2026-07-29: Den Lago-v1.50-Webhook auf Staging ausgerollt und den
Provider-Vertrag live geschlossen. Der Lago Workspace hat genau einen
HMAC-Webhook-Endpunkt. Ein signierter `subscription.started`-Event fuer die
kanonische aktive `business`-Subscription von `demo-pro-crm` wurde einmal
synchronisiert; der identische Replay wurde als Replay quittiert. Danach
existierten exakt ein Idempotency-Datensatz, ein Audit-Event und ein
Activity-Eintrag, der lokale Zustand blieb `business|active`.
Vor dem Live-Proof wurden sechs veraltete synthetische Parallel-Subscriptions
ohne Abschlussrechnung oder Gutschrift terminiert. Genau eine aktive
`business`-Subscription bleibt; der Rechnungsbestand blieb bei `27`. Der
Cleanup ist ueber den verschluesselten Post-Upgrade-Snapshot
wiederherstellbar.
Live-Proof:
- PR `#287`, Merge-Commit `ba1e14c12`
- Unsigned Probe HTTP `401`
- Signierter Erstlauf `synced`, Replay `replayed`
- Persistenz nach Replay: `1` Idempotency-Key, `1` Audit-Event, `1` Activity
**Fortschritt:** `BILL-03`: 8/8 DoD = 100 % done.
## Quellen
@@ -78,3 +78,15 @@ Proof:
- `pnpm run typecheck`
DoD: 8/8 = 100 % done.
### 2026-07-28 · Abhaengigkeits-Nachzug aus BILL-03
- Die produktive API-Grenze fuer Lago-v1.50-Subscription-Events ruft den bestehenden
`applyLagoSubscriptionSync` jetzt tenantgebunden und mit dem gehashten
`X-Lago-Unique-Key` als persistentem Replay-Schluessel auf.
- Nur im lokalen Catalog als `base_plan` bekannte Lago-Plaene duerfen den Basiszustand veraendern.
Add-on-Events bleiben beim getrennten Product-Acquisition-Ledger und koennen dessen Fence nicht umgehen.
- Der bestehende State-, Audit-, Activity- und Idempotenz-Vertrag bleibt unveraendert; die BILL-05-Konsumenten
bleiben gruen.
**BILL-05: 8/8 DoD = 100 % done.**
@@ -1,12 +1,12 @@
# BILL-06 · Interne Admin-Billing-Basis
| | |
|---|---|
| **Typ** | Dev/UI ohne finale Screens |
| **Owner** | Raffael |
| **Phase** | Billing-Recut nach AD-27 |
| **Cycle/Fenster** | nach `BILL-05` |
| **Status** | Done |
| | |
| ----------------- | -------------------------- |
| **Typ** | Dev/UI ohne finale Screens |
| **Owner** | Raffael |
| **Phase** | Billing-Recut nach AD-27 |
| **Cycle/Fenster** | nach `BILL-05` |
| **Status** | Done |
## Abhaengigkeiten & Parallelitaet
@@ -61,6 +61,14 @@ in Lago/Mollie zu arbeiten.
**BILL-06: 7/7 DoD = 100 % done.**
2026-07-28 · Abhaengigkeits-Nachzug aus BILL-03
- Der manuelle Admin-Pull-Sync bleibt als operatorgesteuerter Recovery-Pfad bestehen.
- Die neue signierte Lago-Push-Grenze nutzt denselben lokalen Sync-Service, aendert aber weder Admin-Actions
noch deren Berechtigungs-, Audit- oder Klartext-Vertrag.
**BILL-06: 7/7 DoD = 100 % done.**
## Nicht im Scope
- Finales Customer-Billing-Center.
@@ -1,12 +1,12 @@
# BILL-07 · Billing E2E Sandbox-Flow
| | |
|---|---|
| **Typ** | Dev/Test |
| **Owner** | Raffael |
| **Phase** | Billing-Recut nach AD-27 |
| | |
| ----------------- | ---------------------------- |
| **Typ** | Dev/Test |
| **Owner** | Raffael |
| **Phase** | Billing-Recut nach AD-27 |
| **Cycle/Fenster** | nach `BILL-03` bis `BILL-06` |
| **Status** | Done |
| **Status** | Done |
## Abhaengigkeiten & Parallelitaet
@@ -136,3 +136,14 @@ DoD: 8/8 = 100 % done.
- Beispielrechnung `HIV-6711-002-008` fuer `demo-pro-crm` erzeugt und ueber HiveGrid-Kundendownload geprueft:
`200 application/pdf`, Dateiname `HIV-6711-002-008.pdf`, Footer im PDF-Text vorhanden.
- DoD bleibt: 8/8 = 100 % done.
2026-07-28 Nachtrag Lago-v1.50-Webhook:
- Der Live-Sandbox-Flow bekommt zusaetzlich die signierte API-Grenze
`POST /v1/billing/lago/webhooks`.
- Vor Aktivierung des Endpoints in Lago muessen die HiveGrid-Staging-API mit dem Lago-Organisations-HMAC
uebereinstimmen und der neue API-Stand deployed sein; die bisherige Staging-Route liefert erwartungsgemaess
noch `404`.
- Der lokale Contract-Proof deckt gueltige Signatur, manipulierten Body, fehlende Header, Replay,
Tenant-RLS, Pending-Subscription, unbekannten Tenant und die Abgrenzung zum Add-on-Ledger ab.
- DoD bleibt: 8/8 = 100 % done.
@@ -1,18 +1,23 @@
# BILL-08 · Billing Production Prep
| | |
|---|---|
| **Typ** | Setup/Infra |
| **Owner** | Raffael |
| **Phase** | Billing-Recut nach AD-27 |
| **Cycle/Fenster** | spaeter, erst wenn Production-Billing wirklich gebraucht wird |
| **Status** | Geparkt / nicht fuer aktuellen Staging-Test erforderlich |
| | |
| ----------------- | ------------------------------------------------------------------------------------- |
| **Typ** | Setup/Infra |
| **Owner** | Raffael |
| **Phase** | Billing-Recut nach AD-27 |
| **Cycle/Fenster** | Production-Foundation am 2026-07-27 freigegeben; Live-Billing weiter extern blockiert |
| **Status** | In Arbeit · Lago Production provisioniert, Mollie-/Legal-Gates offen |
## Abhaengigkeiten & Parallelitaet
- **Blocked by:** Firmierung/Rechnungssteller-Entscheidung, Mollie-Live-Verifizierung.
- **Blocked by:** Firmierung/Rechnungssteller-Entscheidung,
Mollie-Live-Verifizierung sowie `BILL-23` für den finalen versionierten
Production-Speicherkatalog.
- **Blocks:** produktives Self-Service-Billing.
- **Aktuelle Entscheidung 2026-07-04:** Prod-Billing wird jetzt nicht weiter verfolgt; getestet wird ueber Staging.
- **Aktuelle Entscheidung 2026-07-27:** Die getrennte Production-Foundation wird
provisioniert und per Restore-Drill abgesichert. Echte Zahlungen,
Self-Service-Checkout und Provider-Side-Effects bleiben bis `EXT-16`
fail-closed.
## Was wir bauen
@@ -54,9 +59,66 @@ Hetzner-Kapazitaet limitiert ist, aber mit eigener Resource, eigener DB, eigenem
Kein Public-Lago-Zugang als Default; Operator-Zugriff intern/SSH-Tunnel, Authentik-gated Admin spaeter nur bei Bedarf.
Backup-/Restore-Drill, Secret-Liste, Mollie-Live-Gates und Rollback-Pfad stehen in `docs/ops/lago-production-prep.md`.
2026-07-27: Nach expliziter Operator-Freigabe wurde `lago-production` auf dem
Production-Worker provisioniert. Eigene Postgres-/Redis-Volumes, eigene
Production-Secrets und der private, versionierte Bucket
`hivegrid-prod-lago` sind aktiv. Die API ist nur im privaten Hetzner-Netz
erreichbar; öffentliche Lago-Ports und DNS fehlen absichtlich. Die leere
Production-Organisation wurde angelegt, Signup danach wieder geschlossen.
Der tägliche verschlüsselte Backup-Job ist aktiv. Snapshot `3d8a1deb` wurde in
einer vollständigen Disposable-Topologie wiederhergestellt und per
API-/DB-/S3-Probe verifiziert. Mollie Live bleibt unkonfiguriert;
`PRODUCT_ACQUISITION_PROVIDER_SIDE_EFFECT_REQUIRED=false` hält den
Provider-Subscriber fail-closed.
2026-07-28: `lago-production` kontrolliert von `v1.27.1` auf `v1.50.0`
aktualisiert. Die Pflicht-Bridges `v1.28.1`, `v1.30.0`, `v1.31.0`, `v1.32.0`,
`v1.42.0`, `v1.43.0`, `v1.44.0` und `v1.45.0` wurden mit den jeweiligen
Required Jobs durchlaufen. Snapshots `cc8c5c88` (vor Upgrade), `3c245001`
(Bridge `v1.45.0`) und `176fdf80` (nach Upgrade) wurden jeweils in der
disposable Production-Topologie wiederhergestellt. Der Restore-Drill prüft
jetzt zusätzlich den neuen `api-clock`-Dienst.
Abschluss-Proof 2026-07-28: private API meldet `v1.50.0`; `0` offene
DB-Migrationen; Production-Bestand unverändert (`1` Organisation, `1` API-Key,
sonst keine Billing-Daten); Queues ohne Pending/Retry/Dead-Jobs; PDF-Service
HTTP 200; Object-Storage-HEAD erfolgreich; laufende HiveGrid-Production-API
erreicht Lago authentifiziert mit HTTP 200. Der Provider-Side-Effect-Gate
bleibt `false`; Mollie Live ist weiterhin nicht aktiviert.
**Fortschritt:** `BILL-08`: 5/7 DoD = ~71 % done. Offen: 2 externe Gates
(`Mollie-Live-Konto`, `Rechnungssteller-/Steuer-/Impressumsdaten`).
Selbst machbarer Dev-/Ops-Anteil 5/5 = 100 %.
2026-07-29 · Abhaengigkeitsnachzug aus `BILL-11`:
- Der Production-Katalog Core / Swarm / Colony ist katalogseitig provisioniert
und driftfrei zu Staging.
- Der Side-Effect-Gate bleibt `false`; es wurde keine Production-Zahlung
ausgeloest.
- Das dokumentierte EUR-1.000-SEPA-Transaktionslimit wird nicht mehr als
externe Limiterhoehung vorausgesetzt. `BILL-21` erzwingt fuer jeden
Bruttobetrag ab 1.000,01 EUR eine Kartenautorisierung; bereits Colony liegt
mit 19 % Umsatzsteuer darueber.
- Die erste Mandatserteilung nutzt eine kundenpraesente Zahlart mit
`sequenceType=first`; echte Folgeeinzuege nutzen erst danach
`sequenceType=recurring`.
Proof:
- `docs/ops/lago-production-prep.md`
- `git diff --check`
- `workflows/hivegrid-lago-backup` und
`workflows/hivegrid-lago-restore-drill` im `infra`-Repo
- Cloud Runtime-Gate `85fac5bb7`; Infra Backup/Restore `936a32a`;
Clock-Restore `cfbe109` / normaler Merge `f7abfda`
- Restic-Snapshots `3d8a1deb`, `cc8c5c88`, `3c245001`, `176fdf80`;
Restore-Drills 2026-07-27 und 2026-07-28
- `BILL-11` Production-Verify und Promote Run `11477`: identischer
Katalog-Digest, alle Runtime-Ressourcen gesund, Side-Effect-Gate weiterhin
`false`, kein Mollie-Key und keine Production-Zahlung
- `pnpm typecheck`, `pnpm lint`, `pnpm test` (7.840 grün, 60 übersprungen),
`verify:production-docs`, `verify:production-docs-baseline`,
`git diff --check`
## Quellen
@@ -65,3 +127,51 @@ Proof:
- `BILL-07`
- `EXT-16`
- `docs/ops/lago-production-prep.md`
2026-08-02 · Abhängigkeitsschutz für `BILL-21`
- `BILL-21` ersetzt ausschließlich das zusätzliche SEPA-Limit-Gate durch eine
fail-closed Kartenregel. Mollie-Live-KYC sowie Rechnungssteller-/Steuer-/
Impressumsfreigabe bleiben die zwei externen Gates.
- `BILL-08` bleibt 5/7 DoD = ~71 % done; 2 Punkte extern blockiert, 0 Punkte
selbst machbar.
2026-08-02 · Abhängigkeitsschutz für `BILL-22`
- `BILL-22` schließt die freie Kartenwahl unterhalb der Grenze, den
mandatsicheren Folgeeinzug und den geführten Pilot-Checkout. Mollie-Live-KYC
sowie Rechnungssteller-/Steuer-/Impressumsfreigabe bleiben die zwei externen
Production-Gates unverändert.
- `BILL-08` bleibt 5/7 DoD = ~71 % done; 2 Punkte extern blockiert, 0 Punkte
selbst machbar.
2026-08-02 · Abhängigkeitsschutz für `BILL-23`
- `BILL-23` hat den finalen versionierten Speichervertrag auf Staging
synchronisiert und live verifiziert. Technische Plan-/Add-on-Codes blieben
stabil; der Production-Provider wurde nicht verändert.
- Der Speicher-Katalog ist damit kein offenes Gate mehr. `BILL-08` bleibt
dennoch 5/7 DoD = ~71 % done; Mollie-Live-KYC sowie Rechnungssteller-/
Steuer-/Impressumsfreigabe sind die zwei extern blockierten Punkte, 0 Punkte
selbst machbar.
2026-08-03 · Abhängigkeitsschutz für `BILL-24`
- `BILL-24` zieht das neu buchbare Speicherangebot auf drei wertige
`,99`-Stufen nach und bewahrt den bisherigen 100-GB-Code nur für
Bestandsverträge. Production bleibt bis zum neuen Staging-Katalog- und
Deploy-Proof auf dem unveränderten Stand.
- Die 7 DoD-Punkte von `BILL-08` ändern sich nicht: weiterhin 5/7 = ~71 %
done, 2 externe Gates offen. `BILL-24` ist ein zusätzlicher, aktuell
selbst machbarer Abhängigkeitsschutz vor dem späteren Production-Sync.
2026-08-03 · Abhängigkeitsschutz für `BILL-25`
- `BILL-25` ersetzt die neu kaufbaren Speicherpreise durch eine konservative
5×-Egress-Kalkulation und prüft den vollständigen Staging-Journey-Vertrag
erneut. Der Production-Katalog darf erst nach diesem Proof nachgezogen werden.
- Die zwei externen Gates bleiben unverändert: keine Mollie-Live-Zahlung und
keine Aktivierung produktiver Provider-Side-Effects ohne verifiziertes
Live-Konto sowie freigegebene Rechnungssteller-/Steuer-/Impressumsdaten.
- `BILL-08` bleibt 5/7 DoD = ~71 % done; 2 Punkte extern blockiert. Der
Katalog-Sync aus `BILL-25` darf diese Gates nicht als erledigt markieren.
@@ -0,0 +1,184 @@
# BILL-11 · Pricing-Katalog, Jahresbindung und Recurring Payments
| | |
| ----------------- | --------------------------------------------------------------- |
| **Typ** | Dev + kontrollierter Provider-Sync |
| **Owner** | Raffael |
| **Phase** | Billing-Recut nach AD-27 |
| **Cycle/Fenster** | gestartet 2026-07-29 |
| **Status** | Done |
| **Plane** | HIVEGRID-210 |
## Abhaengigkeiten & Parallelitaet
- **Blocked by:** `BILL-10` (Done). Die technische Arbeit und der Katalog-Sync sind frei.
- **Production-Aktivierung blockiert durch:** `BILL-08` / `EXT-16` fuer Mollie-Live-KYC sowie
Rechnungssteller-, Steuer- und Impressumsfreigabe.
- **Blocks:** produktives Self-Service-Billing, `J-SEO`-Pricing-Inhalte und den finalen
Founding-/Vertriebs-Zahlungsweg.
- **Parallelitaet:** Staging-E2E und Production-Katalog-Provisionierung duerfen parallel vorbereitet werden.
Echte Production-Zahlungen bleiben bis zu den externen Gates fail-closed.
- **Abhaengigkeitsschutz:** Bestehende technische Codes und Tenant-/Webhook-Referenzen
`starter` / `pro` / `business` werden nicht umbenannt. Die neuen Kundennamen sind eine
versionierte Katalogeigenschaft.
## Was wir bauen
Einen einzigen versionierten HiveGrid-Billing-Katalog, der in Staging und Production identisch ausgerollt und
gegen Drift geprueft wird. Die Kundennamen sind:
| Technischer Code | Kundename | Monatlich netto | 12 Monate, monatliche Rate netto | Inklusive Nutzer | Inklusive Speicher |
| ---------------- | --------- | ---------------:| -------------------------------------:| ---------------- | ------------------:|
| `starter` | Core | 199 EUR | 179 EUR | 2 Buero + 5 Baustelle | 100 GB |
| `pro` | Swarm | 499 EUR | 449 EUR | 5 Buero + 15 Baustelle | 250 GB |
| `business` | Colony | 999 EUR | 899 EUR | 10 Buero + 30 Baustelle | 500 GB |
Der Jahresvertrag ist **keine Vorauszahlung von 12 Monatsraten**, sondern eine Mindestlaufzeit von 12 Monaten mit
monatlichem Einzug. Bis 1.000,00 EUR brutto kann der bestehende SEPA-Mandatsweg genutzt werden; ab 1.000,01 EUR
erzwingt `BILL-21` eine Kartenautorisierung. Monatliche Vertraege bleiben monatlich kuendbar. Enterprise bleibt ein individueller,
manuell freigegebener Vertrag und ist kein oeffentlicher Lago-Self-Service-Plan.
Zusatznutzer werden nach Rolle berechnet. Fuer die 12-Monatsbindung gilt jeweils 10 Prozent Rabatt:
| Zusatznutzer | Core monatlich | Swarm monatlich | Colony monatlich |
| ------------ | -------------: | ---------------:| -----------------:|
| Buero | 59 EUR | 39 EUR | 35 EUR |
| Baustelle | 25 EUR | 19 EUR | 15 EUR |
Feste Speicher-Add-ons werden als wiederkehrende Pakete, nicht als verbrauchsbasierte Einzel-GB-Abrechnung,
angeboten: +100 GB fuer 9 EUR, +500 GB fuer 29 EUR, +1 TB fuer 49 EUR und +5 TB fuer 199 EUR netto pro Monat.
## Nicht im Scope
- Echte Production-Zahlungen vor Mollie-Live-KYC und Legal-/Steuerfreigabe.
- Verbrauchsbasierte Abrechnung, Credits oder Einzel-GB-Metering.
- Automatische Enterprise-Angebote.
- Finale Subframe-Optik der Billing-Screens.
- Neue Feature-Unterschiede zwischen Core, Swarm und Colony; alle Pakete enthalten denselben HiveGrid-Core.
## Definition of Done
- [x] Ein kanonischer, versionierter Katalog definiert Core/Swarm/Colony samt stabiler technischer Codes,
Monatsrate, 12-Monats-SEPA-Rate, inkludierten Nutzerrollen, Zusatznutzerpreisen und Speicher.
- [x] Die lokale Preis-/Checkout-Domain berechnet Monats- und 12-Monats-Vertraege korrekt; eine Jahresrate wird
niemals faelschlich als kompletter Jahrespreis oder als einmalige Vorauszahlung behandelt.
- [x] Buero- und Baustellen-Nutzer werden getrennt validiert und oberhalb der Inklusivmengen korrekt berechnet.
- [x] Die vier festen Speicher-Add-ons sind als wiederkehrende Produkte modelliert; es entsteht kein Usage-Metering.
- [x] Der Lago-Katalog-Sync ist idempotent, unterstuetzt Dry-Run/Apply, laeuft als kontrollierter Operator-Workflow
und verwendet keinen Runtime-Seed.
- [x] Staging und Production enthalten denselben Katalog-Contract; ein maschinenlesbarer Driftcheck prueft
Codes, Namen, Intervalle, Preise, Steuern und Katalogversion.
- [x] Der Checkout waehlt die richtige Lago-Planvariante, uebergibt Nutzerrollen/Add-ons und erzwingt fuer die
12-Monatsbindung ein explizites Vertragsende. `BILL-21` bestimmt die Zahlart anhand des Bruttobetrags.
- [x] Der erste Mollie-Einzug erzeugt ein Mandat; spaetere Lago-Rechnungen starten idempotent eine
`sequenceType=recurring`-Zahlung und spiegeln Erfolg/Fehlschlag zurueck nach Lago und HiveGrid.
- [x] Die deutsche 19-Prozent-Umsatzsteuer ist im Katalog vorbereitet. Production bleibt ohne
Rechnungssteller-/Steuerfreigabe und Mollie-Live-Konfiguration fail-closed.
- [x] Staging-E2E prueft mindestens Monatsvertrag, 12-Monatsbindung, Zusatznutzer, Speicher-Add-on,
erste Zahlung und einen simulierten Folgemonat.
- [x] Production-Proof prueft Katalogparitaet und deaktivierte Side-Effects, ohne eine echte Zahlung oder
Kundenrechnung auszulosen.
- [x] Typecheck, Lint, Tests, passende Billing-Verifier, RLS-/Security-Gates und Betriebsdokumentation sind gruen.
**Fortschritt:** `BILL-11`: 12/12 DoD = 100 % done. Offen im Ticket: nichts.
Extern blockiert bleibt nur die Production-Live-Aktivierung; sie ist
ausdruecklich nicht Teil dieses Tickets.
## Technische Bausteine
- Kanonischer Katalog im bestehenden `@hivegrid/entitlements`-/Billing-Contract, nicht als zweite Preisquelle.
- Provider-Planvarianten fuer monatlich und 12 Monate bei weiterhin monatlichem Lago-Intervall.
- Explizite Vertragslaufzeit und Rollen-Mengen im lokalen Billing-State; eigenes Billing-Prisma-Schema gemaess AD-21.
- Kontrolliertes Sync-/Drift-CLI fuer Lago Staging und Lago Production mit redigierten Ausgaben.
- Invoice-getriebener Recurring-Payment-Flow ueber vorhandene Billing-Outbox, Lago-Gateway und Mollie-Gateway.
- Bestehende `tenantHasModule()`-/Entitlement-Gates, Audit/Activity und RLS-Kontext bleiben verbindlich.
- Keine Provider-Secrets, Fachdaten oder CRM-Inhalte in Logs, Katalog oder Mollie-Metadaten.
## Rollback
- Katalog-Sync exportiert vor Apply einen redigierten Snapshot und deaktiviert ersetzte Varianten erst nach
erfolgreichem Paritaetscheck.
- Bestehende Subscriptions behalten ihre technischen Codes und Provider-Referenzen.
- Der Recurring-Subscriber kann ueber den bestehenden Production-Side-Effect-Gate deaktiviert werden.
- Ein Code-Rollback darf keine bereits ausgestellte Rechnung oder bestaetigte Mollie-Zahlung loeschen; Korrekturen
erfolgen ueber Gutschrift/Refund und append-only Provider-/Audit-Events.
## Quellen
- `docs/ARCHITECTURE-DECISIONS.md` AD-27
- `.planning/ticket-docs/BILL-08.md`
- `.planning/ticket-docs/BILL-10.md`
- `docs/pricing-draft.md`
- `docs/pricing-draft.md`
- `packages/entitlements/src/seat-packages.ts`
- `docs/ops/lago-staging.md`
- `docs/ops/lago-production-prep.md`
## Umsetzungs-Notiz
2026-07-29 · gestartet
- Plane-Ticket `HIVEGRID-210` angelegt und auf In Progress gesetzt.
- Namensentscheidung aus der historischen D006-Konfiguration uebernommen: Core / Swarm / Colony.
- Technische Codes bleiben migrationsstabil als `starter` / `pro` / `business`.
- Production-Zahlungen bleiben bis `BILL-08` / `EXT-16` fail-closed.
- Der kanonische Katalog `2026-07-29.1` wurde kontrolliert auf Staging und
Production angewandt. Beide Verifies liefern denselben Digest
`a8ba1affd93e1b870d016284457594988c7fc5f58fdf70c3d57be80b3c915b2c`
und keine Drift-Aktion.
- Implementierungs-Proof: `e0f7567fa`, `e9d475a30`, `64f97f65d`,
`c74408076`, `2cdc13c22`, `03f213997`, `a51ff2611`, `ed3503dd1`,
`2017e887e`, `d3b6f6d7a`, `8b17838dc`, `e6b03511c`, `a5c64ad65`.
- Lokaler Proof vor dem Runner: Prisma-Validierung, leere-DB-Migrationsparitaet,
Tenant-Policy-Vertrag, Lint, i18n, Deploy-/Docker-Verifier und 173 fokussierte
Billing-/Webhook-/Worker-Tests gruen. Den vollstaendigen Typecheck und die
komplette Testsuite uebernimmt wegen der lokalen Ressourcenlast der
Gitea-Runner.
2026-07-29 · abgeschlossen
- Der finale Lago-OSS-Fix verwendet fuer ausgewaehlte Seat-/Storage-Mengen
deterministische, unveraenderliche Managed-Plan-Codes statt des nur in
Premium verfuegbaren `plan_overrides`. Identische Plaene werden
wiederverwendet; Drift bricht fail-closed ab. Implementierungs-Commit
`5ec8bd76e`, PR `#292`, normaler Merge `549f708d9`.
- Gitea-PR-CI Run `11474` ist mit 11/11 Jobs gruen, inklusive Typecheck,
Lint, Tests, Build, Docker-Smokes, Datenbank-, API-, MCP-, Realtime-,
Worker- und Security-Gates.
- Staging-Deploy Run `11475` ist gruen. Monats-Preview und
12-Monats-Checkout prueften beide Seat-Rollen und Speicherpakete. Die erste
Mollie-Testzahlung lief kundenpraesent mit iDEAL und
`sequenceType=first`; ein gueltiges Lastschriftmandat entstand.
- Eine simulierte folgende Lago-Rechnung erzeugte genau eine
`directdebit`-Zahlung mit `sequenceType=recurring` ueber EUR 454,22. Nach
dem Mollie-Webhook standen HiveGrid-Ledger und Lago-Rechnung auf bezahlt.
Der Replay desselben Invoice-Events erzeugte keine zweite Zahlung.
- Alle deterministischen Staging-Fixtures wurden entfernt. Der verwendete
Demo-Benutzer zeigt wieder auf `demo-pro-crm`; es bleibt keine offene
Mollie-Fixture-Zahlung.
- Der Production-Driftcheck meldet Katalog `2026-07-29.1`, Digest
`a8ba1affd93e1b870d016284457594988c7fc5f58fdf70c3d57be80b3c915b2c`
und ausschliesslich `noop`. Der Production-Gate bleibt `false`, ein
Mollie-Key ist nicht hinterlegt und es wurde keine Production-Zahlung
ausgeloest.
- Promote Run `11477` ist gruen. App, Admin, Portal, API, MCP, Realtime und
alle fuenf Worker-Gruppen laufen gesund auf Revision `549f708d9`.
**BILL-11: 12/12 DoD = 100 % done.**
2026-08-02 · Abhängigkeitsschutz für `BILL-23`:
- `BILL-23` versioniert ausschließlich Speicherpool und Add-on-Preise neu.
Technische Codes, Laufzeiten, Sitzpreise, Steuervertrag, Lago-Intervall,
Mandate und bestehende Providerreferenzen bleiben stabil.
- Katalog-Sync und Driftcheck müssen den neuen Digest vor `BILL-08` auf
Staging belegen. `BILL-11` bleibt 12/12 DoD = 100 % done.
2026-08-02 · Abhängigkeitsschutz für `BILL-21`
- Der technische Variantencode `annual_sepa` und alle Providerreferenzen
bleiben migrationsstabil. Für Zahlungen bis 1.000,00 EUR bleibt der
bestehende SEPA-Vertrag unverändert; darüber erzwingt der gemeinsame
Payment-Policy-Resolver Karte für Erst- und Folgezahlungen.
- Katalogpreis, Rabatt, Vertragslaufzeit, Lago-Intervall, Rechnungen und
Entitlements bleiben unverändert. `BILL-11` bleibt 12/12 DoD = 100 % done.
@@ -0,0 +1,128 @@
# BILL-12 · Kundenplan-Namen im Billing konsistent anzeigen
| | |
| ----------------- | ------------------------ |
| **Typ** | Dev/QA/Docs |
| **Owner** | Raffael |
| **Phase** | Billing-Recut nach AD-27 |
| **Cycle/Fenster** | gestartet 2026-07-29 |
| **Status** | Done |
| **Plane** | HIVEGRID-211 |
## Abhaengigkeiten & Parallelitaet
- **Blocked by:** `BILL-11` (Done). Der kanonische Katalog Core / Swarm / Colony steht.
- **Blocks:** keinen technischen Vertrag. Der Nachzug stabilisiert die Kundenanzeige, die
`VA-P24a` und spaeter `VD-P24` konsumieren.
- **Parallelitaet:** `BILL-08` / `EXT-16` bleiben unabhaengige externe Production-Gates.
- **Abhaengigkeitsschutz:** Die technischen Codes `starter` / `pro` / `business`, die
Sitzpaket-IDs `starter` / `team` / `business` und alle Provider-Referenzen bleiben
unveraendert. Insbesondere bleibt das Mapping `pro` -> `team` -> `Swarm` erhalten.
## Was wir bauen
Die bestehende Self-Service- und Sitzplatz-UI zeigt die in `BILL-11` festgelegten
Kundennamen Core, Swarm und Colony. Der Katalog bleibt die fachliche Quelle; ein
ausfuehrbarer i18n-Vertrag verhindert, dass deutsche oder englische Anzeigen erneut
auf die alten Paketnamen Starter, Team oder Business zurueckfallen.
Der bei leerer Produktdatenbank sichtbare Boilerplate-Demo-Generator wird entfernt.
Er darf keine alten Basic-/Starter-/Pro-Tarife in USD/MXN oder Usage-Modelle mehr
erzeugen. Ein leerer Admin-Katalog bleibt stattdessen mit Klartext fail-closed;
individuelle pauschale oder einmalige Produkte bleiben separat anlegbar.
Zusaetzlich wird der Billing-Track auf den tatsaechlichen Stand bis BILL-12
nachgezogen. Die bereits erfolgreich erzeugte Staging-Rechnung bleibt als
Betriebs-Proof dokumentiert.
## Nicht im Scope
- Umbenennung technischer Plan-, Sitzpaket- oder Provider-Codes.
- Neue Preise, Laufzeiten, Features oder Usage-Metering.
- Echte Production-Zahlungen vor `BILL-08` / `EXT-16`.
- Mollie-Live-KYC, Legal-/Steuerfreigabe oder Erhoehung des SEPA-Limits.
- Finale Subframe-Optik aus `VD-P24`.
## Definition of Done
- [x] Self-Service-Planwahl und Sitzplatz-Uebersicht zeigen in Deutsch und Englisch
Core, Swarm und Colony.
- [x] Das technische Mapping `starter` / `pro` / `business` zu
`starter` / `team` / `business` bleibt unveraendert und ist fuer den mittleren
Tarif regressionsgetestet.
- [x] Ein ausfuehrbarer Vertrag gleicht die kundenpraesenten i18n-Namen mit dem
kanonischen Commercial Catalog ab.
- [x] Billing-Track und betroffene Downstream-Doku bilden BILL-11/BILL-12 sowie
die getrennten externen `BILL-08`-Gates korrekt ab.
- [x] Der Admin-Billing-Pfad kann keine alten Demo-Tarife oder Usage-Modelle
mehr erzeugen und zeigt einen leeren Katalog mit Klartext fail-closed.
- [x] Fokussierte Billing-/i18n-Tests und passende Verifier sind gruen; der
vollstaendige Typecheck und die Gesamtsuite laufen in CI.
**Fortschritt:** `BILL-12`: 6/6 DoD = 100 % done. Offen: nichts.
## Technische Bausteine
- Bestehende Keys unter `settings.subscription.seats.package.*` und
`settings.subscription.checkout.plans.packages.*.title`.
- Kanonischer Vertrag aus `@hivegrid/entitlements` (`hiveGridBasePlans`).
- Fokussierter i18n-Vertrag fuer `de` und `en`.
- Bestehende Self-Service-Server-Tests fuer das `pro`-/`team`-Mapping.
- Admin-Pricing-Policy ohne Demo-Seed sowie ohne Usage-/Per-Seat-Modell.
## Rollback
- Reiner Anzeige-/Test-/Doku-Nachzug ohne Schema- oder Provider-Mutation.
- Ein Code-Rollback stellt nur die vorherigen Anzeigenamen wieder her; bestehende
Subscriptions, Rechnungen, Zahlungen und Mandate bleiben unveraendert.
## Quellen
- `.planning/ticket-docs/BILL-11.md`
- `.planning/ticket-docs/BILL-08.md`
- `.planning/ticket-docs/VA-P24a.md`
- `.planning/ticket-docs/VD-P24.md`
- `packages/entitlements/src/commercial-catalog.ts`
## Umsetzungs-Notiz
2026-07-29 · gestartet
- Saubere Worktree `/tmp/hivegrid-bill-12` auf aktuellem `origin/main`
(`ca96e036d`) und Branch `fix/billing-followup-20260729` angelegt.
- Audit bestaetigt: Provider-Katalog, Checkout-Success und Rechnungen verwenden
bereits Core / Swarm / Colony. Veraltet sind die kundenpraesenten
Self-Service-/Sitzpaket-Uebersetzungen.
- Zweiter Audit-Fund: Die Admin-Tarifseite bietet bei leerer Datenbank noch
Boilerplate-Demo-Plaene in USD/MXN und Usage-Modelle aus `plans.server.ts` an.
Dieser nicht-kanonische Schreibpfad wird in BILL-12 entfernt.
- Externe Gates bleiben ausschliesslich in `BILL-08` / `EXT-16`.
- Plane-Identitaet als `raffael@tool-ctrl.de` bestaetigt; `HIVEGRID-211`
angelegt, Raffael zugewiesen und auf In Progress gesetzt.
- Kundenanzeige in `de` und `en` auf Core / Swarm / Colony gezogen und mit
`commercial-plan-names.i18n.test.ts` an `hiveGridBasePlans` gebunden.
- Der mittlere technische Tarif bleibt `pro`, verwendet weiterhin das
Sitzpaket `team` und wird kundenpraesent als Swarm getestet.
- `plans.server.ts`, der zugehoerige Create-all-Schreibpfad und der ungenutzte
`createPlans`-Helper sind entfernt. Die Admin-Policy erlaubt nur noch
pauschale wiederkehrende und einmalige Produkte; Usage- und Per-Seat-Modelle
sind fail-closed.
- Lokaler Proof: 32 fokussierte Tests sowie 21 Katalogtests gruen; zielgerichtetes
ESLint, `verify:i18n`, `verify:billing-catalog`, `verify:docs-links`,
`verify:source-health`, JSON-Validierung und EU-Provider-Import-Guard gruen.
Vollstaendiger Typecheck, Gesamtsuite und der ressourcenintensive
Coverage-Vertrag bleiben bewusst dem Gitea-Runner vorbehalten.
- Der erste PR-CI-Lauf `11521` hat in `PricingPlanForm.tsx` eine nach der
Policy-Verschaerfung unmoegliche TypeScript-Abfrage auf die ausgeschlossenen
Usage-Modelle gefunden. Der redundante Portal-Filter ist entfernt;
zielgerichtetes ESLint und die betroffenen Policy-/Katalogtests sind erneut
gruen. Der vollstaendige CI-Rerun bleibt der letzte offene DoD-Punkt.
- Im zweiten PR-CI-Lauf `11522` waren 10/11 Jobs gruen. Die Gesamtsuite hat als
einzigen Fehler einen veralteten Audit-i18n-Vertrag gefunden, der den
entfernten Demo-Seed-Audit `admin.pricing.createdPlans` noch als aktiven
Route-Call verlangte. Der historische Anzeige-Schluessel bleibt fuer alte
Logs erhalten; der Source-Vertrag prueft nun explizit, dass kein neuer
Demo-Seed-Audit mehr erzeugt wird.
- Abschluss-Proof: PR `#296`, Head `012a8d1b1`, CI-Lauf `11523` mit 11/11
erfolgreichen Jobs. Vollstaendiger Typecheck, Gesamtsuite, Build/Bundle,
Docker-Smoke, Datenbank-Checks und alle Service-Checks sind gruen.
@@ -0,0 +1,263 @@
# BILL-13 · Immersiver Mollie-Checkout und Usage-Transparenz
| | |
| ----------------- | ------------------------------------------------------ |
| **Typ** | Dev/QA + kontrollierter Staging-Provider-Proof |
| **Owner** | Raffael |
| **Phase** | Billing-Recut nach AD-27 |
| **Cycle/Fenster** | gestartet 2026-07-30 |
| **Status** | Done |
| **Plane** | HIVEGRID-212 |
## Abhängigkeiten & Parallelität
- **Blocked by:** kein technischer Blocker. `BILL-10`, `BILL-11` und `BILL-12`
sind Done; der katalog- und webhook-basierte Zahlungsweg steht.
- **Production-Aktivierung blockiert durch:** `BILL-08` / `EXT-16` für
Mollie-Live-KYC, SEPA-Limit und Rechnungssteller-/Steuer-/Impressumsfreigabe.
- **Blocks:** keinen bestehenden Ticketvertrag. Der Slice verbessert den
Pilot-Checkout und schließt beobachtete Self-Service-Lücken.
- **Abhängigkeitsschutz:** Lago bleibt Billing-Source-of-Truth, Mollie bleibt
Payment Processor und HiveGrid bleibt Entitlement-Schicht. Bestehende
technische Produktcodes, Preise, Provider-Referenzen und Quoten ändern sich
nicht.
## Was wir bauen
HiveGrid zeigt die Kaufentscheidung vollständig in der eigenen Billing-Oberfläche:
Preis, Leistung, Wirksamkeit und die aktuell bei Mollie für Betrag und
Zahlungssequenz freigeschalteten Zahlarten. Erst nach der Bestätigung erzeugt
der Server den providerseitigen Checkout und übergibt die gewählte Zahlart an
Mollie. Die eigentliche Bank-, Wallet- oder 3DS-Bestätigung bleibt im sicheren
Mollie Hosted Checkout und wird als Top-Level-Navigation geöffnet.
Wiederkehrende Produktkäufe erhalten eine eigene tenant-gebundene Rückkehrseite,
die den Mollie-Status erneut liest und ausschließlich über den idempotenten
Billing-Sync freischaltet. Für E-Mail-Marketing kann direkt in ein anderes
festes Kontingent gewechselt werden: Das bisherige Paket bleibt bis zur
bestätigten neuen Zahlung aktiv; danach wird es in derselben lokalen
Transaktion beendet und sein exakter Lago-Vertrag über die vorhandene
Outbox gekündigt.
Die Billing-Seite zeigt zusätzlich den realen Speicherverbrauch einschließlich
laufender Upload-Reservierungen sowie die im aktuellen Zeitraum versendeten
E-Mail-Marketing-Sendungen. Die Anzeige ist read-only und erzeugt weder
verbrauchsbasierte Rechnungen noch Credits.
## Nicht im Scope
- Echte Production-Zahlungen vor `BILL-08` / `EXT-16`.
- Einbettung des Mollie Hosted Checkout in ein Iframe.
- Nutzung der privaten Mollie Checkout-Session-/Custom-Components-Beta.
- Eigene Kartenfelder oder Speicherung von Karten-/Bankdaten in HiveGrid.
- Usage-Metering, Einzel-GB-Abrechnung, Credits oder automatische Overages.
- Neue Preise, Tarife, Feature-Unterschiede oder finale Subframe-Optik.
## Definition of Done
- [x] Der Mollie-Gateway-Vertrag lädt aktive Zahlarten nach Betrag, Währung,
Locale und `sequenceType`; Providerantworten und gewählte Methoden werden
strikt validiert.
- [x] Tarif- und E-Mail-Marketing-Checkout zeigen in HiveGrid eine klare
Zusammenfassung samt Zahlart. Mollie übernimmt nur den sicheren
Top-Level-Zahlungsschritt; ein Hosted-Checkout-Fallback bleibt verfügbar.
- [x] Der Server prüft Auswahl, Betrag, Zahlart und SEPA-Vertrag erneut. Eine
manipulierte oder nicht passende Zahlart erzeugt keine Freischaltung.
- [x] Wiederkehrende Produktkäufe kehren auf eine tenant-/permission-gebundene
Statusseite zurück, die den Providerstatus idempotent synchronisiert und
aktive, offene sowie fehlgeschlagene Zahlungen verständlich anzeigt.
- [x] Ein E-Mail-Marketing-Tierwechsel hält das alte Paket bis zur bestätigten
Zahlung aktiv, aktiviert nie zwei Kontingente gleichzeitig und terminiert
das ersetzte Lago-Abo über die bestehende durable Outbox.
- [x] Speicherverbrauch, Upload-Reservierungen und E-Mail-Marketing-Verbrauch
werden RLS-gebunden und read-only in der Billing-VM angezeigt; die
bestehenden atomaren Quotenprüfungen bleiben die Schreib-Grenze.
- [x] Unit-, Route-, Provider-, Webhook-/Sync-, i18n-, A11y-, Visual- und
Hot-Swap-Tests decken Auswahl, Rückkehr, Tierwechsel, Usage sowie
Manipulations-/Fehlerpfade ab.
- [x] Der kontrollierte Staging-Proof validiert Katalogdrift, Mollie-Auswahl,
Redirect/Return, Webhook-Freischaltung, direkten Tierwechsel und Cleanup
ohne offene Testzahlung oder Test-Subscription.
- [x] Typecheck, Lint, vollständige Testsuite, Billing-/RLS-/Security-Verifier,
PR-CI und Staging-Deploy sind grün.
**Fortschritt:** `BILL-13`: 9/9 DoD = 100 % done. Kein selbst machbarer Punkt
offen. Production-Live-Aktivierung bleibt bewusst außerhalb des Ticket-Scopes
und durch `BILL-08` / `EXT-16` blockiert.
## Technische Bausteine
- `@hivegrid/billing`: typisierte Mollie Methods API und validierte
`method`-/`locale`-Übergabe.
- Pure Checkout-/Usage-VMs in `packages/view-models`.
- Bestehende `~/ui`-Komponenten in der `VA-P24a`-Interim-Oberfläche.
- Tenant-gebundene Return-Route und vorhandener `completeProductAcquisition`-
/`applyMolliePaymentSync`-Pfad.
- Bestehende Product-Acquisition-Outbox für die exakte Lago-Terminierung.
- Read-only Usage-Projektionen auf Basis von `OutboundEmail`, `File`,
`FileUpload`, Billing-State und den vorhandenen Quotenservices.
## Rollback
- Die Zahlungsmethoden-Auswahl kann auf den bisherigen Hosted-Checkout ohne
vorausgewählte Methode zurückfallen; Provider-IDs und Mandate bleiben
unverändert.
- Ein Code-Rollback darf bestätigte Zahlungen oder Rechnungen nicht löschen.
Provider-Korrekturen laufen ausschließlich über bestehende
Refund-/Kündigungs- und append-only Audit-/Outbox-Pfade.
- Usage-Anzeigen sind read-only und können ohne Datenmigration entfernt werden.
- Ein begonnener Tierwechsel lässt das alte Kontingent bis zum erfolgreichen
neuen Payment aktiv; fehlgeschlagene oder abgebrochene Zahlungen entziehen
keine bestehende Leistung.
## Quellen
- `docs/CHANGE-REQUESTS.md` CR-008
- `.planning/ticket-docs/BILL-10.md`
- `.planning/ticket-docs/BILL-11.md`
- `.planning/ticket-docs/BILL-08.md`
- `.planning/ticket-docs/EXT-16.md`
- Mollie Docs: Hosted Checkout, Build your own checkout, Methods API,
Create payment und Recurring payments
## Umsetzungs-Notiz
2026-07-30 · gestartet
- Explizite Produktfreigabe im Chat für die offenen Billing-Nachzüge und eine
stärker in HiveGrid eingebettete Mollie-Erfahrung.
- Plane-Identität als `raffael@tool-ctrl.de` bestätigt; `HIVEGRID-212`
angelegt, Raffael zugewiesen und auf In Progress gesetzt.
- Saubere Worktree
`/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud-billing-completion`
auf `origin/main` (`9dfde216e`) und Branch
`feat/billing-checkout-usage-20260730`.
- Preflight-Proof: SOPS-Dev-Env geladen, EU-Provider-Guard leer,
vollständiger Typecheck grün und 8.064 Tests grün (60 übersprungen).
- Offizielle Mollie-Auslegung: Zahlungsmethoden-Auswahl über die Methods API
in HiveGrid, danach Top-Level-Redirect zu `_links.checkout`. Mollie empfiehlt
diesen Weg für einen eigenen Checkout. Der vollständige eingebettete
Components-Checkout ist Private Beta und daher kein Launch-Vertrag.
2026-07-30 · Implementierung und lokaler Proof
- Mollie Methods API wird für Tarif- und E-Mail-Marketing-Checkout nach
Bruttobetrag, Währung, Sequenz, Locale und SEPA-Anforderung geladen; die
gewählte Methode wird unmittelbar vor jeder Provider-Mutation erneut
validiert (`73b92d996`, `7dc123557`, `ebc8fbaa3`).
- Die Billing-Interim-UI zeigt Kaufzusammenfassung, verfügbare Zahlarten und
Hosted-Checkout-Fallback. Der E-Mail-Marketing-Wechsel hält das alte
Kontingent bis zum bestätigten Payment aktiv und beendet es danach lokal
atomar samt exaktem Lago-Outbox-Cleanup (`5d0897404`, `9557be6bb`).
- Produktkäufe kehren über eine tenant-, permission- und RLS-gebundene
Statusroute zurück. Sie pollt ausschließlich den idempotenten
`completeProductAcquisition`-Pfad und unterscheidet aktive, offene,
fehlgeschlagene, abgebrochene, abgelaufene und erstattete Zahlungen
(`05d1b7747`).
- Speicherverbrauch einschließlich laufender Upload-Reservierungen sowie
E-Mail-Sendungen im aktuellen Abrechnungszeitraum sind read-only in der
Billing-VM sichtbar (`4dc218667`).
- Deferred Annual-SEPA ohne belastbaren Nullbetrags-Mandatsweg bricht
fail-closed vor Lago-/Mollie-Mutationen ab; der bestehende Vertrag bleibt
unverändert (`374ce57dc`).
- Lokaler Proof: Root-Typecheck und Lint grün; Core-Suite 8.086 Tests grün
(60 übersprungen); Billing-Paket 54 Tests grün; fokussierte Return-, Billing-
und Portal-Suite 100 Tests grün; i18n 15.228 Keys, Hot-Swap,
Route-Inventar, Billing-/RLS-/Security-Verifier und Sandbox-Flow grün.
- Fresh-DB-Proof: RLS-Rollen auf einer leeren Wegwerf-Postgres-Instanz
provisioniert, alle 25 Migrationen von null angewandt, kanonische lokale
Credentials und E2E-Readiness erzeugt. Der reale Chromium-Flow
Login → Billing → E-Mail-Paket → Zahlungsart/Hosted-Fallback → Abbruch ist
grün. Die Wegwerf-Datenbank wurde danach entfernt.
**BILL-13: 7/9 DoD = ~78 % done. Offen: Staging-Provider-Proof und
PR-CI/Staging-Deploy.**
2026-07-31 · kontrollierter Staging-Proof und Abschluss
- Der kanonische Katalog `2026-07-30.1` mit Digest
`6b64ff563c3077f7010aa74a1c2b0ecbd22bf35536560a4e34ae3c9b1b628064`
wurde auf Staging angewandt. Die anschließende Verifikation meldete alle
16 Ressourcen ohne Drift und ohne weitere Änderung.
- Ein vollständig neu registrierter und verifizierter synthetischer
Staging-Tenant übernahm den gewählten Core-/Starter-Tarif korrekt. Die
HiveGrid-Auswahl zeigte die für den Betrag verfügbaren Mollie-Methoden
einschließlich iDEAL und Wero; eine reale Mollie-Testzahlung wurde im
Hosted Checkout über iDEAL/ABN AMRO abgeschlossen und schaltete den
Basistarif frei.
- E-Mail-Marketing S wurde über denselben echten Checkout bezahlt und danach
direkt auf M gewechselt. Das alte S-Kontingent blieb bis zur bestätigten
M-Zahlung aktiv, wurde anschließend atomar beendet und sein exakter
Lago-Vertrag über die durable Outbox terminiert. Alle zwei
Provider-Side-Effects endeten mit `DONE`, ohne Retry oder Fehler.
- Drei echte Mollie-Webhook-Aufrufe wurden mit HTTP 200 verarbeitet und
hinterließen genau die erwarteten dauerhaften Idempotenz- und Audit-Spuren.
Manipulierte Methoden, offene Zahlungen und der sichere Return-/Polling-Pfad
waren im selben Staging-Flow abgedeckt.
- Beim Cleanup wurde ein echter Lifecycle-Randfall gefunden: Der verwaltete
Lago-Preiscode `hg_price_*_<tarif>_<digest>` wurde bei einer
`subscription.terminated`-Nachricht nicht auf den kanonischen Basistarif
zurückgeführt; außerdem blieb dessen lokales Entitlement bei Kündigung
aktiv. Commit `5fe992bb6` ordnet verwaltete Monats- und
Annual-SEPA-Varianten dem Basistarif zu und beendet auch das
Basistarif-Entitlement.
- Der signierte Replay des echten terminierten Lago-Abos auf der
ausgerollten Fix-Revision wechselte den lokalen Zustand von `past_due` auf
`cancelled`. Danach bestanden 0 aktive Produkte, 0 offene
Add-on-Akquisitionen, 0 pending Checkout-Sessions, 0 unfertige
Outbox-Einträge, 0 Outbox-Retries/-Fehler und 0 aktive Lago-Subscriptions.
Bei Mollie blieben 3 bezahlte und 2 bewusst abgebrochene Testzahlungen,
aber keine offene Zahlung.
- Feature-PR `#298` wurde als normaler Merge
`a4d3381d91441a073a07bc0a4021356cf180646b` übernommen; Staging-Deploy
`11559` war grün. Fix-PR `#300` bestand CI-Run `11564` mit 11/11 Jobs,
wurde als normaler Merge
`e7dfff48209132c5d00480d3e3a389a0072e3fce` übernommen und bestand
Staging-Deploy `11565` einschließlich Migration, Primary- und acht
abhängigen Deploys. API-Health und Readiness meldeten exakt diese Revision.
- Finaler lokaler Proof für den Fix: Root-Typecheck, Lint und vollständige
Core-Suite mit 8.127 grünen Tests (60 übersprungen), 48 fokussierte
Billing-Sync-Tests sowie `verify:ci-baseline` und `verify:source-health`
waren grün.
**BILL-13: 9/9 DoD = 100 % done. Kein selbst machbarer Punkt offen.**
2026-08-02 · Abhängigkeitsschutz für `BILL-21`
- Die bestehende HiveGrid-Auswahl und der Mollie Hosted Checkout bleiben
unverändert. `BILL-21` verengt die serverseitig geladene Methodenauswahl ab
1.000,01 EUR brutto auf `creditcard` und zeigt fehlende
Kartenverfügbarkeit als blockierenden Klartextzustand.
- Unterhalb der Grenze bleiben SEPA-Mandatsmethoden und sonstige von Mollie
für `sequenceType=first` gelieferte Methoden unverändert. `BILL-13` bleibt
9/9 DoD = 100 % done.
2026-08-01 · Post-Close-Regression aus finalem Billing-UAT
- Ein frischer, aktiver Swarm-Tenant mit `storage_100gb` zeigte auf der
Billing-Hauptseite korrekt 350 GB, im separaten Usage-Tab jedoch
„0 BYTES / Kein Limit konfiguriert“.
- Root Cause: Die dedizierte Route nutzte noch die Legacy-Projektion aus
`SubscriptionFeature` und `TenantSubscriptionUsageRecord`; nach dem
RLS-gebundenen Modul-Gate liefen ihre eigenen Reads zudem wieder ohne
gebundenen Tenant-Kontext.
- `BILL-17` korrigiert ausschließlich diese Anzeige über den bereits
kanonischen Storage-Resolver. Checkout, Entitlement, Upload-Grenze, Preise
und Provider-Sync waren im selben UAT korrekt und bleiben unverändert.
**BILL-13: 8/9 DoD = ~89 % done. Offen: `BILL-17` CI, Staging-Deploy und
Live-Proof; kein externer Blocker.**
2026-08-01 · Post-Close-Regression erneut abgenommen
- `BILL-17` / PR `#331` bindet den dedizierten Usage-Read an Tenant-RLS und
verwendet für Speicher dieselbe kommerzielle Kapazitätsprojektion wie
Billing-Hauptseite und Upload-Grenze.
- CI `11690`, normaler Merge `a47d6e13e` und Staging-Deploy `11691` waren
vollständig grün. Der Live-Chromium-Proof zeigt beim aktiven Swarm-Tenant
mit `storage_100gb` exakt 0 Bytes Verbrauch, 350 GB Limit und 350 GB Rest.
- Screenshot `59-final-usage-tab-350gb.png` ergänzt den finalen Desktop-UAT-
Ordner. Checkout, Freischaltung, Rechnungen und Provider-Sync blieben
unverändert und waren im selben Tenant bereits erfolgreich belegt.
**BILL-13: 9/9 DoD = 100 % done. Kein selbst machbarer Punkt offen.**
@@ -0,0 +1,282 @@
# BILL-14 · Registrierung mit Teamgröße und Tarifempfehlung
| | |
| ----------------- | ------------------------------------------------------ |
| **Typ** | Dev/UX + Billing-Übergabe |
| **Owner** | Raffael |
| **Phase** | Billing-Recut nach AD-27 |
| **Cycle/Fenster** | gestartet 2026-07-31 |
| **Status** | Done |
| **Plane** | HIVEGRID-213 |
## Abhängigkeiten & Parallelität
- **Blocked by:** kein technischer Blocker. `BILL-11` und `BILL-13` sind Done
und liefern Katalog, Checkout, Mollie-Return und Freischaltung.
- **Production-Aktivierung blockiert durch:** unverändert `BILL-08` / `EXT-16`
für Mollie-Live-KYC sowie Legal-/Steuerfreigaben.
- **Blocks:** keinen bestehenden Ticketvertrag. Der Slice verbessert den
Registrierungs- und ersten Kauf-Flow.
- **Abhängigkeitsschutz:** technische Plan-/Preis-Codes, Preise, Leistungen,
Lago-/Mollie-Referenzen und bestehende Checkout-Validierung ändern sich nicht.
Neue Registrierungsfelder sind optional und brechen bestehende Pre-Auth-
Konsumenten oder ausstehende Verifizierungen nicht.
## Was wir bauen
Die bestehende Registrierung wird als zweistufiger Wizard dargestellt. Nach den
Konto- und Firmenangaben folgt eine eigenständige Seite „Teamgröße & Tarif“.
Dort gibt der Nutzer die geplanten Büro- und Monteur-/Baustellen-Nutzer an.
HiveGrid berechnet für Core, Swarm und Colony anhand des versionierten
Monatskatalogs den echten Nettopreis aus Grundpreis und Zusatznutzern. Empfohlen
wird deterministisch die günstigste Konfiguration für die eingegebenen Mengen.
Die Empfehlung wird begründet und hervorgehoben, bleibt aber bewusst
überschreibbar.
Die gewählten Mengen und der Tarif werden serverseitig validiert, sowohl im
direkten Signup als auch über die E-Mail-Verifizierung hinweg gespeichert und
beim ersten Billing-Aufruf vorausgefüllt. Die verbindliche Preisberechnung und
Freischaltung bleiben im vorhandenen serverseitigen Billing-/Mollie-Flow.
## Nicht im Scope
- Neue Preise, Tarife, Leistungen, Rabatte oder Feature-Unterschiede.
- Automatische Enterprise-Angebote oder Vertriebs-Lead-Erzeugung.
- Eine verbindliche Bestellung vor dem vorhandenen Billing-/Mollie-Checkout.
- Production-Zahlungen vor `BILL-08` / `EXT-16`.
- Finale Subframe-Optik; die vorhandene Auth-Interim-UI aus `~/ui` wird
konsistent erweitert.
## Definition of Done
- [x] Eine pure, providerunabhängige Funktion berechnet für gültige Büro-/
Monteur-Mengen alle monatlichen Katalogpreise und empfiehlt bei Gleichstand
deterministisch den niedrigeren Tarif.
- [x] Die Registrierung zeigt Kontoangaben und Teamgröße/Tarif als zwei getrennte,
per Tastatur bedienbare Seiten mit Zurück-Navigation und erhaltenen Werten.
- [x] Die Teamgrößen-Seite validiert mindestens einen Büro-Nutzer, null oder mehr
Monteur-Nutzer und die kanonische Obergrenze; Empfehlung, Preisbestandteile
und manuelle Tarifabweichung sind verständlich sichtbar.
- [x] Der Server akzeptiert ausschließlich ganzzahlige, begrenzte Mengen und eine
aktive kanonische Monats-Preis-ID; manipulierte Daten erzeugen keine
Registrierung oder Provider-Mutation.
- [x] Tarif und Mengen werden optional im Pre-Auth-Registrierungsdatensatz
gespeichert, in exakten Replay-/Resend-Prüfungen berücksichtigt und über
die E-Mail-Verifizierung hinweg unverändert übernommen.
- [x] Der erste Billing-Aufruf übernimmt Tarif sowie Büro-/Monteur-Mengen als
reine Präferenz; belegte Sitze und die vorhandene serverseitige
Checkout-Preisvalidierung bleiben die verbindlichen Untergrenzen.
- [x] Unit-, Component-, Route-, DB-, i18n-, A11y-, Visual- und Hot-Swap-Tests
decken Empfehlung, Override, Rücknavigation, Persistenz, Manipulation und
Billing-Prefill ab.
- [x] Die Forward-only-Migration ist von einer leeren Datenbank reproduzierbar,
enthält Inverse-SQL als Kommentar und verändert keine RLS-Policy.
- [x] Typecheck, Lint, vollständige Testsuite, Billing-/RLS-/Security-Verifier,
PR-CI und Staging-Deploy sind grün.
**Fortschritt:** `BILL-14`: 9/9 DoD = 100 % done. Kein selbst machbarer Punkt
offen.
## Technische Bausteine
- Kanonischer `@hivegrid/entitlements`-Katalog und dessen vorhandene
Preisberechnung; keine zweite Preisquelle in der UI.
- Bestehender `RegisterScreen` mit `~/ui`-Primitives und VM-/Callback-Daten.
- Optionale Mengenfelder auf `Registration` im bestehenden `accounts.prisma`-
Vertrag; keine neue Tabelle und kein neuer RLS-Umfang.
- Tenant-dauerhafte Signup-Präferenz auf der bestehenden, RLS-geschützten
`TenantProductConfiguration`; kein vorgezogenes Abo und kein Checkout-Dummy.
- Bestehende Registration-Capabilities, Replay-Grenzen und Verification-Flow.
- Erweiterte optionale `preferredSelection` in der Billing-VM; Checkout bleibt
serverseitig autoritativ.
## Rollback
- UI- und Empfehlungs-Slice können atomar zurückgerollt werden; die bisherigen
Plan-Karten bleiben als kompatibler Fallback nutzbar.
- Die zwei neuen Datenbankspalten sind optional. Ein Code-Rollback ignoriert sie
sicher; Inverse-SQL zum späteren kontrollierten Entfernen steht in der
Migration.
- Bereits gestartete oder bestätigte Zahlungen werden nie gelöscht oder
verändert. Providerkorrekturen bleiben im bestehenden append-only
Billing-/Webhook-Pfad.
## Quellen
- `docs/CHANGE-REQUESTS.md` CR-009
- `.planning/ticket-docs/BILL-11.md`
- `.planning/ticket-docs/BILL-13.md`
- `packages/entitlements/src/commercial-catalog.ts`
- `docs/AGENT-CHECKLIST.md`
## Umsetzungs-Notiz
2026-08-01 · Abhängigkeitsschutz für BILL-18
- `BILL-18` überarbeitet ausschließlich Darstellung und CAPTCHA-Retry des hier
gelieferten Registrierungsflows. Tarifkatalog, serverseitige Empfehlung,
Sitzgrenzen, persistierter Checkout-Prefill und alle Mollie-/Lago-
Folgeverträge bleiben unverändert.
2026-08-02 · Abhängigkeitsschutz für BILL-19
- `BILL-19` stellt den bestehenden ersten Billing-Aufruf als eigenen
Aktivierungszustand dar. Persistierte Präferenz, Katalog, Preisvorschau,
Mollie-/Lago-Checkout und Entitlement-Aktivierung aus diesem Ticket bleiben
autoritativ und unverändert.
2026-07-31 · gestartet
- Explizite Produktfreigabe im Chat für eine separate Registrierungsseite mit
Büro-/Monteur-Mengen und daraus abgeleiteter Tarifempfehlung.
- Abhängigkeiten in den Ticket-Docs und Plane in beide Richtungen geprüft:
`BILL-11` und `BILL-13` sind Done; kein offener Nachfolger konsumiert einen
geänderten Plan-, Preis- oder Providervertrag.
- Plane-Identität als `raffael@tool-ctrl.de` bestätigt; `HIVEGRID-213`
angelegt, Raffael zugewiesen und auf In Progress gesetzt.
- Sauberer Worktree
`/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud-feat-bill-14-registration-plan-advisor-20260731`
auf `origin/main` (`288e09a33`) und Branch
`feat/bill-14-registration-plan-advisor-20260731`.
- Preflight-Proof: EU-Provider-Guard leer, vollständiger Typecheck grün und
8.133 Tests grün (60 übersprungen).
**BILL-14: 0/9 DoD = 0 % done. 9 Punkte selbst machbar.**
2026-07-31 · Implementierung und lokaler Release-Proof
- Zweistufiger Registrierungs-Wizard mit serverseitiger Tarifempfehlung,
echtem Preis inklusive Zusatznutzern, verständlicher Aufschlüsselung,
manueller Abweichung und wertstabiler Zurück-Navigation umgesetzt.
- Tarif und Büro-/Monteur-Mengen werden streng als Paar validiert, in der
Pre-Auth-Registration gespeichert, bei Replay/Resend exakt gebunden, nach
Reload wiederhergestellt und in den ersten Billing-Aufruf übernommen.
- Der Billing-Prefill bleibt eine Präferenz: aktive Belegung, kanonischer
Katalog und vorhandene Checkout-Validierung bleiben autoritativ.
- Fresh-Migration-Parität, Nicht-Superuser-RLS-Kette und Release-Readiness
grün. Die Migration verändert keine RLS-Policy und dokumentiert die
koordinierte Inverse-SQL.
- Lokaler Proof: Typecheck und Lint grün; 1.157 Testdateien und 8.151 Tests
grün (60 bewusst übersprungen); 104 fokussierte Tests grün; i18n,
Billing-Katalog/-Boundary, Route-Inventar, Secrets, Hot-Swap, Visual,
A11y-Coverage/Axe und RLS-Verifier grün.
**BILL-14: 8/9 DoD = ~89 % done. Offen: PR-CI, Staging-Deploy und Live-UAT.**
2026-08-01 · Live-UAT-Zwischenstand
- Registrierung, Tarifempfehlung, Swarm-Basischeckout, Mollie-Testzahlung,
bestätigte Freischaltung, Rechnungsansicht sowie E-Mail-Marketing-Add-on mit
zweiter Mollie-Testzahlung sind auf Staging erfolgreich belegt.
- Die Customer-Portal-Verwaltung zeigte danach einen abhängigen Pilotfehler:
Frische Tenants besaßen keinen Portal-Scaffold und liefen vor dem Kaufen-Gate
in `PORTAL_NOT_FOUND`. Der eng begrenzte Nachzug wird als `BILL-15` / CR-010
umgesetzt; Preise, Entitlements und der BILL-14-Vertrag bleiben unverändert.
**BILL-14: 8/9 DoD = ~89 % done. Offen: Abschluss des Live-UAT nach BILL-15;
kein externer Blocker.**
2026-08-01 · Live-Abschluss
- Haupt-PR `#304` und die im Live-UAT gefundenen eng begrenzten Nachzüge
`#306`, `#308`, `#310`, `#311`, `#313`, `#314` und `#315` wurden normal
gemergt. Die abschließende PR-CI `#11619` sowie die Main-Runs `#11622` und
`#11623` waren grün.
- Der synthetische Staging-UAT belegt Registrierung, serverseitige Swarm-
Empfehlung, manuelle Tarifwahl, Rücknavigation, Billing-Prefill, exakte
Preisvorschau, Mollie-Testcheckout, bestätigte Freischaltung und
Rechnungsansicht. Die Screenshots `06` bis `17` liegen im Desktop-Ordner
`HiveGrid-BILL-14-UAT-2026-07-31/final-live-verified-2026-08-01`.
- `BILL-15` schloss den während dieses UAT entdeckten Portal-Scaffold-Fehler.
`BILL-16` bleibt ein nachgelagerter Settlement-Bugfix für wiederkehrende
Add-on-Erstrechnungen; er ändert den abgeschlossenen Registrierungs-, Tarif-
und Basischeckout-Vertrag dieses Tickets nicht.
**BILL-14: 9/9 DoD = 100 % done. Plane-Sync ausstehend; 0 Punkte selbst
machbar offen.**
2026-08-01 · Live-Reload-Korrektur gestartet
- Ein frischer zweiter Staging-UAT bestätigte Registrierung, Captcha,
Swarm-Empfehlung und 5/15-Sitzpräferenz. Beim späteren direkten Aufruf der
Billing-Route ohne die einmaligen Redirect-Queryparameter fiel der noch
unbezahlte Tarif jedoch auf Core zurück; es wurde bewusst keine falsche
Zahlung gestartet.
- Root Cause: Die Präferenz war korrekt im konsumierten `Registration`-Datensatz
gespeichert, der Billing-Loader las bisher aber ausschließlich die URL.
- Der Nachzug verwendet eine schmale app-only SECURITY-DEFINER-Projektion für
exakt Tarif, Büro- und Feldsitze. Tenant, User, aktive Mitgliedschaft,
Runtime-Rolle und transaktionslokaler RLS-Kontext müssen vollständig
übereinstimmen; direkte Registration-Lesezugriffe bleiben operator-only.
- URL-Präferenzen bleiben vorrangig, persistierte Werte werden erneut am
aktiven Katalog validiert und nach bestehendem Abo nicht mehr gelesen.
- Lokaler Proof: 108 fokussierte Tests, Typecheck, Lint, Policy-Generator
377/377 und der vollständige achtphasige Fresh-Migration-/FORCE-RLS-Live-Gate
einschließlich 47/47 Kern-RLS-Tests sind grün.
**BILL-14: 8/9 DoD = ~89 % done. Offen: PR-CI, normaler Merge,
Staging-Deploy und Queryless-Reload-UAT; kein externer Blocker.**
2026-08-01 · direkter Signup-Pfad korrigiert
- Der erste Korrektur-PR `#324` wurde normal gemergt und als Revision
`35160c967` auf Staging ausgerollt. Der anschließende frische UAT widerlegte
jedoch die angenommene Datenquelle: Bei deaktivierter E-Mail-Verifizierung
erzeugt der direkte Signup absichtlich keine `Registration`-Zeile. Der erste
Billing-Aufruf war deshalb nur durch die Redirect-Query korrekt; vor einer
falschen Mollie-Testzahlung wurde der Lauf gestoppt.
- Der gemeinsame Post-Bootstrap-Pfad speichert die validierte Tarif-/Büro-/
Monteur-Auswahl jetzt als vollständiges Triplet in der tenant-gebundenen
`TenantProductConfiguration`. Ein eigener Idempotency-Fingerprint bindet die
Auswahl an den deterministischen Signup-Key: Exakte Retries sind erlaubt,
eine abweichende Auswahl unter demselben Key scheitert geschlossen.
- Der Billing-Loader priorisiert weiterhin eine gültige URL, liest danach die
Tenant-Präferenz und nutzt die schmale Registration-Capability nur noch als
Rolling-Compatibility-Fallback für bereits konsumierte Verify-Signups. Nach
vorhandenem Abo wird keine Signup-Präferenz mehr angewendet.
- Lokaler Zwischenproof: 77 fokussierte Tests, Prisma-Validierung, Typecheck,
fokussiertes ESLint, Policy-Generator `377/377` und Diff-Check grün. Der
FORCE-RLS-Livetest deckt eigene Sichtbarkeit sowie ungebundene und
Cross-Tenant-Zugriffe ab und läuft im abschließenden Release-Gate.
**BILL-14: 8/9 DoD = ~89 % done. Offen: vollständiges Release-Gate, PR-CI,
normaler Merge, Staging-Deploy und neuer Queryless-Reload-/Mollie-Test-UAT;
kein externer Blocker.**
2026-08-01 · finaler Registrierungs-, Billing- und Add-on-UAT
- Der dauerhafte Präferenz-Nachzug `10886efae` wurde über PR `#326` normal
gemergt. Der abschließende Main-Stand mit dem Mail-Nachzug wurde als Revision
`137358736` in Deploy `11669` erfolgreich auf Staging ausgerollt.
- Ein vollständig frischer Signup mit 5 Büro- und 15 Monteur-Nutzern empfahl
Swarm. Der direkte Billing-Übergang und ein späterer Aufruf ohne einmalige
Redirect-Query behielten dieselbe Auswahl.
- Drei ausschließlich in Mollie TEST abgeschlossene Käufe wurden ohne Duplikat
freigeschaltet: Swarm plus 100 GB für 508,00 EUR netto, E-Mail-Marketing S
für 59,00 EUR netto und Customer Portal für 19,99 EUR netto. Die jeweiligen
Rechnungen zeigen 19 % USt. und korrekte Bruttosummen.
- Der aktive Tenant besitzt 350 GB Speicher, das E-Mail-Marketing-Kontingent
und den entsperrten Customer-Portal-Admin. Rechnungsansicht, Return-Flows und
Nachbuchungen sind in den Screenshots `34` bis `57` des finalen Desktop-UAT-
Ordners belegt; `BILL-17` ergänzt dort den konsistenten Usage-Proof `59`.
- Die zugehörigen vollständigen lokalen Gates, PR-CIs, normalen Merge-Commits
und Staging-Deploys sind grün. Es wurde keine Production-Zahlung ausgelöst.
**BILL-14: 9/9 DoD = 100 % done. Kein selbst machbarer Punkt offen.**
2026-08-02 · Abhängigkeitsschutz für `BILL-21`
- Registrierungs-Empfehlung, persistierte Rollen-/Tarifauswahl und der
Aktivierungs-Gate bleiben unverändert. Erst die serverautoritativ berechnete
Bruttorate im Billing-Preview entscheidet: ab 1.000,01 EUR ist Karte Pflicht.
2026-08-02 · Abhängigkeitsschutz für `BILL-22`
- `BILL-22` übernimmt die hier gespeicherten Büro-/Baustellenmengen und die
serverautoritativ berechnete Empfehlung, trennt deren Darstellung aber in
Team- und Tarifschritt. Persistenz, Grenzwerte und Checkout-Prefill bleiben
kompatibel.
- Ohne vom konkreten Mollie-Profil angebotene Karte entsteht keine
Provider-Mutation und kein Produktzugriff. `BILL-14` bleibt 9/9 DoD =
100 % done.
@@ -0,0 +1,122 @@
# BILL-15 · Customer-Portal-Scaffold für neue und bestehende Tenants
| | |
| ----------------- | ------------------------------------------------------ |
| **Typ** | Pilot-Bugfix · Tenant-Bootstrap |
| **Owner** | Raffael |
| **Phase** | Billing-/Customer-Portal-Pilot-Readiness |
| **Cycle/Fenster** | gestartet 2026-08-01 |
| **Status** | Complete · Plane-Sync pending |
| **Plane** | HIVEGRID-216 |
## Abhängigkeiten & Parallelität
- **Auslöser:** Der Live-UAT von `BILL-14` hat nach erfolgreicher Basis- und
E-Mail-Marketing-Testzahlung einen 500er auf der Customer-Portal-Verwaltung
nachgewiesen: Der Tenant-Bootstrap erzeugte keinen `Portal`-Datensatz.
- **Erfüllte Grundlagen:** `VA-P26a`, `VA-P26c`, `BILL-11`, `BILL-13` und die
aktiven Customer-Portal-Produkte bleiben unverändert.
- **Blocks:** Abschluss des `BILL-14`-Live-UAT und Pilot-Nutzung des
Customer-Portal-Add-ons durch frisch registrierte Tenants.
- **Abhängigkeitsschutz:** Der Scaffold ist reine, unveröffentlichte
Konfiguration. Entitlement, Checkout, Freischaltung und öffentliche
Portalauflösung bleiben an die bestehenden kommerziellen Gates gebunden.
## Was wir bauen
Der bestehende Tenant-Bootstrap erzeugt innerhalb derselben Transaktion genau
einen unveröffentlichten Customer-Portal-Scaffold. Er verwendet den kanonischen
Tenant-Slug, den Tenant-Namen und den Owner als Ersteller. Ein Fehler rollt den
gesamten Bootstrap zurück; ein Replay verändert ein bestehendes Portal nicht.
Eine Forward-only-Migration legt denselben Scaffold für bestehende Tenants ohne
Portal an. Fremd belegte Slugs brechen vor jeder Mutation fail-closed ab.
## Nicht im Scope
- Portal veröffentlichen, PortalUser oder Projekte anlegen.
- Preise, Pläne, Add-ons, Entitlements, Rechnungen oder Checkout ändern.
- Custom-Domain-Claims oder DNS-/TLS-Zustände erzeugen.
- Bestehende Portal-Konfigurationen überschreiben.
## Definition of Done
- [x] Neue Tenants erhalten vor Marker-Abschluss und Aktivierung idempotent
genau einen unveröffentlichten Portal-Scaffold mit Tenant-Slug/-Name.
- [x] Ein Scaffold-Fehler verhindert Marker-Abschluss und Tenant-Aktivierung;
Bootstrap-Replays überschreiben kein bestehendes Portal.
- [x] Die Forward-only-Migration ergänzt nur fehlende Portale, prüft fremde
Slug-Belegung fail-closed und enthält guarded Inverse-SQL.
- [x] Weder Bootstrap noch Migration erzeugen Billing-, Entitlement-,
Checkout-, Domain- oder Veröffentlichungszustand und ändern keine RLS-Policy.
- [x] Unit-, Performance-, Migration-, Typecheck-, Lint-, Gesamt- und
Release-Verifier sind grün.
- [x] PR-CI, Staging-Deploy und der Customer-Portal-Add-on-UAT mit
Mollie-Testzahlung sind grün und per Screenshots belegt.
**Fortschritt:** `BILL-15`: 6/6 DoD = 100 % done. Plane-Abschluss steht nach
Wiederverfügbarkeit des Trackers aus; 0 Punkte selbst machbar offen.
## Rollback
- Der Code-Commit ist atomar revertierbar. Bereits angelegte unveröffentlichte
Scaffolds sind mit dem alten Code kompatibel.
- Die Migration dokumentiert ausführbare, streng begrenzte Inverse-SQL. Sie
entfernt ausschließlich von dieser Migration markierte, weiterhin
unveröffentlichte und unkonfigurierte Scaffolds; konfigurierte Daten bleiben.
- Entitlements, Zahlungen, Rechnungen und Domain-Zustände werden nie verändert.
## Quellen
- `docs/CHANGE-REQUESTS.md` CR-010
- `.planning/ticket-docs/VA-P26a.md`
- `.planning/ticket-docs/VA-P26c.md`
- `.planning/ticket-docs/BILL-14.md`
- `docs/AGENT-CHECKLIST.md`
## Umsetzungs-Notiz
2026-08-01 · gestartet
- Fehler im echten Staging-Registrierungs-/Billing-UAT reproduziert: Basisplan
und E-Mail-Marketing wurden bezahlt und aktiviert; die Portal-Domain-Route
scheiterte vor Darstellung des Kaufen-Gates an `PORTAL_NOT_FOUND`.
- Kleinsten sicheren Fix gegen Loader-Mutation, Bezahl-Settlement und
nachträgliches Lazy-Provisioning geprüft: Der unveröffentlichte Scaffold
gehört in den Tenant-Bootstrap; bestehende Tenants brauchen einen einmaligen
Backfill.
- Bootstrap-, Performance- und Migrationsverträge ergänzt; 44 fokussierte Tests
sind grün.
- Lokaler Abschluss-Proof grün: Workspace-Typecheck, Web-Typecheck, Lint,
1.160 Testdateien mit 8.184 bestandenen Tests, Migration-/Schema-Parität,
CI-Baseline und Source-Health. Die vollständige frische RLS-Migrationskette
lief als Nicht-Superuser einschließlich 47 App-/Worker-RLS-Tests, 39
Portal-RLS-Tests und 7 echter Produkt-Tenant-Bootstrap-Tests grün. Das
Bootstrap-Query-Budget bleibt mit maximal 26 Abfragen explizit begrenzt.
- Plane-Identität als `raffael@tool-ctrl.de` bestätigt; `HIVEGRID-216`
angelegt, Raffael zugewiesen und auf In Progress gesetzt.
**BILL-15: 5/6 DoD = ~83 % done. 1 Punkt selbst machbar.**
2026-08-01 · Live-Abschluss
- PR `#318` wurde normal gemergt (`c585ae27e`); PR-CI `#11631` und
Staging-Deploy `#11633` waren grün.
- Der synthetische Staging-UAT belegt das Entitlement-Gate, den ausschließlich
in Mollie-Testmode ausgeführten Customer-Portal-Checkout, die bestätigte
Freischaltung und den danach zugänglichen Domain-Admin-Screen. Screenshots
`22` bis `25` liegen im Desktop-Ordner
`HiveGrid-BILL-14-UAT-2026-07-31/final-live-verified-2026-08-01`.
- Die dabei sichtbar gebliebene ausstehende Lago-Erstrechnung ist fachlich
`BILL-16`; Scaffold, Zahlung und Portal-Entitlement aus diesem Ticket sind
korrekt und bleiben durch dessen Settlement-Nachzug unverändert.
**BILL-15: 6/6 DoD = 100 % done. Plane-Sync ausstehend; 0 Punkte selbst
machbar offen.**
2026-08-02 · Abhaengiger Billing-IA-Nachzug
- `BILL-20` macht den bestehenden Customer-Portal-Kauf-/Domain-Flow als
Zusatzmodul-Aufgabe aus der Billing-Uebersicht erreichbar. Scaffold,
Produktcodes, 19,99-EUR-Checkout, Entitlement und Domain-Setup aus diesem
Ticket bleiben unveraendert.
@@ -0,0 +1,190 @@
# BILL-16 · Exaktes Settlement wiederkehrender Add-on-Erstrechnungen
| | |
| ----------------- | ---------------------------------------- |
| **Typ** | Pilot-Bugfix · Billing-Settlement |
| **Owner** | Raffael |
| **Phase** | Billing-/Customer-Portal-Pilot-Readiness |
| **Cycle/Fenster** | gestartet 2026-08-01 |
| **Status** | In Progress |
| **Plane** | ausstehend, Plane aktuell HTTP 502 |
## Abhängigkeiten & Parallelität
- **Auslöser:** Der vollständige Live-UAT von `BILL-14`/`BILL-15` hat zwei
erfolgreiche Mollie-Testzahlungen für wiederkehrende Add-ons mit aktiven
Entitlements, aber weiterhin ausstehenden Lago-Rechnungen nachgewiesen.
- **Erfüllte Grundlagen:** `BILL-11`, `BILL-13`, `BILL-14`, `BILL-15`,
`AK-P14b` und `VA-P26c` liefern Katalog, Produktledger, Checkout,
Freischaltung, Rechnungsansicht und Portal-Gate.
- **Blocks:** fachlicher Abschluss von `BILL-14` und `BILL-15` sowie ein
doppelabbuchungssicherer Pilotbetrieb wiederkehrender Add-ons.
- **Abhängigkeitsschutz:** `TenantProductAcquisition.invoiceExternalId` bleibt
die unveränderte Mollie-Attempt-Referenz. Preise, Entitlements,
Produkt-Scope und Base-Plan-Lifecycle ändern sich nicht.
## Was wir bauen
HiveGrid persistiert bei einem wiederkehrenden Produktkauf neben der externen
Lago-Subscription-ID auch deren Provider-ID und die exakt zugehörige initiale
Lago-Invoice-ID. Die bestehende transaktionale Outbox markiert ausschließlich
diese Invoice nach bewiesenem, aktuellem Mollie-Payment als bezahlt.
Die Korrelation verlangt Tenant, beide Subscription-IDs, Betrag, Währung,
Subscription-Invoice und Lagos `subscription_starting`-Grund. Null oder mehrere
Treffer bleiben fail-closed. Der bestehende bounded 5-Minuten-Reconciler zieht
aktive Bestandskäufe ohne Mirror selbstheilend nach.
Der Lago-Webhook darf eine bereits durch den Produkt-Checkout bezahlte
`subscription_starting`-Invoice nur als `skipped_initial` markieren und nie in
das Recurring-Inkasso geben. Ausschließlich `subscription_periodic` darf eine
neue Mollie-Folgezahlung erzeugen.
## Nicht im Scope
- Preise, Tarife, Entitlements oder Produkt-Scope ändern.
- Mollie-Live-Zahlungen oder Aufhebung von `BILL-08` / `EXT-16`.
- Amount-/Newest-Heuristiken ohne exakten Subscription- und Invoice-Reason-
Vertrag.
- Provider-Mutationen aus einer SQL-Migration oder ein ungebundener
Cross-Tenant-Backfill.
- Neue Billing-Features außerhalb des Settlement- und Collection-Vertrags.
## Definition of Done
- [x] Provider-Subscription-ID und initiale Lago-Invoice-ID werden getrennt von
der unveränderten Mollie-Attempt-Referenz nullable und tenant-gebunden
persistiert und in den lokalen Produkt-Mirror übernommen.
- [x] Der Lago-Invoice-Contract bildet `billing_periods.invoicing_reason` ab;
der Matcher akzeptiert genau eine `subscription_starting`-Invoice mit
Tenant, beiden Subscription-IDs, Betrag und Währung.
- [x] Neue Add-on-Checkouts berechnen aus dem unveränderten Nettokatalog den
kanonischen Bruttobetrag mit 19 Prozent Umsatzsteuer, persistieren und
belasten exakt diesen Betrag; Portal-Plan und One-off-Fee tragen den
expliziten `de-vat-19`-Vertrag und Fixed-Price-Produkte erlauben keine
Mengenmanipulation.
- [x] Die transaktionale Outbox markiert nur die exakt persistierte initiale
Invoice eines aktuell aktiven, exakt passenden Mollie-Attempts als
bezahlt; stale, refundete, mehrdeutige und gefälschte Jobs bleiben
fail-closed.
- [x] Der bestehende bounded Reconciler repariert aktive Bestandskäufe ohne
Provider-Mirror tenantweise, CAS-/RLS-sicher und ohne ungebundene
Provider-Mutation.
- [x] `subscription_starting` wird nach aktiver bezahlter Acquisition
idempotent als `skipped_initial` markiert und nie erneut eingezogen;
ausschließlich `subscription_periodic` wird als Folgerechnung gequeued.
- [x] Forward-only-Migration mit Inverse-SQL, fokussierte Unit-/Worker-/API-
Tests, Typecheck, Lint, Gesamttests und passende Billing-/RLS-/Migration-
Verifier sind grün.
- [ ] PR-CI, normaler Merge, Staging-Deploy und Live-UAT belegen bezahlte
Add-on-Rechnungen ohne zweite Mollie-Zahlung; Screenshots liegen im
Desktop-Review-Ordner.
**Fortschritt:** `BILL-16`: 7/8 DoD = ~88 % done. 1 Punkt selbst machbar:
PR-CI, normaler Merge, Staging-Deploy und Live-UAT mit Screenshots. Kein
externer Blocker. Plane-Synchronisierung wartet auf Verfügbarkeit.
## Rollback
- Die zwei neuen Provider-Mirror-Felder sind nullable; alter Code ignoriert sie
sicher. Die Migration enthält streng begrenzte Inverse-SQL.
- Bereits bezahlte Rechnungen, Zahlungen und Entitlements werden niemals
gelöscht. Ein Code-Rollback stoppt nur neue automatische Korrelationen.
- Die Reconciler- und Collection-Änderungen sind getrennt atomar revertierbar.
Bestehende Outbox-Receipts und `skipped_initial`-Marker bleiben append-only.
## Quellen
- `docs/CHANGE-REQUESTS.md` CR-011
- `.planning/ticket-docs/BILL-14.md`
- `.planning/ticket-docs/BILL-15.md`
- Lago API: Invoice-Objekt und `billing_periods.invoicing_reason`
- `docs/AGENT-CHECKLIST.md`
## Umsetzungs-Notiz
2026-08-01 · gestartet
- Live-Proof: Basisplan-Invoice bezahlt; wiederkehrende E-Mail-Marketing- und
Customer-Portal-Invoices trotz jeweils erfolgreicher Mollie-Testzahlung und
aktivem Entitlement weiterhin ausstehend.
- Root Cause: Der Produkt-Sync publiziert nach Aktivierung einen durable
Provider-Side-Effect, dessen Builder für `recurring_add_on + active` bisher
jedoch `null` liefert. Die gespeicherte `invoiceExternalId` ist bei diesem
Produkttyp bewusst nur die Mollie-Attempt-Referenz und darf nicht als Lago-
Invoice-ID verwendet werden.
- Zweiter Vertragsfehler: Der lokale `TenantSubscriptionProduct` übernimmt die
Lago-Provider-Subscription-ID nicht. Der Recurring-Collector kann deshalb
weder initiale noch spätere Invoices exakt an den Produkt-Mirror binden.
- Offizielle Lago-Dokumentation verifiziert: `billing_periods` koppelt externe
und Provider-Subscription-ID; `invoicing_reason=subscription_starting`
kennzeichnet die initiale, `subscription_periodic` die spätere Rechnung.
- Isolierter Worktree auf `origin/main` (`0141ad43b`), EU-Provider-Guard leer,
Workspace-Typecheck grün und 1.168 Testdateien / 8.200 Tests grün
(60 bewusst übersprungen).
- Plane ist beim Start mit HTTP 502 nicht verfügbar. Keine Plane-Schreibaktion
ohne erneute erfolgreiche Identitätsprüfung.
- Implementiert in den atomaren Commits `4f91b00eb`, `07daa4d61`,
`ef8830f82`, `24973c050`, `c5d2c02da`, `d022e16b1` und `48a8a3e24`:
exakter Lago-Invoice-Reason-Vertrag, getrennte Provider-Referenzen,
RLS-/CAS-sicherer Bestands-Reconciler, exklusiver Outbox-Claim sowie
doppelabbuchungssichere Trennung von Start- und Folgerechnung.
- Ein unabhängiger Code-Review fand sieben konkrete Race-/Kompatibilitäts-
und Settlement-Risiken. Alle sieben sind behoben; der zuletzt geschlossene
High-Fund bewahrt eine bereits bezahlte Startrechnung bei freiwilliger
Kündigung und ist durch einen gezielten Regressionstest belegt.
- Abschlussprüfung vor Push: Typecheck und Lint grün; 1.168 Testdateien mit
8.200 bestandenen Tests (60 bewusst übersprungen); Prisma-Schema valid;
Billing-Katalog 21/21; Tenant-Policy-Vertrag 377/377; Migrations-Parität ohne
Diff; Billing-Boundary-, CI- und Source-Health-Baselines grün.
- Der strenge Live-RLS-Check lief in allen 8 Phasen grün: frische
Migrationskette, eingeschränkte App-/Worker-/Chat-/Portal-Rollen,
Portal-Policy-Parität und Produkt-Tenant-Bootstrap. Der direkte lokale
`prisma migrate status` war mangels laufender Standard-DB auf Port 6432 nicht
erreichbar; die stärkere isolierte Fresh-DB-Prüfung war erfolgreich.
- PR `#320` wurde normal gemergt (`ea48f1102`) und das Staging-Deployment
`#11648` rollte Web, API und Worker erfolgreich aus. Der anschließende
Live-UAT blieb bei 6/7 DoD: Der General-Worker lief im 5-Minuten-Takt und
inspizierte die drei synthetischen Acquisitions, meldete für beide Add-ons
aber reproduzierbar `active_initial_invoice_missing`; die Rechnungen
`HIV-25FE-013-002` und `HIV-25FE-013-003` blieben ausstehend.
- Live-Root-Cause: Lago v1.50 liefert `billing_periods` im Listen-Endpunkt für
diese Rechnungen als leeres Array, obwohl der jeweilige Invoice-Detail-
Endpunkt exakt eine Periode mit beiden Subscription-IDs und
`subscription_starting` enthält. Der Matcher war korrekt fail-closed, der
Reconciler hatte jedoch nur den Listen-Vertrag geladen.
- Nachzug implementiert: Der Reconciler filtert Listenzeilen zunächst exakt
nach Tenant, Subscription-Invoice, Final-/Zahlungsstatus, Betrag und Währung
und hydriert ausschließlich fehlende Perioden über den Invoice-Detail-
Endpunkt. Eine tenantweit geteilte Momentaufnahme begrenzt jeden Sweep auf
höchstens vier Listen- und 25 deduplizierte Detail-Requests. Eine vierte
nichtleere Seite, Detailfehler, Summary-/Detail-Widersprüche und jeder
Budget-Overflow bleiben ohne Provider-Mutation fail-closed und erzeugen
eigene Operator-Alarmcodes.
- Der Live-UAT deckte zusätzlich einen finanziell relevanten Altfehler auf:
Die E-Mail-Marketing-Acquisition und Mollie-Testzahlung betragen 59,00 EUR
netto, während Lago wegen des bereits korrekten 19-Prozent-Steuervertrags
70,21 EUR brutto fakturiert. Diese um 11,21 EUR unterbezahlte Alt-Rechnung
wird ausdrücklich nicht künstlich als bezahlt markiert. Die Portal-
Altzahlung über 19,99 EUR stimmt dagegen mit ihrer damaligen steuerfreien
Lago-Rechnung überein und bleibt exakt settlebar.
- Für neue Käufe nutzt der Produktcheckout jetzt den zentralen
Brutto-/Rundungsvertrag: E-Mail-Marketing S wird mit 70,21 EUR statt 59,00
EUR belastet, Customer Portal mit 23,79 EUR statt 19,99 EUR und das
einmalige Domain-Setup mit 356,99 EUR statt 299,99 EUR. Lago erhält beim
Portal-Plan, Add-on und der konkreten One-off-Fee explizit `de-vat-19`;
ausschließlich Tax-only-Katalogdrift darf der auditierte Staging-Operator
automatisch nachziehen. Alle anderen Provider-Drifts bleiben blockiert.
- Die Kaufoberflächen zeigen vor Mollie denselben Vertrag ohne Preisüberraschung:
E-Mail-Marketing weist Nettobetrag, 19 Prozent Umsatzsteuer und Zahlbetrag
separat aus; Portal-Monatspreis und Domain-Setup nennen Brutto- und
Nettobetrag gemeinsam. Das View-Model lehnt widersprüchliche
Netto-/Steuer-/Bruttowerte ab.
- Alte Mollie-Testzahlungen ohne das später ergänzte
`lagoProviderSubscriptionId`-Metadatum bleiben über die übrige vollständige
Ledger-Bindung kompatibel; ein vorhandener abweichender Wert wird weiterhin
deterministisch abgelehnt. 110 fokussierte Tests belegen die neuen
Steuer-, Hydrierungs-, Request-Budget-, Overflow- und Legacy-Verträge.
**BILL-16: 7/8 DoD = ~88 % done. Offen: PR-CI, normaler Merge,
Staging-Deploy und Live-UAT mit Screenshots.**
@@ -0,0 +1,116 @@
# BILL-17 · Storage-Limit im Billing-Usage-Tab konsistent anzeigen
| | |
| ----------------- | ------------------------------------------------------ |
| **Typ** | Launch-Fix · Billing Usage / RLS |
| **Owner** | Raffael |
| **Phase** | Pilot-Härtung |
| **Cycle/Fenster** | gestartet 2026-08-01 |
| **Status** | Done |
| **Plane** | HIVEGRID-236 |
## Abhängigkeiten & Parallelität
- **Blocked by:** kein technischer Blocker. `BILL-11` liefert den kanonischen
Plan-/Speicherkatalog; `BILL-13` liefert Usage-UI und Storage-Resolver.
- **Blocks:** erneuter Abschluss des wieder geöffneten `BILL-13`-DoD-Punkts
für RLS-gebundene Speichertransparenz.
- **Abhängigkeitsschutz:** Checkout, Mollie/Lago-Sync, Tarif- und Add-on-Codes,
Upload-Grenze sowie Automation-Usage bleiben unverändert.
## Was / Warum
Der finale Staging-UAT zeigte auf demselben aktiven Swarm-Workspace mit
`storage_100gb` zwei widersprüchliche Aussagen: Die Billing-Hauptseite zeigte
korrekt 350 GB, der separate Tab „Nutzung“ dagegen „0 BYTES“ und
„Kein Limit konfiguriert“.
Der große Wert „0 BYTES“ ist für einen frischen Workspace als aktueller
Verbrauch korrekt. Falsch ist die unbegrenzte Kapazität: Die alte Usage-Route
las Limits nur aus `SubscriptionFeature` und band ihre eigenen Queries nach dem
Modul-Gate nicht an den Tenant-RLS-Kontext. Sie verwendet künftig die bereits
kanonische Storage-Projektion aus Basistarif, Rollen-Sitzen, festen Add-ons,
gespeicherten Bytes und laufenden Upload-Reservierungen.
## Nicht im Scope
- Keine Preis-, Tarif-, Add-on-, Checkout-, Mollie- oder Lago-Änderung.
- Keine Migration, kein Backfill und kein neues Usage-Metering.
- Keine automatische Zusatzabrechnung oder Änderung an Upload-Schreibgrenzen.
- Keine neue Usage-UI oder finale Subframe-Optik.
## Definition of Done
- [x] Der Usage-Tab verwendet für Speicher die kanonische kommerzielle
Kapazitätsprojektion aus Plan, Rollen-Sitzen und aktiven Speicher-Add-ons.
- [x] Angezeigt werden gespeicherte plus laufend reservierte Bytes; Restmenge,
Prozentwert und Erschöpfung werden gegen exakt dieselbe Kapazität berechnet.
- [x] Der gesamte Tenant-Read ist RLS-gebunden; ein fehlender oder unbekannter
Speichervertrag wird nicht als unbegrenzte Kapazität dargestellt.
- [x] Service- und Route-Tests decken 350 GB, gespeicherte plus reservierte
Bytes, RLS-Bindung und den fail-closed Fehlerzustand ab; Texte sind de/en.
- [x] Typecheck, Lint, vollständige Testsuite und passende Source-/i18n-/RLS-
Gates sind grün.
- [x] PR-CI, normaler Merge und Staging-Deploy sind grün; der frische
Swarm-Workspace zeigt im Usage-Tab „Limit: 350 GB“ per Screenshot.
**BILL-17: 6/6 DoD = 100 % done. Kein selbst machbarer Punkt offen.**
2026-08-02 · Abhängigkeitsschutz für `BILL-23`:
- Der RLS-gebundene Usage-/Upload-Vertrag bleibt unverändert und konsumiert
weiterhin ausschließlich `calculateStorageCapacity`. `BILL-23` ändert die
versionierten Eingabewerte dieser einen Quelle, nicht den Read- oder
Locking-Pfad. Usage und Upload-Grenze werden zusammen regressionsgeprüft.
- `BILL-17` bleibt 6/6 DoD = 100 % done.
## Technische Bausteine
- `apps/web/app/utils/services/.server/billingStatusService.ts`
- `apps/web/app/services/billing/storage-capacity.server.ts`
- `apps/web/app/routes/app.$tenant/settings/billing/usage.tsx`
- bestehende `BillingUsageVM` und `BillingUsagePage`
- CR-014 in `docs/CHANGE-REQUESTS.md`
## Rollback
Reiner Code-Rollback der Read-Projektion und ihrer Klartext-Diagnostik. Es gibt
keine Datenmigration und keine Provider-Mutation. Bereits gebuchte Tarife,
Speicher-Add-ons, Zahlungen und Rechnungen bleiben unverändert. Ein Rollback
ändert weder die kanonische Upload-Grenze noch persistierte Usage-Daten.
## Umsetzungs-Notiz
2026-08-01 · Live-Fund, Scope und Implementierung
- Frischer Staging-Proof auf Revision `137358736`: Swarm mit 5 Büro-/15
Monteur-Sitzen plus `storage_100gb`, 350 GB auf der Billing-Hauptseite, aber
„Kein Limit konfiguriert“ im dedizierten Usage-Tab.
- Abhängigkeiten beidseitig geprüft: `BILL-11` und `BILL-13` liefern Katalog
und Resolver; `BILL-17` ändert keinen Konsumentenvertrag und blockiert nur die
erneute Abnahme des wieder geöffneten `BILL-13`-DoD-Punkts.
- Der Usage-Service bindet seinen vollständigen Read mit `runWithRlsContext`
und ersetzt ausschließlich die Storage-Metrik durch
`resolveTenantStorageUsage`. Gespeicherte und reservierte Bytes werden
addiert; ein nicht sicher bestimmbarer Vertrag erzeugt einen klaren
Fehlerzustand statt „unbegrenzt“.
- Fokussierter Zwischenproof: 9/9 Service-/Route-Regressionstests grün.
**BILL-17: 4/6 DoD = ~67 % done. Offen: vollständiges lokales Release-Gate,
PR-CI, normaler Merge, Staging-Deploy und Live-Screenshot.**
2026-08-01 · Release und Live-Abnahme
- Implementierung `d33080b17`, Main-Nachzug `cf373626a` und PR `#331`
bestanden CI-Run `11690` mit 11/11 Jobs einschließlich vollständigem
Typecheck/Test, Docker-Smoke und Datenbank-/RLS-Gates.
- PR `#331` wurde als normaler Merge-Commit `a47d6e13e` übernommen; die
ursprünglichen Feature-Commits bleiben als Main-Ancestors erhalten.
- Staging-Deploy `11691` war vollständig grün. Web, Admin, Portal, API und MCP
meldeten vor der Browser-Abnahme exakt Revision `a47d6e13e`.
- Der bezahlte frische Swarm-Tenant mit 100-GB-Add-on zeigt im dedizierten
Usage-Tab `0 BYTES`, `Limit: 350 GB` und `350 GB remaining`. Der gezielte
Chromium-UAT bestand 1/1; Screenshot
`59-final-usage-tab-350gb.png` liegt im finalen Desktop-UAT-Ordner.
**BILL-17: 6/6 DoD = 100 % done. Kein selbst machbarer Punkt offen.**
@@ -0,0 +1,137 @@
# BILL-18 · Registrierungs-Tarifwahl und CAPTCHA-Retry launchfest machen
| | |
| ----------------- | -------------------------------------------------------- |
| **Typ** | Launch-Fix · Registrierung / Billing-UX / CAPTCHA |
| **Owner** | Raffael |
| **Phase** | Pilot-Härtung |
| **Cycle/Fenster** | gestartet 2026-08-01 |
| **Status** | Done |
| **Plane** | HIVEGRID-239 |
## Abhängigkeiten & Parallelität
- **Blocked by:** kein technischer Blocker. `BILL-14` liefert den zweistufigen
Registrierungsvertrag, die serverseitige Tarifempfehlung und den Checkout-
Prefill. Die bestehende self-hosted CAP-Integration liefert Challenge und
serverseitige Verifikation.
- **Blocks:** visuelle und funktionale Pilotabnahme der öffentlichen
Registrierung.
- **Abhängigkeitsschutz:** Tarifcodes, Preise, Sitzberechnung, E-Mail-
Verifikation, Mollie-/Lago-Checkout und Entitlement-Aktivierung bleiben
unverändert. Der Registrierungs-POST erhält nur einen opaken Retry-Schlüssel
für eine neue clientseitige CAPTCHA-Instanz.
## Was / Warum
Der Team-/Tarif-Schritt zeigte alle Tarife dauerhaft untereinander, verwendete
rohe Zahlenfelder und platzierte CAPTCHA, Einwilligungen und Aktion ohne klare
Entscheidungshierarchie in einer schmalen Card. Auf Mobile entstand dadurch ein
langer, schwer erfassbarer Screen.
Zusätzlich war am gesamten Formular `noValidate` gesetzt und die UI kannte den
CAP-`solve`-Status nicht. Ein Klick auf „Fortfahren“ konnte deshalb ohne Token
beim Server landen. CAP-Proofs sind außerdem einmalig: Lehnte der Server den
Request nach erfolgreicher CAPTCHA-Prüfung später aus einem anderen Grund ab,
blieb derselbe bereits verbrauchte Token im weiterhin gelöst aussehenden Widget
und vergiftete den nächsten Versuch bis zum manuellen Reload.
## Nicht im Scope
- Keine Änderung an Tarifpreisen, Seat-Formeln oder Produktausstattung.
- Keine Änderung an E-Mail-Verifikation, Mollie Hosted Checkout, Lago,
Rechnungen oder Entitlements.
- Kein neuer CAPTCHA-Provider, kein Fail-open und keine schwächere
serverseitige Prüfung.
- Keine neue Registrierungsstufe und kein neues Produktfeature.
## Definition of Done
- [x] Teamgrößen werden über zugängliche Plus-/Minus-Steuerungen erfasst; die
bestehenden sicheren 1..10.000- bzw. 0..10.000-Grenzen bleiben erhalten.
- [x] Der gewählte bzw. empfohlene Tarif steht als klare Zusammenfassung neben
der Teamkonfiguration; andere Tarife sind standardmäßig eingeklappt und
bleiben manuell wählbar.
- [x] Ein Konto/Team-&-Tarif/Zahlung-Stepper, kleineres Branding und eine eigene
Bestätigungszone erklären Reihenfolge und „noch keine Zahlung“ korrekt.
- [x] Der CAP-CTA bleibt bis zum echten `solve`-Event gesperrt; `reset` und
Clientfehler nehmen die Freigabe zurück.
- [x] Jeder fehlgeschlagene initiale Registrierungs-POST liefert einen neuen
opaken Reset-Key und remountet damit eine frische Challenge für den Retry.
- [x] Texte sind de/en sowie informell/formell vorhanden; fokussierte Unit- und
Component-Tests sowie Desktop-/Mobile-Pixelbaselines sind grün.
- [x] Typecheck, Lint, vollständige Testsuite und passende i18n-/Source-Gates
sind grün.
- [x] PR-CI, normaler Merge, Staging-Deploy und Live-Registrierungsproof mit
Mollie-Testumgebung sind grün; Review-Screenshots liegen auf dem Desktop.
**BILL-18: 8/8 DoD = 100 % done. Offen: nichts.**
2026-08-02 · Abhängiger Erstaktivierungs-Nachzug
- `BILL-19` konsumiert den hier gehärteten Konto-/Tarif-/CAPTCHA-Vertrag und
korrigiert die danach sichtbare Erstaktivierung. CAPTCHA-Events, Retry-Key,
Tarifempfehlung und alle BILL-18-DoD bleiben unverändert.
## Technische Bausteine
- `apps/web/app/modules/users/components/RegisterScreen.tsx`
- `apps/web/app/components/captcha/Captcha.tsx`
- `apps/web/app/modules/users/services/AuthService.ts`
- `apps/web/app/routes/register.tsx`
- React-Router-Component-Fixture und Playwright-CT-Pixelbaselines
- CR-016 in `docs/CHANGE-REQUESTS.md`
## Rollback
Reiner Code-/UI-Rollback auf den bisherigen Registrierungs-Screen. Es gibt
keine Migration, keinen Backfill und keine Provider-Mutation. Bestehende
Registrierungen, Tarifauswahlen, Zahlungen und Entitlements bleiben
unverändert. Beim Rollback ginge nur die neue Client-Freigabe und automatische
CAPTCHA-Retry-Erneuerung verloren; die serverseitige Prüfung bliebe fail-closed.
## Umsetzungs-Notiz
2026-08-01 · Diagnose, Interim-UI und lokaler Proof
- Abhängigkeiten geprüft: `BILL-14` bleibt in seinem Request-/Katalogvertrag
unverändert; keine nachgelagerte Checkout- oder Entitlement-Schnittstelle
ändert sich.
- Root Cause nach Quellcode- und Provider-Widget-Prüfung: `noValidate` erlaubte
fehlende CAP-Proofs; der Client beobachtete `solve`/`reset`/`error` nicht und
remountete nach verbrauchtem oder abgelaufenem Proof keine neue Challenge.
- Der neue Screen verwendet ausschließlich vorhandene `~/ui`-/Subframe-
Komponenten. Desktop ordnet Team und Empfehlung nebeneinander; Mobile
stapelt ohne horizontalen Überlauf. Andere Tarife bleiben einklappbar.
- Lokaler Zwischenproof: Typecheck grün, 43/43 fokussierte Unit-/Service-Tests
grün, Playwright-CT Desktop und Mobile 2/2 grün einschließlich exaktem
`scrollWidth=390`-Vertrag.
- Vollständiges lokales Release-Gate: Lint und Typecheck grün, 1.174/1.174
ausführbare Testdateien mit 8.262/8.262 Tests grün, i18n-Parität mit 15.691
Keys grün, Source-Health 22/22 grün, CI-Baseline 35/35 grün und Hot-Swap-
Drill grün.
- Plane-Identität als `raffael@tool-ctrl.de` bestätigt; `HIVEGRID-239`
angelegt, Raffael zugewiesen und auf In Progress gesetzt.
2026-08-02 · PR-, Deploy- und Live-Proof
- PR `#341` wurde nach 11/11 grünen Checks normal gemergt. Der erste Docker-
Smoke lief wegen Runner-Contention ins Zeitlimit; nur dieser Job wurde
gezielt wiederholt und war als Job `49449` grün. Merge-Commit:
`b6501b0eafb8a6f6a93fd1520530caffb040a418`.
- Staging-Deploy-Run `11724` ist grün. `/healthz` und `/readyz` melden exakt
den Merge-Commit. Es gab keinen Production-Deploy.
- Live-Registrierungs-UAT auf Staging: Der CTA blieb vor der echten CAP-Lösung
gesperrt. Ein absichtlich abgelehnter Proof remountete eine neue Challenge
und sperrte den CTA wieder; der folgende frische Proof registrierte
erfolgreich.
- Die Auswahl 5 Büro- und 15 Baustellen-Nutzer empfahl Swarm und blieb ohne
URL-Query im Billing erhalten. Die ausschließlich im Mollie-Testmodus
simulierte Zahlung aktivierte erst nach Bestätigung Swarm und 250 GB
Speicher; die Rechnung über 593,81 EUR brutto ist finalisiert und bezahlt.
- Review-Proof liegt unter
`~/Desktop/HiveGrid-BILL-18-Registration-CAPTCHA-2026-08-01/` mit Konto-,
Tarif-, CAPTCHA-Retry-, Preis-, Zahlungs-, Entitlement- und Rechnungs-
Screenshots sowie einer `README.md`.
**BILL-18: 8/8 DoD = 100 % done. Offen: nichts.**
@@ -0,0 +1,122 @@
# BILL-19 · UX-Review Registrierung bis Zahlung
**Audit-Basis:** Staging-Flow vom 2026-08-02, Screenshots `04`, `09`, `10`
und `11` aus `~/Desktop/HiveGrid-BILL-18-Registration-CAPTCHA-2026-08-01/`,
aktueller Quellcode auf `origin/main`.
## Ergebnis vor Korrektur
| Säule | Wertung | Befund |
| --- | ---: | --- |
| Copywriting | 2/4 | Einzeltexte sind verständlich, widersprechen aber als Flow: „Zahlung“ ist Schritt 3, nach Schritt 2 erscheint dennoch zuerst ein fertiger Workspace. Der allgemeine Trial-Hinweis wirkt auch bei Tarifen ohne Testphase. |
| Visuals | 2/4 | Auth-Screens sind ruhig und konsistent. Der Erstkauf springt abrupt in eine informationsdichte Verwaltungsoberfläche mit Sidebar, Tabs und mehreren gleichrangigen Cards. |
| Color | 3/4 | Tokens und Zustandsfarben sind konsistent; die blaue Trial-Information erhält jedoch mehr Gewicht als die noch ausstehende Aktivierung. |
| Typography | 3/4 | Typografische Hierarchie ist innerhalb einzelner Cards sauber, aber über die Gesamtseite konkurrieren zu viele Überschriften und Beschreibungen. |
| Spacing | 2/4 | Einzelabstände stimmen, die vertikale Strecke bis zur primären Preis-/Zahlungsaktion ist für den Erstkauf zu lang. |
| Experience Design | 1/4 | Passwortfehler kommt zu spät; Systemgrenze nach Signup ist falsch; Erstkauf und laufende Billing-Verwaltung sind vermischt; der notwendige Mollie-Schritt ist nicht die dominante nächste Aktion. |
**Gesamt: 13/24. Launch-blockierende UX-Lücken vorhanden.**
## Flow-Befunde nach Priorität
### P0 · Passwortvalidierung verliert den Schrittbezug
Die Checkliste berechnet Mindestlänge und Zeichenklassen bereits clientseitig,
das Passwortfeld bindet diese Regeln aber nicht an Feldvalidität oder
`showPlanStep()`. Ein ungültiges Passwort erreicht deshalb Team & Tarif. Der
serverseitige Fehler erscheint erst beim finalen POST und damit auf der
falschen Seite.
**Ziel:** Regelverletzungen beim Feld zeigen, Konto-Schritt nicht verlassen,
Fokus am Passwort halten. Serverseitige HIBP-/E-Mail-Kontextprüfung bleibt
weiterhin autoritativ und wird nicht clientseitig nachgebaut.
### P0 · Unbezahlter Tenant sieht eine scheinbar aktive Anwendung
Der technische Tenant-Bootstrap vor Zahlung ist fachlich sinnvoll. Der
Subscription-Gate schützt Fachmodule ohne Produkt oder aktive Testphase. Seine
Ausnahme gilt jedoch für den gesamten Settings-Pfad. Dadurch rendert der
Erstkauf in `AppLayout` mit vollständiger Sidebar und Workspace-Navigation.
**Ziel:** Ohne Produkt/aktive Testphase ist ausschließlich die exakte
Aktivierungsroute erreichbar. Sie rendert ohne App-Chrome. Andere App- und
Settings-Ziele bleiben serverseitig am Plan-Gate.
### P1 · Erstkauf und Bestandsverwaltung haben dieselbe Oberfläche
Vor dem ersten Checkout zeigt die Seite nacheinander: leeres Abonnement,
leere Nutzung, generische Trial-Policy, Tarifkatalog, Perioden, Sitze,
Speicherpakete, E-Mail-Marketing und drei Billing-Tabs. Das sind sechs
unterschiedliche Aufgaben für einen Nutzer, der nur seine bereits getroffene
Auswahl bezahlen möchte.
**Ziel:** eigener Aktivierungscheckout mit drei Gruppen:
1. Gewählter Tarif und Nutzerplätze
2. Optionale Speichererweiterung
3. Servergeprüfte Bestellübersicht und Mollie-Aktion
Nutzung, Rechnungen und E-Mail-Marketing erscheinen erst nach Basisaktivierung.
### P1 · Testphase ist nicht produktspezifisch erklärt
Der globale Hinweis „Testphase ohne Vertriebsfreigabe“ wird auch dann dominant
angezeigt, wenn der gewählte Preis `trialDays = 0` besitzt. Damit bleibt offen,
ob Zahlung sofort nötig ist oder später erfolgt.
**Ziel:** Die Preisvorschau erklärt exakt einen von zwei Zuständen:
- echte Testphase: Dauer, Zahlungsmethode erforderlich oder nicht, heute 0 EUR
- keine Testphase: heutige Mollie-Zahlung aktiviert Tarif und Funktionen
Es wird keine Testphase erfunden.
## Was bewusst korrekt bleibt
- Workspace wird vor Zahlung als technische, tenantgebundene Hülle angelegt.
- Produktzugriff entsteht nur durch bestätigten Checkout-Sync oder eine echte
aktive Testphase.
- Tarif-/Sitzpräferenz ist nur Vorbelegung; serverseitiger Katalog und
belegte Sitze bleiben autoritativ.
- Mollie Hosted Checkout bleibt eine eigene sichere Top-Level-Seite.
- Preisvorschau zeigt bereits korrekt netto, 19 Prozent Umsatzsteuer, brutto,
Zeitraum und Wirksamkeit.
## Abnahmekriterien des Re-Audits
- Kein Schrittwechsel mit synchron ungültigem Passwort.
- Kein App-/Settings-Chrome vor Basisaktivierung.
- Eine sichtbare primäre Aktion führt von der übernommenen Auswahl zur
servergeprüften Vorschau beziehungsweise direkt weiter zu Mollie.
- Desktop und Mobile zeigen Preis, Zahlungszeitpunkt und Freischaltungsfolge
ohne Scroll-Suche oder widersprüchlichen Trial-Hinweis.
- Aktive/Trial-Bestandskunden behalten die bisherige Billing-Verwaltung.
## Ergebnis nach Korrektur
| Säule | Wertung | Ergebnis |
| --- | ---: | --- |
| Copywriting | 4/4 | Konto, technische Workspace-Anlage, Zugriffssperre und Zahlungszeitpunkt werden in der Reihenfolge erklärt, in der sie tatsächlich passieren. Trial- und Sofortzahlungsfälle verwenden preisabhängige Texte. |
| Visuals | 4/4 | Die Aktivierung hat eine eigene, ruhige Oberfläche ohne Sidebar oder Settings-Tabs. Auswahl, Zusammenfassung und Mollie-Übergabe bilden eine visuell geschlossene Aufgabe. |
| Color | 4/4 | Aktivierungswarnung, Auswahlzustand und primäre Aktion haben eine klare Gewichtung; ein allgemeiner Trial-Hinweis überstrahlt den Zahlungsbedarf nicht mehr. |
| Typography | 4/4 | Eine Seitenüberschrift, kurze Abschnittstitel und eine kompakte Bestellzusammenfassung ersetzen die konkurrierenden Verwaltungsüberschriften. |
| Spacing | 3/4 | Desktop und Mobile sind ohne horizontalen Überlauf sauber gegliedert. Die drei Tarifoptionen bleiben auf kleinen Displays bewusst untereinander und erzeugen weiterhin eine längere, aber nachvollziehbare Strecke. |
| Experience Design | 4/4 | Ungültige Passwörter stoppen im Kontoschritt; unbezahlte Tenants bleiben im Aktivierungszustand; genau eine primäre Aktion öffnet die servergeprüfte Preisvorschau und anschließend Mollie. |
**Gesamt: 23/24. Die launch-blockierenden UX-Lücken sind lokal behoben.**
## Visueller Proof
- `bill-19-registration-password-validation.png`: lokalisierter Inline-Fehler
im Kontoschritt, Fokus bleibt am Passwort.
- `bill-19-activation-checkout-desktop.png`: fokussierte Aktivierung ohne
Workspace-/Settings-Chrome.
- `bill-19-activation-checkout-mobile.png`: gleiche Hierarchie ohne
horizontalen Überlauf.
- `bill-19-activation-mollie-preview.png`: serverberechnete Netto-, USt.- und
Bruttosumme, Zahlungsart und eindeutiger Hosted-Checkout-Übergang.
Der externe Mollie Hosted Checkout bleibt absichtlich eine eigene
Top-Level-Seite. Das ist keine UX-Lücke des neuen Aktivierungsflows, sondern
die bestehende PCI-arme Provider-Grenze; die HiveGrid-Seite erklärt nun vor
dem Redirect exakt Betrag und Folge der Zahlung.
@@ -0,0 +1,196 @@
# BILL-19 · Registrierung bis Zahlung als klaren Aktivierungsflow führen
| | |
| ----------------- | ------------------------------------------------------ |
| **Typ** | Launch-Fix · Registrierungs-/Billing-UX |
| **Owner** | Raffael |
| **Phase** | Pilot-Härtung |
| **Cycle/Fenster** | gestartet 2026-08-02 |
| **Status** | Done |
| **Plane** | HIVEGRID-240 |
## Abhängigkeiten & Parallelität
- **Blocked by:** `BILL-14` und `BILL-18` sind Done und liefern die
zweistufige Registrierung, persistierte Tarif-/Sitzpräferenz sowie den
gehärteten CAPTCHA-Retry.
- **Blocks:** `BILL-20` und damit die visuelle und funktionale Pilotabnahme des
kompletten Signup-zu-Zahlung-zu-Welcome-Flows.
- **Abhängigkeitsschutz:** Workspace-Bootstrap, Katalog, Preise,
Mollie-/Lago-Checkout, Testphasen-Policy, Rechnungen und Entitlement-
Aktivierung bleiben unverändert. `BILL-19` ändert ausschließlich frühe
Clientvalidierung, Navigation/Gating und die Darstellung der bestehenden
Erstaktivierung.
## Was / Warum
Die Konto-Seite ließ ein nach der sichtbaren Passwort-Checkliste noch
ungültiges Passwort in den Tarifschritt wechseln. Der verbindliche Fehler
erschien dadurch erst beim finalen Registrierungs-POST auf der folgenden
Seite.
Nach erfolgreicher Registrierung wird der Workspace technisch vor der Zahlung
angelegt, damit Checkout, Rechnung und spätere Entitlements tenantgebunden
gespeichert werden können. Der Nutzer landete jedoch in der vollständigen
Workspace-/Settings-Hülle. Die Erstaktivierung mischte dort Abonnement,
Nutzung, Testphasenhinweis, alle Tarife, Sitzplätze, Speicher, E-Mail-Marketing
und Rechnungsnavigation. Obwohl Fachmodule serverseitig gesperrt blieben,
wirkte der Workspace bereits freigeschaltet und der notwendige Mollie-Schritt
war visuell nachrangig.
Der Flow wird deshalb als eigener Aktivierungszustand dargestellt: Konto und
Workspace sind angelegt, Produktzugriff bleibt bis bestätigter Zahlung oder
einer tatsächlich im Katalog hinterlegten Testphase gesperrt. Die bestehende
serverseitige Preisvorschau und der Mollie-Checkout bilden die eine primäre
nächste Aktion.
## Nicht im Scope
- Keine Änderung an Tarifpreisen, Sitzformeln, Speicherpaketen oder Features.
- Keine neue oder automatisch gewährte Testphase.
- Keine Zahlung während des Pre-Auth-POSTs und kein eingebetteter
Mollie-Checkout.
- Keine Änderung an Mollie, Lago, Webhooks, Rechnungen oder Entitlements.
- Kein Redesign der laufenden Billing-Verwaltung für bereits aktive Kunden.
## Definition of Done
- [x] Die Konto-Seite zeigt Passwortverletzungen beim Tippen/Verlassen des
Feldes und verhindert den Wechsel zu Team & Tarif, solange die
synchron prüfbaren Policy-Regeln nicht erfüllt sind.
- [x] Nach der Registrierung erklärt ein eigener Aktivierungszustand klar:
Workspace angelegt, noch kein Produktzugriff, Zahlung oder echte
Testphase als nächster Schritt.
- [x] Unbezahlte Tenants sehen auf der Erstaktivierung weder App-Sidebar noch
Settings-Hub; alle anderen App-/Settings-Ziele bleiben serverseitig am
bestehenden Plan-Gate hängen.
- [x] Der Aktivierungsscreen übernimmt Tarif und Büro-/Baustellenplätze,
trennt Pflichtauswahl von optionalem Speicher und zeigt höchstens eine
primäre Checkout-Aktion.
- [x] Die serverseitige Preisvorschau erscheint im Aktivierungsflow mit
Netto, Umsatzsteuer, Zahlbetrag, Abrechnungszeitraum und eindeutiger
Testphasen-/Sofortzahlungsinformation vor Mollie.
- [x] Laufende Billing-Verwaltung für aktive oder echte Trial-Tenants bleibt
funktional und visuell unverändert; E-Mail-Marketing wird nicht vor der
Basisaktivierung angeboten.
- [x] Unit-, Route-, Component-, Accessibility- und Desktop-/Mobile-
Visualtests decken Passwortgrenze, Gate und Aktivierungszustand ab.
- [x] Typecheck, Lint, vollständige Testsuite, passende Verifier, PR-CI,
Staging-Deploy und ein ausschließlich mit Mollie TEST ausgeführter
Signup-zu-Zahlung-UAT sind grün.
**BILL-19: 8/8 DoD = 100 % done. 0 Punkte offen.**
2026-08-02 · Abhängigkeitsschutz für `BILL-22`
- `BILL-22` ersetzt die dichte Aktivierungsdarstellung durch einen geführten
Team-/Tarif-/Upsell-/Zahlungsablauf. Das appweite Gate aus diesem Ticket
bleibt unverändert: ohne bestätigte Basiszahlung oder echte Katalog-
Testphase gibt es keinen Produktzugriff.
## Technische Bausteine
- `apps/web/app/modules/users/components/RegisterScreen.tsx`
- `apps/web/app/routes/app.$tenant.tsx`
- `apps/web/app/routes/app.$tenant/settings/billing.tsx`
- `apps/web/app/routes/app.$tenant/settings/billing/index.tsx`
- `apps/web/app/components/screens/billing/SelfServiceSubscriptionPage.tsx`
- bestehende Billing-/Registration-View-Models und `~/ui`-Komponenten
- CR-017 in `docs/CHANGE-REQUESTS.md`
## Rollback
Reiner Code-/UI-Rollback auf die bisherige Workspace-/Billing-Hülle. Es gibt
keine Migration, keinen Backfill und keine Provider-Mutation. Bereits
angelegte Workspaces, Zahlungen, Rechnungen und Entitlements bleiben
unverändert. Der bestehende serverseitige Subscription-Gate bleibt auch beim
Rollback aktiv.
## Umsetzungs-Notiz
2026-08-02 · Diagnose und Start
- Staging-Screenshot und Quellcode gemeinsam geprüft. Das Backend schaltet
Fachmodule ohne Subscription-Produkt oder aktive Testphase nicht frei.
Die gesamte Settings-Hülle war jedoch ausgenommen und vermittelte dadurch
fälschlich einen bereits nutzbaren Workspace.
- Die bestehende Erstkaufseite vermischt sechs Informationsaufgaben. Der
notwendige Preis-/Mollie-Schritt liegt erst unter Status, Nutzung und
allgemeiner Testphaseninformation.
- Die Passwort-Checkliste berechnet die synchronen Policy-Regeln bereits,
bindet sie aber nicht an die native Feldvalidität oder den Übergang in den
Tarifschritt.
- `BILL-14` und `BILL-18` in Ticket-Docs und Plane in beide Richtungen gelesen.
Der neue Slice konsumiert ihre Verträge, ohne Katalog-, Provider- oder
Entitlement-Schnittstellen zu ändern.
- Plane-Identität als `raffael@tool-ctrl.de` bestätigt; `HIVEGRID-240`
angelegt, Raffael zugewiesen und auf In Progress gesetzt.
- Preflight auf aktuellem `origin/main`: EU-Provider-Guard leer, Typecheck und
Core-Testlauf grün.
**BILL-19: 0/8 DoD = 0 % done. 8 Punkte selbst machbar.**
2026-08-02 · Lokale Umsetzung und Re-Audit
- `9bff9e550`: Die sichtbare Passwort-Policy ist jetzt eine echte
Schrittgrenze. Ungültige Werte erzeugen einen lokalisierten Inline-Fehler,
bleiben im Kontoschritt und fokussieren das Passwortfeld.
- `80dcefbb8`: Unbezahlte Tenants dürfen ausschließlich die exakte
Billing-Aktivierung öffnen. Die Route rendert ohne App-/Settings-Chrome und
übernimmt Tarif, Rollenplätze und optionalen Speicher in einen fokussierten
Checkout mit genau einer primären Aktion.
- Preisvorschau und Hosted-Checkout-Vertrag bleiben serverautoritativ. Die
Vorschau unterscheidet echte Trial-Tage von sofort erforderlicher Zahlung
und zeigt Netto, Umsatzsteuer und Brutto vor dem Mollie-Redirect.
- Visueller Re-Audit: `23/24`; Desktop, Mobile, Passwortzustand und
Mollie-Vorschau liegen als Playwright-Baselines im Repo und im Desktop-Ordner
`HiveGrid-BILL-19-UX-Review-2026-08-02`.
- Proof lokal: Typecheck, Lint, i18n, CI-Baseline, Source-Health, Hot-Swap,
A11y-Coverage, vier Chromium-Component-Tests und die vollständige Suite mit
`1176` bestandenen Dateien / `8280` bestandenen Tests sind grün.
**BILL-19: 7/8 DoD = ~88 % done. Offen: PR-CI, Staging-Deploy und
ausschließlich mit Mollie TEST ausgeführter Signup-zu-Zahlung-UAT.**
2026-08-02 · Abhaengiger Welcome-/Billing-Nachzug
- `BILL-20` konsumiert den hier gelieferten Aktivierungscheckout und setzt erst
nach bestaetigtem Return mit Welcome/Setup fort. Subscription-Gate,
Preisvorschau und Mollie-Vertrag bleiben unveraendert. Der finale
`BILL-19`-UAT wird deshalb gemeinsam mit der kompletten Folge-Journey belegt.
2026-08-02 · Staging-Gate-Nachzug aus BILL-20
- Der echte Signup-UAT deckte auf, dass die Billing-Aktivierung bei global
optionaler Subscription-Konfiguration nicht aus der persistierten Tarifwahl
der Registrierung abgeleitet wurde. Dadurch blieb die Fachnavigation auf
Staging sichtbar, obwohl der Workspace noch unbezahlt war.
- `BILL-20` zieht diesen blockierenden Vertrag mit `92845ec15` fail-closed nach:
Persistierte Signup-Praeferenz plus fehlender Subscription-Zugriff erzwingt
die appweite Aktivierungsroute; ein bestaetigtes Abo oder eine echte
Katalog-Testphase hebt den Gate wieder auf. Die vorhandenen Preis-, Mollie-
und Entitlement-Vertraege bleiben unveraendert.
**BILL-19: 7/8 DoD = ~88 % done. Offen: Hotfix-CI, Staging-Deploy und der
fortgesetzte Mollie-TEST-UAT.**
2026-08-02 · Finaler Aktivierungs-UAT
- PRs `#350`, `#351` und `#352` sind normal nach `main` gemergt. Der finale
Merge `0172889382`, Main-Runs `11817` bis `11820` und der vollstaendige
Coolify-Staging-Deploy sind gruen.
- Der komplette frische Signup bestaetigt die fruehe Passwortgrenze, den
Team-/Tarifschritt, Test-CAPTCHA und den fokussierten Aktivierungszustand.
Die verschachtelten App-/Settings-Layouts liefern dort keine Sidebar, keine
Icon-Rail und keine Billing-Tabs; ein direkter Dashboard-Aufruf wird
serverseitig auf `plan-required` abgefangen.
- Die Basisaktivierung wurde ausschliesslich mit Mollie TEST als Swarm-Jahres-
SEPA fuer 5 Buero-/15 Baustellen-Nutzer bezahlt. Preisvorschau,
Providerbetrag, Return und Rechnung stimmen bei `449,00 EUR` netto,
`85,31 EUR` USt. und `534,31 EUR` Zahlbetrag ueberein. Ohne bestaetigte
Zahlung blieb ein zweiter Test-Workspace gesperrt.
- Desktop-/Mobile- und Live-Nachweise wurden nach vollstaendigem Laden visuell
geprueft; die finale Aktivierung liegt als `36-activation-final-no-settings-
chrome.png` im BILL-20-Desktop-Review-Ordner.
**BILL-19: 8/8 DoD = 100 % done. 0 Punkte offen.**
@@ -0,0 +1,271 @@
# BILL-20 · Bezahlten Workspace mit Welcome-Setup statt CRM-Sprung starten
| | |
| ----------------- | ------------------------------------------------------ |
| **Typ** | Launch-Fix · Welcome-/Billing-UX |
| **Owner** | Raffael |
| **Phase** | Pilot-Härtung |
| **Cycle/Fenster** | gestartet 2026-08-02 |
| **Status** | Done |
| **Plane** | HIVEGRID-241 |
**🎨 design-nachzug: offen** — der Pilot-Slice nutzt gemaess AD-28 die
bestehenden `~/ui`-Bausteine. `VD-P24` enthaelt weiterhin kein finales
Welcome-/Billing-Delta.
## Abhängigkeiten & Parallelität
- **Blocked by:** `BILL-19` liefert den klaren, app-chrome-freien
Erstaktivierungscheckout. `AK-P20` liefert die RLS-gebundene,
resumierbare Erste-Schritte-Session. `VA-P24a`, `BILL-13`, `BILL-14`,
`BILL-15` und `MAIL-01` liefern Self-Service-Billing, Mollie-Return,
Registrierung, Customer-Portal-Kaufvertrag und Willkommensmail.
- **Blocks:** visuelle und funktionale Pilotabnahme vom Signup ueber
Mollie TEST bis zum eingerichteten Workspace sowie die abschliessende
`BILL-19`-Journey-Abnahme.
- **Keine Reaktivierung von `VA-P24b`:** Der gecancelte 10-Schritt-Wizard mit
YAML-Branchen-Template, irreversiblem Step-Cursor und Demo-Daten-Orchestrierung
bleibt ausserhalb dieses Launch-Slices. `BILL-20` baut eine fokussierte
Welcome-/Setup-Surface auf der vorhandenen AK-P20-Session.
- **Abhängigkeitsschutz:** Katalog, Preise, Trial-Policy, Checkout,
Webhook-/Return-Sync, Rechnungen, Entitlements, Customer-Portal-Commerce und
transaktionale Mailzustellung bleiben autoritativ und unveraendert. Es gibt
keine neue Testphase, kein Provider-Embedding und keine Schema-Migration.
## Was / Warum
Nach einer bestaetigten Zahlung zeigt HiveGrid derzeit eine eigenstaendige
Erfolgsseite mit drei gleichrangigen Abzweigungen und leitet nach zehn Sekunden
automatisch auf das Dashboard weiter. Dadurch bestimmt ein Timer statt des
Nutzers den naechsten Schritt; die vorhandene Erste-Schritte-Session wird nicht
als Welcome-Phase genutzt und die wichtige Team-Einladung bleibt vom
resumierbaren Setup getrennt.
Die aktive Billing-Seite stapelt zugleich aktuellen Vertrag, Nutzung,
allgemeine Trial-Policy, kompletten Tarif-/Seat-/Speicher-Builder und
E-Mail-Marketing-Pakete in einer langen Flaeche. Laufender Vertrag,
Tarifaenderung und Zusatzmodule sind unterschiedliche Nutzeraufgaben und
werden deshalb getrennt.
Der Pilot-Flow wird zu einer klaren Journey:
1. Registrierung und Team-/Tarifempfehlung.
2. App-chrome-freie Basisaktivierung mit serverseitiger Preisvorschau.
3. Mollie Hosted Checkout im TEST-Modus.
4. Bestaetigung ohne automatischen CRM-/Dashboard-Sprung.
5. Eigene Welcome-/Setup-Surface mit automatisch fortschreitenden Aufgaben
fuer Profil, Team-Einladung, ersten Kontakt, erstes Projekt und Billing.
6. Bewusster Wechsel ins Dashboard; das Setup bleibt dort resumierbar.
## Nicht im Scope
- Kein 10-Schritt-Wizard, keine Branchenwahl und keine neuen Demo-Seeds.
- Keine neuen Preise, Plaene, Add-ons, Trial-Tage oder Entitlements.
- Kein eingebetteter Mollie-Checkout; Hosted Checkout bleibt der sichere
Provider-Schritt.
- Keine neue Team-Einladungs-Domain und kein Multi-Invite-Backend; die
bestehende tenantgebundene Einladungsroute wird als Setup-Aktion verwendet.
- Keine neue Customer-Portal-Kauflogik; das Billing verweist auf den bestehenden
`VA-P26c`-Kauf-/Domain-Flow.
- Keine neue Willkommensmail. Der mit `CR-015` gehaertete `MAIL-01`-Flow wird
als Teil der Launch-Abnahme erneut visuell und technisch auditiert.
## Definition of Done
- [x] Der bestehende Signup-/Aktivierungsflow bleibt fachlich unveraendert:
Ohne bestaetigte Basiszahlung oder echte Katalog-Testphase gibt es keinen
Produktzugriff.
- [x] Der erfolgreiche Checkout-Return bestaetigt Plan/Zahlungszustand, hat
keinen Timer und fuehrt mit genau einer primaeren Aktion in das Setup.
- [x] Eine responsive, app-chrome-freie Welcome-Surface zeigt Workspace,
naechsten Nutzen und Setup-Fortschritt; das Dashboard ist eine bewusste
Sekundaeraktion, nicht der automatische Zielort.
- [x] Profil, Team-Einladung, erster Kontakt, erstes Projekt und Billing werden
tenant-/usergebunden erkannt. Bestehende Membership oder ausstehende
Einladung erfuellt den Team-Schritt; Deep-Links nutzen die bestehenden
geschuetzten Routen.
- [x] Das Setup bleibt ueber die vorhandene Onboarding-Session und das
Dashboard-Widget resumierbar; manuelles Erledigen ist nur fuer echte
Session-Schritte moeglich.
- [x] Die aktive Billing-Hauptseite startet mit einer kompakten Uebersicht und
trennt `Tarif & Nutzer` von `Zusatzmodule`, statt alle Editoren dauerhaft
untereinander zu stapeln.
- [x] Speicher, E-Mail-Marketing und Customer-Portal sind als getrennte
Zusatzmodul-Aufgaben erklaert. Checkout und Freischaltung verwenden
ausschliesslich die vorhandenen serverautoritativen Vertraege.
- [x] Loading-, Empty-, Error-, Permission- und Read-only-Zustaende sowie alle
neuen Texte sind in de/en und informell/formell verstaendlich; Tastatur,
Fokus und mobile Darstellung sind abgedeckt.
- [x] Pure View-Model-, Service-, Route-, Component-, Accessibility-,
Hot-Swap- und Desktop-/Mobile-Visualtests decken Welcome, Team-Erkennung,
Checkout-Return und die Billing-Navigation ab.
- [x] Typecheck, Lint, vollstaendige Testsuite und passende Release-/Source-/
i18n-/A11y-/Visual-Verifier sind gruen.
- [x] Jeder sichtbare Registrierungs-, Zahlungs-, Welcome-, Setup- und
Billing-Zustand liegt nach manueller Bildpruefung als fertig geladener
Screenshot im Desktop-Review-Ordner.
- [x] PR-CI, normaler Merge, Staging-Deploy und ein ausschliesslich mit Mollie
TEST ausgefuehrter Signup-zu-Zahlung-zu-Welcome-UAT inklusive Rechnung,
Entitlements und Zusatzmodul-Einstiegen sind gruen.
**BILL-20: 12/12 DoD = 100 % done. 0 Punkte offen.**
2026-08-02 · Abhängigkeitsschutz für `BILL-22`
- `BILL-22` führt Speicher und E-Mail-Marketing bereits vor der Zahlung als
getrennte, optionale Entscheidungen. Die Welcome-Surface, der bewusste
Dashboard-Wechsel und die bestätigungsgebundene Add-on-Freischaltung aus
diesem Ticket bleiben unverändert.
2026-08-02 · Erster Staging-UAT und fail-closed Nachzug
- PR `#350` wurde nach vollstaendig gruener CI normal als `b55fd29e8` nach
`main` gemergt; Staging-Deploy `11792` war fuer Web und API gesund.
- Der echte Registrierungs-UAT bestaetigte die neue Passwortgrenze, die
Swarm-Empfehlung fuer 5 Buero-/15 Baustellen-Nutzer und den direkten Weg in
Billing statt CRM. Dabei zeigte sich eine reale Umgebungsluecke: Auf Staging
war `subscription.required=false`, wodurch die persistierte Tarifwahl aus
der Registrierung den appweiten Aktivierungs-Gate nicht einschaltete.
- `92845ec15` macht die persistierte Signup-Billing-Praeferenz zur
serverseitigen Aktivierungsentscheidung. Ohne bestaetigte Zahlung oder echte
Trial-Berechtigung sind App-Chrome und Fachrouten nun auch bei global
optionalem Billing gesperrt; die exakte Aktivierungsroute bleibt erreichbar.
- Proof des Nachzugs: 25/25 fokussierte Root-/Gate-Tests, Typecheck, Lint und
die vollstaendige Suite mit 1.184 Testdateien / 8.238 Tests sind gruen.
Vier vollstaendig geladene Live-Screens der Registrierung liegen bereits im
Review-Ordner; Zahlung, Welcome und Billing folgen erst nach dem Hotfix-
Deploy mit Mollie TEST.
**BILL-20: 11/12 DoD = ~92 % done. 1 Punkt offen und selbst machbar: Hotfix-CI,
normaler Merge, Staging-Deploy und Fortsetzung desselben Live-UAT.**
## Technische Bausteine
- `apps/web/app/routes/subscribe.$tenant.$session.success.tsx`
- neue Route `apps/web/app/routes/app.$tenant/onboarding/welcome.tsx`
- `apps/web/app/routes/app.$tenant.tsx`
- `apps/web/app/utils/services/.server/akP20OnboardingService.ts`
- `packages/view-models/src/onboarding/**`
- `apps/web/app/components/screens/onboarding/**`
- `apps/web/app/components/screens/billing/SelfServiceSubscriptionPage.tsx`
- `apps/web/app/routes/app.$tenant/settings/billing/index.tsx`
- bestehende `~/ui`-Komponenten, keine Direktimporte aus `ui-subframe`
- CR-018 in `docs/CHANGE-REQUESTS.md`
## Rollback
Reiner Code-/UI-Rollback auf Checkout-Erfolgsseite, vorhandene Checklistenroute
und den bisher dauerhaft ausgeklappten Billing-Builder. Es gibt keine Migration,
keinen Backfill und keine Provider-Mutation. Bereits bestaetigte Zahlungen,
Rechnungen, Entitlements, Einladungen und Onboarding-Sessions bleiben
unveraendert. Der Subscription-Gate aus `BILL-19` bleibt auch beim Rollback
fail-closed.
## Quellen
- `docs/CHANGE-REQUESTS.md` · CR-018
- `.planning/ticket-docs/BILL-19.md`
- `.planning/ticket-docs/AK-P20.md`
- `.planning/ticket-docs/VA-P24a.md`
- `.planning/ticket-docs/VA-P24b.md` · explizite Nicht-Uebernahme
- `.planning/ticket-docs/BILL-15.md`
- `.planning/ticket-docs/MAIL-01.md`
- `docs/AGENT-CHECKLIST.md`
## Umsetzungs-Notiz
2026-08-02 · Diagnose und Start
- `origin/main` nach PR `#347`/Merge `5a2a82224` in einem isolierten Worktree
ausgecheckt. EU-Provider-Guard, Workspace-Typecheck und der vollstaendige
Baseline-Lauf mit 1.176 Testdateien / 8.280 Tests sind gruen. Staging-Deploy
`11737` ist ebenfalls gruen.
- Bestehenden Provider-/App-Flow bis in Return, Billing-Loader, Portal-Commerce,
Onboarding-Session und Dashboard-Widget verfolgt. Der Bruch ist
praesentationsseitig: Der Return besitzt einen 10-Sekunden-Timer, waehrend
die aktive Billing-Seite drei verschiedene Aufgaben in einer langen
Editor-Flaeche vermischt.
- Offizielle Muster von Linear, Notion, Slack und Intercom verglichen:
Einladungen sind eine eigene, klar bepreiste Setup-Aufgabe; Billing trennt
Plan, Zahlungsdaten/Rechnungen und Add-ons; Onboarding arbeitet mit kleinen,
automatisch fortschreitenden Aufgaben statt eines erzwungenen Tours.
- Abhaengigkeiten in beide Richtungen in den Ticket-Docs und in Plane gelesen.
`BILL-20` konsumiert bestehende Vertraege und reaktiviert `VA-P24b` nicht.
- Plane-Identitaet als `raffael@tool-ctrl.de` bestaetigt; `HIVEGRID-241`
angelegt, Raffael zugewiesen und auf In Progress gesetzt.
**BILL-20: 0/12 DoD = 0 % done. 12 Punkte selbst machbar.**
2026-08-02 · Lokale Implementierung und Abnahme
- `f99d03624` ersetzt Timer und CRM-/Dashboard-Sprung durch einen
app-chrome-freien, responsiven Welcome-/Setup-Screen. Profil,
Team-Einladung, Kontakt, Projekt und Billing werden tenant- und
usergebunden aus der vorhandenen AK-P20-Session abgeleitet; das
Dashboard-Widget nimmt den Flow wieder auf.
- `738eaef12` strukturiert die aktive Billing-Verwaltung in die drei
Hauptaufgaben `Uebersicht`, `Nutzung` und `Rechnungen`. Tarif/Nutzer sowie
Speicher, E-Mail-Marketing und Customer-Portal liegen als getrennte,
erklaerte Unteraufgaben vor; Checkout-, Preis- und Entitlement-Vertraege
bleiben serverautoritativ.
- `ab6c9b447` macht den Checkout-Beleg autoritativ: Er unterscheidet
bestaetigte Zahlung, echte Katalog-Testphase und nullpreisige Aenderung,
zeigt den gespeicherten Plan sowie den monatlichen Bruttobetrag inklusive
Zusatznutzern, Speicher und Umsatzsteuer und erfindet kein Rechnungsdatum.
- `45a5d327b` registriert die neue Welcome-Route in den harten Runtime- und
Route-Inventar-Baselines.
- Vollstaendige Regression: 1.178 Testdateien / 8.286 Tests gruen, 60
umgebungsgebundene Integrationstests erwartungsgemaess uebersprungen.
Zusaetzlich sind `pnpm test:packages`, Typecheck, Lint, Billing-Katalog,
Billing-Boundary, Route-Inventar, Sidebar-Routen, i18n, Onboarding,
Phase-C-Grenzen, Hot-Swap, 45 fokussierte A11y-Tests, A11y-Coverage,
Source-Health, CI-Baseline und Staging-UAT-Readiness gruen. Der globale
`verify:a11y-baseline`-Altbestand auf `main` meldet 66 statt historisch 56
`jsx-a11y/no-autofocus`-Treffer; der Branch fuegt keinen `autoFocus`-Treffer
hinzu und veraendert diese Altlast nicht.
- 35 vollstaendig geladene und manuell gepruefte lokale beziehungsweise
vorherige Staging-Nachweise liegen in
`~/Desktop/HiveGrid-BILL-20-Welcome-Billing-UAT-2026-08-02`. Der getrennte
Ordner `live-staging/` wird erst nach Merge und Deploy gefuellt.
**BILL-20: 11/12 DoD = ~92 % done. 1 Punkt offen und selbst machbar: PR-CI,
normaler Merge, Staging-Deploy und Live-UAT.**
2026-08-02 · Finaler Merge, Deploy und Live-UAT
- PR `#350` lieferte Welcome-Setup, resumierbares Dashboard-Widget und die
aufgeteilte Billing-Verwaltung; PR `#351` zog den fail-closed Gate fuer eine
persistierte, noch unbezahlte Signup-Auswahl nach. PR `#352` behob die im
echten UAT gefundenen Restabweichungen: autoritativer Bruttobetrag im Return,
aktuelle Core-/Swarm-/Colony-Namen und kein verschachtelter Settings-Chrome
auf der Erstaktivierung.
- PR `#352` wurde nach gruener Bundle-, Coverage- und Voll-CI normal als
`0172889382` nach `main` gemergt. Ein erster Docker-Smoke lief bei drei
parallelen Runtime-Dateisystemscans in das gemeinsame 90-Sekunden-Limit;
der unveraenderte SHA bestand Attempt 2 vollstaendig. Main-Runs `11817` bis
`11820`, Build-once-Images und der komplette Coolify-Staging-Deploy sind
gruen.
- Echte Staging-Journey ausschliesslich mit Mollie TEST: Swarm, 5 Buero- und
15 Baustellen-Nutzer, 12 Monate SEPA, `449,00 EUR` netto plus `85,31 EUR`
USt. Die Testzahlung und die bezahlte Rechnung stimmen mit `534,31 EUR`
ueberein; Plan, 20 Plaetze und 250 GB sind aktiv. Der Return bleibt auch nach
13 Sekunden stehen und fuehrt erst per bewusster Aktion ins Setup.
- Das Welcome-Setup wurde durch eine ausstehende Testeinladung, den Kontakt
`Pilot Kontakt` und das Projekt `Pilotprojekt Nord` von 2/5 auf 5/5
fortgeschrieben. Das Dashboard-Widget bleibt danach sichtbar und meldet alle
Setup-Schritte als erledigt.
- Zusatzmodul-Einstiege wurden getrennt geprueft: Speicher `+100 GB`,
E-Mail-Marketing `S` mit 10.000 Nachrichten und Customer Portal bis zum
Mollie-TEST-Checkout. Der zweite Customer-Portal-Checkout wurde nicht
bezahlt; die bereits abgenommene BILL-14/15-Staging-Referenz belegt Zahlung,
Rechnung und Entitlement fuer Speicher, E-Mail-Marketing und Customer Portal.
- Ein zweiter, frischer Signup nach dem finalen Deploy belegt den unbezahlten
Zustand: Activation-Shell `1`, Workspace-Shell `0`, Settings-Hub `0`; ein
direkter Dashboard-Aufruf endet auf `plan-required` ohne Produkt-Chrome.
- 37 vollstaendig geladene und manuell gepruefte Live-Bilder plus lokale und
vorherige Provider-Referenzen liegen in
`~/Desktop/HiveGrid-BILL-20-Welcome-Billing-UAT-2026-08-02`. Die
Welcome-Mail wurde anhand der lokalisierten HTML-/Plaintext-Staging-Zustellung
erneut auditiert; BILL-20 fuegt keinen konkurrierenden Mail-Flow hinzu.
**BILL-20: 12/12 DoD = 100 % done. 0 Punkte offen.**
@@ -0,0 +1,159 @@
# BILL-21 · Mollie-Zahlungen über 1.000 € ausschließlich per Karte einziehen
| | |
| ----------------- | --------------------------------------------- |
| **Typ** | Launch-Fix · Billing-/Payment-Sicherheit |
| **Owner** | Raffael |
| **Phase** | Pilot-Härtung |
| **Cycle/Fenster** | gestartet 2026-08-02 |
| **Status** | Done |
| **Plane** | HIVEGRID-242 |
## Abhängigkeiten & Parallelität
- **Blocked by:** `BILL-11` definiert Katalog und invoice-getriebenes
Recurring, `BILL-13` die Mollie-Methodenauswahl und `BILL-14` den
Registrierungs-/Erstkaufpfad. Alle drei Tickets sind Done.
- **Blocks:** `BILL-08` Production-Aktivierung. Der bisherige externe Blocker
„SEPA-Limit anheben“ wird durch einen fail-closed Kartenvertrag ersetzt.
- **Abhängigkeitsschutz:** Preise, Vertragslaufzeit, technische
`annual_sepa`-Codes, Lago-Rechnungen, Entitlements und Hosted Checkout
bleiben unverändert. Der Code ist aus Kompatibilitätsgründen weiterhin ein
Katalogname, aber keine Zusage, Zahlungen oberhalb des Providerlimits per
Lastschrift einzuziehen.
## Was / Warum
Mollie dokumentiert für SEPA Direct Debit standardmäßig maximal 1.000 EUR je
Transaktion. Colony kostet bereits ohne Zusatznutzer oder Speicher 899 EUR
netto beziehungsweise 1.069,81 EUR brutto. HiveGrid filterte bei
12-Monatsverträgen Karten bislang vollständig heraus und erzwang im Worker
später erneut `directdebit`. Im aktivierten Testprofil blieb dadurch sichtbar
nur iDEAL: Die kundenpräsente iDEAL-Erstzahlung erzeugt ein SEPA-Mandat, löst
aber das Limit der späteren Lastschrift nicht.
Der verbindliche Vertrag lautet:
- Bis einschließlich 1.000,00 EUR brutto bleibt die bisherige, von Mollie für
`sequenceType=first` freigegebene Mandatsauswahl gültig.
- Ab 1.000,01 EUR brutto ist `creditcard` die einzige zulässige Methode.
- Dieselbe Grenze gilt für Basisplan-, Änderungs- und Add-on-Checkouts sowie
für die invoice-getriebene wiederkehrende Zahlung.
- Bietet das konkrete Mollie-Profil für den Betrag keine Karte an, bricht
HiveGrid vor Lago-/Mollie-Mutationen ab und erklärt den Zustand im UI.
## Nicht im Scope
- Keine eigenen Kartenfelder, kein Iframe und keine Speicherung von Karten-,
Bank- oder Mandatsdaten in HiveGrid.
- Keine Preis-, Rabatt-, Vertragslaufzeit-, Steuer- oder Entitlement-Änderung.
- Keine Production-Live-Zahlung und keine Umgehung der übrigen `BILL-08`-Gates.
- Keine automatische Aufteilung einer Rechnung in mehrere Teilzahlungen.
## Definition of Done
- [x] Ein zentraler, reiner Payment-Policy-Contract definiert die exakte
Grenze: 100.000 Cent erlaubt SEPA, 100.001 Cent verlangt Karte.
- [x] Basisplan- und Planwechsel-Previews zeigen oberhalb der Grenze nur die
aktuell verfügbare Mollie-Kartenmethode.
- [x] Ohne verfügbare Karte bricht der Basischeckout vor jeder Lago-/Mollie-
Mutation mit einem sicheren Klartextzustand ab.
- [x] Wiederkehrende und einmalige Add-on-Käufe verwenden oberhalb der Grenze
denselben Kartenvertrag.
- [x] Der Recurring-Worker setzt für Rechnungen oberhalb der Grenze
`sequenceType=recurring` plus `creditcard`, statt `directdebit` aus dem
technischen Katalogcode abzuleiten.
- [x] Die Billing-UI erklärt die Kartenpflicht, zeigt eine fehlende Karte als
Fehler und deaktiviert die Checkout-Aktion.
- [x] Unit-, Service-, Worker-, UI-, i18n- und Grenzwerttests decken 1.000,00
EUR, 1.000,01 EUR und fehlende Kartenverfügbarkeit ab.
- [x] Typecheck, Lint, vollständige Testsuite und passende Billing-/Source-
Verifier sind grün.
- [x] Plane, abhängige Ticket-Docs und Change-Request dokumentieren Ergebnis,
Proof und verbleibende Production-Gates konsistent.
**BILL-21: 9/9 DoD = 100 % done. Kein selbst machbarer Punkt offen.**
2026-08-02 · Abhängigkeitsschutz für `BILL-22`
- `BILL-22` erhält die harte Grenze von 100.000/100.001 Cent, öffnet darunter
aber die kundenseitige Wahl einschließlich Kreditkarte. Außerdem wird der
hier gefundene Worker-/Gateway-Widerspruch geschlossen: Recurring-Karte ist
nur mit passendem gültigem Mandat zulässig; ein fehlendes Mandat bleibt
fail-closed und fällt nie auf SEPA zurück.
2026-08-02 · Release-Proof
- PR `#354` lief auf Head `0b9351eef` mit 13/13 grünen Checks und wurde
ausschließlich per normalem Merge-Commit `86eb01825` in `main` übernommen;
die drei atomaren Feature-Commits bleiben vollständig in der Historie.
- Main-/Staging-Run `3082` sowie alle vier Main-Statuschecks sind grün. Der
Run baute und promotete die unveränderlichen Images und schloss den
Coolify-/Readiness-Pfad erfolgreich ab.
- `https://staging-app.hivegrid.de/healthz` und `/readyz` melden
`hivegrid-web`, `core`, `86eb01825af39d9c28fcd663887d3189cfeb0854` als
gesund beziehungsweise bereit. Die beiden entsprechenden Endpunkte auf
`https://staging-api.hivegrid.de` melden dieselbe Revision für `api`.
- Es wurde keine Production-Zahlung und keine Production-Promotion ausgelöst.
**BILL-21: 9/9 DoD = 100 % done. Kein selbst machbarer Punkt offen.**
## Rollback
- Der zentrale Resolver und seine drei Konsumenten können gemeinsam auf den
vorherigen Methodenvertrag zurückgesetzt werden. Bereits erzeugte Zahlungen,
Rechnungen und Mandate bleiben append-only und werden nicht gelöscht.
- Der bestehende Provider-Side-Effect-Gate kann das Recurring-Inkasso stoppen.
Ein Rollback darf niemals eine Rechnung oberhalb von 1.000 EUR automatisch
auf `directdebit` zurückfallen lassen; bis zur Korrektur bleibt sie offen.
## Quellen
- https://docs.mollie.com/docs/sepa-direct-debit
- https://docs.mollie.com/docs/cards
- https://docs.mollie.com/docs/recurring-payments
- https://docs.mollie.com/reference/create-customer-payment
- `.planning/ticket-docs/BILL-08.md`
- `.planning/ticket-docs/BILL-11.md`
- `.planning/ticket-docs/BILL-13.md`
- `.planning/ticket-docs/BILL-14.md`
## Umsetzungs-Notiz
2026-08-02 · gestartet
- Plane-Ticket `HIVEGRID-242` angelegt, Raffael zugewiesen und auf In Progress
gesetzt. Die Plane-Identität wurde als `raffael@tool-ctrl.de` geprüft.
- `blocked-by` und `blocks` wurden in Plane sowie in den vier abhängigen
Ticket-Docs in beide Richtungen gelesen. `CR-019` genehmigt den Ersatz des
externen SEPA-Limit-Gates durch die harte Kartenregel.
- Baseline vor dem ersten Edit: Typecheck grün, Core-Suite 8.244 Tests grün
(60 übersprungen), EU-Provider-Guard leer.
**BILL-21: 0/9 DoD = 0 % done. 9 Punkte selbst machbar.**
2026-08-02 · umgesetzt
- `1ff12656c` zentralisiert das dokumentierte EUR-1.000-SEPA-Limit und
erzwingt ab 100.001 Cent `creditcard` in Basis-/Änderungscheckout, Add-ons
und invoice-getriebenem Recurring-Worker. Die serverseitige Methods-Abfrage
prüft den konkreten Betrag und bricht ohne angebotene Karte vor
Lago-/Mollie-Mutationen ab.
- `70765fae3` ergänzt den expliziten Kartenstatus im View-Model, Klartext in
de/en, automatische Auswahl der einzigen Kartenmethode, deaktivierte
Checkout-Aktionen sowie UI-/A11y-Regressionsproof.
- Ein 0,00-EUR-`first`-Payment für Kreditkarte bleibt bei Trial und
periodischem Planwechsel zulässig und erzeugt laut Mollie-Dokumentation das
für die spätere Kartenbelastung benötigte Mandat. Der tatsächlich fällige
Folgebetrag steuert bereits bei dieser Autorisierung die Kartenregel.
- Proof: `pnpm typecheck`, `pnpm lint`, vollständige Core-Suite mit 1.185
Testdateien / 8.252 bestandenen Tests / 60 bewusst übersprungenen Tests,
zusätzlich 127 fokussierte Billing-/Worker-/UI-Tests sowie
`verify:i18n`, `verify:billing-boundary-baseline`, `verify:source-health`
und `verify:ci-baseline` grün. `git diff --check` ist sauber; keine
Schema-/Migration-/Secret-Änderung.
- Die verbleibenden Production-Gates sind unverändert in `BILL-08`: Mollie
Live/KYC und Legal-/Steuerfreigabe. Eine echte Production-Zahlung wurde
nicht ausgelöst.
**BILL-21: 9/9 DoD = 100 % done. Kein selbst machbarer Punkt offen.**
@@ -0,0 +1,227 @@
# BILL-22 · Geführter Checkout mit freier Zahlart und Add-on-Upsells
| | |
| ----------------- | ------------------------------------------------ |
| **Typ** | Launch-Fix · Registrierungs-/Billing-/Payment-UX |
| **Owner** | Raffael |
| **Phase** | Pilot-Härtung |
| **Cycle/Fenster** | gestartet 2026-08-02 |
| **Status** | In Arbeit · auf Staging deployed |
| **Plane** | HIVEGRID-244 |
**🎨 design-nachzug: offen** (seit 2026-08-02) — der Pilot-Slice nutzt gemäß
AD-28 ausschließlich bestehende `~/ui`-Bausteine; ein finales Subframe-Delta
für den neu geschnittenen Checkout liegt noch nicht vor.
## Abhängigkeiten & Parallelität
- **Blocked by:** `BILL-11`, `BILL-14`, `BILL-19`, `BILL-20` und `BILL-21`
sind Done und liefern Katalog, Registrierungspräferenz, Aktivierungs-Gate,
Welcome-Journey und die EUR-1.000-Kartenregel.
- **Blocks:** `BILL-08` Production-Aktivierung. Dessen Mollie-Live-/Legal-Gates
bleiben unverändert extern blockiert.
- **Abhängigkeitsschutz:** Plan-/Preis-/Entitlement-Codes, Lago-Rechnungen,
bestätigungsgebundene Freischaltung, Hosted Checkout und bestehende aktive
Abos bleiben autoritativ. Der technische Cadence-Code `annual_sepa` bleibt
aus Kompatibilitätsgründen bestehen, erzwingt im Checkout aber keine SEPA-
Auswahl mehr.
## Was / Warum
Die aktuelle Registrierung und Erstaktivierung vermischen Teamgröße, Tarif,
Laufzeit, Speicher, Preisprüfung und Zahlung in langen Karten. Die Empfehlung
ist dadurch weniger klar als die Eingabe, aus der sie entsteht. Zugleich
filtert der 12-Monatsvertrag unterhalb von 1.000 EUR Kreditkarten heraus,
obwohl Mollie diese Zahlart anbietet. Der Recurring-Adapter akzeptiert intern
außerdem nur `directdebit`, obwohl `BILL-21` oberhalb der Grenze `creditcard`
anfordert.
Der neue Vertrag ist ein geführter, responsiver Ablauf:
1. Büro- und Baustellen-Nutzer zuerst erfassen; Slider, Zahleneingabe und
Rollen-Icons bleiben synchron und tastaturbedienbar.
2. Die günstigste passende Konfiguration live serverseitig berechnen,
verständlich begründen und alle Tarife samt echtem Teampreis vergleichen.
3. Zusatzspeicher auf einer eigenen, überspringbaren Seite anbieten und den im
Tarif enthaltenen Speicher klar gegen den Mehrbedarf stellen.
4. E-Mail-Marketing auf einer eigenen Ja/Nein-Seite erklären. Die optionale
Produktbuchung bleibt ein separater, bestätigter Add-on-Checkout nach der
Basisaktivierung; es gibt keine vorgetäuschte Bündelzahlung.
5. Netto, Umsatzsteuer, Brutto, Laufzeit und verfügbare Mollie-Zahlarten auf
einer fokussierten Zahlungsseite zusammenfassen. Bis einschließlich
1.000,00 EUR kann der Kunde einschließlich Kreditkarte frei wählen; ab
1.000,01 EUR ist Karte Pflicht.
6. Wiederkehrende Belastungen verwenden ein gültiges Mandat der gewählten
Methodenfamilie. Eine Rechnung fällt nie still von Karte auf SEPA zurück.
## Nicht im Scope
- Keine eigenen Kartenfelder, kein Mollie-Iframe und keine Speicherung
sensibler Karten-/Bankdaten in HiveGrid.
- Keine Änderung der öffentlichen Speicherpreise in diesem Ticket. Die
Hetzner-Margen werden separat mit Quelle und Preisempfehlung dokumentiert;
eine Preisänderung braucht eine eigene Produktentscheidung.
- Keine neue Testphase, kein Enterprise-Self-Service und keine automatische
Aufteilung großer Rechnungen.
- Keine Production-Live-Zahlung vor den offenen `BILL-08`-Gates.
## Definition of Done
- [x] Registrierung trennt Konto, Teamgröße und Tarifentscheidung; Slider,
Zahleneingabe, Rollen-Icons und vorhandene serverseitige Empfehlung sind
synchron, responsiv und barrierearm.
- [x] Aktivierung führt in klar getrennten Schritten durch Team, Tarif,
Speicher, E-Mail-Marketing und Zahlung; jeder optionale Upsell ist
explizit überspringbar.
- [x] Plan- und Zahlungsseiten zeigen den live serverseitig berechneten Netto-,
Umsatzsteuer- und Bruttobetrag sowie enthaltene und zusätzliche Nutzer/
Speicher ohne zweite clientseitige Preisquelle.
- [x] Unterhalb und einschließlich 1.000 EUR bleiben alle für den konkreten
Betrag von Mollie angebotenen Erstzahlarten wählbar, einschließlich
Kreditkarte; oberhalb bleibt ausschließlich Kreditkarte zulässig.
- [x] Wiederkehrende Mollie-Zahlungen akzeptieren Karte und Lastschrift nur mit
einem gültigen, betragskonformen Mandat; ein fehlendes Kartenmandat
bricht oberhalb der Grenze fail-closed ab.
- [x] E-Mail-Marketing wird als eigener, optionaler Folgeschritt transparent
vom Basischeckout getrennt; Freischaltung erfolgt weiterhin erst nach
bestätigtem Add-on-Checkout.
- [x] Unit-, Service-, Worker-, Route-, Component-, i18n-, A11y-, Hot-Swap-
und Desktop-/Mobile-Visualtests decken Schrittfolge, Livepreise,
Zahlartwahl, Grenze und Mandatsfehler ab.
- [x] Typecheck, Lint, vollständige Testsuite und passende Billing-/Source-/
i18n-/A11y-/Visual-Verifier sind grün.
- [ ] PR-CI, normaler Merge, Staging-Deploy und ein ausschließlich mit Mollie
TEST ausgeführter Signup-zu-Zahlung-UAT sind grün; fertige Screenshots
liegen im Desktop-Review-Ordner.
**BILL-22: 8/9 DoD = ~89 % done. Offen: interaktiver Mollie-TEST-UAT.
PR-CI, normaler Merge, Staging-Deploy und nichtinteraktive Live-Probes sind
grün.**
## Technische Bausteine
- `apps/web/app/modules/users/components/RegisterScreen.tsx`
- `apps/web/app/modules/users/components/RegistrationPlanStep.tsx`
- `apps/web/app/components/screens/billing/SelfServiceSubscriptionPage.tsx`
- `apps/web/app/routes/app.$tenant/settings/billing/index.tsx`
- `apps/web/app/services/billing/payment-methods.server.ts`
- `packages/billing/src/mollie-payment-policy.ts`
- `packages/billing/src/mollie.ts` und `packages/billing/src/types.ts`
- `apps/worker/src/jobs/recurring-invoice-collection.ts`
- bestehende `~/ui`-Komponenten und serverautoritatives Billing-View-Model
- `docs/CHANGE-REQUESTS.md` · CR-021
## Rollback
- UI-Schrittfolge und freie Auswahl unterhalb der Grenze können gemeinsam auf
den bisherigen Aktivierungsbuilder zurückgesetzt werden. Serverseitige
Preis-, Gate- und Entitlement-Verträge bleiben bestehen.
- Bereits erzeugte Mollie-Zahlungen, Mandate und Lago-Rechnungen werden nie
gelöscht oder umgeschrieben. Bei einem Payment-Rollback bleibt die
EUR-1.000-Grenze mindestens fail-closed; es gibt keinen SEPA-Fallback.
## Quellen
- `docs/CHANGE-REQUESTS.md` · CR-021
- `.planning/ticket-docs/BILL-11.md`
- `.planning/ticket-docs/BILL-14.md`
- `.planning/ticket-docs/BILL-19.md`
- `.planning/ticket-docs/BILL-20.md`
- `.planning/ticket-docs/BILL-21.md`
- https://docs.mollie.com/docs/recurring-payments
- https://docs.mollie.com/reference/mandates-api
- https://docs.hetzner.com/storage/object-storage/overview/
- https://www.hetzner.com/storage/object-storage/
## Dev-Nachzug
- Interim-UI wird gegen Desktop und Mobile visuell geprüft. Nach Davids
finalem Delta müssen ausschließlich Adapter/Visual-Baselines nachgezogen
werden; View-Model-, Payment- und Entitlement-Verträge bleiben stabil.
## Umsetzungs-Notiz
2026-08-02 · gestartet
- Explizite Produktfreigabe im Chat für freie Kreditkartenwahl auch unter
1.000 EUR, Teamgröße vor Tarif, live berechnete Preise und getrennte
Speicher-/E-Mail-Marketing-Upsells.
- `blocked-by` und `blocks` in Plane sowie den betroffenen Ticket-Docs in beide
Richtungen geprüft. Plane-Identität als `raffael@tool-ctrl.de` bestätigt;
`HIVEGRID-244` angelegt, Raffael zugewiesen und auf In Progress gesetzt.
- Neuer Worktree `HiveGrid-Cloud-feat-bill-22-guided-checkout` auf aktuellem
`origin/main`; EU-Provider-Guard leer, Typecheck und vollständige Baseline
mit 1.187 Testdateien / 8.278 Tests grün (60 bewusst übersprungen).
- Diagnose: `BILL-21` wählt für wiederkehrende Rechnungen über 1.000 EUR zwar
`creditcard`, der Mollie-Adapter lehnte für `sequenceType=recurring` jedoch
weiterhin jede Methode außer `directdebit` ab. Gemockte Worker-Tests hatten
diesen Integrationswiderspruch nicht erkannt. Der Nachzug ist Teil dieses
Tickets.
2026-08-02 · lokale Umsetzung und Verifikation
- Registrierung in Konto, Team und Tarif getrennt. Büro-/Baustellen-Nutzer
lassen sich per Slider, Zahleneingabe und Plus/Minus bedienen; die
serverseitige Empfehlung und alle Teampreise aktualisieren sich live.
- Aktivierung in Team, Tarif, Speicher, E-Mail und Zahlung geteilt. Speicher
und E-Mail-Marketing sind eigene überspringbare Upsells. Ein ausgewähltes
E-Mail-Paket wird erst nach bestätigter Basiszahlung in einen eigenen
Add-on-Checkout überführt.
- Mollie lässt bis einschließlich 1.000,00 EUR alle für den Betrag verfügbaren
Erstzahlarten inklusive Kreditkarte zu. Ab 1.000,01 EUR wird ausschließlich
Kreditkarte angefordert. Recurring Collections prüfen die passende
Mandatsfamilie und brechen ohne erforderliches Kartenmandat fail-closed ab.
- Commits: `90c4f4079`, `c1fa42867`, `b15d3b5f6`, `9242ab48c`,
`3f3aa7903`, `cbb0a071f`, `aee4fb301`, `2cd062114`.
- Vollständige Testsuite: 1.187 Testdateien und 8.293 Tests grün, 60 bewusst
übersprungen. Package-Tests, Coverage-Vertrag, Typecheck, Lint, i18n,
Billing-Boundary/-Catalog, Source-Health, Hot-Swap, A11y-Coverage und
Visual-Verifier grün. Component-Visualtests: 6/6 Desktop/Mobile grün.
- Bekannte globale Baseline-Altlast: `verify:a11y-baseline` meldet auf diesem
Branch unverändert 66 historische `autoFocus`-Treffer gegenüber 56 in der
Baseline. BILL-22 fügt keinen Treffer hinzu; A11y-Coverage und die neuen
interaktiven Flows sind grün. Dieser repo-weite Nachzug ist nicht Teil des
Tickets.
- 13 fertig gerenderte und visuell geprüfte Screens liegen unter
`/Users/raffaelsheikh/Desktop/HiveGrid-BILL-22-Checkout-Review-2026-08-02/`.
Live-Staging-Screens folgen nach dem Deploy.
- Hetzner-Recherche: 1 TB ist im Object-Storage-Grundpreis von 6,49 EUR/Monat
enthalten; zusätzlicher Speicher kostet 6,26 EUR/TB/Monat. Die aktuellen
HiveGrid-Aufpreise erzielen vor Grundpreis, Redundanz, Betrieb und Traffic
rund 93,0 % (100 GB), 89,2 % (500 GB), 87,2 % (1 TB) und 84,3 % (5 TB)
Rohmarge. Eine niedrigere Preisstaffel ist in `docs/pricing-draft.md`
vorgeschlagen, aber bewusst nicht ohne Produktentscheidung aktiviert.
2026-08-02 · Merge, Deploy und Live-Probes
- PR `#360` nach grüner Bundle-, Coverage- und 11/11-Haupt-CI normal gemergt;
BILL-22-Head `69f74183c`, Merge-Commit `a44a239e7`.
- Ein durch den unmittelbar vorausgehenden Parallel-Merge `#359` sichtbar
gewordener i18n-Paritätskonflikt wurde separat in PR `#362` behoben. Der
Hotfix lief lokal mit Typecheck, Lint, 8.320 Tests, i18n und Coverage grün
und wurde nach vollständiger PR-CI normal als `54dab6304` gemergt.
- Main-Runs `11881` (Bundle), `11882` (Coverage), `11883` (Images, Migration,
Coolify-Staging) und `11884` (Repository-Metriken) sind grün. Alle zwölf
Coolify-Ressourcen wurden mit dem immutable Merge-SHA ausgerollt; der
revisionsgebundene Portal-Domain-Controller-Healthcheck ist grün.
- Live auf `staging-app.hivegrid.de`: `/healthz`, `/readyz` und `/register`
antworten mit HTTP 200; Health und Readiness melden Revision `54dab6304`.
Die serverseitige Tarifberatung empfiehlt und berechnet für 1/0 Core mit
199 EUR, für 5/15 Swarm mit 499 EUR und für 10/20 Swarm inklusive Extras mit
789 EUR netto.
- Der ausschließlich mit Mollie TEST auszuführende interaktive
Signup-zu-Zahlung-UAT bleibt offen, weil in der ausführenden Sitzung keine
unterstützte Browser-Verbindung verfügbar war. Es wurde weder eine echte
Zahlung ausgelöst noch ein Browser-UAT vorgetäuscht.
**BILL-22: 8/9 DoD = ~89 % done. Offen: interaktiver Mollie-TEST-UAT
(extern durch fehlende Browser-Verbindung blockiert; 0 weitere selbst
machbare Implementierungspunkte).**
2026-08-02 · Abhängigkeitsschutz für `BILL-23`:
- Die getrennte Speicher-Upsell-Seite bleibt strukturell bestehen und zeigt
künftig den lizenzbasierten gemeinsamen Workspace-Pool sowie die fairen
`Cloud-Speicher Plus`-Preise aus derselben serverseitigen Vorschau.
- Team-, Tarif-, E-Mail- und Zahlartfluss sowie das offene Mollie-TEST-UAT
ändern sich nicht. `BILL-22` bleibt 8/9 DoD = ~89 % done.
@@ -0,0 +1,208 @@
# BILL-23 · Lizenzbasierter Workspace-Speicherpool und faire Add-on-Preise
| | |
| ----------------- | -------------------------------------------- |
| **Typ** | Produktentscheidung · Billing-/Storage-Recut |
| **Owner** | Raffael |
| **Phase** | Pilot-Härtung |
| **Cycle/Fenster** | gestartet 2026-08-02 |
| **Status** | Done |
| **Plane** | HIVEGRID-246 |
**🎨 design-nachzug: offen** (seit 2026-08-02) — der Pilot-Slice verwendet
vorhandene `~/ui`-Bausteine; ein finales Subframe-Delta bleibt ein getrackter
Nachzug gemäß AD-28.
## Abhängigkeiten & Parallelität
- **Blocked by:** `BILL-11` liefert den versionierten Katalog und Lago-Sync,
`BILL-17` den RLS-gebundenen Kapazitäts-/Usage-Vertrag und `BILL-22` die
getrennte Speicher-Upsell-Seite. Alle drei technischen Grundlagen sind Done.
- **Blocks:** `BILL-08` darf den Production-Katalog erst nach dem neuen
Katalog-/Staging-Proof freigeben; dessen Mollie-/Legal-Gates bleiben extern.
- **Abhängigkeitsschutz:** Technische Plan-, Add-on- und Provider-Codes bleiben
stabil. Checkout, Upload-Grenze, Usage-Tab, Lago-Rechnung und Mollie-Betrag
verwenden weiterhin dieselbe serverautoritative Katalogquelle.
## Was / Warum
Der bisherige Vertrag nennt pro Tarif einen pauschalen Workspace-Speicher und
gibt zusätzlichen Büro-/Baustellen-Nutzern unterschiedliche Kontingente. Das
ist schwer erklärbar, obwohl Projektdateien dem Workspace und nicht einer
Person gehören. Gleichzeitig liegen die Add-on-Preise bei 84 bis 93 Prozent
Rohmarge gegenüber den direkten Hetzner-Speicherkosten.
Der neue Vertrag kombiniert eine verständliche Nutzerlogik mit einem technisch
gemeinsamen Workspace-Pool:
| Tarif | Inklusiver gemeinsamer Pool | Wachstum je zusätzlichem bezahlten Nutzer |
| ------ | --------------------------: | ----------------------------------------: |
| Core | 100 GB | +10 GB |
| Swarm | 500 GB | +20 GB |
| Colony | 2 TB | +40 GB |
Büro- und Baustellen-Nutzer erweitern den Pool gleich. Es entstehen keine
persönlichen Speicher-Silos; Dateien bleiben bei Austritt eines Nutzers im
Projekt/Workspace. Der Pool kann über feste, vorhersehbare
`Cloud-Speicher Plus`-Pakete erweitert werden:
| Zusatzpool | Preis netto/Monat | direkte Hetzner-Speicherkosten | Rohmarge vor Egress |
| ---------- | ----------------: | -----------------------------: | ------------------: |
| +100 GB | 1,25 EUR | 0,626 EUR | 49,9 % |
| +500 GB | 6,25 EUR | 3,13 EUR | 49,9 % |
| +1 TB | 12,50 EUR | 6,26 EUR | 49,9 % |
| +5 TB | 62,50 EUR | 31,30 EUR | 49,9 % |
Der Preisdeckel verwendet bewusst nur die direkten zusätzlichen
Speicherkosten von 6,26 EUR/TB/Monat als COGS. Ausgehender Traffic senkt die
tatsächliche Rohmarge weiter. Es gibt keine überraschende Einzel-GB- oder
Overage-Abrechnung.
## Nicht im Scope
- Keine harten Speicher-Silos oder Eigentumswechsel pro Nutzer.
- Kein verbrauchsabhängiges GB-Metering, keine automatische Overage-Rechnung
und keine rückwirkende Rechnungsänderung.
- Keine Änderung an Basisplan-, Sitz-, E-Mail-Marketing- oder Portalpreisen.
- Keine Umbenennung technischer Codes und keine Production-Provider-Mutation
vor den Gates aus `BILL-08`.
- Keine Archiv-/Cold-Storage-Funktion oder neue Storage-Infrastruktur.
## Definition of Done
- [x] Der kanonische Katalog modelliert 100/500/2.000 GB gemeinsamen
Basisspeicher sowie 10/20/40 GB je zusätzlichem Nutzer; Büro und
Baustelle sind für Speicher gleichwertig.
- [x] Die vier stabilen Speicher-Add-on-Codes kosten 1,25/6,25/12,50/62,50 EUR
netto pro Monat; automatisierte Kalkulation beweist maximal 50 Prozent
Rohmarge gegen 6,26 EUR/TB direkte Speicherkosten.
- [x] Kapazitätsresolver, Upload-Reservierung und Usage-Projektion verwenden
exakt denselben gemeinsamen Pool und bleiben RLS-/fail-closed-sicher.
- [x] Registrierung und Tarifkarten erklären Inklusivpool plus Wachstum je
Zusatznutzer; die Aktivierung zeigt den serverseitig berechneten
Gesamtpool vor dem optionalen `Cloud-Speicher Plus`-Upsell.
- [x] Billing-Verwaltung, Checkout-Vorschau, Lago-Managed-Plan und Rechnung
verwenden die neuen Preise ohne zweite clientseitige Preisquelle;
technische Codes und bestehende Providerreferenzen bleiben stabil.
- [x] Alle neuen UI-Texte sind in den sechs Katalogsprachen vorhanden;
Component-/VM-/Service-/Katalog-/Capacity-/Sync-Tests decken den Vertrag.
- [x] CR-023, Preisentwurf und die abhängigen Ticket-Docs dokumentieren
Produktentscheidung, Auswirkung und Rollback.
- [x] Typecheck, Lint, vollständige Testsuite sowie Billing-, i18n-, Source-,
Hot-Swap-, Visual- und relevante Security-Verifier sind grün.
- [x] PR-CI, normaler Merge, Staging-Katalog-Sync, Deploy und Live-UAT sind
grün; kein Production-Provider wird verändert.
**BILL-23: 9/9 DoD = 100 % done. Offen: nichts.**
2026-08-03 · Abhängigkeitsschutz für `BILL-24`
- `BILL-24` ersetzt ausschließlich die sichtbaren Speicher-Add-on-Stufen und
ihre Neukaufpreise. Gemeinsamer Workspace-Pool, Wachstum je Zusatznutzer,
technische Codes sowie Bestandsauflösung aus `BILL-23` bleiben unverändert.
- Das bisherige 100-GB-Paket bleibt für aktive Verträge auflösbar, ist aber
kein neues Self-Service-Angebot mehr. `BILL-23` bleibt 9/9 DoD = 100 % done.
## Technische Bausteine
- `packages/entitlements/src/seat-packages.ts`
- `packages/entitlements/src/commercial-catalog.ts`
- `packages/entitlements/src/storage-capacity.ts`
- `packages/view-models/src/billing/self-service-subscription.vm.ts`
- `apps/web/app/services/billing/{registration-plan-selection,self-service-subscription,storage-capacity}.server.ts`
- `apps/web/app/modules/users/components/RegistrationPlanStep.tsx`
- `apps/web/app/components/screens/billing/SelfServiceSubscriptionPage.tsx`
- kontrollierter `scripts/billing-catalog`-Sync und bestehende Usage-/Upload-Gates
## Rollback
- Katalog und UI können gemeinsam auf Version `2026-08-02.1` zurückgesetzt
werden. Bereits ausgestellte Rechnungen, Zahlungen und historische
Provider-Managed-Pläne werden nicht gelöscht oder umgeschrieben.
- Technische Plan-/Add-on-Codes bleiben identisch. Ein Rollback verändert nur
neue Preisvorschauen und zukünftige Managed-Pläne; aktive Providerobjekte
werden ausschließlich über den kontrollierten Katalog-Sync behandelt.
- Die Upload-Grenze bleibt zu jedem Zeitpunkt aus genau einer versionierten
Kapazitätsfunktion abgeleitet und fällt bei unbekanntem Vertrag geschlossen.
## Quellen
- `docs/CHANGE-REQUESTS.md` · CR-023
- `.planning/ticket-docs/BILL-11.md`
- `.planning/ticket-docs/BILL-17.md`
- `.planning/ticket-docs/BILL-22.md`
- https://support.google.com/a/answer/9214707
- https://learn.microsoft.com/en-us/office365/servicedescriptions/sharepoint-online-service-description/sharepoint-online-limits
- https://www.hetzner.com/storage/object-storage/
## Umsetzungs-Notiz
2026-08-02 · gestartet
- Explizite Produktentscheidung im Chat: Speicherabrechnung vollständig neu
denken, pro Tarif verständlich mit Nutzern wachsen lassen, in den vorhandenen
geführten Billing-Flow integrieren und Add-on-Rohmarge auf maximal 50 Prozent
begrenzen.
- Plane-Identität als `raffael@tool-ctrl.de` bestätigt; `HIVEGRID-246`
angelegt, Raffael zugewiesen und auf In Progress gesetzt.
- Neuer Worktree auf `origin/main` (`eab504cff`). EU-Provider-Guard leer;
Typecheck und vollständige Baseline mit 1.193 Testdateien / 8.320 Tests grün
(60 bewusst übersprungen).
- Marktvertrag geprüft: Google Workspace poolt pro Endnutzerlizenz gewährten
Speicher organisationsweit; Microsoft 365 kombiniert einen gemeinsamen
Organisationssockel mit zusätzlichem Speicher je Lizenz. HiveGrid übernimmt
dieses verständliche Pool-Prinzip, nicht deren absolute Kontingentgrößen.
2026-08-02 · lokale Umsetzung abgeschlossen
- `fd812a1de` dokumentiert `CR-023`, Preis-/Margenmodell, Abhängigkeiten und
Rollback. Der Speicherkatalog verwendet stabile technische Codes.
- `2730cc308` macht den serverautoritativen Pool zur einzigen Quelle für
Registrierung, Vorschau, Checkout, Usage-/Upload-Kapazität und Lago-Sync.
Automatisierte Tests beweisen 100/500/2.000 GB Basis, 10/20/40 GB je
Zusatzlizenz sowie 4.992 Basispunkte Rohmarge für alle vier Add-ons.
- `7cd38a025` erklärt den gemeinsamen Pool und dessen Lizenzwachstum in
Registrierung, Aktivierung und Billing-Verwaltung in allen sechs
Katalogsprachen. `90be6c0d5` pinnt die Visual-Fixture auf den VM-Vertrag;
`c01d52332` aktualisiert ausschließlich die beabsichtigten Plan- und
Speicher-Screens.
- Typecheck, Lint, CI-Baseline, Billing-Katalog/-Boundary, i18n, Source-Health,
Hot-Swap und Chromium-Component-Test sind grün. Die vollständige Suite hat
1.194 Testdateien und 8.323 Tests bestanden; 60 Live-/Integrationstests
blieben wie vorgesehen umgebungsbedingt übersprungen.
- Die sieben geprüften Journey-Screens liegen zusätzlich unter
`~/Desktop/HiveGrid-BILL-23-Speicher-Review-2026-08-02/`.
**BILL-23: 8/9 DoD = ~89 % done. Offen: PR-CI, normaler Merge,
Staging-Katalog-Sync, Deploy und Live-UAT; 0 weitere lokale
Implementierungspunkte.**
2026-08-02 · Staging-Proof und Abschluss
- Pull Request `#365` lief mit den CI-Runs `11895`, `11896` und `11897`
vollständig grün und wurde normal gemergt. Merge-Revision:
`5b5c961105eb9c599089321d1bffc7624c16f728`; der Feature-Head
`7e4983f608e4401874067be5d7854aa9294bcf21` ist nachweislich Vorfahr des
Merge-Commits.
- Der kontrollierte Lago-Staging-Sync hat Katalogversion `2026-08-02.2` mit
Digest
`492992bcefd923d35c94f84b564372b7cfd89c08a9ecb9439f25d9b6becc5977`
angewendet. Der anschließende Verify-Lauf meldete alle 16 Steuer-/Planobjekte
als No-op. Redaktierter Snapshot:
`tmp/billing-catalog-snapshots/staging-2026-08-02T21-20-18-902Z.json`.
Der Production-Provider blieb unangetastet.
- Die vier Main-Runs `11898`, `11899`, `11900` und `11901` sind grün. Der
Deploy-Job `50139` schloss erfolgreich ab. `/healthz`, `/readyz` und
`/register` antworteten live mit HTTP 200; Health und Readiness lieferten
exakt Revision `5b5c961105eb9c599089321d1bffc7624c16f728`.
- Die Live-Planberatung empfahl auf Staging für 1/0 Nutzer Core, für 5/15 und
10/20 Nutzer Swarm sowie für 20/50 Nutzer Colony. Die Antworten enthielten
die neuen serverautoritativen Speicherwerte 100/500/2.000 GB und
10/20/40 GB je Zusatzlizenz. Der visuelle Journey-Proof bleibt unter
`~/Desktop/HiveGrid-BILL-23-Speicher-Review-2026-08-02/`.
- Ein erneuter interaktiver Mollie-Checkout war für diesen reinen
Speichervertrag nicht erforderlich: Zahlungsmethoden, Mandat und
Provider-Codes wurden nicht geändert; deren echte Testzahlungs-UAT bleibt im
eigenen Checkout-Ticket `BILL-22` getrackt.
**BILL-23: 9/9 DoD = 100 % done. Offen: nichts.**
@@ -0,0 +1,177 @@
# BILL-24 · Wertige ,99-Speicherpakete mit Legacy-Kompatibilität
| | |
| ----------------- | --------------------------------------------------- |
| **Typ** | Produktentscheidung · Billing-/Storage-Preisnachzug |
| **Owner** | Raffael |
| **Phase** | Pilot-Härtung |
| **Cycle/Fenster** | gestartet 2026-08-03 |
| **Status** | Done · Staging und Live-UAT verifiziert |
| **Plane** | HIVEGRID-247 |
**🎨 design-nachzug: offen** (seit 2026-08-03) — der Pilot-Slice verwendet
die bestehende Billing-UI aus `~/ui`; ein finales Subframe-Delta bleibt ein
getrackter Nachzug gemäß AD-28.
## Abhängigkeiten & Parallelität
- **Blocked by:** `BILL-23` liefert den gemeinsamen Workspace-Pool, die
stabilen technischen Add-on-Codes und den versionierten Lago-Vertrag.
- **Blocks:** `BILL-08` darf den Production-Katalog erst nach dem neuen
Katalog-/Staging-Proof freigeben; dessen Mollie-/Legal-Gates bleiben extern.
- **Abhängigkeitsschutz:** Basisplan, Inklusivspeicher, Speicherwachstum je
Zusatznutzer, technische Codes und Bestandsverträge bleiben unverändert.
Nur das neu buchbare Add-on-Angebot und dessen Preise werden nachgezogen.
## Was / Warum
Die in `BILL-23` eingeführten fairen Speicherpreise erfüllen die
50-Prozent-Margengrenze, wirken mit `1,25`, `6,25`, `12,50` und `62,50` EUR
aber wie interne Kalkulationswerte. Besonders `1,25 EUR` für 100 GB setzt
einen zu billigen Preisanker und erzeugt unnötig viele Kleinstpakete.
Neu buchbar sind deshalb drei klare, wertigere Stufen:
| Zusatzpool | Preis netto/Monat | direkte Hetzner-Kosten | Rohmarge vor Egress |
| ---------- | ----------------: | ---------------------: | ------------------: |
| +500 GB | 4,99 EUR | 3,13 EUR | 37,3 % |
| +1 TB | 9,99 EUR | 6,26 EUR | 37,3 % |
| +5 TB | 49,99 EUR | 31,30 EUR | 37,4 % |
Das bisherige `storage_100gb` bleibt mit seinem historischen Preis technisch
auflösbar, damit aktive Verträge, Rechnungen und Kapazitätsberechnungen nicht
brechen. Es wird im Self-Service weder angezeigt noch für einen neuen
Checkout akzeptiert.
## Nicht im Scope
- Keine Änderung an Basisplan-, Sitz-, E-Mail-Marketing- oder Portalpreisen.
- Keine Änderung am gemeinsamen Pool oder am Speicherwachstum je Nutzer.
- Keine Umbenennung oder Löschung technischer Codes und keine rückwirkende
Preisänderung bestehender Verträge.
- Keine Production-Provider-Mutation vor den Gates aus `BILL-08`.
- Kein verbrauchsabhängiges GB-Metering, Overage-Billing oder neue
Storage-Infrastruktur.
## Definition of Done
- [x] Im Self-Service sind ausschließlich 500 GB / 1 TB / 5 TB zu
4,99 / 9,99 / 49,99 EUR netto pro Monat neu buchbar.
- [x] Alle sichtbaren Speicherpreise enden auf `,99`; automatisierte
Kalkulation belegt weniger als 50 Prozent direkte Rohmarge.
- [x] `storage_100gb` ist unsichtbar und wird bei manipulierten Neuabschluss-
oder Checkout-Requests serverseitig fail-closed abgewiesen.
- [x] Bestehende `storage_100gb`-Verträge bleiben für Preis-, Rechnungs- und
Kapazitätsauflösung kompatibel.
- [x] Self-Service-VM, Checkout und Lago-Sync beziehen Preis und Kaufstatus
aus genau einem versionierten Katalog.
- [x] Typecheck, Lint, vollständige Testsuite sowie Billing-, i18n-, Source-,
Hot-Swap- und Visual-Verifier sind grün; Review-Screenshots sind geprüft.
- [x] PR-CI, normaler Merge, Staging-Katalog-Sync, Deploy und Live-UAT sind
grün; kein Production-Provider wird verändert.
**BILL-24: 7/7 DoD = 100 % done. Offen: 0 Punkte.**
2026-08-03 · Abhängigkeitsschutz für `BILL-25`
- `BILL-25` ersetzt ausschließlich die Neukaufpreise durch eine konservative
5×-Egress-Kalkulation und ergänzt beobachtende Download-Telemetrie. Technische
Codes, Kaufbarkeit, gemeinsamer Pool, Bestandsauflösung und historische
Rechnungen aus `BILL-24` bleiben unverändert.
- `BILL-24` bleibt 7/7 DoD = 100 % done. Die neue Katalogversion und ihr
Staging-/Production-Proof werden ausschließlich in `BILL-25` getrackt.
## Technische Bausteine
- `packages/entitlements/src/commercial-catalog.ts`
- `apps/web/app/services/billing/self-service-subscription.server.ts`
- `apps/web/app/services/billing/self-service-checkout.server.ts`
- `packages/view-models/src/billing/self-service-subscription.vm.ts`
- kontrollierter `scripts/billing-catalog`-Sync
- bestehende Billing-Verwaltung und Speicher-Upsell-Seite
## Rollback
- Katalog und Self-Service können gemeinsam auf Version `2026-08-02.2`
zurückgesetzt werden. Historische Rechnungen und Zahlungen werden nicht
gelöscht oder umgeschrieben.
- Technische Add-on-Codes bleiben identisch. Ein Rollback macht die alten
Stufen nur wieder für neue Vorschauen sichtbar; Bestandsverträge bleiben in
beiden Richtungen auflösbar.
- Staging wird ausschließlich über den kontrollierten Katalog-Sync geändert;
Production bleibt bis zur separaten Freigabe aus `BILL-08` unangetastet.
## Quellen
- `docs/CHANGE-REQUESTS.md` · CR-024
- `.planning/ticket-docs/BILL-23.md`
- `.planning/ticket-docs/BILL-08.md`
- `docs/pricing-draft.md`
## Umsetzungs-Notiz
2026-08-03 · gestartet
- Explizite Produktentscheidung im Chat: sichtbare Speicherpreise sollen
konsistent auf `,99` enden, wertiger wirken und nicht mit `1,99 EUR` oder
einem noch kleineren Preisanker beginnen.
- Entscheidung innerhalb der bestehenden Margengrenze: 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. Die direkte
Rohmarge liegt bei rund 37 Prozent vor Egress und damit klar unter 50 Prozent.
- Plane-Identität als `raffael@tool-ctrl.de` bestätigt; `HIVEGRID-247`
angelegt, Raffael zugewiesen und auf In Progress gesetzt.
- Neuer Worktree auf `origin/main` (`1c8d8ad5e`). Workspace-Shape und
EU-Provider-Guard sind sauber; Typecheck und vollständige Baseline mit 1.194
Testdateien / 8.323 Tests grün (60 bewusst übersprungen).
2026-08-03 · lokale Umsetzung abgeschlossen
- Katalogversion `2026-08-03.1` trennt Bestandsauflösung und Neukauf: Alle vier
stabilen Providercodes bleiben auflösbar; neu kaufbar sind ausschließlich
`storage_500gb`, `storage_1tb` und `storage_5tb` zu 499/999/4.999 Cent.
- Self-Service veröffentlicht nur die drei kaufbaren Pakete. Die serverseitige
Vorschau lehnt unbekannte oder historische Pakete für neue Verträge ab, lässt
ein bereits aktives `storage_100gb` aber bei Plan-/Platzänderungen bestehen.
Checkout und Kapazitätsresolver verwenden dieselbe validierte Auswahl.
- Der Lago-Manifest-Sync führt den Kaufstatus als Metadatum mit. Der
Bestandsplan bleibt für bestehende Rechnungen erhalten; Production wurde
nicht verändert.
- Der visuelle Review fand zusätzlich widersprüchliche alte Tariftexte. Swarm
nennt jetzt in allen sechs Katalogsprachen durchgehend 500 GB und Colony 2
TB; Quellhashes und Browser-Baselines wurden kontrolliert nachgezogen.
- Typecheck, Lint, Billing-Boundary, 1.194 Core-Testdateien mit 8.324 grünen
Tests (60 bewusst übersprungen), 13 Chromium-Komponententests, i18n,
Source-Health, Hot-Swap, UI-Visual und CI-Baseline sind grün.
- Die drei selbst visuell geprüften Screens liegen unter
`~/Desktop/HiveGrid-BILL-24-Speicherpreise-Review-2026-08-03/`.
**BILL-24: 6/7 DoD = ~86 % done. Offen: PR-CI, normaler Merge,
Staging-Katalog-Sync, Deploy und Live-UAT; 0 weitere lokale
Implementierungspunkte.**
2026-08-03 · abgeschlossen
- Die drei atomaren Commits `5f25f258f`, `b2d970c60` und `6aac9c2d4` wurden
über PR #367 normal gemergt. Merge-Commit `5fba54e72`; die Feature-Commit-
Ancestry ist auf `main` erhalten.
- Alle 13 PR-Checks waren grün. Der Main-Lauf war mit 4/4 Checks grün; der
16:38 Minuten lange Stage-/Promote-Lauf hat Staging und die vorgesehenen
Production-Images ausgerollt und alle Web-/Service-Healthchecks bestanden.
- Web und API meldeten auf Staging jeweils `healthz` und `readyz` mit HTTP 200
und exakt Revision `5fba54e72c8b351a37c158ce5be27aba65db1f4d`.
- Der kontrollierte Staging-Lago-Plan wurde auf Version `2026-08-03.1` mit
Digest `e400ac119050602009c7a27bd51e4d17aa92e003de3fcd4d9852b09a8cd934c9`
angewandt. Die anschließende Verifikation lieferte alle 16 Ressourcen als
No-op. Redaktierter Snapshot:
`tmp/billing-catalog-snapshots/staging-2026-08-02T23-35-27-833Z.json`.
- Die echte Staging-Registrierung wurde ohne Versand, Account-Anlage oder
Zahlung bis zur Tarifempfehlung durchlaufen. Für 10 Büro- und 20
Baustellen-Nutzer wurde genau einmal Swarm empfohlen; Core, Swarm und Colony
zeigten konsistent 100 GB, 500 GB und 2.000 GB Inklusivspeicher.
- Zwei zusätzliche Live-Screenshots wurden visuell geprüft und zusammen mit
den drei Implementierungs-Screens unter
`~/Desktop/HiveGrid-BILL-24-Speicherpreise-Review-2026-08-03/` abgelegt.
- Der Production-Lago-Provider wurde weder geplant noch angewandt oder
verändert. Dessen Freigabe bleibt bei `BILL-08`.
**BILL-24: 7/7 DoD = 100 % done. Offen: 0 Punkte.**
@@ -0,0 +1,227 @@
# BILL-25 · Egress-resiliente Speicherpreise und Traffic-Transparenz
| | |
| ----------------- | ------------------------------------------------------ |
| **Typ** | Produktentscheidung · Billing-/Storage-Launch-Härtung |
| **Owner** | Raffael |
| **Phase** | Pilot-Härtung |
| **Cycle/Fenster** | gestartet 2026-08-03 |
| **Status** | In Arbeit |
| **Plane** | HIVEGRID-248 |
## Abhängigkeiten & Parallelität
- **Blocked by:** `BILL-24` liefert die drei neu kaufbaren Speicherstufen,
stabile technische Codes und die Trennung zwischen Neu- und Bestandsvertrag.
- **Blocks:** `BILL-08` darf den Production-Katalog erst nach grünem
Staging-Katalog-, Checkout-, Invoice- und Journey-Proof nachziehen.
- **Abhängigkeitsschutz:** Basispläne, Inklusivspeicher, Wachstum je
Zusatznutzer, Add-on-Codes, historische Preise und bereits ausgestellte
Rechnungen bleiben unverändert. Nur künftige Neukäufe erhalten die neue
Katalogversion.
## Was / Warum
Die Preise aus `BILL-24` decken direkte Speicherkosten, aber nur ungefähr 3,7
vollständige externe Auslieferungen des gebuchten Zusatzspeichers, bevor die
Deckung negativ wird. Für den Piloten soll der Katalog konservativ fünf
vollständige Auslieferungen pro Monat tragen, ohne tatsächliche Nutzung
vorzutäuschen oder Kunden mit variablen Traffic-Nachberechnungen zu überraschen.
Der neue Vertrag verwendet weiterhin drei feste, monatliche Zusatzpools:
| Zusatzpool | Preis netto | Speicher-COGS | 4× Egress-COGS | Marge bei 4× | 5× Egress-COGS | Marge bei 5× |
| ---------- | ----------: | -------------: | --------------: | ------------: | --------------: | ------------: |
| +500 GB | 6,99 EUR | 3,36 EUR | 2,15 EUR | 21,2 % | 2,68 EUR | 13,5 % |
| +1 TB | 12,99 EUR | 6,72 EUR | 4,29 EUR | 15,2 % | 5,37 EUR | 6,9 % |
| +5 TB | 60,99 EUR | 33,61 EUR | 21,47 EUR | 9,7 % | 26,84 EUR | 0,9 % |
Die Kalkulation verwendet 6,26 EUR/TB-Monat zusätzliche Speicherkosten und
1,00 EUR/TB externen Mehrtraffic. HiveGrid gewährt Quota in Einheiten von
`1024^3` Bytes, Hetzner rechnet dagegen dezimale TB; der Nachweis verwendet
deshalb die tatsächlich gewährten Bytes statt einer vereinfachten
GB-durch-1000-Rechnung. Hetzners monatlich ungefähr 1 TB großer,
accountweiter Egress-Freibetrag ist ein gemeinsamer Plattformpuffer und wird
keinem Workspace oder Paket versprochen. Ohne Egress liegt die direkte
Rohmarge bei 51,9 / 48,3 / 44,9 Prozent. Die kleinste Stufe überschreitet die
angestrebte 50-Prozent-Marke minimal: 5,99 EUR wäre unter realen Binäreinheiten
bei 5× Egress negativ, 6,99 EUR ist die kleinste freigegebene `,99`-Stufe.
Hetzners Abrechnungsminimum von 64 kB je gespeichertem Objekt ist kein weiterer
pauschaler Egress-Zyklus und rechtfertigt ohne reale Objektverteilung keine
zusätzliche Preiserhöhung. Es wird im Pilot separat als Differenz zwischen
logischen HiveGrid-Bytes und providerseitig abgerechnetem Speicher überwacht;
bei auffälliger Abweichung werden Objektmix, unvollständige Multipart-Uploads,
Versionen und fremde Account-Buckets geprüft.
Traffic-Transparenz trennt drei Werte sauber:
1. **Provider-Istkosten:** accountweiter, extern abgerechneter Hetzner-Egress.
2. **Autorisierter Traffic:** Anzahl und Objektgröße der von HiveGrid
freigegebenen Downloads, aggregiert nach stabiler Produktoberfläche ohne
Tenant-/Datei-Labels in Prometheus.
3. **Workspace-Näherung:** nur für Support-/Kostenprüfung; keine automatische
Rechnung und keine Behauptung, ein ausgestellter Signed Link sei tatsächlich
vollständig geladen worden.
Der komplette Registrierungs-, Verifikations-, Aktivierungs-, Mollie-TEST-,
Welcome-, Invoice- und Add-on-Pfad wird gegen Staging neu geprüft. Nur konkret
reproduzierte Fehler innerhalb dieser Journey werden in diesem Ticket behoben;
weitergehende Features bleiben eigene Change-Requests.
## Nicht im Scope
- Kein Traffic-Overage-Billing, keine nachträgliche Einzel-GB-Rechnung und kein
„unlimited traffic“-Versprechen.
- Kein Tenant als Prometheus-Label, keine Dateinamen/Objektschlüssel in Logs
und keine Speicherung von Signed URLs.
- Kein Proxy aller Downloads durch den Webprozess und keine neue CDN-, Server-
oder Bucket-Infrastruktur in diesem Ticket.
- Keine eigenen Zahlungsfelder, kein Mollie-Iframe und keine echte
Production-Zahlung vor den zwei externen Gates aus `BILL-08`.
- Keine Änderung an Basisplan-, Sitz-, E-Mail-Marketing- oder Portalpreisen.
## Definition of Done
- [x] Neu buchbare Speicherpakete kosten 6,99 / 12,99 / 60,99 EUR netto pro
Monat; stabile Codes und historische Verträge bleiben auflösbar.
- [x] Automatisierte Kalkulation verwendet die tatsächlich gewährten
Binärbytes und beweist für jede kaufbare Stufe positive Deckung nach fünf
vollständig kostenpflichtigen externen Auslieferungen der Paketkapazität.
- [x] Autorisierte Downloadanzahl und bekannte Objektbytes sind auf den
zentralen Auslieferungspfaden niedrig-kardinal, secretsicher und
ausfallsicher messbar; Signed-URL- und Provider-Blindspots sind im
Betriebsvertrag ausdrücklich benannt.
- [ ] Registrierung, Verifikation, Aktivierung, Welcome-Setup, Billing-Hub,
Rechnungszugriff und Add-on-Käufe wurden UX-, Security- und
Zustands-seitig geprüft; reproduzierte Launch-Blocker sind mit Tests
behoben oder als externer Blocker dokumentiert.
- [x] Typecheck, Lint, vollständige Testsuite sowie Billing-, Source-, i18n-,
Security-, ticketbezogene A11y-, Hot-Swap- und Visual-Verifier sind
grün; atomare Commits und geprüfte Screenshots liegen vor. Der gegenüber
`main` unveränderte globale `no-autofocus`-Baseline-Drift ist als
bestehender Repository-Nachzug ausgewiesen und nicht still hochgesetzt.
- [ ] PR-CI, normaler Merge, kontrollierter Staging-Katalog-Sync, Deploy und
ein ausschließlich mit Mollie TEST ausgeführter End-to-End-UAT sind grün.
- [ ] Production erhält erst danach exakt dieselbe geprüfte Katalogversion und
Invoice-Konfiguration; Provider-Side-Effects und echte Zahlungen bleiben
bis `BILL-08` fail-closed.
**BILL-25: 4/7 DoD = ~57 % done. Offen: 3 Punkte; davon Production-Sync
zusätzlich durch die externen `BILL-08`-Gates begrenzt.**
## Technische Bausteine
- `packages/entitlements/src/commercial-catalog.ts`
- `packages/metrics` und die bestehenden service-scoped Registries
- autorisierte Download-Routen und `mediaSigning.server.ts`
- `scripts/billing-catalog`
- Registrierungs-, Welcome-, Billing-, Invoice- und Add-on-Flows aus
`BILL-14`, `BILL-19`, `BILL-20` und `BILL-22`
- `docs/ops/lago-staging.md`, `docs/ops/lago-production-prep.md` und ein
redaktierter Storage-Traffic-Betriebsvertrag
## Rollback
- Katalog und UI können gemeinsam auf Version `2026-08-03.1` zurückgesetzt
werden. Bereits ausgestellte Rechnungen, Zahlungen und historische
Providerobjekte werden nie gelöscht oder umgeschrieben.
- Die neuen Metriken sind rein beobachtend. Ihr Ausfall darf keinen Download
blockieren; ein Rollback entfernt nur die Beobachtung, nicht Auth-, RLS-,
Scan- oder Signed-URL-Gates.
- Production wird ausschließlich nach erfolgreichem Staging-Proof und über den
kontrollierten idempotenten Katalog-Sync verändert. Der Zahlungs-Side-Effect-
Gate bleibt unverändert geschlossen.
## Quellen
- `docs/CHANGE-REQUESTS.md` · CR-025
- `.planning/ticket-docs/BILL-08.md`
- `.planning/ticket-docs/BILL-22.md`
- `.planning/ticket-docs/BILL-24.md`
- https://www.hetzner.com/storage/object-storage/
- https://docs.hetzner.com/storage/object-storage/overview/
## Umsetzungs-Notiz
2026-08-03 · gestartet
- Explizite Produktfreigabe im Chat: Preise nur so weit anheben, dass vier bis
fünf vollständige externe Auslieferungen wirtschaftlich enthalten sind;
Storage-Traffic sauber beobachtbar machen und den gesamten Billing-/Signup-
Pfad erneut gegen Staging prüfen.
- Korrektur nach Cross-Layer-Audit: HiveGrid-Quota nutzt `1024^3` Bytes pro GB,
Hetzner rechnet dezimale TB. Die zunächst vereinfachte Kalkulation war damit
bei 5× Egress leicht negativ. Der kleinste nötige `,99`-Nachzug ist 500 GB
für 6,99 EUR, 1 TB für 12,99 EUR und 5 TB für 60,99 EUR netto pro Monat. Bei
vollständig kostenpflichtigem 5×-Egress verbleiben 0,94 / 0,90 / 0,54 EUR
positive Deckung.
- Plane-Identität als `raffael@tool-ctrl.de` bestätigt; `HIVEGRID-248`
angelegt, Raffael zugewiesen und auf In Progress gesetzt.
- Isolierter Worktree auf `origin/main` (`b1f14d63e`). Workspace-Shape und
EU-Provider-Guard sind sauber; Typecheck und vollständige Baseline mit 1.194
Testdateien / 8.324 Tests grün (60 bewusst übersprungen).
- Katalogversion `2026-08-03.3` ist implementiert. Automatisierte Tests pinnen
Preis, unveränderte Codes, Bestandsauflösung, Rohmargen-Obergrenze und
positive Deckung nach fünf vollen externen Auslieferungen.
- Niedrig-kardinale Prometheus-Zähler erfassen autorisierte Downloads und nur
serverseitig bekannte Objektbytes auf Core-, Vorschau-, Thumbnail- und
Portalpfaden. Der Betriebsvertrag dokumentiert ausdrücklich: Das ist keine
Provider-Egress-Messung; Hetzner-Istkosten werden accountweit manuell
abgeglichen und führen nicht automatisch zu Kundenabrechnungen.
- Das 64-kB-Abrechnungsminimum pro Hetzner-Objekt ist als eigener
Speicherkosten-Blindspot aufgenommen. Es verändert die freigegebenen Preise
ohne belastbare Objektverteilung nicht, wird im Pilot aber gegen die logischen
HiveGrid-Bytes abgeglichen.
- Journey-Härtung in atomaren Commits: Passwortregeln werden vor Submit
validiert; die Billing-Präferenz wird atomar im Tenant-Bootstrap gebunden;
die Aktivierung berechnet Tarifempfehlung und Preise serverseitig live neu;
fehlgeschlagene Checkout-Aktionen entsperren die UI; Mollie-Zustände
`open`/`pending`/`authorized` bleiben in Verarbeitung, während
`cancelled`/`failed`/`expired` statt einer nutzlosen Status-Neuprüfung einen
frischen Checkout starten; nur `paid` aktiviert Entitlements. Invoice-Listen
paginieren vollständig und prüfen Downloads
unabhängig von der ersten Seite. Welcome- und Registrierungstexte
versprechen weder Direkt-Checkout noch Freischaltung vor bestätigter
Zahlung; der Dashboard-Einstieg bleibt eine bewusste Aktion.
- Read-only Staging-Audit vor Deploy: Katalog-Diff enthält exakt 16 erwartete
Updates und keine Creates/Deletes; Invoice-Entity ist eindeutig und auf
EUR/de, 14 Tage, Europe/Berlin, Per-Customer-Nummerierung sowie vorhandene
Rechts-/Steuer-/Absenderdaten konfiguriert. Ein finalisiertes Testdokument
war als PDF abrufbar. Mollie verwendet ausschließlich TEST, aber das Profil
ist providerseitig `unverified`; deshalb bietet Mollie derzeit nur iDEAL und
keine Karte/Recurring-Methode an. Das bleibt ein externer `BILL-08`-Blocker.
- Read-only Registrierungs-Baseline gegen Staging grün: Account-, Team-,
Swarm-Empfehlungs-, Core-Override- und Zurück-Navigation-Screenshots liegen
vollständig geladen und visuell geprüft unter
`~/Desktop/HiveGrid-BILL-25-Billing-Journey-2026-08-03/00-staging-before-deploy`.
- Provider- und Nebenläufigkeits-Härtung aus dem finalen Cross-Layer-Audit:
Basis-, E-Mail- und Portal-Checkouts werden tenantweit serialisiert und
berücksichtigen bereits reservierte Erwerbungen bei der kombinierten
Zahlungsmethoden-Policy. Wiederholte Tabs teilen ihre persistierte
Checkout-Identität. Preis- oder Provider-Drift bricht fail-closed ab.
Kündigungen sind nur noch für aktive wiederkehrende Add-ons mit exakt
gebundener Lago-Subscription möglich; lokale Entitlements werden nie vor
bestätigter Provider-Kündigung entfernt.
- Quota-Härtung deckt neben Browser-Uploads auch KWP, öffentliche Formulare,
E-Mail-Anhänge, Plantafel-Annahmen und Signatur-PDFs ab. Reservierungen
erfolgen zentral pro Tenant. Schlägt das Löschen eines hochgeladenen
Objekts fehl, bleibt die DB-Zeile quota-wirksam, statt das noch vorhandene
Objekt unsichtbar aus der Abrechnung zu entfernen.
- Lokaler Pre-Push-Proof nach allen Änderungen: `pnpm typecheck`, `pnpm lint`
und `pnpm test` grün mit 1.202 Testdateien / 8.508 Tests (60 bewusst
übersprungen). Zusätzlich grün: Billing-/Storage-Boundaries,
Katalogverträge, i18n, Source-Health, CI-Baseline, Onboarding-Flow,
Staging-UAT-Readiness, Hot-Swap, statische Visual-Baseline, 45
Accessibility-Komponententests, Prisma-Validation, Migration-Parität und
alle acht Live-RLS-Phasen einschließlich Portal und Tenant-Bootstrap.
`verify:a11y-baseline` meldet auf Branch und `main` denselben bestehenden
Stand von 70 `no-autofocus`-Fundstellen bei einer veralteten Baseline von
56; diese Branch erhöht die Fundstellenzahl nicht und weitet die Baseline
nicht auf.
- Vor dem Push liegen 64 fachlich getrennte Commits vor. Der EU-Provider-Guard
ist leer; Secrets- und Pre-Commit-Gates sind grün.
**BILL-25: 4/7 DoD = ~57 % done. Offen: vollständiger Post-Deploy-UAT,
PR/CI/Merge/Deploy/Staging-Sync und der durch `BILL-08` gegatete
Production-Abgleich.**
@@ -6,7 +6,7 @@
| **Owner** | Raffael |
| **Phase** | Billing-Recut nach AD-27 |
| **Cycle/Fenster** | nach MCP-/P12-Arbeit einplanen |
| **Status** | Neu geplant |
| **Status** | Technischer Pfad umgesetzt; BILL-08 wartet auf externe Production-Gates |
## Ziel
@@ -16,7 +16,10 @@ Legacy-Provider wird als Billing-/Payment-Default abgeloest. HiveGrid nutzt:
- **Mollie** nur als Payment Processor.
- **HiveGrid** als Produkt-/Entitlement-Schicht.
v1-Scope ist **Plans + Seats**. Kein Usage-Billing, keine Credits, keine oeffentlichen Preisversprechen im Code.
Der umgesetzte Scope umfasst die drei Basispakete **Core / Swarm / Colony**,
rollenbasierte Zusatzsitze, feste wiederkehrende Speicherpakete, Lago-Rechnungen
und Mollie-Zahlungen. Es gibt kein Usage-Metering, keine Credits und keine
automatische Enterprise-Buchung.
## Ticket-Reihenfolge
@@ -30,7 +33,21 @@ v1-Scope ist **Plans + Seats**. Kein Usage-Billing, keine Credits, keine oeffent
8. `BILL-07` — E2E-Sandbox-Flow
9. `BILL-09` — Kunden-Rechnungszugriff in HiveGrid
10. `BILL-10` — Self-Service-Checkout fuer Planwechsel
11. `BILL-08` — Prod-Prep fuer eigene Lago-Instanz
11. `BILL-11` — Pricing-Katalog, Jahresbindung und Recurring Payments
12. `BILL-12` — Kundenplan-Namen in Billing-Oberflaechen konsistent halten
13. `BILL-13` — Immersiver Mollie-Checkout, Add-on-Wechsel und
read-only Usage-Transparenz
14. `BILL-14` — Zweistufige Registrierung mit Teamgröße, Tarifempfehlung und
Checkout-Prefill
15. `BILL-18` — Responsive Registrierungs-Tarifwahl und sicherer CAPTCHA-Retry
16. `BILL-21` — Beträge über 1.000 EUR brutto in Erst- und Folgezahlungen
ausschließlich per Mollie-Karte einziehen
17. `BILL-22` — geführter Checkout mit Teamgröße vor Tarif, getrennten
Speicher-/E-Mail-Upsells und freier Mollie-Zahlart bis 1.000 EUR
18. `BILL-08` — Prod-Prep; technisch vorbereitet, wartet nur auf
`EXT-16` Mollie-Live/KYC und Legal-/Steuerfreigabe
19. `BILL-25` — egress-resiliente Speicherpreise, Download-Traffic-
Transparenz und erneuter Staging-Journey-Proof vor Production-Sync
## Architektur-Grenzen
@@ -38,9 +55,20 @@ v1-Scope ist **Plans + Seats**. Kein Usage-Billing, keine Credits, keine oeffent
- HiveGrid cached den Zustand, der fuer Feature-Gates und UI noetig ist.
- Mollie bekommt nur Payment-Minimum: Betrag, Invoice-Referenz, Customer-Referenz, noetige Kontaktdaten.
- Keine HiveGrid-Fachdaten an Lago oder Mollie.
- Staging darf eine geteilte Lago-Instanz nutzen; Prod bekommt spaeter eine eigene.
- Staging und Production nutzen getrennte Lago-Instanzen und denselben
versionierten Katalog-Contract.
- Kein Lago-Core-Fork ohne separate Lizenz-/Legal-Entscheidung wegen AGPL-3.0.
## Aktueller Betriebsstand
- Lago Staging und Production laufen auf `v1.50.0`; der Katalog-Driftcheck ist
fuer beide Umgebungen identisch.
- Staging hat Monats- und 12-Monatsvertrag, Rollen-Sitze, Speicherpaket, erste
Mollie-Zahlung, Mandat und recurring Folgezahlung bewiesen.
- Am 2026-07-29 entstand im vollstaendigen Staging-Checkout die Rechnung
`HIV-25FE-002-015`; Status und PDF sind in HiveGrid abrufbar.
- Production-Side-Effects bleiben bis `BILL-08` / `EXT-16` fail-closed.
## Legacy-Drift
`BILL-00` hat die aktiven Ticketdocs fuer den Billing-Pfad auf `AD-27` recuttet. Alte Legacy-Provider-Erwaehnungen in
@@ -0,0 +1,350 @@
# CI-05 · Docker-Smoke: Runner-Isolation, Fail-fast-Timeouts und Diagnostik
| | |
|---|---|
| **Typ** | Dev (CI/Infra) |
| **Owner** | Raffael |
| **Phase** | P1 · Querschnitt/CI |
| **Cycle/Fenster** | v2-W1 · 2026-07-18 |
| **Status** | abgeschlossen · **6/6 DoD = 100 % done** |
## Abhängigkeiten & Parallelität
- **Blocked by:** keine. Die Repository-Härtung ist unabhängig von Produktcode ausführbar.
- **Blocks:** `VA-P26a` ausschließlich für einen vertrauenswürdigen Remote-Docker-Proof. Die fachlichen
Staging-/UAT-Gates von `VA-P26a` bleiben davon getrennt. `VA-P26b` und `VA-P26c` sind nur transitiv
über `VA-P26a` betroffen; es werden keine redundanten direkten Kanten angelegt.
- **Läuft parallel zu:** Produktarbeit, solange keine fremden Actions-Läufe abgebrochen und keine
Shared-Runner-/Docker-Daemon-Ressourcen neu gestartet werden.
- **Konflikt-Risiko:** hoch auf dem geteilten Docker-Daemon. Deshalb sind lauf-spezifische
Runtime-Ressourcen, ausschließlich gesperrte Dependency-Caches und begrenzte Prozessgruppen Teil
des Ticket-Scopes. Die fünf Root-Closures entstehen parallel innerhalb eines gemeinsamen,
atomaren Bundle-Schritts. Diese Isolation erlaubt Parallelität ohne Namens- oder Cache-Kollisionen.
## Auslöser und Befund
Der Docker-Smoke in Actions-Lauf `10527`, Job `44007`, baute rund 79 Minuten alle Images, bevor der
Worker-Smoke nach 1:21 Minuten mit Exit 1 und nur zwei Prisma-Ladezeilen scheiterte. Web-, Portal-,
API- und MCP-Runtime waren zuvor grün. Parallel laufende PR-Jobs verwendeten dieselben globalen
`hivegrid-*:smoke`-Tags, dieselbe Fake-Revision und denselben Host-Docker-Daemon. Auf `node1` wurden
gleichzeitig extreme Last, fehlende Snapshot-Layer, festhängende Container-Entfernung und
Healthcheck-/FIFO-Timeouts beobachtet. Ein retained-image-Probecontainer beendete seinen Prozess mit
Exit 0, blieb aber im Docker-Status `removing` hängen. Das belegt die Runner-/Daemon-Fehlerklasse,
nicht einen reproduzierbaren Worker-Produktfehler.
Zusätzlich läuft auf `node1` noch ein Runner, der `timeout-minutes` nicht wirksam durchsetzt. Dieses
Ticket baut deshalb einen vom Runner unabhängigen Prozessgruppen-Hardcap ein. Ein Runner-Upgrade ist
ein separater operativer Rollout und autorisiert keinen Neustart während aktiver Jobs.
## Was wir bauen
Den vorhandenen Gitea-Docker-Smoke so härten, dass PR-Läufe den geteilten Daemon nicht gegenseitig
verfälschen, ein kaputter Worker früh sichtbar wird und jeder Build-/Runtime-Schritt eine echte
Obergrenze sowie verwertbare, secret-sichere Fehlerausgabe besitzt. Der Smoke bleibt ein lokaler
Build gegen den persistenten BuildKit-Cache; es werden keine Images publiziert und keine
Produktions-/Staging-Ressourcen verändert.
## Definition of Done
- [x] **Lauf-Isolation:** echte `gitea.sha`-Revision; Image-Tags sowie Container-, DB-, Redis-,
Netzwerk- und Controller-Volume-Namen enthalten `run_id` + `run_attempt`. Globale `:smoke`-Tags,
Fake-SHA und kollidierende `/tmp`-Dateien sind im CI-Pfad ausgeschlossen.
- [x] **Parallel-sichere Cache- und Laufisolation:** die gemeinsamen Dependency-Layer bleiben über
einen ausschließlich gesperrten, selbstheilenden Store deduplizierbar. Alle fünf
Production-Closures entstehen parallel in einem atomaren Bundle-Layer, danach laufen ihre
Prune-/SBOM-Stages ohne Store-Mount. Lauf-spezifische Runtime-Ressourcen erlauben Smokes
verschiedener Refs ohne globale Job-Sperre; supersedierte Läufe werden abgebrochen statt weiter
in der Queue zu stehen.
- [x] **Zwei-Wellen-Ausführung und gezielter Retry:** alle sechs Images bauen kontrolliert parallel
und werden vollständig eingesammelt; erst nach dieser Barriere laufen alle sechs unveränderten,
service-isolierten Runtime-Smokes parallel. Jeder Zieltyp bleibt einzeln erneut ausführbar und
nutzt dabei das revisionsgleiche Web-Migrator-Image.
- [x] **Echte Zeitgrenzen und Cleanup:** portable Prozessgruppen-Timeouts begrenzen Suite, Builds,
Runtime-Smokes, Docker-Probes, Logs und Cleanup. TERM wird nach kurzer Grace-Period zu KILL
eskaliert; Exit 124 ist eindeutig. Cleanup erhält den ursprünglichen Fehlerstatus und kann den
Job nicht endlos blockieren.
- [x] **Verwertbare, secret-sichere Diagnostik:** Stage, Dauer und Exit/Signal werden ausgegeben,
aber weder argv noch Environment. Migrations-/`db push`-Fehler werden nicht unterdrückt;
Containerlogs sind zeitlich und per Tail begrenzt. Keine `ERR`-/`BASH_COMMAND`-Ausgabe.
- [x] **Proof:** Workflow-/Runtime-Vertragstests, Typecheck, Lint und vollständige Testsuite sind
lokal grün. Ein isolierter Gitea-Lauf beweist entweder den vollständigen grünen Docker-Smoke oder
einen innerhalb des definierten Budgets abgebrochenen Fehler mit benannter Stage und Diagnose.
## Technische Bausteine
- `.gitea/workflows/ci.yml`: superseded-run-Cancellation, `gitea.run_id`/`run_attempt`, echte SHA und
runner-unabhängiger Suite-Hardcap.
- `Dockerfile` und `scripts/ci/deploy-production-closures.sh`: ein deduplizierter, gesperrter und
selbstheilender v2-Store; Fetch plus fünf parallele Offline-Deploys bilden gemeinsam einen
atomaren Closure-Layer, danach bleiben Pruning und SBOM target-spezifisch.
- `scripts/ci/docker-smoke-suite.sh`: Zwei-Wellen-Orchestrator mit `all` sowie einzelnen Targets;
run-spezifische Tags, Build-Barriere, Web-Migrator-Reuse und pro Phase begrenzte Ausführung.
- `scripts/lib/run-command-with-timeout.mjs`: portabler Node-24-Prozessgruppen-Runner ohne Shell-
Interpolation oder Ausgabe von Kommandoargumenten/Environment.
- `scripts/lib/docker-runtime-smoke.sh`: gemeinsame Bash-3.2-Helfer für Run, Capture, Probe,
Tail-Logs und statusbewahrenden Cleanup.
- `scripts/docker-*-runtime-smoke.sh`: lauf-spezifische Ressourcen, sichtbare Migrationen,
begrenzte Diagnostik/Cleanup.
- `scripts/verify-gitea-ci-workflow.mjs` und Vertragstests: negative Guards gegen Fake-SHA, globale
Tags, erneut eingeführte Job-Serialisierung, unkontrollierte Parallelität und fehlende Timeouts.
## Retry-Vertrag
Ein fehlgeschlagener Lauf behält seine run-spezifischen Image-Tags. Auf demselben Runner kann exakt
ein Target mit identischer Run-ID und Revision erneut ausgeführt werden, zum Beispiel
`DOCKER_SMOKE_RUN_ID=<run>-<attempt> DOCKER_SMOKE_REVISION=<sha> bash
scripts/ci/docker-smoke-suite.sh worker`. Fehlt das passende Web-Migrator-Image oder stimmt sein
Revision-Label nicht, baut der Orchestrator nur dieses notwendige Image nach. Erfolgreiche Retries
ersetzen keinen vollständigen CI-Proof.
## Rollback
Repository-Rollback: Workflow auf den vorherigen monolithischen Docker-Smoke zurücksetzen und die
neuen Orchestrator-/Helper-Dateien entfernen. Bereits erzeugte run-spezifische Tags und Ressourcen
sind reine CI-Artefakte; sie können erst nach read-only Namensprüfung durch die bestehende
Runner-Prune-Routine entfernt werden. Kein Daemon-Neustart, kein pauschales Löschen und keine
Änderung an Staging/Produktion gehören zu diesem Rollback.
## Quellen
- Gitea Actions `10519/43979`, `10527/44007` und paralleler Lauf `10523`
- Erfolgreicher isolierter Docker-Proof: Gitea Actions `10574/44135`
- `.gitea/workflows/ci.yml` · `scripts/docker-*-runtime-smoke.sh`
- `docs/AGENT-CHECKLIST.md` · `AGENTS.md` §Estate-Infrastruktur/Deploy
- `infra/STANDARDS.md` · `infra/LESSONS.md` (Shared Runner und Docker-Daemon)
## Umsetzungs-Notiz
2026-07-18 · Raffael: Ticket nach Runner-/Workflow-Forensik angelegt. Der Produktbranch von
`VA-P26a` bleibt unverändert. **Startstand: CI-05: 0/6 DoD = 0 % done · 6 Punkte selbst machbar.**
2026-07-18 · Raffael: Der Docker-Smoke ist lokal auf lauf-spezifische Images, Container, Netze und
Volumes umgestellt und ref-übergreifend serialisiert. Der neue sequenzielle Orchestrator prüft Web
und Worker zuerst, bietet einen revisionsgebundenen Einzel-Target-Retry und beendet die Gesamtsuite
runner-unabhängig nach spätestens 42 Minuten. Jeder Build-, Migrations-, Rollen-, Runtime-, Probe-,
Log- und Cleanup-Pfad besitzt einen benannten Prozessgruppen-Timeout mit TERM/KILL-Eskalation.
Erwartete fachliche Ablehnungen benötigen zusätzlich zu ihrem Exit 1 einen ausschließlich im
laufenden Container erzeugten Marker; Timeout 124, Spawn-, Transport- und Docker-Daemon-Fehler
können Negativtests nicht mehr falsch-grün machen. Cleanup ist bei bereits
fehlenden Ressourcen idempotent, meldet aber hängende oder nachweislich verbliebene Ressourcen,
ohne den ursprünglichen Jobstatus zu überschreiben. Environment-Werte und Kommandoargumente werden
nicht in Wrapper-Diagnosen ausgegeben.
**Lokaler Proof:** Typecheck und Lint grün; vollständige Suite: 957 Testdateien und 6.598 Tests
bestanden, 10 Dateien beziehungsweise 55 Tests erwartungsgemäß übersprungen. Die fokussierten
Timeout-/Runtime-/Workflow-Verträge sind 190/190 grün. Gitea-CI-Vertrag 167/167,
Deploy-Vertrag 201/201, Portal-Controller-Vertrag 27/27, CI-Baseline 35/35, Source-Health 19/19,
Docker-Baseline 309/309 und Non-Root 4/4 grün. Secret-Scan: 0 reale Treffer. `bash -n`, ShellCheck
auf Warning-Level und `git diff --check` sind grün. Das unabhängige Diff-Review wurde bis zu den
Negativtest-, RLS-Provisionierungs- und Cleanup-Fehlerklassen nachgezogen; alle konkreten Findings
sind mit Regressionstests geschlossen.
Der erste Remote-Qualitätslauf zeigte zusätzlich eine Linux-spezifische Test-Harness-Falle: Der
Gitea-Jobcontainer verwendet keinen reaping Init-Prozess, sodass bereits getötete Enkelprozesse als
Zombies in `/proc` sichtbar bleiben und `kill(pid, 0)` weiter erfolgreich ist. Der Test akzeptiert
jetzt ausschließlich die Linux-States `Z`/`X`/`x` oder `ENOENT` als terminiert; laufende und
gestoppte States bleiben rot. Die produktive Timeout-Logik war davon nicht betroffen.
**Remote-Proof:** PR `#159`, Actions-Lauf `10574`, Docker-Job `44135`, Revision
`794cf1caadf11d96ecb197dfe2850999c70d88f8`. Der Job war nach 35:44 Minuten grün; die isolierte
Suite selbst nach 34:46,190 Minuten. Web, Worker, API, MCP, Hocuspocus und Portal-Controller waren
vollständig grün. Der Web-Build blieb mit 18:13 Minuten unter seinem 20-Minuten-Limit. Der danach
früh ausgeführte Worker-Build dauerte 3:20 Minuten; `runtime:worker` war nach 45,456 Sekunden grün,
einschließlich der zuvor unsichtbaren Migration in 31,753 Sekunden sowie Health-, Revisions-,
Negativ- und Cleanup-Probes. Der Gesamtlauf war nur wegen der oben beschriebenen Linux-Zombie-
Fehlklassifikation im separaten Unit-Test-Job rot; der Test-Harness-Fix ist lokal mit zehn
Wiederholungen, 190/190 fokussierten Tests und der vollständigen Suite verifiziert.
**Stand:** CI-05: **6/6 DoD = 100 % done · 0 Punkte offen, 0 selbst machbar**. Es wurden weder
fremde Actions-Läufe abgebrochen noch Runner, Docker-Daemon, Staging oder Produktion verändert.
### Performance-Nachzug nach Laufzeit-Regression
2026-07-19 · Raffael: Die historische Gegenprobe zeigt den harten Laufzeitknick: Mit allen sechs
Targets war der Docker-Smoke in Run `10389` noch nach 8:58 Minuten fertig. Nach globalem
`sharing=locked`, fünf zusätzlichen Production-Store-Rehydrationen und der vollständigen
Serialisierung brauchten Runs `10424`, `10440` und `10519` 32:56, 25:18 und 25:15 Minuten. Der
Controller beziehungsweise die Anzahl der Targets ist damit nicht die Hauptursache.
Der Nachzug nutzt den bereits warmen, ausschließlich gesperrt gemounteten v2-Store in genau einem
Production-Bundle-Schritt. Dieser versucht alle fünf Offline-Deploys innerhalb desselben Locks parallel
in getrennte `/prod/*`-Ziele. Bei einem vollständigen Warm-Store-Treffer entfällt `pnpm fetch` komplett.
Erst nach einem Fehlschlag werden alle fünf Child-Prozesse eingesammelt, genau die fünf Zielverzeichnisse
gelöscht, der Store mit einem frozen Fetch selbst geheilt und die vollständige parallele Welle einmal
wiederholt. Fetch- und Retry-Fehler bleiben fail-closed. Die Closures werden gemeinsam als regulärer
Layer-Output committed; Pruning und SBOM laufen anschließend pro Target außerhalb des Store-Locks.
Damit bleibt die Selbstheilung nach BuildKit-Garbage-Collection erhalten, ohne eine vorsorgliche
Store-Rehydration oder fünf serialisierte Deploys. Der Full-Smoke läuft in zwei kontrollierten parallelen
Wellen. Alle Build-Childs werden vor dem Start der Runtime-Welle vollständig eingesammelt;
alle Runtime-Ressourcen bleiben service- und laufisoliert. Die globale Job-Sperre entfällt und
supersedierte PR-/Branch-Läufe blockieren den Runner nicht mehr. Der bereits parallele Deploy
profitiert ohne Änderung seiner Release-, Signatur-, Migrations- oder Runtime-Gates von demselben
Fetch-once-/Deploy-parallel-Vertrag.
Ein verworfener Zwischenstand mit fünf getrennten kalten Stores wurde in Run `10647` bewusst
fail-closed widerlegt: Alle fünf Production-Targets erreichten parallel ihre Fetch-/Deploy-Stufe,
erzeugten danach 20 Minuten lang keinen Fortschritt und liefen gemeinsam in den Build-Timeout.
Hocuspocus war bereits nach 1:37 Minuten grün. Der Fetch-once-/Deploy-parallel-Vertrag ersetzt deshalb
diesen Zwischenstand; fünf vollständige parallele Kalt-Fetches sind nicht Teil des Ergebnisses.
Run `10653` bestätigte anschließend die gemeinsame Prime-Barriere, widerlegte aber einen read-only
gemounteten Store: Alle fünf Deploys starteten innerhalb von 0,2 Millisekunden und scheiterten mit
`ERR_SQLITE_ERROR`, weil pnpm 11 seinen Store-Index auch bei `--offline deploy` schreibbar öffnet.
Der Store bleibt deshalb nach dem Prime für pnpm-Metadaten schreibbar. Die Deploys enthalten
weiterhin keinen eigenen Paket-Fetch.
Run `10663` bestätigte den parallelen Writable-Deploy vollständig: Der Docker-Smoke war nach 12:47
Minuten grün, alle fünf Deploys starteten innerhalb von 0,6 Millisekunden, luden null Pakete nach und
alle sechs Runtime-Smokes bestanden in einer 1:47-Minuten-Welle. Der absichtlich pro Lauf leere
Zwischenstore verursachte dabei aber noch 1.655 Downloads beziehungsweise 6:14 Minuten Prime-Zeit.
Weil dies das Ziel weniger Minuten verfehlte, entfernt der finale Bundle-Vertrag diesen Run-Scope
wieder: v2 wird im gesamten Dockerfile ausschließlich `sharing=locked` verwendet; andere Refs können
den Store daher während Fetch und der intern parallelen Deploys weder lesen noch verändern.
Run `10665` lieferte den entscheidenden Zwischen-Proof: Der gemeinsame Store meldete 1.655 wiederverwendete
und null heruntergeladene Pakete, trotzdem kostete der noch vorsorglich ausgeführte Fetch 222,9 Sekunden;
die fünf parallelen Deploys danach nur rund 25 Sekunden. Der Web-Build war mit 13:16 Minuten Critical Path,
davon entfielen allein 185,4 Sekunden auf einen Layer-Copy. Beim Jobstart liefen auf dem geteilten
Docker-Host bereits 114 Container. Direkt nach dem I/O-intensiven Export blockierten fünf Runtime-
Docker-Kommandos exakt am bisherigen 30-Sekunden-Limit und der Web-Artefaktcheck am 60-Sekunden-Limit.
Die Image-Builds selbst waren vollständig grün; der Worker-Service-Job scheiterte unabhängig davon nach
fünf Sekunden im Checkout am defekten Runner-Action-Cache, bevor Repository-Code lief.
Der finale Nachzug überspringt deshalb den belegten 222,9-Sekunden-Hot-Path, entfernt außerdem die
ungenutzte `docker/setup-buildx-action` samt 83 Sekunden Setup und rund 14 Sekunden Post-Cleanup und setzt
BuildKit direkt über `DOCKER_BUILDKIT=1`. Die parallel ausgeführten gesunden Runtime-Pfade werden nicht
verlangsamt; nur ihre harten Docker-Kommando-/Artefakt-Caps steigen von 30/60 auf 90/180 Sekunden, damit
kurze Daemon-Lastspitzen keinen falschen roten Lauf erzeugen.
**Lokaler Proof:** Ein echter, durch die Helper-Änderung invalidierter Build der
`production-deps-bundle`-Stufe meldete alle fünf Starts innerhalb einer Millisekunde, null Downloads,
alle fünf erfolgreichen Abschlüsse und `READY source=warm-store`; die Bundle-RUN selbst brauchte 20,6
Sekunden. Der Fetch-Fallback, exakte Cleanup-Grenzen, vollständiges PID-Reaping, genau ein Retry und die
Fehlerweitergabe sind durch positive und negative Verträge geschützt. Die vier fokussierten Testdateien
sind 246/246 grün; Gitea-CI-Vertrag 170/170, Docker-Baseline 329/329 und Controller-Deploy-Vertrag 31/31
grün. Typecheck, Lint und die vollständige Suite sind grün: 971 Testdateien beziehungsweise 6.724 Tests
bestanden, 10 Dateien beziehungsweise 55 Tests wurden erwartungsgemäß übersprungen. ShellCheck,
Dockerfile-Check, Action-Pins, Non-Root 4/4 und `git diff --check` sind ebenfalls grün. Der Remote-Lauf
des finalen Nachzugs liefert den abschließenden Wallclock-Proof; bis dahin wird keine konkrete neue
Zielzeit als erreicht behauptet.
**Stand nach Performance-Nachzug:** CI-05 bleibt **6/6 DoD = 100 % done**. Die sechs Prüfoberflächen,
Timeouts, Diagnostik, Einzel-Target-Retries und Laufisolation bleiben vollständig erhalten.
**Temporäre Runner-Entlastung (2026-07-19):** Der separate Gitea-A11y-Workflow ist bis einschließlich
2026-07-22 nur manuell startbar. Die schnellen A11y-Verträge in der Haupt-CI bleiben aktiv. Danach
wird der separate Workflow mit UI-fokussierten Pfadfiltern wieder für Pull Requests aktiviert.
Der im ersten Remote-Lauf beobachtete Portal-Controller-Fehler war ein reproduzierbarer Test-Flake:
30 Sekunden Produktions-Lease waren im Test auf 30 Millisekunden komprimiert und konnten unter
Runner-Last vor dem JavaScript-Heartbeat ablaufen. Nur die zwei zeitabhängigen Tests wurden auf
virtuelle Timer umgestellt; die Lock-Implementierung bleibt unverändert. Proof: 64 parallele
Fokusläufe mit Parallelität 16 sowie der Controller-Typecheck sind grün.
Der Database-Check in Run `10653` traf denselben Lasttyp: Ein gesunder kalter
`postgres:16-alpine`-Start war nach rund 32 Sekunden bereit, während das Fixture bereits nach
30 Versuchen fail-closed abbrach. Nur das begrenzte Init-Fenster wurde auf 90 Sekunden erweitert;
Migration und Assertions bleiben unverändert. Der lokale Clean-/Legacy-/Concurrency-Proof ist
13/13 grün.
### Performance-Nachzug: CI- und Deploy-Critical-Path
2026-07-19 · Raffael: Der Deploy läuft künftig auf dem dedizierten Homeserver-Runner
`homeserver-hivegrid-deploy` mit Kapazität 1 und ausschließlich dem Label `toolctrl-deploy`. Die
Registrierung ist repository-scoped auf `toolctrl-labs/HiveGrid-Cloud`; der zunächst zu breit
registrierte Runner wurde vor Nutzung deaktiviert, gelöscht und seine Registrierung widerrufen.
Der operative Aufbau, die Repo-Scope-Prüfung und der Recovery-Pfad sind im separaten Infra-PR `#4`
dokumentiert. Preflight und Stage/Promote bleiben fail-closed, laufen nun aber in einem einzigen
Runner-Job. Dadurch entfallen ein zusätzlicher Queue-Slot sowie ein zweiter Checkout, eine zweite
Installation und ein zweiter Cache-Restore bei der Promotion. Die Produktions-Migrationskontrolle
verwendet den bereits exakt auf die freigegebene SHA gebundenen Workspace erneut.
Jeder Staging-Build importiert nur das vorherige target-spezifische `:staging`-Image und exportiert
den Cache inline mit dem ohnehin erforderlichen SHA-Image. Damit kann der neue Runner nach einem
kalten Start Cache-Metadaten per Pull wiederverwenden, ohne sechs tote `build-cache:*`-Lookups oder
einen separaten, nach dem eigentlichen Build zusätzlich fehleranfälligen Registry-Cache-Push. Die
Coolify-Abfrage läuft alle zwei statt fünf Sekunden; das harte Fehlerbudget bleibt unverändert bei
450 Sekunden. Healthchecks behalten ihre 30-Sekunden-Steady-State-Frequenz und erhalten nur während
des Startfensters ein Zwei-Sekunden-Intervall.
Der PR-CI-Job erzeugt den Prisma-Client einmal vor den Lesern und überlappt danach Typecheck/Lint,
Foundation/Package-Tests und Core-Tests. Die Parallelität ist explizit begrenzt: vier Core-Worker,
zwei Foundation-Worker sowie höchstens zwei Package-Prozesse mit jeweils einem Worker. So bleibt
der Wallclock-Gewinn erhalten, ohne den geteilten 20-CPU-Runner neben den sechs Docker-Builds in
Swap zu drücken. Docker-Builds rufen Prisma und die Build-Skripte ohne zusätzliche pnpm-Wrapper auf,
erzeugen die vier DB-Runtime-Artefakte in einem Node/esbuild-Prozess und lassen `.map`/`.d.ts`
bereits beim finalen BuildKit-Copy aus. Coverage und Bundle-Budget brechen supersedierte PR-Läufe
jetzt ebenso ab wie die Haupt-CI.
**Lokaler Proof:** Sechs unabhängige CI-/Deploy-/Docker-Verifier und 315 fokussierte Vertrags-Tests
sind grün. Typecheck, Lint, Foundation- und Package-Suiten sind grün. Der auf vier Worker begrenzte
Core-Rerun bestand 972 Testdateien und 6.743 Tests; 10 Dateien beziehungsweise 55 Tests wurden
erwartungsgemäß übersprungen, Wallclock 2:22,70 Minuten. Ein bewusst gleichzeitig ausgeführter
kalter Portal-Controller-Build provozierte zuvor genau einen zeitabhängigen Core-Flake; der
unbelastete identische Core-Rerun war vollständig grün. Das reale Controller-Image wurde danach
erfolgreich geladen und beweist Nonroot-UID 1000, exaktes Revisionslabel, SBOM sowie null
`.map`-/`.d.ts`-Dateien unter finalem `node_modules`. `git diff --check` ist grün. Der neue Remote-Lauf
`10674` lieferte den Full-Docker- und Wallclock-Proof: Alle sechs Images und Runtime-Smokes waren in
16:35 Minuten grün; die eigentliche Build-Welle brauchte rund zwölf Minuten statt der zuvor beobachteten
80 Minuten. Typecheck/Test war nach 13:07 Minuten grün, sein paralleler Quality-Block nach 7:23 Minuten;
Bundle-Budget und Coverage waren nach 9:34 beziehungsweise 4:12 Minuten grün. Der einzige rote Job
scheiterte vor jedem Repository-Schritt im bekannten parallelen Action-Cache-Race des alten
`gitea/act_runner` v0.6.1. Der node1-CI-Runner und der Homeserver-Deploy-Runner wurden deshalb bei
vollständig leerer Queue auf den digest-gepinnten `gitea/runner` v1.0.8 gehoben; der Upstream-Fix ist
seit v1.0.2 enthalten.
Der Wiederanlauf des Homeserver-Runners deckte zusätzlich einen bestätigten Docker-Engine-29.2.1-
BuildKit-Panic im History-Listener auf. Bis zum kontrollierten Host-Upgrade auf die gefixte Engine-Linie
29.4+ nutzt jeder Staging-Deploy deshalb denselben `docker-container`-Builder mit digest-gepinntem
BuildKit v0.31.2. Seine History ist auf 24 Stunden/20 Einträge, sein Cache auf 30 GB sowie 100 GB freien
Host-Speicher und seine Parallelität auf zwölf Build-Schritte begrenzt. Er startet erst direkt vor der
Build-Welle und wird danach auch bei regulären Fehlern gestoppt, aber nicht gelöscht; dadurch bleiben die
begrenzten Paket-Cache-Mounts warm. Jeder folgende serialisierte Deploy stoppt zuerst eine verwaiste
Host-Instanz; `restart-policy=no` verhindert ihren automatischen Wiederanlauf nach einem Docker-Neustart.
Der Staging-Pfad prüft Host-Image, Restart-Policy und die tatsächlich geladene TOML unabhängig von den
frischen Buildx-Client-Metadaten des Jobcontainers. Ein Hard-Abbruch kann damit nur diese eine stabile
Instanz bis zum nächsten Deploy hinterlassen, aber kein weiteres Cache-Volume erzeugen. Der reale
Fresh-Client-Boot/Stop/Restart beweist Driver `docker-container`, BuildKit v0.31.2, Cache-Erhalt und die
übernommenen GC-Grenzen. Promotionen bauen weiterhin kein Image neu.
Der erste Lauf nach der Runner-Umstellung (`10684`–`10686`) bestätigte den Effekt: Bundle-Budget war
nach 4:22 Minuten und Coverage nach 3:29 Minuten grün. Die Haupt-CI brauchte vom ersten bis zum letzten
Job 16:09 Minuten; Docker Smoke war nach 15:05 Minuten grün, davon 14:13 Minuten für die Suite und rund
12:01 Minuten für die Build-Welle. Static 1/2, Build, API, MCP, Hocuspocus, Worker, Controller und DB
brauchten 2:32/6:03, 7:30, 3:16, 1:37, 2:15, 3:52, 2:05 und 7:33 Minuten. Der grüne Hocuspocus-Lauf
bestätigt insbesondere, dass das frühere Action-Cache-Race unter Runner v1.0.8 nicht wieder auftrat.
Der einzige rote Job dieses Laufs waren zwei lastabhängige 20-Sekunden-Testtimeouts. Die beiden alten
Marketing-Report-Fixtures kopierten pro Negativfall rekursiv rund 41 MB beziehungsweise 4.896 Dateien;
zusammen erzeugten sie etwa 248 MB und 29.000 Dateikopien im Docker-Overlay. Die Tests verlinken nun die
nur gelesenen vollständigen `apps`-/`packages`-/`prisma`-Oberflächen und kopieren ausschließlich die
wenigen mutierten Doku-Fixtures. Dadurch bleibt der globale 20-Sekunden-Guard scharf; außerdem enthält
die KB-Fixture jetzt die zuvor fehlende `packages`-Oberfläche. Der Fokuslauf ist 8/8 grün bei rund
0,23 Sekunden je Datei. Typecheck, Lint und der vollständige lokale Lauf sind ebenfalls grün:
973 Testdateien und 6.762 Tests bestanden; 10 Dateien beziehungsweise 55 Tests wurden erwartungsgemäß
übersprungen. Der Folge-Lauf liefert den abschließenden Remote-Proof.
**Stand nach CI-/Deploy-Nachzug:** CI-05 bleibt **6/6 DoD = 100 % done · 0 Punkte offen,
0 selbst machbar**. RLS-, Migrations-, Signatur-, SBOM-, Nonroot-, Revision- und Runtime-Gates wurden
nicht gelockert.
Der zweite Remote-Lauf (`10687`–`10689`) bestätigte den inkrementellen Docker-Cache: Eine reine
Test-/Planungsänderung reduzierte die Build-Welle von rund zwölf auf 2:46 Minuten; alle sechs
Anwendungs-Layer wurden wiederverwendet. Drei Runtime-Smokes brachen danach nicht an Migrationen oder
Anwendungschecks ab, sondern während ihre frischen Postgres-Container unter der parallelen Hostlast
noch im Post-Bootstrap liefen. Die bereits zentral definierte 90er Readiness-Grenze ersetzt deshalb
für alle fünf DB-Smokes die versehentlich hart codierten 30 Versuche. TCP-Readiness, Fail-closed-Exit,
Logs und der äußere 420-Sekunden-Hardcap bleiben unverändert. Der Cleanup bleibt begrenzt, erhält aber
15 statt fünf Sekunden; die drei fehlgeschlagenen Container-Entfernungen hatten jeweils erst nach dem
bisherigen 5+2-Sekunden-Budget abgebrochen. Erfolgreiche Probes und Cleanups kehren weiterhin sofort
zurück.
Der gleichzeitig rote Coverage-Lauf war ein unabhängiges Listener-Race im WebSocket-Gateway-Test:
Ein 15-ms-Heartbeat konnte den Socket schließen, bevor der Test nach der Authentifizierung seinen
`close`-Listener registrierte. Der Listener wird nun vor der Authentifizierung gesetzt; produktiver
Code, Heartbeat-Intervall und globales 20-Sekunden-Testlimit bleiben unverändert. Der Fokusproof ist
130/130 grün; Gitea-CI-Vertrag 173/173, Docker-Baseline 355/355 und deren negative Vertrags-Suiten
165/165 sind grün. Der neue Remote-Lauf liefert den abschließenden End-to-End-Proof.
**Stand nach Robustheits-Nachzug:** CI-05 bleibt **6/6 DoD = 100 % done · 0 Punkte offen,
0 selbst machbar**.
@@ -0,0 +1,92 @@
# CR-ADMIN-IA · Vorschlag: Admin-Navigation auf 8 Bereiche mit Inner Sidebars
| | |
|---|---|
| **Typ** | Change-Request (nicht beauftragt) |
| **Owner** | offen — Entscheidung Raffael |
| **Phase** | Querschnitt · Plattform-Admin |
| **Status** | Vorschlag, wartet auf Entscheidung |
| **Herkunft** | Kapitel 9 des Admin-Audits vom 26.07.2026 |
| **Verwandt** | [`R-ADMIN1`](R-ADMIN1.md) (Fix-Serie), `UI-01` dort |
## Warum das ein CR ist und kein Fix
`R-ADMIN1` behebt Defekte: falsche Texte, kaputte Zahlen, tote Links. Kapitel 9
des Berichts ist etwas anderes — es entwirft eine **neue
Informationsarchitektur** für den Admin-Bereich: 8 statt rund 28
Navigationspunkte, umbenannte und zusammengelegte Routen, eine Redirect-Map über
etwa 30 URLs. Das ist eine Produktentscheidung mit Migrationsaufwand, kein
Fehlerbehebung. Nach `AGENTS.md` läuft so etwas über den
Change-Request-Workflow, nicht über ein Fix-Ticket.
Die Analyse dahinter (Kapitel 8, `IA-01` bis `IA-13`) ist als Befundliste in
`R-ADMIN1` erfasst und dort einzeln behebbar. Dieses Dokument hält nur den
**Gesamtentwurf** fest.
## Der Entwurf in Kurzform
Acht Top-Level-Bereiche, jeder mit permanent sichtbarer Inner Sidebar
(Textlabels, kein Hover, keine Icon-Rail, keine Tabs im Content):
| # | Bereich | Route | fasst zusammen |
|---|---|---|---|
| 1 | Übersicht | `/` | heute `/dashboard` |
| 2 | Kunden | `/tenants` | `/accounts*`, `/kwp-contracts` |
| 3 | Betrieb | `/ops` | `/health` + `/system` (Merge), `/jobs`, `/deploys` |
| 4 | Plattform | `/platform` | `/api*`, `/feature-flags*`, `/notifications*`, `/marketing-integrations` |
| 5 | Support | `/support` | `/support*`, `/select-tenant` |
| 6 | Sales | `/sales` | eigener Produktbereich, 11 Routen |
| 7 | Sicherheit & Audit | `/security` | `/audit`, `/admin-users*`, Sessions |
| 8 | Einstellungen | `/settings` | Profil, Sicherheit, Plattform, Benachrichtigungen, Sales-Settings |
Dazu zwei Detailvorschläge:
- **Mandanten-Detailseite in Tabs** statt einer Mega-Seite (Überblick, Abo,
Nutzer, Billing, Notizen, Erweitert). Der Abo-Baukasten erhält **einen**
Sticky-Save mit Diff-Anzeige statt 34 einzelner Speichern-Buttons.
- **Redirect-Map alt → neu** als permanente Weiterleitungen für Bookmarks.
Der vollständige Wortlaut inklusive aller Inner-Sidebar-Listen liegt im
Auditbericht. Die Redirect-Map ist dort **abgebrochen** (endet in der Zeile für
`/sales/...`) und müsste vor einer Umsetzung vervollständigt werden.
## Konflikte mit dem Bestand — vor einer Entscheidung zu klären
1. **Mandanten-Identifier in Routen.** Der Entwurf schreibt `/tenants/:slug`.
Heute laufen Routen über IDs; `DATA-08` zählt drei parallele Schemata (CUID,
UUID, Slug). Ein Wechsel auf Slug ist eine eigene Migration mit
Eindeutigkeits- und Umbenennungsfragen, nicht ein Routing-Rename.
2. **`/dashboard` → `/`.** Der Admin-Host hat bereits eine Wurzel-Logik
(`isAdminRootPath`, Redirect auf `/dashboard`). Die Umkehrung berührt
Host-Routing und die `.__host`-Alias-Erzeugung.
3. **Sales als eigener Produktbereich.** `IA-11` ist berechtigt, aber der
Admin-Sales-Workspace ist frisch gebaut (`feat/admin-sales-workspace`, gemergt
am 26.07.). Ein Umbau direkt nach dem Merge sollte bewusst entschieden werden.
4. **Merge `/health` + `/system`.** Beide haben eigene Loader, Services und
Tests. Der Merge ist sinnvoll (`IA-07`), aber kein Nebenprodukt.
5. **Bestehende Design-Nachzüge.** `D-ADMIN` ist noch offen; eine neue IA würde
Davids Screen-Grundlage verschieben.
## Empfehlung
**Nicht als Ganzes umsetzen, sondern in zwei Stufen trennen:**
- **Stufe 1 — jetzt sinnvoll, ohne IA-Umbau:** die Einzelbefunde `IA-01`, `IA-02`,
`IA-05`, `IA-06`, `IA-09`, `IA-12` aus `R-ADMIN1`. Kern ist eine
**Route-Registry** als einzige Quelle für Nav-Label, H1, `document.title` und
Breadcrumb. Damit werden tote Links strukturell unmöglich (`IA-03`), die
Titel-Widersprüche verschwinden, und die Command-Palette speist sich aus
derselben Quelle. Das ist ein abgrenzbares Dev-Ticket ohne URL-Änderung.
- **Stufe 2 — echter CR:** die Umbenennung und Zusammenlegung der Routen samt
Redirect-Map. Braucht eine Produktentscheidung, eine vollständige Redirect-Map
und eine Abstimmung mit `D-ADMIN`.
`UI-01` (fünf Sub-Navigations-Patterns auf eines) lässt sich unabhängig von
Stufe 2 lösen: ein Pattern für alle bestehenden Routen, ohne eine URL zu ändern.
## Offene Fragen an Raffael
1. Stufe 1 (Route-Registry) als eigenes Dev-Ticket freigeben?
2. Soll `UI-01` das bestehende Routing behalten oder auf Stufe 2 warten?
3. Ist der Sales-Bereich als eigenes Produkt gewollt (`IA-11`) — und wenn ja,
vor oder nach dem v2-Gate?
@@ -42,7 +42,6 @@ Abnahme-Formular-Renderer (Repeater für Mängel mit Foto-Upload aus Kamera); M
## Quellen (granular)
- `designer-briefs/P09-projekt-pipelines-auftrag.md` → §Benötigte Screens „📱 Abnahme-Workflow" + „Abnahme-Liste" (NUR diese) + zugehörige Features/UI-Elemente
- `ENTITY-MODEL.md` → **Domäne 5** (AbnahmeProtokoll/AbnahmeSignatur als immutable Sub-Area am Projekt; Checkliste typ=maengel) — **Pivot-Vorrang**
- `SCREEN-MAP.md` → §4 Abnahme · `ROADMAP.md` → Phase 9 · `_bmad-output/specs/M04-auftragspipeline.md`
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
@@ -54,7 +54,6 @@ Eigene Admin-Sidebar + -Topbar (getrennt von A1); KPI-Kacheln mit Drill-Down + Z
## Quellen (granular)
- `designer-briefs/P19-plattform-admin.md` (vollständiger Brief — alle Admin-Screens, diese Doc ist sein Ticket-Destillat)
- `ENTITY-MODEL.md` → Domäne 11 (Plattform-Admin) + Domäne 12 (Abo-Baukasten, für Abo-Zusammenstellung)
- `SCREEN-MAP.md` → §3 Plattform-Admin · `ROADMAP.md` → Phase 19 · `_bmad-output/specs/M37-plattform-admin.md`, `M32-feature-flags.md`
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
@@ -44,7 +44,6 @@ Kalender-Grid (Monat/Woche, Quell-farbige Termine); Connection-Card mit Status-A
## Quellen (granular)
- `designer-briefs/P16-kalender-booking-forms-signatur.md` → §Benötigte Screens „Booking-Page" + „Kalender" + „Kalender-Verbindungen/-Detail" (NUR diese) + zugehörige Features/UI-Elemente
- `ENTITY-MODEL.md` → Domäne 9 (Kalender/Booking)
- `SCREEN-MAP.md` → §5 Booking/Kalender · `ROADMAP.md` → Phase 16 · `_bmad-output/specs/M25-calendar-sync.md`, `M06-booking.md`
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
@@ -51,7 +51,6 @@ Channel-Listen-Einträge (Snippet, Unread-Badge, Mention-Marker, Pin-/Mute-/Typ-
## Quellen (granular)
- `designer-briefs/P15-telefonie-chat.md` → §Benötigte Screens „Chat-Index" + „Channel-Detail" + Chat-Nebenflächen (Thread/Pinned/Mentions/Suche/Neuer-Channel/Settings/Admin-Chat) — NUR Chat; Telefonie → `D-REST`
- `ENTITY-MODEL.md` → Domäne 8 (Kommunikation: TeamChat/Member/Message/Thread/PinnedMessage/Reaction/Read)
- `SCREEN-MAP.md` → §4 Chat · `ROADMAP.md` → Phase 15 · `_bmad-output/specs/M13-team-chat.md`
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
@@ -8,7 +8,7 @@
| **Cycle/Fenster** | W2 — Plattform & CRM (Demo 1) · 2026-06-22 → fällig 2026-06-24 |
| **Status** | geplant |
> 🔴 **Pivot-Vorrang (AD-20):** Für den CRM-Kern gilt das **`ENTITY-MODEL.md`**, nicht die teils noch pre-Pivot-SCREEN-MAP. Konkret: **kein Lead-Promotion-Modal** mehr (gehört zu P7, jetzt Lead→Projekt). `Kontakt` ist Oberbegriff mit **Kontakttyp** (Privatperson/Organisation), **Kontaktstatus** (Kontakt/Kunde/Bestandskunde), **Kontaktart** (Haupt-/Sekundärkontakt = Rolle einer Relation). Zwei Listen-Einstiege: Organisationen **und** Kontakte.
> 🔴 **Pivot-Vorrang (AD-20):** Für den CRM-Kern gilt das **`ENTITY-MODEL.md`**. Es gibt **kein Lead-Promotion-Modal** mehr (gehört zu P7, jetzt Lead→Projekt). `Kontakt` ist Oberbegriff mit **Kontakttyp** (Privatperson/Organisation), **Kontaktstatus** (Kontakt/Kunde/Bestandskunde), **Kontaktart** (Haupt-/Sekundärkontakt = Rolle einer Relation). Zwei Listen-Einstiege: Organisationen **und** Kontakte.
## Abhängigkeiten & Parallelität
- **Blocked by:** `D-D0b` (Archetypen A2/A3/A5/A6), `R-REFIT` (Boilerplate-Entity-Builder entfernt, Datenmodell-Refit)
@@ -47,7 +47,6 @@ Daten-Tabelle (sortierbar, paginiert); Filter-Bar (Multi-Select Tags UND/ODER);
## Quellen (granular)
- `designer-briefs/P06-crm-kern.md` (vollständiger Brief — diese Doc ist sein Ticket-Destillat)
- `ENTITY-MODEL.md` → **Domäne 5: Projekt-zentrischer CRM-Kern** (Pivot-Vorrang: Kontakt-Oberbegriff/Kontakttyp/-status/-art, KontaktRelation; kein Lead-Promotion-Modal)
- `SCREEN-MAP.md` → §2 · `ROADMAP.md` → Phase 6 · `_bmad-output/specs/M01-crm-kern.md`
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
@@ -39,7 +39,7 @@ Sidebar mit Icon+Label-Navigationseinträgen und drei Konnektor-Zuständen (akti
## Quellen (granular)
- `designer-briefs/P01-fundament-walking-skeleton.md` → §Benötigte Screens „App-Shell-Baseline (A1)" + §Features (App-Shell/Topbar/Status-Banner/Toast) + §UI-Elemente (Sidebar/Topbar/Banner-Teile)
- `SCREEN-MAP.md` → §0.1 App-Shell
- `.planning/designer-briefs/P01-fundament-walking-skeleton.md` → App-Shell
- `DESIGNER-FIRST-PLAYBOOK.md` → §1
- `ROADMAP.md` → Phase 1 · Querschnitt-Block (M00)
@@ -36,7 +36,7 @@ Daten-Tabelle (sortierbar/paginiert) + Karten-Alternative + Filter-Bar + Bulk-Ac
## Quellen (granular)
- `designer-briefs/P01-fundament-walking-skeleton.md` → §Benötigte Screens „Archetypen-Kit A2–A7" + „Basis-Primitives" + §Features (Archetypen + Primitives) + §UI-Elemente (A2–A7 + Primitives)
- `SCREEN-MAP.md` → §0.2/0.3
- `.planning/designer-briefs/P01-fundament-walking-skeleton.md` → Navigation und Zustände
- `DESIGNER-FIRST-PLAYBOOK.md` → §2 Archetypen
- `ROADMAP.md` → Phase 1 · Querschnitt-Block (M00)
@@ -10,43 +10,47 @@
| **Cycle/Fenster** | W3 — Kern-Kette & Kommunikation (Demo 2) · 2026-07-01 → fällig 2026-07-03 |
| **Status** | geplant |
> 🟦 **Bespoke + Compose:** Das **Cmd+K-Such-Modal ist BESPOKE** (klein); das **Dashboard** ist KPI+Widget-Compose; die Vollbild-Such-View aus A2. Deckt alle P11-Screens (Suche + Dashboard).
> 🟦 **Bespoke + Compose:** Die **Spotlight-Suche ist BESPOKE** (klein); das **Dashboard** ist KPI+Widget-Compose. Deckt alle P11-Screens (Spotlight-Suche + Dashboard).
> **Scope-Schnitt 2026-07-12 (verbindlich):** Es gibt in v1 keine nutzerseitige
> `/search`-Vollseite. Globale Suche bedeutet Desktop-Modal per `Cmd+K`/`Ctrl+K` oder
> Header-Suchsymbol und mobiles viewportfüllendes Overlay über das Header-Suchsymbol.
> `/search/api` ist ein interner Resource-Endpunkt und kein Design-Screen. R-P11a darf nach AD-28
> mit Interim-UI fertig werden; das finale `D-DASH`-Delta bleibt als `design-nachzug` offen.
> 🟢 **Kein Pivot-Sonderfall** (P11 nicht Teil der projekt-zentrischen Kern-Kette). Aber: Such-Index + Dashboard-Widgets greifen auf den **`Projekt`-Kern** zu (EIN `Projekt`-Entity-Typ, kein separater Index-Typ je Pipeline). **v1 = nur 3 feste Rollen-Layouts (GF/Büro/Monteur)** ohne Drag&Drop (Layout-Persistenz + Custom-Widgets + Export → v2). Such-Backend = **Meilisearch-Keyword**; pgvector/Hybrid/RAG entfällt nach AD-26.
## Abhängigkeiten & Parallelität
- **Blocked by:** `D-D0b` (Archetypen, KPI-Kacheln, Charts, A5 Modal für Cmd+K)
- **Blockt:** `D-POLISH` (Politur baut u. a. auf Dashboard auf)
- **Bedient (Dev):** `R-P11a`/`R-P11b` (M24 Globale Suche + M20 Dashboard)
- **Subframe:** Pflicht je Route. Cmd+K-Modal **BESPOKE** (klein); Dashboard = KPI+Widget-Compose; Vollbild-Suche aus A2.
- **Bedient (Dev):** `R-P11a`/`R-P11b` (M24 Globale Suche + M20 Dashboard); der Spotlight-Scope-Schnitt lässt `R-P11b` unverändert
- **Subframe:** Pflicht je Screen. Spotlight-Suche **BESPOKE** (klein); Dashboard = KPI+Widget-Compose.
## Was wir bauen
Das **Cmd+K-Such-Modal** (global, gruppierte Treffer mit Match-Highlight), die **Vollbild-Such-View** mit Filtern und das **Dashboard mit 3 festen Rollen-Layouts** (GF/Büro/Monteur) inkl. Dashboard-Switcher.
Die globale **Spotlight-Suche** (Desktop-Modal, mobiles viewportfüllendes Overlay, gruppierte Treffer mit Match-Highlight) und das **Dashboard mit 3 festen Rollen-Layouts** (GF/Büro/Monteur) inkl. Dashboard-Switcher.
## Benötigte Screens
| Screen [Route] | Kern-Inhalt | Archetyp |
|---|---|---|
| **Cmd+K-Such-Modal** [global] | Auto-fokussiertes Such-Eingabefeld, Live-Suche (300ms debounce) · Trefferliste **gruppiert nach Entity-Typ** mit Icon, Titel, Subtitle, **Match-Highlight-Snippet**, letzte-Aktivität (relativ) · Filter-Chips für Entity-Typ (Multi-Select: Kontakte/Projekte/Files/Tasks/Leads …) · Tastatur-Navigation (↑↓ + Enter öffnen, Cmd+Enter neuer Tab, Esc schließen) + Shortcut-Anzeige · Leer-Zustand: **RecentSearches** + Tipps · „Alle {n} Treffer zeigen" → Vollbild-Suche · Loading-Indikator | **BESPOKE** (klein) |
| Vollbild-Such-View [`/search`] | Such-Feld (aus URL-Param), volle Trefferliste (cursor-paginiert 50/Page) mit erweiterten Metadaten (Erstellt, Verantwortlicher, Tags) · **Filter-Sidebar** (Entity-Typ, Erstellt-Range, Verantwortlicher, Tags, modul-spezifisch z.B. Pipeline-Status, Toggle „Archivierte einbeziehen") · Trefferanzahl-Klartext („1.247 Treffer in 0,3 s") · Sortierung (Relevanz/Letzte Aktivität/Erstellt) · Klick → Ziel-Route | A2 |
| **Spotlight-Suche** [global, keine nutzerseitige Route] | Desktop als Modal, Mobile als viewportfüllendes Overlay · Auto-fokussiertes Such-Eingabefeld, Live-Suche (300ms debounce) · Trefferliste **gruppiert nach Entity-Typ** mit Icon, Titel, Subtitle, **Match-Highlight-Snippet**, letzte Aktivität (relativ) · Filter-Chips für Entity-Typ (Multi-Select: Kontakte/Projekte/Files/Tasks/Leads …) · Tastatur-Navigation (↑↓ + Enter öffnen, Cmd/Ctrl+Enter neuer Tab, Esc schließen) + Shortcut-Anzeige · Leer-Zustand: **RecentSearches** + Tipps · Loading-, Keine-Treffer- und Fehlerzustand · Klick/Enter öffnet direkt die Ziel-Route | **BESPOKE** (klein) |
| **Dashboard** [`/dashboard` bzw. `/`] | **3 feste Rollen-Layouts (kein Drag&Drop v1):** **GF** (Begrüßung, Sales-KPIs, Umsatz-Forecast einfach, Projekt-KPIs, Auslastung, offene Mängel, Team-heute) · **Büro** (Begrüßung, Projekt-KPIs, meine Tasks, Anrufe heute, HR-Anträge) · **Monteur 📱** (meine Termine heute, meine Projekte, meine Tasks) · Widgets: KPI-Kachel, Liste, Trend-Chart · Live-Update (SSE/WebSocket) + „Live-Updates pausieren" · Edit = **nur Widget-Filter/Zeitraum** · „Daten zuletzt aktualisiert vor X Min" bei veralteten Aggregaten | KPI + Widget-Compose |
| Dashboard-Switcher [im Dashboard-Header] | Verfügbare Dashboards (rollen-gematcht) auswählbar · Default-Routing nach Rolle | (Teil des Dashboard) |
*(Flow-Editor/Booking/Kalender/Signatur aus SCREEN-MAP §5 gehören zu P12/P16, nicht hierher. Custom-Widgets/Export + Drag&Drop-Grid = v2. Forecast/KPI-Datenquellen kommen aus P8.)*
*(Flow-Editor/Booking/Kalender/Signatur gehören zu P12/P16, nicht hierher. Custom-Widgets/Export + Drag&Drop-Grid = v2. Forecast/KPI-Datenquellen kommen aus P8.)*
## Features (muss abgedeckt sein)
- [ ] Cmd+K-Modal (global Hotkey, debounced, gruppierte Treffer, Match-Highlight, Tastatur-Navigation, RecentSearches) + Wechsel in Vollbild-Such-View mit Filtern
- [ ] Spotlight-Suche (Desktop per Cmd+K/Ctrl+K oder Header-Suchsymbol als Modal, Mobile per Header-Suchsymbol viewportfüllend; debounced, gruppierte Treffer, Match-Highlight, Tastatur-Navigation, RecentSearches)
- [ ] Meilisearch-Keyword-Suche permission-aware (SearchAdapter je Modul); Server-side Permission-Filter (Trefferanzahl = erlaubte Treffer; Klartext „weitere Treffer, die du nicht siehst")
- [ ] 3 feste Rollen-Dashboards (GF/Büro/Monteur, SHK-Default geseedet) aus Widget-Katalog (Sales/Projekte/Tasks/HR/Activity/Comms/~~KI~~ → KI entfällt [[AD-26]])
- [ ] Dashboard-Widgets live (SSE/WebSocket) mit Aggregat-Cache + Lazy-Load/Skeleton; permission-gegated; Monteur-Dashboard mobile-first
- [ ] Edit nur Widget-Filter/Zeitraum (kein Grid-Editor v1); „zuletzt aktualisiert"-Hinweis
## UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)
Such-Eingabefeld mit Auto-Fokus + Debounce; Trefferliste gruppiert nach Entity-Typ mit Typ-Icon; Match-Highlight-Snippet; Relativ-Zeit; Entity-Typ-Filter-Chips (Multi-Select); Tastatur-Navigations-Highlight + Shortcut-Leiste; RecentSearches-Liste (Einzel-/Alle-Löschen); „Alle Treffer zeigen"-Link; Filter-Sidebar (Entity-Typ/Date-Range/Verantwortlicher/Tags/modul-spezifisch + Archiviert-Toggle); Sortier-Auswahl; Trefferanzahl-Klartext; Pagination; KPI-Kachel (Wert/Label/Trend-Pfeil/Vergleich); Listen-Widget; Trend-Chart (Linie/Balken/Donut); Begrüßungs-Widget; Dashboard-Switcher; Widget-Filter-/Zeitraum-Konfig (kein Grid-Editor v1); „Live-Updates pausieren"-Toggle; „zuletzt aktualisiert"-Hinweis; Skeleton-Loading; Empty-/Keine-Treffer-/Fehler-/Permission-Denied-States (Klartext).
Such-Eingabefeld mit Auto-Fokus + Debounce; Desktop-Modal und mobiles viewportfüllendes Overlay; Trefferliste gruppiert nach Entity-Typ mit Typ-Icon; Match-Highlight-Snippet; Relativ-Zeit; Entity-Typ-Filter-Chips (Multi-Select); Tastatur-Navigations-Highlight + Shortcut-Leiste; private RecentSearches-Liste ohne manuelle Löschverwaltung in R-P11a; Loading-, Empty-/Keine-Treffer-/Fehler-/Permission-Denied-States (Klartext); KPI-Kachel (Wert/Label/Trend-Pfeil/Vergleich); Listen-Widget; Trend-Chart (Linie/Balken/Donut); Begrüßungs-Widget; Dashboard-Switcher; Widget-Filter-/Zeitraum-Konfig (kein Grid-Editor v1); „Live-Updates pausieren"-Toggle; „zuletzt aktualisiert"-Hinweis; Skeleton-Loading.
## Quellen (granular)
- `designer-briefs/P11-suche-dashboard.md` (vollständiger Brief — Suche + Dashboard, diese Doc ist sein Ticket-Destillat)
- `ENTITY-MODEL.md` → Domäne 6 (Suche & Dashboard; Projekt-Kern als EIN Index-/Widget-Typ)
- `SCREEN-MAP.md` → §5 Dashboard/Cmd+K · `ROADMAP.md` → Phase 11 · `_bmad-output/specs/M24-globale-suche.md`, `M20-dashboard.md`
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
@@ -13,7 +13,9 @@
> 🟦 **Bespoke-Abgrenzung:** Dieses Ticket deckt **NUR den Flow-/Node-Editor** (~~inkl. eingebettetem Sprach-zu-Automation-Einstieg~~ → entfällt [[AD-26]]; Dry-Run-Vorschau und Loop-/Rate-Schutz-Warnmodal — alles Bespoke-Teile des Editors). Die übrigen P12-Screens (Automation-Liste, Execution-Detail/-Liste, Template-Katalog) sind Compose aus A2/A3 → P12-Compose-Anteil.
> 🔴 **Schwerste UI der App (AD-16, ab 22.06. täglich 1h).** Erste USP-Säule, vollständig bespoke. Klartext-First überall: Knoten-Labels, Dry-Run-Ausgaben, Loop-/Rate-Warnungen und Logs in **verständlichem Deutsch**.
> 🟡 **v1-Grenze:** KWP-Push-Action nur als erweiterbarer Registry-Eintrag (kein KWP-Konfig-UI in v1). ~~Sprach-zu-Automation rendert hier den Flow-Vorschlag; die KI-Pipeline selbst liegt in P13.~~ → **entfällt ([[AD-26]]).**
> 🟡 **v1-/AD-32-Grenze:** KWP-Push bleibt ein nicht ausführbarer Extension-Slot. Keine ausführbare Action und kein
> KWP-Konfig-UI vor `VEXT-6` plus erneuter ausdrücklicher Produktfreigabe. ~~Sprach-zu-Automation rendert hier
> den Flow-Vorschlag; die KI-Pipeline selbst liegt in P13.~~ → **entfällt ([[AD-26]]).**
## Abhängigkeiten & Parallelität
- **Blocked by:** `D-D0b` (Archetypen, A5 Modal)
@@ -31,11 +33,11 @@
| **Dry-Run-Vorschau** [Modal im Editor] | „Trifft X Datensätze" + erste 5 Beispiele · Schritt-für-Schritt-Simulation mit Klartext je Step (z. B. „Email würde an … gehen") · **Bestätigungs-Pflicht** ab >100 Datensätzen/Schritt (Schwelle tenant-konfigurierbar) | A5 + Simulations-Liste |
| Loop-/Rate-Schutz-Warnmodal [im Editor] | Schleifen-Erkennung mit **Abhängigkeits-Graph-Visualisierung** + „Beheben" · Anomalie-Pause-Hinweis (Klartext: „2.000-mal in 5 Min, typisch 5-10/Tag — pausiert") | A5 + Mini-Graph |
*(Automation-Liste, Execution-Detail/-Liste, Template-Katalog = P12-Compose. Trigger-/Action-Library = Daten im Knoten-Katalog, kein eigener Screen. KWP-Push-Konfig → v2.)*
*(Automation-Liste, Execution-Detail/-Liste, Template-Katalog = P12-Compose. Trigger-/Action-Library = Daten im Knoten-Katalog, kein eigener Screen. KWP-Push-Konfig erst nach `VEXT-6` + erneuter Produktfreigabe.)*
## Features (muss abgedeckt sein)
- [ ] Graph-Editor: Knoten hinzufügen/konfigurieren/löschen/duplizieren, Kanten erstellen/löschen, verschieben, Auto-Layout, Undo/Redo, Mini-Map
- [ ] Knoten-Katalog mit voller Trigger-Library (CRM/Lead/Sales/Projekte/Email/Forms/Booking/Kalender/Zeit/Webhook) + Action-Library (CRM/Notification/HTTP/Task/If-Else/Delay/Loop; KWP-Push erweiterbar)
- [ ] Knoten-Katalog mit voller Trigger-Library (CRM/Lead/Sales/Projekte/Email/Forms/Booking/Kalender/Zeit/Webhook) + Action-Library (CRM/Notification/HTTP/Task/If-Else/Delay/Loop; KWP-Push nur nicht ausführbarer Extension-Slot bis `VEXT-6` + erneuter Freigabe)
- [ ] Klartext-Knoten-Labels + Klartext-Validation-Hinweise (unverbunden, Cycle, unvollständig)
- [ ] ~~Sprach-zu-Automation: Satz → Flow-Vorschlag mit Rückfragen, Risiko-Hinweisen, **Bestätigungs-Pflicht (nie Auto-Aktivierung)**~~ → **entfällt ([[AD-26]])**
- [ ] Dry-Run mit Klartext-Wirkungsvorschau + Pflicht-Bestätigung ab Schwelle
@@ -47,7 +49,6 @@ Graph-Canvas (Knoten + Kanten, Pan/Zoom); Knoten-Katalog-Panel (gruppiert/filter
## Quellen (granular)
- `designer-briefs/P12-automation-engine.md` → §Benötigte Screens „Flow-/Node-Editor" ~~+ „Sprach-zu-Automation-Einstieg"~~ (entfällt [[AD-26]]) + „Dry-Run-Vorschau" + „Loop-/Rate-Schutz-Warnmodal" (NUR diese) + zugehörige Features/UI-Elemente
- `ENTITY-MODEL.md` → Domäne 7 (Automation ~~& KI~~: AutomationRule/Step/Execution/Credential — KI entfällt [[AD-26]])
- `SCREEN-MAP.md` → §5 Flow-Editor · `DESIGNER-FIRST-PLAYBOOK.md` → §3 Rang 1 · `ROADMAP.md` → Phase 12 · `_bmad-output/specs/M17-automation-engine.md`
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
@@ -42,10 +42,13 @@ Feld-Palette (12 Typen); Drag-&-Drop-Canvas-Feldliste; Feld-Konfigurations-Panel
## Quellen (granular)
- `designer-briefs/P16-kalender-booking-forms-signatur.md` → §Benötigte Screens „Form-Builder-Canvas" + „Öffentliches Formular" (NUR diese) + zugehörige Features/UI-Elemente
- `ENTITY-MODEL.md` → Domäne 9 (Forms)
- `SCREEN-MAP.md` → §3 Form-Builder · `DESIGNER-FIRST-PLAYBOOK.md` → §3 Rang 2 · `ROADMAP.md` → Phase 16 · `_bmad-output/specs/M05-form-builder.md`
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
- [ ] Neue UI/UX-Entscheidungen:
- [ ] Subframe-Screen-Link(s):
- [ ] Offene Fragen an Dev:
## Dev-Integrations-Notiz (2026-07-10, Akeshan — Querverweis AK-P16c)
Der Subframe-Flow **„(MCP) WF-P16 Form Builder"** (S00/S01/S02/S02L/S03/S04/S05 inkl. E01–E05/V01–V03) wurde am 2026-07-10 als Dev-Nachzug von `AK-P16c` in die App integriert (PR #71). Damit ist der D-FORM-Scope (Builder-Canvas + öffentliches Formular) app-seitig umgesetzt; die „Davids Delta"-Sektion unten ist noch unausgefüllt und kann bei Bedarf gegen den integrierten Stand abgeglichen werden. Nicht umgesetzt (kein Backend, siehe AK-P16c §Noch offen): Versionsverlauf, Theme-Logo/Formularbreite, Lead-Mapping Bereich/Datei/Pipeline, Optionen mischen.
@@ -18,6 +18,11 @@
- **Bedient (Dev):** `AK-P17a`/`AK-P17b` (M14 HR-Hub)
- **Subframe:** Pflicht je Route. Archetypen aus D0; M05-Form-Renderer aus P16 einbetten (nicht neu bauen).
**UX-Nachzug (2026-07-25):** `R-UX3` konkretisiert Personal als **Für mich / Mein Team /
Verwaltung**; `R-UX4` konkretisiert Passwörter als eigenständigen Hauptbereich. D-HR bleibt
Designquelle für beide Flächen. Bis zum finalen Delta gilt AD-28; die historische D-HR-Spec wird
nicht überschrieben.
## Was wir bauen
Den **kompletten HR-Hub**: persönlicher MA-Bereich + Announcements, Urlaubs-/Krankmeldungs-Workflow, Lohnabrechnungen, MA-Anträge, verschlüsselter Passwort-Safe, Surveys, MA-Verzeichnis + Standorte, eigene Dokumente — plus die HR-Admin-Flächen (`/admin/hr/...`).
@@ -56,7 +61,6 @@ KPI-Kacheln (heute krank / im Urlaub / pendente Genehmigungen / offene AU); Card
## Quellen (granular)
- `designer-briefs/P17-hr-hub.md` (vollständiger Brief — alle HR-Screens, diese Doc ist sein Ticket-Destillat)
- `ENTITY-MODEL.md` → Domäne 10 (HR-Hub)
- `SCREEN-MAP.md` → §3 HR · `ROADMAP.md` → Phase 17 · `_bmad-output/specs/M14-hr-hub.md`
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
@@ -18,6 +18,10 @@
- **Bedient (Dev):** `AK-P14a`/`AK-P14b` (M10 Marketing — Kampagnen-Versand + Segment-Engine)
- **Subframe:** Pflicht je Route. Archetypen aus D0; Kampagnen-Editor ist **BESPOKE**.
**UX-Nachzug (2026-07-25):** `R-UX2` konkretisiert den freigegebenen Sechs-Schritt-Wizard,
Segment-Builder und servergleichen Versand-Preflight. D-KAMP bleibt Quelle der finalen
Subframe-Optik und ist nach AD-28 kein Hard-Blocker für eine verifizierte Interim-UI.
## Was wir bauen
**Nur den mehrstufigen Kampagnen-Editor** (Basis → Inhalt → Empfänger → Test → Zeit → Bestätigung, DSGVO-gegated) und den **Segment-Builder** (verschachtelter AND/OR-Filter-Baum mit Live-Empfänger-Anzahl + Auto-Exclusion).
@@ -43,7 +47,6 @@ Mehrstufiger Wizard mit Progress; Rich-Text-/HTML-Editor mit Token-Einfügen; Bi
## Quellen (granular)
- `designer-briefs/P14-email-marketing.md` → §Benötigte Screens „Kampagnen-Editor" + „Segmente" (NUR diese) + zugehörige Features/UI-Elemente
- `ENTITY-MODEL.md` → Domäne 8 (Kommunikation: Campaign/OutboundEmail/RecipientSegment/Unsubscribe/EmailSuppressionList)
- `SCREEN-MAP.md` → §3 Kampagnen · `ROADMAP.md` → Phase 14 · `_bmad-output/specs/M10-email-marketing.md`
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
@@ -10,7 +10,7 @@
> 🟦 **Bespoke-Abgrenzung:** Dieses Ticket deckt **NUR den Pipeline-Kanban** (das EINE konfigurierbare Board). Die übrigen P8-Screens (Projekt-Liste, **Projekt-Detail**, Pipeline-Config-Admin, Lost-Reasons) sind Compose aus A2/A3/A6 → gehören in den P8-Compose-Anteil von **`D-CRM`** bzw. das Projekt-Detail wird in P9 von **`D-PLAN`/`D-ABN`** um Sub-Areas erweitert. Forecast/KPI-Widgets → `D-DASH` (P11).
> 🔴 **Pivot-Vorrang (AD-20):** Es gibt **EINEN `Projekt`-Kern** und **konfigurierbare Pipeline-Views**. „Deal" und „Auftrag" sind **Pipeline-Typen** (`Pipeline.typ_hint = sales/auftrag/custom`), KEINE eigenen Entitäten. **EIN konfigurierbarer Kanban** statt getrenntem Sales- + Projekt-Kanban (SCREEN-MAP §3 „Sales-Kanban [/deals]" ist überholt). **Kein Won-Handoff**, kein zweiter Datensatz — ein Projekt wechselt nur die Pipeline. **`Status` ist immer pipeline-intern** (`PipelineStage.stage_kind = offen/gewonnen/verloren`).
> 🔴 **Pivot-Vorrang (AD-20):** Es gibt **EINEN `Projekt`-Kern** und **konfigurierbare Pipeline-Views**. „Deal" und „Auftrag" sind **Pipeline-Typen** (`Pipeline.typ_hint = sales/auftrag/custom`), KEINE eigenen Entitäten. Es gibt **EINEN konfigurierbaren Kanban**, **kein Won-Handoff** und keinen zweiten Datensatz — ein Projekt wechselt nur die Pipeline. **`Status` ist immer pipeline-intern** (`PipelineStage.stage_kind = offen/gewonnen/verloren`).
## Abhängigkeiten & Parallelität
- **Blocked by:** `D-D0b` (Archetypen, KPI-Kit), `R-REFIT` (Datenmodell-Refit)
@@ -41,7 +41,6 @@ Kanban-Board (Spalten = Stages, horizontal scrollbar/responsive); Drag&Drop-Kart
## Quellen (granular)
- `designer-briefs/P08-projekt-pipelines-kern.md` → §Benötigte Screens „Pipeline-Kanban (konfigurierbar)" (NUR dieser Screen) + zugehörige Features/UI-Elemente
- `ENTITY-MODEL.md` → **Domäne 5** (Projekt-Kern + Pipeline/Stage/PipelineFieldConfig/PipelineAccess; Pivot: typ_hint, stage_kind, EIN Board) — **Pivot-Vorrang**
- `SCREEN-MAP.md` → §3 Kanban · `ROADMAP.md` → Phase 8 · `_bmad-output/specs/M03-sales-pipeline.md`
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
@@ -22,7 +22,9 @@
Die **Nicht-Canvas-Flächen der Automation-Engine**: Übersichtsliste aller Automationen, Run-History (Execution-Liste + Step-by-Step-Execution-Detail mit Klartext-Diagnostik + 24h-Rückgängig), Template-Katalog (SHK + Tenant) und die **Trigger-/Aktion-Konfiguration** als typ-abhängige Knoten-Konfig-Panel-Inhalte (vom Flow-Editor eingebettet).
> 🔴 **Klartext-First überall:** Knoten-Labels, Dry-Run-Ausgaben, Loop-/Rate-Warnungen und Execution-Logs in verständlichem Deutsch, nicht technisch.
> 🟡 **v1-Grenze:** KWP-Push-Action nur als erweiterbarer Registry-Eintrag (zieht v2 nach) — kein KWP-spezifisches Konfig-UI in v1. ~~Sprach-zu-Automation rendert im Flow-Editor (D-FLOW); die KI-Pipeline selbst liegt in P13.~~ → **entfällt ([[AD-26]]).**
> 🟡 **v1-/AD-32-Grenze:** KWP-Push bleibt ein nicht ausführbarer Extension-Slot. Eine ausführbare Action und
> KWP-spezifisches Konfig-UI dürfen erst nach `VEXT-6` plus erneuter ausdrücklicher Produktfreigabe folgen.
> ~~Sprach-zu-Automation rendert im Flow-Editor (D-FLOW); die KI-Pipeline selbst liegt in P13.~~ → **entfällt ([[AD-26]]).**
## Benötigte Screens
| Screen [Route] | Kern-Inhalt | Archetyp |
@@ -31,9 +33,9 @@ Die **Nicht-Canvas-Flächen der Automation-Engine**: Übersichtsliste aller Auto
| **Execution-Detail** [`/automations/:id/executions/:exec_id`] | `summary_text` · Trigger-Payload user-lesbar · **Step-by-Step-Verlauf mit Klartext je Schritt** (Status, Input/Output, Dauer) · Dry-Run-Marker · **24h-Rückgängig-Button mit Restzeit-Anzeige** · Manuell-Retry · Resume-ab-Schritt | A3 + Timeline |
| Execution-Liste [`/automations/:id/executions`] | Letzte N Läufe · Filter (Status/Datum/Trigger-Typ) · Klick → Detail | A2 |
| Template-Katalog [`/automations/templates`] | SHK-Vorlagen + Tenant-Vorlagen nach Kategorie · je Template Beschreibung + Use-Case + Nutzungs-Anzahl · „Verwenden"-Button · „Eigenes Template aus Rule anlegen" | A2 |
| Trigger-/Aktion-Konfiguration [Knoten-Konfig-Panel-Inhalte] | Typ-abhängige Konfig-Felder je Trigger (CRM/Lead/Sales/Projekte/Email/Forms/Booking/Kalender/Zeit/Webhook) und je Action (CRM/Notification/HTTP/Task/If-Else/Delay/Loop) mit **Klartext-Labels** + Validation-Hinweisen (Pflichtfeld fehlt, unverbunden) · KWP-Push als registriert-erweiterbarer Eintrag (kein eigenes UI v1) · **werden vom Flow-Editor (D-FLOW) als Konfig-Panel eingebettet** | Compose (in D-FLOW-Panel) |
| Trigger-/Aktion-Konfiguration [Knoten-Konfig-Panel-Inhalte] | Typ-abhängige Konfig-Felder je Trigger (CRM/Lead/Sales/Projekte/Email/Forms/Booking/Kalender/Zeit/Webhook) und je Action (CRM/Notification/HTTP/Task/If-Else/Delay/Loop) mit **Klartext-Labels** + Validation-Hinweisen (Pflichtfeld fehlt, unverbunden) · KWP-Push nur als nicht ausführbarer Extension-Slot, ohne KWP-Adapter/Executor-Handler bis `VEXT-6` + erneuter Freigabe · **werden vom Flow-Editor (D-FLOW) als Konfig-Panel eingebettet** | Compose (in D-FLOW-Panel) |
*(Flow-/Node-Editor ~~+ Sprach-zu-Automation-Einstieg~~ (entfällt [[AD-26]]) + Dry-Run-Vorschau-Modal + Loop-/Rate-Schutz-Warnmodal = **D-FLOW**. Trigger-/Action-Library selbst sind Daten im Knoten-Katalog, kein eigener Screen. KWP-Push-Konfig → v2.)*
*(Flow-/Node-Editor ~~+ Sprach-zu-Automation-Einstieg~~ (entfällt [[AD-26]]) + Dry-Run-Vorschau-Modal + Loop-/Rate-Schutz-Warnmodal = **D-FLOW**. Trigger-/Action-Library selbst sind Daten im Knoten-Katalog, kein eigener Screen. KWP-Push-Konfig erst nach `VEXT-6` + erneuter Produktfreigabe.)*
## Features (muss abgedeckt sein)
- [ ] Automation-Liste (Name/Trigger/Status/Läufe/letzte Ausführung, „nur meine"-Filter)
@@ -51,8 +53,7 @@ Daten-Tabelle (sortierbar, paginiert) für Automation-/Execution-Liste; Status-P
## Quellen (granular)
- `designer-briefs/P12-automation-engine.md` (vollständiger Brief MINUS Flow-Editor/~~Sprach-Einstieg~~ (entfällt [[AD-26]])/Dry-Run-Modal/Loop-Schutz-Modal)
- `ENTITY-MODEL.md` → **Domäne 7** (Automation ~~& KI~~: AutomationRule/Step/Execution/StepExecution/Credential/Template — KI entfällt [[AD-26]])
- `ROADMAP.md` → Phase 12 · `REQUIREMENTS.md` → Modul 17 · `PHASE-SOURCES.md` → P12
- `_bmad-output/specs/M17-automation-engine.md`
- `ROADMAP.md` → Phase 12 · `REQUIREMENTS.md` → Modul 17
- Geschwister-Ticket (Editor): `D-FLOW` · Dev-Pendant: `ticket-docs/R-P12a.md`, `ticket-docs/R-P12b.md`
## Davids Delta (David füllt aus)
@@ -16,6 +16,10 @@
- **Parallel/Geschwister:** `D-KAMP` (Kampagnen-Editor + Segmente, BESPOKE) — D-P14 liefert Domain/Listen/Detail/Suppression/Templates/Unsubscribe, D-KAMP den Compose-Wizard + Segment-Builder
- **Subframe:** Pflicht je Route (A2/A3 + KPI, A6 Settings, A4-Public/Bespoke-Public für Unsubscribe)
**UX-Nachzug (2026-07-25):** `R-UX2` bündelt die freigegebene Ziel-Journey. D-P14 bleibt die
Designquelle für Setup, Listen und Reporting; AD-28 erlaubt bis zum finalen Delta eine gegen
`/forms` ausgerichtete Interim-UI.
## Was wir bauen
Die **Nicht-Kampagnen-Editor-Flächen von Email & Marketing**: die Sende-Domain-Verifikation (DKIM/SPF/DMARC + BCC-Logging-Toggle), Kampagnen-Liste + -Detail mit Tracking/Reporting (KPIs, Klick-Map, Pro-Empfänger-Tabelle), Sender + Suppression-Verwaltung, Templates und die öffentliche Unsubscribe-Page.
@@ -48,8 +52,7 @@ DNS-Record-Karten mit Copy-Button + Status-Ampel (Connection-Card-Stil aus D-P5)
## Quellen (granular)
- `designer-briefs/P14-email-marketing.md` (vollständiger Brief MINUS Kampagnen-Editor & Segmente)
- `ENTITY-MODEL.md` → **Domäne 8: Kommunikation** (TenantSendingDomain, TenantInboundAddress, Email, Campaign, OutboundEmail (+Open/Click), EmailTemplate/Sender, RecipientSegment, Unsubscribe, EmailSuppressionList)
- `ROADMAP.md` → Phase 14 · `REQUIREMENTS.md` → Modul 9/10 · `PHASE-SOURCES.md` → P14
- `_bmad-output/specs/M09-email-inbox.md` (nur Sende-Domain/Inbound/BCC — Rest v2), `M10-email-marketing.md`
- `ROADMAP.md` → Phase 14 · `REQUIREMENTS.md` → Modul 9/10
- Geschwister-Ticket (Editor): `D-KAMP` · Dev-Pendant: `ticket-docs/AK-P14a.md`, `ticket-docs/AK-P14b.md`
## Davids Delta (David füllt aus)
@@ -8,11 +8,15 @@
| **Cycle/Fenster** | W3 — Kern-Kette & Kommunikation (Demo 2) · 2026-06-30 → 2026-07-02 · Gate W3 |
| **Status** | geplant (NEU — schließt P15-Telefonie-Screen-Lücke außerhalb der Chat-UI) |
> 🎨 **design-nachzug: offen** · `AK-P15a` baut nach AD-28 bis zu Davids finalem Delta eine Interim-UI aus
> `~/ui` mit VM als Prop. Dieses Screen-Ticket ist daher kein harter Dev-Blocker.
> **Ergänzt das Bespoke-Ticket `D-CHAT`** (Real-Time-Chat-UI: Chat-Index, Channel-/Thread-Detail, Pinned/Mentions/Suche, Admin-Chat-Übersicht). **Dieses Ticket deckt den Telefonie-Teil von P15**: AirCall-Setup (Telefonie-Panel), Call-Log (Anruf-Liste), Click-to-Call und Anruf-Detail. Die Team-Chat-Screens sind **NICHT** Teil von D-P15 (→ D-CHAT).
## Abhängigkeiten & Parallelität
- **Blocked by:** `D-D0a` (App-Shell), `D-D0b` (Archetypen A2 Liste, A3 Detail, A5 Modal, A6 Connection), `D-P5` (Connection-Card-Stil für AirCall-Setup)
- **Bedient (Dev):** `AK-P15a` (Telefonie / AirCall) — der Team-Chat-Teil (`AK-P15b`) wird von `D-CHAT` bedient
- **Bedient (Dev):** finales Design für `AK-P15a` (Telefonie / AirCall); nach AD-28 kein Blocker für dessen
Interim-UI. Der Team-Chat-Teil (`AK-P15b`) wird von `D-CHAT` bedient.
- **Parallel/Geschwister:** `D-CHAT` (BESPOKE Chat-UI) — D-P15 liefert den Telefonie-Teil
- **Subframe:** Pflicht je Route (A6 Connection für Setup, A2/A3 für Call-Log/Detail, A5 Modal für Nummer-Auswahl)
@@ -24,7 +28,7 @@ Die **Telefonie-Flächen von P15**: das AirCall-Setup (Connect-Card + User-Bindi
## Benötigte Screens
| Screen [Route] | Kern-Inhalt | Archetyp |
|---|---|---|
| **AirCall-Setup** [`/settings/integrations/telephony`] | Connect-Card (Status-Ampel connecting/active/error/revoked + Klartext) · **User-Binding-Liste** (AirCall-User ↔ HiveGrid-User mit Email-Auto-Match-Vorschlag + manuelle Korrektur) · „Verbindung testen" · Trennen mit Bestätigung | A6 (Connection) |
| **AirCall-Setup** [`/settings/integrations/telephony`] | Technology-Partner-OAuth-Connect · klarer Vorabhinweis „Du musst HiveGrid-Tenant-Admin und Aircall-Company-Admin sein" · Connect-Card (connecting/active/error/revoked + Klartext) · **User-Binding-Liste** (AirCall-User ↔ HiveGrid-User mit Email-Auto-Match-Vorschlag + manuelle Korrektur) · „Verbindung testen" · Trennen/Reinstall mit Bestätigung; **keine** API-Key-, Refresh-Token- oder Ablaufzeit-Eingabe | A6 (Connection) |
| Anruf-Liste + -Detail [`/calls`] | Liste: Nummer, Richtung, Dauer, **gematchter Kontakt** (mit Confidence-Hinweis bei Soft-Match), Notiz-Snippet, verpasst-Marker · Detail: **Match-Override**, Markdown-Notiz-Editor, Aufnahme-Link · Click-to-Call-Button + eingehender-Anruf-Notification | A6 + A2/A3 |
**Eingebettet (kein eigener Screen, aber zu designen):** Click-to-Call-Buttons leben außerdem in Kontakt-/Lead-/Projekt-Detail (aus D-CRM/D-P7/D-P8) — Mehrfach-Nummern → Auswahl-Modal; `tel:`-Fallback ohne Connection.
@@ -32,7 +36,8 @@ Die **Telefonie-Flächen von P15**: das AirCall-Setup (Connect-Card + User-Bindi
*(Chat-Index/Channel-/Thread-Detail/Pinned/Mentions/Suche/Neuer-Channel/Channel-Settings/Admin-Chat-Übersicht = **D-CHAT**. HalloPetra-Adapter-UI → v2; Whisper-Diktat entfällt nach AD-26.)*
## Features (muss abgedeckt sein)
- [ ] AirCall-Connect (OAuth, Status-Diagnose) als Connection-Card mit Klartext-Status
- [ ] AirCall-Connect als Technology-Partner-OAuth-Flow mit Company-Admin-Voraussetzung und
Klartext-Status; permanenter Token wird nie angezeigt, kein Basic-Auth-/Refresh-Token-Formular
- [ ] User-Bindings mit Email-Auto-Match-Vorschlag + manuelle Zuordnung + „Verbindung testen"
- [ ] Click-to-Call aus Kontakt-/Lead-/Projekt-Detail; Mehrfach-Nummern → Auswahl-Modal; Klartext-Edge-Cases (kein Binding / keine Connection / API-Fehler / ungültige Nummer); `tel:`-Fallback
- [ ] Inbound-Anruf-Notification beim Klingeln; Auto-Match-Anzeige (Hard/Soft mit Confidence), unbekannte Nummer → Auto-Lead-Hinweis
@@ -40,13 +45,29 @@ Die **Telefonie-Flächen von P15**: das AirCall-Setup (Connect-Card + User-Bindi
- [ ] Empty/Loading/Permission-Denied/Offline-States (Klartext)
## UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)
Connection-Card (Status-Ampel connecting/active/error/revoked + Klartext, „Verbindung testen", Trennen-Bestätigung); **User-Binding-Mapping-Liste** mit Auto-Match-Vorschlag + manueller Korrektur; **Click-to-Call-Button** + Nummer-Auswahl-Modal (Mehrfach-Nummern); eingehender-Anruf-Notification; Anruf-Liste (Nummer/Richtung/Dauer/Match-Confidence/verpasst-Marker/Notiz-Snippet); **Match-Override-Picker**; Markdown-Notiz-Editor; Recording-Player-Link; Klartext-Edge-Case-Hinweise (kein Binding / keine Connection / API-Fehler / ungültige Nummer / `tel:`-Fallback); Empty-/Loading-/Permission-Denied-/Offline-States.
Connection-Card (Status-Ampel connecting/active/error/revoked + Klartext, Company-Admin-Voraussetzung,
„Verbindung testen", Reinstall/Trennen-Bestätigung, keine Credential-Eingabe); **User-Binding-Mapping-Liste** mit
Auto-Match-Vorschlag + manueller Korrektur; **Click-to-Call-Button** + Nummer-Auswahl-Modal (Mehrfach-Nummern);
eingehender-Anruf-Notification; Anruf-Liste (Nummer/Richtung/Dauer/Match-Confidence/verpasst-Marker/
Notiz-Snippet); **Match-Override-Picker**; Markdown-Notiz-Editor; Recording-Player-Link;
Klartext-Edge-Case-Hinweise (kein Aircall-Company-Admin / keine Nummer ausgewählt / kein Binding / keine
Connection / API-Fehler / ungültige Nummer / `tel:`-Fallback); Empty-/Loading-/Permission-Denied-/Offline-States.
## Contract- und Dependency-Nachzug (2026-07-15)
- Der Connect-Screen bildet den in `AK-P15a`/`EXT-08` festgelegten Technology-Partner-OAuth-Vertrag ab.
- Der Aircall-Admin wählt während der Installation die Aircall-Nummern aus, deren Events HiveGrid erhält; der
Status-/Empty-State muss „keine Nummer ausgewählt" verständlich erklären.
- Der permanente Access Token und der Webhook-Token sind reine Server-Credentials und dürfen in der UI weder
angezeigt noch editierbar sein.
- Bis Davids Delta vorliegt, ist die Interim-Baseline aus `AK-P15a` die gültige Visual-Regression-Baseline;
beim Design-Nachzug wird sie bewusst re-baselined.
## Quellen (granular)
- `designer-briefs/P15-telefonie-chat.md` (Telefonie-Teil; Chat-Teil → D-CHAT)
- `ENTITY-MODEL.md` → **Domäne 8: Kommunikation** (TelephonyConnection/UserBinding/CallSession/WebhookEvent)
- `ROADMAP.md` → Phase 15 · `REQUIREMENTS.md` → Modul 12 · `PHASE-SOURCES.md` → P15
- `_bmad-output/specs/M12-telefonie.md`
- `ROADMAP.md` → Phase 15 · `REQUIREMENTS.md` → Modul 12
- `ticket-docs/EXT-08.md` (Technology-Partner-OAuth, Live-Voraussetzungen und registrierte URLs)
- Geschwister-Ticket (Chat): `D-CHAT` · Dev-Pendant: `ticket-docs/AK-P15a.md`
## Davids Delta (David füllt aus)
@@ -54,3 +75,8 @@ Connection-Card (Status-Ampel connecting/active/error/revoked + Klartext, „Ver
- [ ] Neue UI/UX-Entscheidungen:
- [ ] Subframe-Screen-Link(s):
- [ ] Offene Fragen an Dev:
## Umsetzungs-Notiz
- **2026-07-15 · 0/6 Feature-DoD = 0 % done:** Aircall-Connect-Fläche an den verifizierten
Technology-Partner-OAuth-Vertrag und AD-28 angepasst. Kein Screen-/Delta-Punkt als umgesetzt markiert.
@@ -51,8 +51,7 @@ Connection-Card mit Status-Ampel + letzter-Sync-Zeit + verbundenem Konto-Email;
## Quellen (granular)
- `designer-briefs/P16-kalender-booking-forms-signatur.md` (vollständiger Brief MINUS Form-Builder-Canvas/öffentliches Formular & öffentliche Booking-Page/Kalender-Grid-View)
- `ENTITY-MODEL.md` → **Domäne 9** (Kalender/Booking/Forms/Signatur; `ProjektSignatureDocument`/`Signer` am Projekt-Kern — 🔴 Pivot: Signatur hängt am Projekt, nicht „Deal")
- `ROADMAP.md` → Phase 16 · `REQUIREMENTS.md` → Modul 25/06/05/07 · `PHASE-SOURCES.md` → P16
- `_bmad-output/specs/M25-calendar-sync.md`, `M06-booking.md`, `M05-form-builder.md`, `M07-angebot-signatur.md`
- `ROADMAP.md` → Phase 16 · `REQUIREMENTS.md` → Modul 25/06/05/07
- Geschwister-Tickets: `D-FORM`, `D-BOOK` · eingebettet: `D-P4` · Dev-Pendant: `ticket-docs/AK-P16a.md`–`AK-P16d.md`
## Davids Delta (David füllt aus)
@@ -27,7 +27,7 @@ Die **11 Identitäts-/Auth-Screens**: Self-Service-Signup, sicheres Login (E-Mai
| Tenant-Auswahl | Tenant-Liste (zuletzt genutzt, Suche) + „ohne Tenant"-Screen (Workspace anlegen / auf Einladung warten) | A2 |
| Session-Verwaltung [`/settings/security`] | Aktive Sessions (Gerät/Browser/IP/Standort) + Abmelden je Session + „überall abmelden" + Trust-Device-Revoke | A2/A6 |
| Profil [`/settings/profile`] | Name, Avatar, Telefon, PW ändern, 2FA (QR), Hell/Dunkel (Sprache fest DE — kein Wechsler v1) | A6 |
| Rollen-Editor [`/admin/roles`] | Rollen-Liste + Editor (Permission-Bundles + Advanced-Einzelrechte), 6 SHK-Rollen geseedet, Löschen mit Reassign | A2+A6 |
| Rollen-Editor [`/admin/roles`] | Rollen-Liste + Editor (Permission-Bundles + Advanced-Einzelrechte), fünf editierbare SHK-Tenant-Rollen angelegt und Owner ausschließlich mit globaler Rolle `Admin`, Löschen mit Reassign | A2+A6 |
| Gruppen [`/admin/groups`] | Gruppen-Liste, Bulk-Add/Remove | A2 |
| Mitarbeiter [`/admin/users`] | User-Liste + Einladungs-Modal + **Deaktivieren mit Reassign-Workflow** | A2+A5 |
| Konto löschen [`/settings/account`] | Multi-Step: Erklärung → Export → PW+2FA → Countdown · Block bei einzigem Admin | A5 |
@@ -39,7 +39,7 @@ Die **11 Identitäts-/Auth-Screens**: Self-Service-Signup, sicheres Login (E-Mai
- [ ] Login E-Mail+PW (NIST/HIBP-Breach-Block) + mCaptcha ab 3. Fehlversuch + Magic-Link
- [ ] TOTP-2FA (QR-Setup + Trust-Device)
- [ ] Session-Verwaltung (Geräte-Liste, Revoke einzeln / überall)
- [ ] Rollen-/Gruppen-Verwaltung (Bundles + Advanced), 6 SHK-Rollen, Reassign beim Deaktivieren
- [ ] Rollen-/Gruppen-Verwaltung (Bundles + Advanced), fünf editierbare SHK-Tenant-Rollen plus globale Owner-`Admin`-Rolle, Reassign beim Deaktivieren
- [ ] Konto-Löschung (DSGVO, mehrstufig, Einzig-Admin-Edge-Case)
- [ ] „keine-Berechtigung"-Zustände der UI (RLS prägt die Empty/Denied-States)
@@ -49,7 +49,6 @@ Auth-Formulare (E-Mail/PW, Stärke-Anzeige, Breach-Klartext-Block, AGB/DSGVO/AVV
## Quellen (granular)
- `designer-briefs/P02-identitaet-mandantentrennung.md` (vollständiger Brief — diese Doc ist sein Ticket-Destillat)
- `ENTITY-MODEL.md` → **Domäne 1: Identität & Mandanten** (Tenant/User/TenantUser/TenantRole/Permission/Group/Session)
- `ROADMAP.md` → Phase 2 · `REQUIREMENTS.md` → Modul 27 · `_bmad-output/specs/M27-auth-multi-tenancy.md`
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
@@ -13,12 +13,12 @@
| **Owner** | David |
| **Phase** | P20 — Billing, Onboarding & Branding (bedient `AK-P20`/`BILL-*`) |
| **Cycle/Fenster** | W4 — USP, Härtung & Launch · 2026-07-08 · Gate W4 |
| **Status** | Recut noetig |
| **Status** | Design-Nachzug offen; AK-P20-Interim-UI steht |
## Abhängigkeiten & Parallelität
- **Blocked by:** `D-D0a` (App-Shell + A1-Status-Banner-System), `D-D0b` (Archetypen A2 Liste, A6 Settings, KPI/Charts, A5 Modal)
- **Bedient (Dev):** `AK-P20` fuer Onboarding/Branding/Frozen-Vorarbeit sowie `BILL-02` bis `BILL-06` fuer neue Billing-Architektur
- **Bedient (Dev):** finale Optik fuer `AK-P20` sowie `BILL-02` bis `BILL-06`; nach AD-28 blockiert dieses Design-Ticket den Dev-Abschluss nicht mehr
- **Subframe:** Pflicht je Route (A6 Settings, KPI/Charts, A5 Modal, Banner in A1-Shell)
## Was wir bauen
@@ -31,7 +31,7 @@ Die **Billing-/Onboarding-/Branding-Flächen fuer v1**:
- Demo-Daten-Verwaltung
- Erste-Schritte-Checkliste
- Tenant-Status-Banner-System
- Hell/Dunkel-Toggle
- Light/Dark-Unterbau bleibt erhalten; der Toggle ist vorerst deaktiviert (PR #81)
> 🟡 **v1-Schnitte (verbindlich):**
> - **Billing:** Plans + Seats, read-only fuer Endkunden. Keine In-App Pricing-Tabelle, keine Upgrade-/Downgrade-UI,
@@ -40,19 +40,19 @@ Die **Billing-/Onboarding-/Branding-Flächen fuer v1**:
> Zahlung selbst laeuft ueber Mollie; Rechnung/Invoice-Record kommt aus Lago. Rechnungssteller-/Steuerfreigabe bleibt
> bis `BILL-08` offen.
> - **Onboarding:** v1 = Auto-SHK-Provisionierung beim Signup, kein Setup-Wizard.
> - **Branding:** v1 = Hell/Dunkel-Toggle, kein System-Modus, kein White-Label.
> - **Branding:** Der vorhandene Light/Dark-Unterbau bleibt erhalten, wird aber im App-/Admin-Bereich vorerst nicht angeboten (`DARK_MODE_IN_APP=false`, PR #81). Kein System-Modus, kein White-Label.
## Benötigte Screens
| Screen [Route] | Kern-Inhalt | Archetyp |
|---|---|---|
| Abo-Übersicht [`/admin/subscription`] | Plan + Seats + gebuchte Feature-Module, Status/Trial-Countdown, externer Kontakt-/Account-Manager-Hinweis, Pausieren/Kündigen falls fachlich freigegeben | A6 + KPI |
| Verbrauchs-Übersicht [`/admin/usage`] | Quota-Balken fuer Automation-Läufe und Speicher, aktueller Verbrauch vs. inklusiv, Klartext bei Limit-Erreichen; nicht als Abrechnungs-/Usage-Billing-Screen formulieren | KPI + Charts |
| Rechnungen/Zahlung [`/admin/billing`] | Lago-Invoice-Referenzen, Mollie-Payment-Status, Download-/Kontaktzustand, Zahlungsproblem-Klartext; kein Legacy-Provider-Portal/iFrame | A6 |
| Demo-Daten [`/admin/onboarding/demo-data`] | Settings-Knopf „Beispieldaten anlegen", Klartext-Liste was kommt, Demo-Liste mit Zähler + Lösch-Funktion, „Demo ausblenden"-Filter | A6 |
| Erste-Schritte-Checkliste [`/onboarding/checklist`] | Items mit Status-Häkchen, Klartext + Beschreibung, CTA-Link je Item, manuell abhakbar, dauerhaft ausblendbar, Glückwunsch bei 100 %; auch als Dashboard-Widget | A2 |
| Status-Banner-System (Shell) | Trial-Ende-3-Tage / `past_due` / `frozen` / `deletion_pending`; je eigener Klartext + Action-Button; Read-only-Toast bei blockiertem Schreib-Button | in A1-Shell (D0) |
| Hell/Dunkel-Toggle [im Profil / User-Menü] | Zwei Optionen Hell / Dunkel, sofortige Anwendung ohne Reload, flash-frei via SSR-Cookie | A6 |
| Abo-Übersicht [`/:tenant/settings/subscription`] | Plan + Seats + gebuchte Feature-Module, Status/Trial-Countdown, externer Kontakt-/Account-Manager-Hinweis, Kündigen falls fachlich freigegeben | A6 + KPI |
| Verbrauchs-Übersicht [`/:tenant/settings/usage`] | Quota-Balken fuer Automation-Läufe und Speicher, aktueller Verbrauch vs. inklusiv, Klartext bei Limit-Erreichen; nicht als Abrechnungs-/Usage-Billing-Screen formulieren | KPI + Charts |
| Rechnungen/Zahlung [`/:tenant/settings/billing`] | Lago-Invoice-Referenzen, Mollie-Payment-Status, Download-/Kontaktzustand, Zahlungsproblem-Klartext; kein Legacy-Provider-Portal/iFrame | A6 |
| Demo-Daten [`/:tenant/settings/onboarding/demo-data`] | Settings-Knopf „Beispieldaten anlegen", Klartext-Liste was kommt, Demo-Liste mit Zähler + Lösch-Funktion, „Demo ausblenden"-Filter | A6 |
| Erste-Schritte-Checkliste [`/:tenant/onboarding/checklist`] | Items mit Status-Häkchen, Klartext + Beschreibung, CTA-Link je Item, manuell abhakbar, dauerhaft ausblendbar, Glückwunsch bei 100 %; auch als Dashboard-Widget | A2 |
| Status-Banner-System (Shell) | Trial-Ende-3-Tage / `past_due` / `frozen` mit Klartext + Abo-Aktion. `deletion_pending` samt Shell-Aktion gehört zu `AK-P21`/`D-P21`. Die bestehende 423-Klartext-Hülle bleibt; der finale Read-only-Toast ist offener Design-Nachzug. | in A1-Shell (D0) |
| Light/Dark-Toggle [Profil / User-Menü] | Vorerst nicht sichtbar und im App-/Admin-Bereich deaktiviert (`DARK_MODE_IN_APP=false`); kein neuer Screen | keiner |
## Features (muss abgedeckt sein)
@@ -62,27 +62,44 @@ Die **Billing-/Onboarding-/Branding-Flächen fuer v1**:
- [ ] Rechnungen/Zahlung ohne Legacy-Provider: Lago-Invoice-Status + Mollie-Payment-Status + Klartext-Hilfe.
- [ ] Demo-Daten-Verwaltung (Anlege-Knopf mit Klartext-Inhaltsliste, Zähler + Lösch-Funktion, „Demo ausblenden"-Filter).
- [ ] Erste-Schritte-Checkliste (auto-erkannter Status, CTA-Links, manuell abhakbar/ausblendbar, Dashboard-Widget).
- [ ] Status-Banner-System (trial/past_due/frozen/deletion_pending je Klartext + Action) + Read-only-Toast.
- [ ] Hell/Dunkel-Toggle (2 Optionen, flash-frei, kein System-Modus).
- [ ] Status-Banner-System für trial/past_due/frozen finalisieren + Read-only-Toast gestalten; `deletion_pending` liegt in `D-P21`.
- [x] Light/Dark-Toggle vorerst deaktiviert; App-/Admin-Bereich bleibt bewusst hell (PR #81).
- [ ] Empty/Loading/Fehler/Permission-Denied-States (Klartext + Lösungs-Knopf).
## UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)
Plan-/Seat-/Feature-Positionsliste; Trial-Countdown-Badge; Billing-Status-Badge; Payment-Status-Badge; letzte
Invoice-/Rechnungsreferenz; Button/Link fuer Rechnung ansehen, wenn verfuegbar; Kontakt-/Account-Manager-Hinweis;
Quota-Balken fuer Automation/Speicher; Pause-/Kündigen-Button nur falls fachlich freigegeben; Demo-Daten-Anlege-Knopf;
Demo-Zähler + Lösch-Button mit Multi-Step-Confirm; „Demo ausblenden"-Filter-Toggle; Checklisten-Items mit Status-Icon
und CTA-Link + manuell-abhaken + ausblenden; Status-Banner-Stack; Read-only-Toast; Hell/Dunkel-Toggle; Empty-/Loading-/
Quota-Balken fuer Automation/Speicher; Kündigen-Button nur falls fachlich freigegeben; Demo-Daten-Anlege-Knopf;
Demo-Zähler + Lösch-Button; „Demo ausblenden"-Filter-Toggle; Checklisten-Items mit Status-Icon
und CTA-Link + manuell-abhaken + ausblenden; Status-Banner-Stack; Read-only-Toast; Empty-/Loading-/
Fehler-/Permission-Denied-States.
## Quellen (granular)
- `docs/ARCHITECTURE-DECISIONS.md` → `AD-27` (Billing-Recut) und `AD-26` (KI→MCP)
- `BILL-README.md`, `BILL-00.md` bis `BILL-08.md`
- `designer-briefs/P20-billing-onboarding-branding.md` bleibt historische Screen-Quelle, muss aber nach AD-27 recuttet werden
- `designer-briefs/P20-billing-onboarding-branding.md` ist auf AD-27 und den deaktivierten Theme-Toggle aktualisiert
- `ENTITY-MODEL.md` → Domäne 12/13, soweit nicht durch AD-27 ueberholt
- Dev-Pendant: `AK-P20.md`
## Interim-UI-Handoff (AD-28, Stand 2026-07-12)
Die Dev-Vorschau ist auf den fünf kanonischen Tenant-Routen integriert. Reine VMs liegen unter
`packages/view-models/src/billing/` und `packages/view-models/src/onboarding/`; die app-chrome-freien
Screens unter `apps/web/app/components/screens/billing/` und `.../onboarding/` erhalten ausschließlich
VM + Action-Callbacks. Das Dashboard nutzt dasselbe First-Steps-VM. Der Visual-/Hot-Swap-Nachweis ist
`packages/ui-mock/visual-baseline/ak-p20-interim.*`; der echte M016-Pixelnachweis liegt in
`tests/component/ak-p20-interim.ct.tsx` mit fünf PNG-Baselines unter `tests/component/__screenshots__/`.
Der schnelle React-Markup-Nachweis bleibt in `apps/web/app/components/screens/ak-p20-interim.visual.test.tsx`.
Nicht Teil des AK-P20-100%-Proofs sind `deletion_pending` und dessen Shell-Aktion (`AK-P21`/`D-P21`)
sowie die finale Read-only-Toast-Optik; für blockierte Root-Aktionen besteht bereits die 423-Klartext-Hülle.
Offen bleibt Davids finales Layout-/Copy-Delta inklusive Subframe-Links. Beim Nachzug werden nur die
Screen-Internals getauscht und die Interim-Baseline neu gezogen; Routen, Loader und VM-Verträge bleiben
stabil. Die Feature-Checkboxen dieses Design-Tickets bleiben deshalb bewusst offen.
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
@@ -19,18 +19,18 @@ Die **DSGVO-Lebenszyklus- und Launch-Reife-Screens (alle v1)**: Privacy-Hub, Ten
> 🟡 **v1-Schnitte (verbindlich):**
> - **DSGVO-Auskunft = manuelles Playbook v1** (Suche → Kontakt-Detail-Activity-Stream → CSV-Export → Anwalts-Vorlage → Frist-Task +25 Tage). **KEIN** automatisches Auskunfts-/Voll-Export-Tooling pro betroffener Person (→ v2). **Keinen** Auskunfts-Wizard designen — das Playbook nutzt bestehende Screens (Cmd+K, Kontakt-Detail, CSV).
> - **v1 baut:** DSGVO-ZIP-Export (User-Self + Tenant-Full, 72h-signed-URL), Tenant-Lösch-Workflow (Crypto-Shredding, 30-Tage-Grace, Slug-Confirm-Phrase), Feedback-Widget, Minimal-FAQ. AVV/Subprozessoren-Anzeige im Privacy-Hub.
> - **v1 baut:** DSGVO-ZIP-Export (User-Self + Tenant-Full, authentifizierter bis zu 72 h verfügbarer Download), Tenant-Lösch-Workflow (Crypto-Shredding, 30-Tage-Grace, Slug-Confirm-Phrase), Feedback-Widget, Minimal-FAQ. AVV/Subprozessoren-Anzeige im Privacy-Hub.
> - **PWA-only (AD-17):** alle neuen Screens mobil tauglich; **kein** App-Store-/Native-Screen (PWA-Installierbarkeit/Web-Push → v2).
## Benötigte Screens
| Screen [Route] | Kern-Inhalt | Archetyp |
|---|---|---|
| Privacy-Hub [`/admin/privacy`] | Übersicht: Export, Löschung, Subprozessoren, AVV, Privacy-Manifest-Link · Einstieg in die Sub-Bereiche | A6 + KPI |
| Tenant-Daten-Export [`/admin/privacy/export`, `/new`, `/:jobId`] | Job-Liste mit Status/Progress/Download (72h-Link) · Anstoßen mit Klartext (was, geschätzte Größe/Dauer, 7-Tage-Window) · Job-Status mit Progress | A2 + A5 |
| Tenant-Daten-Export [`/admin/privacy/export`, `/new`, `/:jobId`] | Job-Liste mit Status/Progress/Download (authentifizierte App-Route, maximal 72 h) · Anstoßen mit Klartext (was, geschätzte Größe/Dauer, Retention) · Job-Status mit Progress | A2 + A5 |
| **Tenant-Löschung** [`/admin/privacy/deletion`, `/:requestId`] | Multi-Step: Erklärung (30-Tage-Grace, Read-Only, Hard-Delete) → Export-Angebot → Legacy-Provider-Hinweis (Pro-rata) → Passwort + 2FA → **Slug als Confirm-Phrase** · Grace-Countdown mit Abbruch-Button | A5 (Wizard) |
| Subprozessoren [`/admin/privacy/subprocessors`] | Tabelle: Name, Land, EU/EEA-Marker, Zweck, Datenkategorien, DPA-Link, „aktiv seit" · Filter (EU/alle, Kategorie) · Export CSV/PDF | A2 |
| AVV [`/admin/privacy/avv`] | Aktuelle Version als PDF-Download + Akzeptanz-History (Version, Datum, Signer) · Re-Akzeptanz-Modal bei Update (Klartext-Änderungen) | A2 + A5 |
| User-Daten-Export [`/settings/account/data-export`, `/:jobId`] | Klartext was exportiert wird, Start-Button, Rate-Limit-Hinweis, Job-Status mit Download (signed-URL) | A6 |
| User-Daten-Export [`/settings/account/data-export`, `/:jobId`] | Klartext was exportiert wird, Start-Button, Rate-Limit-Hinweis, Job-Status mit authentifiziertem Download | A6 |
| Account-Löschung [`/settings/account/delete`] | Multi-Step: Erklärung → optional Daten-Export-Angebot → Passwort + 2FA → Countdown-Bestätigung (24h-Reverse-Window) · *(Detail-Logik M27 D.3)* | A5 (Wizard) |
| **Feedback-Widget** [global, klein] | Schwebender Button → Mini-Form (Kategorie Bug/Feature/Frage, Text, Screenshot-Häkchen, Rate-Limit) → landet in Admin-Support-Inbox (P19) · Erfolgs-/Fehler-Zustand | A5-klein |
| Minimal-FAQ [`/help` o. ä.] | Statische FAQ-Seite mit gruppierten Fragen/Antworten (Markdown), Suchfeld optional · kein Help-Center-Ausbau (→ v2) | A6 / statisch |
@@ -38,7 +38,7 @@ Die **DSGVO-Lebenszyklus- und Launch-Reife-Screens (alle v1)**: Privacy-Hub, Ten
*(Kein DSGVO-Auskunfts-Wizard v1 — Playbook nutzt Cmd+K-Suche + Kontakt-Detail-Activity-Stream + CSV-Export + Task aus P6/P4/P11. Admin-Support-Inbox + Subprozessor-/AVV-Verwaltung → P19. Privacy-Manifest-Inhalt = Marketing-Site.)*
## Features (muss abgedeckt sein)
- [ ] DSGVO-ZIP-Export (User-Self **und** Tenant-Full) mit Progress + 72h-signed-URL + Rate-Limit-Hinweis
- [ ] DSGVO-ZIP-Export (User-Self **und** Tenant-Full) mit Progress + authentifiziertem, ablaufendem `200`-Download + Rate-Limit-Hinweis
- [ ] Tenant-Löschung (Multi-Step-Wizard, 30-Tage-Grace + Read-Only + Abbruch, **Slug als Confirm-Phrase**, Passwort + 2FA, Legacy-Provider-Pro-rata-Hinweis)
- [ ] Account-Löschung (Multi-Step, optionales Export-Angebot, Passwort + 2FA, 24h-Reverse-Countdown)
- [ ] Subprozessoren-Liste (EU/Drittland-Marker, DPA-Link, CSV/PDF-Export) + AVV-Download + Akzeptanz-History + Re-Akzeptanz-Flow
@@ -48,13 +48,12 @@ Die **DSGVO-Lebenszyklus- und Launch-Reife-Screens (alle v1)**: Privacy-Hub, Ten
- [ ] Empty/Loading/Fehler/Permission-Denied/Offline-States (Klartext + Lösungs-Knopf)
## UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)
Export-Job-Liste mit Progress-Balken + Status-Badge + Download-Button (signed-URL, Ablauf-Hinweis); Export-Anstoß-Dialog mit Klartext-Größen-/Dauer-Schätzung; **Multi-Step-Lösch-Wizard** mit Progress; **Slug-Confirm-Phrase-Eingabe** (Tippen statt Knopf); Grace-Countdown-Banner mit Abbruch-Button; Passwort-+2FA-Bestätigungsschritt; **Subprozessor-Tabelle** mit EU/Drittland-Marker + DPA-Link + CSV/PDF-Export; AVV-PDF-Download + Akzeptanz-History-Liste + Re-Akzeptanz-Modal mit Änderungs-Klartext; Drittland-Warn-Badge; **schwebender Feedback-Button** + Mini-Form (Kategorie-Select, Textarea, Screenshot-Häkchen) mit Rate-Limit-Hinweis; **FAQ-Akkordeon** (gruppierte Fragen/Antworten, Markdown) + optionales Suchfeld; Empty-/Loading-/Fehler-/Permission-Denied-/Offline-States; mobile-first-Varianten aller Screens.
Export-Job-Liste mit Progress-Balken + Status-Badge + Download-Button (authentifizierte App-Route, Ablauf-Hinweis); Export-Anstoß-Dialog mit Klartext-Größen-/Dauer-Schätzung; **Multi-Step-Lösch-Wizard** mit Progress; **Slug-Confirm-Phrase-Eingabe** (Tippen statt Knopf); Grace-Countdown-Banner mit Abbruch-Button; Passwort-+2FA-Bestätigungsschritt; **Subprozessor-Tabelle** mit EU/Drittland-Marker + DPA-Link + CSV/PDF-Export; AVV-PDF-Download + Akzeptanz-History-Liste + Re-Akzeptanz-Modal mit Änderungs-Klartext; Drittland-Warn-Badge; **schwebender Feedback-Button** + Mini-Form (Kategorie-Select, Textarea, Screenshot-Häkchen) mit Rate-Limit-Hinweis; **FAQ-Akkordeon** (gruppierte Fragen/Antworten, Markdown) + optionales Suchfeld; Empty-/Loading-/Fehler-/Permission-Denied-/Offline-States; mobile-first-Varianten aller Screens.
## Quellen (granular)
- `designer-briefs/P21-dsgvo-launch.md` (vollständiger Brief — alle v1-Screens)
- `ENTITY-MODEL.md` → **Domäne 13** (Onboarding/Branding/DSGVO)
- `ROADMAP.md` → Phase 21 · `REQUIREMENTS.md` → Modul 35 (+ M27 D.3 User-Lösch-Verweis) · `PHASE-SOURCES.md` → P21
- `_bmad-output/specs/M35-dsgvo-export.md`
- `ROADMAP.md` → Phase 21 · `REQUIREMENTS.md` → Modul 35 (+ M27 D.3 User-Lösch-Verweis)
- Dev-Pendant: `ticket-docs/AK-P21.md`
## Davids Delta (David füllt aus)
@@ -46,8 +46,7 @@ Audit-Daten-Tabelle (server-paginiert) mit Actor-Kind-Marker (User/Automation/~~
## Quellen (granular)
- `designer-briefs/P03-querschnitts-oberflaechen.md` (vollständiger Brief — diese Doc ist sein Ticket-Destillat)
- `ENTITY-MODEL.md` → **Domäne 2: Querschnitt** (AuditEntry, Notification, NotificationPreference, NotificationDevice; i18n = Felder, keine Tabelle)
- `ROADMAP.md` → Phase 3 · `REQUIREMENTS.md` → Modul 21/22/30 (`REQ-audit-retention-export`, `-audit-permissions`, `-notification-versand-pipeline`, `-i18n-outbound`) · `PHASE-SOURCES.md` → Phase 3
- `_bmad-output/specs/M21-audit-log.md`, `M22-notifications.md`, `M30-i18n.md` (Oberflächen-Teile; Service-Kerne liegen in P1)
- `ROADMAP.md` → Phase 3 · `REQUIREMENTS.md` → Modul 21/22/30 (`REQ-audit-retention-export`, `-audit-permissions`, `-notification-versand-pipeline`, `-i18n-outbound`) · Milestones:
- Dev-Pendant: `ticket-docs/AK-P3.md`
## Davids Delta (David füllt aus)
@@ -47,8 +47,7 @@ Daten-Tabelle mit Tabelle/Grid-Umschalter, Vorschau-Thumbnail, sortierbaren Spal
## Quellen (granular)
- `designer-briefs/P04-files-tasks.md` (vollständiger Brief — diese Doc ist sein Ticket-Destillat)
- `ENTITY-MODEL.md` → **Domäne 3** (File, FileChunk, FileUploadProgress, FileEntityLink, Task, TaskWatcher)
- `ROADMAP.md` → Phase 4 · `REQUIREMENTS.md` → Modul 23/26 (`REQ-files-datenmodell`, `-upload-preview`, `-tasks-datenmodell`, `-tasks-reminder-archivierung`) · `PHASE-SOURCES.md` → Phase 4
- `_bmad-output/specs/M23-files.md`, `M26-tasks.md`
- `ROADMAP.md` → Phase 4 · `REQUIREMENTS.md` → Modul 23/26 (`REQ-files-datenmodell`, `-upload-preview`, `-tasks-datenmodell`, `-tasks-reminder-archivierung`) · Milestones:
- Dev-Pendant: `ticket-docs/AK-P4a.md`, `ticket-docs/AK-P4b.md`
## Davids Delta (David füllt aus)
@@ -17,7 +17,7 @@
- **Subframe:** Pflicht je Route (A6 Settings/Connection-Kit, A5 Wizard, A2 Liste)
## Was wir bauen
Die **generische Katalog-/Wizard-/Sync-UI** des einen typsicheren Integrations-Frameworks: App-Katalog, Connection-Verwaltung (mehrere Connections pro App pro Tenant), Connect-Wizard (OAuth2-Redirect **und** API-Key-Eingabe), Connection-Health-Monitoring mit Klartext-Diagnostik und Sync-History/-Detail. **Recut-Hinweis:** KWP = `DataConnection type='rest-api'` (API-Key) — **kein `kwpsync.exe`-Windows-Client-Flow** (v1-Connect-Typen in der UI: OAuth2 + API-Key; `windows_client` bleibt im Modell ohne UI).
Die **generische Katalog-/Wizard-/Sync-UI** des einen typsicheren Integrations-Frameworks: App-Katalog, Connection-Verwaltung (mehrere Connections pro App pro Tenant), Connect-Wizard (OAuth2-Redirect **und** API-Key-Eingabe), Connection-Health-Monitoring mit Klartext-Diagnostik und Sync-History/-Detail. **KWP-Recut 2026-07-12:** KWP nutzt die OAuth2/PKCE-Variante mit Kundenkürzel und dynamischer Relay-Auflösung; kein API-Key-Feld und kein `kwpsync.exe`-Windows-Client-Flow. Die API-Key-Variante bleibt für andere Provider bestehen.
## Benötigte Screens
| Screen [Route] | Kern-Inhalt | Archetyp |
@@ -45,8 +45,7 @@ App-Katalog als Karten-Grid gruppiert nach Kategorie (je Karte App-Logo + Beschr
## Quellen (granular)
- `designer-briefs/P05-apps-engine-integrations-framework.md` (vollständiger Brief — Recut KWP→v2)
- `ENTITY-MODEL.md` → **Domäne 4** (App, DataConnection, AppSyncRun, AppSyncRunLog, AppSyncItem)
- `ROADMAP.md` → Phase 5 · `REQUIREMENTS.md` → Modul 33a (`REQ-apps-engine-datenmodell`, `-apps-engine-lifecycle`) · `PHASE-SOURCES.md` → Phase 5
- `_bmad-output/specs/M33a-apps-engine.md` (⚠ Drei-Komponenten-/`kwpsync.exe`-Architektur ist NICHT zu bauen — Scope-Schnitt #12)
- `ROADMAP.md` → Phase 5 · `REQUIREMENTS.md` → Modul 33a (`REQ-apps-engine-datenmodell`, `-apps-engine-lifecycle`) · Milestones:
- Dev-Pendant: `ticket-docs/R-P5.md`
## Davids Delta (David füllt aus)
@@ -17,7 +17,7 @@
## Was wir bauen
Den **Lead-Triage-Arbeitsplatz**: eingehende Leads aus allen Quellen (Form, eingehende E-Mail, AirCall-Inbound, manueller Eintrag, Custom-Quellen) landen automatisch angelegt in einer Inbox, sind spam-geschützt, auswertbar und per Workflow weiterverarbeitbar.
> 🔴 **Pivot-Vorrang (AD-20):** Es gilt das `ENTITY-MODEL.md`, nicht die pre-Pivot-SCREEN-MAP. Das **Lead-Promotion-Modal (4-Optionen) entfällt** — es wird **Lead → Projekt**. Ein Lead trägt **`weiterverarbeitung_freigabe` (ja/nein/unklar)**; bei „ja" entsteht ein `Projekt` (kein Contact-Promotion), Lead-Daten werden vererbt (`konvertiert_projekt_id`), der **Kontakt wird separat verknüpft** (`verknuepfter_kontakt_id` — neu oder bestehend). Status-Enum bleibt `new/qualified/converted/lost/spam`.
> 🔴 **Pivot-Vorrang (AD-20):** Es gilt das `ENTITY-MODEL.md`. Das **Lead-Promotion-Modal (4-Optionen) entfällt** — es wird **Lead → Projekt**. Ein Lead trägt **`weiterverarbeitung_freigabe` (ja/nein/unklar)**; bei „ja" entsteht ein `Projekt` (kein Contact-Promotion), Lead-Daten werden vererbt (`konvertiert_projekt_id`), der **Kontakt wird separat verknüpft** (`verknuepfter_kontakt_id` — neu oder bestehend). Status-Enum bleibt `new/qualified/converted/lost/spam`.
## Benötigte Screens
| Screen [Route] | Kern-Inhalt | Archetyp |
@@ -48,8 +48,7 @@ Triage-Daten-Tabelle/Karten-Umschalter (sortierbar, cursor-paginiert 50/Page), F
## Quellen (granular)
- `designer-briefs/P07-lead-inbox.md` (vollständiger Brief — 🔴 Pivot-Vorrang AD-20)
- `ENTITY-MODEL.md` → **Domäne 5: Projekt-zentrischer CRM-Kern** (Lead-Zeile + Lead→Projekt) — 🔴 **Pivot-Vorrang (AD-20)**: kein Promotion-Modal, `weiterverarbeitung_freigabe`, `konvertiert_projekt_id`/`verknuepfter_kontakt_id`
- `ROADMAP.md` → Phase 7 (+ Pivot-Note) · `REQUIREMENTS.md` → `REQ-lead-*` · `PHASE-SOURCES.md` → P7
- `_bmad-output/specs/M02-lead-inbox.md` (⚠ teils pre-pivot: „promovieren zu Contact"/4-Optionen-Modal überholt — ENTITY-MODEL hat Vorrang)
- `ROADMAP.md` → Phase 7 (+ Pivot-Note) · `REQUIREMENTS.md` → `REQ-lead-*`
- Dev-Pendant: `ticket-docs/R-P7.md`
## Davids Delta (David füllt aus)
@@ -30,7 +30,7 @@ Die **Nicht-Kanban-Flächen des `Projekt`-Kerns + der Pipeline-Engine**: die Mus
| Lost-Reasons [`/admin/pipelines/lost-reasons`] | Liste (Name, Anzahl verknüpfter Projekte, Status) · Add/Edit/Archive (kein Hard-Delete — Reporting) · SHK-Default 5 Reasons geseedet | A2 |
| Forecast/KPI-Quellen (Widgets in P11) | Datenquellen/Berechnungen: Pipeline-Forecast (Volumen × Win-%), realisierter Umsatz, KPIs pro Verantwortlichem, Stage-Conversion-Rates, Lost-Reason-Verteilung · Aggregat-Cache · (kein eigener Screen — Widgets leben in P11/D-DASH; hier: Datenform + Charts-Bausteine) | KPI-Kit/Charts |
*(Pipeline-Kanban = **D-KANBAN** (BESPOKE). Plantafel + Rechnungen/Checklisten/Abnahme-Sub-Areas → P9. „Deal-Liste/Deal-Detail" aus SCREEN-MAP entfällt — projekt-zentrische Routen oben.)*
*(Pipeline-Kanban = **D-KANBAN** (BESPOKE). Plantafel + Rechnungen/Checklisten/Abnahme-Sub-Areas → P9. Alle Routen bleiben projekt-zentrisch.)*
## Features (muss abgedeckt sein)
- [ ] EIN `Projekt`-Kern (typisierte Superset-Tabelle) mit fortlaufenden Projekt-Nummern (HiveNumberSeq)
@@ -48,8 +48,7 @@ Daten-Tabelle (sortierbar, paginiert, Spalten-Konfig, CSV), Pipeline-Spalte + -F
## Quellen (granular)
- `designer-briefs/P08-projekt-pipelines-kern.md` (vollständiger Brief MINUS Kanban — 🔴 Pivot-Vorrang AD-20)
- `ENTITY-MODEL.md` → **Domäne 5** (Projekt-Kern + Pipeline/Stage/FieldConfig/Access) + Kern-Ketten-Diagramm + Modellierungs-Fragen 3/4 — 🔴 **Pivot-Vorrang (AD-20)**
- `ROADMAP.md` → Phase 8 (+ Pivot-Note) · `REQUIREMENTS.md` → `REQ-projekt-kern-datenmodell` / `REQ-pipeline-rechte-config` / `REQ-projekt-kanban-listen-view` / `REQ-projekt-forecast-kpis` · `PHASE-SOURCES.md` → P8
- `_bmad-output/specs/M03-sales-pipeline.md` (⚠ „Deal"/„won_handoff_project_id" = Projekt-Kern bzw. Pipeline-Wechsel)
- `ROADMAP.md` → Phase 8 (+ Pivot-Note) · `REQUIREMENTS.md` → `REQ-projekt-kern-datenmodell` / `REQ-pipeline-rechte-config` / `REQ-projekt-kanban-listen-view` / `REQ-projekt-forecast-kpis`
- Geschwister-Ticket (Kanban): `D-KANBAN` · Dev-Pendant: `ticket-docs/R-P8a.md`, `ticket-docs/R-P8b.md`
## Davids Delta (David füllt aus)
@@ -57,3 +56,51 @@ Daten-Tabelle (sortierbar, paginiert, Spalten-Konfig, CSV), Pipeline-Spalte + -F
- [ ] Neue UI/UX-Entscheidungen:
- [ ] Subframe-Screen-Link(s):
- [ ] Offene Fragen an Dev:
---
## Umsetzungs-Notiz — Subframe-Baseline (2026-07-28, Akeshan)
Davids Handoff `D-P8 + D-KANBAN` (2026-07-28, Repo `Hivegrid-Wireframes`, lokaler
Stand = Source of Truth) hat den Flow `WF-P8 Pipelines` auf **23 Subframe-Seiten**
neu geschnitten. Alle 23 sind inventarisiert; 10 davon wurden in diesem Durchgang
neu gebaut, inklusive des fehlenden Datenmodells.
**Davids Delta — beantwortet:**
- [x] Überschriebene/geänderte Spec-Punkte: `S01b` und `S02a` entfallen; `S02` ist
kein Karteikarten-Platzhalter mehr, sondern ein voller Editor mit Feldgruppen,
Schnellaktionsleiste und rechter Pipeline-Seitenleiste.
- [x] Neue UI/UX-Entscheidungen: M04 ist **statusgetrieben**, kein Button — das
Erreichen der letzten Stage öffnet die Übergabe. M03 hängt am Rechtsklick auf
die Kanban-Karte. Bei „Verloren" ist der Grund Pflicht, die Notiz optional.
S00 = normale Board-Auswahl, S07 = Admin-Verwaltung.
- [x] Subframe-Screen-Link(s): Flow `d9dfdec6-7236-4386-8514-697b9e0f0bc4`,
Projekt `f023064a5ca0`. Einzel-Links stehen in den Screen-Dateien des
Wireframe-Repos.
- [ ] Offene Fragen an Dev → jetzt **Fragen an David**, siehe unten.
**Rückfragen an David (blockieren nichts, ändern aber Verhalten):**
1. **M04, abgewählte Begleitdaten.** Der Screen zeigt nicht, was mit Notizen/Dateien/
Aufgaben/Terminen passiert, die *nicht* angehakt sind. Umgesetzt ist die
nicht-destruktive Lesart: die Auswahl ist das Übergabe-Paket, abgewählte Daten
bleiben unverändert am Projekt. Falls sie tatsächlich verschwinden sollen, ist das
eine kleine Änderung im Service — bitte bestätigen.
2. **Nachfolge-Pipeline.** M04 braucht ein „welche Pipeline kommt danach", kein Screen
zeigt dieses Control. Gebaut in den Board-Einstellungen. Falls es woanders hin
soll, bitte melden.
3. **S05-Feldtypen.** Prozent, Datum + Uhrzeit, Person/Team, Adresse und Link fehlen
im Backend und wurden bewusst nicht angeboten (sie bräuchten eine
modulübergreifende Enum-Erweiterung im CRM). Sind sie für v1 nötig?
**Stand der 23 Screens:**
| Gruppe | Screens | Stand |
|---|---|---|
| Neu gebaut | M04, M04a, M04b, M04c, S02-A, S02-N, S02-T, S02-F, S05, M05 | ✅ inkl. Datenmodell |
| Erweitert | S02 | ✅ Feldgruppen + Projektkontaktdaten |
| Funktional integriert, 1:1-Nachzug offen | S00, S01, S01a, S03, S03a, S04, S06, S07, S07-D, S07a, M01, M03 | 🟡 |
Detail-Proof, Rest-Delta und die technischen Entscheidungen stehen in der
Querverweis-Notiz in [`R-P8a.md`](./R-P8a.md).
@@ -48,8 +48,7 @@ Sub-Area-Tabs/Sektionen am Projekt-Detail; ProjektMitglieder-Liste mit Rollen-Ba
## Quellen (granular)
- `designer-briefs/P09-projekt-pipelines-auftrag.md` (vollständiger Brief MINUS Plantafel & Abnahme-Workflow/Liste — 🔴 Pivot-Vorrang AD-20)
- `ENTITY-MODEL.md` → **Domäne 5** (Sub-Areas am Projekt: Rechnung/Termin/Checkliste/AbnahmeProtokoll/AbnahmeSignatur/ProjektMitglied/ProjektExternesFeld) + Kern-Ketten-Diagramm — 🔴 **Pivot-Vorrang (AD-20)**
- `ROADMAP.md` → Phase 9 (+ Pivot-Note) · `REQUIREMENTS.md` → `REQ-projekt-*` · `PHASE-SOURCES.md` → P9
- `_bmad-output/specs/M04-auftragspipeline.md` (⚠ „AcceptanceProtocol/ProjectPipeline/source_deal_id-Snapshot" = Sub-Area am gemeinsamen `Projekt`-Kern)
- `ROADMAP.md` → Phase 9 (+ Pivot-Note) · `REQUIREMENTS.md` → `REQ-projekt-*`
- Geschwister-Tickets: `D-PLAN` (Plantafel), `D-ABN` (Abnahme) · Basis: `D-P8` · Dev-Pendant: `ticket-docs/R-P9a.md`, `ticket-docs/R-P9b.md`
## Davids Delta (David füllt aus)
@@ -41,7 +41,6 @@ Plantafel-Raster (Y=MA, X=Zeit, Zeitraum-Switcher Tag/Woche/Monat); Drag&Drop-/R
## Quellen (granular)
- `designer-briefs/P09-projekt-pipelines-auftrag.md` → §Benötigte Screens „📱 Plantafel" (NUR dieser Screen) + zugehörige Features/UI-Elemente
- `ENTITY-MODEL.md` → **Domäne 5** (ScheduleEntry/ProjektMitglied am Projekt-Kern; Pivot: kein separates Project-Objekt) — **Pivot-Vorrang**
- `SCREEN-MAP.md` → §4 Plantafel · `DESIGNER-FIRST-PLAYBOOK.md` → §3 Rang 3 · `ROADMAP.md` → Phase 9 · `_bmad-output/specs/M04-auftragspipeline.md`
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
@@ -8,7 +8,7 @@
| **Cycle/Fenster** | W1 — Fundament & Identität · 2026-06-16 → fällig 2026-06-16 |
| **Status** | geplant |
> ℹ️ **Kein Designer-Phasen-Brief:** Dieses Ticket sitzt nicht auf einem `PXX.md`, sondern liefert die **Marketing-Website-Screens + die Brand-/Design-Tokens** für Web **und** App. Quellen sind der Snapshot-DoD, `SCREEN-MAP.md` (Website) und das `HANDOUT-DAVID.md` (Website). Die Tokens müssen mit `D-D0a` (App-Tokens) konsistent gehalten werden.
> ℹ️ **Kein Designer-Phasen-Brief:** Dieses Ticket sitzt nicht auf einem `PXX.md`, sondern liefert die **Marketing-Website-Screens + die Brand-/Design-Tokens** für Web **und** App. Die Tokens müssen mit `D-D0a` (App-Tokens) konsistent gehalten werden.
## Abhängigkeiten & Parallelität
- **Blocked by:** — (Fundament, kein Vorgänger; sehr früh fällig)
@@ -43,8 +43,7 @@ Hero-Sektion mit CTA; Feature-Sektions-Bausteine (Text + Bild/Illustration); Soc
## Quellen (granular)
- Plane-Snapshot `D-WEB` → DoD: „Landing/Features/Pricing-Teaser/Demo-Formular" + „Brand-/Design-Tokens (Web + App)"
- `SCREEN-MAP.md` → Website
- `handouts/david/HANDOUT-DAVID.md` → Website
- diese Bau-Spec → Website-Screens
- Konsistenz-Anker: `D-D0a` (App-Tokens)
## Davids Delta (David füllt aus)
@@ -0,0 +1,145 @@
# DB-BASELINE · Prisma-Migrationshistorie konsolidieren
| | |
|---|---|
| **Typ** | Dev/Infra |
| **Owner** | Raffael |
| **Phase** | Querschnitt / Datenbankbetrieb |
| **Cycle/Fenster** | Sofortiger Wartungsschnitt |
| **Status** | Done |
## Abhängigkeiten & Parallelität
- **Blocked by:** keine. Der vollständige Main-Migrationsstand muss vor dem Schnitt reproduzierbar und schema-paritätisch sein.
- **Blocks:** keine fachlichen Tickets. Während des PRs gilt jedoch ein operativer Schema-Freeze; parallele Schema-Branches müssen nach dem Merge auf die Baseline rebasen und ihre Merge-Migration neu erzeugen.
- **Plane-Prüfung:** Beide Richtungen wurden am 2026-07-22 gelesen. Es gibt keine bestehende `blocked-by`-/`blocks`-Relation für diesen Wartungsschnitt.
- **Auswirkung auf Abhängige:** Keine Prisma-Modelle und keine Fachverträge ändern sich. Geändert werden ausschließlich die aktive Migrationshistorie, ihr Deploy-Cutover und die zugehörigen Verifikationsverträge.
## Was wir bauen
Die historische Prisma-Migrationskette wird in eine einzelne, aus einer leeren PostgreSQL-Datenbank reproduzierbare
HiveGrid-Baseline überführt. Die Baseline bildet nicht nur das deklarative Prisma-Schema ab, sondern auch alle
PostgreSQL-spezifischen Laufzeitverträge wie RLS-Policies, Security-Definer-Funktionen, Rollen-Grants, Extensions,
partielle Indizes und Constraints.
Bestehende Datenbanken übernehmen die neue Baseline genau einmal über `prisma migrate resolve --applied`, nachdem
ein fail-closed Check die vollständig angewendete Legacy-Historie einschließlich Checksums bestätigt hat. Frische
Datenbanken dürfen die Baseline nicht überspringen und wenden sie regulär mit `prisma migrate deploy` an.
## Benötigte Screens
Keine UI-Arbeit.
## Definition of Done
- [x] Eine einzelne Baseline-Migration stellt den aktuellen Main-Datenbankzustand aus einer leeren PostgreSQL-16-Datenbank her.
- [x] Prisma-Schema, RLS-Policies, Security-Definer-Funktionen, Grants, Extensions, Constraints und Indizes entsprechen katalogseitig dem Endzustand der bisherigen vollständigen Migrationskette.
- [x] Ein versioniertes Legacy-Manifest erfasst alle ersetzten Migrationen mit SHA-256-Checksum; die aktive Legacy-Kette ist aus `prisma/migrations/` entfernt und bleibt über ein checksum-verifiziertes Audit-Archiv sowie Git rekonstruierbar.
- [x] Der One-shot-Migrator übernimmt die Baseline nur bei einer vollständig erfolgreichen kanonischen Legacy-Historie oder bei Git-belegten historischen Checksums mit zusätzlicher Live-Schema-/Katalogparität; frische, bereits baselinierte, partielle oder unbekannt abweichende Datenbanken werden korrekt behandelt beziehungsweise fail-closed abgewiesen.
- [x] Der bestehende Migrator-Rollen-, Secret- und Runtime-Env-Vertrag bleibt unverändert scharf; Staging und Produktion verwenden weiterhin den kurzlebigen `DIRECT_URL`-Migrator vor jedem Rollout.
- [x] Automatisierte Tests decken Fresh-DB, Legacy-Adoption, wiederholten No-op, partielle/abweichende Historie und den vollständigen Alt-vs.-Baseline-Katalogvergleich ab.
- [x] `prisma validate`, Migrations-Parity, Tenant-Policy-Contract, RLS-Release-Readiness, strikter RLS-Live-Test, Docker-/Deploy-Verträge sowie die allgemeine Commit-/Push-Checkliste sind grün.
- [x] Rollback, Merge-Reihenfolge und der einmalige Staging-/Produktions-Cutover sind dokumentiert; PRs #215 und #218 sind nach gemeinsamem Sign-off mit grüner CI gemergt und die Staging-Adoption ist grün.
**Fortschritt:** `DB-BASELINE`: 8/8 DoD = 100 % done. Offen: 0 Punkte.
## Technische Bausteine
- `prisma/migrations/00000000000000_hivegrid_baseline/migration.sql`
- Legacy-Migrationsmanifest unter `prisma/`
- Fail-closed Adoption vor `prisma migrate deploy` im bestehenden One-shot-Migrator
- Unit-Tests für die History-Klassifikation und den Prisma-CLI-Aufruf
- Docker-basierter Alt-vs.-Baseline-Replay mit normalisiertem PostgreSQL-Katalogvergleich
- Anpassung der RLS-Generator-/Freeze-Verträge auf die neue Baseline
## Rollback-Pfad
- **Vor Merge:** Branch/PR verwerfen; produktive Datenbanken bleiben unverändert.
- **Nach Merge, vor Baseline-Adoption:** Merge-Commit revertieren und die Legacy-Migrationsordner aus Git wiederherstellen.
- **Nach erfolgreicher Adoption:** Keine DDL wird durch die Adoption ausgeführt. Bei einem Code-Rollback werden die Legacy-Migrationsordner wiederhergestellt; der zusätzliche erfolgreiche Baseline-Eintrag kann bestehen bleiben, solange kein Legacy-Image erneut `migrate deploy` ausführt. Der konkrete Rollback wird zuerst in Staging geprobt.
- **Nach Anwendung auf einer frischen Datenbank:** Datenbank verwerfen und aus Backup/Seed neu aufbauen. Die Baseline ist forward-only; ein produktives `DROP SCHEMA` ist kein zulässiger Rollback.
## Quellen
- `AGENTS.md` §Prisma-Schema & Migrationen, §RLS, §Ticket-Treue
- `docs/AGENT-CHECKLIST.md`
- `docs/deployment.md` §One-shot-Migrator
- `docs/security/RLS-HARDENING-2026-07-13.md`
- `infra/LESSONS.md` §9
- Prisma-Dokumentation: Baselining und Squashing migrations
## Umsetzungsnotiz
2026-07-22: Ticket als eigenständiger, fachmodell-neutraler Wartungsschnitt angelegt. Ausgangs-Pre-Flight auf
`origin/main` ist grün (`pnpm typecheck`; `pnpm test`: 999 Testdateien, 7.135 Tests bestanden). Der aktuelle
Main-Stand enthält 195 aktive Migrationen mit 42.140 SQL-Zeilen. Die Implementierung erfolgt isoliert auf
`chore/prisma-baseline-20260722`.
2026-07-22: Die 195 Legacy-Migrationen wurden durch
`00000000000000_hivegrid_baseline` ersetzt. Die Baseline enthält 293 Tabellen, 844 Policies, 92 Funktionen,
293 `ENABLE ROW LEVEL SECURITY`, 293 `FORCE ROW LEVEL SECURITY`, 2 Extensions sowie die migrations-eigenen
SHK-Onboarding- und Customer-Portal-Feature-Flag-Referenzdaten. Baseline-SHA-256:
`f39a3e6800356d3199b1274a492721217c12c0c5cafcf3f648b3050868c3abbe`. Das versionierte Audit-Archiv
`prisma/baseline-legacy-migrations.tar.gz` hat SHA-256
`0571766bcd2bc7d4424706617ad9a495c2b11d6b3e8f9511510dc710716d6093`; sein Manifest pinnt alle 195
Migrationen einzeln.
Proof: Fresh-DB-Deploy, checksum-verifizierte Legacy-Adoption, wiederholter No-op und der vollständige
PostgreSQL-Katalog- und Referenzdatenvergleich sind grün. `prisma validate`, Migrations-Parity,
Tenant-Policy-Contract (293/293), RLS-Release-Readiness (246/246), strikter RLS-Live-Test,
Docker-Baseline (399 Checks), Docker-Non-Root, Deploy-/CI-/Source-/Doku-Verträge, Typecheck und Lint sind grün.
Core-Tests: 1.001 Testdateien / 7.155 Tests bestanden; `@hivegrid/db`: 94 Testdateien / 854 Tests bestanden.
Rollback, Merge-Reihenfolge und Cutover sind in `docs/ops/prisma-baseline.md` dokumentiert. Lokal sind 7/8
DoD erfüllt; offen bleibt ausschließlich PR plus grüne Remote-CI vor dem gemeinsamen Merge-Sign-off.
2026-07-22: PR [#215](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/pulls/215) gegen `main` ist
eröffnet. Die Remote-CI für Implementierungs-Commit `66b1b1b68` ist mit 13/13 Checks grün, einschließlich
Database Checks mit Baseline-Äquivalenz und Live-RLS sowie Docker Smoke, Typecheck/Tests, Coverage und
Build/Bundle. Damit sind 8/8 DoD erfüllt. Der PR bleibt bis zum gemeinsamen Sign-off ungemergt.
2026-07-22: PR #215 wurde nach erneut grüner CI als Squash nach `main` gemergt. Der erste Staging-Deploy
stoppte erwartungsgemäß vor `migrate resolve` und vor jeder Datenbankmutation, weil die bestehende
Staging-Historie mindestens eine früher deployte, später im Git geänderte Migration mit ihrer damaligen
Prüfsumme enthält. Der Hotfix auf `fix/prisma-baseline-staging-adoption-20260722` pinnt alle zehn im
Git belegten historischen Prüfsummenvarianten samt Quellcommit. Eine solche Variante wird nur übernommen,
wenn ein Live-`prisma migrate diff` keine Schemaabweichung findet und die zusätzlichen PostgreSQL-
Katalogverträge für Audit-FKs, tenant-gebundenes Booking sowie Security-Definer-Owner/ACLs grün sind.
Lokaler Proof des Hotfixes: Der vollständige Äquivalenzlauf spielte alle 195 Migrationen ein, simulierte
alle acht betroffenen Migrationen mit den zehn historischen Ledger-Checksums und bestätigte danach
Adoption, wiederholten No-op sowie vollständige Katalog- und Referenzdatenäquivalenz. Zusätzlich grün:
`prisma validate`, Migrations-Parity, Tenant-Policy-Contract (293/293), RLS-Release-Readiness (246/246),
strikter RLS-Live-Test, Docker-/Deploy-/CI-/Source-/Doku-Verträge, Typecheck, Lint sowie 1.017 Testdateien
mit 7.341 bestandenen Tests. `DB-BASELINE`: 8/8 DoD = 100 % done; operativ offen ist nur der erneute
Remote-CI- und Staging-Deploy-Nachweis vor dem Ticketabschluss.
2026-07-22: Im ersten Lauf von Hotfix-PR #218 stoppte ausschließlich der SHK-Migrationsfixture, weil der
parallele Runner-Cold-Start von PostgreSQL das alte 30-Sekunden-Fenster überschritt; der Container war laut
Runner-Log unmittelbar danach gesund. Der Fixture nutzt nun wie der benachbarte Identity-/Invite-Check einen
auf 90 Sekunden begrenzten TCP-`pg_isready`-Probe. Der neue statische Vertragstest und der reale lokale
SHK-Clean-/Legacy-Upgrade-Lauf (9/9 Tests) sind grün. Es gab keine Datenbank- oder Anwendungsänderung.
2026-07-22: Hotfix-PR [#218](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/pulls/218) wurde mit
Merge-Commit `ce748f10b` nach `main` übernommen. Der exakt rebasierte PR-Head `bfbae1b98` bestand CI-Run
[11057](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/11057) mit 11/11 grünen Checks.
Der erste Post-Merge-Lauf übernahm die Baseline auf Staging nach Prüfung von drei Git-belegten historischen
Checksum-Varianten sowie Live-Schema- und sicherheitskritischer Katalogparität; anschließend meldete Prisma
keine ausstehenden Migrationen. Ein nachgelagerter, transienter Controller-Pre-Stop-Health-Probe brach den
Rollout sicher ab und stellte den vorherigen Release wieder her. Der idempotente Deploy-Re-Run
[11058, Job 46077](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/11058/jobs/46077)
erkannte die bereits verbuchte Baseline, bestätigte erneut keine ausstehenden Migrationen und rollte alle
Staging-Ressourcen einschließlich des revisionsgebundenen Portal-Domain-Controllers erfolgreich aus.
`DB-BASELINE`: 8/8 DoD = 100 % done; 0 Punkte offen.
2026-07-23: Die erste Forward-Migration nach der konsolidierten Baseline (`kwp_project_inbound`) hat einen
Reihenfolgefehler im One-shot-Migrator sichtbar gemacht: Ein Vergleich der bestehenden Legacy-Datenbank mit
dem aktuellen Prisma-Schema muss die noch nicht angewandte Forward-Migration zwangsläufig als Drift melden.
Der fail-closed Ablauf ist deshalb jetzt explizit `Rollen-Probe → Legacy-Historie und
sicherheitskritische Varianten-Kataloge prüfen → Baseline übernehmen → prisma migrate deploy → aktuelles
Live-Schema prüfen → Permission-Katalog synchronisieren`. Unbekannte Legacy-Checksums und abweichende
sicherheitskritische Kataloge stoppen weiterhin vor jeder Adoption; eine Abweichung vom aktuellen
Prisma-Schema stoppt nach den atomaren Forward-Migrationen und vor Permission-Sync beziehungsweise Rollout.
Der vollständige Docker-Nachweis spielte alle 195 Legacy-Migrationen ein, simulierte die acht historischen
Checksum-Varianten, adoptierte die Baseline, wandte `kwp_project_inbound` an und bestätigte anschließend
`No difference detected`; Fresh-DB und Legacy-DB blieben vollständig katalogäquivalent. Die Änderung betrifft
keine Prisma-Modelle oder Fachverträge. `DB-BASELINE`: 8/8 DoD = 100 % done; 0 Punkte offen.
@@ -0,0 +1,280 @@
<!-- markdownlint-disable MD013 MD060 -->
# DESKTOP-1 · Electron-Client produktionsreif fertigstellen
| Feld | Wert |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Typ** | Dev (Desktop / Release) |
| **Owner** | Raffael |
| **Phase** | Nachzug außerhalb der aktuellen v1/v2-Kernkette |
| **Cycle/Fenster** | Backlog · bewusst später |
| **Status** | Backlog · Prototyp 6/12 DoD = 50 % done |
| **Plane** | [HIVEGRID-249](https://project.tool-ctrl.de/toolctrl/projects/35d0d968-8ab3-40cc-97b8-b81d917dc5df/issues/64897557-907f-4f7c-8431-0fe352ab66df) |
## Entscheidung und aktueller Kontext
Der User hat am 2026-08-03 einen ersten Desktop-Prototyp für macOS, Windows und
Linux ausdrücklich beauftragt und anschließend entschieden, die
Produktionsreife als Backlog-Nachzug zu parken. Der Desktop-Client bleibt eine
dünne Electron-Hülle um die bestehende HiveGrid-Web-App. Es entsteht keine
zweite UI-, Fachlogik-, Auth- oder Datenschicht.
Die Desktop-Entscheidung ist im lokalen Prototyp-Branch als **AD-33** vorbereitet.
Sie ändert **AD-17 nicht**: Mobile bleibt responsive Web/PWA-only. Vor einem
Code-Merge müssen der AD-33-Eintrag und die zugehörige operative Klarstellung in
`AGENTS.md` gemeinsam mit dem Desktop-Paket geprüft und übernommen werden. Damit
wird die noch auf `main` vorhandene allgemeine Anti-Listen-Formulierung nicht
stillschweigend durch diese Ticket-Doc gelockert.
**Wichtig:** Der Prototyp-Branch und seine Commits existieren zum Zeitpunkt
dieser Doc nur lokal und wurden noch nicht gepusht.
- Worktree:
`/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud-feat-desktop-client-prototype`
- Branch: `feat/desktop-client-prototype`
- Basis: `origin/main@b1f14d63e5252e0a70029ece139591b98e26d3b8`
- Paket-Dokumentation im Prototyp-Branch: `apps/desktop/README.md`
- Lokale Build-Artefakte: `artifacts/desktop/` (gitignored)
## Abhängigkeiten & Parallelität
- **blocked-by:** Keine Plane- oder Ticket-Abhängigkeit hinterlegt.
- **blocks:** Keine Plane- oder Ticket-Abhängigkeit hinterlegt.
- **Externe Voraussetzungen vor Release:** Apple Developer ID und
Notarisierungszugang, Windows-Authenticode-Zertifikat sowie ausführbare
macOS-/Windows-/Linux-Release-Runner oder gleichwertige kontrollierte
Build-Maschinen. Verfügbarkeit und Owner werden beim Wiederaufnehmen geprüft;
sie sind aktuell nicht als formale Plane-Blocker modelliert.
- Die Arbeit ist unabhängig von Prisma, RLS, Entity Model und der fachlichen
v1/v2-Kernkette. Es gibt keine Schema- oder Migrationsänderung.
- Web-App, Auth und fachliche Screens bleiben alleinige Produktquelle. Änderungen
an diesen Flächen gehören in ihre jeweiligen Tickets, nicht in `DESKTOP-1`.
- Mobile und App-Store-Scope bleiben außerhalb dieses Tickets. Desktop-Store-
Distribution darf nur nach eigener Produktentscheidung ergänzt werden.
## Was wir bauen
Der vorhandene Prototyp wird zu einem reproduzierbar veröffentlichten,
signierten und updatefähigen Desktop-Client für:
- macOS Apple Silicon und Intel,
- Windows x64,
- Linux x64.
Der Client lädt ausschließlich die freigegebene HiveGrid-Web-Origin. Native
Zuständigkeit bleibt auf sicheren Web-Container, Lifecycle, Single Instance,
Fensterzustand, Menüs, Deep Links, Badge, Offline-Fallback und Updates begrenzt.
Der Produktionsnachzug umfasst außerdem:
- native Signierung, Notarisierung und installierbare Paketformate,
- reproduzierbare Gitea-Release-Jobs auf den Zielplattformen,
- unveränderliche Release-Artefakte und Prüfsummen,
- einen signierten Update-Kanal mit echtem Upgrade-/Rollback-Drill,
- native Smoke-Tests auf allen Zielbetriebssystemen,
- Installations-, Release- und Rollback-Dokumentation.
## Benötigte Screens
Keine neue Fach- oder Subframe-Oberfläche. Die bestehende Web-App bleibt die
vollständige sichtbare Produktsurface.
Native beziehungsweise lokale Systemflächen sind auf Folgendes begrenzt:
| Fläche | Inhalt |
| ---------------- | ---------------------------------------------------------------------- |
| App-Menü | Zurück/Vorwärts, Reload, Zoom, Vollbild, Update-Prüfung, Hilfe |
| Offline-Fallback | Klartextstatus, Ziel-Origin und erneuter Verbindungsversuch |
| Update-Dialog | Update verfügbar, Downloadstatus, Neustart jetzt/später |
| Betriebssystem | Installer, Signatur-/Notarisierungsdialoge und Deep-Link-Registrierung |
Die finale Web-Optik wird nicht im Electron-Paket dupliziert. Es gibt keinen
`design-nachzug` und keinen eigenen Subframe-Screen für dieses Ticket.
## Definition of Done
- [x] **Dünne Sicherheitsarchitektur:** `apps/desktop` lädt nur die bestehende
Web-App; Node-Integration und Webviews sind aus, Context Isolation,
Sandbox, Web Security, enge Navigation und validierte Preload-IPC sind
aktiv. AD-17 bleibt für Mobile unverändert.
- [x] **Native Desktop-Grundfunktionen:** Single Instance, Fensterzustand,
native Menüs, Deep Links, Badge, sichere externe Links und Offline-Fallback
sind implementiert.
- [x] **Vier reproduzierbare Prototyp-Builds:** macOS arm64/x64, Windows x64 und
Linux x64 werden aus demselben Workspace gebaut; ASAR-Integrität,
gehärtete Electron-Fuses und HiveGrid-Branding sind enthalten.
- [x] **Update-Grundlage fail-closed:** macOS/Windows verwenden Electrons
`autoUpdater`, Linux einen manuellen Downloadpfad; ohne konfigurierte
Release-URL bleiben automatische Updates deaktiviert. Öffentliche URLs
sind build-time einbettbar und zur Laufzeit überschreibbar.
- [x] **Automatisierte Qualität:** Desktop-Typecheck, Unit-Tests, Build und
echter Electron-E2E sind vorhanden; Root-Docker- und Gitea-CI-Verträge
berücksichtigen das Workspace-Paket.
- [x] **Lokaler macOS-Proof:** Der finale arm64-Prototyp startet nativ, stellt
das App-Menü bereit und beendet sich über den normalen App-Lifecycle;
Binärformat, ZIP-Integrität, lokale Signatur und Fuses sind geprüft.
- [ ] **Branch gesichert und integriert:** Der lokale Prototyp-Branch ist
gepusht, per PR geprüft und mit normalem Merge-Commit in `main` integriert;
AD-33, `AGENTS.md` und diese Ticket-Doc sind widerspruchsfrei.
- [ ] **Echte Zielsystem-Smokes:** Installation, Start, Login, Session-Restore,
Navigation, Deep Link, Offline-Fallback und Deinstallation sind auf
Windows x64 und Linux x64 sowie erneut auf einem produktionssignierten
macOS-Build geprüft.
- [ ] **Produktionspakete signiert:** macOS besitzt Developer-ID-Signatur und
Notarisierung; Windows besitzt Authenticode und einen update-kompatiblen
Installer; Linux besitzt mindestens AppImage sowie die entschiedenen
DEB-/RPM-Pakete. Keine produktive Warnung wird durch Test-Flags umgangen.
- [ ] **Release-Automation:** Native Gitea-Runner bauen aus einem Tag
unveränderliche Artefakte, veröffentlichen SHA-256-Prüfsummen und hängen
sie an einen versionierten Gitea-Release. Secrets bleiben ausschließlich
im jeweiligen Runner-/Signing-Kontext.
- [ ] **Update- und Rollback-Drill:** Ein signierter Build aktualisiert sich über
den veröffentlichten Kanal auf die nächste Version; Feed, Signatur,
Neustart, fehlgeschlagener Download und Rückkehr zum letzten freigegebenen
Artefakt sind auf macOS und Windows bewiesen. Linux folgt dem dokumentierten
Paketmanager-/Downloadpfad.
- [ ] **Release-Abnahme:** Security-Review, Lizenz-/SBOM-Prüfung, Installations-,
Release- und Rollback-Runbook sowie abschließender UAT sind dokumentiert;
Ticket-Doc und Plane enthalten den Proof.
**Fortschritt: 6/12 DoD = 50 % done · 6 Punkte offen · aktuell keine formale
`blocked-by`-Kante; das Ticket ist bewusst zurückgestellt.**
## DoD-Proof und Nicht-genug-Kriterien
| DoD | Fertigkeitskriterium | Proof | Zählt nicht als fertig |
| --- | --------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------ |
| 1 | Sicherheitsoptionen und IPC-Grenze im Release-Build aktiv | Unit-/E2E-Test und Fuse-Ausgabe | nur ein `BrowserWindow`, das eine URL lädt |
| 2 | Alle begrenzten nativen Flows funktionieren | Desktop-Tests und manueller Smoke | Menüpunkte ohne funktionalen Handler |
| 3 | vier portable Test-Bundles reproduzierbar | Paketbefehle, `file`, `unzip -t`, Fuses | nur der Host-Mac-Build |
| 4 | kein Feed führt sicher zu deaktivierten Updates | Unit-Test und Status-API | ungeprüfte oder hartkodierte Download-URL |
| 5 | Desktop ist Teil der lokalen/CI-Qualitätsverträge | grüne fokussierte Tests und CI-Verifier | nur ein lokaler manueller Start |
| 6 | finaler arm64-Build startet und beendet sauber | nativer macOS-Smoke | nur Dev-Electron über Playwright |
| 7 | Commits sind remote geprüft und normal gemerged | PR, grüne CI, Merge-Commit | lokaler Branch oder Squash-Merge |
| 8 | Nutzerflows laufen auf echten Zielsystemen | UAT-Protokoll je OS | Cross-Packaging auf macOS |
| 9 | OS-Vertrauenskette und Installer sind produktiv | Signatur-, Notarisierungs- und Installer-Proof | ad-hoc signiertes ZIP |
| 10 | Tag erzeugt veröffentlichte immutable Releases | grüner Release-Run, Assets, Prüfsummen | manuell erzeugtes `artifacts/`-Verzeichnis |
| 11 | echtes N→N+1-Update und Rollback bewiesen | Feed-/Installer-/Rollback-Protokoll | Unit-Test des Update-Controllers |
| 12 | Übergabe ist operativ vollständig | Review, SBOM, Runbooks, UAT-Sign-off | README ohne ausgeführten Release-Proof |
## Technische Bausteine
- `apps/desktop/src/main.ts`: Lifecycle und gehärtetes `BrowserWindow`.
- `apps/desktop/src/preload.ts` und `ipc.ts`: kleine, validierte Native-Bridge.
- `apps/desktop/src/url-policy.ts`: Trusted-Origin-, Deep-Link- und
External-Navigation-Vertrag.
- `apps/desktop/src/updates.ts` und `update-settings.ts`: Update-Modi,
Statusmodell und öffentliche Release-Konfiguration.
- `apps/desktop/scripts/build.mjs`: deterministischer Main-/Preload-Build.
- `apps/desktop/scripts/package.mjs`: Plattformpakete, Branding, ASAR,
Signatur-Hook und Fuses.
- `apps/desktop/scripts/e2e.mjs`: echter Electron-E2E gegen einen lokalen
Testserver.
- `scripts/ci/run-quality-groups.sh`: Desktop-Qualitätsgruppe nach den
bestehenden bounded Core-Gruppen.
Öffentliche Konfiguration:
- `HIVEGRID_DESKTOP_WEB_URL`: Ziel-Web-App; im Paket nur HTTPS.
- `HIVEGRID_DESKTOP_UPDATE_URL`: macOS-/Windows-Update-Feed.
- `HIVEGRID_DESKTOP_DOWNLOAD_URL`: manueller Linux-/Fallback-Download.
- `HIVEGRID_DESKTOP_MAC_SIGN_IDENTITY`: macOS-Signing-Identität beim Build.
Keine Signing-Zertifikate, Passwörter, PATs oder Update-Secrets werden in Git,
Plane, Build-Logs oder Artefakt-Metadaten geschrieben.
## Vorhandener Prototyp-Proof (2026-08-03)
Atomare lokale Commits:
1. `0e7c8e906` · `feat(desktop): add secure Electron shell`
2. `df496a297` · `feat(desktop): add native lifecycle and updates`
3. `5c5cc3af3` · `build(desktop): package branded cross-platform clients`
4. `6d9f322c8` · `feat(desktop): embed public update configuration`
5. `006d319f2` · `ci(desktop): enforce client quality gates`
6. `8b9071fa3` · `docs(desktop): record client release contract`
7. `1f66d3562` · `fix(desktop): guard shutdown navigation race`
Prüfstand:
- `pnpm typecheck` und `pnpm lint` grün.
- `pnpm test`: 1.194 Testdateien und 8.325 Tests grün; 60 bewusst
deaktivierte Integrationstests übersprungen.
- Desktop: 44/44 Unit-Tests, Typecheck, Build und echter Electron-E2E auf
macOS arm64 grün.
- Alle vier ZIPs bestehen `unzip -t`; Binärformate sind Mach-O arm64/x64,
PE32+ x64 und ELF x64.
- Beide Mac-Prototypen bestehen die lokale ad-hoc-Signaturprüfung; alle vier
Builds besitzen die erwarteten gehärteten Fuses.
- Der native Mac-Smoke nutzte für den wiederholt ad-hoc signierten lokalen
Build Chromiums isolierten Test-Keychain. Das ist kein Release-Flag und darf
in produktiven Startpfaden nicht verwendet werden; eine stabile Developer-ID-
Signatur muss den regulären Keychain-Pfad beweisen.
Lokale SHA-256-Prüfsummen des letzten Prototyp-Builds:
- macOS arm64: `252bb76b248a378106a8f7e071a61cd806cc1e8928589c50ec3a82a9d5edc3b1`
- macOS x64: `05c23c17db3a051fab472bc54507158ccd2a7d7dba775884f2ca36781d8c6137`
- Linux x64: `3fd15c50439750f9b8bb1f8b97c449e46d6002855770d16dc5169284d8d61be1`
- Windows x64: `1ccb839161f66c00511b02c8e658b51b5a5429fd69f6eb22769648bbf4ca04ea`
Die Prüfsummen sind nur lokaler Proof. Sie werden nicht als veröffentlichter
Release-Vertrag behandelt, weil `artifacts/desktop/` gitignored ist.
## Verifikation vor Commit, Push und Release
Fokussiert:
```bash
pnpm --filter @hivegrid/desktop typecheck
pnpm --filter @hivegrid/desktop test
pnpm --filter @hivegrid/desktop build
pnpm --filter @hivegrid/desktop test:e2e
```
Vor Push/PR zusätzlich die vollständige `docs/AGENT-CHECKLIST.md` und alle
betroffenen CI-/Docker-Verifier. Vor Release außerdem:
- ZIP-/Installer-Integrität und SHA-256,
- Fuse- und ASAR-Integritätsprüfung,
- native Signatur- und Notarisierungsprüfung,
- SBOM-/Lizenz- und Production-Audit,
- echter Installations-/Update-/Rollback-Smoke je Zielbetriebssystem.
## Rollback
- Vor dem Merge: den Desktop-PR schließen; die bestehende Web-App bleibt
unverändert nutzbar.
- Nach dem Merge ohne Release: die Desktop-Commits normal reverten. Es gibt
keine Datenbankmigration und keinen serverseitigen Zustand zurückzusetzen.
- Nach Release: Update-Feed auf das letzte freigegebene, weiterhin signierte
Artefakt zurücksetzen und dieses erneut als aktuelle Version veröffentlichen.
Bereits installierte Clients werden nicht durch Löschen alter Assets
unbrauchbar gemacht.
- Zertifikate oder Secrets werden nur nach ausdrücklichem Auftrag rotiert.
## Quellen
- Plane: `HIVEGRID-249` / `DESKTOP-1`.
- User-Auftrag und ausdrückliche Desktop-Freigabe vom 2026-08-03.
- Lokaler Branch `feat/desktop-client-prototype`, insbesondere
`apps/desktop/README.md` und der dort vorbereitete AD-33-Nachzug.
- `AGENTS.md` · Arbeitsmodus, Ticket-Treue, Desktop-/Mobile-Grenzen und
operative Checkliste.
- [Electron Security](https://www.electronjs.org/docs/latest/tutorial/security)
- [Electron Updates](https://www.electronjs.org/docs/latest/tutorial/updates)
- [Electron Distribution](https://www.electronjs.org/docs/latest/tutorial/application-distribution)
- [Electron Code Signing](https://www.electronjs.org/docs/latest/tutorial/code-signing)
## Umsetzungs-Notiz
### 2026-08-03 · Prototyp gebaut und Produktionsnachzug geparkt
Der sichere Desktop-Prototyp wurde in sieben atomaren lokalen Commits erstellt,
für vier Plattform-/Architekturziele paketiert und auf macOS arm64 automatisiert
sowie nativ geprüft. Plane-Ticket `HIVEGRID-249` wurde im Backlog mit Priorität
Low und Owner Raffael angelegt. Der User hat entschieden, die Produktionsreife
erst nach anderen Aufgaben fortzusetzen.
**DESKTOP-1: 6/12 DoD = 50 % done · 6 Punkte offen · 0 formale Plane-Blocker ·
bewusst zurückgestellt.**
@@ -32,3 +32,9 @@ Ohne verifizierte, aufgewärmte Sende-Domain landen Mails im Spam.
- AD-6 auf `Accepted` gelockt (Mailjet als EU-Provider, MailerSend verworfen) — Commit `b5502f28`.
- Plane: Kommentar gesetzt, Ticket auf Done.
- Follow-up (nicht blockierend): MailerSend-`include` aus SPF entfernen; DMARC nach Warm-up auf `quarantine`.
## Abhängigkeits-Nachzug (2026-08-01)
`MAIL-01` korrigiert ausschließlich die Mailjet-`CustomID`-Grenze für lange,
idempotente Signup-Replay-Keys. Der hier verifizierte Sender-, SPF-, DKIM-,
DMARC- und Providervertrag bleibt unverändert.
@@ -5,7 +5,7 @@
| **Typ** | Setup (External) |
| **Owner** | Raffael |
| **Cycle/Fenster** | W1 — Fundament & Identität · fällig 2026-06-17 · Gate W1 |
| **Status** | geplant |
| **Status** | Done · **2/2 DoD = 100 % done** |
## Was zu tun ist
- Beide **OAuth-Callback-URLs** (PKCE) an KWP melden:
@@ -29,7 +29,10 @@ KWP ist das erste v2-Modul; die API-Anbindung in v2-P10 braucht registrierte Cal
## Umsetzung (2026-06-21, Owner Raffael)
- Mail an Noah/Geerkens-IT raus: beide OAuth-Callback-URLs (`app.` + `staging-app.hivegrid.de/integrations/kwp/oauth/callback`, Auth-Code + PKCE, Tenant im `state`) gemeldet, bnWin.net-Update auf 8.1 N3 angestoßen.
- Pfad auf `/integrations/kwp/...` aktualisiert (INTEGRATION-CONTRACTS §3, abgelöstes `/api/apps/kwp/...`).
- **Außerhalb dieses Tickets:** der eigentliche KWP-API-Zugang (Hersteller ~19.07.) + die Anbindung laufen im v2-Modul → [[VEXT-1]] / [[VR-P32a]]. KWP-Bestätigung wird dort nachgehalten.
- **Außerhalb dieses Tickets:** KWP-Runtime-Proof + read-only Anbindung laufen im v2-Modul → [[VEXT-1]] /
[[VR-P32a]]. Freischaltungsdaten, Runtime-Scopes und Dauer-Refresh sind dort bewiesen; `VR-P32a` ist im
read-only Scope 5/5 Done. Ein späterer Write-/Auftrag-Create-Vertrag wird ausschließlich in `VEXT-6`
nachgehalten und blockiert die initiale Anbindung nicht.
- **Nachtrag 2026-06-25:** KWP-Zugang ist **eingetroffen — ~3–4 Wochen früher** als ~19.07. (OAuth2/Keycloak `kwp-federated`, Mandant `geerkens2`). Details + Vertrags-Fragen-Stand in [[VEXT-1]]. Bleibt v2-Scope.
- **Nachtrag 2026-06-28 (Callback-Host-Korrektur):** Bei einem Review fiel auf, dass die an KWP gemeldete **Staging**-Callback-URL `https://staging-app.hivegrid.de/...` zum Meldezeitpunkt **nicht als Host existierte** — der reale Staging-Host hieß `staging-web.hivegrid.de` (DNS-Lookup: `staging-app` = NXDOMAIN, `staging-web`/`staging-api` → 46.225.5.93). Die gemeldete URL hätte bei KWP-OAuth ins Leere gezeigt. **Behoben (statt KWP eine neue URL zu melden, den Host an die gemeldete URL angepasst):** Cloudflare A-Record `staging-app.hivegrid.de` → 46.225.5.93 (proxied=false, analog `staging-web`/`-api`) + die Coolify-Domain der App `hivegrid-web` (zentrales Coolify auf `control`) von `staging-web` auf `staging-app` umgestellt + Redeploy (LE-Cert). Der obsolete `staging-web` wurde entfernt (Cloudflare-DNS gelöscht + nicht mehr in der Coolify-Route). Die an KWP/Noah gemeldete URL ist damit gültig — **keine erneute Meldung nötig**.
@@ -1,39 +1,107 @@
# EXT-08 · AirCall-Konto + API + Webhooks (kein Sandbox — an P15 gekoppelt)
# EXT-08 · AirCall Technology-Partner-OAuth + Live-Zugang (keine Sandbox)
| | |
|---|---|
| **Typ** | Setup (External) |
| **Owner** | Raffael |
| **Cycle/Fenster** | direkt vor **P15-Bau** (AK-P15a, start 2026-06-30) · fällig 2026-06-30 |
| **Status** | geplant (erst kurz vor P15 ausführen) |
| **Cycle/Fenster** | Just-in-time vor der Live-Verifikation von `AK-P15a` |
| **Status** | geplant · blockiert nur den Live-Proof, nicht den Fixture-first-Bau |
## Wichtig: AirCall hat KEINE Sandbox (geprüft 2026-06-21)
Offizielle AirCall-Doku: *„Currently, Aircall does not offer a dedicated sandbox environment for testing."*
Anders als Legacy-Provider/Google/PandaDoc gibt es **kein gratis Sandbox-Testen**:
- Getestet wird im **echten/Trial-Account** mit **Test-Usern + Test-Nummern** (als „TEST" labeln, danach löschen).
- **Test-Nummern + Seats kosten ggf. Geld** → mit AirCall-Account-Manager Konditionen klären.
- AirCall-Trial = nur **7 Tage** → läuft lange vor P15 ab, wenn man jetzt auf Vorrat anlegt.
> **Vertragskorrektur 2026-07-15:** HiveGrid ist eine Integration für mehrere Aircall-Companies und verwendet
> deshalb den offiziellen **Technology-Partner-OAuth-Flow**. `api_id`/`api_token` per Basic Auth ist laut
> Aircall nur für eine Integration in das eigene Aircall-Konto gedacht und ist **nicht** der HiveGrid-Vertrag.
→ **Konsequenz: NICHT jetzt auf Vorrat aufsetzen.** Konto + Test-Nummern + API-Key + Webhooks **direkt vor dem
P15-Bau** (AK-P15a, ab 2026-06-30) anlegen, damit keine ungenutzten Nummern bezahlt werden.
## Verifizierter Aircall-Vertrag
## Was zu tun ist (kurz vor P15)
- **AirCall-Konto** (Trial oder bezahlt) anlegen; falls nötig Test-Nummer(n) buchen (kostenpflichtig).
- **API-Key** (`api_id`/`api_token`, Basic-Auth) erzeugen, in Coolify-Env (staging/prod) hinterlegen.
- **Webhooks** konfigurieren (Call-Events/Click-to-Dial) auf `staging-api`/`api`, HMAC-Signaturprüfung + Rate-Limit.
- Aircall bietet **keine dedizierte Sandbox**. Live-Verifikation erfolgt in einem echten Partner-/Trial-Account
mit Test-Usern und ausgewählten Test-Nummern; Seats/Nummern können kostenpflichtig sein.
- Aircall stellt für die Technology-Partner-App `client_id` und `client_secret` bereit. Diese sind
**umgebungsweite App-Secrets**, keine Tenant-Credentials, und liegen ausschließlich in den jeweiligen
Coolify-Secrets für Staging/Produktion.
- Der Authorization-Code ist zehn Minuten gültig und wird über `POST https://api.aircall.io/v1/oauth/token`
gegen einen **permanenten Bearer-`access_token`** getauscht. Der Token läuft laut Aircall-Vertrag nicht ab;
es gibt für diesen Flow **keinen Refresh-Token und keinen Refresh-Worker**.
- Installationen sind auf Aircall-Company-Ebene. Die Person, die in HiveGrid als Tenant-Admin verbindet, muss
deshalb zugleich **Admin der betreffenden Aircall-Company** sein. Andernfalls kann sie die App nicht
autorisieren.
- Nach dem Token-Tausch legt HiveGrid den Webhook über `POST https://api.aircall.io/v1/webhooks` an. Aircall
liefert dabei einen eindeutigen Webhook-`token`, der in jedem Event mitgesendet und zur Connection-Zuordnung
geprüft wird. Aircall liefert für diesen Vertrag **keine HMAC-Signatur**; HMAC darf daher nicht vorgetäuscht
werden. Pflicht bleiben TLS, Payload-/Event-Allowlist, Token-Abgleich, Idempotenz und Rate-Limit.
- Bei OAuth wählt der Aircall-Company-Admin die Aircall-Nummern aus, deren Call-Events an die Integration gehen.
Offizielle Quellen: [Aircall OAuth für Technology Partners](https://developer.aircall.io/tutorials/how-aircall-oauth-flow-works/),
[Aircall API Reference](https://developer.aircall.io/api-references/) und
[Aircall Sandbox](https://support.aircall.io/en-gb/articles/23108614387485-Aircall-Sandbox).
## Registrierte URLs
| Zweck | Produktion | Staging |
|---|---|---|
| Aircall `install_uri` | `https://app.hivegrid.de/integrations/aircall/oauth/install` | `https://staging-app.hivegrid.de/integrations/aircall/oauth/install` |
| Aircall `redirect_uri` / Callback | `https://app.hivegrid.de/integrations/aircall/oauth/callback` | `https://staging-app.hivegrid.de/integrations/aircall/oauth/callback` |
| automatisch angelegter Webhook | `https://api.hivegrid.de/v1/webhooks/telephony/aircall` | `https://staging-api.hivegrid.de/v1/webhooks/telephony/aircall` |
Der `install_uri` erzeugt einen kurzlebigen, signierten OAuth-`state` (Tenant, initiierender User, Nonce) und
leitet mit `client_id`, festem `redirect_uri`, `response_type=code`, `scope=public_api` und `state` an
`https://dashboard.aircall.io/oauth/authorize` weiter. Der Callback prüft den `state`; Tenant-Identität steht
weder im Callback- noch im Webhook-Pfad.
### Getrennter Admin-Sales-Vertrag für VA-P28d
| Zweck | Produktion | Staging |
|---|---|---|
| Aircall Admin-Connect | `https://admin.hivegrid.de/sales/settings/telephony/connect/aircall` | `https://staging-admin.hivegrid.de/sales/settings/telephony/connect/aircall` |
| Aircall Admin-Callback | `https://admin.hivegrid.de/sales/settings/telephony/callback/aircall` | `https://staging-admin.hivegrid.de/sales/settings/telephony/callback/aircall` |
| Admin-Sales-Webhook | `https://api.hivegrid.de/v1/webhooks/admin-telephony/aircall` | `https://staging-api.hivegrid.de/v1/webhooks/admin-telephony/aircall` |
Der Admin-Sales-Flow bindet OAuth-State, Connection und Call-Daten ausschließlich an einen
aktiven `AdminUser` und `AdminDataConnection`. Er verwendet weder Tenant-IDs noch Tenant-RLS
oder die produktiven Tenant-Redirects. Das Aircall-Partner-App-Setup muss beide klar getrennten
URL-Sätze registrieren; der Live-Proof für `VA-P28d` bleibt bis dahin extern blockiert.
## Was extern zu tun ist
- Technology-Partner-App bei Aircall mit den Install-/Callback-URLs registrieren und `client_id`/
`client_secret` getrennt für die vorgesehenen Umgebungen sicher bereitstellen.
- Aircall-Konto (Trial oder bezahlt) mit Aircall-Company-Admin, Test-Usern und gegebenenfalls kostenpflichtigen
Test-Nummern bereitstellen.
- Die HiveGrid-App durch den Company-Admin installieren, Nummern auswählen und den permanenten Access Token via
Callback erzeugen; danach `/v1/ping`, User-Liste und Click-to-Call live prüfen.
- Den Webhook automatisiert anlegen und mindestens die vereinbarten Call-Events live gegen Staging verifizieren.
## Fixture-first vs. Live-Verifikation
`AK-P15a` beginnt **fixture-first**: OAuth-State/Callback, Token-Tausch, API-Mapping, Webhook-Normalisierung,
Idempotenz und Fehlerpfade werden gegen versionierte Fixtures und HTTP-Fakes gebaut. `EXT-08` blockiert nur den
abschließenden Live-Proof mit echtem Aircall-Account, echter Nummernauswahl, Callback, Call und Webhook. Ohne
diesen Proof bleibt `AK-P15a` unter 100 %, der restliche Bau ist aber nicht blockiert.
## Warum / was es blockt
Telefonie-Integration (Call-Events, Click-to-Dial) braucht API-Zugang + Webhooks.
- **Blocks:** P15 (Telefonie, **AK-P15a**)
- **Blocks:** ausschließlich die **Live-Verifikationspunkte** von `AK-P15a` und `VA-P28d`,
nicht deren Fixture-first-Umsetzung.
## Abhängigkeiten
- **blocked-by:** — (aber bewusst an P15-Timing gekoppelt; kostenpflichtig, daher Just-in-time)
- **blocks:** P15 (AK-P15a)
- **blocked-by:** Aircall Technology-Partner-Onboarding und Verfügbarkeit eines Aircall-Company-Admins mit
Test-User/-Nummer (extern)
- **blocks:** `AK-P15a` Live-Proof
- **Auswirkung auf Abhängige (2026-07-15):** `AK-P15a` wird fixture-first entblockt; `D-P15` ist nach AD-28
kein Dev-Blocker. `AK-P15b` (Chat) erhält durch den Aircall-Auth-Vertrag keine technische Änderung.
- **Auswirkung auf Abhängige (2026-07-24):** `VA-P28d` verwendet einen separaten, tenantlosen
Admin-Sales-OAuth-/Webhook-Vertrag. Der Codebau bleibt fixture-first entblockt; nur der
kontrollierte Admin-Live-Proof wartet auf die zusätzliche Partner-App-Registrierung.
## Definition of Done
- [ ] AirCall-Konto + (ggf. kostenpflichtige) Test-Nummer(n)
- [ ] API-Key in Coolify-Env (staging/prod)
- [ ] Webhooks konfiguriert (HMAC + Rate-Limit)
- [ ] Technology-Partner-App/OAuth-Credentials für die benötigten Umgebungen vorhanden; Install-/Callback-URLs
sind bei Aircall registriert
- [ ] Aircall-Company-Admin + Test-User/-Nummer vorhanden und Nummernauswahl im Install-Flow durchgeführt
- [ ] Permanenter Access Token per Callback erzeugt, verschlüsselt gespeichert und mit `/v1/ping` live geprüft
- [ ] Webhook per OAuth-Bearer angelegt; Webhook-Token-Zuordnung, Rate-Limit und mindestens ein echtes Call-Event
auf Staging nachgewiesen
## Hinweis
„Sandbox" aus dem alten Ticket-Titel gestrichen — existiert bei AirCall nicht. Quelle: AirCall Help Center „Aircall Sandbox" + developer.aircall.io.
## Umsetzungs-Notiz
- **2026-07-15 · 0/4 DoD = 0 % done:** Planungsvertrag auf Technology-Partner-OAuth korrigiert. Keine DoD als
umgesetzt markiert; Live-Zugang und Live-Proof bleiben extern offen.
@@ -10,7 +10,7 @@
## Entscheidung (2026-06-21) — siehe [[AD-25]]
Default = HiveGrid baut die Signatur (Angebote/Aufträge/Abnahmen) **selbst als gehärtete SES** — souverän, günstig,
rechtlich ausreichend. **PandaDoc bleibt als optionale BYOK-Anbindung** ([[EXT-17]]): Tenant mit eigenem Account
trägt seinen Key ein (Opt-in). Abweichung vom Pflichtenheft (V.4.4 nannte PandaDoc als *den* Provider) → [[AD-25]].
trägt seinen Key ein (Opt-in). AD-25 ersetzt die frühere Annahme, PandaDoc sei der alleinige Provider.
**Yousign/Skribble/DocuSeal fallen weg; PandaDoc nur noch als Opt-in-Adapter, nicht als Default.**
**Warum (Kurzfassung, Details in AD-25):**
@@ -30,7 +30,7 @@ Diese Anträge brauchen Wochen Vorlauf, daher schon in W3 anstoßen, obwohl sie
**Stand:** 1/3 DoD = ~33 % done. Selbst machbarer Repo-/Planungsanteil ist erledigt; 2/3 DoD bleiben extern blockiert.
**Proof / Abgleich:**
- PWA-only ist durch AD-17 und `.planning/EXTERNALS-CHECKLISTE.md` bestätigt: kein Google Play, kein FCM/APNs, Push später über Web-Push/VAPID.
- PWA-only ist durch AD-17 bestätigt: kein Google Play, kein FCM/APNs, Push später über Web-Push/VAPID.
- `EXT-10` hat bereits die v1-Google-Cloud-OAuth-App mit Calendar-Scope ohne Gmail-Scopes angelegt; `EXT-13` bleibt der separate v2-Vorlauf für Gmail-Restricted-Scopes.
- `VA-P23`/`VD-P23` hängen fachlich an diesem Vorlauf: Gmail/Outlook-Postfach-Sync mit Gmail restricted scopes und Microsoft Graph Subscriptions.
@@ -1,11 +1,11 @@
# EXT-16 · Mollie Live + Billing Production Prep
| | |
|---|---|
| **Typ** | Setup (External) |
| **Owner** | Raffael |
| | |
| ----------------- | ------------------------------------------------ |
| **Typ** | Setup (External) |
| **Owner** | Raffael |
| **Cycle/Fenster** | Backlog · erst nach Sandbox-Proof und Firmierung |
| **Status** | Backlog |
| **Status** | Backlog |
## Recut-Hinweis
@@ -37,11 +37,21 @@ und Rechnungssteller-/Steuerfreigabe zusammenstehen.
- [ ] Mollie-Live-Profil verifiziert.
- [ ] Live-Keys und Webhook-Setup ausserhalb des Repos hinterlegt bzw. dokumentiert.
- [ ] Eigene Lago-Production-Instanz geplant oder provisioniert, getrennt von Staging.
- [x] Eigene Lago-Production-Instanz geplant oder provisioniert, getrennt von Staging.
- [ ] Rechnungssteller-/Steuer-/Impressumsdaten freigegeben.
- [ ] Backup, Restore, Monitoring und Rollback fuer Billing-Prod dokumentiert.
- [x] Backup, Restore, Monitoring und Rollback fuer Billing-Prod dokumentiert.
**Fortschritt:** `EXT-16`: 2/5 DoD = 40 % done. Offen: Mollie-Live-Profil,
Live-Keys/Webhooks und Rechnungssteller-/Steuer-/Impressumsfreigabe. Alle drei
offenen Punkte sind extern blockiert; 0 Punkte sind aktuell selbst machbar.
## Kontext
Der fruehere Legacy-Provider-Live-Scope ist durch `AD-27` obsolet. `BILL-08` ist die operative Production-Prep-Quelle; dieses
Ticket bleibt als externe Abhaengigkeit fuer Mollie/KYC/Firmierung bestehen.
2026-07-27: Die getrennte Lago-Production-Instanz inklusive privatem
Object-Storage-Bucket, täglichem verschlüsseltem Backup und vollständigem
Restore-Drill ist provisioniert. Das löst keine der Mollie-/Legal-Gates:
Live-Zahlungen und Provider-Side-Effects bleiben explizit deaktiviert. Proof:
`docs/ops/lago-production-prep.md`, Snapshot `3d8a1deb`.
@@ -0,0 +1,71 @@
# EXT-18 · BauHow Test-Workspace + OAuth-/API-Vertrag klären
| | |
|---|---|
| **Typ** | Setup (External) |
| **Owner** | Raffael |
| **Plane** | `HIV-217` |
| **Cycle/Fenster** | ungeplant · vor dem Bau von `R-BAUHOW` |
| **Status** | In Progress · **1/6 DoD = ~17 % done** · Mail an Nick geschrieben, Rückmeldung offen |
## Was zu tun ist
Mit Nick von BauHow den belastbaren Zugangs- und Integrationsvertrag für einen HiveGrid-Connector klären. Es
werden bewusst **keine unbestätigten BauHow-Funktionen vorausgesetzt**. Bekannt ist nur, dass Raffael die API
bereits über Noah gesehen hat; daraus folgt noch kein freigegebener Testzugang oder OAuth-Vertrag.
Der in der Mail beschriebene vorläufige HiveGrid-Scope ist:
- einen BauHow-Account mit HiveGrid verbinden,
- Kunden-, Projekt- und Gebäudedaten im vereinbarten Minimalumfang übertragen,
- das zugehörige BauHow-Projekt aus HiveGrid öffnen,
- Status, Ergebnisse und Dokumente synchronisieren, soweit die BauHow-API diese Vorgänge tatsächlich trägt.
## Angefragter Partner-Input
1. **Test-Workspace:** separater Testzugang mit API-Zugriff und realistischen, nicht produktiven Testdaten.
2. **OAuth-App:** Kann HiveGrid selbst eine OAuth-App anlegen und verwalten oder legt BauHow sie für uns an?
3. **OAuth-Vertrag:** Client-ID/-Secret, Authorization-/Token-Endpunkte, Scopes, Refresh-/Revocation-Verhalten
und Bindung der Autorisierung an Nutzer beziehungsweise Organisation/Workspace.
4. **Redirect-URIs:** Unterstützung fester Callback-URLs für lokal, Staging und Produktion. Nach dem
HiveGrid-Routenvertrag wären dies, sofern BauHow sie akzeptiert:
- `http://localhost:3000/integrations/bauhow/oauth/callback`
- `https://staging-app.hivegrid.de/integrations/bauhow/oauth/callback`
- `https://app.hivegrid.de/integrations/bauhow/oauth/callback`
5. **Direkter Projekteinstieg:** Unterstützter SSO-, Deep-Link- oder vergleichbarer Mechanismus, mit dem ein
autorisierter Nutzer das verknüpfte Projekt ohne erneute Anmeldung öffnen kann.
6. **API-Unterlagen:** aktuelle Dokumentation und Setup-Schritte sowie die tatsächlich unterstützten
Ressourcen für Kunden, Projekte, Gebäude, Status, Ergebnisse und Dokumente; außerdem Webhooks oder die
empfohlene Alternative für den Rückkanal.
## Abhängigkeiten
- **blocked-by:** Rückmeldung und Bereitstellung durch Nick/BauHow (extern)
- **blocks:** `R-BAUHOW`
- **Auswirkung auf den Abhängigen:** `R-BAUHOW` bleibt bis zur dokumentierten Antwort auf **Blocked / On Hold**.
Insbesondere werden OAuth, API-Token, SSO/Deep-Link, Scopes und Sync-Richtung nicht vorab erfunden.
## Definition of Done
- [x] Initiale Mail an Nick mit kurzem HiveGrid-Scope sowie Fragen zu Test-Workspace, OAuth-App, Callback-URLs,
direktem Projekteinstieg und API-Unterlagen geschrieben
- [ ] Separater Test-Workspace mit nutzbarem API-Zugang und Testdaten ist bereitgestellt
- [ ] OAuth-App-Modell ist geklärt: Self-Service oder Provisionierung durch BauHow, inklusive Client-Credentials
- [ ] OAuth-Vertrag ist dokumentiert: Endpunkte, Redirect-URIs, Scopes, Token-Lifecycle und Nutzer-/Org-Bindung
- [ ] Unterstützter Vertrag für den direkten Projekteinstieg ohne zweite Anmeldung ist dokumentiert
- [ ] Aktuelle API-Unterlagen und der bestätigte Daten-/Sync-Umfang liegen vor
## Umsetzungs-Notiz
- **2026-08-01 · 1/6 DoD = ~17 % done:** Raffael hat die initiale Mail an Nick geschrieben. Sie nennt nur den
geplanten HiveGrid-Integrationsscope und fragt nach Test-Workspace, OAuth-App beziehungsweise eigener
App-Erstellung, Callback-URLs, Client-Credentials, OAuth-Endpunkten/Scopes, Token-Lifecycle, direktem
Projekteinstieg und aktueller API-Dokumentation. Offen: fünf Punkte; davon fünf durch BauHow-Input blockiert,
sobald die Anfrage bei Nick liegt. Es wird ausdrücklich noch nicht behauptet, dass BauHow OAuth/OIDC,
SSO/Deep-Links oder alle genannten Sync-Ressourcen anbietet.
## Quellen
- Anfrage und Mail-Stand von Raffael, 2026-08-01
- `docs/INTEGRATION-CONTRACTS.md` §3 (kanonischer Connector-Callback)
- `.planning/ticket-docs/R-P5.md` (bestehende Apps-Engine und `DataConnection`-Vertrag)
@@ -1,23 +1,32 @@
# H-INBOUND · Lead-Sheet + Inbound-Prozess (<24h)
# H-INBOUND · Nativer Lead-Inbound-Prozess (<24h)
| | |
|---|---|
| **Typ** | Vertrieb |
| **Owner** | Haris (mit Dejan für Routing) |
| **Owner** | Haris (mit Raffael für technische Abnahme) |
| **Cycle/Fenster** | W1 — Fundament & Identität · fällig 2026-06-19 · Gate W1 |
| **Status** | geplant |
## Was zu tun ist
Sobald die Website live ist (17./18.06.), ein Lead-Sheet aufsetzen und den Inbound-Prozess definieren: jede Website-Anfrage landet sofort bei Haris, Erst-Antwort in **unter 24 Stunden**. Benachrichtigungs-Routing mit Dejan testen. Übergangslösung, bis die HiveGrid-Lead-Inbox steht — dann Umstieg aufs eigene Produkt (Dogfooding).
Den operativen Inbound-Prozess auf der nativen Plattform-Lead-Inbox aus `R-LEADS`
abnehmen: jede Website-Anfrage ist Haris zugewiesen, die konfigurierte
Benachrichtigung kommt an und die Erst-Antwort erfolgt in **unter 24 Stunden**.
Vertretung, tägliche Kontrolle und Eskalation bei fehlgeschlagener Zustellung werden
als kurzer Vertriebs-SOP festgehalten. Ein paralleles Lead-Sheet ist danach nicht
mehr Source of Truth.
## Warum / Ziel
Kein eingehender Lead darf verloren gehen oder kalt werden. Schnelle Reaktion ist der wichtigste Conversion-Hebel in der Frühphase.
## Abhängigkeiten
- **Blocked by:** `J-LIVE` (Website live von Dejan)
- **Blocked by:** `J-LIVE` (öffentlicher Eingang), `R-LEADS` (native Admin-Inbox,
Assignment und M011-Benachrichtigung)
- **Blocks:** —
> **Recut 2026-07-16:** Der frühere Sheet-Übergang entfällt. H-INBOUND bleibt als
> operative Abnahme bestehen und dupliziert keine technische R-LEADS-DoD.
## Definition of Done
- [ ] Lead-Sheet aufgesetzt
- [ ] Benachrichtigungs-Routing mit Dejan getestet (Anfrage landet sofort bei Haris)
- [ ] Prozess steht: jede Anfrage < 24h beantwortet
- [ ] realer/synthetischer Website-Lead ist in `admin.hivegrid.de/leads` Haris zugewiesen
- [ ] M011-Benachrichtigung an Haris sowie Fehler-/Vertretungsweg operativ getestet
- [ ] SOP steht: tägliche Kontrolle, Vertretung und jede Erst-Antwort < 24h
@@ -0,0 +1,254 @@
# HIVEGRID-198 · Produktion auf 10 VMs trennen und Promote-/DNS-Prozess fertigstellen
| Feld | Wert |
| ------ | -------------------------------- |
| Typ | Infra / Deployment |
| Owner | Raffael |
| Phase | Production |
| Cycle | Backlog, am 2026-07-27 gestartet |
| Status | Done |
## Abhängigkeiten & Parallelität
- **blocked-by:** Im Plane-Ticket und in den lokalen Ticket-Docs ist kein
`blocked-by` hinterlegt.
- **blocks:** Im Plane-Ticket und in den lokalen Ticket-Docs ist kein
nachgelagertes `blocks`-Ticket hinterlegt.
- Die bestehenden Runtime-Verträge aus `R-P1a`, AD-30, VR-MCP und dem
Realtime-Modul bleiben unverändert. Der Cutover darf sie nur auf getrennte
Hosts verschieben.
- Die Produktion bleibt bis zum vollständigen Promote- und Smoke-Proof auf den
alten Runtimes erreichbar. Alte Ressourcen werden erst nach dem
Beobachtungsfenster bereinigt.
## Was wir bauen
Die bestehende HiveGrid-Produktion wird kontrolliert von fünf auf zehn klar
getrennte VMs erweitert. Neu hinzu kommen eigene Hosts für Website, Portal,
Admin, MCP und Realtime. Alle Hosts werden gehärtet, an Hetzner-Privatnetz,
WireGuard-Mesh, Coolify sowie zentrales Logging und Monitoring angebunden.
Die vorhandenen Build-once-/Stage-/Promote-Verträge werden vollständig
produktionsfähig gemacht. Production erhält exakt die in Staging geprüften
SHA-/OCI-Digests; Migrationen laufen einmalig vor der Runtime-Mutation. DNS
wechselt Service für Service mit dokumentiertem Rollback.
Verbindlicher Realtime-Hostname ist `realtime.hivegrid.de`.
Vom User am 2026-07-27 ausdrücklich in den Arbeitsumfang aufgenommen: ein
eigenes Lago-Production-Setup mit separatem, versioniertem Object Storage,
verschlüsseltem Backup und verifiziertem Restore-Drill. Mollie-Live-Side-Effects
bleiben bis zum Abschluss der externen Gates in `EXT-16` ausdrücklich
deaktiviert.
## Zielbild
1. Control/Coolify
2. App/Web
3. API
4. Worker und private Seitendienste
5. Datenbank/Stateful
6. Website
7. Portal inklusive Portal-Domain-Controller
8. Admin nur über VPN/WireGuard und Authentik
9. MCP
10. Realtime/Hocuspocus
## Nicht im Scope
- Kubernetes
- Load Balancer oder horizontale Replikation
- Umzug der HiveGrid-Anwendungsdatenbank
- automatische Skalierung
- Aktivierung von Mollie-Live-Zahlungen vor KYC-, Legal- und Live-Key-Proof
- Löschung alter Ressourcen vor Ende des Beobachtungsfensters
## Scope-Übergabe an HIVEGRID-207
Der User hat am 2026-07-28 entschieden, den noch ausstehenden autorisierten
Production-E2E-Proof, das daran anschließende 72-Stunden-Beobachtungsfenster und
die spätere Bereinigung der alten Rollback-Ressourcen als eigenständigen
operativen Nachzug in `HIVEGRID-207` zu backloggen.
`HIVEGRID-198` schließt damit den Infrastruktur-, Cutover-, Promote-, DNS-,
Backup-/Restore- und Observability-Scope ab. Die ausgelagerten Arbeiten werden
unten transparent weitergeführt, zählen aber nicht mehr zur DoD dieses Tickets.
Die alten Rollback-Ressourcen bleiben bis zum Sign-off von `HIVEGRID-207`
unangetastet.
## Definition of Done
- [x] Hetzner-Limit ist mindestens 12.
- [x] Fünf neue VMs sind erstellt, gehärtet und im privaten Netz/Coolify
eingebunden.
- [x] Logging, Monitoring und Healthchecks sind für alle fünf neuen Hosts grün.
- [x] Website, Portal, Admin, MCP und Realtime laufen auf den vorgesehenen VMs.
- [x] Admin hat eine echte fail-closed Runtime-Surface und ist nur über
VPN/WireGuard plus Authentik erreichbar.
- [x] Alle internen Verbindungen und DB-Rollen sind privat und nach Least
Privilege geprüft.
- [x] DNS, TLS und Cloudflare-Konfiguration sind für alle öffentlichen Hosts
korrekt.
- [x] HiveGrid-Cloud promotet exakt den getesteten SHA/Digest auf alle
benötigten Production-Ressourcen.
- [x] HiveGrid-Website promotet exakt den getesteten SHA/Digest auf die
Website-Production-Ressource.
- [x] Cloudflare-Purge nutzt Account/Zone korrekt, läuft nur beim Promote und
bestätigt `success=true`.
**Fortschritt: 10/10 Infra-DoD = 100 % done.**
### Ausgelagerter operativer Nachzug
Diese Punkte sind unverändert verpflichtend, werden aber vollständig in
`HIVEGRID-207` getrackt:
- [ ] Alle autorisierten Production-End-to-End-Smoke-Tests sind grün.
- [ ] Das 72-Stunden-Beobachtungsfenster ist stabil abgeschlossen und alte
Rollback-Ressourcen wurden erst danach bereinigt.
## Technische Bausteine
- Hetzner Cloud `fsn1`, privates Produktionsnetz und WireGuard-Mesh
- Coolify Projekt `HiveGrid`, Environment `production`, eine Resource pro
Runtime
- Cloudflare SSL `strict`; Public Records erst nach Origin-Zertifikats-Proof
proxied; Admin ohne öffentlichen A/AAAA-Record
- `realtime.hivegrid.de` als umgebungsneutraler Hocuspocus-Gateway-Hostname
- Gitea Package Registry und bestehender Build-once-/Promote-Workflow
- einmaliger Migrator vor Runtime-Rollout; keine Runtime-Migrations-Credentials
- getrennte Least-Privilege-Rollen für App, Portal, Worker und Admin-JIT
- private Lago-API, eigenes PostgreSQL/Redis, eigener S3-Bucket und
restic-Backup
## Quellen
- Plane `HIVEGRID-198`
- `AGENTS.md`, Abschnitt „Estate-Infrastruktur“
- `docs/deployment.md`
- `docs/ops/prod-rollout-hivegrid.md`
- `docs/ops/lago-production-prep.md`
- `docs/ARCHITECTURE-DECISIONS.md`, insbesondere AD-30
- Infra: `README.md`, `STANDARDS.md`, `LESSONS.md`
- Infra: `runbooks/hivegrid-production-split-cutover.md`
- Infra: `diagrams/hivegrid-production-topology.md`
## Umsetzungs-Notiz
### 2026-07-27
- Hetzner-Limit bestätigt und fünf CX23-Hosts in `fsn1` erstellt.
- Alle neuen Hosts gehärtet, privat vernetzt, ins WireGuard-Mesh und in Coolify
aufgenommen; Monitoring, Logs und Host-Health sind grün.
- Separate Coolify-Ressourcen für Website, Portal, Admin, MCP und Realtime
angelegt. DNS-01-Origin-Zertifikate und der private Admin-Split-DNS-Pfad sind
vorbereitet; öffentliche Records wurden noch nicht umgeschaltet.
- Runtime-Rollen, RLS, PgBouncer-Pfad und Produktions-Allowlist nach Least
Privilege geprüft. Die Migrationshistorie wurde über den einmaligen
Promote-Migrator auf den aktuellen Stand gebracht; die alte Runtime blieb
danach gesund.
- Lago Production mit eigener Datenbank, Redis, privater API, deaktiviertem
Signup und separatem versioniertem Object Storage provisioniert. Der
verschlüsselte Snapshot `73b2c338` wurde vollständig in disposable
PostgreSQL/Redis plus API, Frontend, Worker, Billing-Worker und PDF-Service
restauriert. Der S3-Schreib-/Lese-/Lösch-Canary war grün.
- Mollie-Live ist weiterhin nicht freigegeben. Die Runtime benötigt deshalb
den expliziten Schalter
`PRODUCT_ACQUISITION_PROVIDER_SIDE_EFFECT_REQUIRED=false`; ungültige Werte
und fehlende Provider-Konfiguration im aktivierten Modus schlagen
fail-closed fehl.
- Tests: Typecheck und Lint grün; Vollsuite nach der Gate-Änderung mit 1.122
Testdateien und 7.821 Tests grün, 10 Dateien beziehungsweise 60 Tests
erwartungsgemäß übersprungen. CI-Proof folgt vor Promote.
- Lokale Commits: Cloud Runtime-Gate `85fac5bb7`; Infra Backup/Restore und
Runbook `936a32a`.
### 2026-07-28
- Die fünf neuen Produktions-VMs tragen den Live-Traffic: Website
`188.34.157.34`, Portal `167.233.117.104`, Admin privat auf `10.42.0.14`,
MCP `2.28.5.232` und Realtime `2.28.5.14`. Alle elf Cloud-Ressourcen und alle
fünf Worker-Gruppen sind gesund.
- DNS/TLS-Cutover abgeschlossen: `hivegrid.de`/`www`, `portal` inklusive
Domain-Controller, `mcp` und `realtime` laufen über Cloudflare mit SSL
`strict`. `admin.hivegrid.de` hat bei öffentlichen Resolvern keinen Record,
die öffentliche Admin-IP bietet kein HTTPS. Über den WireGuard-Meshpfad
liefert Admin den exakten Release und leitet fail-closed zu
`auth.tool-ctrl.de` weiter.
- HiveGrid-Cloud PR `#281` wurde normal gemergt. Staging Run `11387` und
Production Promote Run `11389` sind für den exakten Merge-SHA
`ce08af27b217aa55ccc5daab5ffe66b995ccb3f4` grün. Core, Admin und Portal
verwenden denselben Web-Digest
`sha256:ca579bc0c39dea6b6b865c095457a5508edf455e59b80394f51942b4a49ece81`.
API, MCP, Realtime und Worker melden ebenfalls exakt diesen Commit über ihre
eigenen unveränderlichen Digests.
- Die Website läuft auf Revision `5271afc` und Digest
`sha256:2d776182df98c36cb47e7c710860e48d1ae3331a48d60cce271f1787c207c7b6`.
Production Run `11385` war grün; der abschließende Cloudflare-Purge bestätigte
`success=true`.
- Frischer Backup-Gate-Proof für den Promote: PostgreSQL-Restic-Snapshot
`b10d7874` von `2026-07-28T00:09:30Z`, Repository-Check ohne Fehler,
Prüfsumme gültig und vollständiger Restore in PostgreSQL 16 mit 373
öffentlichen Tabellen, 212 Prisma-Migrationen und 372 FORCE-RLS-Tabellen.
Die Live-Datenbank wurde beim Drill nicht verändert.
- Production-Acceptance-Hotfix `aded46303`: Bei
`PRODUCT_ACQUISITION_PROVIDER_SIDE_EFFECT_REQUIRED=false` wird kein
Mollie-Reconciler gebootstrapped und ein vorhandener 5-Minuten-Scheduler
entfernt. Web/API/Worker verwenden bei leerem `SENTRY_RELEASE` den
unveränderlichen `APP_REVISION`. Proof: Typecheck, Lint, Release-Build,
Runtime-/Deploy-Verträge, 107 fokussierte Tests und die Vollsuite mit 1.122
Testdateien beziehungsweise 7.823 bestandenen Tests; alle elf zentralen
PR-CI-Gates grün.
- Öffentliche Acceptance: Health/Readiness für Core, Portal, API und MCP jeweils
HTTP 200 auf dem exakten Release; API unauthentifiziert 401 und mit
Service-Token 200; MCP-Metadaten mit korrektem Issuer und zwölf Scopes,
tokenloser Initialize-Aufruf 401 mit Bearer-Challenge; Realtime-WebSocket
Upgrade 101.
- Monitoring: Prometheus 34/34 aktive Targets `UP`, inklusive beider Exporter
auf allen zehn Hosts. Loki liefert aktuelle Production-Logs aller zehn Hosts
mit `project`, `environment`, `server`, `service`. Zehn Minuten nach dem
Rollout meldete Sentry für Web, API und Worker jeweils null aktuelle
Production-Issues; seit dem neuen Worker-Rollout erschien auch in Loki keine
Meldung des zuvor periodischen `UnsupportedWorkerJobError`.
- Rollback-Snapshots liegen lokal unter
`~/.cli-tokens/hivegrid-dns-before-hivegrid-198-20260727T143742Z.json` und
`~/.cli-tokens/hivegrid-coolify-before-hivegrid-198-20260727T143827Z.json`.
Das Infra-Runbook dokumentiert Release-first-/DNS-second-Rollback,
Forward-only-Migrationen, Backups und das 72-Stunden-Fenster.
- Noch offen: ein freigegebener echter Production-Login für Core-Read/Write,
Portal-Login/Upload/Logout, Admin-JIT, autorisierten MCP-Aufruf und
autorisierten Realtime-Roundtrip. Für den Rollout wurde bewusst kein
Production-Passwort zurückgesetzt und keine Testidentität erfunden. Erst
nach diesen Checks beginnt das verbindliche 72-Stunden-Fenster; alte
Rollback-Ressourcen bleiben bis zu dessen Sign-off bestehen.
- Der Promote wurde für beide Repositories auf einen input-freien manuellen
Run vereinfacht. HiveGrid-Website PR `#6` wurde normal gemergt; Run `11405`
promotete den live auf Staging geprüften Release `ec9402a` ohne Neubau nach
Production und bestätigte dort dieselbe Revision.
- HiveGrid-Cloud behandelt einen manuellen Run von `main` jetzt ausschließlich
als Production-Promote. Der Workflow liest den vollständigen SHA aus der
live Staging-Core-Health-Antwort, prüft Service/Surface, Main-Ancestry und
alle sechs `staging`-OCI-Digests und behält RLS-, Migrator-, Runtime-,
Health- und Digest-Gates unverändert bei. Der manuelle Start ist die
auditierte Operator-Bestätigung der zuvor geprüften Backup- oder
Restore-Point-Bereitschaft.
- Lokaler Proof für den Cloud-Nachzug: Typecheck und Lint grün; 185 fokussierte
Deploy-/Readiness-Tests grün; `verify:gitea-ci-workflow`,
`verify:deploy-workflow`, `verify:deploy-readiness`,
`verify:ci-baseline` und `verify:source-health` grün; Vollsuite mit 1.122
bestandenen Testdateien beziehungsweise 7.823 bestandenen Tests, 10 Dateien
beziehungsweise 60 Live-Integrationstests erwartungsgemäß übersprungen.
- Abschluss-Proof der input-freien Workflows: HiveGrid-Cloud Staging-Run
`11409` und Production-Promote `11411` sind für
`d060e626ccebe84d5df01717c9b04c8b3ff6fd15` grün; Staging und Production
melden für Core, Portal, API und MCP exakt diesen Release. Der nachfolgende
Website-Run `11412` promotete Dejans neuen Staging-Stand `cfd08ee` ohne
Eingaben; `staging.hivegrid.de` und `hivegrid.de` meldeten danach beide
`cfd08ee`.
- User-Entscheidung vom 2026-07-28: Production-E2E, das daran anschließende
72-Stunden-Fenster und die Altressourcen-Bereinigung werden in
`HIVEGRID-207` weitergeführt. Die bestehenden Rollback-Ressourcen bleiben bis
zu dessen Sign-off erhalten.
**Stand: 10/10 Infra-DoD = 100 % done · operativer Nachzug vollständig nach
HIVEGRID-207 übertragen.**
@@ -0,0 +1,108 @@
# HIVEGRID-207 · Production-E2E abnehmen und 72-Stunden-Fenster abschließen
| Feld | Wert |
| ------ | ------------------ |
| Typ | Infra / Acceptance |
| Owner | Raffael |
| Phase | Production |
| Cycle | Backlog |
| Status | Backlog |
## Abhängigkeiten & Parallelität
- **blocked-by:** Keine Plane- oder Ticket-Abhängigkeit. Die benötigte
Produktionsinfrastruktur aus `HIVEGRID-198` ist fertig und live.
- **blocks:** Keine hinterlegte Ticket-Abhängigkeit.
- **Externe Startvoraussetzung:** Eine Production-Testidentität sowie ein
separater Authentik-Operatorzugang müssen ausdrücklich für die Abnahme
freigegeben sein. Zugangsdaten gehören weder in Plane noch ins Repository.
- Das 72-Stunden-Beobachtungsfenster startet erst nach dem letzten erfolgreichen
autorisierten End-to-End-Test.
- Alte Rollback-Ressourcen aus `HIVEGRID-198` bleiben bis zum erfolgreichen
Abschluss dieses Tickets bestehen.
## Was wir bauen
Dieses Ticket ist der vom User am 2026-07-28 aus `HIVEGRID-198` ausgelagerte
operative Production-Nachzug. Es nimmt die bereits live geschaltete
Infrastruktur mit echten autorisierten Benutzerflüssen ab, beobachtet den
stabilen Betrieb anschließend 72 Stunden und bereinigt erst danach die alten
Rollback-Ressourcen.
Die Abnahme verwendet vorhandene Produkt- und Authentik-Flows. Es werden keine
Production-Identitäten erfunden, keine Passwörter zurückgesetzt und keine
RLS- oder Seed-Schutzschranken umgangen.
## Testmatrix
1. **Core:** Production-Login, autorisiertes Lesen und ein kontrollierter,
reversibler Schreibvorgang.
2. **Portal:** Login, ungefährlicher Test-Upload mit AV-Prüfung und Logout.
3. **Admin:** Zugriff ausschließlich über WireGuard/VPN und Authentik-JIT;
öffentlicher Zugriff bleibt fail-closed.
4. **MCP:** Autorisierter Aufruf mit gültigem Production-Token und passendem
Scope.
5. **Realtime:** Autorisierter WebSocket-Verbindungsaufbau und Roundtrip.
6. **Beobachtung:** Healthchecks, Prometheus, Loki und Sentry über 72 Stunden
nach dem letzten grünen End-to-End-Test auswerten.
## Nicht im Scope
- neue VMs, DNS-Umbauten oder Änderungen am Promote-Vertrag
- neue Produktfeatures oder Refactorings
- Aktivierung von Mollie-Live-Zahlungen
- Production-Seeding unter erzwungenem RLS
- Credentials, Tokens oder personenbezogene Testdaten in Git, Plane oder Logs
## Definition of Done
- [ ] Production-Testidentität und Authentik-Operatorzugang sind ausdrücklich
freigegeben.
- [ ] Core-Login, Read und kontrollierter Write sind in Production grün.
- [ ] Portal-Login, ungefährlicher Upload und Logout sind in Production grün.
- [ ] Admin-JIT, autorisierter MCP-Aufruf und autorisierter Realtime-Roundtrip
sind grün.
- [ ] Das anschließende 72-Stunden-Fenster ist mit Health-, Prometheus-, Loki-
und Sentry-Proof stabil abgeschlossen.
- [ ] Alte Rollback-Ressourcen sind erst nach Sign-off bereinigt; Runbook,
Diagramm, Ticket-Doc und Plane enthalten den Abschluss-Proof.
**Fortschritt: 0/6 DoD = 0 % done · durch die noch nicht freigegebene
Production-Testidentität blockiert · 0 aktuell selbst machbar.**
## Technische Bausteine
- Live-Releases zu Beginn und Ende über `/healthz` beziehungsweise die
dienstspezifischen Readiness-Probes dokumentieren.
- Für Core und Portal ausschließlich freigegebene Production-Tenant-Daten
verwenden; Testmutationen reversibel und eindeutig kennzeichnen.
- Admin nur über den bestehenden privaten WireGuard-/Authentik-Pfad testen.
- MCP- und Realtime-Tokens nicht ausgeben oder in Shell-/CI-Logs schreiben.
- `PRODUCT_ACQUISITION_PROVIDER_SIDE_EFFECT_REQUIRED=false` bleibt während der
Abnahme unverändert; Mollie-Side-Effects sind nicht Teil dieses Tickets.
- Beobachtungsbeginn und -ende mit Zeitzone festhalten. Während des Fensters
keine alten Rollback-Ressourcen löschen.
- Bei einem kritischen Fehler: Beobachtungsfenster abbrechen, Runbook-Rollback
bewerten und nach dem Fix ein neues vollständiges 72-Stunden-Fenster starten.
## Quellen
- Plane `HIVEGRID-207`
- `.planning/ticket-docs/HIVEGRID-198.md`
- `docs/deployment.md`
- `docs/ops/prod-rollout-hivegrid.md`
- Infra: `runbooks/hivegrid-production-split-cutover.md`
- Infra: `diagrams/hivegrid-production-topology.md`
- `AGENTS.md`, Abschnitte „Plane-Tracking“ und „Estate-Infrastruktur“
## Umsetzungs-Notiz
### 2026-07-28
- Vom User als eigener Backlog-Nachzug aus `HIVEGRID-198` beauftragt.
- Plane-Ticket im Status Backlog mit den Labels `infra`, `chore` und
`wartet-extern` angelegt.
- Startbedingung bleibt die ausdrückliche Freigabe einer
Production-Testidentität und des Authentik-Operatorzugangs.
**Stand: 0/6 DoD = 0 % done · 1 externe Startvoraussetzung offen.**
@@ -0,0 +1,86 @@
<!-- markdownlint-disable MD013 MD060 -->
# I18N-01 · Polnisch, Russisch, Ukrainisch und Ungarisch
| | |
| --- | --- |
| **Typ** | Dev (Code + Kataloge + QA) |
| **Owner** | Raffael |
| **Phase** | Querschnitt · CR-020 |
| **Plane** | `HIVEGRID-243` · Issue `8e7c8c3b-558e-4d58-9650-5decc1b5d3c6` |
| **Cycle/Fenster** | ohne Cycle · Priorität High |
| **Status** | Done |
## Abhängigkeiten & Parallelität
- **Blocked by:** `R-P1b` (Done: i18n-Foundation und `verify:i18n`), genehmigter `CR-020`.
- **Blocks:** keine bestehende Implementierung; die produktive Freigabe jeder neuen Sprache bleibt bis zu ihrem Review-Manifest blockiert.
- **Plane-Prüfung:** `HIVEGRID-243` wurde nach bestätigter Identität `raffael` angelegt. Das abgeschlossene Foundation-Ticket `R-P1b` ist die einzige technische Vorbedingung; das neue Ticket übernimmt keinen bestehenden `blocks`-Vertrag und blockiert nur die sprachweisen Release-Gates in seinen Review-Manifesten.
- **Konflikt-Risiko:** hoch in den zentralen Locale-Dateien und Querschnittsverträgen. Umsetzung deshalb im isolierten Worktree `feat/i18n-pl-ru-uk-hu`, keine Schemaänderung.
## Was wir bauen
HiveGrid erhält vollständige statische Produktübersetzungen für Polnisch (`pl`), Russisch (`ru`), Ukrainisch (`uk`, niemals `ua`) und Ungarisch (`hu`). Der sichtbare Scope umfasst App, Admin, Auth, Fehler, Einstellungen, Billing, Customer-Portal, Dialoge/Toasts und transaktionale E-Mails. Deutsch bleibt fachliche Quelle, Englisch zweite Kontextreferenz.
Vorhandene Kataloge und freigegebene Runtime-Sprachen werden getrennt. `I18N_ENABLED_LOCALES` enthält ohne Konfiguration nur `de,en`. Deaktivierte Sprachen erscheinen nicht im Selector und können weder Cookie, gespeicherte Präferenz noch Browserheader erzwingen. Auflösung: aktivierte User-Präferenz → aktivierter Tenant-Default → aktiviertes `Accept-Language` → Deutsch.
Alle sechs Sprachen sind LTR. Basisdateien sind informell. Formelle Bundles folgen zwingend `<locale>-formal → <locale> → de`; fehlende formelle Übersetzungen einer Zielsprache dürfen nicht direkt nach Deutsch springen. UI-Sprache und Knowledge-Base-Inhaltssprache bleiben getrennt. Nutzergenerierte Inhalte werden nicht maschinell verändert.
## Benötigte Screens
Keine neue Oberfläche. Vorhandene Sprachwahl, App-/Admin-Shell, Customer-Portal und kritische Journeys werden für lange lateinische sowie kyrillische Texte browserseitig geprüft. Die Kataloge landen zunächst deaktiviert; visuelle Produktfreigabe erfolgt Sprache für Sprache.
## Definition of Done
- [x] `SupportedLocale` und alle öffentlichen UI-/Mail-/Portal-Locale-Verträge umfassen exakt `de`, `en`, `pl`, `ru`, `uk`, `hu`; alle sechs sind LTR, keine DB-Migration.
- [x] `I18N_ENABLED_LOCALES` validiert unbekannte, doppelte, leere und nicht release-fertige Werte fail-closed; Default ist `de,en`.
- [x] Locale-Auflösung und Selector respektieren ausschließlich aktivierte Sprachen in der Reihenfolge User → Tenant → `Accept-Language` → DE; deaktivierte Cookies/Preferences/Header werden ignoriert.
- [x] Jede Basis-Sprache liefert alle neun Namespaces mit exakt derselben Key-Struktur wie DE; jede Sprache besitzt vollständige Namespace-Dateien für `<locale>-formal` mit ausschließlich abweichenden Overrides.
- [x] date-fns/Wochenbeginn, Portal-Cookie/`Accept-Language`, Portal-Mailvorlagen, Mail-Worker, React-E-Mail-Dokumentsprache/Betreff/HTML/Plaintext/Footer, inline Mailtexte und Billing-Checkout sind vollständig verdrahtet.
- [x] Mollie erhält `pl_PL` und `hu_HU`; für `ru`/`uk` wird keine erfundene Provider-Locale gesendet. Die HiveGrid-Checkout-Hülle bleibt übersetzt.
- [x] Knowledge-Base-Inhaltssprachen und nutzergenerierte Inhalte bleiben vom UI-Locale-Ausbau getrennt.
- [x] Verbindliches SHK-/HiveGrid-Glossar sowie Styleguide je Zielsprache dokumentieren Fachbegriffe, Ton und informelle/formelle Anrede.
- [x] `verify:i18n` prüft Key-Parität, JSON, leere/unveränderte Texte, Platzhalter/ICU/Tags/URLs, Unicode-Normalisierung, Mojibake und CLDR-Pluralformen (`pl/ru/uk`: one/few/many/other; `hu`: one/other).
- [x] Review-Manifest je Zielsprache enthält Source-Hashes, automatisierten Übersetzungs-/Zweitprüfstatus, Muttersprachler-Stichprobe und Release-Status; geänderte DE-Quellen invalidieren den Reviewstatus.
- [x] Tests decken Locale-Auflösung, deaktivierte Quellen, Profil-/Tenant-Anrede, Portal, Worker/Mail, Billing-Mapping, Formal-Fallback und ICU-Werte `0/1/2/5/21` plus Dezimalwert ab.
- [x] Startzeit/RSS mit zwei versus sechs Katalogen sind gemessen; bei mehr als 250 ms oder 30 MB Delta wird vor Freigabe localeweise gecacht geladen.
- [x] Rollout und Rollback sind dokumentiert: initial alle neuen Sprachen deaktiviert; Freigabe `pl → uk → ru → hu` jeweils erst nach bestandenem Manifest-Gate. Rumänisch ist als nächster Ausbau dokumentiert, aber nicht als Katalog angelegt.
- [x] Fokussierte Tests, `pnpm typecheck`, `pnpm lint`, `pnpm test`, `pnpm run verify:i18n`, `verify:ci-baseline` und `verify:source-health` sind grün.
**Fortschritt:** 14/14 DoD = 100 % done · 0 Punkte selbst machbar. Die Muttersprachler-Freigabe ist kein Merge-Gate dieses initial deaktivierten Katalog-PRs; alle vier Sprachen bleiben bis dahin technisch vorhanden, aber produktiv gesperrt (`nativeReview: pending`, `release: disabled`).
## Technische Bausteine
- `packages/i18n`: statische versus aktivierte Locales, Parser/Resolver, Formal-Fallback, Plural-/Token-Verträge.
- `apps/web/public/locales/{pl,ru,uk,hu}` und `{pl,ru,uk,hu}-formal`: neun Namespaces je Verzeichnis.
- `apps/web/app/locale`: Serverressourcen, Cookie/Header/User-/Tenant-Auflösung, date-fns und Mail-Translator.
- `apps/web/app/services/customer-portal`, `apps/web/app/modules/emails`, `apps/worker`: Portal- und Outbound-Wiring.
- `packages/mail`, `packages/billing`: Mail-Dokumentsprache und unterstützte Mollie-Locales.
- `scripts/i18n-check.ts` plus Review-/Glossar-Artefakte unter `docs/i18n/`.
## Qualitäts- und Release-Prozess
1. Deutsch ist die fachliche Quelle; Englisch wird als Kontextreferenz verwendet.
2. Automatische Erstübersetzung läuft namespaceweise und schützt Platzhalter, ICU, Tags und URLs.
3. Ein separater semantischer Zweitlauf und die statischen Validatoren prüfen Bedeutung und Vertragsintegrität.
4. Vor produktiver Aktivierung prüft ein Muttersprachler Auth, Fehler, Billing, Mail, alle formellen Overrides, kritische App-/Portal-Journeys und mindestens 200 geschichtete Stichproben. Reviewer, Datum und Korrekturen landen im Manifest.
## Quellen
- `docs/CHANGE-REQUESTS.md` → CR-020.
- `.planning/REQUIREMENTS.md` → `REQ-i18n-architektur`, `REQ-i18n-six-locale-outbound`.
- `.planning/ROADMAP.md` → Phase 3 und revidierter Phase-30-i18n-Scope.
- `AGENTS.md` → Querschnitt i18n, Ticket-Treue, EU-Stack, keine Runtime-LLM-Abhängigkeit.
- Unicode CLDR Plural Rules sowie Mollie Locale-Vertrag (Links im Rollout-/QA-Dokument).
## Rollback
`I18N_ENABLED_LOCALES` wird auf `de,en` zurückgesetzt und der vorherige immutable Image-SHA erneut deployt. Katalogdateien können dabei im Image verbleiben: deaktivierte Sprachen sind weder auswählbar noch über Cookie/Präferenz/Header aktivierbar. Es gibt keine Migration und keinen Daten-Rollback.
## Umsetzungs-Notiz
**2026-08-02 · 14/14 DoD = 100 % done.** Umsetzung in `feat/i18n-pl-ru-uk-hu` ab `origin/main` (`86eb01825`) mit atomaren Commits `52b94bd8a`, `d23b22f10`, `21e1c8997`, `9d83caedd`, `46624686f`, `f37cedf8c`, `e4b9890d0`, `6b7686cb9`, `79ab32c10`, `e60303dc6`, `216a7373e`, `6527f2d8f`, `9839cf0e3`, `5c7b33c72` und `7cf0bafa5`; aktuelles `origin/main` samt Avatar-Crop-Texten über `c4af2e0c0` integriert.
Proof: sechs Basis-Kataloge und sechs Formal-Bundles mit je neun Namespaces; `verify:i18n` meldet nach Integration des aktuellen `origin/main` 16.483 identische Keys pro Basis-Locale. `pnpm typecheck`, `pnpm lint`, 1.197 Core-Testdateien, `verify:i18n`, `verify:i18n-performance`, `verify:ci-baseline`, `verify:source-health` und `verify:secrets` sind grün. Die finale Performance-Messung ergab gegenüber `de,en` +22,62 ms Startladezeit und +11,09 MB RSS (Grenzen: +250 ms/+30 MB), daher bleibt das einmalige eager Laden bestehen.
Kein Schema- oder Migrations-Nachzug. Runtime-Default und Produktion bleiben `de,en`. Die Review-Manifeste halten Polnisch, Ukrainisch, Russisch und Ungarisch bis zur dokumentierten muttersprachlichen Prüfung von kritischen Oberflächen, Du/Sie-Ton, Fachterminologie und mindestens 200 Stichproben ausdrücklich auf `pending`/`disabled`.
@@ -17,7 +17,6 @@ Die Website bekommt ihre finalen Inhalte. Ohne abgenommene Texte kein freigabef
## Abhängigkeiten
- Blocked by: J-STRUKTUR, H-TXT (Texte Haris), N-TXTABN (Text-Abnahme Noah)
- Blockt: J-LIVE
- Quelle: HANDOUT-DEJAN.md — AP-1
## Definition of Done
- [ ] Texte (Haris, Noah-abgenommen) eingepflegt
@@ -17,7 +17,6 @@ Website-seitiger Abschluss des v1-Launch: vollständige Feature-Darstellung, fin
## Abhängigkeiten
- Blocked by: J-LIVE, J-SEO
- Blockt: —
- Quelle: HANDOUT-DEJAN.md — AP-4
## Definition of Done
- [ ] finale Feature-Seiten + Pricing live
@@ -16,7 +16,7 @@ Rechtssicherer LIVE-Gang. Ohne Impressum/Datenschutz darf die Website nicht öff
## Abhängigkeiten
- Blocked by: EXT-03 (Rechtstexte vom Anwalt)
- Blockt: J-LIVE
- Quelle: EXTERNALS-CHECKLISTE.md — E6
- Quelle: Plane-Ticket und diese Bau-Spec
## Definition of Done
- [ ] Impressum/Datenschutz/AVV-Link eingebaut
@@ -10,15 +10,23 @@
## Was zu tun ist
- Website live schalten auf hivegrid.de.
- EU-konformes Analytics einrichten + Search Console anbinden.
- Responsive QA über die produktiven Seiten/Breakpoints durchführen und das
Formular bis zur serverseitigen Übergabe smoke-testen.
## Warum / Ziel
Erster öffentlich sichtbarer Auftritt von HiveGrid. Fixer LIVE-Termin 17./18.06. — eröffnet den Inbound-Kanal (H-INBOUND).
## Abhängigkeiten
- Blocked by: J-QA, J-LAW
- Blocked by: J-CONTENT, J-LAW
- Blockt: H-INBOUND
- Quelle: TIMELINE.md (Dejan / LIVE 17./18.), HANDOUT-DEJAN.md — AP-1
- Quelle: Plane-Ticket und diese Bau-Spec
> **Recut 2026-07-16:** Das historische `J-QA`-Ticket ist als HIVEGRID-73 zu
> `R-LEADS` geworden und blockiert den bereits erfolgten Website-Livegang nicht
> rückwirkend. Der responsive Launch-QA-Anteil liegt deshalb direkt in `J-LIVE`.
> Die native Plattform-Lead-Anbindung wird separat in `R-LEADS` gebaut.
## Definition of Done
- [ ] live auf hivegrid.de
- [ ] EU-konformes Analytics + Search Console aktiv
- [ ] responsive Produktions-QA + Formular-Smoke bis zur serverseitigen Übergabe dokumentiert
@@ -1,24 +0,0 @@
# J-QA · QA + Lead-Routing-Test
| | |
|---|---|
| Typ | Website |
| Owner | Dejan |
| Cycle/Fenster | W1 — Fundament & Identität · 2026-06-17 → fällig 2026-06-18 |
| Status | geplant |
## Was zu tun ist
- Responsive QA über alle Seiten und Breakpoints.
- Demo-Formular testen: Lead-Routing an Haris funktioniert end-to-end.
## Warum / Ziel
Qualitätssicherung vor LIVE. Defekte Darstellung oder verlorene Leads beim Launch sind nicht akzeptabel.
## Abhängigkeiten
- Blocked by: J-CONTENT
- Blockt: J-LIVE
- Quelle: HANDOUT-DEJAN.md — AP-1
## Definition of Done
- [ ] responsive QA durchgeführt
- [ ] Formular → Lead-Routing an Haris getestet
@@ -18,7 +18,15 @@ Nach LIVE die Auffindbarkeit und Conversion verbessern und die Pricing-Seite sta
## Abhängigkeiten
- Blocked by: J-LIVE
- Blockt: —
- Quelle: HANDOUT-DEJAN.md — AP-2
2026-07-29 · Abhängigkeitsnachzug aus `BILL-11`:
- Der versionierte Pricing-Contract für Core / Swarm / Colony inklusive
Zusatznutzern, Speicherpaketen und 12-Monats-SEPA-Raten ist fertig und in
Staging und Production driftfrei provisioniert.
- Die Pricing-Inhalte sind damit nicht mehr durch fehlende Produktpreise
blockiert. Ein echter Production-Payment-Link bleibt bis `BILL-08` /
`EXT-16` (Mollie Live, Rechnungssteller, Steuer und Impressum) gesperrt.
## Definition of Done
- [ ] SEO-Basics + Conversion-Feinschliff umgesetzt
@@ -18,7 +18,6 @@ Fundament für die Website. Ohne lauffähigen Stack und Repo kann Davids Design
## Abhängigkeiten
- Blocked by: — (Fundament, kein Vorgänger)
- Blockt: J-STRUKTUR
- Quelle: HANDOUT-DEJAN.md — AP-1
## Definition of Done
- [ ] Stack/Hosting/Domain geklärt
@@ -17,7 +17,6 @@ Die Website bekommt ihr Gerüst und ihren markenkonformen Auftritt. Grundlage f
## Abhängigkeiten
- Blocked by: J-SETUP, D-WEB (Davids Website-Screens + Brand-Tokens)
- Blockt: J-CONTENT
- Quelle: HANDOUT-DEJAN.md — AP-1
## Definition of Done
- [ ] Seitenstruktur (Landing/Features/Pricing-Teaser/Demo-Formular/Webinar-Warteliste) steht
@@ -17,7 +17,6 @@ Anmeldungen für das Webinar (14./15.07.) sammeln und Teilnehmer zuverlässig er
## Abhängigkeiten
- Blocked by: J-LIVE
- Blockt: H-WEBINAR
- Quelle: HANDOUT-DEJAN.md — AP-3
## Definition of Done
- [ ] Landing + Anmelde-Flow live
@@ -17,7 +17,6 @@ Technisch reibungsloser Webinar-Ablauf und nachträgliche Verwertung über Aufze
## Abhängigkeiten
- Blocked by: J-WEBINAR
- Blockt: —
- Quelle: HANDOUT-DEJAN.md — AP-5
## Definition of Done
- [ ] Plattform-Setup (Livestorm/Zoom) + Generalprobe erledigt
@@ -0,0 +1,104 @@
# MAIL-01 · Mailjet-Willkommensmail nach Signup zuverlässig zustellen
| | |
| ----------------- | -------------------------------------------- |
| **Typ** | Launch-Fix · Transactional Mail |
| **Owner** | Raffael |
| **Phase** | Pilot-Härtung |
| **Cycle/Fenster** | gestartet 2026-08-01 |
| **Status** | Done |
| **Plane** | HIVEGRID-237 |
## Abhängigkeiten & Parallelität
- **Blocked by:** kein technischer Blocker. `EXT-02` bestätigt Domain, Sender,
SPF und DKIM; Signup und Transactional-Mail-Queue sind bereits produktiv verdrahtet.
- **Blocks:** zuverlässige Welcome-Experience für neue Pilot-Tenants.
- **Abhängigkeitsschutz:** Sender, React-Email-Template, Queue, Retry,
Signup-Idempotenz und Marketingversand bleiben unverändert.
## Was / Warum
Der direkte Staging-Signup erzeugt für die Willkommensmail den stabilen Key
`mail:signup-welcome:<tenant>:<creation-request-key>`. Dieser Key ist im echten
Fall 93 Zeichen lang. Der Mailjet-Sandbox-Proof mit dem exakten Staging-Konto
bestätigte die Grenze: 64 Zeichen werden akzeptiert; ab 65 Zeichen antwortet
Mailjet mit HTTP 400 / `mj-0006` für `CustomID`.
Der Provider-Adapter nahm fälschlich 100 Zeichen an. Lange Replay-Keys werden
deshalb deterministisch auf eine höchstens 64 Zeichen lange Korrelation
abgebildet. Kurze IDs bleiben für den Betrieb lesbar. Exakte Retries müssen
dieselbe ID, verschiedene lange Keys praktisch kollisionsfrei verschiedene IDs
erhalten.
## Nicht im Scope
- Kein neues Mail-Template, kein Providerwechsel und kein Marketingversand.
- Keine Änderung an Signup-, Queue-, Retry- oder Delivery-Idempotenz.
- Keine Live-/Produktionsmail und keine Änderung an Mailjet-Secrets.
## Definition of Done
- [x] `CustomID` ist für jede Eingabe höchstens 64 Zeichen lang; Werte bis zur
Grenze bleiben bytegleich.
- [x] Lange Keys werden deterministisch und kollisionsresistent kompaktiert;
der rohe lange Key verlässt den Adapter nicht im Payload.
- [x] Fokus-Tests decken 64/65+, exaktes Replay und verschiedene lange Keys ab.
- [x] Typecheck, Lint, vollständige Testsuite und Package-/Security-Gates sind grün.
- [x] PR-CI, normaler Merge und Staging-Deploy sind grün; ein frischer
Test-Signup belegt die Welcome-Zustellung und das Rendering per Screenshot.
**MAIL-01: 5/5 DoD = 100 % done. Kein selbst machbarer Punkt offen.**
## Technische Bausteine
- `packages/mail/src/mailjet.ts`
- `packages/mail/src/mailjet.test.ts`
- bestehender `mail:signup-welcome`-Outbox-/Queue-Vertrag
- CR-012 in `docs/CHANGE-REQUESTS.md`
## Rollback
Reiner Code-Rollback des Provider-Normalizers. Es gibt keine DB-Migration und
keinen persistierten Vertragswechsel. Bereits kompaktierte IDs sind nur
Provider-Korrelationen; Queue- und Delivery-Idempotenz bleiben an den
unveränderten vollständigen Replay-Key gebunden.
## Umsetzungs-Notiz
2026-08-01 · Diagnose und Implementierung gestartet
- Mailjet-Sandbox-Proof: 32, 50 und 64 Zeichen HTTP 200; 65, 80, 93 und 100
Zeichen HTTP 400 / `mj-0006` für `CustomID`.
- Sender `noreply@hivegrid.de` und Wildcard-Domain sind im exakten
Staging-Konto aktiv; SPF/DKIM sind grün. Der Fehler liegt nicht am Sender.
- Der Adapter bewahrt IDs bis einschließlich 64 Zeichen bytegleich. Längere
IDs erhalten `hivegrid-id:` plus 52 Hex-Zeichen SHA-256; gleiche Keys bleiben
replay-stabil, verschiedene lange Keys erhalten verschiedene Korrelationen.
- Lokaler Proof: 99/99 Mail-Package-Tests, Package-Typecheck und fokussiertes
ESLint grün; anschließend Repo-Typecheck, Repo-Lint und 8.207/8.207 Tests in
1.168 Testdateien grün (60 bewusst übersprungen).
- Der bestehende Transactional-Mail-Baseline-Gate verwies noch auf die längst
entfernte `mailersend.test.ts` und scannte historische Doku nach Postmark.
Er läuft jetzt gegen Mailjet plus den kanonischen Runtime-Removed-Module-
Scanner; 3.834 Runtime-Dateien sind frei von verbotenen Provider-Resten und
der vollständige Baseline-Gate ist grün.
**MAIL-01: 4/5 DoD = 80 % done. Offen: PR-CI, normaler Merge,
Staging-Deploy und Welcome-Zustellproof; kein externer Blocker.**
2026-08-01 · Staging-Zustellung und Rendering abgenommen
- Commit `71ea96992` bestand die vollständigen Gates, wurde über PR `#327`
normal gemergt und war Bestandteil der grünen Staging-Revision `137358736`
aus Deploy `11669`.
- Der frische deutsche BILL-14-Signup erzeugte exakt eine Mail. Das reale
Testpostfach erhielt am 2026-08-01 um 12:55:44 UTC den Betreff
„Willkommen bei HiveGrid, Pilot!“; HTML-Rendering und CTA waren vorhanden.
- Screenshot `58-final-welcome-mail-delivered.png` im finalen Desktop-UAT-
Ordner belegt die tatsächlich zugestellte und gerenderte Mail. Es wurden
keine Production-Mail und keine Mailjet-Secret-Änderung ausgelöst.
- Locale-/Footer-, Plaintext- und Branding-Härtung bleiben bewusst außerhalb
des engen CustomID-Fix-Scope und werden getrennt nachgezogen.
**MAIL-01: 5/5 DoD = 100 % done. Kein selbst machbarer Punkt offen.**
@@ -0,0 +1,100 @@
# MAIL-02 · Transaktionale Mail-Sprache und Plaintext vollständig ausliefern
| | |
| ----------------- | ------------------------------------------- |
| **Typ** | Launch-Härtung · Mail-UX / Accessibility |
| **Owner** | Raffael |
| **Phase** | Pilot-Härtung |
| **Cycle/Fenster** | gestartet 2026-08-01 |
| **Status** | Done |
| **Plane** | HIVEGRID-238 |
## Abhängigkeiten & Parallelität
- **Blocked by:** kein technischer Blocker. `MAIL-01` ist Done und belegt den
funktionierenden Signup-, Queue-, Mailjet- und Inbox-Pfad.
- **Blocks:** barriereärmere, sprachkonsistente transaktionale Pilot-Mails.
- **Abhängigkeitsschutz:** Provider, Sender, Queue-Namen, Retry, Idempotenz,
Signup-Replay und Marketingversand bleiben unverändert.
## Was / Warum
Der reale deutsche Welcome-Proof aus `MAIL-01` wurde zugestellt, deklariert das
HTML-Dokument aber als Englisch und zeigt im Footer englische Legal-/Support-
Texte. Zudem erzeugt der kanonische Renderer bereits eine Plaintext-Version,
die der Web-Wrapper vor Queue und Mailjet verwirft. Der einzelne Bindestrich in
der Signatur wird als eigene sichtbare Zeile gerendert.
Dieser Slice führt die vorhandene Locale und die bestehenden de/en-Mailtexte
als expliziten Chrome-Vertrag bis in das React-Template. HTML und Plaintext
werden gemeinsam durch den unveränderten Outbox-/Queue-Vertrag transportiert;
Mailjet erhält den Text über das bereits unterstützte `TextPart`.
## Nicht im Scope
- Kein neuer Welcome-Inhalt, Workspace-Text, Onboarding-Schritt oder CTA-Ziel.
- Kein Branding-/Logo-Adapter und keine White-Label-Erweiterung.
- Kein neuer Delivery-Status, Alarm oder Operator-Dashboard.
- Keine Provider-, Sender-, Secret-, Retry-, Idempotenz- oder Marketingänderung.
## Definition of Done
- [x] Transaktionale Templates erhalten eine normalisierte `de`-/`en`-Sprache
und setzen das passende `lang`-Attribut am HTML-Dokument.
- [x] Legal-Links, Supportzeile und optionaler Abmeldelink verwenden die
vorhandenen de/en-Übersetzungen; kein englischer Footer bleibt in der
deutschen Welcome-Mail.
- [x] Der einzelne Signatur-Bindestrich entfällt, ohne Absendername oder
bestehenden Signoff-Text zu verändern.
- [x] Die bereits erzeugte Plaintext-Version wird im Template-Resultat, im
Welcome-Outbox-Payload und im Mailjet-`TextPart` unverändert erhalten.
- [x] Fokus-Tests decken deutsche und englische Sprache, Footer, Plaintext,
Welcome-Outbox, Replay-Stabilität und den finalen Provider-Payload ab.
- [x] Typecheck, Lint, vollständige PR-CI, normaler Merge und Staging-Deploy
sind grün; ein gerenderter deutscher Welcome-Proof liegt als Screenshot vor.
**MAIL-02: 6/6 DoD = 100 % done. 0 Punkte offen.**
## Technische Bausteine
- `packages/mail/src/templates-react/_layout/BaseLayout.tsx`
- `packages/mail/src/templates-react/_layout/Footer.tsx`
- `packages/mail/src/templates-react/transactional/shared.tsx`
- `apps/web/app/modules/emails/utils/EmailTemplates.ts`
- Signup-Welcome-Outbox in `apps/web/app/utils/services/authService.ts`
- bestehende `packages/mail`- und Signup-/Outbox-Tests
- CR-015 in `docs/CHANGE-REQUESTS.md`
## Rollback
Reiner Code-Rollback des optionalen Mail-Chrome- und Text-Payload-Vertrags.
HTML bleibt bei älteren Aufrufern durch Defaults kompatibel. Es gibt keine
Datenmigration, Provider-Mutation oder Änderung persistierter Idempotenzkeys.
## Quellen
- Mailjet: `https://documentation.mailjet.com/hc/de/articles/39399376475675-Barrierefreie-E-Mails-erstellen-Best-Practices`
- `MAIL-01` Inbox- und Rendering-Proof, Screenshot `58`
## Umsetzungs-Notiz
2026-08-01 · Scope, Implementierung und lokaler Proof
- Der echte deutsche Signup wurde exakt einmal zugestellt; Funktion und
Mailjet-CustomID sind damit kein Blocker mehr.
- Visueller Proof: deutscher Hauptinhalt, aber `lang="en"`, englischer Footer,
sichtbare einzelne Bindestrichzeile und HTML-only Provider-Payload.
- Mailjets aktuelle Accessibility-Empfehlung verlangt die passende
Dokumentsprache und eine lesbare Reintext-Version.
- Der optionale de/en-Chrome-Vertrag gilt für alle React-Templates; der
Web-Wrapper liefert HTML und Text gemeinsam an Queue beziehungsweise Outbox.
- Signup-Welcome, Passwort-Reset und Standard-Mitgliedseinladung erhalten den
Plaintext-Payload. Der bestehende Mailjet-Adapter setzt ihn als `TextPart`.
- Proof: `@hivegrid/mail` 99/99 grün, fokussierte Web-Slices 65/65 grün,
Mail- und Web-Typecheck grün. Screenshot `60-final-welcome-mail-localized-plaintext.png`.
- PR `#336`: vollständige CI `11701` mit 11/11 Jobs grün; normaler Merge
`ab18351309c8e1fcbe21ffc262b5ddb23c822341`.
- Staging-Deploy `11702` grün. Öffentliche Healthchecks von Web, Admin und API
melden jeweils exakt Revision `ab18351309c8e1fcbe21ffc262b5ddb23c822341`.
**MAIL-02: 6/6 DoD = 100 % done. 0 Punkte offen.**
@@ -0,0 +1,163 @@
<!-- markdownlint-disable MD013 MD060 -->
# MAIL-03 · HiveGrid-Systemmails visuell und textlich vereinheitlichen
| | |
| ----------------- | ------------------------------------------- |
| **Typ** | Launch-Härtung · Mail-UX / Branding |
| **Owner** | Raffael |
| **Phase** | Pilot-Härtung · CR-022 |
| **Cycle/Fenster** | gestartet 2026-08-02 |
| **Status** | Done |
| **Plane** | `HIVEGRID-245` · Issue `03e41c05-6b82-4085-8a33-9ad8eead9613` |
## Abhängigkeiten & Parallelität
- **Blocked by:** `MAIL-01`, `MAIL-02` und `I18N-01` sind Done. Mailjet-Zustellung,
HTML-/Plaintext-Transport und der Sechs-Sprachen-Vertrag sind damit vorhanden.
- **Blocks:** konsistentes Systemmail-Erlebnis für Pilotkunden; keine bestehende
Code-Implementierung wird durch dieses Ticket blockiert.
- **Abhängigkeitsschutz:** Sender-Domain, Mailjet, Queue-Namen, Retry,
Idempotenz, Tracking-, Billing- und Datenbankverträge bleiben unverändert.
`I18N_ENABLED_LOCALES` bleibt standardmäßig `de,en`; `pl`, `uk`, `ru` und
`hu` werden durch diese Arbeit nicht freigeschaltet.
- **Plane-Prüfung:** Ticket nach bestätigter Plane-Identität `raffael` als
`HIVEGRID-245` angelegt. Es besitzt keine `blocked-by`-/`blocks`-Relationen.
## Was wir bauen
Alle fest von HiveGrid formulierten Systemmails verwenden einen gemeinsamen,
responsiven Markenrahmen. Dazu gehören insbesondere Signup/Auth, Einladungen,
Billing/Rechnungen, Plattformbenachrichtigungen, Buchungen, Signatur/Abnahme,
Formulare/Double-Opt-in, DSGVO-Export, Customer-Portal-Authentifizierung und
Portal-Lifecycle. Der Rahmen enthält:
- das horizontale HiveGrid-Logo als absolut erreichbares HTTPS-Bild mit
Textfallback und Link zu `https://hivegrid.de`;
- klare Typografie und Informationshierarchie aus Anlass, Headline, Einleitung,
optionaler Detailkarte, eindeutiger Hauptaktion und Sicherheitshinweis;
- lokalisierte Preheader, HTML- und vollständige Plaintext-Versionen;
- einen persönlichen, professionellen Abschluss als HiveGrid-Team;
- Supportkontakt und die unveränderlichen Plattformlinks
`https://hivegrid.de/agb`, `https://hivegrid.de/datenschutz` und
`https://hivegrid.de/impressum`.
Bestehende rohe HTML-/Textpfade werden auf den zentralen Renderer umgestellt.
Tenant-, Projekt-, Termin- und Absenderkontext bleibt sichtbar, ersetzt aber
nicht die HiveGrid-Plattformidentität. Nutzergenerierte Kampagnen-, Workflow-
und Portal-Template-Inhalte werden nicht redaktionell verändert.
## Benötigte Screens
Keine App-Oberfläche. Die E-Mail-Artefakte werden als Desktop- und Mobile-HTML
visuell geprüft. Der abschließende UAT versendet jede feste Kundenvariante wie
im echten Betrieb an das freigegebene Postfach, ohne Testpräfix oder
Testhinweis im sichtbaren Inhalt.
## Definition of Done
- [x] Ein zentraler Mail-Brand-Adapter bildet `@hivegrid/brand` vollständig und
typsicher auf den Mail-Theme-Vertrag ab; Logo, Farben, Support und Links
gehen nicht durch Strukturunterschiede verloren.
- [x] Das zentrale Layout nutzt ein öffentliches horizontales HiveGrid-Logo,
responsive E-Mail-kompatible Styles, abgestufte Textgrößen/-gewichte,
zugängliche Kontraste, aussagekräftige Alt-Texte und einen verlinkten
Textfallback.
- [x] AGB, Datenschutz und Impressum zeigen in jeder Plattform-Systemmail
exakt auf die drei freigegebenen `hivegrid.de`-Ziele; Tenant-Konfiguration
kann diese Plattformlinks nicht überschreiben.
- [x] Signup/Auth, Einladung, Billing/Rechnung und generische Notification-
Templates erhalten die freigegebene persönlich-professionelle Tonalität,
eindeutige CTA-Texte, sinnvolle Preheader, Sicherheits-/Ablaufhinweise und
den Abschluss `Viele Grüße` / `Dein HiveGrid-Team` sinngemäß je Sprache
und Anredeform.
- [x] Alle festen Runtime-Systemmails aus Web und Worker verwenden den
gemeinsamen Renderer statt rohem Ein-Zeilen-HTML/Text; dynamische
Detailwerte sind strukturiert, escaped und in HTML wie Plaintext präsent.
- [x] Alle neuen oder geänderten Texte existieren für `de`, `en`, `pl`, `ru`,
`uk` und `hu`; Formal-Bundles fallen korrekt auf ihre Basissprache zurück.
Keine Zielsprache wird produktiv aktiviert.
- [x] Renderingtests prüfen Logo, Plattformlinks, Preheader, CTA, Textversion,
sichere URLs und das Fehlen roher Keys beziehungsweise unerlaubter
Sprachfallbacks; die festen Kundenvarianten besitzen einen vollständigen
Inventar-/Coverage-Vertrag.
- [x] Desktop- und Mobile-Rendering sind visuell abgenommen; lange lateinische
und kyrillische Texte, deaktivierte Bilder und Dark-Mode-Farbanpassung
bleiben lesbar.
- [x] Fokussierte Tests, `pnpm typecheck`, `pnpm lint`, `pnpm test`,
`pnpm run verify:i18n`, `verify:ci-baseline`, `verify:source-health` und
`verify:secrets` sind grün.
- [x] Alle festen Kundenvarianten wurden ohne Testkennzeichnung an
`raffaelsheikh@protonmail.com` gesendet; Providerannahme und Inbox-
Rendering sind dokumentiert.
**Fortschritt:** 10/10 DoD = 100 % done · 0 Punkte offen.
## Technische Bausteine
- `packages/brand`: kanonische öffentliche Logo- und Plattformlink-Tokens.
- `packages/mail/src/templates-react`: Mail-Theme-Adapter, zentraler Rahmen,
strukturierte Detail-/Hinweis-Komponenten und Renderer.
- `apps/web/app/modules/emails`, Auth-, Booking-, Signatur-, Abnahme-, Formular-
und Portal-Services: bestehende Versender auf den Renderer verdrahten.
- `apps/worker/src/jobs`: Plattformnotification, Portal-Lifecycle, GDPR,
Form-/Transactional-Outbox und Reminder auf denselben Vertrag umstellen.
- `apps/web/public/locales/*/mail.json`: fachliche Mailtexte aller sechs
Basissprachen; Formal-Overrides ausschließlich bei tatsächlicher Abweichung.
## Nicht im Scope
- Keine neue Mailkategorie und keine Änderung nutzergenerierter Kampagnen-,
Workflow-, Sales- oder Portal-Template-Inhalte.
- Kein Provider-, Sender-Domain-, Secret-, Queue-, Retry-, Idempotenz-,
Tracking-, Billing-, Entitlement-, Schema- oder Migrationswechsel.
- Keine Aktivierung von `pl`, `uk`, `ru` oder `hu` in Produktion.
## Rollback
Reiner Code- und Katalog-Rollback auf den vorherigen Renderer und die bisherigen
Versand-Call-Sites. Queue-Payloads bleiben rückwärtskompatibel; es gibt keine
Datenmigration. Bereits zugestellte E-Mails sind externe Artefakte und können
nicht zurückgerufen werden.
## Quellen
- `docs/CHANGE-REQUESTS.md` → CR-022.
- `MAIL-01`, `MAIL-02`, `I18N-01` und `REQ-i18n-six-locale-outbound`.
- User-Freigabe im Chat vom 2026-08-02 für vollständiges Marken-/Text-Polish
und realen Kundenmail-UAT.
## Umsetzungs-Notiz
2026-08-02 · Ticket nach bestätigter Plane-Identität `raffael` als
`HIVEGRID-245` angelegt. Isolierte Session
`feat/mail-system-polish-20260802` basiert exakt auf `origin/main`
`fda162ea2`; die bestehenden schmutzigen Worktrees bleiben unangetastet.
**MAIL-03: 0/10 DoD = 0 % done. Offen: 10 Punkte, davon 0 blockiert.**
2026-08-02 · Umsetzung atomar in `32f04667e` (Mail-Foundation), `88b17bd27`
(Kataloge), `1be0c8623` (Web-Wiring), `cbcc813ba` (Worker-Wiring) und
`51f675b24` (Buchungserinnerungen): zentraler HiveGrid-Mailrahmen mit
öffentlichem Logo, responsiver Typografie, WCAG-AA-Farbkontrasten, unveränderlichen
Plattformlinks, lokalisierten HTML-/Plaintext-Texten und persönlicher Tonalität.
Alle festen Web-/Worker-Systempfade wurden auf den gemeinsamen Renderer
umgestellt. Das ausführbare Inventar umfasst 30 feste Kundenvarianten; Kampagnen,
Workflows und kundeneigene Portal-Templates blieben unverändert.
Prüfnachweis: `pnpm typecheck`, `pnpm lint`, `pnpm test` (1.194 Testdateien,
8.317 Tests grün), `pnpm run verify:i18n` (6 Basis-Locales, 16.542 Keys in
9 Namespaces), `pnpm run verify:i18n-performance` (Delta 45,01 ms / 13,20 MB),
`verify:ci-baseline` (35/35), `verify:source-health` (24/24), `verify:secrets`
und `verify:test-coverage` grün. Die vier Review-Manifeste bleiben auf
`release.status: disabled`; standardmäßig sind weiterhin ausschließlich `de,en`
aktiviert.
Realer Versandnachweis: Mailjet hat am 2026-08-02 alle 30/30 Nachrichten an
`raffaelsheikh@protonmail.com` angenommen. Erste Provider-ID
`98192a83-b346-4dc4-9fce-a70a34c56312`, letzte Provider-ID
`f3909bc0-cd90-4aff-9a98-8e6eb92e44d1`. Sichtbarer Absendername: `HiveGrid`;
Betreff und Inhalt enthalten keine Test-/UAT-Kennzeichnung. Der Empfänger hat
die Inbox-/Sichtprüfung am 2026-08-02 mit „ok passt erstmal“ bestätigt.
**MAIL-03: 10/10 DoD = 100 % done. Offen: 0 Punkte.**
Loaded 100 of 5955 files, more files were not shown because too many files have changed in this diff. Show more