Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
@@ -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
Reference in new issue
Block a user