Update hivegrid-cloud reference to latest main
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
e98d38e716
commit
7b21524c86
3781 files changed
+373484
-225607
No files matched your search
@@ -47,6 +47,43 @@ Das **v1-Fundament der Email-Welt** (Postfach-Sync ist v2 → P23): pro Mandant
|
||||
- `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)
|
||||
|
||||
### 2026-06-29 — Backend-Fundament (S1–S5), ~45 % DoD
|
||||
Branch `feat/AK-P14a` (noch nicht gepusht). Strategie laut Plan: Backend-Fundament jetzt, Kontakt-abhängige Verdrahtung + finale Subframe-UI zurückgestellt (R-P6/R-P7/David offen).
|
||||
|
||||
**Gebaut + verifiziert (alle Typechecks grün, 35 neue Unit-Tests grün):**
|
||||
- **S1 Schema** (`prisma/schema/email.prisma`, additiv, `prisma db push`-bereit, keine Migration): neu `TenantSendingDomain` (RLS, DKIM-Privatkey als per-Tenant-Envelope-Ciphertext AD-8, Soft-Delete, `verificationStatus`, `firstProbeAt`/`lastProbedAt`, `mailjetDnsId`), `EmailSuppressionList` (`@@unique([tenantId,emailAddress])`, `reason`), `EmailTemplate` (`isDefault`/`isDemoData`). Erweitert: `TenantInboundAddress` (`purpose`/`localPart`/`fullAddress`/`enabled`), `EmailSender` (`isDefault`/`isDemoData`/`sendingDomainId`), `Email` (`purpose`/`deliveryStatus`/`relatedKontaktId`/`relatedProjektId` als bare Scalars — FK erst R-P6). RLS: 3 neue Modelle in `TENANT_SCOPED_MODELS` + `prisma/rls/email-isolation.sql` (deferred-cutover wie hr). `prisma validate` + Registry-Test grün.
|
||||
- **S2 DNS-Auto-Probe** (`apps/worker/src/jobs/email-domain-probe-cron.ts` + Handler in `handlers.ts` + Registrierung `index.ts`, Payload-Literal in `queue/payloads.ts`): 5-Min-Cron, DKIM/SPF/DMARC-Lookup (injizierbarer Resolver), Status `pending→verifying→verified|failed`, 7-Tage-Klartext-Key, `notify` bei verified/failed, Write auto-auditiert (M001). 9 Unit-Tests.
|
||||
- **S3 Bounce/Complaint → Suppression**: `packages/db/src/email-suppression.server.ts` (idempotenter Upsert + `isEmailSuppressed`-Pre-Send-Guard) + `apps/api/src/webhooks/mailjet-suppression.ts` (reiner Signal-Parser, Tenant via Mailjet-`Payload`/`CustomID`), additiv in den bestehenden Mailjet-Webhook gehängt (optionaler Dep → keine Regression). 13 Unit-Tests.
|
||||
- **S4 Tracking-Endpoints**: `packages/db/src/email-tracking.server.ts` (`anonymizeTrackingIp` sha256/trunc, `safeRedirectTarget` Open-Redirect-Schutz, `recordEmailOpen`/`recordEmailClick`) + öffentliche Routes `e.o.$outboundEmailId` (1×1-GIF) / `e.c.$outboundEmailId` (302-Redirect). `ipHash` additiv auf Open/Click-Modellen. 8 Unit-Tests.
|
||||
- **S5 Provider-Abstraktion**: `packages/mail/src/mailjet-dns.ts` (`createMailjetDnsProvisioner`: registerDomain/getRecords/check via Mailjet `/v3/REST`, Basic-Auth, injizierbarer fetch, AD-6, kein US-Kern). 5 Unit-Tests.
|
||||
|
||||
**Teilweise (S6) / offen:**
|
||||
- **S6 (angefangen)** — `buildSendingDomainVM` (`packages/view-models/src/email/sending-domain.vm.ts`, 5 Tests grün) ✅. Offen: Domain-Service (`emailDomainService.server.ts`, wiret S1+S5+withTenantRLS), reachable Route + Plain-UI + i18n + Smoke. **Befund:** Modul `email-marketing` existiert bereits inkl. Shell `app.$tenant/email-marketing.tsx` (Gate `requireTenantProductAccess(featureKeys.emailMarketing)`) + Sidebar-Eintrag (`AppSidebar.tsx`, `hasFeatureAccess("email-marketing")`) + `email-marketing/senders.tsx`. → Sende-Domain kommt als gated Tab in dieses Modul; finale Route `/settings/integrations/email` ist Davids UI-Entscheidung (Dev-Nachzug).
|
||||
- **S8 (revidiert)** — Konnektor/Sidebar **existiert bereits** über `featureKeys.emailMarketing` ("email-marketing"); **kein** Eingriff in `@hivegrid/entitlements` nötig (Ticket-`tenantHasModule('email')` = das vorhandene `email-marketing`-Feature). Offen: tenant-seitige Permissions `email.domain.view`/`.manage` in 4 Registries (`DefaultPermissions.ts`, `permissions-seed.server.ts` Array+Rollen-Map, `roleDisplay.ts` scope→`emailDomain`, i18n scopes/actions inkl. `manage`) + i18n-Parität (4 Locales, roleDisplay-Test + verify:i18n als Gates).
|
||||
- **S7** BCC-/Inbound→Activity-am-Kontakt + Lead-Anlage — **blockiert R-P6 (`Kontakt`) / R-P7 (tenant-Lead)**; Empfang/Persistenz machbar, Kontakt-Resolver-Write bleibt markierter Stub.
|
||||
|
||||
### 2026-06-29 (Update) — S6 + S8 umgesetzt
|
||||
- **S6** `emailDomainService.server.ts` (Context+Permission-Gate 404, getSendingDomainState, createSendingDomain via Mailjet-Provisioner S5, setBccLogging, pure normalizeDomainInput/bccAddressFor) + Route `app.$tenant/email-marketing/sending-domain.tsx` (Loader→VM, Actions create-domain/toggle-bcc) + Plain-UI (DNS-Karten+Copy, Status-Ampel, 7-Tage-Klartext, BCC-Toggle, Empty-State, data-ui-id) + Tab im Modul-Shell. **Reachable** über das gated `email-marketing`-Modul.
|
||||
- **S8** Permissions `email.domain.view/.manage` in 4 Registries (DefaultPermissions, permissions-seed Array+Rollen-Map, roleDisplay scope `emailDomain`, i18n en/de) + Domain-Screen-i18n (en/de). Konnektor = vorhandenes Feature `email-marketing` (kein entitlements-Eingriff). roleDisplay-Test (7) + verify:i18n grün, web/db typecheck grün.
|
||||
|
||||
### 2026-06-29 (Merge) — main in Branch + Email-Phasen-Migration (AD-21)
|
||||
`main` in `feat/AK-P14a` gemergt (R-P6 typisierte Kontakte, R-P6B/C, AD-2-Präzisierung). Einzige Konflikte im generierten Prisma-Client → via `pnpm db:generate` aus dem gemergten Schema neu erzeugt (enthält beide Seiten). Kein neuer Entity-Builder-Bezug (AD-2 + Raffaels R-P14C-Ownership eingehalten).
|
||||
|
||||
Der CI-Docker-Smoke (`migrate deploy` gegen leere DB + Seed) schlug fehl (`P2022: TenantInboundAddress.createdAt does not exist`) — die Email-Schema-Änderungen lagen per AD-21 nur als `db push` vor, ohne Migration. Migration **`20260629120000_p14a_email_foundation`** erzeugt (AD-21 „beim Merge"): schema-zu-schema-Diff (merge-base vs. Branch), auf das Email-Delta getrimmt (3 Enums + 3 neue Tabellen + Spalten auf TenantInboundAddress/Email/EmailSender/OutboundEmail* + Indizes), Forward-only mit Inverse-SQL-Kommentar (DoD 28), RLS deferred (Artefakt `prisma/rls/email-isolation.sql`, Muster wie AK-P4a/hr). Verifiziert: `migrate deploy` auf frischer DB grün, Seed läuft komplett durch (`rolesAndPermissions` + entitlements `success`), `prisma validate` grün.
|
||||
|
||||
### 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] 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).
|
||||
|
||||
## Dev-Nachzug (nach Davids `D-KAMP`/`D-P14`-Delta)
|
||||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
|
||||
@@ -49,6 +49,66 @@ Das **vollständige DSGVO-konforme Email-Marketing** (bleibt VOLL inkl. A/B): ei
|
||||
- `designer-briefs/P14-email-marketing.md` (Kampagnen-Editor BESPOKE, Segmente, Unsubscribe-Page)
|
||||
- `_bmad-output/specs/M10-email-marketing.md`
|
||||
|
||||
## Umsetzung (Akeshan)
|
||||
|
||||
### 2026-06-29 — Typisierte Backend-Foundation (S1–S7), ~78 % DoD
|
||||
Branch `feat/AK-P14b` (von `feat/AK-P14a`, noch nicht gepusht). Plan-Entscheidung (User, 2026-06-29):
|
||||
**typisierter Pfad** (neuer Code liest R-P6 `Kontakt`, KEIN neuer Entity-Builder-Konsument, AD-2) +
|
||||
**Backend-Foundation jetzt**, bespoke Editor/Unsubscribe-Page + Lead/Projekt-Segment-Dimensionen + e2e/Visual
|
||||
zurückgestellt. Der bestehende Entity-Builder-Kampagnen-Pfad (`CrmService`/`EntityViewsApi`/
|
||||
`OutboundEmail.contactRowId`) bleibt **unangetastet** (gehört R-P14C).
|
||||
|
||||
**Gebaut + verifiziert (46 neue Unit-Tests grün, alle Typechecks 0 Fehler, verify:i18n exit 0):**
|
||||
- **S1 Schema** (`prisma/schema/email.prisma`, additiv, `db push`, keine Migration — AD-21): neu `RecipientSegment`
|
||||
(+`SegmentSnapshotMember`), `CampaignVariant` (A/B), `KontaktMarketingConsent` (in email.prisma, **nicht**
|
||||
crm.prisma), `Unsubscribe`; `Campaign` (+`recipientSegmentId`/`scheduledAt`/`timezone`/`previewText`/
|
||||
`footerHtml`/`isDemoData`/`archivedAt`), `OutboundEmail` (+`kontaktId`/`campaignVariantId`/`unsubscribeToken`/
|
||||
`trackingToken`). Bare `tenantId`/`kontaktId`-Scalars. RLS-Artefakt `prisma/rls/email-isolation.sql` +
|
||||
`TENANT_SCOPED_MODELS`-Registry nachgezogen. `models.test.ts` (11) grün.
|
||||
- **S2 Segment-Engine** (typisiert, Kontakt-only): pure `segmentFilter.ts` (Validierung Tiefen-/Node-Cap,
|
||||
Lookup-Collection, JSONB→`Prisma.KontaktWhereInput`) + `SegmentService.server.ts` (Lookup-Auflösung Tag/
|
||||
Custom-Feld, Auto-Exclusion archiviert/keine-Email/Unsubscribe/Suppression/kein-Double-OptIn als
|
||||
non-overlapping Breakdown, Live-Count+Sample, Snapshot). 13 Tests.
|
||||
- **S3 Versand-Engine**: pure `personalization.ts` (Token inkl. `cf.<key>`, idempotente Footer-Injektion) +
|
||||
`campaignSendPlan.ts` (A/B per d'Hondt interleaved, Throttle→BullMQ-`delay`, timezone-`startAt`) +
|
||||
`CampaignSendService.server.ts` (Audience→harter Checklisten-Gate→Suppression-Re-Check→OutboundEmail-Row→
|
||||
ein `mail.transactional`-Job je Empfänger mit List-Unsubscribe-Header; kein neuer Worker-Queue). 14 Tests.
|
||||
- **S4 Double-Opt-In + Ein-Klick-Abmeldung**: `marketingToken.server.ts` (HMAC unsub/optin, 5 Tests) +
|
||||
`ConsentService.server.ts` (startDoubleOptIn/confirmOptIn/unsubscribeKontakt, idempotent) + public Routes
|
||||
`optin.$token` + `unsubscribe.$token` (erweitert um Marketing-Token, RFC-8058 One-Click). i18n `marketing.optin.*`.
|
||||
- **S5 VMs** (`packages/view-models/src/email/`, pure): `presend-checklist.vm` (kanonischer Checklisten-Kern,
|
||||
von der Send-Engine importiert), `campaign-detail.vm` (KPI%/Klick-Map/Pro-Empfänger/A-B), `campaign-list.vm`,
|
||||
`segment.vm`. 7 Tests.
|
||||
- **S6 Permissions**: `emailMarketing.view/.manage` in 4 Registries (permissions-seed Array+Rollen-Map,
|
||||
DefaultPermissions, roleDisplay-Scope, i18n en/de). roleDisplay.test (7) grün.
|
||||
- **S7 Segmente-Route** (`app.$tenant/email-marketing/segments.tsx`, reachable, gated, i18n en/de, Empty-State):
|
||||
Liste + Erstellen aus AND/OR-Filter + Live-Preview gegen typisierte Kontakte. Tab im Modul-Shell.
|
||||
|
||||
**Proof:** 46/46 neue Unit-Tests grün; `@hivegrid/web`+`@hivegrid/db`+`@hivegrid/view-models`+`@hivegrid/cli`
|
||||
typecheck 0 Fehler; `prisma validate` + `db push` (lokal) grün; `verify:i18n` exit 0 (Parität en/de);
|
||||
hardcoded-strings auf Baseline; lefthook pre-commit je Commit grün. 7 Commits (S1–S7) auf `feat/AK-P14b`.
|
||||
|
||||
### DoD-Stand
|
||||
- [~] Block-/Rich-Text-Editor + Tokens (inkl. Custom-Felder) + Pflicht-Footer + Desktop/Mobile-Vorschau —
|
||||
Token-/Footer-Logik ✅ (pure, getestet); Rich-Text-Editor + Vorschau-UI **blockiert (David D-KAMP)**.
|
||||
- [x] Segmente: verschachtelter AND/OR-Baum, Live-Auflösung, Auto-Exclusion, dynamisch/statisch — ✅
|
||||
(Kontakt-Dimensionen). Lead/Projekt-Dimension **blockiert (R-P7/R-P8 offen)**.
|
||||
- [x] Versand-Engine (BullMQ, Rate-Limit/Throttling, timezone-Scheduling) — ✅ (Throttle via per-Empfänger-
|
||||
`delay`-Spreizung; worker-seitiger Limiter unverändert).
|
||||
- [~] Double-Opt-In + Suppression-Check vor Versand + One-Click-Unsubscribe + List-Unsubscribe-Header — ✅
|
||||
Kern; volle Form-Widget-Verdrahtung (Submission→Opt-In-Mail-Trigger) **teilweise** (Service da, Auto-Trigger offen).
|
||||
- [x] Pflicht-Checkliste (Domain/Unsub/Impressum/Subject/>0/Daily-Cap) + Block + Fix-Link — ✅ Logik + harter
|
||||
Server-Gate; Checklisten-**UI** Teil des bespoke Editors (blockiert David).
|
||||
- [x] Reporting (Open/Click/Bounce/Abmeldung %, Klick-Map, Pro-Empfänger) + A/B-Varianten — ✅ VMs + A/B-Schema/
|
||||
-Versand; Reporting-**UI** blockiert (David).
|
||||
- [x] Konnektor `tenantHasModule('email')` + RLS + `is_demo_data` — ✅ (Feature `email-marketing` + RLS-Artefakt
|
||||
+ `emailMarketing.*`-Permissions).
|
||||
|
||||
**Stand: 5/7 DoD voll + 2 partiell ≈ ~78 % done.** Extern blockiert: bespoke Kampagnen-Editor + Reporting-UI +
|
||||
Unsubscribe-Page-Branding (Davids `D-KAMP`/`D-P14`-Delta), Lead/Projekt-Segmentdimension (R-P7/R-P8), e2e-Smoke
|
||||
(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).
|
||||
|
||||
## Dev-Nachzug (nach Davids `D-KAMP`/`D-P14`-Delta)
|
||||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
|
||||
@@ -15,7 +15,7 @@
|
||||
- **Konflikt-Risiko:** gering — additive Tabellen; `apps.prisma` + `crm.prisma` nur lesend für Relationen.
|
||||
|
||||
## 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** (Whisper-Diktat ist v2) und eine Recording-Anzeige. **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` (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).
|
||||
|
||||
## Benötigte Screens (Backend bedient — Design liefert `D-CHAT` + `D-P15`)
|
||||
| Screen [Route] | Kern-Inhalt |
|
||||
|
||||
@@ -11,11 +11,11 @@
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `AK-P15a` (P15-Vorlauf), `AK-P4a` (Files — Chat-Anhänge via FileEntityLink)
|
||||
- **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/Deal aus dem CRM-Kern (R-P6/P8) read-only. **Sync-Punkt:** ProjektMitglied-Sync braucht den Projekt-Kern (P8/P9).
|
||||
- **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.
|
||||
|
||||
## 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/Deal mit ProjektMitglied-Sync), **@Mentions** (User/Projekt/Deal/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), **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.
|
||||
|
||||
## Benötigte Screens (Backend bedient — Design liefert `D-CHAT` + `D-P15`)
|
||||
| Screen [Route] | Kern-Inhalt |
|
||||
@@ -29,10 +29,10 @@ Den **Real-Time-Team-Chat (Bespoke, AD-9)**: WebSocket-Messaging mit **Presence,
|
||||
|
||||
## 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/Deal) mit **ProjektMitglied-Sync**
|
||||
- [ ] **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-/Deal-Detail (P8/P9)
|
||||
- [ ] 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
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
| **Owner** | Akeshan |
|
||||
| **Phase** | P16 — Kalender, Booking, Forms & Signatur |
|
||||
| **Cycle/Fenster** | W4 — USP, Härtung & Launch · fällig 2026-07-04 · Gate W4 |
|
||||
| **Status** | geplant |
|
||||
| **Status** | in Arbeit (~83 % DoD, Backend+Routen+Sync+Worker+Write-Pfad fertig; Rest David D-P16/D-BOOK + Staging-DB) |
|
||||
|
||||
## 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`)
|
||||
@@ -25,12 +25,12 @@ Den **bidirektionalen Kalender-Sync mit Google** (Outlook-Adapter → v2, Interf
|
||||
| Kalender-Verbindungs-Detail [`/settings/integrations/calendar/:id`] | gewählte Kalender, Sync-Status, Konflikt-Liste (letzte 50, Klartext + Resolution) |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **Bidirektionaler Google-Sync** (CalendarAdapter, Auto-Token-Refresh, Webhook-Subscriptions); Outlook → v2 (Interface provider-agnostisch)
|
||||
- [ ] HiveGrid-Termine (Booking/Projekt/Plantafel) gehen **extern**, externe Events kommen **read-only** für Verfügbarkeit
|
||||
- [ ] **Connection pro User**; externe Event-Inhalte nie an andere User leaken (nur „belegt von X bis Y")
|
||||
- [ ] **Last-Write-Wins-Konflikt** mit Klartext-Notification + Konflikt-Log (letzte 50)
|
||||
- [x] **Bidirektionaler Google-Sync** (CalendarAdapter, Auto-Token-Refresh, Webhook-Subscriptions); Outlook → v2 (Interface provider-agnostisch)
|
||||
- [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)
|
||||
- [ ] Konnektor `tenantHasModule('calendar')`; RLS auf allen Tenant-Tabellen; OAuth verschlüsselt (AD-8, via Apps-Engine)
|
||||
- [x] Konnektor `tenantHasModule('calendar')`; RLS auf allen Tenant-Tabellen; OAuth verschlüsselt (AD-8, via Apps-Engine)
|
||||
|
||||
## 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).
|
||||
@@ -50,3 +50,73 @@ Den **bidirektionalen Kalender-Sync mit Google** (Outlook-Adapter → v2, Interf
|
||||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
- [ ] Plane-Ticket `AK-P16a` aktualisiert
|
||||
|
||||
## Umsetzungs-Notiz (2026-06-30, Akeshan) — ~70 % DoD
|
||||
|
||||
Branch `feat/AK-P16a`, 6 lokale Commits (`ca0a410` → `4ac8cb07`), nichts gepusht,
|
||||
Plane-Status unverändert. Alle Verifikations-Gates grün: `pnpm prisma validate`,
|
||||
`@hivegrid/{web,db,view-models,integrations}` typecheck **0 Fehler**, `verify:i18n`
|
||||
exit 0, **36 Calendar-Tests grün** (8 Files: availability 8, conflict 6, mapping 3,
|
||||
oauthState 5, webhook-renewal 5, VM 5, auth-boundary 2, drift 2). lefthook pre-commit
|
||||
je Commit grün.
|
||||
|
||||
**DoD-Stand:**
|
||||
- [x] **Connection pro User + Leak-Schutz (DoD 3)** — `calendar.prisma` per-User,
|
||||
`availability.ts` exponiert nur Busy-Intervalle (getestet), Owner-Check im Guard.
|
||||
- [x] **Konnektor + RLS + OAuth verschlüsselt (DoD 6)** — Gate via
|
||||
`tenantHasModule('integrations')` (Freigabe 2026-06-29: Kalender = Apps-Engine-
|
||||
Integration), `calendar-isolation.sql` (deferred cutover), Token-Seal per-Tenant-DEK
|
||||
(AD-8).
|
||||
- [~] **Bidirektionaler Sync (DoD 1)** — CalendarAdapter + Google-REST/OAuth-Client
|
||||
(fetch, kein SDK), Auto-Token-Refresh (Adapter + `ensureFreshCreds`), Webhook
|
||||
subscribe (Connect) + receive (`/webhooks/calendar/google`) + Renewal-Entscheidung.
|
||||
**Offen:** Worker-Cron (Refresh/Renewal/Webhook-Drain) + HiveGrid→extern Write-Pfad.
|
||||
- [~] **HiveGrid extern / externe read-only (DoD 2)** — externer Delta→Cache-Sync
|
||||
(Cursor, 410→Full-Resync) fertig + Initial-Sync nach Connect. **Offen:** Write-Pfad
|
||||
HiveGrid→Google (`CalendarWriteService`). **Update 2026-06-30 (AK-P16b gemerged-ready):**
|
||||
AK-P16b legt nun je Buchung ein lokales `CalendarEvent` (`source: hivegrid_internal`,
|
||||
`isBusyForAvailability`) an → die Quell-Events für den Write-Pfad **existieren jetzt**;
|
||||
der Write-Pfad ist damit **entsperrt** (nur noch P9/Plantafel offen). Bauen bleibt
|
||||
AK-P16a-Scope (Nachzug), schließt zugleich AK-P16b-DoD-2-extern.
|
||||
- [~] **Last-Write-Wins + Konflikt-Log (DoD 4)** — Resolver-Logik (getestet) +
|
||||
`CalendarConflict`-Tabelle + Detail-VM mit Konflikt-Liste. **Offen:** Persistenz +
|
||||
`notify()` am Write/Mapped-Pfad (entsteht mit dem Write-Pfad).
|
||||
- [~] **Kalender-Ansicht Quell-Marker (DoD 5)** — erreichbare Route `/calendar` + VM
|
||||
mit Quell-Markern. **Blockiert:** bespoke Monats-/Wochen-Grid → David `D-P16`
|
||||
(+ Visual-Regression, Hot-Swap-Adapter).
|
||||
|
||||
**Selbst machbar offen:** Worker-Crons (Architektur-Entscheid: Sync-Orchestrierung
|
||||
liegt in `apps/web`, Worker kann sie nicht importieren — entweder nach
|
||||
`packages/integrations` ziehen oder interner Trigger-Endpoint), `CalendarWriteService`
|
||||
+ Konflikt-Persistenz. **Extern blockiert:** bespoke UI (David `D-P16`), `db push` +
|
||||
RLS-Live-Check + Visual-Regression (Staging-DB), Live-OAuth (EXT-15-Google-Verify).
|
||||
|
||||
**Hinweise:** Redirect-URI an EXT-10 ausgerichtet (`/integrations/google/oauth/callback`,
|
||||
App-Root). Env-Var-Namen `GOOGLE_CALENDAR_CLIENT_ID/_SECRET/_REDIRECT_URI` +
|
||||
`GOOGLE_CALENDAR_WEBHOOK_URL` — Coolify-Abgleich beim Live-Test nötig. Connect/Disconnect
|
||||
sind Account-Events → Audit (M001-Middleware), kein Activity-Stream (CRM-Subject-only).
|
||||
|
||||
## Umsetzungs-Notiz (2026-06-30, Akeshan) — ~83 % DoD
|
||||
|
||||
Nachzug für den übrig gebliebenen AK-P16a-Teil auf `feat/AK-P16a`: Worker-Crons
|
||||
und Maintenance-Handler für `calendar-token-refresh`, `calendar-webhook-renewal`,
|
||||
`calendar-webhook-drain` und `calendar-internal-write-sync` ergänzt. Die
|
||||
Calendar-Orchestrierung liegt jetzt worker-sicher in `@hivegrid/integrations`
|
||||
(`calendar-worker-tasks.server`) und importiert keine `apps/web`-Module. Der
|
||||
Write-Pfad spiegelt lokale `CalendarEvent`-Rows (`source: hivegrid_internal`,
|
||||
aktuell aus AK-P16b-Bookings) nach Google, persistiert `CalendarEventMapping`,
|
||||
zieht Updates/Deletes nach und schreibt bei Provider-ETag-Konflikten
|
||||
`CalendarConflict` + In-App-Notification mit `calendar.conflict.*`.
|
||||
|
||||
**DoD-Stand:** 5/6 DoD = ~83 % done. Selbst machbarer Backend-Rest ist erledigt.
|
||||
Offen bleibt DoD 5 als extern blockiert: bespoke Monats-/Wochen-Grid mit
|
||||
Quell-Markern und Visual-/Hot-Swap-Abschluss warten auf David `D-P16`/`D-BOOK`.
|
||||
Staging-DB-Checks (`db push`, RLS-Live) bleiben wie bisher env-blockiert; keine
|
||||
Migration auf dem Branch erzeugt (AD-21).
|
||||
|
||||
**Proof grün:** `pnpm prisma validate`; `@hivegrid/{db,queue,integrations,worker,web,view-models}`
|
||||
typecheck; `pnpm run verify:i18n`; gezielte Vitest-Suite **40 Tests grün**
|
||||
(Calendar Services/Auth 24, Calendar Worker/Cron 3, Webhook-Renewal 5,
|
||||
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.
|
||||
@@ -6,7 +6,7 @@
|
||||
| **Owner** | Akeshan |
|
||||
| **Phase** | P16 — Kalender, Booking, Forms & Signatur |
|
||||
| **Cycle/Fenster** | W4 — USP, Härtung & Launch · fällig 2026-07-05 · Gate W4 |
|
||||
| **Status** | geplant |
|
||||
| **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) |
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `AK-P16a` (Kalender-Sync — Slot-Verfügbarkeit braucht Busy-Slots aus Google)
|
||||
@@ -27,13 +27,13 @@
|
||||
| Verfügbarkeit [`/availability`] | Wöchentliche Standard-Regeln (mehrere Zeitfenster/Tag), Datums-Ausnahmen (frei/Custom-Window), Timezone |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] Ö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
|
||||
- [ ] **iFrame-Embed** + Public-URL mit Copy
|
||||
- [ ] 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
|
||||
- [ ] Permission-Bundle `bookings.*` (read_own/read_all/write/admin) serverseitig Owner-gefiltert
|
||||
- [ ] Konnektor `tenantHasModule('booking')`; RLS auf allen Tenant-Tabellen
|
||||
- [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] **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] 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)*
|
||||
|
||||
## 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).
|
||||
@@ -53,3 +53,105 @@
|
||||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
- [ ] Plane-Ticket `AK-P16b` aktualisiert
|
||||
|
||||
## Umsetzungs-Notiz (2026-06-30, Akeshan) — ~85 % DoD
|
||||
|
||||
Branch `feat/AK-P16b` (von `feat/AK-P16a` abgezweigt, AD-21), **8 Commits** (`fecf6f19f`
|
||||
→ `b262dabe8`), nicht gepusht, Plane-Status unverändert. Alle Verifikations-Gates grün:
|
||||
`pnpm prisma validate`, `@hivegrid/{web,db,view-models,entitlements,queue}` +
|
||||
`@hivegrid/activity` typecheck **0 Fehler**, `verify:i18n` (i18n-check) exit 0,
|
||||
**26 Booking-Unit-Tests grün** (slotEngine 11, ics 5, transitions 5, VM 3,
|
||||
auth-boundary 2). lefthook pre-commit je Commit grün.
|
||||
|
||||
**4 Forks (User-Freigabe 2026-06-30):** (1) Lead-Gap → Kontakt-Match/Create +
|
||||
`logActivity`, `leadId` reserviert R-P7. (2) Intake-Gap → `intakeAnswers` Json am
|
||||
Appointment, `formSubmissionId` reserviert AK-P16c. (3) Modul-Gate → eigener
|
||||
`booking` Feature-Key (`tenantHasModule('booking')`). (4) Scope → Backend +
|
||||
funktionale Routen inkl. minimal-funktionaler öffentlicher Strecke.
|
||||
|
||||
**DoD-Stand:**
|
||||
- [x] **Slot-Engine timezone-aware (DoD 1)** — `slotEngine.ts` pure (Regeln/Ausnahmen,
|
||||
Buffer, min-notice/max-advance, Increment, `first_available`-Union); Google-Busy
|
||||
via AK-P16a `availability.ts` (leak-safe). 11 Tests inkl. DST. `/b/{tenant}/{slug}`.
|
||||
- [~] **Post-Booking + Race (DoD 2)** — Serializable-Tx Slot-Re-Check + Postgres
|
||||
`EXCLUDE USING gist`-Backstop (`booking-constraints.sql`); Kontakt-Match/Create +
|
||||
`appointment_scheduled`-Activity; `intakeAnswers` Json; lokales CalendarEvent;
|
||||
Bestätigungsmail + **.ics-Attachment** (`buildIcs` pure). **Offen:** echte
|
||||
`FormSubmission` (AK-P16c), echtes CRM-`Lead` (R-P7) — bewusst reserviert.
|
||||
- [x] **iFrame-Embed + Public-URL (DoD 3)** — `/b/.../embed` (frame-ancestors) +
|
||||
Embed-Code-Generator + Public-URL-Copy im Page-Editor.
|
||||
- [x] **Eine Strategie (DoD 4)** — `first_available` implementiert; Enum trägt alle 3
|
||||
(round_robin/specific_provider_choice → v2, additiv).
|
||||
- [~] **Lifecycle M129 (DoD 5)** — `BookingLifecycleService`: held/no_show/cancel/
|
||||
reschedule/reassign mit lokalem CalendarEvent-Nachzug + Auto-Mail + Activity +
|
||||
`notify()`; Detail-Route mit held/no_show/cancel-Actions (CSRF+Owner). **Offen:**
|
||||
Reschedule-/Re-Assign-**Picker-UI** (Slot-/Provider-Auswahl) → David D-P16.
|
||||
- [x] **bookings.* owner-gefiltert (DoD 6)** — 4 Registries, `bookingAccess.server.ts`
|
||||
(Modul-Gate + Permission + Appointment-Owner-Check, 404 statt 403), Liste
|
||||
server-seitig owner-gefiltert. Auth-Boundary-Test.
|
||||
- [x] **Konnektor + RLS (DoD 7)** — `booking` Feature-Key + Gate; `booking-isolation.sql`
|
||||
(deferred Cutover wie Kalender), `booking-constraints.sql` (gist + btree_gist).
|
||||
|
||||
**Selbst machbar offen (~15 %):** `/availability`-Editor-UI (M06 F — Modelle +
|
||||
Slot-Engine konsumieren Verfügbarkeit bereits; nur die Pflege-Oberfläche fehlt) ·
|
||||
Reschedule/Re-Assign-Picker-Verdrahtung. **Staging-DB-blockiert:** `prisma db push` +
|
||||
`psql -f booking-constraints.sql` + RLS-Live-Check + **Race-Integrationstest**
|
||||
(db-gated) — lokal keine DB gestartet, wie AK-P16a deferred. **David D-P16-blockiert:**
|
||||
bespoke öffentliche Booking-Page + Reschedule-Picker + Visual-Regression (DoD 21) +
|
||||
Hot-Swap-Drill (DoD 20).
|
||||
|
||||
**Hinweise:** Mail-Attachment-Durchreichung im Queue-Provider ergänzt (Payload trug
|
||||
`attachments` bereits, nur der Provider-Hop ließ sie fallen). 3 Booking-Activity-Typen
|
||||
(`appointment_cancelled/rescheduled/no_show`) zur Activity-Union ergänzt. Connect/
|
||||
Lifecycle sind CRM-Subject-Activities (kein eigenes Booking-Subject).
|
||||
|
||||
## Umsetzungs-Notiz (2026-07-01, Raffael) — ~90 % gewichtet, 5/7 DoD vollständig
|
||||
|
||||
Direkt auf `main` serverseitig nachgezogen, um den ohne Screens selbst machbaren
|
||||
P16b-Rest zu maximieren.
|
||||
|
||||
**Nachzug:**
|
||||
- Public Booking erzeugt bei fehlendem Kontakt jetzt ein echtes `InboxLead` über
|
||||
`createLead(...)`, verknüpft es über `Appointment.leadId` und schreibt die Activity
|
||||
auf Kontakt oder Lead. Der alte automatische Kontakt-Create ist raus.
|
||||
- Detail-Route akzeptiert serverseitig die M129-Intents `reschedule` und `reassign`
|
||||
mit `bookings.write` bzw. `bookings.admin`; die Picker-UI bleibt D-P16-blockiert.
|
||||
- `AvailabilityService.server.ts` ergänzt den atomaren Replace-/Read-Contract für
|
||||
`AvailabilityRule`/`AvailabilityException` inkl. Zeitfenster-, Datum- und
|
||||
Timezone-Validierung. Die `/availability`-Oberfläche bleibt screen-blockiert.
|
||||
- Tests ergänzt: Availability-Service-Unit-Test, Post-Booking-Static-Guard,
|
||||
Lifecycle-Action-Authorization-Guard.
|
||||
|
||||
**DoD-Stand nach Nachzug:**
|
||||
- Vollständig abgehakt: DoD 1, 3, 4, 6, 7 = **5/7 vollständig**.
|
||||
- Teilfertig: DoD 2 ist serverseitig bis auf echte `FormSubmission` erledigt
|
||||
(`AK-P16c`); DoD 5 ist serverseitig erledigt, aber Reschedule/Reassign-Picker-UI
|
||||
wartet auf David D-P16.
|
||||
- Offen/blockiert: echte `FormSubmission` (`AK-P16c`), D-P16-Screens/Visuals,
|
||||
Staging-DB-Cutover (`prisma db push`, `booking-constraints.sql`, RLS-Live-Check,
|
||||
Race-Integrationstest).
|
||||
|
||||
**Proof lokal:** `pnpm exec vitest run apps/web/app/modules/booking/services/AvailabilityService.server.test.ts apps/web/app/modules/booking/services/booking-postbooking-boundary.test.ts apps/web/app/modules/booking/routes/booking-auth-boundary.test.ts` → 8/8 grün; `pnpm typecheck` → grün.
|
||||
|
||||
## Umsetzungs-Notiz (2026-07-01, Raffael) — ~92 % gewichtet, selbst machbarer Server-Rest erledigt
|
||||
|
||||
Noch ohne Screens nachgezogen:
|
||||
- `BookingPage.intakeFormId` wird im Public-Booking-Resolve mitgeladen.
|
||||
- Public Booking schreibt innerhalb derselben Serializable-Transaktion eine echte
|
||||
`FormSubmission`, sobald die BookingPage ein Intake-Form referenziert, und verlinkt
|
||||
`Appointment.formSubmissionId`. Ohne `intakeFormId` bleibt `intakeAnswers` der
|
||||
Fallback, damit bestehende BookingPages nicht brechen.
|
||||
- Statische DB-Artefakt-Guards ergänzt: `booking-constraints.sql` muss die
|
||||
`appointment_no_overlap`-Exclusion-Constraint für `scheduled`/`held` enthalten;
|
||||
`booking-isolation.sql` muss alle fünf Booking-Tabellen mit RLS/FORCE/GUC-Policy
|
||||
und `hivegrid_app`-Grant abdecken.
|
||||
|
||||
**DoD-Stand nach Nachzug:**
|
||||
- DoD 2 ist serverseitig maximal: Lead/Activity, FormSubmission bei konfiguriertem
|
||||
Intake-Form, .ics-Mail, Serializable Slot-Re-Check und SQL-Backstop sind vorhanden.
|
||||
Vollständig grün wird der Punkt erst mit AK-P16c-Renderer/Form-Auswahl und echter
|
||||
Staging-DB-Ausführung.
|
||||
- DoD 5 bleibt screen-blockiert für den Reschedule-/Reassign-Picker; Service und
|
||||
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.
|
||||
@@ -6,7 +6,7 @@
|
||||
| **Owner** | Akeshan |
|
||||
| **Phase** | P16 — Kalender, Booking, Forms & Signatur |
|
||||
| **Cycle/Fenster** | W4 — USP, Härtung & Launch · fällig 2026-07-06 · Gate W4 |
|
||||
| **Status** | geplant |
|
||||
| **Status** | Dev-Anteil umgesetzt · Design-Delta 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")
|
||||
@@ -26,13 +26,47 @@ Einen Drag-&-Drop-**Form-Builder auf Google-Forms-Niveau**: **12 Feld-Typen**, *
|
||||
| Submissions [`/forms/:id/submissions`] | Antwort-Tabelle (Spalten = Felder), Filter, CSV; Detail: alle Antworten, Submitter-Metadata, **Action-Log mit Re-Run**, File-/Foto-Vorschau, PDF-Export |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **12 Feld-Typen** + **Conditional Logic** + Validierung pro Feld + geseedete **SHK-Templates** + Live-Vorschau
|
||||
- [ ] **Embed**: öffentliche URL + QR + iFrame (personalisierte Links / JS-Snippet → v2)
|
||||
- [ ] **Post-Submit-Actions** (Lead/Kontakt/Projekt/Task, Email, Webhook, Automation-Trigger, Auto-Match) mit **Field-Mapping** + **ActionLog** (Re-Run)
|
||||
- [ ] **Rate-Limit + mCaptcha + DSGVO-Pflicht** auf öffentlichen Endpunkten; Race-Schutz beim Submit
|
||||
- [ ] **Form-Renderer als wiederverwendbare Komponente** (Booking-Intake, HR-Anträge)
|
||||
- [ ] Permission-Bundle `forms.*` (basic/builder/publisher/admin) serverseitig Owner-gefiltert
|
||||
- [ ] Konnektor `tenantHasModule('forms')`; RLS auf allen Tenant-Tabellen
|
||||
- [x] **12 Feld-Typen** + **Conditional Logic** + Validierung pro Feld + geseedete **SHK-Templates** + Live-Vorschau
|
||||
- [x] **Embed**: öffentliche URL + QR + iFrame (personalisierte Links / JS-Snippet → v2)
|
||||
- [x] **Post-Submit-Actions** (Lead/Kontakt/Projekt/Task, Email, Webhook, Automation-Trigger, Auto-Match) mit **Field-Mapping** + **ActionLog** (Re-Run)
|
||||
- [x] **Rate-Limit + mCaptcha + DSGVO-Pflicht** auf öffentlichen Endpunkten; Race-Schutz beim Submit
|
||||
- [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
|
||||
|
||||
## Umsetzungs-Notiz
|
||||
|
||||
**2026-07-01:** AK-P16c umgesetzt auf Branch `feat/AK-P16c-complete`.
|
||||
|
||||
- Form-Datenmodell in `prisma/schema/formWidget.prisma` erweitert (`FormField`, `FormFile`, `FormAction`, `FormActionLog`, Slug/Status/Subtype/Public-Flags, Submission-Idempotency/GDPR/Linked-Entity). Keine Migration erzeugt, AD-21 Feature-Branch-Regel eingehalten; Prisma Client regeneriert.
|
||||
- Form-Widget-Schema auf 12 Feldtypen plus Honeypot gehoben, Conditional-Logic-Engine mit Tests ergänzt und Entity-Builder/`entity-row` aus dem Routing-Kontrakt entfernt.
|
||||
- Web-Builder erweitert: Palette, Feldvalidierung, Conditional-Logic-Editor, Live-Vorschau, SHK-Template-Upsert, Public URL `/f/{tenant}/{slug}`, QR/iFrame, Publish/Re-Run, Owner-Filter und `forms.*` Permissions.
|
||||
- Public Submit gehärtet: Origin-Allowlist, Rate-Limit, mCaptcha, DSGVO-Pflicht, sichtbarkeitsgefilterte Validierung, Idempotency-Key/Race-Schutz und Outbox-Publish.
|
||||
- Worker-Pipeline erweitert: Post-Submit-Actions für Auto-Match, Lead/Kontakt/Projekt/Task, Team-/Submitter-Mail, Webhook und Automation-Trigger mit `FormActionLog`.
|
||||
- Feature/Permission-Wiring ergänzt: Entitlements, Rollen-Seed, Sidebar, UI-Registry, Tenant-Isolation-Report/RLS-Datei.
|
||||
|
||||
**2026-07-01 Nachzug selbst machbarer Rest:** Admin-Konfiguration für `FormAction` im Builder ergänzt und Save-Action synchronisiert `FormAction`-Rows. Public Submit akzeptiert multipart Uploads fuer Datei-/Foto-Felder, persistiert `File`/`FormFile`/`FileEntityLink`, queued Scan/Preview und haelt das JSON-Payload-Limit getrennt vom Upload-Request-Limit. Submissions-Ansicht zeigt feldbasierte Antwort-Tabelle mit Statusfilter, CSV/PDF-Export, Submitter-Metadata, ActionLog/Re-Run und Datei-Links. Public Renderer aus den Routes nach `apps/web/app/modules/forms/public/PublicFormRenderer.tsx` extrahiert; `/embed/forms/:formKey` und `/f/:tenant/:slug` nutzen denselben Renderer. Builder-Save synchronisiert `FormField`-Rows aus der Definition.
|
||||
|
||||
**Proof:** `pnpm exec prisma validate`; `pnpm --filter @toolctrl/web typecheck`; `pnpm --filter @toolctrl/worker typecheck`; `pnpm --filter @toolctrl/form-widget test`; `pnpm exec vitest run apps/worker/src/jobs/form-submission-route.test.ts apps/worker/src/index.test.ts packages/entitlements/src`; `pnpm exec vitest run apps/web/app/modules/formWidget/builder 'apps/web/app/routes/api.embed.forms.$formKey.submit.test.ts' 'apps/web/app/routes/app.$tenant/forms.$id.defaults.test.ts' 'apps/web/app/routes/app.$tenant/forms.$id.action.test.ts' 'apps/web/app/routes/app.$tenant/forms.$id.i18n.test.ts'`; `pnpm lint`.
|
||||
|
||||
**Stand:** 7/7 Dev-DoD grün = 100 % selbst machbarer Dev-Anteil. Ticket noch nicht final Done, solange Davids `D-FORM`/`D-P16` Design-Delta und der anschliessende Doku-/Plane-Abgleich offen sind.
|
||||
|
||||
**Push-Status:** Commit/Push erfolgt auf User-Kommando am 2026-07-01; exakten Hash siehe Git-Historie/Push-Bestaetigung.
|
||||
|
||||
**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.
|
||||
|
||||
## 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.
|
||||
|
||||
**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.
|
||||
|
||||
**Bewusst v2 laut Ticket-Text:**
|
||||
- Personalisierte Links/FormLink bleiben v2.
|
||||
- JS-Snippet ist laut Ticket-Text v2; v1 deckt Public URL, QR und iFrame ab.
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (eigene `prisma/schema/forms.prisma`): `Form` (slug, subtype standard/acceptance_form/onboarding/survey, status, is_public), `FormField` (field_key, field_type 12 Typen, required, validation_rules), `FormSubmission` (submission_data JSON, linked_entity_type/id polymorph), `FormFile` (→ File), `FormAction` (action_type send_email/create_lead/create_projekt/webhook/trigger_automation, action_config). `crm.prisma`/`tasks.prisma`/`automation.prisma` nur über Actions berührt (AD-21).
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# AK-P16d · P16 Angebot/Signatur (PandaDoc)
|
||||
# AK-P16d · P16 Angebot/Signatur (SES-Default + BYOK-Adapter)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
@@ -6,14 +6,13 @@
|
||||
| **Owner** | Akeshan |
|
||||
| **Phase** | P16 — Kalender, Booking, Forms & Signatur |
|
||||
| **Cycle/Fenster** | W4 — USP, Härtung & Launch · fällig 2026-07-07 · Gate W4 |
|
||||
| **Status** | geplant |
|
||||
| **Status** | in Umsetzung |
|
||||
|
||||
> ⚠️ **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
|
||||
> optionaler BYOK-Adapter** (`pandadoc-byok`, Tenant bringt eigenen Key) — Anbindungs-Spec in [[EXT-17]]. Dieses
|
||||
> Ticket bitte entsprechend bauen: **SES als Default** (Touch vor Ort + Fern-Link + OTP + PAdES-Versiegelung +
|
||||
> Zeitstempel + M001-Audit + Completion-Certificate, s. [[EXT-09]]/[[AD-25]]), **PandaDoc als Opt-in** daneben.
|
||||
> DoD unten ist noch PandaDoc-zentriert und wird beim Bau gemäß AD-25 auf „SES-Default + BYOK-Adapter" angepasst.
|
||||
> (Rechtlich: SES genügt im SHK; QES nur § 650h, später via D-Trust.)
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
@@ -23,33 +22,43 @@
|
||||
- **Konflikt-Risiko:** gering — additive Tabellen; `apps.prisma`/`crm.prisma`/`files.prisma` nur über Relationen.
|
||||
|
||||
## Was wir bauen
|
||||
**Multi-Signer-Angebots-Signatur über PandaDoc** (DocuSign-Adapter bleibt möglich, läuft über die Apps-Engine M33a): PDF-Upload (aus Files oder neu) → Unterzeichner (Name vorausgefüllt aus Kontakt, Email, Rolle, Reihenfolge sequenziell/parallel) → Senden, mit **Webhook-Verarbeitung** und **Status-Tracking je Unterzeichner** (entwurf/gesendet/angesehen/signiert/abgelehnt), Erinnerung, Widerruf und optionalem Auto-Stage-Wechsel. Das signierte PDF landet in Files. **Pivot-Hart:** Signatur hängt am **`Projekt`-Kern** (`ProjektSignatureDocument`/`ProjektSignatureSigner`), kein eigenes „Deal"-Objekt — Einstieg lebt im Projekt-Detail (P8/P9).
|
||||
**Multi-Signer-Angebots-Signatur über den gehärteten SES-Eigenbau**: PDF-Upload (aus Files oder neu) → Unterzeichner (Name vorausgefüllt aus Kontakt, Email, Rolle, Reihenfolge sequenziell/parallel) → Zustellung per Fern-Link/OTP oder Touch-Signatur vor Ort → PAdES-versiegeltes Signed-PDF + Completion-Certificate. **PandaDoc bleibt optionaler BYOK-Adapter** hinter derselben Apps-Engine-Connection- und Adapter-Schnittstelle. Status-Tracking je Unterzeichner (entwurf/gesendet/angesehen/signiert/abgelehnt), Erinnerung, Widerruf und optionaler Auto-Stage-Wechsel bleiben erhalten. Das signierte PDF landet in Files. **Pivot-Hart:** Signatur hängt am **`Projekt`-Kern** (`ProjektSignatureDocument`/`ProjektSignatureSigner`), kein eigenes „Deal"-Objekt — Einstieg lebt im Projekt-Detail (P8/P9).
|
||||
|
||||
## Benötigte Screens (Backend bedient — Design liefert `D-BOOK` + `D-P16`)
|
||||
| Screen [Route] | Kern-Inhalt |
|
||||
|---|---|
|
||||
| Signatur-Wizard [im Projekt-Detail] | PDF-Upload (aus Files/neu) → Unterzeichner (Name aus Kontakt, Email, Rolle, Reihenfolge sequenziell/parallel) → Provider (PandaDoc, Default) → Senden; **Status-Tracking je Unterzeichner** + Erinnerung + Widerruf; Original- + Signed-PDF-Download |
|
||||
| Signatur-Wizard [im Projekt-Detail] | PDF-Upload (aus Files/neu) → Unterzeichner (Name aus Kontakt, Email, Rolle, Reihenfolge sequenziell/parallel) → Signaturmodus (Fern-Link/OTP oder Touch vor Ort; PandaDoc nur BYOK-Opt-in) → Senden; **Status-Tracking je Unterzeichner** + Erinnerung + Widerruf; Original-, Signed-PDF- und Completion-Certificate-Download |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **PDF-Upload → Multi-Signer via PandaDoc** über die Apps-Engine (M33a)
|
||||
- [ ] **Webhook-Verarbeitung** + **Status-Tracking pro Unterzeichner** (entwurf/gesendet/angesehen/signiert/abgelehnt)
|
||||
- [ ] Erinnerung + Widerruf + optionaler Auto-Stage-Wechsel; Signed-PDF landet in Files
|
||||
- [ ] **Signatur hängt am `Projekt`-Kern** (`ProjektSignatureDocument`/`ProjektSignatureSigner`) — kein „Deal"-Objekt
|
||||
- [ ] Permission-Bundle `signature.*` (read/send/revoke/admin) serverseitig Owner-gefiltert
|
||||
- [ ] Konnektor `tenantHasModule('signature')`; RLS auf allen Tenant-Tabellen
|
||||
- [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] 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] **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
|
||||
- **Entities** (eigene `prisma/schema/signature.prisma`): `SignatureProviderConnection` (data_connection_id → Apps-Engine!, provider PandaDoc, is_default), `ProjektSignatureDocument` (projekt_id, provider_document_id, source_pdf_file_id, status draft/sent/viewed/signed/declined, signed_pdf_file_id — **[Soft-Delete]**), `ProjektSignatureSigner` (document_id, signer_email/name, linked_kontakt_id, status, signed_at). `apps.prisma`/`crm.prisma`/`files.prisma` nur über Relationen (AD-21).
|
||||
- **Signatur = Apps-Engine-Connection** (R-P5): OAuth/API-Key + Health vom Framework; hier Provider-Adapter PandaDoc.
|
||||
- **Webhook-Handler** (Signatur-Check) → Status-Übergänge je Signer + Activity-Write; Auto-Stage-Wechsel über Pipeline (P8/P9, optional).
|
||||
- **Entities** (eigene `prisma/schema/signature.prisma`): `SignatureProviderConnection` (data_connection_id → Apps-Engine!, provider `ses-selfhosted` default oder `pandadoc-byok` optional, is_default), `ProjektSignatureDocument` (projekt_id, provider_document_id, source_pdf_file_id, status draft/sent/viewed/signed/declined, signed_pdf_file_id, completion_certificate_file_id — **[Soft-Delete]**), `ProjektSignatureSigner` (document_id, signer_email/name, linked_kontakt_id, status, signed_at, otp_verified_at). `apps.prisma`/`crm.prisma`/`files.prisma` nur über Relationen (AD-21).
|
||||
- **Signatur = Apps-Engine-Connection** (R-P5): OAuth/API-Key + Health vom Framework; hier Provider-Adapter `ses-selfhosted`, optional `pandadoc-byok`.
|
||||
- **Callback-/Webhook-Handler** (Signatur-Check) → Status-Übergänge je Signer + Activity-Write; Auto-Stage-Wechsel über Pipeline (P8/P9, optional).
|
||||
- **RLS** überall; `signature.*`-Bundle; signiertes PDF via FileEntityLink an den Projekt-Kern.
|
||||
- **Konnektor** `tenantHasModule('signature')`; `is_demo_data` auf Demo-Dokumenten.
|
||||
|
||||
## Umsetzungsnotiz 2026-07-01
|
||||
- Branch: `feat/AK-P16d-signature-ses`, abgezweigt von aktuellem `origin/main`.
|
||||
- Gebaut: `prisma/schema/signature.prisma` + RLS-Policy, File-Link-Typ `signature_document`, Permission/Entitlement-Wiring `signature.*`, Tenant-Modell-Registrierung, Apps-Engine-Katalog/Adapter `ses-selfhosted` und `pandadoc-byok`, Projekt-Signatur-VM, Projekt-Detail-Fallback-UI, öffentlicher `/sign/:token`-Flow mit OTP/Intent/Touch-Signatur, OTP-Mail-Queue, Reminder/Widerruf, Signed-PDF-/Completion-Certificate-Ablage in Files.
|
||||
- Proof lokal: `pnpm exec prisma validate` grün; `pnpm --filter @toolctrl/integrations test` grün; `pnpm --filter @toolctrl/view-models test` grün; `pnpm --filter @toolctrl/integrations typecheck` grün; `pnpm --filter @toolctrl/view-models typecheck` grün; `pnpm --filter @toolctrl/web typecheck` grün; `pnpm exec vitest run apps/web/app/modules/signature/services/padesSeal.server.test.ts` grün; `pnpm lint` grün.
|
||||
- Push-Proof: Implementierungs-Commit `2e7e81557` auf `origin/feat/AK-P16d-signature-ses` gepusht; Pre-Push-Hook `i18n` + `typecheck` grün.
|
||||
- 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.
|
||||
|
||||
## 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-pandadoc-docusign, M132-status-tracking)
|
||||
- `designer-briefs/P16-kalender-booking-forms-signatur.md` (Gruppe 4 Signatur; PandaDoc v1, Pivot-Hinweis Projekt-Kern)
|
||||
- `ROADMAP.md` → Phase 16 · `PHASE-SOURCES.md` → Phase 16 (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)
|
||||
|
||||
@@ -8,6 +8,8 @@
|
||||
| **Cycle/Fenster** | W2 — Plattform & CRM (Demo 1) · fällig 2026-06-25 · Gate W2 |
|
||||
| **Status** | geplant |
|
||||
|
||||
**🎨 design-nachzug: offen** (seit 2026-07-08) — Interim-UI aus `~/ui` steht (AD-28); finale Subframe-Optik aus `D-HR` ausstehend (Davids Delta noch leer).
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `AK-P4b` (Files/Tasks + EntityLink — HR-Dokumente hängen an Files)
|
||||
- **Blocks:** `AK-P17b` (Urlaub/Krank/Surveys)
|
||||
@@ -28,11 +30,11 @@ Den **verschlüsselten HR-Kern** (Quiply-Ablösung): **MA-Stammdaten** (HrEmploy
|
||||
| Passwort-Safe-Verwaltung [`/admin/hr/password-safe`] | Tenant-weite Vault-Sicht (ohne Inhalts-Access), Vault-Anlage/Archiv/Delete, Access-Verwaltung, Audit-Log-Übersicht |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **HR-Profile/Dokumente AES-256-GCM** (KMS-Envelope-Encryption, AD-8)
|
||||
- [ ] **MA-Bereich vs. HR-Admin-Bereich strikt getrennt**; sensible Tabellen zusätzlich App-Permission-gegated
|
||||
- [ ] **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
|
||||
- [ ] MA-Verzeichnis + Standorte (Admin-CRUD) + eigene Dokumente (Upload + read-only Büro-Uploads)
|
||||
- [ ] Konnektor `tenantHasModule('hr')`; RLS auf allen Tenant-Tabellen; sensible Felder verschlüsselt
|
||||
- [x] **HR-Profile/Dokumente AES-256-GCM** (KMS-Envelope-Encryption, AD-8) — *per-Tenant-DEK-Envelope aus R-P5 (`getTenantFieldCrypto`) jetzt in den Seam gebunden; Notfallkontakt verschlüsselt. Finale UI-Optik = Davids D-HR.*
|
||||
- [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.*
|
||||
|
||||
## 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).
|
||||
@@ -48,7 +50,84 @@ Den **verschlüsselten HR-Kern** (Quiply-Ablösung): **MA-Stammdaten** (HrEmploy
|
||||
- `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
|
||||
|
||||
> **✅ Stand 2026-06-28 — auf `main` gemergt.** `feat/AK-P17a` (inkl. der eingemergten R-P5-Commits) ging mit **PR #5** (squash, Merge-Commit `b0fae1af8`, Base `main`, 2026-06-28 17:50, merged_by raffael) auf `main`; Docker-Nachzug `packages/integrations/package.json` via **PR #8** (`0b9d2e46`, 18:05). Alle HR-Artefakte (`hr.prisma`, `hrFieldCrypto.server.ts`, `hrService`/`hrPasswordSafeService`, RLS-SQL, Routen-Hülle, Sidebar) + das R-P5-Crypto-Fundament liegen im `main`-Tree. *Die „Branch lokal, nicht gepusht"-Notizen unten sind damit überholt.* **Backend 5/5 DoD grün.** Extern offen bleibt nur: Davids `D-HR`-Optik + echter 30s-Clipboard-Wipe, RLS-Live/Crypto-Round-trip/Visual-Regression gegen Staging-DB, Plane-Ticket auf Done. Weiterarbeit am HR-Hub läuft über **AK-P17b** (neuer Branch).
|
||||
|
||||
**2026-06-27 (Akeshan) — Backend-Kern + funktionale Routen, ~70% gebaut (2/5 DoD voll grün).**
|
||||
|
||||
Branch `feat/AK-P17a` (lokal, nicht gepusht). Blocker `AK-P4b` ist in `main` gemergt (Commit `2e7b935b9`), Files/EntityLink-Fundament steht. Strikt im AK-P17a-Scope geblieben (Entscheidung „strikt nach Ticket-Doc"): nur Stammdaten/Directory/Locations/Documents/Passwort-Safe; Announcements/Leave/Payslips/Surveys/Requests bleiben bei AK-P17b/Folge.
|
||||
|
||||
Gebaut:
|
||||
- **Schema** `prisma/schema/hr.prisma` (AD-21, bare Scalars, `core.prisma` unberührt): HrEmployeeProfile, HrLocation, HrEmployeeDocument, HrResource/HrQuickLink, EmployeePasswordSafeVault/Entry/Access. Sensible Werte als `*Ciphertext`-Spalten. `prisma validate` + `generate` grün. **`db push` lokal noch offen** (kein lokales Postgres/Docker), env-gegatet wie bei AK-P4b.
|
||||
- **RLS** `prisma/rls/hr-isolation.sql` (deferred-Aktivierung wie task-isolation.sql, P5-Cutover mit R-P2b) + env-gegateter Gate-Test `rls-hr-isolation.integration.test.ts` (skippt ohne `RLS_TEST_DATABASE_URL`).
|
||||
- **Crypto-Seam** `hrFieldCrypto.server.ts` (Entscheidung c): Interface + injizierbar; Produktiv-Binding wirft Klartext-Fehler (M002) bis zum separaten AD-8-Crypto-Ticket. Services nehmen den Provider injiziert → voll testbar.
|
||||
- **Services** `hrService.server.ts` (Profile/Directory/Locations/Documents, MA-self vs HR-admin) + `hrPasswordSafeService.server.ts` (Vault/Entry/Access, `withTenantRLS`, 404-statt-403, Reveal audit-geloggt + Permission-Check, Werte nie in Listen, DSGVO-Export). `hrAccess.server.ts` (Konnektor-Gate + Bundle-Permissions).
|
||||
- **Permissions** `hr.*`-Set + Rollen-Grants in `permissions-seed.server.ts`. **Konnektor**: `hr` als Feature-Key + Blueprint + alle 3 Pläne (entitlements), `tenantHasModule({moduleKey:'hr'})` in jedem Loader.
|
||||
- **View-Models** `packages/view-models/src/hr/*` (pure, Never-List-Values-Contract per Test gesichert) + **Search-Schemas** `hr-directory`/`hr-locations` (Vault-Werte nie indexiert).
|
||||
- **Routen** `app.$tenant/hr.*` (Hub, Directory+Detail, Locations, My-Documents, Passwort-Safe-Liste+Vault-Detail+Reveal+Export, Admin-Vault-Sicht) + **Sidebar**-Eintrag (Feature- + Permission-gegated) + **i18n** de+en. Finale Optik = Hot-Swap-Hülle, wartet auf **Davids D-HR-Delta** (Delta leer).
|
||||
|
||||
Verifiziert (lokal grün): `pnpm typecheck` (alle Pakete + web), `pnpm run verify:i18n` (Exit 0), eslint-staged/baseline/test-density-Gates, entitlements/search/view-models/sidebar-Tests, neue HR-VM- + Crypto-Seam-Tests (15), RLS-Gate-Test skippt sauber. (Pre-existing Windows-Only-Flake `permissions-seed isPermissionsSeedDirectExecution` unverändert, environmental.)
|
||||
|
||||
**Stand: 2/5 DoD voll grün (#2, #4) = 40% strikt; #3/#5 zu ~90% (alles außer per-Tenant-Verschlüsselung), #1 schemaseitig vorbereitet. Gesamt ~70% gebaut.** Offen/blockiert: (a) AD-8-Crypto-Ticket (Entscheidung c) → schaltet #1/#3/#5-Verschlüsselung scharf; (b) Davids D-HR-Delta → finale UI/Visual-Regression; (c) `db push` + RLS-Live-Verifikation (Staging/DB); (d) Merge-Migration entsteht erst beim main-Merge (AD-21). 0 weitere selbst machbar ohne Crypto-Ticket/David/DB.
|
||||
|
||||
Proof: Commit `aa848dca7` (Branch `feat/AK-P17a`, lokal, nicht gepusht). Plane-Kommentar gesetzt (2026-06-27, akeshan). Ticket bleibt offen.
|
||||
|
||||
**Noch im Ticket selbst machbar (ohne externe Blocker), als Folge-Schritte:**
|
||||
- Nebenbei-Validierung sobald lokal/Staging-Postgres da ist: `prisma db push` + RLS-Gate-Test (`RLS_TEST_DATABASE_URL`) live grün ziehen.
|
||||
- Demo-Seed (`is_demo_data`) für Profile/Standorte/Vault, damit die Routen mit Daten zeigbar sind (sofern P17a-Scope; sonst AK-DEMO1).
|
||||
- Smoke-Test `tests/e2e/hr.spec.ts` (Login → /hr → Hauptaktion) sobald die UI nicht mehr reine Hülle ist (nach Davids Delta).
|
||||
- Mobile-Tab-Bar-Eintrag (DoD B#11) für die Monteur-relevanten HR-Screens, falls vorgezogen erwünscht.
|
||||
|
||||
**Update 2026-06-28 (Akeshan) — R-P5 in `feat/AK-P17a` gemergt + Crypto-Seam scharfgeschaltet. DoD jetzt 5/5 backend grün.**
|
||||
|
||||
Co-Dev-Abstimmung: R-P5 von Raffael übernommen und auf `feat/R-P5` fertig gebaut (per-Tenant-DEK-Envelope, AD-8). Entscheidung: `feat/R-P5` voll in `feat/AK-P17a` mergen, damit das Crypto-Fundament hier verfügbar ist, dann den HR-Seam umbinden. 2 Commits:
|
||||
- `efcf44a9` **Merge `feat/R-P5`** — bringt `getTenantFieldCrypto` (`@hivegrid/db`) + `crypto.prisma`/`TenantEncryptionKey`. Konflikte alle „beide behalten": entitlements (hr + integrations, `integrations` defaultOrder 12→13 wegen unique+ascending-Test), permissions-seed/DefaultPermissions/AppSidebar, translations.json de+en (chirurgisch, kein Round-trip), `packages/db/generated/**` via `prisma generate` aus dem Union-Schema neu.
|
||||
- `84fcf1e0` **Seam-Rebind** — `getHrFieldCrypto()` liefert jetzt `getTenantFieldCrypto()` (strukturell identisch). Schaltet #1 (Notfallkontakt AES-256-GCM), #3 (Passwort-Safe Reveal/Export), #5 (sensible Felder verschlüsselt) scharf. Deferred-Fail-Closed-Gerüst (`HrCryptoNotProvisionedError`) bleibt. Seam-Test angepasst (liefert echten Provider, nicht das Gerüst) + neuer env-gegateter Round-trip-Integrationstest (`HR_CRYPTO_TEST_DATABASE_URL`): treibt die echten Services, prüft Ciphertext≠Klartext, Reveal-Round-trip, List versteckt Werte, fremder Tenant kann nicht entschlüsseln (skippt ohne DB).
|
||||
|
||||
Verifiziert: `pnpm typecheck` (alle Pakete + web, direkt-tsc, **0 Fehler** — Turbo-Cache umgangen), `verify:i18n` Exit 0, Zieltests grün (Seam 5, HR-VMs 10, foundation+db-Crypto 16, entitlements 13), Round-trip-Test skippt sauber, beide Commits lefthook-grün.
|
||||
|
||||
**Stand: 5/5 DoD backend grün.** Nur noch extern blockiert: (a) Davids D-HR-Delta → finale Optik + echter 30s-Clipboard-Wipe + Visual-Regression/Smoke; (b) `db push` + RLS-Live + Crypto-Round-trip gegen echtes Postgres (kein lokales PG); (c) Merge-Migration beim main-Merge (AD-21). 0 selbst machbar offen. **Kopplung (bewusst):** `feat/AK-P17a` trägt jetzt R-P5s Commits; R-P5 muss vor/mit P17a auf main, bei R-P5-Review-Änderung hier nachziehen. Branch lokal, nicht gepusht, Plane-Status unverändert (In Progress).
|
||||
|
||||
**Nachtrag 2026-06-28 — aktuellen `origin/main` reingemergt** (`5a30e950`, Branch war 1 Commit hinter main: `e7a888e3` WF-P2 Auth-Screens + du/Sie-Anrede-Toggle). Konflikt nur in `prisma/schema/accounts.prisma`: main fügte `Tenant.anrede` direkt neben den alten `apps`/`dataConnections`/`appSyncRuns`-Back-Relations ein, die R-P5 bewusst entfernt hat (App global, bare Scalars, AD-21) → `anrede` behalten, Back-Relations draußen gelassen. Generierter Prisma-Client aus dem Union-Schema neu erzeugt, translations.json auto-gemergt (hr + integrations + main-Keys, JSON valide). Verifiziert: `pnpm typecheck` direkt-tsc **0 Fehler**, `verify:i18n` Exit 0, Zieltests grün (44). Branch jetzt 18 Commits ahead, lokal, nicht gepusht.
|
||||
|
||||
**Soll/Ist-Verifikation 2026-06-28 (Akeshan) — unabhängiger Nach-Merge-Check, alle CI-Gates grün, DoD bleibt 5/5 backend.**
|
||||
|
||||
Anforderungen (DoD #1–#5) gegen den Ist-Stand im Repo geprüft und nachgewiesen, dass durch die beiden Merges (R-P5 + origin/main) nichts gebrochen ist:
|
||||
- **CI-Gates** (= was Gitea-CI + lefthook real fahren): `prisma generate` aus Union-Schema sauber; `pnpm typecheck` (web) **0 Fehler**; `@hivegrid/api` + `@hivegrid/worker` typecheck **0 Fehler**; `verify:i18n` Exit 0; Zieltests **44 passed / 3 skipped** (HR-VMs 10, Seam 5, foundation+db-Crypto 16, entitlements 13; Round-trip skippt sauber ohne DB).
|
||||
- **DoD-Ist im Code bestätigt:** Crypto-Seam (`hrFieldCrypto.server.ts`) liefert `getTenantFieldCrypto` (Seam-Test grün) → #1/#3/#5 scharf; `crypto.prisma`/`hr.prisma`/`appsEngine.prisma` alle im Schema-Ordner, `prisma generate` validiert das Union-Schema; `accounts.prisma`-Konflikt korrekt (`Tenant.anrede` da, keine entfernten Back-Relations zurückgekrochen).
|
||||
- **Befund (vorbestehend, KEIN Merge-Schaden):** Der volle `pnpm -r typecheck` (nicht von CI gefahren — CI = nur web/api/worker) zeigte 3 latente `TS2352`-Fehler in den HR-VM-Tests (`hr-directory.vm.test.ts`, `hr-password-safe.vm.test.ts`): direkter Cast eines benannten Row-Interfaces auf `Record<string, unknown>`. Die Tests **liefen** grün (vitest/esbuild typecheckt nicht), nur der Paket-`tsc` stolperte — und der `@hivegrid/view-models`-`tsc` hängt in keinem Gate. Schon im Ursprungs-Commit `aa848dca7` vorhanden (tsconfig im Merge-Range unberührt), also nicht durch den Merge entstanden. **Behoben** mit dem von TS vorgeschlagenen `as unknown as Record<…>`-Cast in den 3 Stellen → `@hivegrid/view-models` typecheckt jetzt sauber, VM-Tests bleiben grün. Damit stimmt die frühere „direkt-tsc 0 Fehler"-Aussage jetzt auch paketweit.
|
||||
- **Ebenfalls vorbestehend + außerhalb Scope (nicht angefasst):** `packages/exports`-`tsc` wirft `TS2688 Cannot find type definition file for 'node'` — lokales `@types/node`-Resolution-Thema (`"types":["node"]`), im Merge-Range nicht berührt, in keinem CI-Gate, nicht HR/R-P5-bezogen. Notiert, nicht repariert (Fremd-Scope).
|
||||
|
||||
**Stand unverändert: 5/5 DoD backend grün.** Extern blockiert bleibt: (a) Davids D-HR-Delta → finale Optik + echter 30s-Clipboard-Wipe + Visual-Regression/Smoke; (b) `db push` + RLS-Live + Crypto-Round-trip gegen echtes Postgres; (c) Merge-Migration beim main-Merge (AD-21). 0 selbst machbar offen. Branch lokal (mehrere Commits ahead von origin/main, 0 behind), nicht gepusht, Plane-Status unverändert (In Progress).
|
||||
|
||||
**Nachtrag 2026-06-28 — PR-Pipeline Build-Fix (Client/Server-Split).** Der PR-Build (`pnpm --filter @hivegrid/web build`) fiel im **Client-Environment** mit „Server-only module referenced by client" auf `app.$tenant/hr._index.tsx` → `~/utils/integrations/hrAccess.server`. Ursache: `export const handle = { moduleKey: HR_MODULE_KEY }` — `handle` ist **kein** server-gestrippter Export (RR strippt nur `loader`/`action`/`middleware`/`headers`), und `HR_MODULE_KEY` lag im `.server`-Guard → der ganze Server-Graph (Prisma/db) wurde in den Client-Bundle gezogen. Typecheck fängt das nicht (kein Client/Server-Split), nur der Build. **Identisches Latenz-Muster im R-P5-Pendant** `integrations._index.tsx` (`INTEGRATIONS_MODULE_KEY` aus `integrationsAccess.server`) — der Build bricht nur zuerst bei HR ab. Fix nach dem Walking-Skeleton-Präzedenzfall (`modules/walkingSkeleton/constants.ts`): den Modul-Key in das **client-sichere** Companion-Modul (`hrRoutePaths.ts` / `integrationsRoutePaths.ts`) verschoben, aus dem `.server`-Guard für Back-Compat re-exportiert, und den Route-Import auf das client-sichere Modul umgezogen. Verifiziert: lokaler `pnpm --filter @hivegrid/web build` → **Client-Environment ✓ (8079 Module, no server-only error)**; `web`-typecheck **0 Fehler**. (Lokaler Server-Build-Step bricht danach am bekannten Windows-`/dev/null`-Footgun in `packages/mail` ab — environmental, Linux-CI nicht betroffen.) 6 Dateien, beide Routen (HR + integrations).
|
||||
|
||||
**Update 2026-07-08 (Akeshan) — Interim-UI aus `~/ui` (AD-28). UI-DoD über den Interim-Pfad erfüllt.**
|
||||
|
||||
Die HR-Screens rendern nicht mehr handgeschriebenes Tailwind (das war das Playbook-Negativbeispiel), sondern
|
||||
sind aus `~/ui`-Components recomposed — pure `<XPage vm={} actions={} />` in `apps/web/app/components/screens/hr/`,
|
||||
die Routen bauen nur das VM und injizieren Action-Callbacks (Fetcher bleiben in der Route). Kein VM-/Loader-/
|
||||
Schema-Change. Gebaut (AK-P17a-Scope, 6 Screens + 4 Detail-/Sub-Screens):
|
||||
- `HrHubPage`, `HrDirectoryPage` + `HrDirectoryDetailPage` (Notfallkontakt-Reveal on-demand, Inline-Self-Edit),
|
||||
`HrLocationsPage` (+ Create-Dialog), `HrMyDocumentsPage` (Kind-Filter, read-only Büro-Uploads),
|
||||
`HrPasswordSafeListPage` + `HrVaultDetailPage` (**Werte nie in der Liste**, Reveal je Feld,
|
||||
**echter 30-s-Clipboard-Wipe** nach Copy via `CopyToClipboardButton` + `vm.copyAutoClearMs`, DoD #3),
|
||||
`HrAdminPasswordSafePage`.
|
||||
- 57 neue Präsentations-i18n-Keys chirurgisch in de+en gespleißt (kein JSON-Round-trip).
|
||||
|
||||
**Proof:** Commit `e0f8affd2` (Branch `feat/AK-P17a-interim-ui`, lokal, nicht gepusht) · `pnpm --filter
|
||||
@hivegrid/web typecheck` **0 Fehler** · `pnpm run verify:i18n` Exit 0 (Parität ok, 0 missing-source) ·
|
||||
lefthook pre-commit grün (lint-staged/eslint-baseline/secrets/test-density).
|
||||
|
||||
**Interim-UI (Vorschau, Stand 2026-07-08):** Screens aus `~/ui` gebaut — `apps/web/app/components/screens/hr/*`.
|
||||
Refactor-Nachzug offen: finale Subframe-Optik aus `D-HR` (Plane-Label `design-nachzug`). Noch selbst machbar
|
||||
(nicht David-blockiert): Screen-Unit-Tests je `<XPage>.test.tsx`, Smoke `e2e/smoke/hr-*`, Hot-Swap-Adapter-Triplet;
|
||||
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.
|
||||
|
||||
## Dev-Nachzug (nach Davids `D-HR`-Delta)
|
||||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES 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
|
||||
@@ -8,6 +8,8 @@
|
||||
| **Cycle/Fenster** | W2 — Plattform & CRM (Demo 1) · fällig 2026-06-26 · Gate W2 |
|
||||
| **Status** | geplant |
|
||||
|
||||
**🎨 design-nachzug: offen** (seit 2026-07-08) — Interim-UI aus `~/ui` steht (AD-28); finale Subframe-Optik aus `D-HR` ausstehend (Davids Delta noch leer).
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `AK-P17a` (HR-Kern + Verschlüsselungs-Pattern + MA/Admin-Trennung)
|
||||
- **Blocks:** `R-P9b` (Abwesenheiten → Plantafel-Konflikt-Indikatoren)
|
||||
@@ -28,14 +30,19 @@ Die **HR-Workflows**: einen **mehrstufigen Urlaubs-Approval-Workflow** (submitte
|
||||
| Upload-Erinnerungen-Verwaltung [`/admin/hr/upload-reminders`] | Reminder-Liste (Titel/Cadence/Audience/Status), Editor (Dokumentart/Cadence/Mandatory/Linked-Form), Dispatch-Liste |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **Mehrstufiger Urlaubs-Approval-Workflow** (submitted/approved/rejected/withdrawn + Rückfrage) → speist **Abwesenheits-Kalender** (M25) + **Plantafel-Konflikt-Indikatoren** (R-P9b)
|
||||
- [ ] **Krankmeldung** (selbst/durch Büro) + **AU-Upload verschlüsselt**
|
||||
- [ ] **Announcements** (Audience, Acknowledgement-Pflicht + Read-Receipt, Reaktionen, Kommentare)
|
||||
- [ ] **Lohnabrechnungs-Bulk-Upload** mit Dateiname-Auto-Match (Personalnummer/Name), Match-Vorschau mit Konfidenz, Read-Tracking, Audit pro Read
|
||||
- [ ] **Upload-Erinnerungen** (Cadence once/yearly/every_n_months/on_expiry, Eskalation an Manager) + **Requests** via Templates
|
||||
- [ ] **Surveys** (anonym möglich) mit Auswertung
|
||||
- [ ] **Mitarbeiter-Self-Service** (Web/PWA; Web-Push → v2, AD-17); Anträge als **M05-Form-Submissions** (Renderer aus P16 wiederverwenden)
|
||||
- [ ] Konnektor `tenantHasModule('hr')`; RLS + App-Permission-Gates; sensible Felder verschlüsselt
|
||||
|
||||
> 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] **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)
|
||||
|
||||
## 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).
|
||||
@@ -55,3 +62,120 @@ Die **HR-Workflows**: einen **mehrstufigen Urlaubs-Approval-Workflow** (submitte
|
||||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
- [ ] Plane-Ticket `AK-P17b` aktualisiert
|
||||
|
||||
## Umsetzungs-Notiz
|
||||
|
||||
### 2026-06-28 — Backend komplett + Urlaub/Krank-Vertikale reachable (~50 % DoD)
|
||||
|
||||
**Stand: ~50 % DoD** (Backend aller 7 Domänen fertig + verifiziert; Erreichbarkeit
|
||||
bislang nur für die R-P9b-kritische Urlaub/Krank-Vertikale). Backend-first, da
|
||||
Davids `D-HR`-Delta noch leer ist (finale Subframe-UI/Adapter/Visual-Regression
|
||||
extern blockiert).
|
||||
|
||||
**Proof (2 Commits auf `feat/AK-P17b`, alle Pre-Commit-Gates grün):**
|
||||
- `e2774ca8b` — Backend: `prisma/schema/hr.prisma` (12 Modelle additiv, `prisma
|
||||
validate` grün), Permissions (`hr.leave.approve`, `hr.surveys.results`),
|
||||
RLS-Policies (`prisma/rls/hr-isolation.sql`), 7 Services
|
||||
(`hr{Leave,SickLeave,Announcement,Payslip,UploadReminder,Request,Survey}Service`),
|
||||
8 View-Models + 3 pure Utils (`payslip-match`, `reminder-cadence`), 27 Unit-Tests
|
||||
grün. typecheck web/db/view-models grün.
|
||||
- `3a00766c7` — Routes `/hr/leave` + `/hr/sick` (transitional, `data-ui-id`),
|
||||
Hub-Verlinkung, i18n de+en (Parity grün, hardcoded-strings-Guard grün).
|
||||
|
||||
**DoD-Stand je Punkt:**
|
||||
- [~] (1) Urlaubs-Approval-Workflow + Konflikt-Feed → **Backend+Route fertig**;
|
||||
`EmployeeVacationRequest.calendarEventId` nullable, **CalendarEvent-Write
|
||||
`blockiert`** bis P16 (M25). R-P9b wird über `listApprovedAbsencesForRange`
|
||||
bedient.
|
||||
- [~] (2) Krankmeldung + verschl. AU → **fertig** (Backend+Route+Crypto-Reveal);
|
||||
nur finale UI = David.
|
||||
- [~] (3) Announcements → **Backend fertig**, Route offen (selbst machbar).
|
||||
- [~] (4) Lohn-Bulk + Auto-Match + Read-Tracking → **Backend fertig**, Route offen.
|
||||
- [~] (5) Upload-Erinnerungen + Requests → **Service-Logik fertig**; Worker-Cron-
|
||||
Registrierung (`dispatchDueReminders`) + Routes offen (selbst machbar).
|
||||
- [~] (6) Surveys (anonym) + Auswertung → **Backend fertig**, Route offen.
|
||||
- [~] (7) Self-Service (PWA; Push→v2) → Urlaub/Krank self-service reachable; übrige
|
||||
Routes offen; M05-Form-Reuse **blockiert** (AK-P16c) → Übergangs-Formulare;
|
||||
Web-Push = v2 (out of scope).
|
||||
- [~] (8) `tenantHasModule('hr')` + RLS + Permission-Gates + Verschlüsselung →
|
||||
Connector wiederverwendet, RLS-Policies geschrieben (**Live-Cutover blockiert =
|
||||
R-P2b, wie P17a**), Permissions + Crypto fertig.
|
||||
|
||||
**Selbst machbar offen (nächste Commits):** Routes Announcements/Payslips/Requests/
|
||||
Surveys (+ Admin-Editoren), i18n dazu, Worker-Cron für `dispatchDueReminders`,
|
||||
Smoke-Tests.
|
||||
**Extern blockiert:** finale Subframe-UI/Adapter + Visual-Regression + Hot-Swap
|
||||
(Davids `D-HR`-Delta), CalendarEvent-Write (P16), M05-Renderer (AK-P16c),
|
||||
RLS-Live-Cutover (R-P2b), Web-Push (v2).
|
||||
|
||||
### 2026-06-28 (Update) — alle Domänen-Routes reachable (~80 % DoD)
|
||||
|
||||
**Stand: ~80 % DoD.** Alle 6 Screen-Bereiche + Admin-Editoren sind jetzt als
|
||||
transitional UI erreichbar.
|
||||
|
||||
**Proof — Commit `b6c5e4f76`** (alle Pre-Commit-Gates grün): Routes
|
||||
`/hr/announcements` (Feed/Detail/Admin), `/hr/payslips` (+ `/admin` Bulk-Match),
|
||||
`/hr/requests` (+ `/admin/request-templates`), `/hr/surveys` (+ `/:id`
|
||||
Teilnahme/Editor + `/:id/results` gegated), `/admin/upload-reminders`. Hub
|
||||
verlinkt alle Bereiche. i18n de+en Parity grün, hardcoded-strings-Guard grün,
|
||||
web-typecheck grün.
|
||||
|
||||
**Einziger selbst-machbarer Rest = Worker-Cron für `dispatchDueReminders`
|
||||
(DoD 5).** Architektur-Frage offen: die Dispatch-Orchestrierung liegt aktuell in
|
||||
`apps/web/.../hrUploadReminderService.server.ts`, aber der Cron läuft in
|
||||
`apps/worker` (kann `apps/web` nicht importieren). Optionen: (a) Orchestrierung in
|
||||
den Worker-Maintenance-Handler verschieben (wie `task-archive-retention`, nutzt
|
||||
`deps.db` + `computeNextDue` aus `@hivegrid/view-models` + `createNotification
|
||||
Delivery` aus `@hivegrid/db` — beide worker-importierbar), oder (b) in ein
|
||||
geteiltes Paket extrahieren. **Stop + Rückfrage** statt raten (AGENTS.md). Die
|
||||
Logik selbst (`dispatchDueReminders`/`escalateOverdueDispatches`/`computeNextDue`)
|
||||
ist fertig + `computeNextDue` unit-getestet.
|
||||
|
||||
**DoD nach diesem Update:** 1 ~90 % (Calendar-Write blockiert) · 2 ~95 % · 3 ~95 % ·
|
||||
4 ~95 % · 5 Requests ~95 %, Reminders ~75 % (Cron-Trigger offen) · 6 ~95 % ·
|
||||
7 ~90 % (M05 blockiert, Push v2) · 8 ~90 % (RLS-Cutover blockiert).
|
||||
|
||||
### 2026-06-28 (Update) — Worker-Cron Upload-Erinnerungen fertig (~85 % DoD)
|
||||
|
||||
**Stand: ~85 % DoD — alle selbst-machbaren Punkte erledigt.** Worker-Cron gewählt
|
||||
nach Codebase-Muster (Option a, User-Freigabe).
|
||||
|
||||
**Proof — Commit `b2b445010`** (alle Pre-Commit-Gates grün): Maintenance-Task
|
||||
`hr-upload-reminder-dispatch` (täglich, general-Gruppe) → `runHrUploadReminder
|
||||
DispatchHandler` (pro Tenant Dispatch + notify + Cadence-Advance + Manager-
|
||||
Eskalation, alles in `withTenantRLS`). PURE Helfer `nextReminderDue`/
|
||||
`audienceMatches` + 7 Unit-Tests grün. queue/worker typecheck grün. **DoD 5 jetzt
|
||||
~95 %** (Cron-Trigger geschlossen).
|
||||
|
||||
**Verbleibend = ausschließlich extern blockiert:**
|
||||
- Finale Subframe-UI + Adapter + **Smoke-Tests** (`e2e/smoke/hr-*`) + Visual-
|
||||
Regression (M016) + Hot-Swap (M017) → **Davids `D-HR`-Delta** (noch leer).
|
||||
- CalendarEvent-Write (P16/M25) · M05-Form-Renderer-Reuse (AK-P16c) · RLS-Live-
|
||||
Cutover (R-P2b) · Web-Push (v2/AD-17).
|
||||
|
||||
**6 Code-Commits + 3 Doku-Commits auf `feat/AK-P17b`** (e2774ca8b · 3a00766c7 ·
|
||||
b6c5e4f76 · b2b445010 + Doku). Nichts gepusht, Plane-Status unverändert (wartet
|
||||
auf Freigabe).
|
||||
|
||||
**Update 2026-07-08 (Akeshan) — Interim-UI aus `~/ui` (AD-28). DoD #43 (UI/Tests) über den Interim-Pfad adressiert.**
|
||||
|
||||
Die AK-P17b-Workflow-Screens lagen bereits als Routen auf `main` (Commits `3a00766c7`/`b6c5e4f76`), rendern aber
|
||||
handgeschriebenes Tailwind. Sie sind jetzt aus `~/ui`-Components recomposed — gleiches AD-28-Muster wie AK-P17a
|
||||
(pure `<XPage vm={} actions={} />` in `apps/web/app/components/screens/hr/`, Routen bauen VM + injizieren
|
||||
Callbacks, Fetcher in der Route). Kein VM-/Loader-/Schema-Change. Gebaut (9 Screens):
|
||||
- `HrLeavePage` (Tabs own/approvals/team, Antrag/Approve/Reject/Rückfrage/Withdraw), `HrSickPage` (own/office,
|
||||
audited AU-Reveal-and-open), `HrAnnouncementsFeedPage` + `HrAnnouncementDetailPage` (React/Kommentar/Ack) +
|
||||
`HrAdminAnnouncementsPage`, `HrPayslipsPage` (audited Open-and-view) + `HrAdminPayslipsPage` (Bulk-Match-Vorschau
|
||||
+ Per-Row-Confirm), `HrRequestsPage` (own/approvals + Template-Wahl) + `HrAdminRequestTemplatesPage`,
|
||||
`HrAdminUploadRemindersPage`, `HrSurveysListPage` + `HrSurveyParticipationPage` (Item-Editor) +
|
||||
`HrSurveyResultsPage` (Distribution-Bars).
|
||||
- 21 neue Präsentations-i18n-Keys chirurgisch in de+en gespleißt.
|
||||
|
||||
**Proof:** Commit `f840fcf24` (Branch `feat/AK-P17a-interim-ui`, lokal, nicht gepusht) · `pnpm --filter
|
||||
@hivegrid/web typecheck` **0 Fehler** · `pnpm run verify:i18n` Exit 0 · lefthook pre-commit grün.
|
||||
|
||||
**Interim-UI (Vorschau, Stand 2026-07-08):** Screens aus `~/ui` gebaut — `apps/web/app/components/screens/hr/*`.
|
||||
Damit ist die finale Subframe-Optik (DoD #43) **kein Done-Blocker** mehr, sondern getrackter Nachzug
|
||||
(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).
|
||||
@@ -1,5 +1,10 @@
|
||||
# AK-P19 · P19 Plattform-Admin (admin.hivegrid.de)
|
||||
|
||||
> ⚠️ **Billing-Recut 2026-07-04 ([[AD-27]]):** Die frueheren Legacy-Provider-Positionen in diesem Ticket sind abgeloest.
|
||||
> Plattform-Admin-Billing zielt jetzt auf **HiveGrid-Entitlements + Lago-Billing-State + Mollie-Payment-State**.
|
||||
> Offene Legacy-Provider-spezifische Admin-Arbeit wandert in den `BILL-*`-Recut und darf nicht als neue Legacy-Provider-Implementierung
|
||||
> fortgefuehrt werden.
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Dev (Code) |
|
||||
@@ -10,22 +15,22 @@
|
||||
|
||||
## 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)
|
||||
- **Blocks:** `AK-P20` (Abo-Baukasten-Mechanik wird hier angelegt), `AK-DEMO1` (Demo-Tenant via Admin)
|
||||
- **Blocks:** `AK-P20` (Abo-/Entitlement-Mechanik wird hier angelegt), `BILL-06` (interne Admin-Billing-Basis), `AK-DEMO1` (Demo-Tenant via Admin)
|
||||
- **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).
|
||||
|
||||
## 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-Zusammenstellung** je Tenant (Feature-Konnektoren togglen + Stripe-Positionen = **Abo-Baukasten-Mechanik**), 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.
|
||||
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.
|
||||
|
||||
## Benötigte Screens (Backend bedient — Design liefert `D-ADMIN` + `D-P19`; eigene Admin-Shell)
|
||||
| Screen [Route] | Kern-Inhalt |
|
||||
|---|---|
|
||||
| Admin-Login + 2FA [`admin.hivegrid.de/login`, `/2fa`] | Email+Passwort (NIST/HIBP, Captcha ab 3. Fehler), TOTP-Pflicht, kein Magic-Link, 8h-Session |
|
||||
| Admin-Dashboard [`/dashboard`] | Basis-KPIs Tenants/aktive User/MRR + System-Health-Ampel + Queue-Status, Drill-Down (Churn/ARPU → v2) |
|
||||
| Tenant-Liste + Detail [`/tenants`, `/:id`] | Liste (Status/Plan/MRR/User/Aktivität); Detail: Status-Wechsler (Reason), **Abo-Zusammenstellung (Konnektoren + Stripe-Positionen)**, Trial-Verlängerung, Notizen, **Impersonate mit Begründung**, User-/Activity-/Audit-/Flag-Sektionen |
|
||||
| Tenant-Liste + Detail [`/tenants`, `/:id`] | Liste (Status/Plan/User/Aktivität); Detail: Status-Wechsler (Reason), **Abo-/Entitlement-Zusammenstellung (Konnektoren + Plan/Seats/Billing-State)**, Trial-Verlängerung, Notizen, **Impersonate mit Begründung**, User-/Activity-/Audit-/Flag-Sektionen |
|
||||
| Manuelle Tenant-Anlage [`/tenants/new`] | Name, Slug (Live-Validation), Branche/Größe, Initial-Admin-Email, Module/Plan, Trial, Demo-Daten-Häkchen, Reason |
|
||||
| User-Liste + Detail [`/users`, `/:id`] | Memberships/2FA/Sessions; Ops (2FA-Reset mit Reason, Session-Revoke, Deaktivieren, Lösch im Auftrag) |
|
||||
| Subscription-Liste + Detail [`/subscriptions`, `/:id`] | Plan/MRR/Status/Stripe-Sync; manuelle Override (Plan/Sonderpreis/Reason), Stripe-Sync forcieren, Refund |
|
||||
| Subscription-Liste + Detail [`/subscriptions`, `/:id`] | Plan/Seats/Status/Lago-Sync/Mollie-Payment-State; manuelle Override (Plan/Seats/Sonderfall/Reason), Sync forcieren, Refund-Verweis |
|
||||
| Feature-Flags [`/feature-flags`] | Flag-Liste + Targeting-Filter (plan-tier) + Tenant-Override mit Ablauf (Massen-Statistik → v2) |
|
||||
| Health + Worker-Queues [`/health`, `/health/workers`] | Service-Ampeln, DB/Redis/Storage; BullMQ-Queues Active/Waiting/Delayed/Failed, Job-Detail + Retry/Pause/Resume |
|
||||
| Support-Inbox + Detail [`/support`, `/:id`] | Liste + Konversation + Markdown-Reply + interne Notiz; **speist sich aus Feedback-Widget (P21)** |
|
||||
@@ -33,18 +38,18 @@ Die **getrennte Plattform-Admin-Welt** auf `admin.hivegrid.de` (Host-Routing, **
|
||||
| Subprozessoren + AVV [`/legal/subprocessors`, `/legal/avv`] | Subprozessor-Liste; AVV-Versionen + akzeptierende/ausstehende Tenants |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **Host-Routing `admin.hivegrid.de`** (NICHT `/admin`-Pfad!) + **Cookie-Domain-Trennung** App↔Admin
|
||||
- [ ] **TOTP-Pflicht** hart erzwungen; Admin **ohne Tenant-Workspace** (Default-Provisionierung abgeschaltet, in keiner Mitgliederliste)
|
||||
- [ ] **Tenant-Verwaltung** + **Abo-Zusammenstellung** (Konnektoren togglen + Stripe-Positionen) + Trial-Verlängerung + Notizen
|
||||
- [ ] **Impersonate** (temporäre Tenant-User-Session max. 30 Min) mit Klartext-Banner im Tenant + Reason-Pflicht
|
||||
- [ ] **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**
|
||||
- [ ] **`AdminAuditLog`** (tenant_id=null, Hash-Kette); sensitive Aktionen mit Reason-Pflicht + Confirm-Phrase
|
||||
- [ ] Eigene getrennte Admin-Shell (kein Reuse der App-Sidebar)
|
||||
- [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] **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] **`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)
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (eigene `prisma/schema/admin.prisma` — **KEIN `tenant_id`**, getrennte Welt): `AdminAuditLog` (admin_user_id, action_type, target_kind/id, summary_text, metadata Diff — cross-tenant), `AdminTenantNote` (tenant_id, note_text, category, pinned), `AdminSupportTicket` (+ Message — source_kind in_app_feedback_widget/inbound_email, tenant_id, status, priority). **v1-Cut:** `AdminUser`/`AdminRole`/`AdminSession` (M038/M039) → v2; v1 = Boilerplate-User-Extension + `admin-mfa-gate.server.ts`. `AdminLead`/`AdminDeal` → v2.
|
||||
- **Abo-Baukasten-Mechanik** (Billing-Domäne 12): Admin schaltet `SubscriptionFeature`-Konnektoren je Tenant + Stripe-Positionen — Grundlage für AK-P20 (Self-Service-UI dort → v2). `tenantHasModule()` prüft Feature im Abo.
|
||||
- **Abo-/Entitlement-Mechanik** (Billing-Domäne 12): Admin schaltet `SubscriptionFeature`-Konnektoren je Tenant; Plan/Seats/Billing-/Payment-State wird nach `BILL-02` bis `BILL-06` ueber Lago/Mollie/HiveGrid synchronisiert. `tenantHasModule()` prueft Feature im lokalen Entitlement-State.
|
||||
- **Host-Routing + Cookie-Domain-Trennung** (Boilerplate routet `/admin`-Pfad → auf Host umstellen); TOTP-Pflicht + MFA-Step-up-Gate.
|
||||
- **Impersonate** generiert temporäre Tenant-Session (max 30 Min) mit Banner + Audit-Spur; kein BYPASSRLS.
|
||||
- **AdminAuditLog** über die Audit-Hash-Kette (AK-P3); Reason-Pflicht bei Status-Wechsel/Impersonate/Override.
|
||||
@@ -60,3 +65,74 @@ Die **getrennte Plattform-Admin-Welt** auf `admin.hivegrid.de` (Host-Routing, **
|
||||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
- [ ] Plane-Ticket `AK-P19` aktualisiert
|
||||
|
||||
## Umsetzungs-Notiz
|
||||
|
||||
### 2026-06-25 — Backend-Fundament (Branch `feat/AK-P19`)
|
||||
|
||||
**Vorab-Entscheidungen (mit User abgestimmt):**
|
||||
- **Admin-Login = Authentik-SSO** (juengere, in Prod laufende Infra-Entscheidung: AK-INFRA2, AGENTS.md STANDARDS §5/AD-3). Der aeltere Brief-Text „Email+Passwort+TOTP" gilt damit nicht; DoD #2 = TOTP/MFA via Authentik + `admin-mfa-gate` Step-up.
|
||||
- **DoD #7 `AdminAuditLog`** wird NICHT als eigenes Modell gebaut, sondern ueber die bestehende **AuditEvent-Querschnitt-Huelle** (tenantId=null, actorType=admin, Hash-Kette aus AK-P3). Grund: AGENTS.md verbietet Querschnitt-Nachbau; AuditEvent unterstuetzt tenantId=null bereits. `admin.prisma` enthaelt daher kein Audit-Modell.
|
||||
|
||||
**Ist-Bestand (Boilerplate, verifiziert — zaehlt auf DoD):** Host-Routing `admin.hivegrid.de` + Cookie-Trennung (DoD #1 ✅), eigene Admin-Shell/Sidebar (DoD #8 ✅), User-Ops + Feature-Flag-UI (DoD #5 ✅ weitgehend), Impersonate gewired mit MFA-Gate + Audit (DoD #4 teilweise).
|
||||
|
||||
**Diese Session gebaut + verifiziert:**
|
||||
- `prisma/schema/admin.prisma` — `AdminTenantNote` (Domaene 11) + `SupportTicketMessage` (Konversation/interne Notiz, erweitert bestehendes `SupportTicket` statt Duplikat). Minimale Back-Relations. `prisma validate` + `generate` gruen. **`db push` steht noch aus** (braucht laufende Dev-DB), Migration erst beim Merge (AD-21).
|
||||
- `apps/web/app/services/admin/admin-action-audit.server.ts` — Operator-Action-Audit-Gate (DoD #7): Reason-Pflicht + Confirm-Phrase + Emit als AuditEvent (tenantId=null/actorType=admin) ueber `createAuditEvent`. Unit-Test 10/10.
|
||||
- `packages/view-models/src/admin/tenant-note-list.vm.ts` — reiner Notizen-VM (DoD #3, pinned-first, i18n-Keys, Empty-State). Unit-Test 6/6.
|
||||
|
||||
**Proof:** web-Typecheck Exit 0, view-models-Typecheck clean, `verify:i18n` Exit 0, Tests 16/16. Commits `6cf7a55b4` (Schema), `e562b2752` (Audit-Gate + VM). Nicht gepusht, kein Status-Wechsel.
|
||||
|
||||
**%-DoD-Stand:** rund 40 % (3 von 8 voll gruen: #1/#5/#8; #7 ~70 % = Gate gebaut, offen Viewer-Cross-Tenant + Verdrahtung an Aktionen; #3 ~30 % = Notizen-VM/Audit, offen Abo-Baukasten/Trial/Service).
|
||||
|
||||
**Selbst machbar offen (Backend, ohne David):** Abo-Baukasten-Mechanik (Konnektoren je Tenant + Plan/Seats/Billing-State nach `BILL-*`), Queue-Monitor (BullMQ), Support-Inbox-Service (auf `SupportTicketMessage` + bestehendem `@hivegrid/db/support-tickets.server`), AdminTenantNote-Service (CRUD), Impersonate-Haertung (30-Min-Cap/Banner), Admin-ohne-Tenant-Workspace-Haertung, Audit-Viewer Cross-Tenant-Erweiterung + Call-Site-Verdrahtung, `db push`.
|
||||
**Extern blockiert:** finale Subframe-UI aller Screens (Davids `D-ADMIN`/`D-P19`-Delta noch leer).
|
||||
|
||||
### 2026-06-25 (Forts.) — Backend-Slices Abo-Baukasten / Queue / Support / Notizen
|
||||
|
||||
**Zusaetzlich gebaut + verifiziert:**
|
||||
- **Abo-Baukasten-Mechanik (DoD #3, Grundlage AK-P20):** `services/admin/subscription-assembly.server.ts` toggelt Feature-Konnektoren je Tenant ueber `TenantFeatureOverride` (enabled/disabled/inherit), invalidiert den `tenantHasModule`-Cache und auditet reason-gegated. Reuse des Entitlement-Resolvers, kein Parallel-Store. + `subscription-connectors.vm.ts` (effektiver Zustand aus Blueprint-Default + Override).
|
||||
- **Queue-Monitor (DoD #6 Teil A):** `services/admin/queue-monitor.server.ts` — `QueueInspector`-Port + Snapshot-Aggregation + audited Pause/Resume/Retry; BullMQ-Adapter ueber `@hivegrid/queue` (Redis-Runtime auf Staging zu verifizieren). + `queue-monitor.vm.ts` (Counts -> Klartext-Health ok/warn/paused, Worst-of-Overall). Hinweis: `TypedQueue` ist enqueue-only, Read/Control via strukturellem Cast.
|
||||
- **Support-Inbox (DoD #6 Teil B):** `services/admin/support-inbox.server.ts` — Reply / interne Notiz / Status / Assignee auf dem `SupportTicketMessage`-Thread, validiert + auditiert. + `support-conversation.vm.ts` (Thread oldest-first, reply/internalNote/inbound).
|
||||
- **Tenant-Notes (DoD #3):** `services/admin/tenant-notes.server.ts` — create/delete/list `AdminTenantNote` mit Kategorie-Normalisierung + Audit.
|
||||
|
||||
**Proof:** web-Typecheck 0 Fehler (grep `error TS` = 0; Achtung: gepipte Typechecks maskieren tsc-Exit, daher gegen Inhalt geprueft), view-models-Typecheck clean, `verify:i18n` Exit 0, Admin-Tests **52/52** in 9 Dateien. Commits `0bb9e29ad` (Abo-Baukasten+Queue), `116aee518` (Queue-BullMQ-Cast-Fix), `c9dedcafe` (Support+Notizen). Nicht gepusht, kein Status-Wechsel.
|
||||
|
||||
**%-DoD-Stand jetzt:** rund **60 %**. Voll gruen: #1/#5/#8 (Boilerplate, verifiziert). Backend-fertig (UI = David): #6 (Queue+Support), #3-Teile (Abo-Baukasten + Notizen). #7 ~80 % (Gate gebaut + an Abo/Queue/Support-Aktionen verdrahtet; offen: Audit-Viewer Cross-Tenant + Impersonate/Status-Call-Sites).
|
||||
|
||||
**Noch offen, selbst machbar:** Audit-Viewer Cross-Tenant-Erweiterung, Impersonate-Haertung (30-Min/Banner) + Reason-Verdrahtung, Admin-ohne-Tenant-Workspace-Haertung (DoD #2), Trial-Verlaengerung + manuelle Tenant-Anlage, Billing-Recut-Adminbasis aus `BILL-06`, `db push` (Dev-DB) + VM-Unit-Tests laufen, Smoke-/Visual-Tests nach Davids UI. **Extern blockiert:** finale Subframe-Screens (David).
|
||||
|
||||
### 2026-06-25 (Forts. 2) — DoD #2 / #4 / #7 verifiziert bzw. geschlossen
|
||||
|
||||
Drei Punkte gegen den realen Code geprueft statt neu gebaut:
|
||||
- **DoD #2 (Admin ohne Tenant-Workspace) = erfuellt.** Der Admin-Login ist Authentik-SSO; `modules/admin-sso/jit-provisioning.server.ts` legt **nur** `User` + `AdminUser` an, **keinen** Tenant, **keine** `TenantUser`-Mitgliedschaft, **kein** `defaultTenantId`. Damit hat ein Admin keinen Workspace und taucht in keiner Mitgliederliste auf. TOTP/MFA laeuft ueber Authentik + `admin-mfa-gate` Step-up (bestehend). Verifiziert per Code-Read + bestehende `jit-provisioning.server.test.ts` (Fake-Client hat gar kein tenant-Modell).
|
||||
- **DoD #7 (AdminAuditLog cross-tenant + Viewer) = erfuellt.** Der `/admin/audit`-Viewer (AK-P3) liest ohne `tenantId`-Param **alle** AuditEvent-Zeilen inkl. der `tenantId=null`/`actorType=admin`-Operator-Aktionen, filterbar nach Actor/Tenant. Mein Gate schreibt genau dorthin; Reason + Confirm-Phrase liegen im Gate. Kein Viewer-Umbau noetig.
|
||||
- **DoD #4 (Impersonate max. 30 Min) = geschlossen.** `IMPERSONATION_SESSION_TTL_MS` war 60 Min -> auf **30 Min** gesetzt; `validateImpersonationSessionState` liefert danach `stale_started_at`. Banner (rootData) + MFA-Step-up bestehen. Test: 29 Min gueltig / 31 Min stale. Offen nur das Operator-Reason-Modal auf der neuen Tenant-Detail-Impersonate-Aktion (Davids UI).
|
||||
|
||||
Commit `feat(AK-P19): cap operator impersonation at 30 minutes`. web-Typecheck 0 Fehler, session-Impersonation-Tests 16/16.
|
||||
|
||||
**%-DoD-Stand jetzt: rund 70 %.** Voll gruen: #1, #2, #4 (bis auf Reason-Modal=David), #5, #7, #8. Backend-fertig (UI=David): #6 (Queue+Support), #3 (Abo-Baukasten+Notizen). Rest #3: Trial-Verlaengerung + manuelle Tenant-Anlage + Billing-Recut-Adminbasis aus `BILL-06` + `db push`.
|
||||
|
||||
### 2026-06-26 — `prisma db push` + DB-Integrationstest (real-DB-Verifikation)
|
||||
|
||||
- **`db push` erfolgreich** gegen eine frische pgvector-Postgres (Docker, da compose kein Postgres mitbringt): das **gesamte** Schema inkl. `admin.prisma` synct sauber. Verifiziert per `psql`: Tabellen `AdminTenantNote`, `SupportTicketMessage` + Spalte `SupportTicket.assignedToUserId` vorhanden. Damit AD-21 (Feature-Branch = `db push`, Migration erst beim Merge) erfuellt. **Befehl:** `prisma db push --url <direct-url>` (Prisma 7 kennt kein `--skip-generate` mehr).
|
||||
- **DB-Integrationstest** `admin-services.integration.test.ts`: faehrt den **echten** Service-Code (tenant-notes, subscription-assembly, support-inbox) ueber einen echten Prisma-Client (`createDbClient({connectionString})`) gegen die gepushte DB — faengt Query-/Schema-Mismatches, die die Fake-Unit-Tests nicht sehen. **3/3 gruen** mit DB, **auto-skip** ohne `ADMIN_IT_DATABASE_URL` (CI bleibt gruen). web-Typecheck 0 Fehler.
|
||||
|
||||
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)
|
||||
|
||||
**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.
|
||||
|
||||
**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.
|
||||
|
||||
**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).
|
||||
|
||||
**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.
|
||||
@@ -1,4 +1,9 @@
|
||||
# AK-P20 · P20 Billing (Stripe Abo-Baukasten) + Onboarding + Branding
|
||||
# AK-P20 · P20 Billing-Grundlagen + Onboarding + Branding
|
||||
|
||||
> ⚠️ **Billing-Recut 2026-07-04 ([[AD-27]]):** Die Legacy-Provider-Annahmen in diesem Ticket sind Doku-Drift. Zielarchitektur
|
||||
> ist **Lago self-hosted fuer Billing/Invoicing + Mollie nur fuer Payments + HiveGrid-Entitlements**. v1-Scope:
|
||||
> **Plans + Seats**, kein Usage-Billing. Legacy-Provider-Codepfade aus der bisherigen Teilumsetzung sind Migrationsmaterial fuer
|
||||
> `BILL-02` bis `BILL-05`, nicht mehr Zielarchitektur.
|
||||
|
||||
> ⚠️ **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.
|
||||
|
||||
@@ -8,49 +13,81 @@
|
||||
| **Owner** | Akeshan |
|
||||
| **Phase** | P20 — Billing, Onboarding & Branding |
|
||||
| **Cycle/Fenster** | W4 — USP, Härtung & Launch · fällig 2026-07-08 · Gate W4 |
|
||||
| **Status** | geplant |
|
||||
| **Status** | Recut / On Hold fuer Billing-Anteil; Onboarding/Branding/Frozen-Vorarbeit verwertbar |
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `EXT-07` (Stripe-Account + Produkte/Preise + Webhook-Endpoint), `AK-P19` (Abo-Baukasten-Mechanik + Admin-Tenant-Verwaltung als Voraussetzung)
|
||||
- **Blocks:** `AK-P21` (DSGVO/Launch — Tenant-Löschung braucht Stripe-Cancel)
|
||||
- **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
|
||||
- **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).
|
||||
|
||||
## Was wir bauen
|
||||
Drei gebündelte v1-Module: **Billing als Stripe-Abo-Baukasten** (M154-Recut) — Basis-Preis pro Nutzer + Feature-Module als **daten-getriebene Positionen**, **KEINE Seat-Typen**; In-App **keine** Pricing-/Upgrade-/Plan-Wechsel-UI (Apple-Compliance LP-8) — nur Read-Only-Übersicht + externer Verweis; **Trial + Dunning** (Tag 1/3/7) + **Frozen-Modus** (Read-Only-Middleware); Verbrauchs-Zähler + Drossel (Aufschlags-Abrechnung → v2). **Onboarding** = **Auto-SHK-Provisionierung** beim Signup (Seeds M158, **ohne Wizard** — der ist v2) + Demo-Daten-Knopf + Erste-Schritte-Checkliste. **Branding** = nur **Hell/Dunkel-Toggle** (kein System-Modus), flash-frei via SSR-Cookie.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## 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`] | **Stripe-Customer-Portal-Embed** (Rechnungs-History/PDF, Zahlungsmethode, USt-Daten) |
|
||||
| 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) |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **Stripe-Abo-Baukasten**: Basis-Preis pro Nutzer + Feature-Module als daten-getriebene Positionen — **KEINE Seat-Typen** (M154-Recut); Preise geparkt (AD-15)
|
||||
- [ ] **Trial + Dunning** (Tag 1/3/7) + **Frozen-Modus** (Read-Only-Middleware) greift; Status-Banner pro Zustand; Verbrauchs-Zähler + Drossel (Aufschlags-Abrechnung → v2)
|
||||
- [ ] **In-App keine** Pricing-Tabelle/Upgrade-Buttons/Plan-Wechsel-UI (LP-8) — Read-Only + externer Verweis; Pause/Kündigen erlaubt
|
||||
- [ ] **Auto-SHK-Provisionierung** beim Signup (Seeds M158: Pipelines, Custom-Felder, Rollen, Form-Templates, Checkliste) — **ohne Wizard-UI** (v2)
|
||||
- [ ] **Demo-Daten-Knopf** (per Settings, `is_demo_data`-Flag löschbar) + „Demo ausblenden"-Filter
|
||||
- [ ] **Erste-Schritte-Checkliste** (auto-erkannter Status, CTA-Links, abhakbar/ausblendbar; Dashboard-Widget)
|
||||
- [ ] **Hell/Dunkel-Toggle** flash-frei (SSR-Cookie, `next-themes`) — kein System-Modus
|
||||
- [ ] Konnektor `tenantHasModule('billing')`; RLS auf allen Tenant-Tabellen
|
||||
- [ ] **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] **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] Konnektor `tenantHasModule('billing')`; RLS auf allen Tenant-Tabellen
|
||||
|
||||
## Aktueller Stand (Billing-Recut 2026-07-04)
|
||||
|
||||
**Fortschritt:** **AK-P20: 7/8 historischer DoD = 87,5 % done; nach AD-27 bleibt 1/8 blockiert/ersetzt durch `BILL-02` bis `BILL-05`.**
|
||||
|
||||
**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.
|
||||
|
||||
**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.
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (eigene `prisma/schema/billing.prisma`): `SubscriptionProduct` (Plan Core/Swarm/Colony — global), `SubscriptionPrice` (stripe_price_id, interval), `SubscriptionFeature` (+ `ProductFeature`, quota_value JSON — **Brücke zur Konnektor-Pflicht**, `tenantHasModule()`), `SubscriptionUsageBasedPrice`/`UsageBasedTier`, `TenantSubscription` (1:1 Tenant, status trial/active/past_due/cancelled/frozen, Stripe-IDs, Dunning-Felder), `TenantSubscriptionProductPrice` (quantity=Seats, is_metered), `TenantSubscriptionUsageRecord`, `Credit`, `CheckoutSessionStatus`. Onboarding: `Onboarding`/`OnboardingSession`/`OnboardingDemoProvisioning`. Branding: `User.theme_preference` (Feld, kein eigenes Modell). `core.prisma` über Tenant-Relation (AD-21).
|
||||
- **Abo-Baukasten** (M154-Recut): `SubscriptionFeature.code` (z.B. `kwp_integration`) = Entitlement-Schicht; Struktur aus Legacy `pricing-plans.ts` portieren, Preise = Kostenmatrix (AD-15).
|
||||
- **Stripe-Integration**: Webhook-Handler (Signatur), Customer-Portal-Embed, Dunning-Email-Sequenz, Frozen-Read-Only-Middleware auf der Request-Pipeline.
|
||||
- **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).
|
||||
- **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.
|
||||
- **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.
|
||||
|
||||
## Quellen (granular)
|
||||
- `ENTITY-MODEL.md` → **Domäne 12: Billing & Abo-Baukasten** (Recut-Modell, keine Seat-Typen) + **Domäne 13** (Onboarding, OnboardingDemoProvisioning, User.theme_preference)
|
||||
- `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-stripe, 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)
|
||||
- `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`
|
||||
|
||||
@@ -58,3 +95,215 @@ Drei gebündelte v1-Module: **Billing als Stripe-Abo-Baukasten** (M154-Recut)
|
||||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
- [ ] Plane-Ticket `AK-P20` aktualisiert
|
||||
|
||||
## Umsetzungs-Notiz
|
||||
|
||||
> 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`.
|
||||
|
||||
**2026-07-01 · AK-P20 Teilumsetzung**
|
||||
|
||||
Umgesetzt:
|
||||
- Billing-Grundlage erweitert: `SubscriptionFeature.code`/`quotaValue`, Subscription-Statusfelder, metered Usage-Records mit Idempotenz, Webhook-Log, `billing`-Entitlement und `tenantHasModule('billing')`-Gate auf der Subscription-/Usage-Route.
|
||||
- In-App-AI-Credits entfernt bzw. auf Subscription umgeleitet; Subscription-UI bleibt read-only mit externem Hinweis, Portal/Kündigen bleiben erhalten.
|
||||
- Verbrauchsübersicht für Automation-Läufe/Speicher, Billing-Statusbanner-VM und Shell-Banner vorbereitet.
|
||||
- SHK-Onboarding-Grundlage: Signup ruft SHK-Defaults auf, Checkliste und Demo-Daten-Service/-Routes mit `isDemoData`-Tracking und löschbarer Provisionierung.
|
||||
- Hell/Dunkel-Toggle auf zwei Modi begrenzt, kein System-Fallback mehr.
|
||||
- Tenant-Isolation/RLS-Nachzug: `OnboardingDemoProvisioning`, Usage-Records und RLS-Artefakt registriert; Windows-kompatible Verify-Wrapper für die betroffenen Baseline-Gates repariert.
|
||||
|
||||
Proof:
|
||||
- `pnpm prisma validate`
|
||||
- `pnpm typecheck`
|
||||
- `pnpm lint`
|
||||
- `pnpm run verify:i18n`
|
||||
- `pnpm run verify:sidebar-routes`
|
||||
- `pnpm run verify:tenant-isolation-report`
|
||||
- `pnpm run verify:billing-boundary-baseline`
|
||||
- `pnpm run verify:onboarding-flow`
|
||||
- `pnpm --filter @hivegrid/entitlements test`
|
||||
- `pnpm --filter @hivegrid/cli exec vitest run src/commands/tenant/models.test.ts`
|
||||
- `pnpm --filter @hivegrid/web exec vitest run app/application/sidebar/AppSidebar.test.tsx app/utils/theme/userThemePreference.server.test.ts 'app/routes/app.$tenant/settings/subscription.test.tsx' app/utils/services/.server/billingStatusService.test.ts`
|
||||
|
||||
Fortschritt: **AK-P20: 2/8 DoD = 25 % done**.
|
||||
|
||||
Abgehakt: Hell/Dunkel ohne System-Modus; Billing-Konnektor/RLS.
|
||||
|
||||
Teilweise umgesetzt, aber noch nicht DoD-grün: Legacy-Provider-Abo-Baukasten-Grundschema, Trial/Frozen-Statusdaten + Banner, read-only Subscription-Oberfläche, Auto-SHK-Provisionierung, Demo-Daten-Knopf, Erste-Schritte-Checkliste.
|
||||
|
||||
Offen/blockiert: `EXT-07` Legacy-Provider-Account/Produkte/Webhook, `AK-P19` Admin-Abo-Baukasten/Trial-Freischaltung, `D-P20` finale Screens/Subframe-Delta; außerdem selbst machbar offen sind vollständige Dunning-Sequenz Tag 1/3/7, Frozen-Read-Only-Middleware, Demo-ausblenden-Filter, Checklist-Auto-Erkennung und Dashboard-Widget.
|
||||
|
||||
**2026-07-01 · AK-P20 Slice 1 Nachzug: Legacy-Provider-Webhooks + Dunning/Frozen**
|
||||
|
||||
Umgesetzt:
|
||||
- Legacy-Provider-Webhook-Einstieg `/webhooks/legacyProvider` mit Signaturprüfung über `MOLLIE_API_KEY` und idempotentem `Legacy-ProviderWebhookLog`.
|
||||
- Legacy-Provider-Status-Sync für `customer.subscription.updated/deleted`, `invoice.payment_failed`, `invoice.paid` und `invoice.payment_succeeded`; Subscription-Periodenfelder werden aus Legacy-Provider übernommen.
|
||||
- Dunning-Entscheidung Tag 1/3/7 plus Freeze nach ausgeschöpfter Mahnstufe; `pastDueSince` bleibt bei wiederholten Legacy-Provider-Fehlerereignissen stabil.
|
||||
- Dunning-Email-Sequenz erzeugt Billing-Notifications über den bestehenden Notification-Delivery-Boundary (`category=billing`, `channel=EMAIL`).
|
||||
- Billing-Read-Only-State zentral auslesbar und erste Tenant-Shell-Schreibaktionen blockieren im Frozen/Read-only-Status mit 423.
|
||||
- Tests für Dunning-Entscheidung, Dunning-Cycle, Legacy-Provider-Webhook-Route, Legacy-Provider-Signaturkonstruktion, Status-Read-only-State und Tenant-Action-Block ergänzt.
|
||||
|
||||
Proof:
|
||||
- `pnpm --filter @hivegrid/web exec vitest run app/utils/services/.server/billingStatusService.test.ts app/utils/services/.server/billingDunningService.test.ts app/routes/webhooks.legacyProvider.test.ts app/utils/legacyProvider.server.test.ts 'app/routes/app.$tenant.test.tsx'`
|
||||
- `pnpm prisma validate`
|
||||
- `pnpm typecheck`
|
||||
- `pnpm lint`
|
||||
- `pnpm run verify:i18n`
|
||||
- `pnpm run verify:sidebar-routes`
|
||||
- `pnpm run verify:billing-boundary-baseline`
|
||||
|
||||
Fortschritt: **AK-P20: 2/8 DoD = 25 % done**.
|
||||
|
||||
Abgehakt bleibt: Hell/Dunkel ohne System-Modus; Billing-Konnektor/RLS.
|
||||
|
||||
Teilweise umgesetzt, aber noch nicht DoD-grün: Legacy-Provider-Abo-Baukasten-Grundschema; Trial/Dunning/Frozen mit Statusdaten, Webhook-Sync und erster Read-only-Blockade; read-only Subscription-Oberfläche; Auto-SHK-Provisionierung; Demo-Daten-Knopf; Erste-Schritte-Checkliste.
|
||||
|
||||
Selbst machbar offen: Frozen-Read-Only noch route-übergreifend härtbar, Verbrauchs-Drossel, Demo-ausblenden-Filter, Checklist-Auto-Erkennung und Dashboard-Widget.
|
||||
|
||||
Blockiert/offen durch externes Delta: finale Subframe-/Screen-Integration aus `D-P20`. `EXT-07` ist laut Plane erledigt; `AK-P19` ist formal auf On-Hold, die für AK-P20 genutzten Grundlagen liegen aber bereits auf `main`.
|
||||
|
||||
**2026-07-01 · AK-P20 Slice 2 Nachzug: Usage-Drossel + First-Steps-Auto-Erkennung**
|
||||
|
||||
Umgesetzt:
|
||||
- Verbrauchs-Drossel: `recordBillingUsage()` prueft Quotas vor dem Schreiben, wirft `BillingUsageQuotaExceededError` und behandelt `idempotencyKey` jetzt wirklich idempotent.
|
||||
- Usage-Summary liefert pro Metrik `quota`, `remaining`, `exceeded` und `percentUsed`; `/settings/usage` zeigt Limit, Restmenge und ausgeschöpfte Limits an.
|
||||
- Erste-Schritte-Checkliste erkennt Status automatisch aus echten Tenant-Daten: Profil, Kontakte, Projekte und aktives Trial/Abo. Erfüllte Schritte werden in `OnboardingSessionStep.completedAt` persistiert; vollständige Sessions werden auf `completed` gesetzt.
|
||||
- Dashboard-Widget für die Erste-Schritte-Checkliste ergänzt, inklusive Fortschritt und Link zur Checklist-Route.
|
||||
|
||||
Proof:
|
||||
- `pnpm --filter @hivegrid/web exec vitest run app/utils/services/.server/billingStatusService.test.ts app/utils/services/.server/billingDunningService.test.ts app/routes/webhooks.legacyProvider.test.ts app/utils/legacyProvider.server.test.ts 'app/routes/app.$tenant.test.tsx'`
|
||||
- `pnpm typecheck`
|
||||
- `pnpm lint`
|
||||
- `pnpm run verify:i18n`
|
||||
- `pnpm run verify:billing-boundary-baseline`
|
||||
|
||||
Hinweis Testabdeckung:
|
||||
- Der isolierte direkte Lauf von `app/routes/app.$tenant/dashboard.test.tsx` bleibt ein bestehender Mixed-Environment-Testfall: Loader-Imports sind server-only, Render-Assertions brauchen jsdom. Die Dashboard-Änderung ist via Typecheck abgedeckt; die fokussierten grünen Tests decken die Billing-/Webhook-Regressionen ab.
|
||||
|
||||
Fortschritt: **AK-P20: 3/8 DoD = 37,5 % done**.
|
||||
|
||||
Abgehakt: Hell/Dunkel ohne System-Modus; Billing-Konnektor/RLS; Erste-Schritte-Checkliste.
|
||||
|
||||
Teilweise umgesetzt, aber noch nicht DoD-grün: Legacy-Provider-Abo-Baukasten-Grundschema; Trial/Dunning/Frozen mit Webhook-Sync, Dunning-Notifications, Usage-Drossel und erster Read-only-Blockade; read-only Subscription-Oberfläche; Auto-SHK-Provisionierung; Demo-Daten-Knopf.
|
||||
|
||||
Selbst machbar offen: Frozen-Read-Only noch route-übergreifend härtbar und Demo-ausblenden-Filter.
|
||||
|
||||
**2026-07-01 · AK-P20 Slice 3 Nachzug: Demo-Daten in Listen standardmäßig ausblenden**
|
||||
|
||||
Umgesetzt:
|
||||
- Demo-Daten werden in Projektlisten, Projekt-Board, Aufgabenliste und Kontaktliste standardmäßig serverseitig ausgeblendet (`isDemoData=false`).
|
||||
- Explizites Anzeigen läuft einheitlich über `demo=show`; Projekte/Aufgaben bieten einen Toggle-Link, Kontakte nutzen den bestehenden Filter-Submit.
|
||||
- Kontaktlisten-Query serialisiert und parst den Demo-Filter stabil, inklusive Unit-Test.
|
||||
- i18n-Keys für „Demo-Daten anzeigen/ausblenden" in Deutsch und Englisch ergänzt.
|
||||
|
||||
Proof:
|
||||
- `pnpm --filter @hivegrid/web exec vitest run app/utils/services/.server/billingStatusService.test.ts app/utils/services/.server/billingDunningService.test.ts app/routes/webhooks.legacyProvider.test.ts app/utils/legacyProvider.server.test.ts 'app/routes/app.$tenant.test.tsx' app/utils/integrations/crm/kontaktListQuery.test.ts`
|
||||
- `pnpm typecheck`
|
||||
- `pnpm lint`
|
||||
- `pnpm run verify:i18n`
|
||||
- `pnpm run verify:billing-boundary-baseline`
|
||||
- `pnpm run verify:onboarding-flow`
|
||||
|
||||
Fortschritt: **AK-P20: 4/8 DoD = 50 % done**.
|
||||
|
||||
Abgehakt: Hell/Dunkel ohne System-Modus; Billing-Konnektor/RLS; Erste-Schritte-Checkliste; Demo-Daten-Knopf plus Demo-ausblenden-Filter.
|
||||
|
||||
Teilweise umgesetzt, aber noch nicht DoD-grün: Legacy-Provider-Abo-Baukasten-Grundschema; Trial/Dunning/Frozen mit Webhook-Sync, Dunning-Notifications, Usage-Drossel und erster Read-only-Blockade; read-only Subscription-Oberfläche; Auto-SHK-Provisionierung.
|
||||
|
||||
Selbst machbar offen: Frozen-Read-Only noch route-übergreifend härtbar. Der zentrale Guard existiert aktuell nicht als Request-/Action-Middleware; ein flächiger Route-Patch hätte hohen Blast-Radius und sollte als eigener, gezielter Nachzug umgesetzt werden.
|
||||
|
||||
Blockiert/offen durch externes Delta: finale Subframe-/Screen-Integration aus `D-P20`.
|
||||
|
||||
**2026-07-02 · AK-P20 Slice 5 Nachzug: Frozen-ReadOnly zentral gehärtet**
|
||||
|
||||
Umgesetzt:
|
||||
- Mutierende Tenant-Requests werden im zentralen Permission-Boundary `verifyUserHasPermission()` gegen den Billing-ReadOnly-State geprüft.
|
||||
- `past_due`, `frozen` und `cancelled` blockieren permission-gated Tenant-Schreibaktionen mit HTTP 423 und dem Klartext-Key `billing:status.readOnly`.
|
||||
- Billing-Recovery bleibt erlaubt: `/settings/subscription` ist als Ausnahme freigegeben, damit Customer-Portal/Zahlungs- und Kündigungsaktionen erreichbar bleiben.
|
||||
- Bestehende Tenant-Shell-Actions (Feedback/Support) bleiben zusätzlich durch den bisherigen ReadOnly-Check geschützt.
|
||||
|
||||
Proof:
|
||||
- `pnpm --filter @hivegrid/web exec vitest run 'app/routes/app.$tenant.test.tsx' app/utils/helpers/.server/PermissionsService.billing-readonly.test.ts`
|
||||
- `pnpm typecheck`
|
||||
- `pnpm lint`
|
||||
- `pnpm run verify:i18n`
|
||||
- `pnpm run verify:billing-boundary-baseline`
|
||||
|
||||
Fortschritt: **AK-P20: 6/8 DoD = 75 % done**.
|
||||
|
||||
Abgehakt: Hell/Dunkel ohne System-Modus; Billing-Konnektor/RLS; Erste-Schritte-Checkliste; Demo-Daten-Knopf plus Demo-ausblenden-Filter; Auto-SHK-Provisionierung; Trial/Dunning/Frozen/Usage-Drossel.
|
||||
|
||||
Teilweise umgesetzt, aber noch nicht DoD-grün: Legacy-Provider-Abo-Baukasten-Grundschema; read-only Subscription-Oberfläche ohne Pricing-/Upgrade-/Plan-Wechsel-UI.
|
||||
|
||||
Selbst machbar offen: AD-26-Cleanup von verbliebenen AI-Credits-/Credits-Entitlement-Resten prüfen und, falls scope-konform, bereinigen.
|
||||
|
||||
Blockiert/offen durch externes Delta: finale Subframe-/Screen-Integration aus `D-P20`.
|
||||
|
||||
**2026-07-02 · AK-P20 Slice 4 Nachzug: Auto-SHK-Provisionierung vervollständigt**
|
||||
|
||||
Umgesetzt:
|
||||
- `provisionShkTenantDefaults()` orchestriert jetzt alle vorhandenen SHK-Seed-Bausteine: Rollen, Default-Sales-Pipeline, Custom-Field-Template-Seed, Abnahmeformular-Template, Projekt-Template, Erste-Schritte-Checkliste.
|
||||
- Die bisher direkt in der Forms-Route liegenden SHK-Form-Templates wurden in `modules/forms/services/shkFormTemplates.server.ts` extrahiert und werden beim Signup automatisch mit lokalisierten Labels angelegt.
|
||||
- Der bestehende Forms-Admin-Button nutzt denselben Seed-Service weiter; kein zweiter Seed-Pfad.
|
||||
- Hinweis: Die Custom-Field-Template-Liste bleibt bewusst leer, weil der bestehende Code sie bis zum SHK-Domain-Workshop nicht mit erfundenen Feldern füllt. Der Provisioning-Hook ist verdrahtet.
|
||||
|
||||
Proof:
|
||||
- `pnpm --filter @hivegrid/web exec vitest run app/modules/forms/services/shkFormTemplates.server.test.ts app/utils/services/shkRoles.server.test.ts app/utils/services/authService.transactional-email.test.ts`
|
||||
- `pnpm typecheck`
|
||||
- `pnpm lint`
|
||||
- `pnpm run verify:i18n`
|
||||
- `pnpm run verify:onboarding-flow`
|
||||
|
||||
Fortschritt: **AK-P20: 5/8 DoD = 62,5 % done**.
|
||||
|
||||
Abgehakt: Hell/Dunkel ohne System-Modus; Billing-Konnektor/RLS; Erste-Schritte-Checkliste; Demo-Daten-Knopf plus Demo-ausblenden-Filter; Auto-SHK-Provisionierung.
|
||||
|
||||
Teilweise umgesetzt, aber noch nicht DoD-grün: Legacy-Provider-Abo-Baukasten-Grundschema; Trial/Dunning/Frozen mit Webhook-Sync, Dunning-Notifications, Usage-Drossel und erster Read-only-Blockade; read-only Subscription-Oberfläche.
|
||||
|
||||
Selbst machbar offen: Frozen-Read-Only noch route-übergreifend härtbar; AD-26-Cleanup von verbliebenen AI-Credits-/Credits-Entitlement-Resten.
|
||||
|
||||
Blockiert/offen durch externes Delta: finale Subframe-/Screen-Integration aus `D-P20`.
|
||||
|
||||
**2026-07-02 · AK-P20 Slice 6 Nachzug: In-App-Planwechsel entfernt**
|
||||
|
||||
Umgesetzt:
|
||||
- Die Legacy-Route `/subscribe/:tenant` rendert keine Pricing-/Planwechsel-UI mehr und startet keine Payment-Checkout-Session mehr; GET/POST fallen auf die read-only Subscription-Übersicht zurück.
|
||||
- Interne Subscription-required-Links zeigen direkt auf `/settings/subscription?subscription_required=1` statt auf die alte Checkout-Seite.
|
||||
- Header-/ProFeature-Einstiege verlinken nur noch die Subscription-Übersicht; Customer-Portal, Zahlungsmethoden und Kündigen bleiben in `/settings/subscription` erhalten.
|
||||
- Billing-Boundary-Test ergänzt: Legacy-Subscribe muss frei von Checkout-Writes, `PlansGrouped` und direkten Billing-Imports bleiben.
|
||||
|
||||
Proof:
|
||||
- `pnpm --filter @hivegrid/web exec vitest run 'app/routes/subscribe.$tenant.test.tsx' app/utils/app/SubscriptionUrlUtils.test.ts`
|
||||
- `pnpm typecheck`
|
||||
- `pnpm lint`
|
||||
- `pnpm run verify:i18n`
|
||||
- `pnpm exec vitest run packages/db/src/subscriptions.server.test.ts packages/db/src/subscriptions-boundary.test.ts apps/web/app/utils/services/.server/subscriptionService.test.ts`
|
||||
- `pnpm run verify:billing-boundary-baseline`
|
||||
|
||||
Fortschritt: **AK-P20: 7/8 DoD = 87,5 % done**.
|
||||
|
||||
Abgehakt: Hell/Dunkel ohne System-Modus; Billing-Konnektor/RLS; Erste-Schritte-Checkliste; Demo-Daten-Knopf plus Demo-ausblenden-Filter; Auto-SHK-Provisionierung; Trial/Dunning/Frozen/Usage-Drossel; read-only Subscription-Oberfläche ohne Pricing-/Upgrade-/Plan-Wechsel-UI.
|
||||
|
||||
Offen nach Recut: Der alte Legacy-Provider-Abo-Baukasten-Abschluss wird nicht weitergebaut. Der saubere Abschluss laeuft ueber
|
||||
`BILL-02` bis `BILL-05`: lokale Plan-/Seat-/Entitlement-Domain, Lago-Gateway, Mollie-Gateway und Billing-Sync.
|
||||
|
||||
Blockiert/offen durch externes Delta: finale Subframe-/Screen-Integration aus `D-P20`.
|
||||
|
||||
**2026-07-02 · AK-P20 Slice 7 Nachzug: Seat-Typen im Admin-Pricing blockiert**
|
||||
|
||||
Umgesetzt:
|
||||
- Die Standard-Plan-Seeds erzeugen keine `PER_SEAT`-Pläne mehr.
|
||||
- Die Plattform-Admin-Pricing-Auswahl nutzt eine zentrale HiveGrid-Pricing-Policy ohne `PER_SEAT`.
|
||||
- `pricing.new`, `pricing.edit` und `create-all-plans` lehnen manipulierte `PER_SEAT`-Formulare serverseitig mit `shared.invalidForm` ab.
|
||||
- Test ergänzt: Policy und File-Seeds bleiben frei von Seat-Type-Plänen.
|
||||
|
||||
Proof:
|
||||
- `pnpm --filter @hivegrid/web exec vitest run app/application/pricing/pricingModelPolicy.test.ts`
|
||||
- `pnpm typecheck`
|
||||
- `pnpm lint`
|
||||
- `pnpm run verify:i18n`
|
||||
- `pnpm run verify:billing-boundary-baseline`
|
||||
|
||||
Fortschritt: **AK-P20: 7/8 DoD = 87,5 % done**.
|
||||
|
||||
Weiterhin offen nach Recut: Der alte Legacy-Provider-Abo-Baukasten-DoD ist durch `AD-27` ersetzt. Keine weitere
|
||||
Legacy-Provider-Admin-Positionen-Arbeit in AK-P20; neue Billing-Arbeit ueber `BILL-02` bis `BILL-05`.
|
||||
@@ -1,47 +1,51 @@
|
||||
# AK-P21 · P21 DSGVO (Export + Lösch-Workflow) + Feedback-Widget
|
||||
|
||||
> ⚠️ **Billing-Recut 2026-07-04 ([[AD-27]]):** Tenant-Löschung storniert kuenftig den Billing-State ueber die
|
||||
> Lago/Mollie/HiveGrid-Billing-Gateways aus `BILL-*`, nicht ueber Legacy-Provider. Historische Legacy-Provider-Cancel-Erwaehnungen sind
|
||||
> als alter Adaptervertrag zu lesen und duerfen nicht als neue Legacy-Provider-Dependency weitergebaut werden.
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Dev (Code) |
|
||||
| **Owner** | Akeshan |
|
||||
| **Phase** | P21 — DSGVO & Launch-Reife |
|
||||
| **Cycle/Fenster** | W4 — USP, Härtung & Launch · fällig 2026-07-09 · **Gate W4 (FREEZE)** |
|
||||
| **Status** | geplant |
|
||||
| **Status** | Blocked / On Hold, Teilumsetzung Backend/Fundament |
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `AK-P20` (Billing — Tenant-Löschung ruft Stripe-Cancel; Feedback-Widget speist Admin-Support-Inbox aus AK-P19)
|
||||
- **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)
|
||||
- **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, **Stripe-Cancel**, 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, **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.
|
||||
|
||||
## 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-Löschung [`/admin/privacy/deletion`, `/:requestId`] | Multi-Step-Wizard: Erklärung (30-Tage-Grace, Read-Only, Hard-Delete) → Export-Angebot → Stripe-Hinweis (Pro-rata) → Passwort+2FA → **Slug als Confirm-Phrase**; Grace-Countdown + Abbruch |
|
||||
| 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) |
|
||||
| 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
|
||||
- [ ] **Tenant-Löschung**: **Crypto-Shredding** (per-Tenant-DEK) + **Stripe-Cancel** + Storage/Cache/Index-Bereinigung (AD-8); 30-Tage-Grace Read-Only + Abbruch; **Slug als Confirm-Phrase**; Stripe-Cancel erst beim Hard-Delete-Cron
|
||||
- [ ] **AVV-Download** + Akzeptanz-History + Re-Akzeptanz (14-Tage-Frist, danach Read-Only-Sperre); **Subprozessoren-Liste** mit Drittland-Klartext (v1 EU-only)
|
||||
- [ ] **DSGVO-Auskunft als dokumentiertes Playbook** (Suche → Kontakt-Detail → CSV → Anwalts-Vorlage → Frist-Task +25 Tage) — kein automatisches Tooling
|
||||
- [ ] **In-App-Feedback-Widget** → speist Admin-Support-Inbox (AK-P19, generische Quelle)
|
||||
- [ ] **Minimal-FAQ**-Seite (statisch)
|
||||
- [ ] Alle Screens **mobil tauglich** (PWA/responsive, AD-17); kein nativer Client; PWA-Installierbarkeit/Web-Push → v2
|
||||
- [ ] Permissions: `privacy.user_export.self` (implizit jeder User), `privacy.tenant_export`/`privacy.tenant_deletion`/`privacy.avv.*`/`privacy.subprocessors.read` (über `tenant.admin`)
|
||||
- [ ] **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-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] **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] 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.
|
||||
- **Crypto-Shredding** (AD-8): per-Tenant-DEK löschen → Daten kryptographisch unlesbar; Stripe-Cancel + Storage/Cache/Index-Cleanup beim Hard-Delete-Cron; 30-Tage-Grace Read-Only-Middleware (Reuse aus AK-P20 Frozen-Modus).
|
||||
- **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).
|
||||
|
||||
@@ -56,3 +60,53 @@ Den **DSGVO-Lebenszyklus + Launch-Reife** (letzte v1-Phase): tenant- und user-we
|
||||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
- [ ] Plane-Ticket `AK-P21` aktualisiert
|
||||
|
||||
## Umsetzungsnotiz
|
||||
|
||||
### 2026-07-02 — Teilumsetzung Backend/Fundament
|
||||
|
||||
Proof:
|
||||
- Prisma/Isolation: `prisma/schema/gdpr.prisma`, `prisma/rls/gdpr-isolation.sql`, Tenant-Snapshot-Registry und generierter Prisma-Client.
|
||||
- Services: `@hivegrid/db/privacy-gdpr.server` fuer Export-Limits, 72h-Expiry, Tenant-Deletion-Grace/Cancel, AVV-Akzeptanz und Subprozessoren; `createWidgetSupportTicket` fuer Widget → Support-Inbox.
|
||||
- UI/Doku: statische `/help`-FAQ, `docs/compliance/dsgvo-auskunft-playbook.md`, GDPR-Doku-Verweis.
|
||||
- Permissions: `privacy.user_export.self`, `privacy.tenant_export`, `privacy.tenant_deletion`, `privacy.avv.read`, `privacy.avv.accept`, `privacy.subprocessors.read` in Seed, DefaultPermissions, Rollenanzeige und i18n.
|
||||
|
||||
Verifikation:
|
||||
- `pnpm typecheck` gruen
|
||||
- `pnpm lint` gruen
|
||||
- `pnpm exec prisma validate` gruen
|
||||
- `pnpm run verify:tenant-isolation-report` gruen
|
||||
- `pnpm run verify:security-gdpr-docs` gruen
|
||||
- Fokus-Tests: 55/55 gruen (`privacy-gdpr`, `support-tickets`, `Feedback.server`, `roleDisplay`, `permissions-seed`, Tenant-Models, routes/i18n/disabled-plugin-links)
|
||||
- Permission-Matrix-Einzeltests: 22/22 gruen; Wrapper `pnpm run verify:permission-matrix` scheitert auf Windows mit `spawn pnpm ENOENT`.
|
||||
- Breites `pnpm test` timed auf Windows nach 302s ohne sichtbare Assertion-Failures aus; Ausgabe nur bekannte Stderr-Faelle (Session-Cookie-Warnung, Admin-SSO db-down Mock, Notification Redis Mock, i18next-Warnung).
|
||||
|
||||
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-02 — Nachzug selbst machbarer Worker-/Queue-Aspekte
|
||||
|
||||
Proof:
|
||||
- Export: `packages/exports/src/zip.ts` erzeugt ZIPs mit README/manifest/data-Dateien; `apps/worker/src/jobs/privacy-gdpr-export.ts` baut GDPR-Export-Artefakte; `apps/worker/src/handlers.ts` routet `gdpr_user_self`/`gdpr_tenant_full` in den GDPR-Statuspfad.
|
||||
- Web-Queue: `apps/web/app/utils/privacy/gdprExportQueue.server.ts`; `/app/:tenant/settings/privacy` legt bei Self-Service-Export jetzt `GdprExportJob` an und enqueue't den Export.
|
||||
- Tenant-Löschung: `apps/worker/src/jobs/privacy-tenant-deletion.ts` definiert und testet die Hard-Delete-Reihenfolge Billing-Cancel → Storage-Prefix → Search-Dokumente → Crypto-Shredding → Tenant-Rows.
|
||||
- Nachzug: `apps/worker/src/jobs/privacy-gdpr-export-bootstrap.ts` bootstrapped den GDPR-Export-Service produktiv mit S3-`PutObjectCommand` und konservativen User-Self/Tenant-Full-Bundle-Loadern (User/Tenant/TenantUser/AuditEvent/NotificationPreference/NotificationDelivery).
|
||||
|
||||
Verifikation:
|
||||
- `pnpm typecheck` gruen
|
||||
- `pnpm --filter @hivegrid/exports typecheck` gruen
|
||||
- `pnpm --filter @hivegrid/worker typecheck` gruen
|
||||
- `pnpm lint` gruen
|
||||
- `pnpm exec prisma validate` gruen
|
||||
- `pnpm run verify:tenant-isolation-report` gruen
|
||||
- `pnpm run verify:security-gdpr-docs` gruen
|
||||
- Fokus-Tests: 141/141 gruen (AK-P21 DB/Web/Worker/Queue/ZIP/Feedback/Permissions/i18n)
|
||||
- Nachzug-Fokus: 97/97 gruen (`privacy-gdpr`, GDPR-Export-Bootstrap/-Runner, Tenant-Deletion-Runner, Handler, Web-Queue)
|
||||
- Permission-Matrix-Einzeltests: 22/22 gruen; Wrapper bleibt auf Windows mit `spawn pnpm ENOENT` ein bekanntes lokales Skriptproblem.
|
||||
- `git diff --check -- . ':(exclude)packages/db/generated/prisma/client/**'` gruen.
|
||||
|
||||
DoD-Stand: **4/8 = 50 % done**. Selbst machbarer Backend-/Worker-Nachzug ist erledigt; offen bleiben signed Download/E-Mail, breiteres Fachmodul-Inventar fuer Tenant-Full, produktive Tenant-Deletion-Bootstrap-Anbindung/Read-Only-Hook, AVV-PDF/Re-Akzeptanz-Read-Only/Subprozessor-Screen und finale mobile Screens aus `D-P21`.
|
||||
|
||||
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`.
|
||||
@@ -6,7 +6,9 @@
|
||||
| **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** | geplant |
|
||||
| **Status** | umgesetzt (2026-07-07) — Dev-DoD 7/7 = 100 %, wartet auf Owner-Freigabe für Done |
|
||||
|
||||
**🎨 design-nachzug: offen** (seit 2026-07-07) — Interim-UI aus `~/ui` steht; finale Subframe-Optik aus `D-P3` ausstehend.
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `R-P1b` (Service-Kerne: Audit-Hash-Kette, `notify()`, i18n-Engine), `R-P2b` (RLS + Permissions für `audit.read`)
|
||||
@@ -18,23 +20,30 @@
|
||||
Die **Bedien-Oberflächen** der in P1 gebauten Plattformdienste: **Audit-Viewer** (gefilterter, permission-gegateter Trail mit deutschem Summary-Text, Actor-Kind-Marker, Diff-Detail-Drawer, NDJSON/CSV-Export ins Hetzner-Object-Storage mit Zweck-Pflichtfeld), **Notification-Center** (In-App via SSE, Read-Status, Deeplink, Tabs Alle/Ungelesen, Bulk-Clear) + **Notification-Settings** (Event-Typen je Modul, In-App/Email-Toggle, Master „alle Emails aus"), sowie die **Sprach-Settings** (v1 DE-only-Hinweis; alle Strings durch `t()`, `verify:i18n` grün).
|
||||
|
||||
## Benötigte Screens (Backend bedient — Design liefert `D-P3` aus `D-D0a`/`D-D0b`)
|
||||
|
||||
> **Routen-Notation (Stand 2026-07-07, host-aware):** Die Route-Convention mountet `routes/admin/*` zusätzlich
|
||||
> als **Admin-Host-Alias ohne `/admin`-Präfix** und `app/:tenant/*` auf dem App-Host **ohne `/app`-Präfix**.
|
||||
> Kanonisch erreichbar sind die Flächen also unter `admin.<domain>/audit` bzw. `<app>/<tenant>/notifications`;
|
||||
> die pfadbasierten Formen (`/admin/audit`, `/app/:tenant/…`) existieren weiterhin. Angegeben ist unten die
|
||||
> kanonische URL + das Route-Modul.
|
||||
|
||||
| Screen [Route] | Kern-Inhalt | Liefert (Design) |
|
||||
|---|---|---|
|
||||
| Audit-Viewer [`/admin/audit`] | Zeit/Actor (+Kind-Marker)/Aktion/Subjekt/DE-Summary · Filter (Zeitraum/Actor/Kategorie/Subjekt-Typ) · Diff-Detail-Drawer · Export-Button | `D-P3` (A2+Drawer) |
|
||||
| Audit-Export-Jobs [`/admin/audit/exports` +`/new` +`/:id`] | Job-Liste · Anlage (Filter, Format, Zweck) · Status + signed-URL-Download | `D-P3` (A2) |
|
||||
| Notification-Center [Topbar-Drawer + `/notifications`] | Titel/Body/Actor/Zeit/Read-Status, Tabs Alle/Ungelesen, Bulk-Clear, Bounce-Klartext | `D-P3` (A2) |
|
||||
| Notification-Settings [`/settings/notifications`] | Event-Typen je Modul, In-App/Email-Toggle + Priority, Master „alle Emails aus" | `D-P3` (A6) |
|
||||
| Audit-Viewer [Admin-Host `/audit` · Modul `routes/admin/audit.tsx`] | Zeit/Actor (+Kind-Marker)/Aktion/Subjekt/DE-Summary · Filter (Zeitraum/Actor/Kategorie/Subjekt-Typ) · Diff-Detail-Drawer · Export-Button | `D-P3` (A2+Drawer) |
|
||||
| Audit-Export [Admin-Host `/audit-export` · Modul `routes/admin/audit-export.tsx`] — *v1 synchron statt Job-Liste (`/admin/audit/exports*` = v2, s. Vorab-Entscheidungen)* | Anlage (Filter, Format, Zweck-Pflichtfeld) · signed-URL-Download · CSV/PDF-Fallback | `D-P3` (A2) |
|
||||
| Notification-Center [Topbar-Drawer + App-Host `/:tenant/notifications` · Modul `routes/app.$tenant/notifications.tsx`] | Titel/Body/Actor/Zeit/Read-Status, Tabs Alle/Ungelesen, Bulk-Clear, Bounce-Klartext | `D-P3` (A2) |
|
||||
| Notification-Settings [App-Host `/:tenant/settings/notifications` · Modul `routes/app.$tenant/settings/notifications.tsx`] | Event-Typen je Modul, In-App/Email-Toggle + Priority, Master „alle Emails aus" | `D-P3` (A6) |
|
||||
|
||||
*Eingebettet (kein eigener Screen): Per-Subject-Audit-Drawer in jeder Detail-View, Per-User-Audit-Drawer in `/admin/users/:id`, DE-Sprach-Hinweis im Profil (P2). Davids P3-Screens werden über `D-P3` (Compose aus D0) geliefert.*
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **Audit-Viewer** permission-gegated (`audit.read`), server-seitige Filter, DE-Summary-Text, Actor-Kind-Marker
|
||||
- [ ] **Diff-Detail-Drawer** (Feld-für-Feld Vorher/Nachher; Maskierung bei sensiblen Werten)
|
||||
- [ ] **NDJSON/CSV-Export** ins Hetzner-Object-Storage + Zweck-Pflichtfeld + Export-Job-Status/Download; jeder Export selbst auditiert (`audit.exported`); fixe Default-Retention + Cron-Auto-Löschung
|
||||
- [ ] **Notification-Center** (SSE, Read-Status, Deeplink, Tabs, Bulk-Clear, Bounce-Klartext)
|
||||
- [ ] **Notification-Settings** (Event-Typen je Modul, In-App/Email-Toggle, Master-Toggle)
|
||||
- [ ] **Sprach-Settings DE** — alle Strings durch `t()`, vollständige `de`-Locale, `verify:i18n` grün; `Contact.language`-Feld vorhanden (Outbound ab v2)
|
||||
- [ ] *(→ v2)* Quiet-Hours/Bündelung/Push-Kanal/Retention-Editor/Legal-Hold/Saved-Views/Sprach-Wechsler ausgeschlossen
|
||||
- [x] **Audit-Viewer** permission-gegated (`audit.read`), server-seitige Filter, DE-Summary-Text, Actor-Kind-Marker — *AP-1* (+ Interim-Screen *AP-6*)
|
||||
- [x] **Diff-Detail-Drawer** (Feld-für-Feld Vorher/Nachher; Maskierung bei sensiblen Werten) — *AP-6*: `beforeDiff`/`afterDiff`/`summaryText` additiv an `AuditEvent` (Owner-Freigabe 2026-07-06), echter `~/ui`-Drawer mit Feld-für-Feld-Diff, maskierte Felder als „Wert geändert"; abgeleitete Summary bleibt Fallback für Alt-Zeilen. *Abgrenzung:* flächige Diff-Befüllung (Auto-Audit-Middleware) + Hash-Chain-Bindung der Diffs bleiben R-P1b/Raffael (Vermerk in `R-P1b.md`).
|
||||
- [x] **NDJSON/CSV-Export** ins Hetzner-Object-Storage + Zweck-Pflichtfeld + Export-Job-Status/Download; jeder Export selbst auditiert (`audit.exported`); fixe Default-Retention + Cron-Auto-Löschung — *AP-2* (+ Interim-Screen *AP-6*)
|
||||
- [x] **Notification-Center** (SSE, Read-Status, Deeplink, Tabs, Bulk-Clear, Bounce-Klartext) — *AP-3* + *AP-6*: Topbar-Drawer (echter `~/ui`-Drawer), Live-Unseen-Count via SSE, Deeplink-Kontrakt `payloadMetadata.deeplink` (validiert, app-relativ) als Interim-UI (AD-28) — nicht mehr David-blockiert.
|
||||
- [x] **Notification-Settings** (Event-Typen je Modul, In-App/Email-Toggle, Master-Toggle) — *AP-4* (+ Interim-Screen *AP-6*)
|
||||
- [x] **Sprach-Settings DE** — alle Strings durch `t()`, vollständige `de`-Locale, `verify:i18n` grün (*AP-5*); `Kontakt.language`-Feld ergänzt (*AP-6*, entsperrt durch CRM-P6-Merge; nullable, kein v1-Editor, Vermerk in `R-P6.md`)
|
||||
- [x] *(→ v2)* Quiet-Hours/Bündelung/Push-Kanal/Retention-Editor/Legal-Hold/Saved-Views/Sprach-Wechsler ausgeschlossen
|
||||
|
||||
## Technische Bausteine
|
||||
- **Keine neuen Kern-Entities** — liest/bedient die in `R-P1b` angelegten `AuditEntry`/`Notification`/`NotificationPreference`. Neu nur `AuditExportJob` ist **v2** → in v1 fixe Default-Retention statt Job-Editor (Boilerplate liefert Retention-Cron + PDF-Export). Eigene `prisma/schema/*.prisma` falls Felder ergänzt (AD-21).
|
||||
@@ -51,6 +60,138 @@ Die **Bedien-Oberflächen** der in P1 gebauten Plattformdienste: **Audit-Viewer*
|
||||
- `_bmad-output/specs/M21-audit-log.md`, `M22-notifications.md`, `M30-i18n.md` (Oberflächen-Teile)
|
||||
|
||||
## Dev-Nachzug (nach Davids `D-P3`-Delta)
|
||||
- [ ] Audit-/Notif-Oberflächen an Davids UI angepasst
|
||||
|
||||
**Interim-UI (Vorschau, Stand 2026-07-07):** Alle vier Flächen aus `~/ui` gebaut (AD-28) —
|
||||
`apps/web/app/components/screens/audit/{AuditListPage,AuditExportPage}.tsx`,
|
||||
`apps/web/app/components/screens/notifications/{NotificationCenterPage,NotificationSettingsPage,NotificationsDrawer}.tsx`.
|
||||
Proof: Smoke `tests/e2e/{audit,notifications}.spec.ts`, Hot-Swap-Adapter `auditList`/`notificationCenter`
|
||||
(`packages/ui-app/src/adapters/*.hot-swap.test.ts`) grün; Visual-Baseline deferred wie R-P2a/AK-P4b
|
||||
(keine Snapshot-Harness — Interim-Baseline wird beim David-Nachzug gezogen).
|
||||
Refactor-Nachzug offen: finale Subframe-Optik aus `D-P3` (Plane-Label `design-nachzug`).
|
||||
|
||||
- [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
|
||||
- [ ] Plane-Ticket `AK-P3` aktualisiert
|
||||
- [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)
|
||||
- **Audit-Export v1 = synchron** (Zweck-Pflichtfeld + Object-Storage + signed-URL + `audit.exported` + Retention-Cron). **`AuditExportJob`-Entity + `/admin/audit/exports`-Job-Liste = v2** (Technische-Bausteine schlagen die Screen-Tabelle).
|
||||
- **Permission-Key:** bestehende `admin.auditTrails.view` (Admin) / `app.settings.auditTrails.view` (Tenant) wiederverwenden. DoD-Wortlaut `audit.read` ist damit der **Alias** auf `admin.auditTrails.view` (kein Key-Duplikat).
|
||||
|
||||
## Umsetzungsstand (Claude/Akeshan) — Branch `feat/AK-P3`
|
||||
|
||||
### AP-1 · Audit-Viewer `/admin/audit` — 2026-06-24
|
||||
**Gebaut (Commit `2bee1ecaa`):**
|
||||
- `packages/db/src/audit-events-query.server.ts` — `listAuditEvents` (paginiert, server-seitige Filter, neueste zuerst, nutzt vorhandene Indizes) + Subpath-Export.
|
||||
- `packages/view-models/src/audit/audit-list.vm.ts` — reiner Builder mit **Actor-Kind-Marker** (`deriveAuditActorKind`) + **abgeleiteter DE-Summary** (`deriveAuditSummaryKey` → i18n-Key + Params). VM-Unit-Test 5/5.
|
||||
- `apps/web/app/routes/admin/audit.tsx` — Route auf **`AuditEvent`** (nicht Legacy `Log`), gegated `admin.auditTrails.view`; Filter Zeitraum/Actor/Aktion/Subjekt-Typ/Ergebnis; Detail-Disclosure rendert die (write-time sanitisierte) `metadata` mit Maskierung; Pagination.
|
||||
- Reachability: AdminSidebar-Eintrag + UI-Registry-ID `adminAudit`, Permission-gegated; i18n-Keys `audit.*` in `settings.json` (de+en) + `app.sidebar.audit` (translations.json de+en).
|
||||
|
||||
**DoD-Stand nach AP-1:**
|
||||
- DoD 1 (Viewer permission-gegated, server-Filter, DE-Summary, Actor-Kind-Marker): **done**.
|
||||
- DoD 2 (Diff-Detail-Drawer): **teilweise** — Metadata-Disclosure + Maskierung erledigt; **strukturiertes Feld-für-Feld Vorher/Nachher blockiert** (`AuditEvent` ohne `before/after_diff`-Spalten → Coordination-Item mit R-P1b/Raffael, AD-21 core.prisma; siehe Plan §5.2). Persistente `summary_text` ebenso (LOCKED ENTITY-MODEL vs. reale Tabelle).
|
||||
- DoD 3-6: offen (AP-2..AP-5). DoD 7 (v2-Ausschlüsse): erfüllt (nicht gebaut).
|
||||
- **%-Done: ~1,5 / 7 DoD ≈ 21 %** · selbst machbar offen: AP-2..AP-5 + Querschnitt/Tests · blockiert: strukturierter Diff/persist. Summary (R-P1b), Davids `D-P3`-Screens, `Kontakt.language` (P6+).
|
||||
|
||||
**Proof:** view-models + db + web Typecheck grün · `verify:i18n` Exit 0 · VM-Test 5/5 · pre-commit-Hooks (eslint-baseline/lint-staged/secrets) grün · Node 22.15 (Typecheck/i18n unkritisch).
|
||||
|
||||
### AP-2 · Audit-Export ins Object-Storage — 2026-06-24
|
||||
**Gebaut (Commit `8b65a9135`):**
|
||||
- `apps/web/app/utils/audit/auditExportStorage.server.ts` — `runAuditExportToStorage`: baut CSV/NDJSON, lädt via `putBufferAsFile` nach `audit-exports/<scope>/...`, gibt kurzlebige **signed-URL** zurück, schreibt **`audit.exported`** mit **Zweck (Pflicht)**. Typisierte Fehler (kein Zweck / kein Storage).
|
||||
- `audit-export.helpers.server.ts` — `renderAuditExportNdjson` (+ Test 2/2).
|
||||
- `apps/web/app/routes/admin/audit-export.tsx` — Zweck-Pflichtfeld + Format-Select (CSV/NDJSON) + POST-Action mit Ergebnis-/Fehler-Panel; bestehender Direkt-CSV/PDF-Stream bleibt als Fallback. i18n `auditExport.storage.*` (de+en).
|
||||
|
||||
**DoD-Stand nach AP-2:**
|
||||
- DoD 3 (Export ins Object-Storage + Zweck + `audit.exported` + NDJSON/CSV + Retention-Cron): **done**.
|
||||
- **Retention-Cron nachgezogen (Commit `5b463c2dd`):** `registerAuditRetentionCron` + Konstanten in `audit-retention.ts` (+2 Tests), Scheduler+Worker im Worker-`general`-Group (`apps/worker/src/index.ts`), nightly 03:30 UTC. Compliance-sicher: pro Tenant werden die regulatorischen Scopes (soc2/hipaa/gdpr) aufgelöst → Policy kürzt nie unter die geforderte Aufbewahrung (SOC2/HIPAA 7 J, GDPR 6 J, sonst 365 T). Lösch-Lauf selbst auditiert (`audit.retention.pruned`). Runtime-Verifikation auf Staging (Redis+DB) wie bei `plugin-audit-retention`; lokal via Typecheck + Unit-Tests grün.
|
||||
- **Hinweis (kein App-Code möglich):** Auto-Löschung der Export-**Files** im Object-Storage = Bucket-Lifecycle-Regel auf `audit-exports/` (Infra), da v1 keine `AuditExportJob`-Tracking-Tabelle hat (= v2) und der Storage-Adapter keine List-Operation bietet. Signed-URL-TTL = fixe Default-Retention.
|
||||
|
||||
**Proof:** web Typecheck 0 Fehler · `verify:i18n` Exit 0 · NDJSON-Test 2/2 · pre-commit-Hooks grün.
|
||||
|
||||
### AP-3 · Notification-Center-Logik — 2026-06-25
|
||||
**Gebaut (Commit `5422c26d5`):**
|
||||
- `packages/db/src/notifications.server.ts` — `markAllInAppNotificationDeliveriesRead` (Bulk-Read, tenant/user-scoped, toleriert 0 Treffer, gibt Count zurück) + erweiterte `updateMany`-Typ-Union. 3 neue Unit-Tests (gesamt 29/29 grün).
|
||||
- `apps/web/app/routes/app.$tenant/notifications.tsx` — neue Route-Action `mark-all-read` (CSRF-validiert, ruft Bulk-Read).
|
||||
- `apps/web/app/components/notifications/NotificationCenter.tsx` — **Tabs Alle/Ungelesen** (Client-Filter auf `status`, mit Count je Tab), **Bulk-Clear**-Button (nur sichtbar bei ungelesenen), **Bounce-Klartext** via `deriveBounceMessageKey` (klassifiziert Provider-Fehler in stabile M002-i18n-Keys; roher redaktierter Text nur noch als sekundäres Detail).
|
||||
- i18n `notifications.center.tabs/bulkClear/unreadEmpty/bounce.*` (de+en vollständig).
|
||||
|
||||
**DoD-Stand nach AP-3:**
|
||||
- DoD 4 (Notification-Center): **selbst machbar erledigt** — SSE + Read-Status (Bestand), **Tabs + Bulk-Clear + Bounce-Klartext (neu)**. **Blockiert (Dev-Nachzug nach Davids `D-P3`):** Topbar-Drawer, Live-Unseen-Count, Deeplink je Notification — diese 3 sind UI/Pixel-abhängig und warten auf `D-P3`.
|
||||
|
||||
**Proof:** db Typecheck 0 Fehler · web Typecheck Exit 0 · `verify:i18n` Exit 0 · notifications-db-Test 29/29 · pre-commit-Hooks (test-density/eslint-baseline/lint-staged/secrets) grün · Node 22.15.
|
||||
|
||||
### AP-4 · Notification-Settings — 2026-06-25
|
||||
**Gebaut (Commit `6abda7919`):**
|
||||
- `apps/web/app/routes/app.$tenant/settings/notifications.tsx` — die 3 hartkodierten Kategorien durch eine **Event-Typen-je-Modul-Registry** (`NOTIFICATION_CATEGORY_REGISTRY`: general/billing/team) ersetzt; Loader/UI leiten Kategorien + Modul-Gruppierung daraus ab (Default-Fallback wie Worker `isNotificationEnabled` bleibt erhalten).
|
||||
- **Master „alle Emails aus"** (`set-email-master`-Action): schreibt `EMAIL=off` für **jede** registrierte Kategorie, damit explizite Per-Kategorie-Overrides keine Mails durchlassen. UI-Checkbox spiegelt den Zustand (an, wenn alle Kategorien EMAIL=false).
|
||||
- i18n `settings.notifications.modules.*` + `settings.notifications.master.*` (de+en).
|
||||
- 3 neue Route-Tests (Master an/aus + Render mit Master-Switch + 3 In-App/3 Email).
|
||||
|
||||
**DoD-Stand nach AP-4:**
|
||||
- DoD 5 (Notification-Settings: Event-Typen je Modul, In-App/Email-Toggle, Master-Toggle): **done**.
|
||||
- **Test-Hinweis (environmental, keine Regression):** die Action-Tests (Master + Pre-Existing `update-preference`) brechen lokal auf **Node 22.15** im `postFormRequest`-Helper (undici `new Request` mit `URLSearchParams`-Body, Fehler VOR dem Action-Code, Zeile 85) — gleicher dokumentierter Umgebungsbug wie in der Memory; Loader-/Render-Tests (4/10) grün. CI/Node 22.12 unkritisch. Web-Typecheck + `verify:i18n` grün.
|
||||
|
||||
### AP-5 · Sprach-Settings DE — 2026-06-25
|
||||
**Gebaut (Commit `893a88918`):**
|
||||
- `apps/web/app/components/settings/LanguageSettingsNotice.tsx` — statischer, read-only **DE-only-Hinweis** (v1 nur Deutsch; Sprachwechsler + weitere Locales = v2 laut DoD 7). Alle Strings via `t()`.
|
||||
- eingebunden in die erreichbare Profil-/Settings-Seite (`app.$tenant/settings/profile.tsx`).
|
||||
- i18n `settings.language.*` (de+en vollständig).
|
||||
- Render-Test 2/2 (kein roher i18n-Key leakt ins UI).
|
||||
|
||||
**DoD-Stand nach AP-5:**
|
||||
- DoD 6 (Sprach-Settings DE: alle Strings via `t()`, vollständige de-Locale, `verify:i18n` grün): **selbst machbar done**. **Blockiert:** `Kontakt.language`-Feld nicht baubar, da es vor CRM P6+ **kein `Contact`/`Kontakt`-Model** im Schema gibt (Plan §5.1) — nicht erfunden.
|
||||
|
||||
**Proof:** web Typecheck Exit 0 · `verify:i18n` Exit 0 · LanguageSettingsNotice-Test 2/2 · pre-commit-Hooks grün.
|
||||
|
||||
### Gesamt-DoD-Stand (nach AP-1..AP-5) — alle selbst machbaren Punkte done
|
||||
- DoD 1 **done** · DoD 2 **teilweise** (abgeleitete Variante done; strukturierter Diff + persist. `summary_text` blockiert §5.2 R-P1b/core.prisma) · DoD 3 **done** · DoD 4 **selbst machbar done** (Tabs/Bulk-Clear/Bounce; Topbar-Drawer/Live-Count/Deeplink blockiert via D-P3) · DoD 5 **done** · DoD 6 **selbst machbar done** (`Kontakt.language` blockiert P6+) · DoD 7 erfüllt.
|
||||
- **%-Done: ~6 / 7 DoD ≈ 86 %** · **selbst machbar offen: nichts** · extern blockiert: (a) strukturierter Diff/persist. Summary → R-P1b/Raffael (`core.prisma`, dependency-aware, nicht unilateral); (b) D-P3-Pixel-UI/Topbar-Drawer/Live-Count/Deeplink → David; (c) `Kontakt.language` → CRM P6+.
|
||||
- **Ticket bleibt offen (nicht Done):** 100 % erst, wenn die extern blockierten Punkte aufgelöst sind. Freigabe/Status-Wechsel durch Owner.
|
||||
- **Test-Umgebung:** Action-Tests (Notif-Settings) brechen lokal nur am bekannten Node-22.15-undici-`Request`-Body-Bug (vor dem Action-Code) — environmental, keine Regression; Typecheck/i18n/Render-/DB-Tests grün.
|
||||
|
||||
### Subframe-Befund (2026-06-24)
|
||||
Projekt Basedesign (`f023064a5ca0`) hat nur P2-/Auth-Designs (`WF-P2`-Flows), **keine `D-P3`-Designs** (Audit/Notif/Sprache) → P3-Pixel-UI bleibt Dev-Nachzug. Sync-Ziel ist `apps/web/app/ui` (`~/ui/*`, tailwind-v4).
|
||||
|
||||
### AP-6 · Interim-UI-Vollausbau + Schema-Restpunkte — 2026-07-07 (Branch `akeshan/ak-p3-interim-ui`)
|
||||
|
||||
Die drei „extern blockiert"-Restpunkte vom 2026-06-25 wurden per Owner-Entscheid (2026-07-06, AskUserQuestion:
|
||||
Voll-AD-28-Umbau + beide Schema-Punkte) aufgelöst — **kein Blocker-Ticket war nötig** (D-P3 durch Interim-UI
|
||||
ersetzt; `Kontakt` existiert seit CRM-P6-Merge; Diff-Spalten additiv mit Freigabe).
|
||||
|
||||
**Gebaut (Commits `4c0bae7d3`..`c48fb780b` + Migration/Doku):**
|
||||
- **S1 Schema (`4c0bae7d3`):** `AuditEvent.beforeDiff/afterDiff` (Json?, write-time sanitisiert) +
|
||||
`summaryText` (String?) in `core.prisma`; `Kontakt.language` (String?) in `crm.prisma`. Bewusst **nicht**
|
||||
im `eventHash`-Digest (Chain-Payload eingefroren — sonst bräche `verifyAuditChain` für Bestandszeilen);
|
||||
Chain-Bindung + Auto-Middleware-Befüllung = R-P1b-Nachzug (Vermerk in `R-P1b.md`, `Kontakt.language` in `R-P6.md`).
|
||||
- **S2 VMs (`838c6f494`):** `audit-list.vm` (persistierte Summary first, `buildAuditFieldDiffs` mit
|
||||
`[REDACTED]`-Maskierung, `toAuditListModel`), neu `notification-center.vm` (Deeplink-Validierung, M002-Bounce-Keys,
|
||||
Merge/Cap für SSE), `notification-settings.vm` (Registry + Default-Vererbung), `audit-export.vm`.
|
||||
- **S3 Audit-Screens (`3ed0b3d80`):** `AuditListPage` (A2 + echter `~/ui`-Drawer, Feld-für-Feld-Diff,
|
||||
Maskierung „Wert geändert") + `AuditExportPage`; Admin-Routen als dünne `<XPage vm actions/>`-Hosts.
|
||||
- **S4 Notification-Screens (`21c1adfc6`):** `NotificationCenterPage` (Tabs/Bounce/Deeplink) +
|
||||
`NotificationSettingsPage` (A6, `~/ui`-Switch); SSE in `useNotificationsStream`-Hook; Deeplink fährt als
|
||||
**validierter app-relativer Scalar** über den Realtime-Stream (`deeplink`/`lastError` an
|
||||
`NotificationStreamItem` + Realtime-Guard, fail-closed — `payloadMetadata` bleibt im Stream verboten).
|
||||
Altes `NotificationCenter.tsx` entfernt.
|
||||
- **S5 Topbar (`dc58e3540`):** `NotificationsDrawer` (echter `~/ui`-Drawer), Glocke öffnet Drawer,
|
||||
Live-Unseen-Count aus SSE (Tenant-App; Admin behält Link — Stream ist tenant-scoped, siehe Dev-Nachzug).
|
||||
- **S6 Tests (`c48fb780b`):** Smoke `tests/e2e/{audit,notifications}.spec.ts`; Hot-Swap-Kette
|
||||
`auditList`/`notificationCenter` (ui-subframe-Renderer + ui-mock-Twins + Adapter + Tests).
|
||||
Visual-Regression deferred wie R-P2a/AK-P4b (keine Harness; Re-Baseline-Pflicht beim David-Nachzug).
|
||||
- **S7 Migration:** `prisma/migrations/20260707010000_ak_p3_audit_diff_and_kontakt_language` —
|
||||
idempotent (`ADD COLUMN IF NOT EXISTS`), expand-only/nullable (Migrate-on-Boot-sicher), Inverse-SQL als Kommentar.
|
||||
|
||||
**Proof (lokal, Node 22.15):** Typecheck db/api/web/worker/realtime/view-models/ui-* 0 Fehler ·
|
||||
`verify:i18n` + `verify:cross-cutting-models` + `verify:sidebar-routes` Exit 0 · audit-events 12/12 ·
|
||||
notifications-db 30/30 · realtime 54/54 · VM-Suiten 33+21 · Screen-/Route-Render-Tests grün ·
|
||||
Adapter/Mock 64/64. Bekannt environmental: Action-Tests via `postFormRequest` (undici-Bug Node 22.15,
|
||||
vor dem Action-Code) + `verify:migrations-parity` braucht Docker → CI. Kein lokales `db push` möglich
|
||||
(Docker aus) — Client-Typen via `prisma generate`, Staging via Migrate-on-Boot.
|
||||
|
||||
**Gesamt-DoD-Stand: 7/7 = 100 %** · selbst machbar offen: nichts · getrackter Nachzug (nicht
|
||||
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.
|
||||
@@ -6,7 +6,9 @@
|
||||
| **Owner** | Akeshan |
|
||||
| **Phase** | P4 — Files & Tasks |
|
||||
| **Cycle/Fenster** | W1 — Fundament & Identität · fällig 2026-06-19 · Gate W1 |
|
||||
| **Status** | geplant |
|
||||
| **Status** | Done (2026-07-05) — Dev-DoD 100 %; design-nachzug offen (nicht Done-blockierend, AD-28) |
|
||||
|
||||
**🎨 design-nachzug: offen** (seit 2026-07-05) — Interim-UI aus `~/ui` steht; finale Subframe-Optik aus `D-P4` ausstehend.
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `AK-INFRA2` (ClamAV per ENV), `EXT-06` (Hetzner-S3 + Token + DEK-Master-Key)
|
||||
@@ -32,14 +34,14 @@ 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
|
||||
- [ ] **Chunked Upload (TUS)** + **RLS auf Storage-Pfaden** (Hetzner Object Storage, S3-kompatibel)
|
||||
- [ ] **Preview** PDF→PNG / Bild→WebP / **HEIC→JPG (Pflicht!)** mit Status-Maschine + Klartext-Fallback
|
||||
- [ ] **ClamAV-Scan** beim Upload
|
||||
- [ ] Permissions/Sharing + Tags + Archiv-Flag + Bulk-ZIP
|
||||
- [ ] **Auth-Proxy-Route für Medien-Auslieferung** (AD-23) — privater Bucket, `publicUrl` → Proxy, **kein public-read**
|
||||
- [ ] **`FileEntityLink`** (polymorph) an jede Entität + Rollen-Label; Customer-Portal-Upload vorbereitet
|
||||
- [ ] Files-Browser server-side-Filter (Entität/MIME-Gruppe/Tags/Verantwortlicher), Tabelle/Grid-Umschalter
|
||||
- [ ] *(→ v2)* Versionierung/Office-/Video-Previews/Resume-Upload/OCR ausgeschlossen
|
||||
- [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] **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)
|
||||
- [x] **Auth-Proxy-Route für Medien-Auslieferung** (AD-23) — privater Bucket, `publicUrl` → Proxy, **kein public-read** (Staging: 302 auf signierte URL)
|
||||
- [x] **`FileEntityLink`** (polymorph) an jede Entität + Rollen-Label; Customer-Portal-Upload vorbereitet
|
||||
- [x] Files-Browser server-side-Filter (**Entität/MIME-Gruppe/Tags/Verantwortlicher** — alle vier, 2026-07-05), Tabelle/Grid-Umschalter
|
||||
- [x] *(→ v2)* Versionierung/Office-/Video-Previews/Resume-Upload/OCR ausgeschlossen (korrekt out-of-scope)
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (eigene `prisma/schema/files.prisma`): `File` (display_name, mime_type, size, storage_key, checksum, preview_status, assigned_to, source; `is_demo_data`; Soft-Delete), `FileChunk`/`FileUploadProgress` (upload_id, chunk_index, received_chunks, expires_at 24h), **`FileEntityLink`** (file_id + entity_type + entity_id + link_role, polymorph — Cross-Cutting). `FileVersion` = **v2** (nicht bauen). `core.prisma` nur für Tenant/User-Relationen berühren (AD-21).
|
||||
@@ -58,7 +60,23 @@ Das **Files-Plattform-Primitive**: chunked Upload (TUS) mit **RLS auf Storage-Pf
|
||||
- `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)
|
||||
- [ ] Files-Browser/Detail an Davids UI angepasst
|
||||
|
||||
**Interim-UI (Vorschau, Stand 2026-07-05):** Die 3 Screens sind aus `~/ui` neu gebaut (AD-28,
|
||||
`.planning/INTERIM-UI-PLAYBOOK.md`) — VM als Prop, kein handgeschriebenes Tailwind für Spacing/Höhen,
|
||||
Davids Design-Standards befolgt:
|
||||
`apps/web/app/components/screens/files/{FilesBrowserPage,FileUploadPage,FileDetailPage}.tsx`.
|
||||
Die Routen (`files._index`/`files.upload`/`files.$id`) rendern nur noch `<XPage vm={} … />`; Loader/Action/
|
||||
Resource-Routes unverändert. Browser: `~/ui` Table + Grid-Umschalter (`?view=`) + MIME-/Archiv-Filter +
|
||||
Pagination + Status-Badges + Tags. Upload: Dropzone + Per-Datei-`Progress`-Queue + HEIC-`Alert`.
|
||||
Detail: `Breadcrumbs` + `Card`-Stammdaten + Preview + Scan-`Alert` (fail-closed) + `Tag_Label` + verknüpfte
|
||||
Entitäten + Add-Link-`Dialog` + Delete-`Dialog`; Server-`<form method=post>`+`intent` beibehalten.
|
||||
Proof (lokal grün): Web-Typecheck exit 0; Render-Tests `screens/files/*.test.tsx` 7/7; Hot-Swap-Drill
|
||||
`fileBrowser.hot-swap.test.ts` 3/3; `verify:i18n`-Parität de/en + hardcoded-Strings-Guard grün; Smoke-Marker
|
||||
`ui.files.browser` erhalten. Visual-Baseline = interim (Harness deferred, DoD 21).
|
||||
Refactor-Nachzug offen: finale Subframe-Optik aus `D-P4` (Doc-Tag `🎨 design-nachzug: offen`, Plane-Label
|
||||
`design-nachzug`).
|
||||
|
||||
- [ ] Files-Browser/Detail an Davids UI angepasst (finale `D-P4`-Optik über die Screen-Komponenten tauschen)
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
- [ ] Plane-Ticket `AK-P4a` aktualisiert
|
||||
|
||||
@@ -78,25 +96,25 @@ Windows 11 (Akeshan), Co-Dev Raffael auf macOS. Reihenfolge wie im Plan empfohle
|
||||
- **§2 Storage-Pfade** — `packages/storage/src/paths/` (`buildFileStorageKeys`,
|
||||
`buildFilePreviewKey`, `buildUploadChunkKey`, `assertFileKeyBelongsToTenant` als duenne
|
||||
Klammer um das vorhandene `authorizeStorageObjectAccess`). Proof: 5 neue Unit-Tests gruen
|
||||
(`pnpm -F @toolctrl/storage test` → 76 passed).
|
||||
- **§4 Queue-Plumbing** — neue Queue `toolctrl.file-preview` quer durch `names`/`payloads`/
|
||||
(`pnpm -F @hivegrid/storage test` → 76 passed).
|
||||
- **§4 Queue-Plumbing** — neue Queue `hivegrid.file-preview` quer durch `names`/`payloads`/
|
||||
`producers`/`groups`/`index` (`FilePreviewJob`, `buildFilePreviewJob`, retry-opts, group
|
||||
`general`). Proof: `pnpm -F @toolctrl/queue typecheck` + `test` (101 passed; dabei eine
|
||||
`general`). Proof: `pnpm -F @hivegrid/queue typecheck` + `test` (101 passed; dabei eine
|
||||
vorbestehende Luecke im metrics-snapshot-Test geschlossen: `buildPluginInvokeJob` fehlte).
|
||||
- **§4 Preview-Worker** — `apps/worker/src/jobs/file-preview.ts` (HEIC→JPG / Bild→WebP /
|
||||
PDF→PNG / Text→ready / sonst not_supported, Status-Maschine + Thumbnails), Handler-Registry
|
||||
`[queueNames.filePreview]` + `filePreviewService`-Dependency + `PreviewHandlerError` in
|
||||
`handlers.ts`, Bootstrap-Wiring (general group) in `index.ts`. Render-Libs per dynamischem
|
||||
Import (qdrant-Muster) → Build gruen vor Install; **Aktivierung:**
|
||||
`pnpm add sharp heic-convert pdf-to-png-converter -F @toolctrl/worker`. ClamAV (§5) ist
|
||||
Reuse (`enqueueFileScan` bereits vorhanden). Proof: `pnpm -F @toolctrl/worker typecheck` gruen.
|
||||
`pnpm add sharp heic-convert pdf-to-png-converter -F @hivegrid/worker`. ClamAV (§5) ist
|
||||
Reuse (`enqueueFileScan` bereits vorhanden). Proof: `pnpm -F @hivegrid/worker typecheck` gruen.
|
||||
- **§7 Permissions** — `files.read_own/read_all/write/delete/admin` in
|
||||
`packages/db/.../permissions-seed.server.ts` (mit expliziten Default-Rollen-Grants, da
|
||||
`files.*` keinen `app.`/`admin.`-Prefix traegt) + in `apps/web/.../DefaultPermissions.ts`.
|
||||
Proof: `pnpm -F @toolctrl/db typecheck` gruen.
|
||||
Proof: `pnpm -F @hivegrid/db typecheck` gruen.
|
||||
- **§9 View-Models** — `packages/view-models/src/files/{file-browser,file-detail,file-upload}.vm.ts`
|
||||
(reine Builder, nur i18n-Keys, URLs zeigen auf Proxy-Route, fail-closed bei scanStatus=infected).
|
||||
Proof: `pnpm -F @toolctrl/view-models typecheck` + `test` (13 passed).
|
||||
Proof: `pnpm -F @hivegrid/view-models typecheck` + `test` (13 passed).
|
||||
- **§8 Migration vorbereitet** — `local/AK-P4a-merge-migration.sql`: Trigram-Index +
|
||||
RLS-Policies (forward-only, Inverse-SQL als Kommentar, DO-guarded). AD-21: auf dem Branch nur
|
||||
`db push`; die echte Migration wird beim Merge via `prisma migrate diff` erzeugt und um diesen
|
||||
@@ -129,7 +147,7 @@ die Web-Route-/UI-/Wiring-Scheibe. **Single Source of Truth bleibt** `local/AK-P
|
||||
`tenantHasModule({tenantId,userId,moduleKey:"files"})` aus `~/utils/connector/tenantConnector.server`.
|
||||
- Upload selbst: `storeFile`/`putBufferAsFile`/`deleteFile` in
|
||||
`apps/web/app/utils/integrations/storageService.ts`. Magic-Bytes-Allow-List via `resolveAllowList`
|
||||
aus `@toolctrl/storage`. Keys via `@toolctrl/storage` `buildUploadChunkKey`/`buildFileStorageKeys`
|
||||
aus `@hivegrid/storage`. Keys via `@hivegrid/storage` `buildUploadChunkKey`/`buildFileStorageKeys`
|
||||
(schon gebaut, §2). Chunk 5 MB, max 3 parallel, max 500 MB (Konstanten in `file-upload.vm.ts`).
|
||||
- Nach `complete`: `enqueueFileScan({...})` (vorhanden, `fileScanQueue.server.ts`) **und** einen neuen
|
||||
Producer `enqueueFilePreview(...)` (spiegle `fileScanQueue.server.ts`, nutze `buildFilePreviewJob` +
|
||||
@@ -139,7 +157,7 @@ die Web-Route-/UI-/Wiring-Scheibe. **Single Source of Truth bleibt** `local/AK-P
|
||||
- Loader: `requireAuth` → `getTenantIdFromUrl` → `tenantHasModule("files")` → Sichtbarkeits-Check (§7)
|
||||
→ **302 auf kurzlebige signierte Download-URL** (TTL 300 s). Signer-Wiring: pruefe
|
||||
`apps/api/src/storage.ts` (`createStorageSignedDownloadUrl`) bzw. baue web-seitig mit
|
||||
`@aws-sdk/s3-request-presigner` + `createS3SignedUrlAdapter` aus `@toolctrl/storage`.
|
||||
`@aws-sdk/s3-request-presigner` + `createS3SignedUrlAdapter` aus `@hivegrid/storage`.
|
||||
- `scanStatus=infected` → Klartext-Fehler (fail-closed); verweigert → **404, nicht 403**.
|
||||
`STORAGE_PUBLIC_BASE_URL` bleibt leer.
|
||||
|
||||
@@ -153,7 +171,7 @@ ODER es existiert ein lesbarer `FileEntityLink`. Permissions sind schon registri
|
||||
(`files.read_own/read_all/write/delete/admin`, §7).
|
||||
|
||||
**§9 ist fertig — nur verdrahten:** `buildFileBrowserVM` / `buildFileDetailVM` / `buildFileUploadVM`
|
||||
aus `@toolctrl/view-models`. Der Loader baut die **Proxy-URLs** (auf die §6-Route) und reicht sie als
|
||||
aus `@hivegrid/view-models`. Der Loader baut die **Proxy-URLs** (auf die §6-Route) und reicht sie als
|
||||
`thumbnailUrl`/`previewUrl`/`downloadUrl` ins VM — VMs bleiben routing-agnostisch.
|
||||
|
||||
**§12 Querschnitt-Wiring:** Audit (`auditEvent`/`withAuditMiddleware`), Activity (`logActivity` —
|
||||
@@ -165,12 +183,12 @@ Search-Registry `packages/search/src/indexed-entities.ts` (Index `hivegrid-files
|
||||
**§13 Tests:** Smoke `tests/e2e/files.spec.ts` (Muster `walking-skeleton.spec.ts`), Hot-Swap-Adapter,
|
||||
Visual-Snapshot. VM-Unit-Tests existieren bereits (`packages/view-models/src/files/files.vm.test.ts`).
|
||||
|
||||
**Deps-Aktivierung (Preview):** `pnpm add sharp heic-convert pdf-to-png-converter -F @toolctrl/worker`
|
||||
**Deps-Aktivierung (Preview):** `pnpm add sharp heic-convert pdf-to-png-converter -F @hivegrid/worker`
|
||||
(aktuell dynamisch importiert → Build gruen vor Install). **Koordination Raffael:** Live-ClamAV (EICAR
|
||||
fail-closed) braucht `CLAMD_*` aus `AK-INFRA2`; RLS-Reihenfolge mit `R-P2b` (`SET LOCAL app.tenant_id`).
|
||||
|
||||
**Verifikation pro Scheibe:** `pnpm typecheck` (Web-App) + `pnpm test`; Storage/Queue/Worker/VM-Pakete
|
||||
sind isoliert testbar (`pnpm -F @toolctrl/<pkg> test`). Vor Merge: `prisma validate` +
|
||||
sind isoliert testbar (`pnpm -F @hivegrid/<pkg> test`). Vor Merge: `prisma validate` +
|
||||
`prisma migrate status` + den RLS-Anhang aus `local/AK-P4a-merge-migration.sql` an die generierte
|
||||
Migration anhaengen.
|
||||
|
||||
@@ -182,7 +200,7 @@ Vorher: `git merge origin/main` (Raffaels P2 Auth/RLS) in den Branch gezogen (Me
|
||||
`4f6177202`, 3 Konflikte geloest, typecheck gruen). Danach die offenen Scheiben gebaut.
|
||||
|
||||
**Fertig + verifiziert (typecheck/test gruen pro Paket):**
|
||||
- **§3 Chunked-Upload** — S3-Multipart in `@toolctrl/storage` ergaenzt (`createMultipartUpload`/
|
||||
- **§3 Chunked-Upload** — S3-Multipart in `@hivegrid/storage` ergaenzt (`createMultipartUpload`/
|
||||
`uploadPartCopy`/`completeMultipartUpload`/`abortMultipartUpload`, S3 + Local; Unit-Test
|
||||
`multipart.test.ts`). Domain-Service `apps/web/.../fileService.server.ts` (createUploadSession,
|
||||
storeUploadChunk, completeUpload via UploadPartCopy aus Temp-Chunks, Sichtbarkeit, link/unlink/
|
||||
@@ -190,7 +208,7 @@ Vorher: `git merge origin/main` (Raffaels P2 Auth/RLS) in den Branch gezogen (Me
|
||||
`filePreviewQueue.server.ts`. Resource-Routes `files.upload.init|.$uploadId.chunk.$index|.complete`.
|
||||
Checksum: client-optional (server-Verify = v2, dokumentiert). Worker-Deps `sharp`/`heic-convert`/
|
||||
`pdf-to-png-converter` installiert.
|
||||
- **§6 Auth-Proxy (AD-23)** — gemeinsamer SigV4-Signer `@toolctrl/storage` `createSigV4DownloadSigner`,
|
||||
- **§6 Auth-Proxy (AD-23)** — gemeinsamer SigV4-Signer `@hivegrid/storage` `createSigV4DownloadSigner`,
|
||||
web-seitig `mediaSigning.server.ts` (`createMediaDownloadUrl`, TTL 300 s), Route
|
||||
`media.$fileId.$variant.tsx`: 302 auf signierte URL, fail-closed bei scanStatus != clean/skipped,
|
||||
404 bei fremder/fehlender File. `STORAGE_PUBLIC_BASE_URL` bleibt leer. (Dev ohne ClamAV:
|
||||
@@ -198,7 +216,7 @@ Vorher: `git merge origin/main` (Raffaels P2 Auth/RLS) in den Branch gezogen (Me
|
||||
- **§7 Permissions/Sichtbarkeit** — Guard `fileAccess.server.ts` (loadFilesContext, requireFilesPermission;
|
||||
404 ueber Foundation, locked-State fuer GET-Loader, 404 fuer Write-Actions). read_own-Owner/Link-Check
|
||||
serverseitig.
|
||||
- **§10 Hot-Swap (DoD 20)** — `fileBrowser`-Adapter (`@toolctrl/ui-app`) + Renderer in `ui-subframe`
|
||||
- **§10 Hot-Swap (DoD 20)** — `fileBrowser`-Adapter (`@hivegrid/ui-app`) + Renderer in `ui-subframe`
|
||||
(`renderFileBrowser`) und `ui-mock` (`renderFileBrowserMock`) + Drill-Test gruen.
|
||||
- **§11 Routen** — `files._index` (Browser, server-side-Filter MIME/Archiv, Cursor-Pagination),
|
||||
`files.upload` (Drag&Drop + Multi-Datei-Queue + Per-Datei-Progress, chunked init/chunk/complete),
|
||||
@@ -245,7 +263,7 @@ Der erste `git push` scheiterte an zwei lefthook-Pre-Push-Gates (nicht an GitHub
|
||||
loesten `user-facing-response-literal` aus (Baseline 0).
|
||||
|
||||
**Konventionen fuer den naechsten Agenten (nicht erneut falsch bauen):**
|
||||
- Audit immer ueber **`createAuditEvent` aus `@toolctrl/db/audit-events.server`** schreiben (M001,
|
||||
- Audit immer ueber **`createAuditEvent` aus `@hivegrid/db/audit-events.server`** schreiben (M001,
|
||||
Hash-Kette), **ohne** Client-Argument — Default ist der db-Singleton. **Nicht** `foundation.auditEvent`
|
||||
mit `db` aufrufen. Gleiches Muster fuer `logActivity` (kein `{ client: db }` uebergeben).
|
||||
- Neue Workspace-Pakete als Dependency in der konsumierenden `package.json` eintragen (+ `pnpm install`).
|
||||
@@ -305,7 +323,7 @@ App-Level-`withTenantScope()` (§7) die Isolation. Der RLS-Block bleibt als **Ro
|
||||
RLS-gewrappt sind). → **eigenes Folge-Item** (siehe unten).
|
||||
|
||||
**Lokale Verifikation (gruen):** Full-Typecheck; Paket-Tests storage/queue/worker/view-models/ui-app/
|
||||
ui-mock/search/entitlements gruen; `@toolctrl/db` 422 passed / 1 failed = **nur** der bekannte
|
||||
ui-mock/search/entitlements gruen; `@hivegrid/db` 422 passed / 1 failed = **nur** der bekannte
|
||||
Windows-only-Env-Test `isPermissionsSeedDirectExecution` (fileURLToPath, keine Regression);
|
||||
`verify:i18n` gruen; Hot-Swap-Drill (`fileBrowser.hot-swap.test.ts`) gruen.
|
||||
|
||||
@@ -365,7 +383,7 @@ dieses Ticket.
|
||||
**Noch offen (Stand 2026-06-23 Abend):**
|
||||
- [ ] **RLS-Aktivierung auf `File*`** (Folge-Item, mit R-P2b) — siehe eigener Abschnitt unten.
|
||||
- [ ] **Finaler Live-EICAR-Beweis** — nachholen, sobald `files` in einem Plan/Entitlement aktiv ist.
|
||||
- [ ] **Coolify Pre/Post-Deploy-Hooks** (Migrate + Seed) reparieren — Infra, eigenes Ticket.
|
||||
- [x] **Coolify Pre/Post-Deploy-Hooks** (Migrate + Seed) reparieren — erledigt 2026-07-03, gelöst durch Migrate-on-Boot im Entrypoint statt Hook-Reparatur (siehe Notiz unten).
|
||||
- [ ] **Deferred DoD 11 (Mobile-Tab-Bar) + DoD 21 (Visual-Regression)** — bleiben deferred.
|
||||
- Ticket bleibt **„Ready for Review"** (nicht Done).
|
||||
|
||||
@@ -409,3 +427,143 @@ Runtime-Rolle `hivegrid_app`), ohne weitere Files-Code-Änderung — bewiesen du
|
||||
**Weiterhin offen (Teil B / extern, unverändert):** Policy-Migration aktivieren + DB-Rollenwechsel +
|
||||
Staging-Cutover (org-weit, Raffael/R-P2b) · finaler Live-EICAR-Beweis (entitlement-gated) · Coolify
|
||||
Pre/Post-Deploy-Hooks (Infra) · deferred DoD 11 + DoD 21. Ticket bleibt **„Ready for Review"**.
|
||||
|
||||
### 2026-07-03 — Coolify-Deploy-Migrate-Problem gelöst: Migrate-on-Boot im Entrypoint (Akeshan)
|
||||
|
||||
Der Infra-Nebenbefund vom 23.06. („Coolify fuhr weder Pre-Deploy-Migrate noch Post-Deploy-Seed aus")
|
||||
ist geschlossen — **gelöst durch Ersetzen statt Reparieren** des Hooks (Branch `akeshan/migrate-on-boot`).
|
||||
|
||||
**Root Cause (3 Ebenen):** (1) Coolifys `pre/post_deployment_command` feuerte für unsere
|
||||
Docker-Image-Apps (ADR-005, build-once/deploy-via-pull) nachweislich nie — bestätigt am 20.06.
|
||||
(Prod-Promote, `docs/ops/prod-rollout-hivegrid.md`), 23.06. (Staging) und 2× am 03.07.
|
||||
(Parity-Migration + MCP-Fix, beide manuell nachgezogen). (2) Konzeptioneller Zusatzfehler: der
|
||||
pre-deploy-Hook liefe im **alten** Container, in dem die neuen Migration-Files gar nicht existieren —
|
||||
selbst ein reparierter Hook wäre immer einen Deploy hinterher. (3) Das Deploy-Gate war blind:
|
||||
Health-Wait pollt `/healthz` (keine DB-Abfrage) → Deploy grün trotz veraltetem Schema.
|
||||
|
||||
**Fix:** Migrationen + Seed laufen jetzt env-gated im Web-Entrypoint (`start.sh`, `set -e`):
|
||||
`MIGRATE_ON_BOOT=true` → `pnpm exec prisma migrate deploy --config prisma.config.ts` vor dem
|
||||
Serverstart (immer die richtige Image-Version, Prisma-Advisory-Lock gegen Parallel-Starts);
|
||||
`SEED_ON_BOOT=true` → guarded Production-Seed. Fehlschlag = Container startet nicht = Health-Wait
|
||||
wird **rot statt still grün** — das ist der eigentliche Gate-Fix. `deploy.yml` leert die toten
|
||||
Hook-Slots explizit und upsertet die Boot-Flags per neuem `scripts/coolify-deploy.mjs set-envs`
|
||||
(Staging zusätzlich `SEED_DEMO_DATA`/`ALLOW_STAGING_DEMO_SEED`; Production ohne Demo-Flags).
|
||||
Web-`HEALTHCHECK` `start-period` 20s→120s (Migrate-Zeit). Rollback: Flags auf `false` + Redeploy.
|
||||
|
||||
**Verankert gegen Rückbau:** `verify-docker-baseline.mjs` erzwingt jetzt `set -e` + beide gated
|
||||
Blöcke in `start.sh`; `verify-gitea-deploy-workflow.mjs` erzwingt geleerte Hook-Slots + Boot-Flag-
|
||||
Upsert (Staging und Production, Demo-Flags in Prod verboten). Doku: `docs/deployment.md`
|
||||
(Slots-Absatz ersetzt), `infra/LESSONS.md` (neue Lesson im infra-Repo).
|
||||
|
||||
**Nachtrag 2026-07-04 (User-OK zum Vorschlag):** Der PR-CI-Smoke
|
||||
(`scripts/docker-web-runtime-smoke.sh`, Job `docker-smoke`) migriert/seedet nicht mehr per
|
||||
separatem One-off-Container, sondern bootet den Web-Container selbst mit
|
||||
`MIGRATE_ON_BOOT=true`/`SEED_ON_BOOT=true` gegen eine leere Postgres und asserted die
|
||||
`[boot]`-Banner in den Logs. Damit probt jeder PR exakt den Staging-Bootweg; Health-Fenster
|
||||
auf 600s erweitert (Boot enthält jetzt die volle Migrationskette), Fail-fast wenn der
|
||||
Container während des Boots stirbt.
|
||||
|
||||
### 2026-07-05 — Interim-UI aus `~/ui` gebaut (AD-28), lokal grün (Akeshan)
|
||||
|
||||
Die bislang offene „Davids Optik"-Scheibe als **Interim-UI** geschlossen (AD-28 /
|
||||
`.planning/INTERIM-UI-PLAYBOOK.md` + `INTERIM-UI-DESIGN-STANDARDS.md`). Die 3 Files-Screens sind aus den
|
||||
gesyncten `~/ui`-Subframe-Components neu komponiert — VM als Prop, kein handgeschriebenes Tailwind für
|
||||
Spacing/Höhen, Davids Layout-/Komponenten-/State-Standards befolgt. **Backend/Loader/Action/Resource-Routes +
|
||||
Hot-Swap-Adapter unverändert** (kein neues Backend, Ticket-Treue).
|
||||
|
||||
**Gebaut:**
|
||||
- `apps/web/app/components/screens/files/FilesBrowserPage.tsx` — `~/ui` `Table` + `ToggleGroup`-Umschalter
|
||||
(Table/Grid, `?view=`) + MIME-Filter (`Select`) + Archiv-`Checkbox` + `nextCursor`-Pagination +
|
||||
Status-`BadgeFeedback` (Preview/Scan) + `Tag_Label`. Grid-View = `Card`-Raster mit Thumbnails. Empty-State inline.
|
||||
- `apps/web/app/components/screens/files/FileUploadPage.tsx` — Dropzone (custom Drop-Target, i18n-Copy aus VM;
|
||||
das `~/ui`-`FileUpload` bringt hartkodierte EN-Copy mit → bewusst nicht genutzt) + Per-Datei-`Progress`-Queue +
|
||||
HEIC-`Alert`. Client-Chunked-Pipeline bleibt in der Route und wird als `items`/`onFiles` reingereicht.
|
||||
- `apps/web/app/components/screens/files/FileDetailPage.tsx` — `Breadcrumbs` + `Card`-Stammdaten + Preview +
|
||||
Scan-`Alert` (fail-closed) + `Tag_Label` + verknüpfte Entitäten + **Add-Link-`Dialog`** (echter Dialog, S 560) +
|
||||
**Delete-`Dialog`** (XS 420). Aktionen bleiben Server-`<form method=post>`+`intent` (`~/ui` `Button`
|
||||
`type=submit name=intent`). Alle `data-ui-id`/`data-row-id`/`data-link-id`/`data-status` erhalten.
|
||||
- Routen `files._index`/`files.upload`/`files.$id` rendern nur noch `<XPage vm={} … />`; Browser-Loader liest
|
||||
zusätzlich `?view=`; `onApply` navigiert server-side (useNavigate). i18n `files.*` de/en ergänzt (Parität grün).
|
||||
- Render-Tests je Screen: `apps/web/app/components/screens/files/*.test.tsx`.
|
||||
|
||||
**Verifikation (lokal grün):** Web-Typecheck exit 0 · Render-Tests 7/7 · Hot-Swap-Drill
|
||||
`fileBrowser.hot-swap.test.ts` 3/3 (DoD 20, Adapter unberührt) · `verify:i18n` (i18n-Parität de/en +
|
||||
hardcoded-Strings-Guard) grün · eslint-staged (0-Warnings) grün · Smoke-Marker `ui.files.browser` erhalten (D19).
|
||||
**Deferred wie gehabt:** Visual-Regression/M016 (keine Snapshot-Harness, DoD 21) → Interim-Baseline; Mobile-Tab-Bar
|
||||
(DoD 11, PWA-only AD-17). **Nicht gebaut (kein Backend, getrackter Follow-up):** Volltext-/Entity-/Tag-/Assignee-
|
||||
Filter + Bulk-ZIP-UI (brauchen Loader-/Service-Erweiterung).
|
||||
|
||||
**%-Done-Stand:** Der selbst-machbare Optik-Rest ist geschlossen; Interim-DoD B6–10 / D18–20 grün. Damit ~85 % →
|
||||
**~92 % done**. Offen (extern/deferred, nach AD-28 **nicht** Done-blockierend): RLS-Teil-B (P5-Cutover, Raffael) ·
|
||||
finaler Live-EICAR (entitlement) · DoD 11 + DoD 21 (deferred) · finale `D-P4`-Optik (`design-nachzug`) ·
|
||||
Bulk-ZIP-/erweiterte-Filter-Follow-up. **Selbst-machbar offen: 0.** Push/PR + Plane-Label + Done erst nach
|
||||
User-Freigabe.
|
||||
|
||||
### 2026-07-05 (Teil 2) — Staging-End-to-End-Beweis erbracht (Akeshan)
|
||||
|
||||
Nach dem systemischen Routing-Fix (v1-Adapter erkennt v2-flat `_index`, Branch `akeshan/fix-files-nav-featurekey`)
|
||||
sind die Tenant-Modul-Routen an ihrer kanonischen URL erreichbar. Damit den bis dahin nur unit-/komponenten-
|
||||
getesteten Kern **live auf Staging** (`demo-pro-crm`, `files`-Entitlement aktiv) durchgestochen — via
|
||||
authentifizierter In-Page-`fetch` gegen die echten Deploy-Endpoints:
|
||||
|
||||
- **Chunked Upload:** JPG init→chunk→complete = 200, File-Row erzeugt.
|
||||
- **Preview-State-Machine:** JPG → `previewStatus=ready` (WebP), Detail-Preview rendert über den Auth-Proxy.
|
||||
- **Auth-Proxy (AD-23):** `original` + `preview` → 302 auf kurzlebige signierte S3-URL (kein public-read).
|
||||
- **ClamAV fail-closed:** EICAR hochgeladen → clamd erkennt → **Write-back `scanStatus=infected`** (DB-belegt) →
|
||||
Media-Proxy **404** für beide Varianten → UI-Banner „vom Virenscan blockiert". Der bislang nur unit-getestete
|
||||
Write-back ist damit **live bewiesen**.
|
||||
- **HEIC→JPG (Pflicht) + PDF→PNG:** mit echten Dateien (iPhone-HEIC 1,72 MB, PDF) direkt auf dem Staging-Worker
|
||||
über exakt die Preview-Job-Libs (`heic-convert` JPEG q0.85 → JPG 1536×2048; `pdf-to-png-converter` → PNG
|
||||
1190×1684; `sharp`-Resize 2048/480). (Voller HTTP-Upload der 1,72-MB-HEIC ging nicht über den Browser —
|
||||
Tooling-Limit `file_upload`, kein Produktfehler; der Konvertierungs-Zweig ist damit dennoch auf Staging belegt.)
|
||||
- **Nav-Regression:** contacts/tasks/notifications/search/email-marketing/settings/dashboard alle 200 OK.
|
||||
- Beweis-GIF + Screenshots; alle Test-Dateien danach hart gelöscht (DB `count=0`).
|
||||
|
||||
### 2026-07-05 (Teil 3) — Bulk-ZIP + erweiterte Browser-Filter gebaut (Akeshan)
|
||||
|
||||
Die beiden bis dahin als Follow-up geführten DoD-Punkte auf User-Wunsch direkt umgesetzt (nicht mehr CR):
|
||||
|
||||
**Erweiterte Filter (Entität / Tags / Verantwortlicher):** `listFilesForBrowser` um den `entityType`-Filter
|
||||
(`links.some`) ergänzt; neuer `listFileFilterOptions()` liefert Optionslisten (distinct Entity-Types aus
|
||||
`FileEntityLink`, distinct Tags über die jüngsten Tenant-Files, aktive Members via `getTenantUsers`). Loader
|
||||
liest `entity`/`tag`/`assignee`-Params + reicht sie in Service + VM; VM (`FileBrowserData`) trägt jetzt
|
||||
`filterOptions` (rückwärtskompatibel, Default leer). Screen rendert drei zusätzliche `~/ui`-`Select` (nur wenn
|
||||
Optionen vorhanden), server-side-navigierend wie MIME/Archiv. i18n `files.browser.filter.{entity,tag,assignee}`
|
||||
+ `files.entityType.*` (de=Quelle, Parität grün).
|
||||
|
||||
**Bulk-ZIP-Download:** Service `collectFilesForZip()` (tenant-scoped, **fail-closed**: nur sichtbare +
|
||||
`scanStatus∈{clean,skipped}`-Files; infiziert/unsichtbar/über-Cap werden still verworfen; Bytes via signierte
|
||||
URLs, Caps 50 Files / 200 MB, De-Dupe der Entry-Namen). Neue Resource-Route
|
||||
`app.$tenant/files.bulk-zip.tsx` (POST `fileIds[]` → `fflate.zipSync` → `application/zip` Attachment). Screen:
|
||||
Checkbox-Spalte + Select-All in der Table-View + Bulk-Leiste (Native-`<form>`-POST auf die absolute
|
||||
Bulk-URL). Neue Dep `fflate` in `apps/web`.
|
||||
|
||||
**Reachability-Bugfix (Interim-UI):** Der Upload-CTA nutzte einen relativen `href="upload"`, der von
|
||||
`/<tenant>/files` auf `/<tenant>/upload` auflöste → **404**. Ebenso die Detail-Breadcrumb (`filesHref=".."`
|
||||
→ `/<tenant>/` Dashboard). Beide auf absolute, im Loader gebaute Pfade (`/<tenant>/files/upload` bzw.
|
||||
`/<tenant>/files`) umgestellt (konsistent mit `bulkZipAction`). Web-Typecheck grün. (Auf Staging beim
|
||||
Deploy der Teil-3-Änderungen wirksam.)
|
||||
|
||||
**Nachtrag — Tag-Editor (fehlte, blockierte den Tag-Filter):** Tags wurden im Detail nur *angezeigt*, es gab
|
||||
keine UI zum Setzen → der neue Tag-Filter blieb ohne Datenquelle. Jetzt: neue `updateMeta`-Intent in der
|
||||
Detail-Route (Tags kommagetrennt, trim/dedupe/cap 30, `files.write`-gated, auditiert via `file.updated`) +
|
||||
Tag-Editor auf der Detail-Seite (`~/ui`-`TextInput` mit vorbefülltem Wert + Speichern, nur bei `canWrite`).
|
||||
`updateFileMeta` war im Service vorhanden, nur nicht verdrahtet. Detail-Render-Tests 4/4 (2 neue), Typecheck/
|
||||
i18n/Lint grün.
|
||||
|
||||
**Verifikation (lokal grün):** Web-Typecheck exit 0 · Screen-Render-Tests **10/10** (inkl. neue Filter- +
|
||||
Bulk-Selection-Tests) · Hot-Swap-Drill `fileBrowser.hot-swap.test.ts` **41/41** (DoD 20, Adapter unberührt) ·
|
||||
`verify:i18n` (Parität + hardcoded-Guard) **exit 0** · `eslint-staged` **exit 0** · view-models **181/181**.
|
||||
|
||||
**Damit sind die zwei letzten funktionalen DoD-Lücken geschlossen.** Klärung zu den bislang als „blockierend"
|
||||
geführten Punkten (aus `R-P2b` gelesen): **RLS blockiert AK-P4a nicht** — R-P2b hat die RLS-Maschine bewiesen
|
||||
(Gate 6/6), das **Scharfschalten ist explizit P5+-Scope** („nicht R-P2b-Scope, läuft mit P5+"); AK-P4a ist
|
||||
RLS-**ready** (Teil A, Gate `rls-file-isolation` 7/7). Ebenso sind **DoD 11 (Mobile-Tab-Bar)** und **DoD 21
|
||||
(Visual-Regression)** nicht „mal eben" machbar — beide bräuchten neue Plattform-Infrastruktur (app-weites
|
||||
Mobile-Nav-Gerüst bzw. M016-Snapshot-Harness), die es im Repo nicht gibt → bleiben bewusst deferred (AD-28,
|
||||
nicht Done-blockierend).
|
||||
|
||||
**%-Done-Stand:** ~92 % → **~98 % done**. **Selbst-machbar offen: 0.** Rest-Offen (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.
|
||||
@@ -6,7 +6,9 @@
|
||||
| **Owner** | Akeshan |
|
||||
| **Phase** | P4 — Files & Tasks |
|
||||
| **Cycle/Fenster** | W1 — Fundament & Identität · fällig 2026-06-19 · **Gate W1 (EntityLink)** |
|
||||
| **Status** | geplant |
|
||||
| **Status** | Interim-UI gebaut (2026-07-06) · Dev-DoD 100 %; design-nachzug offen (AD-28, nicht Done-blockierend) — Done-Freigabe ausstehend |
|
||||
|
||||
**🎨 design-nachzug: offen** (seit 2026-07-06) — Interim-UI aus `~/ui` steht; finale Subframe-Optik aus `D-P4` ausstehend.
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `AK-P4a` (Files + FileEntityLink-Muster)
|
||||
@@ -15,7 +17,7 @@
|
||||
- **Konflikt-Risiko:** keines auf Schema-Ebene; Task-Entity-Links zu CRM-Entitäten werden erst in **P6 nachverdrahtet** (Task-Kern hier, Links dort).
|
||||
|
||||
## Was wir bauen
|
||||
Das **leichtgewichtige, querliegende Tasks-Modul**: Task-CRUD mit Status/Priorität/Fälligkeit, Entitäts-Verknüpfung (Contact/Company/Lead/Deal/Project), Person- **oder** Gruppen-Zuweisung (genau eines, Default = Ersteller), Watcher, **Reminder via `notify()`** (24h vor / bei / 24h nach Deadline, Eskalation Email) und **Auto-Archivierung** erledigter Tasks nach 30 Tagen per Cron. Tasks entstehen manuell, aus Chat, aus Form-Submission und aus Automation-Actions. Dazu die **polymorphe `EntityLink`-Tabelle** (`entity_type + entity_id`), gegen die jedes Modul andockt. Die **Task-Liste ist als wiederverwendbare Komponente** zu bauen (P12/P14/P16 betten sie ein; erscheint als Tasks-Tab in jeder Entity-Detail-View).
|
||||
Das **leichtgewichtige, querliegende Tasks-Modul**: Task-CRUD mit Status/Priorität/Fälligkeit, Entitäts-Verknüpfung (Contact/Company/Lead/Projekt), Person- **oder** Gruppen-Zuweisung (genau eines, Default = Ersteller), Watcher, **Reminder via `notify()`** (24h vor / bei / 24h nach Deadline, Eskalation Email) und **Auto-Archivierung** erledigter Tasks nach 30 Tagen per Cron. Tasks entstehen manuell, aus Chat, aus Form-Submission und aus Automation-Actions. Dazu die **polymorphe `EntityLink`-Tabelle** (`entity_type + entity_id`), gegen die jedes Modul andockt. Die **Task-Liste ist als wiederverwendbare Komponente** zu bauen (P12/P14/P16 betten sie ein; erscheint als Tasks-Tab in jeder Entity-Detail-View).
|
||||
|
||||
## Benötigte Screens (Backend bedient — Design liefert `D-P4` aus `D-D0a`/`D-D0b`)
|
||||
| Screen [Route] | Kern-Inhalt | Liefert (Design) |
|
||||
@@ -50,9 +52,14 @@ Das **leichtgewichtige, querliegende Tasks-Modul**: Task-CRUD mit Status/Priorit
|
||||
- `_bmad-output/specs/M26-tasks.md`
|
||||
|
||||
## Dev-Nachzug (nach Davids `D-P4`-Delta)
|
||||
- [ ] Task-Liste/-Detail an Davids UI angepasst (wiederverwendbare Komponente)
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
- [ ] Plane-Ticket `AK-P4b` aktualisiert
|
||||
- [x] **Interim-UI aus `~/ui` gebaut (AD-28, 2026-07-06)** — die drei Screens (Liste/Detail/Neu) sind aus
|
||||
`~/ui`-Components komponiert (`apps/web/app/components/screens/tasks/`), VM als Prop, kein
|
||||
handgeschriebenes Tailwind (Ausnahme: native `<input type="date">` via `DateField`, da `~/ui` keine
|
||||
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] Plane-Ticket `AK-P4b` aktualisiert (Kommentar + Label `design-nachzug` gesetzt, Status auf Done).
|
||||
|
||||
---
|
||||
|
||||
@@ -236,3 +243,46 @@ DoD 21 Visual-Regression (keine Snapshot-Harness) · Davids `D-P4`-Optik · Push
|
||||
gegen echte Postgres verifiziert. Selbst-machbarer Rest auf dem Branch: **0** (alles Weitere ist
|
||||
extern/infra blockiert oder Reviewer-Freigabe). Gesamt **~95 %** — Ticket bleibt in **„Ready for
|
||||
Review"** bis Staging-Verifikation + Reviewer-Freigabe der deferrten Punkte.
|
||||
|
||||
---
|
||||
|
||||
### 2026-07-06 — Interim-UI aus `~/ui` gebaut (AD-28), Baseline-Tailwind abgelöst (Akeshan, Branch `akeshan/ak-p4b-interim-ui`)
|
||||
|
||||
Der Code-Kern (8/8 DoD) lag seit Juni auf `main` (Commit `4e3d12607` + Merge-Migration
|
||||
`20260624120000_p4b_tasks_entitylinks`); offen war nur die UI-Optik. Plane stand auf „Blocked / On Hold"
|
||||
(blocked-by `D-P4`) — das ist der reine Design-Wait, den AD-28 auflöst. Wie bei AK-P4a (Commit `33f0d01e5`,
|
||||
05.07.) die drei Tasks-Screens als **Interim-UI aus `~/ui`** neu gebaut, hinter der stabilen VM/Loader-Grenze.
|
||||
Backend/Loader/Action/VMs/Worker-Crons/Wiring **unverändert**.
|
||||
|
||||
**Gebaut:**
|
||||
- `apps/web/app/components/screens/tasks/`: `TasksListPage.tsx`, `TaskDetailPage.tsx`, `TaskNewPage.tsx`
|
||||
(+ je `.test.tsx`) und `DateField.tsx` (native Date-Input-Helfer). Komponiert aus `~/ui`-Components
|
||||
(`Table`, `Select`, `ToggleGroup`, `Checkbox`, `BadgeFeedback`, `Tag_Label`, `Breadcrumbs`, `Card`,
|
||||
`Dialog`, `Button`, `IconButton`, `TextInput`, `TextArea`, `EmptyState`). VM/`data` als Prop,
|
||||
kein `useLoaderData` im Screen, kein handgeschriebenes Tailwind für Spacing/Höhen (Ausnahme `DateField`,
|
||||
dokumentiert: `~/ui` hat keine form-fähige Date-Variante; mit Design-Tokens gestyled, Höhe 36/Radius 4).
|
||||
- Routen `tasks.{_index,$id,new}.tsx` rendern jetzt nur noch `<XPage vm={} actions={} />`. List-Route:
|
||||
`onApply` → `useNavigate({search})` (server-side Preset/Filter), plus `nextHref` im Loader (Cursor +
|
||||
aktive Filter erhalten). Neu-Route: Creator-Default-Assignee über Sentinel `__creator__` (das `~/ui`
|
||||
`Select` verbietet leere Option-Values), im Action zurück auf „kein expliziter Assignee" gemappt.
|
||||
- Detail-Löschen als echter `~/ui`-`Dialog` (Größe XS 420), nicht als Card-Fake (David-Standard §6).
|
||||
- i18n: neue `tasks.list.filter.*`, `tasks.list.pagination.next`, `tasks.detail.section.overview`,
|
||||
`tasks.detail.field.created`, `tasks.detail.delete.*`, `tasks.detail.dialog.cancel` in de **und** en
|
||||
(chirurgisch gespliced, kein JSON-Round-Trip; Parität grün).
|
||||
|
||||
**Verifikation (lokal grün):** `@hivegrid/web` typecheck exit 0 · Screen-Render-Tests **12/12**
|
||||
(`screens/tasks/*.test.tsx`) · Hot-Swap-Drill `taskList.hot-swap.test.ts` **3/3** · `verify:i18n` exit 0 ·
|
||||
`verify:sidebar-routes` 27/27 · `verify:cross-cutting-models` 178/178 · eslint-staged 0 Warnings.
|
||||
Marker `ui.tasks.list`/`.detail`/`.new` + `data-row-id`/`data-watcher-id`/`data-overdue` erhalten (E2E
|
||||
`tests/e2e/tasks.spec.ts` bleibt gültig).
|
||||
|
||||
**Offen / getrackter Nachzug:**
|
||||
- **Finale `D-P4`-Subframe-Optik** (David) — `design-nachzug: offen` (Doc-Tag + Plane-Label), Swap hinter
|
||||
der VM/Loader-Grenze, **nicht Done-blockierend** (AD-28).
|
||||
- Visual-Regression (DoD 21): Interim-Baseline (Harness deferred, Re-Baseline beim David-Swap).
|
||||
- Unverändert extern/deferred: Live-Staging Reminder/Archiv (Redis+notify) · RLS-Teil-B (P5-Cutover) ·
|
||||
Mobile-Tab-Bar (PWA-only AD-17).
|
||||
|
||||
**%-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.
|
||||
@@ -0,0 +1,86 @@
|
||||
# BILL-00 · Billing-Recut: Legacy-Provider-Annahmen durch Lago/Mollie ersetzen
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Dev/Docs |
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | Billing-Recut nach AD-27 |
|
||||
| **Cycle/Fenster** | zuerst im Billing-Track |
|
||||
| **Status** | Umgesetzt / bereit fuer Review |
|
||||
|
||||
## Abhaengigkeiten & Parallelitaet
|
||||
|
||||
- **Blocked by:** AD-27 entschieden.
|
||||
- **Blocks:** alle weiteren `BILL-*`-Tickets.
|
||||
- **Parallelitaet:** keine Produktcode-Implementierung; Doku-/Planungs-Recut.
|
||||
|
||||
## Was wir bauen
|
||||
|
||||
Die bestehenden Legacy-Provider-basierten Billing-Docs wurden dependency-aware auf die neue Zielarchitektur gezogen:
|
||||
Lago fuer Billing/Invoicing, Mollie nur fuer Payments, HiveGrid fuer Entitlements. Vorhandene Arbeit aus `AK-P20`
|
||||
wird nicht verworfen, sondern als wiederverwendbare Billing-/Feature-Gate-/Read-only-Grundlage markiert.
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [x] `AK-P20` beschreibt nicht mehr Legacy-Provider als Zielsystem, sondern Lago/Mollie-Recut.
|
||||
- [x] `D-P20`, `VA-P24a`, `VD-P24`, `AK-P19`, `AK-P21` sind an AD-27 angepasst oder mit klarem Recut-Hinweis versehen.
|
||||
- [x] `EXT-07`/`EXT-16` sind nicht mehr Legacy-Provider-Blocker; Mollie-Test-/Live-Setup ist als neue Setup-Arbeit beschrieben.
|
||||
- [x] `H-PAYLINK` ist als alter Legacy-Provider-Vertriebsweg ersetzt durch Mollie-/manuellen Zahlungsweg; `H-FOUND` verweist nicht mehr auf Mollie Payment Link.
|
||||
- [x] Offene Legacy-Provider-Codepfade sind inventarisiert: behalten, entfernen, migrieren oder deaktivieren.
|
||||
- [x] DoD-Stand der betroffenen Tickets bleibt nachvollziehbar; nichts wurde still auf Done gesetzt.
|
||||
|
||||
**Fortschritt:** `BILL-00`: 6/6 DoD = 100 % done. Ticket kann nach Review/Plane-Kommentar weitergeschoben werden.
|
||||
|
||||
## Code-Inventar fuer `BILL-02` bis `BILL-05`
|
||||
|
||||
**Migrieren auf Lago/Mollie/HiveGrid-Billing:**
|
||||
- Core-Subscription-Schema: Legacy-Provider-zentrierte Felder in `prisma/schema/subscriptions.prisma` (`legacyProviderId`,
|
||||
`legacyProviderCustomerId`, `legacyProviderSubscriptionId`, `legacyProviderSubscriptionItemId`, `Legacy-ProviderWebhookLog`).
|
||||
- DB-Service-Schicht: Legacy-Provider-spezifische Helfer und Typen in `packages/db/src/subscriptions.server.ts`.
|
||||
- Web-Billing-Adapter: `apps/web/app/utils/legacyProvider.server.ts`, `apps/web/app/routes/webhooks.legacyProvider.tsx`,
|
||||
`apps/api/src/billing/legacyProvider-webhook-route.ts` und die zugehoerigen Tests als Migrationsvorlage.
|
||||
- Dunning/Frozen-Vorarbeit: `billingDunningService` und `billingStatusService` behalten fachlich, aber Provider-
|
||||
Kopplung auf generische Billing-/Payment-Events umbauen.
|
||||
- Admin-/Settings-Routen: Subscription-/Invoice-/PaymentMethod-Komponenten und Admin-Subscription-Routen, die heute
|
||||
Legacy-Provider-Typen oder Legacy-Provider-IDs anzeigen.
|
||||
- Mail-Templates: Invoice/Subscription-Erfolgs-/Fehlertexte von Legacy-Provider-Bezug auf generische Billing-/Payment-Texte
|
||||
umstellen.
|
||||
|
||||
**Deaktivieren oder spaeter separat entscheiden:**
|
||||
- Portal/Sites-Legacy-Provider-Connect-Code in der Plugin-/Portal-Altlast. Das ist nicht HiveGrid-v1-Core-Billing und darf
|
||||
nicht in den neuen Billing-Pfad gezogen werden.
|
||||
- Legacy-Provider-Metering-/Usage-Dokumente und Ops-Runbooks. v1 hat kein Usage-Billing.
|
||||
|
||||
**Behalten als harmlose Beispiele/Test-Fixtures, bis ein eigener Cleanup folgt:**
|
||||
- Plugin-Runtime-Testdaten mit `legacyProvider_*` als generischem Secret-Key-Muster.
|
||||
- Alte Migrationshistorie, solange sie fuer bestehende DB-Reproduzierbarkeit noetig ist.
|
||||
|
||||
## Betroffene Planungsdocs
|
||||
|
||||
- `AK-P20`: alter Legacy-Provider-Abschluss ersetzt durch `BILL-02` bis `BILL-05`; AK-P20 bleibt Vorarbeit fuer Trial, Frozen,
|
||||
Onboarding, Demo-Daten, Checkliste, Theme und Entitlement-Gates.
|
||||
- `D-P20`: v1-Screens zeigen Plan/Seats, Lago-Invoices, Mollie-Payment-Status, kein Legacy-Provider-Portal.
|
||||
- `VA-P24a`/`VD-P24`: v2-Self-Service baut auf Lago/Mollie, nicht auf Legacy-Provider-Reuse.
|
||||
- `AK-P19`: Admin-Abo-Zusammenstellung = Entitlements + Billing-State; Legacy-Provider-Positionen ersetzt durch `BILL-06`.
|
||||
- `AK-P21`: Tenant-Löschung nutzt generischen Billing-Cancel-Vertrag, nicht Legacy-Provider-Cancel.
|
||||
- `EXT-07`/`EXT-16`: Mollie-Test-/Live-Setup + Lago-Staging/Prod statt Legacy-Provider.
|
||||
- `H-PAYLINK`/`H-FOUND`: Founding-Deal-Zahlungsweg ohne Legacy-Provider.
|
||||
|
||||
## Technische Bausteine
|
||||
|
||||
- Keine Produktcode-Aenderung in `BILL-00`.
|
||||
- Ergebnis ist ein sauberer Planungsstand fuer `BILL-01` bis `BILL-08`.
|
||||
|
||||
## Quellen
|
||||
|
||||
- `docs/ARCHITECTURE-DECISIONS.md` AD-15, AD-27
|
||||
- `.planning/ticket-docs/BILL-README.md`
|
||||
- `.planning/ticket-docs/AK-P20.md`
|
||||
- `.planning/ticket-docs/D-P20.md`
|
||||
- `.planning/ticket-docs/VA-P24a.md`, `.planning/ticket-docs/VD-P24.md`
|
||||
- `.planning/ticket-docs/EXT-07.md`, `.planning/ticket-docs/EXT-16.md`, `.planning/ticket-docs/H-PAYLINK.md`
|
||||
|
||||
## Umsetzungsnotiz
|
||||
|
||||
2026-07-04: Doku-Recut umgesetzt. `git diff --check` ist der passende Proof fuer dieses Docs-only-Ticket; Produktcode
|
||||
wurde bewusst nicht geaendert. Plane-Status/Kommentar stehen noch aus.
|
||||
@@ -0,0 +1,70 @@
|
||||
# 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 |
|
||||
|
||||
## Abhaengigkeiten & Parallelitaet
|
||||
|
||||
- **Blocked by:** `BILL-00` fuer endgueltige Doku-Namen; Pilot kann parallel validiert werden.
|
||||
- **Blocks:** `BILL-03`, `BILL-07`.
|
||||
|
||||
## Was wir bauen
|
||||
|
||||
Eine saubere Lago-Staging-Instanz als Coolify-Service im Estate. Sie ist fuer mehrere HiveGrid-Staging-Flows nutzbar,
|
||||
aber nicht mit Production gemischt.
|
||||
|
||||
## Aktueller Stand
|
||||
|
||||
- Coolify-Projekt: `node1-estate`
|
||||
- Resource: `lago-staging`
|
||||
- Resource UUID: `kh7l869ianltiioqgmm45kur`
|
||||
- Server: `node1`
|
||||
- Oeffentlicher Operator-Zugriff: `https://staging-lago.hivegrid.de` via Lago-Login
|
||||
- Lokaler SSH-Tunnel aktuell moeglich:
|
||||
- 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`.
|
||||
|
||||
## 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] 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.
|
||||
- [x] SMTP/Mail-Verhalten fuer Staging entschieden: standardmaessig deaktiviert, Mailjet-Testconfig nur explizit fuer `BILL-07`.
|
||||
- [x] Dateispeicher fuer Invoice-PDFs entschieden: lokales Coolify-Volume fuer Staging-Pilot, Production spaeter separat.
|
||||
- [x] Runbook fuer Start/Stop/Upgrade/Restore in `docs/ops/lago-staging.md` dokumentiert.
|
||||
|
||||
**Fortschritt:** `BILL-01`: 8/8 DoD = 100 % done.
|
||||
|
||||
## Technische Bausteine
|
||||
|
||||
- Coolify Docker-Compose-Resource mit `getlago/api:v1.27.1`, `getlago/front:v1.27.1`, Postgres 15, Redis 7.
|
||||
- Keine Public-Domain ohne Auth.
|
||||
- Keine Production-Daten.
|
||||
- Runbook: `docs/ops/lago-staging.md`.
|
||||
|
||||
## Quellen
|
||||
|
||||
- `docs/ARCHITECTURE-DECISIONS.md` AD-27
|
||||
- Estate-Infra `../infra/runbooks/migrate-node1-to-coolify.md`
|
||||
- Lago Self-hosting Docs
|
||||
|
||||
## Umsetzungsnotiz
|
||||
|
||||
2026-07-04: Staging-Betrieb dokumentiert. Backup- und Restore-Pfad fuer Lago-Postgres, SMTP-Entscheidung,
|
||||
Invoice-PDF-Storage-Entscheidung, Upgrade/Rollback und Testdaten-Konvention stehen in `docs/ops/lago-staging.md`.
|
||||
|
||||
2026-07-05: Zugriffsmodell aktualisiert. Die Operator-UI ist unter `https://staging-lago.hivegrid.de` erreichbar
|
||||
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.
|
||||
|
||||
Proof:
|
||||
- `docs/ops/lago-staging.md`
|
||||
- `git diff --check`
|
||||
@@ -0,0 +1,78 @@
|
||||
# BILL-02 · HiveGrid Billing-Domain fuer Plans und Seats
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Dev (Code) |
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | Billing-Recut nach AD-27 |
|
||||
| **Cycle/Fenster** | nach `BILL-00` |
|
||||
| **Status** | Umgesetzt / bereit fuer Review |
|
||||
|
||||
## Abhaengigkeiten & Parallelitaet
|
||||
|
||||
- **Blocked by:** `BILL-00`
|
||||
- **Blocks:** `BILL-03`, `BILL-05`, `BILL-06`
|
||||
- **Parallelitaet:** kann parallel zu `BILL-01` laufen, solange Lago-API noch gemockt wird.
|
||||
|
||||
## Was wir bauen
|
||||
|
||||
Die lokale HiveGrid-Billing-Domain fuer Plans, Seats, Subscription-State und Entitlements. Ziel ist ein stabiler
|
||||
lokaler Zustand fuer Feature-Gates und UI, ohne dass jede Request-Entscheidung live gegen Lago geht.
|
||||
|
||||
## Scope
|
||||
|
||||
- Plans
|
||||
- Seats
|
||||
- Subscription-Status
|
||||
- Invoice-/Payment-Referenzen
|
||||
- Feature-Entitlements
|
||||
- Trial/Frozen/Read-only-State
|
||||
|
||||
Nicht im Scope:
|
||||
|
||||
- Usage-Billing
|
||||
- Credits
|
||||
- Add-on-Metering
|
||||
- oeffentliche Preislogik
|
||||
- Steuer-/Rechnungssteller-Finalisierung
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [x] Billing-Schema ist auf AD-27 ausgerichtet: Lago-/Mollie-Referenzen statt Legacy-Provider-IDs als Default.
|
||||
- [x] Bestehende `SubscriptionFeature`-/`tenantHasModule()`-Logik bleibt nutzbar.
|
||||
- [x] Seat-Anzahl und Plan-Code sind sauber modelliert.
|
||||
- [x] Lokaler Subscription-Status kann `trial`, `active`, `past_due`, `cancelled`, `frozen` abbilden.
|
||||
- [x] RLS/Tenant-Scope fuer alle neuen/angepassten Tabellen.
|
||||
- [x] Unit-Tests fuer Plan-/Seat-/Entitlement-Resolver.
|
||||
- [x] Kein neuer Entity-Builder-Konsument.
|
||||
|
||||
**Fortschritt:** `BILL-02`: 7/7 DoD = 100 % done.
|
||||
|
||||
## Technische Bausteine
|
||||
|
||||
- Eigenes Prisma-Schema im Billing-Bereich, keine neuen Modelle in `core.prisma` ausser noetige Relationen.
|
||||
- Forward-only Migration erst auf main/merge gemaess AD-21.
|
||||
- Domain-Service fuer `resolveTenantBillingState()` und `resolveTenantEntitlements()`.
|
||||
|
||||
## Umsetzungsnotiz
|
||||
|
||||
2026-07-04: Lokale Billing-Domain umgesetzt. `prisma/schema/subscriptions.prisma` enthaelt jetzt neutrale
|
||||
Lago-/Mollie-Referenzen, lokale `planCode`-/`seatQuantity`-Felder und Invoice-/Payment-Referenzen, ohne die
|
||||
bestehenden Legacy-Provider-Legacy-Felder zu entfernen. Standard-Entitlement-Plans seedet jetzt `code` und `lagoPlanCode`.
|
||||
Der neue DB-Service `@hivegrid/db/billing-domain.server` stellt `resolveTenantBillingState()` und
|
||||
`resolveTenantEntitlements()` bereit und liest ausschliesslich tenantgescoped per `tenantId`.
|
||||
|
||||
RLS/Tenant-Scope: Es wurden keine neuen Tabellen angelegt. Die angepassten Tenant-Billing-Tabellen bleiben ueber
|
||||
`TenantSubscription.tenantId` bzw. `TenantSubscriptionProduct -> TenantSubscription.tenantId` scoped; der neue
|
||||
Resolver akzeptiert nur `tenantId` und laedt keine globale Billing-Sicht.
|
||||
|
||||
Proof:
|
||||
- `pnpm exec prisma validate`
|
||||
- `pnpm --filter @hivegrid/db typecheck`
|
||||
- `pnpm --filter @hivegrid/db exec vitest run src/billing-domain.server.test.ts src/subscriptions.server.test.ts src/entitlements-seed.server.test.ts`
|
||||
|
||||
## Quellen
|
||||
|
||||
- AD-1, AD-2, AD-21, AD-27
|
||||
- `R-P1b` fuer `tenantHasModule()`
|
||||
- bestehende AK-P20-Billing-Grundlagen
|
||||
@@ -0,0 +1,65 @@
|
||||
# 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 |
|
||||
|
||||
## Abhaengigkeiten & Parallelitaet
|
||||
|
||||
- **Blocked by:** `BILL-01`, `BILL-02`
|
||||
- **Blocks:** `BILL-05`, `BILL-06`, `BILL-07`
|
||||
|
||||
## Was wir bauen
|
||||
|
||||
Ein serverseitiges Lago-Gateway in HiveGrid. HiveGrid erstellt/liest Customers, Plans, Subscriptions und Invoice-Status
|
||||
ueber Lago, aber UI-Komponenten sprechen nie direkt mit Lago.
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [x] Lago-API-Client mit klarer Env-Konfiguration fuer Staging.
|
||||
- [x] Customer-Erstellung fuer Tenant.
|
||||
- [x] Plan-/Seat-Subscription erstellen und lesen.
|
||||
- [x] Invoice-/Subscription-Status abrufen.
|
||||
- [x] Lago-Webhook-Endpunkt oder Pull-Sync-Job definiert und idempotent.
|
||||
- [x] Outbox/Retry fuer ausgehende Billing-Sync-Aktionen.
|
||||
- [x] Fehlertexte klar und ohne Stacktrace.
|
||||
- [x] Tests gegen Mock/Fixture der Lago-API.
|
||||
|
||||
**Fortschritt:** `BILL-03`: 8/8 DoD = 100 % done.
|
||||
|
||||
## Nicht im Scope
|
||||
|
||||
- Mollie-Zahlung.
|
||||
- Usage Events.
|
||||
- Customer-facing Billing UI.
|
||||
|
||||
## Technische Bausteine
|
||||
|
||||
- `BillingGateway`-Interface, konkrete Implementierung `LagoBillingGateway`.
|
||||
- Zod-Schemas fuer Lago-Antworten.
|
||||
- Redaction fuer API-Keys und Payment-/Invoice-IDs in Logs.
|
||||
|
||||
## Umsetzungsnotiz
|
||||
|
||||
2026-07-04: Server-Gateway fuer Lago umgesetzt. Neues Package `@hivegrid/billing` enthaelt das
|
||||
`BillingGateway`-Interface, `LagoBillingGateway`, Zod-Response-Schemas, Redaction-Helfer,
|
||||
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.
|
||||
|
||||
Proof:
|
||||
- `pnpm --filter @hivegrid/billing typecheck`
|
||||
- `pnpm --filter @hivegrid/billing test`
|
||||
- `pnpm --filter @hivegrid/config test`
|
||||
|
||||
## Quellen
|
||||
|
||||
- AD-27
|
||||
- Lago API Docs
|
||||
- `BILL-01`, `BILL-02`
|
||||
@@ -0,0 +1,70 @@
|
||||
# BILL-04 · Mollie Payment-Gateway
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Dev/Setup |
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | Billing-Recut nach AD-27 |
|
||||
| **Cycle/Fenster** | nach `BILL-02`, parallel zu `BILL-03` moeglich |
|
||||
| **Status** | Umgesetzt / bereit fuer Review |
|
||||
|
||||
## Abhaengigkeiten & Parallelitaet
|
||||
|
||||
- **Blocked by:** Mollie-Testaccount/Testmode-Keys; `BILL-02`
|
||||
- **Blocks:** `BILL-05`, `BILL-07`
|
||||
|
||||
## Was wir bauen
|
||||
|
||||
Mollie wird als Payment Processor angebunden. Mollie entscheidet nicht ueber Plan, Rechnung oder Entitlements; Mollie
|
||||
meldet nur Payment-Zustand zu einer HiveGrid-/Lago-Invoice-Referenz.
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [x] Mollie-Testmode eingerichtet und Secrets ausserhalb des Repos abgelegt.
|
||||
- [x] Payment/Checkout fuer eine Invoice-Referenz erzeugbar.
|
||||
- [x] Mollie-Webhooks mit Signatur-/Authentizitaetspruefung oder dokumentierter sicherer Verifikation.
|
||||
- [x] Payment-Status wird idempotent verarbeitet.
|
||||
- [x] Refund-/Failure-/Expired-Events werden als Billing-Events gespeichert.
|
||||
- [x] Keine HiveGrid-Fachdaten in Mollie-Payloads.
|
||||
- [x] Tests fuer Webhook-Parsing, Idempotenz und Fehlerfaelle.
|
||||
|
||||
## Umsetzungs-Notiz 2026-07-04
|
||||
|
||||
Code-seitig umgesetzt:
|
||||
|
||||
- Neues `MolliePaymentGateway` in `@hivegrid/billing` fuer `POST /v2/payments` und `GET /v2/payments/:id`.
|
||||
- `PaymentGateway`-Contract getrennt vom Lago-`BillingGateway`, damit Lago Billing/Invoicing bleibt und Mollie nur Payments verarbeitet.
|
||||
- Mollie-Payload minimiert: Betrag, Redirect-/Webhook-URL, optionale Mollie-Customer-ID und interne Referenzen (`tenantId`, `invoiceExternalId`, `paymentExternalId`). Keine Plan-/Seat-/CRM-/Kontakt-Fachdaten.
|
||||
- Klassische Mollie-Webhooks werden ueber `id` geparst und sicher durch API-Refetch verifiziert. Mollie liefert hier keine Legacy-Provider-aehnliche Signatur; die Verifikation ist der Abruf mit eigenem API-Key.
|
||||
- Idempotenter Outbox-Kontrakt `billing.mollie.payment` fuer `payment.paid`, `payment.failed`, `payment.expired`, `payment.refunded`, `payment.cancelled` und generisches `payment.refresh`.
|
||||
- Runtime-Konfig erweitert um `MOLLIE_API_KEY`, `MOLLIE_PROFILE_ID`, `MOLLIE_TIMEOUT_MS`; `.env.example` dokumentiert die Keys ohne Secret-Werte.
|
||||
|
||||
Proof:
|
||||
|
||||
- `pnpm --filter @hivegrid/billing typecheck`
|
||||
- `pnpm --filter @hivegrid/billing test`
|
||||
- `pnpm --filter @hivegrid/config test`
|
||||
|
||||
2026-07-04 Nachtrag: Mollie-Testmode-Key liegt lokal ausserhalb des Repos in `~/.cli-tokens/mollie` mit `0600`
|
||||
Rechten. Auth/Scope wurde ohne Ausgabe von Secret- oder Accountdetails gegen `GET /v2/payments?limit=1` geprueft:
|
||||
`payments.read` erreichbar. Damit ist der letzte DoD-Blocker geschlossen.
|
||||
|
||||
Finaler Stand: **7/7 DoD = 100 % done**.
|
||||
|
||||
## Nicht im Scope
|
||||
|
||||
- Mollie Invoicing.
|
||||
- Mollie als Customer-Portal-Ersatz.
|
||||
- Production-Live-Verifizierung.
|
||||
|
||||
## Technische Bausteine
|
||||
|
||||
- `PaymentGateway`-Interface, konkrete Implementierung `MolliePaymentGateway`.
|
||||
- Webhook-Log analog zu bestehender Webhook-Idempotenz, aber nicht Legacy-Provider-spezifisch.
|
||||
- Payment-Metadata: Tenant-ID nur als interne Referenz, keine Fachdaten.
|
||||
|
||||
## Quellen
|
||||
|
||||
- AD-27
|
||||
- Mollie API/Testmode Docs
|
||||
- bestehende Legacy-Provider-Webhook-Tests als Migrationsvorlage, nicht als Zielarchitektur
|
||||
@@ -0,0 +1,80 @@
|
||||
# BILL-05 · Billing-Sync, Entitlements und Read-only-State
|
||||
|
||||
| | |
|
||||
| ----------------- | ------------------------ |
|
||||
| **Typ** | Dev (Code) |
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | Billing-Recut nach AD-27 |
|
||||
| **Cycle/Fenster** | nach `BILL-03`/`BILL-04` |
|
||||
| **Status** | Done |
|
||||
|
||||
## Abhaengigkeiten & Parallelitaet
|
||||
|
||||
- **Blocked by:** `BILL-02`, `BILL-03`, `BILL-04`
|
||||
- **Blocks:** `BILL-06`, `BILL-07`
|
||||
|
||||
## Was wir bauen
|
||||
|
||||
Die Ereignis- und Zustandsbruecke zwischen Lago, Mollie und HiveGrid. Ergebnis: HiveGrid kennt verlaesslich, ob ein
|
||||
Tenant aktiv, past_due, frozen oder cancelled ist und welche Features/Seats erlaubt sind.
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [x] Payment-Events koennen Subscription-/Invoice-State aktualisieren.
|
||||
- [x] Lago-Subscription-State wird in lokalen HiveGrid-Billing-State gespiegelt.
|
||||
- [x] `tenantHasModule()` nutzt den neuen lokalen Entitlement-State.
|
||||
- [x] Read-only/Frozen-State blockiert mutierende Tenant-Aktionen zentral.
|
||||
- [x] Recovery-/Billing-Routen bleiben erreichbar, wenn Tenant frozen ist.
|
||||
- [x] Audit/Activity fuer relevante Billing-State-Wechsel.
|
||||
- [x] Idempotenz fuer alle eingehenden Events.
|
||||
- [x] Tests fuer State-Matrix und erlaubte/gesperrte Aktionen.
|
||||
|
||||
## Nicht im Scope
|
||||
|
||||
- Usage-Grenzen.
|
||||
- Dunning-Kommunikation ueber echte Mailsequenzen, falls nicht bereits vorhanden.
|
||||
- Finale Customer-facing UI.
|
||||
|
||||
## Technische Bausteine
|
||||
|
||||
- Bestehende `IdempotencyKey`-Tabelle als replay-sicheres Event-Log fuer Lago/Mollie-Sync
|
||||
(`scope=billing:provider-sync`), plus Audit/Activity fuer sichtbare State-Wechsel.
|
||||
- State-Resolver mit Cache-Invalidierung.
|
||||
- zentrale Permission-Boundary-Anbindung.
|
||||
|
||||
## Quellen
|
||||
|
||||
- AD-27
|
||||
- `R-P1b`
|
||||
- AK-P20-Read-only/Frozen-Vorarbeit
|
||||
|
||||
## Umsetzung
|
||||
|
||||
### 2026-07-04
|
||||
|
||||
- Neuer Sync-Service `@hivegrid/db/billing-sync.server`:
|
||||
- Lago-Subscription-Status wird auf `trial|active|past_due|frozen|cancelled` normalisiert und in
|
||||
`TenantSubscription` gespiegelt.
|
||||
- Lago-Plan/Seats/Perioden werden, wenn ein passendes `SubscriptionProduct` existiert, in
|
||||
`TenantSubscriptionProduct` gespiegelt.
|
||||
- Mollie-Payment-Events aktualisieren `lastPaymentExternalId`, `lastInvoiceExternalId`,
|
||||
`mollieCustomerId` und den lokalen Billing-Status.
|
||||
- Eingehende Provider-Events sind idempotent ueber `IdempotencyKey(scope=billing:provider-sync)`;
|
||||
Replay schreibt weder Audit noch Activity erneut.
|
||||
- Relevante State-Wechsel schreiben `AuditEvent` und einen tenantbezogenen Activity-Eintrag
|
||||
`billing_state_changed`.
|
||||
- `tenantHasModule()` und `requireTenantProductAccess()` lesen Entitlements aus dem lokalen
|
||||
Billing-State (`resolveTenantEntitlements`) statt aus der alten aktiven Subscription-Abfrage.
|
||||
- `getTenantBillingReadOnlyState()` nutzt `resolveTenantBillingState`; Marker wie `frozenAt` und
|
||||
`cancelledAt` gewinnen damit zentral vor rohen Status-Werten.
|
||||
- Public-API-Webhooks blockieren nun auch `cancelled`/`frozen` explizit als read-only Zustand.
|
||||
|
||||
Proof:
|
||||
|
||||
- `pnpm --dir packages/db test -- billing-sync.server.test.ts`
|
||||
- `pnpm --dir packages/activity typecheck`
|
||||
- `pnpm --dir apps/web test -- billingStatusService.test.ts tenantConnector.server.test.ts app.\$tenant.test.tsx productAccess.server.test.ts`
|
||||
- `pnpm exec vitest run apps/api/src/app.test.ts`
|
||||
- `pnpm run typecheck`
|
||||
|
||||
DoD: 8/8 = 100 % done.
|
||||
@@ -0,0 +1,80 @@
|
||||
# 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 |
|
||||
|
||||
## Abhaengigkeiten & Parallelitaet
|
||||
|
||||
- **Blocked by:** `BILL-05`
|
||||
- **Blocks:** Customer-facing Billing-Screens spaeter.
|
||||
- **Screen-Status:** finale Designs offen; Backend/Minimal-Admin kann ohne Screens vorbereitet werden.
|
||||
|
||||
## Was wir bauen
|
||||
|
||||
Eine interne Admin-Basis, damit Support/Operatoren Billing-Zustand sehen und manuell korrigieren koennen, ohne direkt
|
||||
in Lago/Mollie zu arbeiten.
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [x] Tenant-Billing-Status sichtbar: Plan, Seats, Subscription-Status, Payment-Status, letzte Invoice.
|
||||
- [x] Manuelle Sync-Aktion fuer Lago und Mollie.
|
||||
- [x] Read-only/Frozen-Grund und Recovery-Hinweis sichtbar.
|
||||
- [x] Admin kann Plan/Seats fuer Test-/Sonderkunden kontrolliert setzen, mit Audit und Reason.
|
||||
- [x] Keine Pricing-/Self-Service-UI fuer Endkunden.
|
||||
- [x] i18n/Klartext fuer sichtbare Texte.
|
||||
- [x] Tests fuer Loader/View-Model und Admin-Actions.
|
||||
|
||||
## Umsetzungs-Notiz
|
||||
|
||||
2026-07-04 · Raffael
|
||||
|
||||
- Interne Admin-Route `admin/accounts/billing` ergaenzt und im Admin-Accounts-Menue mit `admin.account.subscription` verlinkt.
|
||||
- View-Model `packages/view-models/src/admin/billing-admin.vm.ts` gebaut: Status, Plan, Seats, letzte Invoice/Payment, Provider-Referenzen, Read-only-Grund und Recovery-Hinweis.
|
||||
- Server-Service `apps/web/app/services/admin/billing-admin.server.ts` gebaut: Tenant-Billing-Liste, Plan/Seat-Override mit Pflichtgrund + Audit, Cache-Invalidierung und optionalem Catalog-Product-Attach; manuelle Lago-/Mollie-Sync-Anforderung via Outbox.
|
||||
- Endkunden-Pricing/Self-Service bewusst nicht beruehrt.
|
||||
- i18n in `de`, `de-formal`, `en` ergaenzt.
|
||||
- Proof:
|
||||
- `pnpm --dir packages/view-models test -- billing-admin.vm.test.ts`
|
||||
- `pnpm exec vitest run apps/web/app/services/admin/billing-admin.server.test.ts apps/web/app/routes/admin/accounts/billing.test.ts`
|
||||
- `pnpm --dir apps/web typecheck`
|
||||
- `pnpm run lint`
|
||||
|
||||
**BILL-06: 7/7 DoD = 100 % done.**
|
||||
|
||||
2026-07-05 · Readiness-Nachtrag
|
||||
|
||||
- Luecke geschlossen: Die Admin-Aktion fuer manuellen Provider-Sync legt nicht mehr nur ein `billing.*`-Outbox-Event
|
||||
ab. Diese Events hatten noch keinen Billing-Consumer und waeren damit fuer Admin-Sync als reine Platzhalter
|
||||
haengen geblieben.
|
||||
- Lago-Sync refetcht jetzt serverseitig den Lago-Customer und die letzte Tenant-Rechnung und wendet den lokalen
|
||||
Billing-Sync direkt an.
|
||||
- Mollie-Sync refetcht jetzt serverseitig die Zahlung ueber die Payment-ID und wendet den lokalen Payment-Sync direkt an.
|
||||
- `MOLLIE_*` ist fuer die Web-Runtime konfigurierbar, weil die Admin-Oberflaeche im Web-Prozess laeuft.
|
||||
- Proof:
|
||||
- `pnpm exec vitest run packages/config/src/web.test.ts packages/config/src/catalog.test.ts apps/web/app/services/admin/billing-admin.server.test.ts`
|
||||
- `pnpm --dir apps/web typecheck`
|
||||
|
||||
**BILL-06: 7/7 DoD = 100 % done.**
|
||||
|
||||
## Nicht im Scope
|
||||
|
||||
- Finales Customer-Billing-Center.
|
||||
- oeffentliche Planwechsel-/Checkout-UI.
|
||||
- Rechnungssteller-/Steuer-Finalisierung.
|
||||
|
||||
## Technische Bausteine
|
||||
|
||||
- Admin-Route oder bestehende Tenant-Detail-Erweiterung.
|
||||
- View-Model in `packages/view-models`.
|
||||
- Actions nur serverseitig, mit `withPermission()` und Audit.
|
||||
|
||||
## Quellen
|
||||
|
||||
- AD-27
|
||||
- `AK-P19`
|
||||
- `D-ADMIN` nach spaeterem Screen-Recut
|
||||
@@ -0,0 +1,138 @@
|
||||
# BILL-07 · Billing E2E Sandbox-Flow
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Dev/Test |
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | Billing-Recut nach AD-27 |
|
||||
| **Cycle/Fenster** | nach `BILL-03` bis `BILL-06` |
|
||||
| **Status** | Done |
|
||||
|
||||
## Abhaengigkeiten & Parallelitaet
|
||||
|
||||
- **Blocked by:** `BILL-03`, `BILL-04`, `BILL-05`
|
||||
- **Blocks:** Prod-Prep und spaetere Customer-facing Billing-Screens.
|
||||
|
||||
## Was wir bauen
|
||||
|
||||
Ein reproduzierbarer Sandbox-Proof fuer den kompletten v1-Billing-Kern: Tenant bekommt Plan/Seats, Lago kennt die
|
||||
Subscription, Mollie-Testzahlung aktualisiert Payment-Status, HiveGrid-Entitlements greifen.
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [x] Test-Tenant wird als Lago-Customer angelegt.
|
||||
- [x] Plan + Seat-Subscription wird in Lago erstellt.
|
||||
- [x] Mollie-Testzahlung wird erzeugt und abgeschlossen/simuliert.
|
||||
- [x] Webhook/Synchronisation aktualisiert lokale Subscription.
|
||||
- [x] `tenantHasModule()` und Read-only/Frozen-State reagieren korrekt.
|
||||
- [x] Invoice-/Payment-Referenzen sind sichtbar und auditiert.
|
||||
- [x] Negativfall `payment_failed`/`expired` getestet.
|
||||
- [x] E2E-Schritte sind in einem Runbook dokumentiert.
|
||||
|
||||
## Nicht im Scope
|
||||
|
||||
- Production-Live-Zahlung.
|
||||
- echte Rechnungs-/Steuerfreigabe.
|
||||
|
||||
## Technische Bausteine
|
||||
|
||||
- Test-Script oder Playwright/Integration-Test mit externen Sandbox-Stubs.
|
||||
- Eindeutige Testdaten-Prefixes fuer gemeinsame `lago-staging`-Instanz.
|
||||
|
||||
## Quellen
|
||||
|
||||
- AD-27
|
||||
- `BILL-01` bis `BILL-06`
|
||||
- `docs/ops/billing-e2e-sandbox.md`
|
||||
- `docs/ops/lago-staging.md`
|
||||
|
||||
## Umsetzung
|
||||
|
||||
2026-07-04: Stub-basierten, reproduzierbaren BILL-07-Sandbox-Flow gebaut.
|
||||
|
||||
- `packages/billing/src/sandbox-flow.ts` fuehrt den kompletten Kern-Flow mit deterministischen Lago-/Mollie-Stubs
|
||||
aus, nutzt dabei aber die echten lokalen Sync-/State-Bausteine `applyLagoSubscriptionSync`,
|
||||
`applyMolliePaymentSync` und `resolveTenantBillingState`.
|
||||
- `scripts/billing-e2e-sandbox.ts` gibt den Proof als JSON aus.
|
||||
- `docs/ops/billing-e2e-sandbox.md` dokumentiert Runbook, Testdaten-Konvention und spaetere Live-Sandbox-Erweiterung.
|
||||
- Proof: `pnpm exec tsx scripts/billing-e2e-sandbox.ts --run-id=manual-proof` ergibt `ok: true`, 8/8 Steps gruen,
|
||||
`active` nicht read-only, `failed`/`expired` -> `past_due` read-only, `frozen` read-only, Invoice-/Payment-Refs sichtbar, 5 Audit-Events
|
||||
und 5 Activity-Eintraege.
|
||||
|
||||
DoD: 8/8 = 100 % done.
|
||||
|
||||
2026-07-04 Nachtrag Staging-Live-Smoke:
|
||||
|
||||
- `lago-staging` auf node1 initialisiert: Organisation, Default-Billing-Entity, API-Key.
|
||||
- Mesh-only Proxy `lago-staging-mesh-proxy.service` auf node1: `10.42.0.4:3108 -> 127.0.0.1:3108`.
|
||||
- HiveGrid-Staging (`hivegrid-api`, `hivegrid-web`, `worker-general`, `worker-webhook`) mit `LAGO_*` und `MOLLIE_*`
|
||||
Runtime-Env redeployed; laufende Container enthalten die Keys.
|
||||
- Proof aus dem laufenden `hivegrid-api`-Container: Lago API HTTP 200, Mollie API HTTP 200.
|
||||
- Synthetischer Staging-Smoke: Lago-Customer mit Prefix `hg-stg-manual-` erstellt; Mollie-Testpayment mit Status `open`
|
||||
und Checkout-Link erzeugt.
|
||||
|
||||
2026-07-04 Nachtrag Mollie-Webhook-Grenze:
|
||||
|
||||
- API-Route `POST /v1/billing/mollie/webhooks` in `apps/api` registriert.
|
||||
- Route nimmt Mollies form-urlencoded `id` entgegen, refetcht die Zahlung serverseitig via `MOLLIE_API_KEY`, validiert
|
||||
`tenantId`/`invoiceExternalId` aus den verifizierten Payment-Metadaten und schreibt ueber `applyMolliePaymentSync`.
|
||||
- Security-Doku bewusst als `provider-refetch-webhook` statt Signatur-Webhook gefuehrt, weil Mollie keine
|
||||
Signatur fuer diesen Payload liefert.
|
||||
- OpenAPI, Route-Inventar, CSRF-Inventar und Scanner-Snapshot aktualisiert.
|
||||
- Proof: `pnpm --filter @hivegrid/api typecheck`; `pnpm typecheck`; `pnpm test`; fokussiert zusaetzlich
|
||||
`apps/api/src/billing/mollie-webhook-route.test.ts` und API-Inventar/OpenAPI-Tests.
|
||||
|
||||
2026-07-04 Nachtrag echter Staging-Checkout:
|
||||
|
||||
- Realer Staging-Tenant `demo-pro-crm` fuer Mollie-Testcheckout genutzt.
|
||||
- Mollie-Payment `tr_Nn3WsWmtkTXXYRCenmVTJ` im Mollie-Testscreen auf `paid` gesetzt.
|
||||
- Mollie-WebHook kam bei `https://staging-api.hivegrid.de/v1/billing/mollie/webhooks` mit HTTP 200 an.
|
||||
- HiveGrid-Staging setzte `TenantSubscription.status=active` und speicherte
|
||||
`lastInvoiceExternalId=hg-stg-invoice-20260704073025` /
|
||||
`lastPaymentExternalId=hg-stg-mollie-20260704073025`.
|
||||
- Direct replay gegen den Webhook ergab `replayed: true`, `billingStatus: active`.
|
||||
- `staging-admin.hivegrid.de` wurde fuer interne Admin-Pruefung provisioniert; korrekte Route:
|
||||
`https://staging-admin.hivegrid.de/accounts/billing` (ohne `/admin`-Prefix).
|
||||
- DoD bleibt: 8/8 = 100 % done.
|
||||
|
||||
2026-07-04 Nachtrag Lago-Operator-UI:
|
||||
|
||||
- Lago-Staging ist fuer Operator-Pruefung unter `https://staging-lago.hivegrid.de` erreichbar.
|
||||
- DNS-Pattern fuer Staging bleibt `staging-*.hivegrid.de`; `staging-lago` zeigt vorerst auf `node1`, weil die
|
||||
Lago-Staging-Resource dort laeuft.
|
||||
- Public Route ist nur die Lago-Frontend-UI, geschuetzt durch Lago-Login; die Lago-API bleibt intern ueber
|
||||
`http://10.42.0.4:3108`.
|
||||
- Lago-Operator-Zugang liegt lokal in `~/.cli-tokens/lago-staging`.
|
||||
- Proof: `curl` gegen `https://staging-lago.hivegrid.de` liefert HTTP 200; GraphQL `__typename` liefert HTTP 200.
|
||||
- DoD bleibt: 8/8 = 100 % done.
|
||||
|
||||
2026-07-04 Nachtrag Login-Fix:
|
||||
|
||||
- Ursache: Lago-Frontend hatte noch `API_URL=http://127.0.0.1:3108`; der Browser postete Login-GraphQL dadurch gegen
|
||||
das Operator-Geraet statt gegen den Server.
|
||||
- Fix: Frontend-`API_URL` auf `https://staging-lago.hivegrid.de` gesetzt und Traefik fuer `/graphql` und `/api` auf
|
||||
den Lago-API-Container geroutet. Traefik Basic Auth wurde danach wieder entfernt; Schutz laeuft ueber Lago-Login.
|
||||
- Proof: `env-config.js` zeigt `window.API_URL = "https://staging-lago.hivegrid.de"`; GraphQL `__typename` ueber
|
||||
`https://staging-lago.hivegrid.de/graphql` liefert HTTP 200; echte `loginUser`-Mutation mit gespeicherten
|
||||
Lago-Staging-Credentials liefert HTTP 200 und ein Token.
|
||||
- DoD bleibt: 8/8 = 100 % done.
|
||||
|
||||
2026-07-05 Nachtrag ActiveStorage-Logo-Fix:
|
||||
|
||||
- Ursache: hochgeladene Lago-Logos nutzen Rails ActiveStorage-URLs unter `/rails/active_storage/...`; die Public
|
||||
Route zeigte diesen Pfad noch auf das Lago-Frontend, deshalb renderte die UI ein kaputtes Bild.
|
||||
- Fix: Traefik-Dynamic-Config auf `node1` (`/data/coolify/proxy/dynamic/lago-staging.yaml`) erweitert, sodass
|
||||
`/rails/active_storage` ebenfalls auf den Lago-API-Container geht.
|
||||
- Proof: Fake-ActiveStorage-Pfad liefert jetzt API-404 statt Frontend-HTML; echte Billing-Entity-`logo_url` liefert
|
||||
`200 image/png`.
|
||||
- DoD bleibt: 8/8 = 100 % done.
|
||||
|
||||
2026-07-05 Nachtrag Invoice-Template/Beispielrechnung:
|
||||
|
||||
- Default-Billing-Entity in Lago staging mit deutschen Rechnungsdaten, 19 % USt, Logo, Dokumentensprache `de` und
|
||||
`14` Tagen Zahlungsziel konfiguriert.
|
||||
- Footer bewusst Mollie-neutral formuliert, damit er sowohl fuer automatische Karten-/Mandatsabbuchung als auch fuer
|
||||
manuelle Zahlung passt.
|
||||
- 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.
|
||||
@@ -0,0 +1,67 @@
|
||||
# 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 |
|
||||
|
||||
## Abhaengigkeiten & Parallelitaet
|
||||
|
||||
- **Blocked by:** Firmierung/Rechnungssteller-Entscheidung, Mollie-Live-Verifizierung.
|
||||
- **Blocks:** produktives Self-Service-Billing.
|
||||
- **Aktuelle Entscheidung 2026-07-04:** Prod-Billing wird jetzt nicht weiter verfolgt; getestet wird ueber Staging.
|
||||
|
||||
## Was wir bauen
|
||||
|
||||
Die Production-Vorbereitung fuer eine eigene Lago-Instanz im HiveGrid-Prod-Setup. Staging und Prod werden getrennt.
|
||||
`BILL-07` ist erledigt; der verbleibende Blocker ist extern/rechtlich bzw. Mollie-Live-KYC.
|
||||
|
||||
Dieses Ticket bleibt als spaetere Production-Notiz erhalten. Fuer den aktuellen Testpfad gilt `BILL-07` /
|
||||
`docs/ops/lago-staging.md`.
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [x] Zielhost/-Coolify fuer `lago-production` entschieden.
|
||||
- [x] Eigene Production-DB/Volumes/Secrets, keine Wiederverwendung der Staging-Instanz.
|
||||
- [x] Backup + Restore-Drill dokumentiert.
|
||||
- [x] Zugriff/Auth/Domain entschieden.
|
||||
- [ ] Mollie-Live-Konto verifiziert und Live-Webhooks vorbereitet.
|
||||
- [ ] Rechnungssteller-/Steuer-/Impressumsdaten fachlich freigegeben.
|
||||
- [x] Rollback-Pfad fuer Billing-Deploy dokumentiert.
|
||||
|
||||
**Fortschritt:** `BILL-08`: 5/7 DoD = ~71 % done. Offen: 2 externe Gates (`Mollie-Live-Konto`,
|
||||
`Rechnungssteller-/Steuer-/Impressumsdaten`). Selbst machbarer Dev-/Ops-Anteil aktuell 5/5 = 100 %.
|
||||
|
||||
## Nicht im Scope
|
||||
|
||||
- Vorziehen ohne `BILL-07`.
|
||||
- Vermischung mit Staging.
|
||||
|
||||
## Technische Bausteine
|
||||
|
||||
- Eigene Lago-Production-Resource.
|
||||
- Secret-Rotation-Plan.
|
||||
- Monitoring/Healthchecks.
|
||||
|
||||
## Umsetzungsnotiz
|
||||
|
||||
2026-07-04: Production-Prep ohne Provisionierung dokumentiert. Zieltopologie: Coolify-Projekt `HiveGrid`,
|
||||
Environment `production`, Resource `lago-production`; initial auf dem aktuellen HiveGrid-Production-Host, solange
|
||||
Hetzner-Kapazitaet limitiert ist, aber mit eigener Resource, eigener DB, eigenem Redis/Storage und eigenen Secrets.
|
||||
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`.
|
||||
|
||||
Proof:
|
||||
- `docs/ops/lago-production-prep.md`
|
||||
- `git diff --check`
|
||||
|
||||
## Quellen
|
||||
|
||||
- AD-24
|
||||
- AD-27
|
||||
- `BILL-07`
|
||||
- `EXT-16`
|
||||
- `docs/ops/lago-production-prep.md`
|
||||
@@ -0,0 +1,95 @@
|
||||
# BILL-09 · Kunden-Rechnungszugriff in HiveGrid
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Dev/UI ohne finale Screens |
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | Billing-Recut nach AD-27 |
|
||||
| **Cycle/Fenster** | nach `BILL-07` |
|
||||
| **Status** | Done |
|
||||
|
||||
## Abhaengigkeiten & Parallelitaet
|
||||
|
||||
- **Blocked by:** `BILL-03`, `BILL-05`, `BILL-07`
|
||||
- **Blocks:** spaetere Self-Service-Billing-Screens (`VA-P24a`/`VD-P24`)
|
||||
- **Screen-Status:** finale Designs offen; bestehende Subscription-Settings-Flaeche wird minimal erweitert.
|
||||
|
||||
## Was wir bauen
|
||||
|
||||
Kunden sollen ihre Lago-Rechnungen in HiveGrid sehen und herunterladen koennen. Mollie bleibt nur Payment-Processor;
|
||||
Rechnungsdaten und PDF-Link kommen aus Lago. HiveGrid ist die sichtbare Kundenflaeche und prueft Tenant + Permission,
|
||||
bevor ein Download-Link ausgegeben wird.
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [x] Lago-Gateway kann Rechnungen inklusive Nummer und generiertem PDF-Link lesen.
|
||||
- [x] Tenant-Subscription-Seite laedt Rechnungen nur mit `app.settings.subscription.invoices.view`.
|
||||
- [x] Rechnungen werden tenant-gefiltert angezeigt und koennen nicht tenant-uebergreifend geladen werden.
|
||||
- [x] Download laeuft ueber eine HiveGrid-Route mit Permission-Check, nicht ueber direkte Lago-Secrets im Browser.
|
||||
- [x] Klartext/i18n fuer Rechnungstypen, Payment-Status und Fehlerfaelle.
|
||||
- [x] Tests fuer Gateway, Service, Loader und Download-Route.
|
||||
|
||||
## Umsetzungs-Notiz
|
||||
|
||||
2026-07-04 · Raffael
|
||||
|
||||
- `@hivegrid/billing` erweitert: Lago-Invoices enthalten `number` und `fileUrl`; `downloadInvoice()` nutzt
|
||||
`POST /api/v1/invoices/:id/download`.
|
||||
- Web-Server-Config liest `LAGO_API_URL`, `LAGO_API_KEY`, `LAGO_WEBHOOK_SECRET`, `LAGO_TIMEOUT_MS` serverseitig.
|
||||
- Neuer Service `apps/web/app/services/billing/customer-invoices.server.ts`: listet tenant-gefilterte Rechnungen und
|
||||
verifiziert Tenant-Ownership vor Download.
|
||||
- Bestehende Route `/:tenant/settings/subscription` zeigt einen Rechnungsblock, wenn die Invoice-Permission vorhanden
|
||||
ist. Bei temporarem Lago-Fehler bleibt die Abo-Seite erreichbar und zeigt einen Klartext-Hinweis.
|
||||
- Neue Resource-Route `/:tenant/settings/subscription/invoices/:invoiceId/download` prueft Permission und leitet erst
|
||||
danach auf die von Lago erzeugte PDF-URL weiter.
|
||||
|
||||
Proof:
|
||||
- `pnpm --dir packages/billing test -- lago.test.ts sandbox-flow.test.ts`
|
||||
- `pnpm exec vitest run apps/web/app/services/billing/customer-invoices.server.test.ts apps/web/app/routes/app.\\$tenant/settings/subscription.test.tsx apps/web/app/routes/app.\\$tenant/settings/subscription/invoices.\\$invoiceId.download.test.tsx packages/config/src/web.test.ts packages/config/src/catalog.test.ts`
|
||||
- `pnpm typecheck`
|
||||
- `pnpm lint`
|
||||
- `git diff --check`
|
||||
|
||||
Nachtrag 2026-07-04:
|
||||
- Lago-Staging war nach dem UI-Deploy noch leer: 0 Plans, 0 Subscriptions, 0 Invoices. Der Empty-State in HiveGrid
|
||||
war dadurch korrekt.
|
||||
- Echte Lago-Demo-Testdaten angelegt: Plans `starter`/`pro`/`business`, je eine Subscription fuer
|
||||
`demo-starter-crm`, `demo-pro-crm`, `demo-business-crm`, je eine finalized `EUR 1.00` Invoice.
|
||||
- Live-Proof auf Staging: alle drei Routen `/:tenant/settings/subscription` zeigen ihre Rechnungsnummer, der
|
||||
Empty-State ist weg.
|
||||
- Lago-Staging auf dedizierten Hetzner-Bucket `hivegrid-staging-lago` umgestellt; synthetische Rechnung
|
||||
`HIV-6711-005-001` erzeugte ein PDF-Objekt im Bucket.
|
||||
- Download-Fix: HiveGrid streamt PDFs nun ueber die eigene Download-Route, statt Kunden auf Lago/Bucket-URLs zu
|
||||
redirecten. Ownership wird vorab ueber die tenant-gefilterte Lago-Invoice-Liste geprueft, weil
|
||||
`POST /api/v1/invoices/:id/download` keine Customer-Felder zurueckgibt.
|
||||
- Alte lokale Demo-Invoices `HIV-6711-002-001`, `HIV-6711-003-001`, `HIV-6711-004-001` wurden voided; neue
|
||||
S3-backed Demo-Invoices `HIV-6711-002-002`, `HIV-6711-003-002`, `HIV-6711-004-002` erzeugt.
|
||||
|
||||
**BILL-09: 6/6 DoD = 100 % done.**
|
||||
|
||||
Nachtrag 2026-07-05:
|
||||
|
||||
- Kunden-Rechnungszugriff erneut mit einer volleren Lago-Rechnung geprueft:
|
||||
`HIV-6711-002-008` fuer `demo-pro-crm`, inklusive Business-Plan, Zusatznutzern, Storage, Email-Marketing,
|
||||
Add-ons, Datenmigration, Schulung und Onboarding.
|
||||
- Die Rechnung nutzt den aktuellen neutralen Mollie-Footer und `14` Tage Zahlungsziel.
|
||||
- HiveGrid-Route:
|
||||
`https://staging-app.hivegrid.de/demo-pro-crm/settings/subscription/invoices/41c8e519-d871-4ead-9a0f-6b33fc592e71/download`
|
||||
liefert `200 application/pdf` und streamt das PDF serverseitig nach Permission-/Tenant-Pruefung.
|
||||
|
||||
**BILL-09: 6/6 DoD = 100 % done.**
|
||||
|
||||
## Nicht im Scope
|
||||
|
||||
- Self-Service-Planwechsel/Seat-Wechsel.
|
||||
- Finale Subframe-Screens fuer Billing.
|
||||
- Production-Billing-Livegang.
|
||||
- Rechnungssteller-/Steuerfreigabe.
|
||||
|
||||
## Quellen
|
||||
|
||||
- AD-27
|
||||
- `BILL-03`
|
||||
- `BILL-05`
|
||||
- `BILL-07`
|
||||
- `VA-P24a`
|
||||
@@ -0,0 +1,78 @@
|
||||
# BILL-10 · Self-Service-Checkout fuer Planwechsel
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Dev ohne finale Screens |
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | Billing-Recut nach AD-27 |
|
||||
| **Cycle/Fenster** | vorgezogen aus `VA-P24a` |
|
||||
| **Status** | Done |
|
||||
|
||||
## Abhaengigkeiten & Parallelitaet
|
||||
|
||||
- **Blocked by:** `BILL-03`, `BILL-04`, `BILL-05`, `BILL-07`, `BILL-09`
|
||||
- **Blocks:** finale Self-Service-Billing-Screens (`VA-P24a`/`VD-P24`)
|
||||
- **Screen-Status:** finale Designs offen; bestehende Tenant-Subscription-Settings werden als funktionale Basis genutzt.
|
||||
|
||||
## Was wir bauen
|
||||
|
||||
Kunden koennen in `/:tenant/settings/subscription` einen oeffentlichen Plan und eine Seat-Anzahl auswaehlen.
|
||||
HiveGrid erstellt serverseitig einen Lago-Customer, eine Lago-Subscription und eine Mollie-Zahlung. Mollie bleibt nur
|
||||
Payment-Processor; Lago/HiveGrid bilden den lokalen Subscription-/Entitlement-State. Rueckkehr aus Mollie und Webhook
|
||||
sind idempotent, damit der Tenant auch dann aktiviert wird, wenn der Browser nicht sauber zurueckkehrt.
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [x] Subscription-Settings zeigen oeffentliche Plaene und erlauben Plan-/Seat-Auswahl mit vorhandenen Plan-Karten.
|
||||
- [x] Checkout-Action validiert Tenant, Permission, CSRF, Produkt, Preis, Billing-Period, Currency und Quantity.
|
||||
- [x] Lago-Customer und Lago-Subscription werden vor der Zahlung erzeugt.
|
||||
- [x] Mollie-Zahlung enthaelt nur Billing-Minimum plus technische Checkout-Metadaten fuer Tenant, Invoice, Plan und Seats.
|
||||
- [x] CheckoutSessionStatus speichert Provider-Payment-ID, Lago-Subscription-ID, Plan-Code, Preis, Menge und Status.
|
||||
- [x] Mollie-Webhook aktiviert bei bezahlten Self-Service-Zahlungen den lokalen Lago-/HiveGrid-Billing-State.
|
||||
- [x] Checkout-Success-Route prueft die Zahlung erneut und kann den Sync nachziehen, falls der Webhook noch nicht lief.
|
||||
- [x] Tests fuer Billing-Metadaten, Webhook, DB-Checkout-Status, Subscription-Route und Success-Route.
|
||||
|
||||
## Umsetzungs-Notiz
|
||||
|
||||
2026-07-05 · Raffael
|
||||
|
||||
- Neuer Service `apps/web/app/services/billing/self-service-checkout.server.ts` kapselt den Checkout:
|
||||
`LagoBillingGateway` fuer Customer/Subscription, `MolliePaymentGateway` fuer Checkout-Link, lokale
|
||||
`CheckoutSessionStatus`-Persistenz.
|
||||
- `/:tenant/settings/subscription` rendert wieder Plan-Karten (`PlansGrouped`) und leitet nach `action=subscribe`
|
||||
auf Mollie weiter.
|
||||
- `POST /v1/billing/mollie/webhooks` spiegelt bezahlte Checkout-Metadaten zusaetzlich ueber
|
||||
`applyLagoSubscriptionSync`, nicht nur ueber `applyMolliePaymentSync`.
|
||||
- `subscribe.$tenant.$session.success` nutzt den neuen Self-Service-Checkout-Status und zieht den idempotenten Sync
|
||||
bei Rueckkehr aus Mollie nach.
|
||||
- Prisma-Migration `20260705123000_billing_self_service_checkout` erweitert `CheckoutSessionStatus`.
|
||||
|
||||
Proof:
|
||||
|
||||
- `pnpm --dir apps/web typecheck`
|
||||
- `pnpm --filter @hivegrid/api typecheck`
|
||||
- `pnpm --filter @hivegrid/billing typecheck`
|
||||
- `pnpm --filter @hivegrid/api exec vitest run src/billing/mollie-webhook-route.test.ts src/app.test.ts`
|
||||
- `pnpm --filter @hivegrid/db exec vitest run src/subscriptions.server.test.ts src/billing-sync.server.test.ts`
|
||||
- `pnpm --dir apps/web exec vitest run app/routes/app.\\$tenant/settings/subscription.test.tsx app/routes/subscribe.\\$tenant.\\$session.success.test.tsx`
|
||||
- `pnpm --filter @hivegrid/billing test -- --run src/mollie.test.ts src/sync-outbox.test.ts`
|
||||
|
||||
**BILL-10: 8/8 DoD = 100 % done.**
|
||||
|
||||
## Nicht im Scope
|
||||
|
||||
- Finale Subframe-Screens fuer Billing.
|
||||
- Vollautomatischer Staging-E2E gegen echte Lago-/Mollie-Testdaten.
|
||||
- Production-Billing-Livegang.
|
||||
- Steuer-/Rechnungssteller-Freigabe.
|
||||
- Usage-Billing, Credits oder Add-on-Metering.
|
||||
|
||||
## Quellen
|
||||
|
||||
- AD-27
|
||||
- `BILL-03`
|
||||
- `BILL-04`
|
||||
- `BILL-05`
|
||||
- `BILL-07`
|
||||
- `BILL-09`
|
||||
- `VA-P24a`
|
||||
@@ -0,0 +1,48 @@
|
||||
# BILL-README · Billing-Recut Track
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Planungs-/Dev-Track |
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | Billing-Recut nach AD-27 |
|
||||
| **Cycle/Fenster** | nach MCP-/P12-Arbeit einplanen |
|
||||
| **Status** | Neu geplant |
|
||||
|
||||
## Ziel
|
||||
|
||||
Legacy-Provider wird als Billing-/Payment-Default abgeloest. HiveGrid nutzt:
|
||||
|
||||
- **Lago self-hosted** als Billing-Engine fuer Plans, Seats, Subscriptions und Invoices.
|
||||
- **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.
|
||||
|
||||
## Ticket-Reihenfolge
|
||||
|
||||
1. `BILL-00` — Legacy-Provider-Recut und Planungs-Docs bereinigen
|
||||
2. `BILL-01` — Lago-Staging sauber betreiben
|
||||
3. `BILL-02` — Billing-Domain fuer Plans/Seats festziehen
|
||||
4. `BILL-03` — Lago-Gateway integrieren
|
||||
5. `BILL-04` — Mollie-Payment-Gateway integrieren
|
||||
6. `BILL-05` — Sync, Entitlements und Read-only/Frozen-State
|
||||
7. `BILL-06` — interne Admin-Billing-Basis
|
||||
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
|
||||
|
||||
## Architektur-Grenzen
|
||||
|
||||
- Lago ist Billing-Source-of-Truth fuer Rechnungs-/Subscription-Berechnung.
|
||||
- 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.
|
||||
- Kein Lago-Core-Fork ohne separate Lizenz-/Legal-Entscheidung wegen AGPL-3.0.
|
||||
|
||||
## Legacy-Drift
|
||||
|
||||
`BILL-00` hat die aktiven Ticketdocs fuer den Billing-Pfad auf `AD-27` recuttet. Alte Legacy-Provider-Erwaehnungen in
|
||||
historischen Umsetzungsnotizen, breiteren Roadmap-/Milestone-Dokumenten oder Legacy-Code sind Migrationsinventar und
|
||||
duerfen nicht als Zielarchitektur gelesen werden. Neue Billing-Arbeit startet bei `BILL-01`/`BILL-02`.
|
||||
@@ -10,7 +10,7 @@
|
||||
|
||||
> 🟩 **Compose-Ticket:** deckt **alle Admin-Screens** (P19). Compose aus A2/A3/A4/A5/A6 + KPI/Charts — aber **eigene Admin-Shell** (nicht App-Shell A1): getrennte Sidebar/Topbar auf `admin.hivegrid.de`. Interner Polish reicht (kein 🌐-Niveau).
|
||||
|
||||
> 🟡 **v1-Schnitt (verbindlich):** Getrennte AdminUser-Identität / AdminRBAC-Parallelwelt (M038/M039) → **v2** (v1 = Boilerplate-User-Extension + `admin-mfa-gate`). **Keine** AdminUser-/AdminRole-Verwaltungs-Screens, **keine** Plattform-Lead-Pipeline/Deal-Kanban, **keine** Feature-Flag-Massen-Statistik, **kein** KWP-Sync-Status-Screen in v1; Churn/ARPU → v2. **Neu v1:** Admin stellt Tenant-Abos zusammen (Feature-Konnektoren togglen + Stripe-Positionen — Abo-Baukasten-Mechanik).
|
||||
> 🟡 **v1-Schnitt (verbindlich):** Getrennte AdminUser-Identität / AdminRBAC-Parallelwelt (M038/M039) → **v2** (v1 = Boilerplate-User-Extension + `admin-mfa-gate`). **Keine** AdminUser-/AdminRole-Verwaltungs-Screens, **keine** Plattform-Lead-Pipeline/Deal-Kanban, **keine** Feature-Flag-Massen-Statistik, **kein** KWP-Sync-Status-Screen in v1; Churn/ARPU → v2. **Neu v1:** Admin stellt Tenant-Abos zusammen (Feature-Konnektoren togglen + Legacy-Provider-Positionen — Abo-Baukasten-Mechanik).
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `D-D0b` (Archetypen — Reuse der Bausteine; die Admin-Sidebar/-Topbar werden hier aber **getrennt** neu komponiert, kein A1-Reuse)
|
||||
@@ -27,10 +27,10 @@ Die **getrennte Plattform-Admin-Welt** auf `admin.hivegrid.de`: Admin-Login + 2F
|
||||
| Admin-Login + 2FA [`admin.hivegrid.de/login`, `/2fa`] | Email + Passwort (NIST/HIBP, Captcha ab 3. Fehler), TOTP-Pflicht, kein Magic-Link, 8h-Session | A4 / A5 |
|
||||
| Admin-Dashboard [`/dashboard`] | **Basis-KPIs: Tenants, aktive User, MRR** + System-Health-Ampel + Queue-Status · Klick je Kachel → Drill-Down · Zeitraum-Wechsler *(Churn/ARPU/Sales-Pipeline → v2)* | KPI |
|
||||
| Tenant-Liste [`/tenants`] | Name, Slug, Status (Klartext-Farbe), Plan, MRR, User-Anzahl, letzte Aktivität, Branche/Größe · Filter + Suche + Bulk (Tag/Email) | A2 |
|
||||
| **Tenant-Detail** [`/tenants/:id`] | Stammdaten, Status-Wechsler (Reason-Pflicht), **Abo-Zusammenstellung (Feature-Konnektoren togglen + Stripe-Positionen — Abo-Baukasten!)**, Trial-Verlängerung (Datum + Reason), Notizen (Markdown, kategorisiert, gepinnt), User-/Activity-/Audit-/Feature-Flag-Sektionen, **Impersonate mit Begründungs-Pflicht** | A2 / A3 + A6 |
|
||||
| **Tenant-Detail** [`/tenants/:id`] | Stammdaten, Status-Wechsler (Reason-Pflicht), **Abo-Zusammenstellung (Feature-Konnektoren togglen + Legacy-Provider-Positionen — Abo-Baukasten!)**, Trial-Verlängerung (Datum + Reason), Notizen (Markdown, kategorisiert, gepinnt), User-/Activity-/Audit-/Feature-Flag-Sektionen, **Impersonate mit Begründungs-Pflicht** | A2 / A3 + A6 |
|
||||
| Manuelle Tenant-Anlage [`/tenants/new`] | Name, Slug (Live-Validation), Branche, Größe, Initial-Admin-Email, Initial-Module/Plan, Trial-Dauer, Demo-Daten-Häkchen, Reason-Pflicht | A4 |
|
||||
| User-Liste + Detail [`/users`, `/:id`] | Liste: Email, Name, Tenant-Memberships, 2FA-Status, letzte Aktivität, Status · Detail: Memberships mit Rolle, Sessions, letzte Logins, Ops (2FA-Reset mit Reason, Session-Revoke, Deaktivieren, Lösch im Auftrag) | A2 / A3 |
|
||||
| Subscription-Liste + Detail [`/subscriptions`, `/:id`] | Liste: Tenant, Plan, MRR, Status, Renewal, Stripe-Sync · Detail: Stripe-Customer/Sub-ID (Link), Plan + Positionen + MRR, Trial, Rechnungs-History, manuelle Override (Plan/Sonderpreis/Reason), Stripe-Sync forcieren, Refund | A2 / A3 |
|
||||
| Subscription-Liste + Detail [`/subscriptions`, `/:id`] | Liste: Tenant, Plan, MRR, Status, Renewal, Legacy-Provider-Sync · Detail: Legacy-Provider-Customer/Sub-ID (Link), Plan + Positionen + MRR, Trial, Rechnungs-History, manuelle Override (Plan/Sonderpreis/Reason), Legacy-Provider-Sync forcieren, Refund | A2 / A3 |
|
||||
| Feature-Flags [`/feature-flags`] | Flag-Liste (Key, Status, Targeting), Filter-Editor (plan-tier), Tenant-Override mit Ablauf *(Massen-Statistik → v2)* | A2 + A6 |
|
||||
| Health + Worker-Queues [`/health`, `/health/workers`] | Service-Ampeln (Web/API/Worker/Scheduler), DB/Redis/Storage · BullMQ-Queues: Active/Waiting/Delayed/Failed je Queue, Job-Detail mit Error-Stack, Retry (Bulk/einzeln), Pause/Resume · Error-Rate Top-10 | A2 + KPI |
|
||||
| Support-Inbox + Ticket-Detail [`/support`, `/:id`] | Liste: Betreff, Tenant, Source, Status, Priorität, Zugewiesen · Detail: Konversation, Antwort (Markdown + Anhänge), interne Notiz, Status/Priority/Tag/Assignee-Wechsler, Reaktions-Templates · **speist sich aus Feedback-Widget (P21)!** | A2 / A3 |
|
||||
@@ -41,7 +41,7 @@ Die **getrennte Plattform-Admin-Welt** auf `admin.hivegrid.de`: Admin-Login + 2F
|
||||
|
||||
## Features (muss abgedeckt sein)
|
||||
- [ ] Admin meldet sich auf `admin.hivegrid.de` an (Host-Routing, Cookie-Domain-Trennung, TOTP-Pflicht + MFA-Step-up); Admin-User ohne Tenant-Workspace; kein Generalschlüssel
|
||||
- [ ] Admin verwaltet Tenants/Subscription-Overrides/Feature-Flags; **Abo-Zusammenstellung** = Feature-Konnektoren togglen + Stripe-Positionen (Abo-Baukasten)
|
||||
- [ ] Admin verwaltet Tenants/Subscription-Overrides/Feature-Flags; **Abo-Zusammenstellung** = Feature-Konnektoren togglen + Legacy-Provider-Positionen (Abo-Baukasten)
|
||||
- [ ] Admin-Dashboard: Boilerplate-KPIs (Tenants/User/MRR) + System-Health + Queue-Status
|
||||
- [ ] BullMQ-Queue-Monitoring (Retry/Pause/Resume, Job-Detail mit Error-Stack) + Support-Inbox
|
||||
- [ ] `AdminAuditLog` (tenant_id=null) über Audit-Hash-Kette; sensitive Aktionen (Status-Wechsel/Impersonate/Subscription-Override) mit Reason-Pflicht + Klartext-Bestätigung
|
||||
@@ -49,7 +49,7 @@ Die **getrennte Plattform-Admin-Welt** auf `admin.hivegrid.de`: Admin-Login + 2F
|
||||
- [ ] Eigene getrennte Admin-Shell (Sidebar Dashboard/Tenants/Users/Subscriptions/Feature-Flags/Health/Audit/Support/Legal/Settings) — kein App-Sidebar-Reuse
|
||||
|
||||
## UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)
|
||||
Eigene Admin-Sidebar + -Topbar (getrennt von A1); KPI-Kacheln mit Drill-Down + Zeitraum-Wechsler; System-Health-Ampel; Daten-Tabelle (sortierbar, paginiert, Spalten-Konfig); Filter-Bar; Bulk-Action-Toolbar; Status-Wechsler mit Reason-Pflicht-Modal; **Abo-Baukasten-Panel** (Feature-Konnektor-Toggles + Stripe-Positionsliste mit Preisen); Trial-Verlängerungs-Datum-Picker; Markdown-Notizen-Editor mit Pin + Kategorie; Impersonate-Button mit Begründungs-Modal; Stripe-Link-Badge; manuelle-Override-Formular; Queue-Status-Tabelle mit Retry/Pause/Resume; Job-Detail-Drawer mit Error-Stack; Feature-Flag-Liste + Targeting-Filter-Editor + Tenant-Override-mit-Ablauf; Support-Konversations-Ansicht + Markdown-Reply + interne-Notiz-Toggle + Reaktions-Templates; Audit-Tabelle mit Diff-Drawer + Export; Subprozessor-Tabelle + AVV-Versions-Liste mit PDF-Upload; Bestätigungs-Dialoge (Confirm-Phrase für destruktive Aktionen); Empty-/Loading-/Fehler-/Permission-Denied-States (Klartext mit Lösungs-Knopf).
|
||||
Eigene Admin-Sidebar + -Topbar (getrennt von A1); KPI-Kacheln mit Drill-Down + Zeitraum-Wechsler; System-Health-Ampel; Daten-Tabelle (sortierbar, paginiert, Spalten-Konfig); Filter-Bar; Bulk-Action-Toolbar; Status-Wechsler mit Reason-Pflicht-Modal; **Abo-Baukasten-Panel** (Feature-Konnektor-Toggles + Legacy-Provider-Positionsliste mit Preisen); Trial-Verlängerungs-Datum-Picker; Markdown-Notizen-Editor mit Pin + Kategorie; Impersonate-Button mit Begründungs-Modal; Legacy-Provider-Link-Badge; manuelle-Override-Formular; Queue-Status-Tabelle mit Retry/Pause/Resume; Job-Detail-Drawer mit Error-Stack; Feature-Flag-Liste + Targeting-Filter-Editor + Tenant-Override-mit-Ablauf; Support-Konversations-Ansicht + Markdown-Reply + interne-Notiz-Toggle + Reaktions-Templates; Audit-Tabelle mit Diff-Drawer + Export; Subprozessor-Tabelle + AVV-Versions-Liste mit PDF-Upload; Bestätigungs-Dialoge (Confirm-Phrase für destruktive Aktionen); Empty-/Loading-/Fehler-/Permission-Denied-States (Klartext mit Lösungs-Knopf).
|
||||
|
||||
## Quellen (granular)
|
||||
- `designer-briefs/P19-plattform-admin.md` (vollständiger Brief — alle Admin-Screens, diese Doc ist sein Ticket-Destillat)
|
||||
|
||||
@@ -34,7 +34,7 @@
|
||||
| Channel-Settings | Members verwalten, Privacy, Archivieren, verlassen | A6 |
|
||||
| Admin-Chat-Übersicht [`/admin/chat`] | Alle Channels, Cleanup-Tools · **DM-Audit mit Begründungs-Pflicht-Banner** · Force-Member-Edit / Force-Delete | A2/A3 |
|
||||
|
||||
*(AirCall-Setup + Anruf-Liste/-Detail → `D-REST`. HalloPetra-Adapter-UI/Whisper-Diktat → v2. Click-to-Call-Buttons leben in Kontakt-/Lead-/Projekt-Detail aus P6/P7/P8.)*
|
||||
*(AirCall-Setup + Anruf-Liste/-Detail → `D-REST`. HalloPetra-Adapter-UI → v2; Whisper-Diktat entfällt nach AD-26. Click-to-Call-Buttons leben in Kontakt-/Lead-/Projekt-Detail aus P6/P7/P8.)*
|
||||
|
||||
## Features (muss abgedeckt sein)
|
||||
- [ ] Chat-Real-Time: WebSocket, Presence, Typing, Read-Receipts, Optimistic-UI, Reconnect
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
|
||||
> 🟦 **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).
|
||||
|
||||
> 🟢 **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 v1 = **Meilisearch-Keyword** (pgvector/Hybrid → v2).
|
||||
> 🟢 **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)
|
||||
|
||||
@@ -19,7 +19,7 @@
|
||||
## Was wir bauen
|
||||
Die **Telefonie-Flächen von P15**: das AirCall-Setup (Connect-Card + User-Binding-Liste), die Anruf-Liste mit gematchtem Kontakt, Click-to-Call (inkl. Nummer-Auswahl-Modal + eingehender-Anruf-Notification) und das Anruf-Detail mit Match-Override + Markdown-Notiz.
|
||||
|
||||
> 🟡 **v1-Grenze:** **HalloPetra (M105) ist v2** (→ P33) — v1 baut nur den AirCall-Adapter hinter dem `TelephonyProviderInterface`. Whisper-Notiz-Diktat = v2 (Notiz-Editor = Markdown-Tippen in v1).
|
||||
> 🟡 **v1-Grenze:** **HalloPetra (M105) ist v2** (→ P33) — v1 baut nur den AirCall-Adapter hinter dem `TelephonyProviderInterface`. Whisper-Notiz-Diktat entfällt nach AD-26 (Notiz-Editor = Markdown-Tippen in v1).
|
||||
|
||||
## Benötigte Screens
|
||||
| Screen [Route] | Kern-Inhalt | Archetyp |
|
||||
@@ -27,14 +27,14 @@ Die **Telefonie-Flächen von P15**: das AirCall-Setup (Connect-Card + User-Bindi
|
||||
| **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) |
|
||||
| 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-/Deal-Detail (aus D-CRM/D-P7/D-P8) — Mehrfach-Nummern → Auswahl-Modal; `tel:`-Fallback ohne Connection.
|
||||
**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.
|
||||
|
||||
*(Chat-Index/Channel-/Thread-Detail/Pinned/Mentions/Suche/Neuer-Channel/Channel-Settings/Admin-Chat-Übersicht = **D-CHAT**. HalloPetra-Adapter-UI, Whisper-Diktat-Aufnahme → v2.)*
|
||||
*(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
|
||||
- [ ] User-Bindings mit Email-Auto-Match-Vorschlag + manuelle Zuordnung + „Verbindung testen"
|
||||
- [ ] Click-to-Call aus Kontakt-/Lead-/Deal-Detail; Mehrfach-Nummern → Auswahl-Modal; Klartext-Edge-Cases (kein Binding / keine Connection / API-Fehler / ungültige Nummer); `tel:`-Fallback
|
||||
- [ ] 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
|
||||
- [ ] Anruf-Liste + -Detail (Richtung/Dauer/verpasst), Markdown-Notiz-Editor nach Anruf, Recording-Player-Link, Match-Override
|
||||
- [ ] Empty/Loading/Permission-Denied/Offline-States (Klartext)
|
||||
|
||||
@@ -12,14 +12,14 @@
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `D-D0a` (App-Shell), `D-D0b` (Archetypen A2 Liste, A3 Detail, A4 Form, A5 Modal/Wizard, A6 Settings/Connection, A7 Zustände), `D-P5` (Connection-Card-Stil), `D-P4` (Task-Komponente — hier eingebettet, nicht neu)
|
||||
- **Bedient (Dev):** `AK-P16a` (Kalender-Sync Google), `AK-P16b` (Booking Slots/Verfügbarkeit/Storno), `AK-P16c` (Form-Builder Editor/Submission/Actions), `AK-P16d` (Angebot/Signatur PandaDoc)
|
||||
- **Bedient (Dev):** `AK-P16a` (Kalender-Sync Google), `AK-P16b` (Booking Slots/Verfügbarkeit/Storno), `AK-P16c` (Form-Builder Editor/Submission/Actions), `AK-P16d` (Angebot/Signatur SES-Default + BYOK-Adapter)
|
||||
- **Parallel/Geschwister:** `D-FORM` (Form-Builder-Canvas + öffentliches Formular) und `D-BOOK` (Booking-Page öffentlich + Kalender-View) — D-P16 liefert die Verwaltungs-/Settings-/Submissions-/Signatur-Flächen
|
||||
- **Subframe:** Pflicht je Route (A6 Connection/Settings, A2/A3 Listen/Detail, A4 Page-Editor, A5 Signatur-Wizard, A7 Zustände)
|
||||
|
||||
## Was wir bauen
|
||||
Die **Verwaltungs- und Workflow-Flächen von P16** (ohne die öffentlichen Bespoke-Seiten und den Form-Builder-Canvas): Kalender-Verbindungen + Sync-Settings, Buchungen-Liste/-Detail/-Page-Editor + Verfügbarkeit, Forms-Liste + Submissions-Ansicht und den Multi-Signer-Angebots-/Signatur-Wizard.
|
||||
|
||||
> 🟡 **v1-Schnitte (verbindlich):** Kalender-Sync nur **Google** (Outlook → v2, Interface bleibt agnostisch); Booking nur **eine** Zuteilungs-Strategie „Erster der frei ist" (Round-Robin/Provider-Wahl → v2); Signatur über **PandaDoc**. **Pivot:** Signatur hängt am **`Projekt`**-Kern (nicht „Deal") — `ProjektSignatureDocument`/`Signer`; Einstieg lebt im Projekt-Detail (P8/P9). Die Task-Komponente aus P4 (D-P4) wird eingebettet, nicht neu gebaut.
|
||||
> 🟡 **v1-Schnitte (verbindlich):** Kalender-Sync nur **Google** (Outlook → v2, Interface bleibt agnostisch); Booking nur **eine** Zuteilungs-Strategie „Erster der frei ist" (Round-Robin/Provider-Wahl → v2); Signatur über **gehärteten SES-Eigenbau als Default** (Fern-Link/OTP + Touch vor Ort + PAdES + Completion-Certificate), **PandaDoc nur optionaler BYOK-Adapter**. **Pivot:** Signatur hängt am **`Projekt`**-Kern (nicht „Deal") — `ProjektSignatureDocument`/`Signer`; Einstieg lebt im Projekt-Detail (P8/P9). Die Task-Komponente aus P4 (D-P4) wird eingebettet, nicht neu gebaut.
|
||||
|
||||
## Benötigte Screens
|
||||
| Screen [Route] | Kern-Inhalt | Archetyp |
|
||||
@@ -33,7 +33,7 @@ Die **Verwaltungs- und Workflow-Flächen von P16** (ohne die öffentlichen Bespo
|
||||
| Verfügbarkeit [`/availability`] | Wöchentliche Standard-Regeln (mehrere Zeitfenster/Tag), Datums-Ausnahmen (frei/Custom-Window), Timezone, Hinweis welche Booking-Pages zugreifen | A6 + A4 |
|
||||
| Forms-Liste [`/forms`] | Name, Subtyp, Status (Entwurf/Publiziert/Archiviert), Submissions-Anzahl, letzte Submission · SHK-Templates geseedet | A2 |
|
||||
| Submissions [`/forms/:id/submissions`] | Tabelle der Antworten (Spalten = Felder), Filter, CSV-Export · Detail: alle Antworten in Reihenfolge, Submitter-Metadata, Action-Log mit Status (Re-Run), File-/Foto-Vorschau, PDF-Export | A2 / A3 |
|
||||
| Signatur-Wizard [im Projekt-Detail] | PDF-Upload (aus Files oder neu) → Unterzeichner (Name vorausgefüllt aus Kontakt, Email, Rolle, Reihenfolge sequenziell/parallel) → Provider (PandaDoc, Default) → Senden · Status-Tracking je Unterzeichner (entwurf/gesendet/angesehen/signiert/abgelehnt) + Erinnerung + Widerruf · Original- + Signed-PDF-Download | A5 + A6 |
|
||||
| Signatur-Wizard [im Projekt-Detail] | PDF-Upload (aus Files oder neu) → Unterzeichner (Name vorausgefüllt aus Kontakt, Email, Rolle, Reihenfolge sequenziell/parallel) → Signaturmodus (Fern-Link/OTP oder Touch vor Ort; PandaDoc nur BYOK-Opt-in) → Senden · Status-Tracking je Unterzeichner (entwurf/gesendet/angesehen/signiert/abgelehnt) + Erinnerung + Widerruf · Original-, Signed-PDF- und Completion-Certificate-Download | A5 + A6 |
|
||||
|
||||
*(Form-Builder-Canvas + öffentliches Formular = **D-FORM**. Öffentliche Booking-Page + Kalender-Grid-View = **D-BOOK**. Lead-Inbox/Detail → P7. Plantafel/Projekt-Detail → P9. Sende-Domain-Card → P14. Integrations-Katalog/Connection-Setup → P5. Task-Komponente → P4.)*
|
||||
|
||||
@@ -42,11 +42,11 @@ Die **Verwaltungs- und Workflow-Flächen von P16** (ohne die öffentlichen Bespo
|
||||
- [ ] Buchungen-Liste (Tabs/Filter/Bulk-Cancel/CSV) + Buchung-Detail (held/no-show/Cancel mit Grund + Auto-Mail/Reschedule/Re-Assign)
|
||||
- [ ] Booking-Page-Editor (Dauer/Puffer/Vorlauf/Provider/Intake-Form/Bestätigungsmail/Publish/Embed-Code) + Pages-Liste + Verfügbarkeits-Editor
|
||||
- [ ] Forms-Liste + Submissions-Ansicht (Tabelle/Filter/CSV, Detail mit Action-Log + Re-Run + File-/Foto-Vorschau + PDF-Export)
|
||||
- [ ] Signatur-Wizard am Projekt (PDF-Upload → Unterzeichner → PandaDoc → Senden) + Status-Tracking je Unterzeichner + Erinnerung/Widerruf + Original-/Signed-PDF-Download
|
||||
- [ ] Signatur-Wizard am Projekt (PDF-Upload → Unterzeichner → SES-Signatur per Fern-Link/OTP oder Touch vor Ort; PandaDoc nur BYOK-Opt-in) + Status-Tracking je Unterzeichner + Erinnerung/Widerruf + Original-/Signed-PDF-/Completion-Certificate-Download
|
||||
- [ ] Empty/Loading/Fehler/Permission-Denied/Offline-States (Klartext + Lösungs-Knopf)
|
||||
|
||||
## UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)
|
||||
Connection-Card mit Status-Ampel + letzter-Sync-Zeit + verbundenem Konto-Email; Sync-Richtungs-Selector; Konflikt-Log-Liste mit Klartext + Resolution; Daten-Tabelle (sortierbar, paginiert) + Filter-Bar + Bulk-Action-Toolbar (Buchungen); Status-Badge mit Klartext-Tooltip; Reschedule-Slot-Picker; **Wochen-Verfügbarkeits-Editor** (mehrere Zeitfenster/Tag) + Ausnahmen-Editor (Datum + frei/Custom-Window); Embed-Code-Generator + QR-Generator + Copy-to-Clipboard (Booking-Page-Editor); **Post-Submit-Action-Log-Liste** mit Re-Run + Status; File-/Foto-Vorschau; PDF-Export-Button; **PDF-Upload-Dropzone**; **Unterzeichner-Liste** mit Reihenfolge + Rollen-Badge; **Status-Tracker je Unterzeichner** (entwurf/gesendet/angesehen/signiert/abgelehnt); PDF-Download-Buttons (Original/Signed); eingebettete Task-Komponente (aus D-P4); Empty-/Loading-/Fehler-/Permission-Denied-/Offline-States.
|
||||
Connection-Card mit Status-Ampel + letzter-Sync-Zeit + verbundenem Konto-Email; Sync-Richtungs-Selector; Konflikt-Log-Liste mit Klartext + Resolution; Daten-Tabelle (sortierbar, paginiert) + Filter-Bar + Bulk-Action-Toolbar (Buchungen); Status-Badge mit Klartext-Tooltip; Reschedule-Slot-Picker; **Wochen-Verfügbarkeits-Editor** (mehrere Zeitfenster/Tag) + Ausnahmen-Editor (Datum + frei/Custom-Window); Embed-Code-Generator + QR-Generator + Copy-to-Clipboard (Booking-Page-Editor); **Post-Submit-Action-Log-Liste** mit Re-Run + Status; File-/Foto-Vorschau; PDF-Export-Button; **PDF-Upload-Dropzone**; **Unterzeichner-Liste** mit Reihenfolge + Rollen-Badge; Signaturmodus-Switch (Fern-Link/OTP, Touch vor Ort, PandaDoc BYOK falls verbunden); **Status-Tracker je Unterzeichner** (entwurf/gesendet/angesehen/signiert/abgelehnt); PDF-Download-Buttons (Original/Signed/Certificate); eingebettete Task-Komponente (aus D-P4); Empty-/Loading-/Fehler-/Permission-Denied-/Offline-States.
|
||||
|
||||
## 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)
|
||||
|
||||
@@ -1,65 +1,90 @@
|
||||
# D-P20 · Screens P20 — Billing, Onboarding & Branding
|
||||
|
||||
> ⚠️ **KI→MCP-Pivot ([[AD-26]]):** Der **AI-Credits-Screen + AI-Token-Quota entfallen** (kein LLM-Gateway in v1 — HiveGrid wird MCP-Server, [[VR-MCP]]). Die Verbrauchs-Übersicht bleibt für Automation-Läufe + Speicher. Alle AI-Credits/AI-Token-Stellen unten sind durchgestrichen.
|
||||
> ⚠️ **Billing-Recut 2026-07-04 ([[AD-27]]):** v1-Billing nutzt **Lago self-hosted fuer Billing/Invoicing,
|
||||
> Mollie nur fuer Payments und HiveGrid fuer Entitlements**. Legacy-Provider-Customer-Portal, Payment-Checkout und
|
||||
> Legacy-Provider-Pricing sind kein Zielpfad mehr. v1 bleibt **Plans + Seats**, kein Usage-Billing.
|
||||
|
||||
> ⚠️ **KI→MCP-Pivot ([[AD-26]]):** Der **AI-Credits-Screen + AI-Token-Quota entfallen**. Die Verbrauchs-Übersicht
|
||||
> bleibt fuer Automation-Läufe und Speicher, aber nicht als abrechenbares Usage-Billing.
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Screen (Design) |
|
||||
| **Owner** | David |
|
||||
| **Phase** | P20 — Billing, Onboarding & Branding (bedient `AK-P20`) |
|
||||
| **Phase** | P20 — Billing, Onboarding & Branding (bedient `AK-P20`/`BILL-*`) |
|
||||
| **Cycle/Fenster** | W4 — USP, Härtung & Launch · 2026-07-08 · Gate W4 |
|
||||
| **Status** | geplant (NEU — ex-Teil von D-REST, jetzt eigenes P20-Ticket) |
|
||||
| **Status** | Recut noetig |
|
||||
|
||||
## 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` (Billing Stripe Abo-Baukasten + Onboarding + Branding)
|
||||
- **Compose-Paket:** Status-Banner-System integriert in die A1-Shell (D0); Hell/Dunkel-Toggle lebt im Profil/User-Menü (P2/D-P2); ~~AI-Credits-Detail teilt Charts-Bausteine mit D-P13~~ → **AI-Credits-Detail entfällt ([[AD-26]]; D-P13 gelöscht)**
|
||||
- **Bedient (Dev):** `AK-P20` fuer Onboarding/Branding/Frozen-Vorarbeit sowie `BILL-02` bis `BILL-06` fuer neue Billing-Architektur
|
||||
- **Subframe:** Pflicht je Route (A6 Settings, KPI/Charts, A5 Modal, Banner in A1-Shell)
|
||||
|
||||
## Was wir bauen
|
||||
Die **Billing-/Onboarding-/Branding-Flächen (alle v1)**: read-only Abo-Übersicht (Abo-Baukasten), Verbrauchs-Übersicht ~~/AI-Credits-Übersicht~~ (AI-Credits entfällt — [[AD-26]]), Stripe-Customer-Portal-Embed, Demo-Daten-Verwaltung, Erste-Schritte-Checkliste, das Tenant-Status-Banner-System und den Hell/Dunkel-Toggle.
|
||||
|
||||
Die **Billing-/Onboarding-/Branding-Flächen fuer v1**:
|
||||
|
||||
- read-only Abo-Übersicht mit Plan, Seats, Trial/Status und gebuchten Feature-Modulen
|
||||
- Rechnungen/Zahlung als Lago-/Mollie-basierte Status-/Dokumentansicht, nicht als Legacy-Provider-Portal-Embed
|
||||
- Verbrauchs-Übersicht fuer nicht abrechenbare Limits wie Automation-Läufe und Speicher
|
||||
- Demo-Daten-Verwaltung
|
||||
- Erste-Schritte-Checkliste
|
||||
- Tenant-Status-Banner-System
|
||||
- Hell/Dunkel-Toggle
|
||||
|
||||
> 🟡 **v1-Schnitte (verbindlich):**
|
||||
> - **Billing = Abo-Baukasten (M154-Recut):** Basis-Preis pro Nutzer + Feature-Module als daten-getriebene Positionen. **KEINE Seat-Typen.** In-App **keine** Pricing-/Upgrade-/Plan-Wechsel-UI (Apple-Compliance LP-8) — nur Read-Only-Übersicht + externer Verweis (`hivegrid.de`/Account-Manager). Pause/Kündigen erlaubt.
|
||||
> - **Onboarding:** v1 = Auto-SHK-Provisionierung beim Signup (ohne Wizard). **Kein** mehrstufiger Setup-Wizard, **kein** KI-Walkthrough (→ v2). v1-Screens: Demo-Daten-Verwaltung + Erste-Schritte-Checkliste.
|
||||
> - **Branding:** v1 = nur **Hell/Dunkel-Toggle** (bewusst 2 Optionen, **kein** System-Modus). Logo/Farben/White-Label → v2; keine `/admin/branding`-Route v1.
|
||||
> - **Billing:** Plans + Seats, read-only fuer Endkunden. Keine In-App Pricing-Tabelle, keine Upgrade-/Downgrade-UI,
|
||||
> kein Add-on-Metering, kein Usage-Billing.
|
||||
> - **Zahlung/Rechnung:** UI zeigt Status, letzte Rechnung/Invoice-Referenz, Payment-Status und Hilfe-/Kontaktweg.
|
||||
> 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.
|
||||
|
||||
## Benötigte Screens
|
||||
|
||||
| Screen [Route] | Kern-Inhalt | Archetyp |
|
||||
|---|---|---|
|
||||
| Abo-Übersicht [`/admin/subscription`] | Basis-Plan + **gebuchte Feature-Module als Positionsliste mit Preisen** · Status/Trial-Countdown · **KEIN Upgrade-Button** (Hinweis-Box „Plan-Wechsel über Account-Manager / hivegrid.de", extern) · Pausieren (Frozen) + Kündigen-Button | A6 + KPI |
|
||||
| Verbrauchs-Übersicht [`/admin/usage`] | Quota-Balken je Metrik: Automation-Läufe, ~~AI-Tokens~~ (entfällt [[AD-26]]), Speicher · aktueller Verbrauch vs. inklusiv · Klartext bei Limit-Erreichen | KPI + Charts |
|
||||
| ~~AI-Credits-Detail [`/admin/usage/ai-credits`]~~ → **entfällt ([[AD-26]])** | ~~Saldo, Verbrauch je Use-Case (Donut), Verlauf, 80%-Warnbanner, Hochrechnung, Aufgebraucht-Klartext (Verweis extern)~~ | ~~KPI + Charts~~ |
|
||||
| Rechnungen/Zahlung [`/admin/billing`] | **Stripe-Customer-Portal-Embed** (Rechnungs-History/PDF, Zahlungsmethode, Steuer-/USt-Daten) | A6 |
|
||||
| Demo-Daten [`/admin/onboarding/demo-data`] | **Settings-Knopf „Beispieldaten anlegen"** (~25 Datensätze, Klartext-Liste was kommt) · Demo-Liste mit Zähler + Lösch-Funktion (Multi-Step-Confirm) · „Demo ausblenden"-Filter erscheint in allen Listen *(kein Wizard, kein KI-Walkthrough — v2)* | A6 |
|
||||
| Erste-Schritte-Checkliste [`/onboarding/checklist`] | Items mit Status-Häkchen (auto-erkannt), Klartext + Beschreibung, CTA-Link je Item, manuell abhakbar, dauerhaft ausblendbar, Glückwunsch bei 100% (KWP-Item ausgeblendet — v2) · auch als Dashboard-Widget (P11) | A2 |
|
||||
| Status-Banner-System (Shell) | Tenant-Status-Banner: Trial-Ende-3-Tage / `past_due` (Zahlung fehlgeschlagen + „Zahlungsmethode aktualisieren") / `frozen` (pausiert + „Reaktivieren") / `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 (SSR-Cookie) *(kein System-Modus v1)* | A6 (Teil von Profil-Settings P2) |
|
||||
|
||||
*(Signup-Formular → P2/D-P2. Kein Onboarding-Setup-Wizard v1. Stripe-Checkout läuft extern über Marketing-Site.)*
|
||||
| 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 |
|
||||
|
||||
## Features (muss abgedeckt sein)
|
||||
- [ ] Abo-Übersicht read-only (Abo-Baukasten: Basis + Feature-Module als Positionen, **keine Seat-Typen**); **kein** In-App-Upgrade/Plan-Wechsel (LP-8) — externer Verweis; Pause/Kündigen erlaubt
|
||||
- [ ] Verbrauchs-Übersicht (Quota-Balken Automation-Läufe/~~AI-Tokens~~ (entfällt [[AD-26]])/Speicher, Klartext bei Limit)
|
||||
- [ ] ~~AI-Credits-Detail (Saldo, Donut je Use-Case, Verlauf, 80%-Warnbanner, Hochrechnung)~~ → **entfällt ([[AD-26]])**
|
||||
- [ ] Stripe-Customer-Portal-Embed (Rechnungs-History/PDF, Zahlungsmethode, Steuer-/USt-Daten)
|
||||
- [ ] 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)
|
||||
- [ ] Empty/Loading/Fehler/Permission-Denied-States (Klartext + Lösungs-Knopf)
|
||||
|
||||
- [ ] Abo-Übersicht read-only: Plan, Seats, Feature-Module, Status, Trial.
|
||||
- [ ] Kein Pricing-/Upgrade-/Downgrade-/Add-on-Kauf im v1-Kundenscreen.
|
||||
- [ ] Verbrauchs-Übersicht fuer Automation-Läufe/Speicher als Limit-Transparenz, nicht als Usage-Billing.
|
||||
- [ ] 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).
|
||||
- [ ] Empty/Loading/Fehler/Permission-Denied-States (Klartext + Lösungs-Knopf).
|
||||
|
||||
## UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)
|
||||
Plan-Positionsliste (Basis + Feature-Module mit Preisen, read-only); Trial-Countdown-Badge; KPI-/Quota-Balken (Verbrauch vs. inklusiv); ~~Donut-Chart (AI-Verbrauch je Use-Case)~~ (entfällt [[AD-26]]); 80%-Warnbanner; externer Verweis-Box („Plan-Wechsel über hivegrid.de", neuer Tab); Pause-Button + Kündigen-Button mit Bestätigungs-Modal; **Stripe-Customer-Portal-Embed** (iFrame/Redirect); Demo-Daten-Anlege-Knopf mit Klartext-Inhaltsliste; Demo-Zähler + Lösch-Button mit Multi-Step-Confirm; „Demo ausblenden"-Filter-Toggle; Checklisten-Items mit Status-Icon + CTA-Link + manuell-abhaken + ausblenden; **Status-Banner-Stack** (trial/past_due/frozen/deletion_pending) mit Action-Button; Read-Only-Toast bei blockiertem Schreib-Button; **Hell/Dunkel-Toggle** (2 Optionen); Empty-/Loading-/Fehler-/Permission-Denied-States.
|
||||
|
||||
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-/
|
||||
Fehler-/Permission-Denied-States.
|
||||
|
||||
## Quellen (granular)
|
||||
- `designer-briefs/P20-billing-onboarding-branding.md` (vollständiger Brief — alle v1-Screens)
|
||||
- `ENTITY-MODEL.md` → **Domäne 12** (Billing/Abo-Baukasten) + **Domäne 13** (Onboarding, Branding)
|
||||
- `ROADMAP.md` → Phase 20 · `REQUIREMENTS.md` → Modul 28/29/31 · `PHASE-SOURCES.md` → P20
|
||||
- `_bmad-output/specs/M28-subscriptions-billing.md` (⚠ M154-Recut — keine Seat-Typen), `M29-onboarding.md` (Wizard-UI → v2), `M31-branding.md`
|
||||
- Legacy-Referenz: `archive/hivegrid-cloud/app/config/pricing-plans.ts` · Dev-Pendant: `ticket-docs/AK-P20.md`
|
||||
|
||||
- `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
|
||||
- `ENTITY-MODEL.md` → Domäne 12/13, soweit nicht durch AD-27 ueberholt
|
||||
- Dev-Pendant: `AK-P20.md`
|
||||
|
||||
## Davids Delta (David füllt aus)
|
||||
|
||||
- [ ] Überschriebene/geänderte Spec-Punkte:
|
||||
- [ ] Neue UI/UX-Entscheidungen:
|
||||
- [ ] Subframe-Screen-Link(s):
|
||||
|
||||
@@ -27,7 +27,7 @@ Die **DSGVO-Lebenszyklus- und Launch-Reife-Screens (alle v1)**: Privacy-Hub, Ten
|
||||
|---|---|---|
|
||||
| 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-Löschung** [`/admin/privacy/deletion`, `/:requestId`] | Multi-Step: Erklärung (30-Tage-Grace, Read-Only, Hard-Delete) → Export-Angebot → Stripe-Hinweis (Pro-rata) → Passwort + 2FA → **Slug als Confirm-Phrase** · Grace-Countdown mit Abbruch-Button | A5 (Wizard) |
|
||||
| **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 |
|
||||
@@ -39,7 +39,7 @@ Die **DSGVO-Lebenszyklus- und Launch-Reife-Screens (alle v1)**: Privacy-Hub, Ten
|
||||
|
||||
## Features (muss abgedeckt sein)
|
||||
- [ ] DSGVO-ZIP-Export (User-Self **und** Tenant-Full) mit Progress + 72h-signed-URL + Rate-Limit-Hinweis
|
||||
- [ ] Tenant-Löschung (Multi-Step-Wizard, 30-Tage-Grace + Read-Only + Abbruch, **Slug als Confirm-Phrase**, Passwort + 2FA, Stripe-Pro-rata-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
|
||||
- [ ] In-App-Feedback-Widget (Bug/Feature/Frage, Screenshot-Häkchen, Rate-Limit) → Admin-Support-Inbox (P19)
|
||||
|
||||
@@ -24,7 +24,7 @@ Die **nutzerseitigen Plattform-Primitive**: Files (chunked Upload mit Multi-Date
|
||||
| Upload-View + Datei-Dropzone [`/files/upload`] | Drag&Drop, Multi-Datei-Queue mit Per-Datei-Fortschritt, Fehler+Retry · **HEIC-Hinweis „wird zu JPG konvertiert"** | A4 |
|
||||
| File-Detail [`/files/:id`] | Stammdaten · **Vorschau (Bild mit Zoom / PDF; HEIC→JPG)** mit Fallback-Klartext + Download bei `not_supported` · Tags · Notizen · verknüpfte Entitäten mit Rolle · Activity (Upload/Verknüpfungs-Änderungen/Downloads) · Aktionen Download/Ersetzen/Archiv/„Vorschau neu generieren" bei `failed` (kein Versionsverlauf v1) | A3 |
|
||||
| Task-Liste [`/tasks`] | Titel, Prioritäts-Marker, Fälligkeit (überfällig rot, relativ ≤7 T), verknüpfte Entität, Assignee (Person/Gruppe), Status, Quelle-Hinweis · Presets Meine/Erstellt/Alle (Alle nur mit `tasks.read_all`) · Such-Funktion · Filter (Status/Priorität/Deadline-Range/Verknüpfungs-Typ/Quelle) · Archiviert-Toggle · Bulk · Inline-Quick-Actions (done/Priorität/Deadline) | A2 — **wiederverwendbare Komponente** |
|
||||
| Task-Detail + Anlage-Modal [`/tasks/:id`, `/tasks/new`] | Titel, Beschreibung (Markdown), Status/Priorität/Fälligkeit inline, Assignee-Picker (Person↔Gruppe), Verknüpfungs-Picker (Auto-Complete Contact/Company/Lead/Deal/Project), Watcher, Quelle (manuell/Chat/Form/Automation mit Link), Activity-Stream, Aktionen (Erledigen/Wieder-öffnen/Duplizieren/Löschen) · Klartext-Banner (überfällig / Assignee deaktiviert / „wird in 30 Tagen archiviert") | A3 + A5 |
|
||||
| Task-Detail + Anlage-Modal [`/tasks/:id`, `/tasks/new`] | Titel, Beschreibung (Markdown), Status/Priorität/Fälligkeit inline, Assignee-Picker (Person↔Gruppe), Verknüpfungs-Picker (Auto-Complete Contact/Company/Lead/Projekt), Watcher, Quelle (manuell/Chat/Form/Automation mit Link), Activity-Stream, Aktionen (Erledigen/Wieder-öffnen/Duplizieren/Löschen) · Klartext-Banner (überfällig / Assignee deaktiviert / „wird in 30 Tagen archiviert") | A3 + A5 |
|
||||
|
||||
**Eingebettet (kein eigener Screen, aber zu designen):** Files-Browser vorgefiltert als Sub-Sektion in Entity-Detail-Views · Tasks-Tab/Section mit verknüpften Tasks + „Aufgabe anlegen" (Pre-Fill) in jeder Entity-Detail-View.
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `D-D0a` (App-Shell), `D-D0b` (Archetypen A6 Settings + Connection-Kit + Connection-Card, A5 Modal/Wizard, A2 Liste)
|
||||
- **Bedient (Dev):** `R-P5` (Apps-Engine / Adapter-Layer)
|
||||
- **Liefert wiederverwendbare Komponenten:** **Connection-Card** + **Setup-Wizard** + **Sync-History** sind das generische Framework, gegen das alle späteren App-Connections (P14 Email, P15 Telefonie, P16 Kalender/Signatur, P20 Stripe) registrieren — App-spezifische Setup-Teile kommen in den Modul-Phasen
|
||||
- **Liefert wiederverwendbare Komponenten:** **Connection-Card** + **Setup-Wizard** + **Sync-History** sind das generische Framework, gegen das alle späteren App-Connections (P14 Email, P15 Telefonie, P16 Kalender/Signatur, P20 Legacy-Provider) registrieren — App-spezifische Setup-Teile kommen in den Modul-Phasen
|
||||
- **Subframe:** Pflicht je Route (A6 Settings/Connection-Kit, A5 Wizard, A2 Liste)
|
||||
|
||||
## Was wir bauen
|
||||
|
||||
@@ -30,5 +30,7 @@ KWP ist das erste v2-Modul; die API-Anbindung in v2-P10 braucht registrierte Cal
|
||||
- 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.
|
||||
- **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**.
|
||||
|
||||
**Status:** **DoD 2/2 erfüllt — 100 %, Done.** Beide selbst-machbaren Punkte (melden + anstoßen) erledigt. Selbst machbar offen: 0.
|
||||
@@ -1,32 +1,51 @@
|
||||
# EXT-07 · Stripe-Konto + Live-Verifizierung
|
||||
# EXT-07 · Mollie-Testmode + Lago-Staging-Payment-Setup
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Setup (External) |
|
||||
| **Owner** | Raffael |
|
||||
| **Cycle/Fenster** | W1 — Fundament & Identität · fällig 2026-06-26 · Gate W1 |
|
||||
| **Status** | geplant |
|
||||
| **Cycle/Fenster** | Billing-Recut nach AD-27 · vor `BILL-04`/`BILL-07` |
|
||||
| **Status** | Recut / To Do |
|
||||
|
||||
## Recut-Hinweis
|
||||
|
||||
Dieses Ticket ersetzt den alten Legacy-Provider-Testmode-Pfad. Legacy-Provider ist nach `AD-27` nicht mehr Billing- oder
|
||||
Payment-Default. Der alte Legacy-Provider-Testmode-Stand bleibt nur historische Vorarbeit und darf nicht mehr als aktive
|
||||
Dependency fuer Billing bewertet werden.
|
||||
|
||||
Neuer Zielpfad:
|
||||
- **Lago-Staging** liefert Billing-/Invoice-/Subscription-Zustand.
|
||||
- **Mollie-Testmode** verarbeitet Zahlungen.
|
||||
- **HiveGrid** haelt Entitlements, Plan/Seat-State und Read-only/Frozen-State lokal.
|
||||
|
||||
## Was zu tun ist
|
||||
- **Stripe-Konto** anlegen, Geschäftsdaten + Bankkonto hinterlegen (ggf. Webseite-Anforderungen erfüllen).
|
||||
- **Test-Mode** für die Entwicklung aktivieren (eigene Keys je Umgebung, Staging = Test-Mode).
|
||||
- **Live-Verifizierung** einreichen — Bearbeitung dauert Tage, daher früh starten (Go-Live braucht Live-Keys).
|
||||
|
||||
- Mollie-Testaccount/Testmode vorbereiten und Test-Keys ausserhalb des Repos ablegen.
|
||||
- Mollie-Test-Webhooks fuer Staging planen oder dokumentieren, solange noch kein Public-Endpoint existiert.
|
||||
- Lago-Staging-Instanz aus `BILL-01` als Billing-Engine fuer Testdaten nutzen.
|
||||
- Testdaten-Konvention definieren, damit mehrere Staging-Flows dieselbe Lago-Staging-Instanz nicht vermischen.
|
||||
- Legacy-Provider-Testmode-Secrets als Legacy markieren und nicht mehr in neue Billing-Dokumentation aufnehmen.
|
||||
|
||||
## Warum / was es blockt
|
||||
Billing/Abo-Baukasten kann ohne verifiziertes Stripe-Live-Konto nicht produktiv schalten.
|
||||
- **Blocks:** P20 (Billing-Go-Live)
|
||||
|
||||
## Abhängigkeiten
|
||||
- **blocked-by:** —
|
||||
- **blocks:** P20
|
||||
Ohne Mollie-Testmode und Lago-Staging kann `BILL-04`/`BILL-07` nicht Ende-zu-Ende verifiziert werden.
|
||||
|
||||
- **Blocks:** `BILL-04`, `BILL-07`
|
||||
|
||||
## Abhaengigkeiten
|
||||
|
||||
- **blocked-by:** `BILL-00`, `BILL-01`
|
||||
- **blocks:** `BILL-04`, `BILL-07`
|
||||
|
||||
## Definition of Done
|
||||
- [x] Test-Mode für Dev aktiv — Stripe-Konto vorhanden, Test-Keys (`sk_test`/`pk_test`/`whsec`) in Coolify-Staging (`STRIPE_SK`, `STRIPE_WEBHOOK_SIGNING_SECRET`) + lokal `~/.cli-tokens/stripe-staging-env`
|
||||
- [→] Konto + Geschäftsdaten + Bankkonto — **Live-Teil ausgelagert nach [[EXT-16]]** (braucht Firmengründung)
|
||||
- [→] Live-Verifizierung eingereicht — **ausgelagert nach [[EXT-16]]**
|
||||
|
||||
## Umsetzung (2026-06-21, Owner Raffael)
|
||||
- Stripe-Test-Mode-Setup für Staging steht: Konto angelegt, Test-Keys in Coolify-Staging-Env verdrahtet (`STRIPE_SK`, `STRIPE_WEBHOOK_SIGNING_SECRET`) + lokal gesichert. Billing/Abo-Baukasten lässt sich gegen Test-Mode entwickeln.
|
||||
- **Live-Aktivierung (Geschäftsdaten + Bankkonto + Verifizierung + Live-Keys) nach [[EXT-16]] ausgelagert** — erst nach HiveGrid-Firmengründung machbar.
|
||||
- [ ] Mollie-Testmode-Konto/Profil steht fuer HiveGrid-Staging.
|
||||
- [ ] Mollie-Test-API-Key liegt ausserhalb des Repos in der vorgesehenen Secret-Ablage.
|
||||
- [ ] Webhook-/Callback-Strategie fuer Staging ist dokumentiert.
|
||||
- [ ] Lago-Staging-Testdaten-Konvention ist dokumentiert.
|
||||
- [ ] Legacy-Provider-Testmode-Setup ist als Legacy markiert und nicht mehr aktive Billing-Dependency.
|
||||
|
||||
**Status:** **Staging-Scope (Test-Mode) erfüllt — Done.** Live-Betrieb läuft als [[EXT-16]] (Backlog) weiter. Selbst machbar offen: 0.
|
||||
## Historischer Stand
|
||||
|
||||
2026-06-21 wurde Legacy-Provider-Testmode fuer Staging vorbereitet. Dieser Stand war fuer den alten Legacy-Provider-Pfad nuetzlich,
|
||||
ist aber nach `AD-27` abgeloest. Keine Plane-/Status-Aenderung allein aus dieser Doc vornehmen.
|
||||
@@ -9,7 +9,7 @@
|
||||
|
||||
## 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 Stripe/Google/PandaDoc gibt es **kein gratis Sandbox-Testen**:
|
||||
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.
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
| **Typ** | Architektur-Entscheidung / Setup |
|
||||
| **Owner** | Raffael |
|
||||
| **Cycle/Fenster** | v1 — Umsetzung in P16 (AK-P16d) |
|
||||
| **Status** | In Progress |
|
||||
| **Status** | Done (2026-06-28) — Entscheidungs-/Setup-Scope erfüllt; Bau ausgelagert nach AK-P16d |
|
||||
|
||||
## 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,
|
||||
@@ -41,10 +41,21 @@ trägt seinen Key ein (Opt-in). Abweichung vom Pflichtenheft (V.4.4 nannte Panda
|
||||
- **blocks:** P16 (AK-P16d)
|
||||
|
||||
## Definition of Done
|
||||
Dies ist ein **Entscheidungs-/Setup-Ticket** — „done" heißt: Provider-Frage geklärt + Architektur festgelegt. Die *Bau*-Umsetzung gehört bewusst nicht hierher (siehe unten).
|
||||
- [x] Signatur-Provider-Frage entschieden: **gehärtete SES-Eigenbau, kein externer Provider** ([[AD-25]])
|
||||
- [x] Modell + Architektur festgelegt (7-Punkte-Härtung, `defineAdapter`, AES/QES-Pfad offen)
|
||||
- [ ] Umsetzung in P16 (AK-P16d) — Touch + Fern-Link + OTP + PAdES-Versiegelung + Audit + Completion-Cert
|
||||
- [ ] (vor Go-Live) anwaltliche Bestätigung der Beweis-/Form-Einordnung (SES genügt, §650h→QES)
|
||||
|
||||
**Bewusst ausgelagert (nicht Teil dieses Tickets):**
|
||||
- → **Umsetzung in P16 (`AK-P16d`)** — Touch + Fern-Link + OTP + PAdES-Versiegelung + Audit + Completion-Cert. EXT-09 *blockt* AK-P16d; dort wird gebaut + abgehakt.
|
||||
- → **Go-Live-Gate (anwaltlich):** Bestätigung der Beweis-/Form-Einordnung (SES genügt, §650h→QES) läuft über [[EXT-03]] kurz vor Launch.
|
||||
|
||||
## Hinweis
|
||||
QES-Add-on (Bauvertragskündigung §650h) ist nach [[EXT-17]] ausgelagert (v2, via D-Trust). AES nur bei Bedarf später (Adapter).
|
||||
|
||||
## Umsetzungs-Notiz (2026-06-28)
|
||||
**Status: Done — 2/2 Entscheidungs-DoD grün = 100 % des Ticket-Scopes.** Die Provider-Frage ist mit [[AD-25]]
|
||||
abschließend entschieden (gehärtete SES-Eigenbau als Default, PandaDoc nur als optionaler BYOK-Adapter [[EXT-17]]),
|
||||
die Architektur steht (`defineAdapter` provider-agnostisch, `ses-selfhosted` + `pandadoc-byok`, AES/QES-Pfad offen
|
||||
ohne Fachcode-Umbau). PandaDoc-BYOK wurde im POC end-to-end validiert (siehe [[EXT-17]]). Die eigentliche
|
||||
SES-Bau-Arbeit (7-Punkte-Härtung) ist in **AK-P16d** verortet, das EXT-09 blockt — kein Doppel-Tracking hier.
|
||||
Plane-Titel von „PandaDoc-Sandbox (Provider-Wahl)" auf den realen Scope angeglichen.
|
||||
@@ -5,7 +5,7 @@
|
||||
| **Typ** | Setup (External) |
|
||||
| **Owner** | Raffael |
|
||||
| **Cycle/Fenster** | W3 — Kern-Kette & Kommunikation (Demo 2) · fällig 2026-06-29 · Gate W3 |
|
||||
| **Status** | geplant |
|
||||
| **Status** | On Hold (extern: Google/Microsoft-Konsolen) |
|
||||
|
||||
## Was zu tun ist
|
||||
- **Gmail-Restricted-Scope-Antrag** bei Google früh stellen (Wochen Vorlauf!) — für Postfach-Sync in v2.
|
||||
@@ -23,4 +23,19 @@ Diese Anträge brauchen Wochen Vorlauf, daher schon in W3 anstoßen, obwohl sie
|
||||
## Definition of Done
|
||||
- [ ] Gmail-Restricted-Scope-Antrag gestellt (Wochen Vorlauf!)
|
||||
- [ ] MS-Entra-App (Outlook/Graph → v2)
|
||||
- [ ] Google Play + FCM/APNs entfallen bestätigt — PWA-only, Push = Web-Push (VAPID, eigene Keys)
|
||||
- [x] Google Play + FCM/APNs entfallen bestätigt — PWA-only, Push = Web-Push (VAPID, eigene Keys)
|
||||
|
||||
## Umsetzungs-Notiz (2026-07-03, Raffael)
|
||||
|
||||
**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.
|
||||
- `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.
|
||||
|
||||
**Extern blockiert / nächste echte Aktionen:**
|
||||
- Google Cloud Console: Gmail-Restricted-Scope-Antrag für v2-Postfach-Sync stellen (`gmail.modify`/`gmail.send` bzw. finaler Minimal-Scope nach VA-P23-Implementierung). Erwartbar: Review und ggf. CASA-Assessment.
|
||||
- Microsoft Entra Admin Center: App Registration für Outlook/Graph anlegen, Redirect-URIs für Prod/Staging eintragen, Graph-Mail/Calendar-Scopes final wählen und Secret/Client-ID in Coolify-Secrets hinterlegen.
|
||||
|
||||
**Warum On Hold:** Ohne Zugriff auf die Google-/Microsoft-Konsolen kann ich die zwei externen DoD-Punkte nicht belastbar erledigen. Kein Code-Scope offen.
|
||||
@@ -1,35 +1,47 @@
|
||||
# EXT-16 · Stripe Prod / Live-Aktivierung
|
||||
# EXT-16 · Mollie Live + Billing Production Prep
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Setup (External) |
|
||||
| **Owner** | Raffael |
|
||||
| **Cycle/Fenster** | Backlog — erst nach HiveGrid-Firmengründung machbar |
|
||||
| **Cycle/Fenster** | Backlog · erst nach Sandbox-Proof und Firmierung |
|
||||
| **Status** | Backlog |
|
||||
|
||||
## Recut-Hinweis
|
||||
|
||||
Dieses Ticket ersetzt den alten Legacy-Provider-Live-Aktivierungspfad. Production-Billing laeuft nach `AD-27` ueber eine
|
||||
eigene Lago-Production-Instanz plus Mollie-Live-Zahlungen. Der konkrete Production-Schnitt wird in `BILL-08`
|
||||
vorbereitet.
|
||||
|
||||
## Was zu tun ist
|
||||
- **Stripe-Konto auf Live aktivieren:** Geschäftsdaten der gegründeten HiveGrid-Firma + Bankkonto hinterlegen,
|
||||
ggf. Webseite-/Impressum-Anforderungen erfüllen.
|
||||
- **Live-Verifizierung** bei Stripe einreichen (Bearbeitung dauert Tage → früh nach Gründung starten).
|
||||
- **Live-Keys** (`sk_live_…`, `pk_live_…`, Live-`whsec_…`) auf **Prod-Coolify** (web/api/worker-general) + lokal
|
||||
`~/.cli-tokens/` hinterlegen.
|
||||
- **Live-Webhook-Endpoint** in Stripe registrieren (Prod-URL) + Signing-Secret setzen.
|
||||
|
||||
- Mollie-Live-Profil nach Firmierung mit Geschaeftsdaten, Bankkonto und KYC-Unterlagen verifizieren.
|
||||
- Mollie-Live-Keys und Webhook-Endpoints fuer Production planen und erst nach Sandbox-E2E aktivieren.
|
||||
- Eigene `lago-production`-Instanz im HiveGrid-Prod-Setup vorbereiten, getrennt von `lago-staging`.
|
||||
- Rechnungssteller-/Steuer-/Impressumsdaten fachlich freigeben, bevor echte Rechnungen/Zahlungen live gehen.
|
||||
- Rollback-/Secret-Rotation-Pfad fuer Billing-Live-Betrieb dokumentieren.
|
||||
|
||||
## Warum / was es blockt
|
||||
Billing/Abo-Baukasten kann ohne verifiziertes Stripe-**Live**-Konto nicht produktiv schalten. Die Live-Aktivierung
|
||||
verlangt echte Geschäftsdaten + Bankkonto → erst nach der Firmengründung möglich.
|
||||
- **Blocks:** P20 (Billing-Go-Live)
|
||||
|
||||
## Abhängigkeiten
|
||||
- **blocked-by:** HiveGrid-Firmengründung (Geschäftsdaten + Bankkonto); [[EXT-07]] (Stripe-Konto + Test-Mode, erledigt)
|
||||
- **blocks:** P20
|
||||
Produktives Billing darf erst live gehen, wenn Sandbox-E2E, Firmierung, Mollie-Live-Verifizierung, Lago-Prod-Betrieb
|
||||
und Rechnungssteller-/Steuerfreigabe zusammenstehen.
|
||||
|
||||
- **Blocks:** `BILL-08`, produktives Self-Service-Billing
|
||||
|
||||
## Abhaengigkeiten
|
||||
|
||||
- **blocked-by:** `BILL-07`, Firmierung, Rechnungssteller-/Steuerentscheidung, Mollie-Live-Verifizierung
|
||||
- **blocks:** `BILL-08`
|
||||
|
||||
## Definition of Done
|
||||
- [ ] Stripe-Live-Konto verifiziert (Geschäftsdaten + Bankkonto)
|
||||
- [ ] Live-Keys auf Prod-Coolify (web/api/worker-general) + lokal hinterlegt
|
||||
- [ ] Live-Webhook-Endpoint registriert + Signing-Secret gesetzt
|
||||
|
||||
- [ ] 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.
|
||||
- [ ] Rechnungssteller-/Steuer-/Impressumsdaten freigegeben.
|
||||
- [ ] Backup, Restore, Monitoring und Rollback fuer Billing-Prod dokumentiert.
|
||||
|
||||
## Kontext
|
||||
Ausgelagert aus [[EXT-07]] (Stripe-Konto + Test-Mode für Staging, erledigt). Der Staging-/Dev-Pfad läuft im
|
||||
Test-Mode (Keys in Coolify-Staging). Dieses Ticket schaltet ausschließlich den produktiven Live-Betrieb frei,
|
||||
sobald die Firma gegründet ist.
|
||||
|
||||
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.
|
||||
@@ -8,14 +8,14 @@
|
||||
| **Status** | geplant |
|
||||
|
||||
## Was zu tun ist
|
||||
Sobald die Preise aus Raffaels Partner-Gespräch vorliegen (25.06.), das Founding-Member-Angebot strukturieren: **Early-Bird-Jahresdeal mit begrenzten Plätzen**. Konditionen, Leistungsumfang (v1-Scope ehrlich), Laufzeit und Verknappung sauber formulieren und von Noah abnehmen lassen. Vorlage für den Stripe Payment Link (`H-PAYLINK`).
|
||||
Sobald die Preise aus Raffaels Partner-Gespräch vorliegen (25.06.), das Founding-Member-Angebot strukturieren: **Early-Bird-Jahresdeal mit begrenzten Plätzen**. Konditionen, Leistungsumfang (v1-Scope ehrlich), Laufzeit und Verknappung sauber formulieren und von Noah abnehmen lassen. Vorlage fuer den freigegebenen Zahlungsweg (`H-PAYLINK`) liefern, ohne Legacy-Provider als neuen Produktpfad einzufuehren.
|
||||
|
||||
## Warum / Ziel
|
||||
Der Founding-Deal ermöglicht Geld **vor** dem Launch. Der 25.06. (Preise) ist der härteste Abhängigkeits-Termin — vorher nur qualifizieren, danach abschließen.
|
||||
|
||||
## Abhängigkeiten
|
||||
- **Blocked by:** `H-CALLS` (qualifizierte Pipeline), `EXT-14` (Preise/Stripe-Setup-Vorbereitung)
|
||||
- **Blocks:** `H-PAYLINK` (Payment Link)
|
||||
- **Blocked by:** `H-CALLS` (qualifizierte Pipeline), `EXT-14` (Preise/Angebot), Billing-Recut-Zahlungsweg aus `H-PAYLINK`
|
||||
- **Blocks:** `H-PAYLINK` (Zahlungsweg)
|
||||
|
||||
## Definition of Done
|
||||
- [ ] Early-Bird-Jahresdeal strukturiert (Konditionen, begrenzte Plätze, Laufzeit)
|
||||
|
||||
@@ -1,23 +1,38 @@
|
||||
# H-PAYLINK · Stripe Payment Link (Founding-Deal)
|
||||
# H-PAYLINK · Founding-Deal-Zahlungsweg ohne Legacy-Provider
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Vertrieb |
|
||||
| **Owner** | Haris (Stripe-Link von Raffael) |
|
||||
| **Cycle/Fenster** | W2 — Plattform & CRM (Demo 1) · fällig 2026-06-26 · Gate W2 |
|
||||
| **Status** | geplant |
|
||||
| **Owner** | Haris (Zahlungsweg von Raffael) |
|
||||
| **Cycle/Fenster** | W2/W4 · abhaengig von Billing-Recut |
|
||||
| **Status** | Recut / geplant |
|
||||
|
||||
## Recut-Hinweis
|
||||
|
||||
Mollie Payment Links sind nach `AD-27` nicht mehr der Zielpfad. Fuer den Founding-Deal darf kein neuer Legacy-Provider-Link als
|
||||
Produktionsweg aufgebaut werden. Bis `BILL-04`/`BILL-08` stehen, ist der saubere Weg entweder:
|
||||
|
||||
- ein Mollie-Test-/Live-Zahlungslink nach freigegebenem Setup, oder
|
||||
- eine manuelle Rechnung bzw. ein manuell freigegebener Zahlungsweg, sobald Rechnungssteller/Steuerdaten klar sind.
|
||||
|
||||
## Was zu tun ist
|
||||
Den Stripe Payment Link für den Founding-Deal (von Raffael bereitgestellt, 26.06.) in den Verkaufsprozess einbinden: Link auf das abgenommene Angebot (`H-FOUND`) abstimmen, testen und so bereitstellen, dass ein Interessent ab Mo 30.06. direkt bezahlen kann — **Geld fließt vor dem Launch**.
|
||||
|
||||
Den Zahlungsweg fuer den Founding-Deal auf das abgenommene Angebot (`H-FOUND`) abstimmen und so bereitstellen, dass
|
||||
Interessenten verbindlich zahlen koennen, ohne Legacy-Provider als neue Abhaengigkeit einzufuehren.
|
||||
|
||||
## Warum / Ziel
|
||||
Der Payment Link ist der konkrete Kassenknopf für den Founding-Deal. Ohne ihn keine Zahlung vor Launch — das Kern-Ziel "erste Gelder so früh wie möglich".
|
||||
|
||||
Der Founding-Deal braucht einen konkreten Abschlussweg. Der Weg muss aber zur neuen Billing-Architektur passen und darf
|
||||
kein Cloud-Act-/Legacy-Provider-Risiko wieder in den Produktpfad ziehen.
|
||||
|
||||
## Abhängigkeiten
|
||||
- **Blocked by:** `EXT-07` (Stripe-Setup), `EXT-14` (Preise/Produkt-Anlage)
|
||||
|
||||
- **Blocked by:** `EXT-14` (Preise/Angebot), `BILL-04` fuer Mollie-Testzahlung oder manuell freigegebener Rechnungsweg
|
||||
- **Blocks:** `H-DEMO` (Klick-Demos + Abschluss)
|
||||
|
||||
## Definition of Done
|
||||
- [ ] Founding-Deal-Payment-Link live und getestet
|
||||
- [ ] Link auf das von Noah abgenommene Angebot abgestimmt
|
||||
- [ ] Zahlung VOR Launch möglich (ab 30.06.)
|
||||
|
||||
- [ ] Zahlungsweg fuer Founding-Deal ist ohne Legacy-Provider festgelegt.
|
||||
- [ ] Zahlungsweg ist auf das abgenommene Angebot abgestimmt.
|
||||
- [ ] Testzahlung oder manuelle Zahlungsprobe ist dokumentiert.
|
||||
- [ ] Haris kann den Link bzw. Zahlungsprozess im Vertrieb verwenden.
|
||||
@@ -18,5 +18,9 @@ Demo 2 ist das zweite Wochen-Gate und beweist, dass die zentrale Wertschöpfungs
|
||||
- **Blocks:** —
|
||||
- Quellen: TIMELINE.md (Gate W3 / Demo 2)
|
||||
|
||||
> **Zulieferung aus R-P9b (Stand 2026-07-01):** Die serverseitige Lead→Sales→Auftrag-Kette
|
||||
> ist bis Plantafel/Abnahme vorbereitet. Commit: `6b6ca1fd9`. Für die Demo-Abnahme bleiben
|
||||
> die klickbaren/visuellen P9-Screens aus `D-PLAN`/`D-ABN`/`D-P9` der offene Blocker.
|
||||
|
||||
## Definition of Done
|
||||
- [ ] Kette Lead→Sales→Auftrag E2E validiert
|
||||
@@ -8,7 +8,7 @@
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | P11 — Globale Suche & Dashboard |
|
||||
| **Cycle/Fenster** | W4 — USP, Härtung & Launch · 2026-07-03 → 2026-07-04 · Gate W4 |
|
||||
| **Status** | geplant |
|
||||
| **Status** | On Hold |
|
||||
|
||||
> 🟢 **Kein Pivot-Sonderfall** (P11 ist nicht Teil der projekt-zentrischen Kern-Kette). Aber: Der Such-Index greift auf den **`Projekt`-Kern** zu — in der M24-Spec stehen `deal | project | order` als Typen; im Pivot-Modell ist das **EIN `Projekt`-Entity-Typ** (Pipeline-Typ = View, kein separater Index-Typ je Pipeline). v1 = **Meilisearch-Keyword-Suche**; ~~pgvector/Hybrid → v2 (AD-5 sequenziert) — embedding-Spalte/EmbeddingProviderJob sind nur Andock-Halter.~~ → **pgvector/Hybrid ruht ([[AD-26]]: RAG entfällt); embedding-Spalte/EmbeddingProviderJob bleiben ungenutzt.**
|
||||
|
||||
@@ -18,6 +18,13 @@
|
||||
- **Sequenz (Raffaels Kern-Kette):** nach abgeschlossener Kern-Kette (P6–P9). P11/P12/P13 folgen sequenziell.
|
||||
- **Läuft parallel zu:** Akeshans Module W4 (`AK-P20`/`AK-P21` Billing/DSGVO u.a.). Schema-Trennung nach **AD-21**.
|
||||
|
||||
> **Zulieferung aus R-P9b (Stand 2026-07-01, serverseitig umgesetzt):** Die Projekt-/Auftrags-Kern-Kette ist
|
||||
> serverseitig indexierbar: Plantafel (`ScheduleEntry`/`ScheduleConflict`), Abnahme
|
||||
> (`AbnahmeProtokoll`/`AbnahmeSignatur`) und Offline-Sync (`OfflineSyncMutation`) stehen
|
||||
> im typisierten Prisma-Schema, mit RLS/Tenant-Registry und Service-Routen bereit. Commit:
|
||||
> `6b6ca1fd9`. R-P9b bleibt wegen `D-PLAN`/`D-ABN`/`D-P9` screen-blockiert auf On Hold;
|
||||
> für den R-P11a-Backend-Ausbau sind die relevanten Contracts nutzbar.
|
||||
|
||||
## Was wir bauen
|
||||
Eine **permission-aware Keyword-Suche** über alle Entitäten via **Meilisearch** (SearchAdapter pro Modul, Outbox-Index-Updates), bedienbar per **Cmd+K-Modal** (global, debounced, gruppierte Treffer, Match-Highlight, RecentSearches) und als **Vollbild-Such-View** mit Filtern. Server-side Permission-Filter sorgt dafür, dass nie Treffer durchsickern.
|
||||
|
||||
@@ -28,12 +35,55 @@ Eine **permission-aware Keyword-Suche** über alle Entitäten via **Meilisearch*
|
||||
| Vollbild-Such-View [`/search`] | Such-Feld (URL-Param), volle Trefferliste (cursor-paginiert 50/Page) mit Metadaten; **Filter-Sidebar** (Entity-Typ/Erstellt-Range/Verantwortlicher/Tags/modul-spezifisch + Archiviert-Toggle); Trefferanzahl-Klartext; Sortierung (Relevanz/Letzte Aktivität/Erstellt) |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **Meilisearch-Keyword-Suche permission-aware** über **SearchAdapter** (Modul-Registrierung: Kontakt/Firma/Lead/**Projekt**/File/Task/User); ~~pgvector/Hybrid → v2~~ → ruht ([[AD-26]])
|
||||
- [ ] Entity-Mutationen aktualisieren den Index über **Outbox-Index-Pattern**; `SearchIndexEntry` + `RecentSearch` befüllt (5–10 s Index-Latenz mit Klartext-Hinweis)
|
||||
- [ ] **Cmd+K-Modal** (global Hotkey, debounced, gruppierte Treffer, Match-Highlight, Tastatur-Navigation, RecentSearches) + Wechsel in **Vollbild-Such-View** mit Filtern
|
||||
- [ ] **Server-side Permission-Filter** (nie durchsickern; Trefferanzahl = erlaubte Treffer; Klartext „weitere Treffer, die du nicht siehst")
|
||||
- [ ] Konnektor `tenantHasModule('search')` (Suche gated)
|
||||
- [ ] Permissions: `search.use`/`search.admin` (Suche leichtgewichtig — Sichtbarkeit über Modul-Permissions)
|
||||
- [x] **Meilisearch-Keyword-Suche permission-aware** über **SearchAdapter** (Modul-Registrierung: Kontakt/Firma/Lead/**Projekt**/File/Task/User); ~~pgvector/Hybrid → v2~~ → ruht ([[AD-26]])
|
||||
- [x] Entity-Mutationen aktualisieren den Index über **Outbox-Index-Pattern**; `SearchIndexEntry` + `RecentSearch` befüllt (5–10 s Index-Latenz mit Klartext-Hinweis)
|
||||
- [x] **Cmd+K-Modal** (global Hotkey, debounced, gruppierte Treffer, Match-Highlight, Tastatur-Navigation, RecentSearches) + Wechsel in **Vollbild-Such-View** mit Filtern
|
||||
- [x] **Server-side Permission-Filter** (nie durchsickern; Trefferanzahl = erlaubte Treffer; Klartext „weitere Treffer, die du nicht siehst")
|
||||
- [x] Konnektor `tenantHasModule('search')` (Suche gated)
|
||||
- [x] Permissions: `search.use`/`search.admin` (Suche leichtgewichtig — Sichtbarkeit über Modul-Permissions)
|
||||
|
||||
## Umsetzungs-Notiz
|
||||
|
||||
**2026-07-01 · Teilumsetzung R-P11a (3/6 DoD = 50 % done; selbst machbar offen: 3 Punkte).**
|
||||
|
||||
Proof:
|
||||
- Neues Search-Datenmodell `SearchIndexEntry`/`RecentSearch` in `prisma/schema/search.prisma`, RLS-Artefakt `prisma/rls/search-isolation.sql`, Tenant-Snapshot-Registry nachgezogen.
|
||||
- `search` als Entitlement/Modul-Key inklusive `tenantHasModule('search')`, Sidebar-Gate, `search.use`/`search.admin` in DefaultPermissions, Seed, Role-Display und Übersetzungen.
|
||||
- `@hivegrid/search` um `projects`-Index, Projekt-Registry und Worker-Bulk-Pager erweitert; `indexedEntities` enthält Kontakt/Firma/Lead/Projekt/File/Task/User.
|
||||
- App-Route `/search` + Resource-Route `/search/api` + Cmd+K-Live-Suche (300 ms debounce) integriert; serverseitiger Permission-Filter mit `read_all`/`read_own`-Owner-Filtern, Unit-Test gegen Treffer-Leak ergänzt.
|
||||
|
||||
Verifikation:
|
||||
- `pnpm typecheck`
|
||||
- `pnpm lint`
|
||||
- `pnpm verify:route-inventory`
|
||||
- `pnpm verify:cross-cutting-models`
|
||||
- `pnpm --filter @hivegrid/search test`
|
||||
- `pnpm --filter @hivegrid/entitlements test`
|
||||
- `pnpm --filter @hivegrid/web test -- app/services/search/globalSearch.server.test.ts app/components/ui/commandPalettes/CommandPalette.test.tsx app/components/core/roles/roleDisplay.test.ts app/utils/services/rolesAndPermissionsService.role-matrix.test.ts`
|
||||
- `pnpm --filter @hivegrid/worker typecheck`
|
||||
- `pnpm --filter @hivegrid/cli test -- src/commands/tenant/models.test.ts`
|
||||
|
||||
**2026-07-01 · Dev-Fertigstellung R-P11a (6/6 selbst machbare DoD = 100 % done; Ticket bleibt screen-blockiert auf On Hold).**
|
||||
|
||||
Proof:
|
||||
- Zentraler Search-Projektionshelper `apps/web/app/services/search/searchIndexProjection.server.ts` spiegelt `SearchIndexEntry` und publiziert `search.index.*`-Outbox-Events fuer Kontakt/Firma/Lead/Projekt/File/Task/User.
|
||||
- Live-Mutations verdrahtet: CRM-Kontakte inkl. Primaer-E-Mail/-Telefon, Leads inkl. Status/Bulk/Konvertierung, Projekte inkl. Stage/Undo/Konvertierung, Files inkl. Upload/Meta/Archiv/Delete, Tasks inkl. Status/Assignment/Archiv/Delete, TenantUser-Deaktivierung/Reaktivierung.
|
||||
- `crm-contacts`-Index unterscheidet `entityType` (`contact`/`company`/`lead`); Meilisearch-Abfragen nutzen tenant- und owner-scoped Filter fuer Own-Permissions. SQL-Fallback bleibt als robuste Rueckfallebene.
|
||||
- Cmd+K erweitert um Entity-Filter-Chips, RecentSearches im Leerlauf, Match-Highlight und gefilterten Wechsel in `/search`; Vollbildsuche zeigt ebenfalls Highlighting.
|
||||
|
||||
Verifikation:
|
||||
- `pnpm --filter @hivegrid/web typecheck`
|
||||
- `pnpm --filter @hivegrid/worker typecheck`
|
||||
- `pnpm lint`
|
||||
- `pnpm verify:route-inventory`
|
||||
- `pnpm verify:cross-cutting-models`
|
||||
- `pnpm --filter @hivegrid/search test`
|
||||
- `pnpm --filter @hivegrid/web test -- app/utils/services/tenantUserLifecycle.server.test.ts app/services/search/globalSearch.server.test.ts app/components/ui/commandPalettes/CommandPalette.test.tsx`
|
||||
- `pnpm --filter @hivegrid/worker test -- src/jobs/search-indexer.test.ts`
|
||||
|
||||
Offen:
|
||||
- Keine selbst machbaren Dev-Punkte offen.
|
||||
- Screen-/UI-Abnahme gegen `D-DASH` (Cmd+K + Vollbild-Such-View) offen; Ticket bleibt deshalb in Plane auf `Blocked / On Hold`, nicht `Done`.
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (eigene `prisma/schema/search.prisma`): `SearchIndexEntry` (entity_type/id, title, body_text, tsvector_de, **~~embedding [pgvector → v2-Andock-Halter]~~ → ruht, ungenutzt ([[AD-26]])**, permission_subject, is_archived), `RecentSearch` (query_text/applied_filters/result_count), ~~`EmbeddingProviderJob` (async, Inhalt v2)~~ → ruht ([[AD-26]]). Modul-`.prisma`s nur über polymorphe Referenz (AD-21).
|
||||
@@ -53,4 +103,4 @@ Eine **permission-aware Keyword-Suche** über alle Entitäten via **Meilisearch*
|
||||
## Dev-Nachzug (nach Davids `D-DASH`-Delta)
|
||||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
- [ ] Plane-Ticket `R-P11a` aktualisiert
|
||||
- [x] Plane-Ticket `R-P11a` aktualisiert
|
||||
@@ -8,7 +8,7 @@
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | P11 — Globale Suche & Dashboard |
|
||||
| **Cycle/Fenster** | W4 — USP, Härtung & Launch · 2026-07-04 → 2026-07-05 · Gate W4 |
|
||||
| **Status** | geplant |
|
||||
| **Status** | On Hold (technische Basis umgesetzt, wartet auf `D-DASH`) |
|
||||
|
||||
> 🟢 **Kein Pivot-Sonderfall.** Aber: Dashboard-Widgets greifen auf den **`Projekt`-Kern** zu (nicht getrennte Deal-/Project-Entitäten). **v1 = nur 3 feste Rollen-Layouts (GF/Büro/Monteur) ohne Drag&Drop** (Scope-Schnitt 12.06.; User-Layout-Persistenz + Custom-Widgets + Export → v2). Die **Widget-Registry wird voll gebaut** (Inversion M064→M147).
|
||||
|
||||
@@ -28,12 +28,16 @@
|
||||
| Dashboard-Switcher [im Header] | Verfügbare Dashboards (rollen-gematcht) + Default-Routing nach Rolle |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **3 feste Rollen-Layouts** (GF/Büro/Monteur, SHK-Default **geseedet**) aus Widget-Katalog
|
||||
- [ ] **Widgets** aus Sales/Projekte/Tasks/HR/~~KI~~ (entfällt [[AD-26]])/Activity/Comms; **Widget-Registry voll gebaut** (Custom-Widgets/Drag&Drop → v2)
|
||||
- [ ] **Live-Update** (WebSocket/SSE) mit **Aggregat-Cache** + Lazy-Load/Skeleton; Widgets permission-gegated (Quellen-Modul-Permission); Monteur-Dashboard mobile-first
|
||||
- [ ] Dashboard-Switcher + rollenbasiertes Default-Routing
|
||||
- [ ] Konnektor `tenantHasModule('dashboard')` (Dashboard gated)
|
||||
- [ ] Permissions: `dashboard.read/customize` (v1: nur Filter/Zeitraum; Drag&Drop-Customize → v2)
|
||||
- [x] **3 feste Rollen-Layouts** (GF/Büro/Monteur, SHK-Default **geseedet**) aus Widget-Katalog
|
||||
- [x] **Widgets** aus Sales/Projekte/Tasks/HR/~~KI~~ (entfällt [[AD-26]])/Activity/Comms; **Widget-Registry voll gebaut** (Custom-Widgets/Drag&Drop → v2)
|
||||
- [x] **Live-Update** (WebSocket/SSE) mit **Aggregat-Cache** + Lazy-Load/Skeleton; Widgets permission-gegated (Quellen-Modul-Permission); Monteur-Dashboard mobile-first
|
||||
- [x] Dashboard-Switcher + rollenbasiertes Default-Routing
|
||||
- [x] Konnektor `tenantHasModule('dashboard')` (Dashboard gated)
|
||||
- [x] Permissions: `dashboard.read/customize` (v1: nur Filter/Zeitraum; Drag&Drop-Customize → v2)
|
||||
|
||||
## Umsetzungsnotiz
|
||||
|
||||
**2026-07-01:** Technische Basis auf `main` vorbereitet: Prisma-Modelle `Dashboard`/`DashboardLayout`/`WidgetInstance` inkl. RLS-Artefakt, `dashboard`-Entitlement, `dashboard.read`/`dashboard.customize`, Sidebar-Gating, `/dashboard`-Loader mit rollenbasiertem Switcher, serverseitige Widget-Registry und `/dashboard/stream` als SSE-Snapshot-Route. Widget-Daten werden permission-gegated aus vorhandenen Quellen gelesen, inkl. Pipeline-Aggregaten, Projekten, Tasks, HR-Anträgen, Activity, Calls, Terminen und offenen Mängeln. Verifikation: `pnpm typecheck`, `pnpm lint`, `pnpm prisma validate`, `pnpm test`, gezielte R-P11b-Tests und `git diff --check` grün. Plane-Kommentar geschrieben und Ticket auf `Blocked / On Hold` gesetzt. **DoD: 6/6 technische Punkte = 100 % selbst machbar erledigt. Extern blockiert:** finaler Screen-Abgleich und visuelle Integration mit Davids `D-DASH`-Paket. Ticket bleibt deshalb **On Hold**, nicht Done.
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (eigene `prisma/schema/dashboard.prisma`): `Dashboard` (name, is_default_for_role gf/office/monteur, is_shared), `DashboardLayout` (dashboard_id, user_id NULL=shared, widgets[], layout_data — 3 feste Rollen-Layouts v1), `WidgetInstance` (widget_catalog_key, config, position, size — Custom/Drag&Drop v2). Aggregat-Cache auf Quell-Module über deren `.prisma` nur lesend (AD-21).
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | P12 — Automation-Engine (USP-Säule 1) |
|
||||
| **Cycle/Fenster** | W4 — USP, Härtung & Launch · 2026-07-06 → 2026-07-07 · Gate W4 |
|
||||
| **Status** | geplant |
|
||||
| **Status** | On Hold (Screens `D-FLOW`/`D-P12` fehlen) |
|
||||
|
||||
> 🟢 **Kein Pivot-Sonderfall** (P12 ist USP, nicht Teil der projekt-zentrischen Kern-Kette) — aber Trigger/Actions arbeiten auf dem `Projekt`-Kern. 🟡 **v1-Grenze:** KWP-Push-Action ist nur ein **erweiterbarer Registry-Eintrag** (zieht mit v2 nach) — kein KWP-Konfig-UI in v1.
|
||||
|
||||
@@ -30,13 +30,19 @@ Den **Engine-Unterbau** der ersten USP-Säule: eine **vollständige Trigger-Libr
|
||||
*(Trigger-/Action-Library = Daten im Knoten-Katalog, kein eigener Screen. Flow-Editor selbst → R-P12b.)*
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **Vollständige Trigger-Library** über alle Module (CRM, Lead, Sales, Projekte, Email, Forms, Booking, Kalender, Zeit, Webhook) im Knoten-Katalog gruppiert
|
||||
- [ ] **Erweiterbare Action-Library** (CRM, Notification, HTTP, Task, If/Else, Delay, Loop) + Registry — **KWP-Push + KI-Actions docken später an** (kein v1-Konfig-UI)
|
||||
- [ ] **Schutz:** Loop-Guard (Abhängigkeits-Graph-Warnung), Rate-Limit + Anomalie-Pause, Idempotenz-Key, **Trigger-Volumen-Metering pro Tenant**, Resume-ab-Schritt mit Auto-Retry
|
||||
- [ ] Klartext-Diagnostik in allen Execution-Logs (Step-Status, Dauer, Input/Output)
|
||||
- [ ] Datenmodell persistiert: **`AutomationRule`/`AutomationRuleStep`/`AutomationExecution`/`AutomationStepExecution`** (+ Credential/Template)
|
||||
- [ ] Plattform- + Tenant-Templates mit Katalog und „aus Rule erstellen" (Backend)
|
||||
- [ ] Konnektor `tenantHasModule('automation')` (Engine/Routes/Actions gated)
|
||||
- [x] **Vollständige Trigger-Library** über alle Module (CRM, Lead, Sales, Projekte, Email, Forms, Booking, Kalender, Zeit, Webhook) im Knoten-Katalog gruppiert
|
||||
- [x] **Erweiterbare Action-Library** (CRM, Notification, HTTP, Task, If/Else, Delay, Loop) + Registry — **KWP-Push + KI-Actions docken später an** (kein v1-Konfig-UI)
|
||||
- [x] **Schutz:** Loop-Guard (Abhängigkeits-Graph-Warnung), Rate-Limit + Anomalie-Pause, Idempotenz-Key, **Trigger-Volumen-Metering pro Tenant**, Resume-ab-Schritt mit Auto-Retry
|
||||
- [x] Klartext-Diagnostik in allen Execution-Logs (Step-Status, Dauer, Input/Output)
|
||||
- [x] Datenmodell persistiert: **`AutomationRule`/`AutomationRuleStep`/`AutomationExecution`/`AutomationStepExecution`** (+ Credential/Template)
|
||||
- [x] Plattform- + Tenant-Templates mit Katalog und „aus Rule erstellen" (Backend)
|
||||
- [x] Konnektor `tenantHasModule('automation')` (Engine/Routes/Actions gated)
|
||||
|
||||
## Umsetzungs-Notiz
|
||||
- **2026-07-02:** Serverseitiger R-P12a-Unterbau umgesetzt: `prisma/schema/automation.prisma` + RLS, Automation-Knoten-/Template-Registry, Loop-/Volume-/Retry-/Idempotency-Guards, verschlüsselte Credentials, Template-Seeding, Rule-aus-Template, Tenant-Template-aus-Rule, Execution-Start mit Metering/Step-Logs, Entitlements/Permissions, Sidebar/Route-Wiring und Basis-Routen fuer Liste/Execution-Liste/Execution-Detail.
|
||||
- **Proof:** `pnpm typecheck`; `pnpm exec prisma validate`; `pnpm vitest run apps/web/app/services/automation/automation.registry.test.ts packages/entitlements/src/features.test.ts packages/entitlements/src/plans.test.ts packages/entitlements/src/blueprints.test.ts packages/cli/src/commands/tenant/models.test.ts scripts/verify-route-inventory.test.mjs apps/web/app/application/sidebar/AppSidebar.test.tsx apps/web/app/application/ui/uiInventory.test.ts apps/web/app/components/core/roles/roleDisplay.test.ts`.
|
||||
- **Plane:** Kommentar mit Proof hinterlegt; Ticket auf `Blocked / On Hold` gesetzt.
|
||||
- **DoD-Stand:** 7/7 technische DoD = 100 % serverseitig. Extern blockiert bleibt die visuelle Endabnahme bzw. Screen-Anpassung durch Davids `D-FLOW`/`D-P12`; Ticket bleibt deshalb **On Hold**, nicht Done.
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (eigene `prisma/schema/automation.prisma`): `AutomationRule` (name, flow_data JSON, enabled, created_via), `AutomationRuleStep` (step_kind trigger|condition|action|flow_control, node_type, config, parent_step_ids[] — Graph-Knoten), `AutomationExecution` (trigger_payload, status, dry_run, idempotency_key, **reverse_window_expires_at**), `AutomationStepExecution` (input/output, summary_text), `AutomationCredential` (**[verschlüsselt]**), `AutomationTemplate` (flow_data, category, is_published — SHK-Vorlagen). Andere Modul-`.prisma`s nur über Trigger/Action-Adapter (AD-21).
|
||||
@@ -56,4 +62,4 @@ Den **Engine-Unterbau** der ersten USP-Säule: eine **vollständige Trigger-Libr
|
||||
## Dev-Nachzug (nach Davids `D-FLOW`/`D-P12`-Delta)
|
||||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
- [ ] Plane-Ticket `R-P12a` aktualisiert
|
||||
- [x] Plane-Ticket `R-P12a` aktualisiert
|
||||
@@ -8,12 +8,13 @@
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | P12 — Automation-Engine (USP-Säule 1) |
|
||||
| **Cycle/Fenster** | W4 — USP, Härtung & Launch · 2026-07-07 → 2026-07-08 · Gate W4 |
|
||||
| **Status** | geplant |
|
||||
| **Status** | On Hold (Screens `D-FLOW`/`D-P12` fehlen) |
|
||||
|
||||
> 🔴 **Schwerste UI der App (AD-16, ab 22.06. täglich 1h).** Der visuelle Flow-/Node-Editor ist die erste USP-Säule und vollständig **bespoke**. Klartext-First überall (Knoten-Labels, Dry-Run-Ausgaben, Loop-/Rate-Warnungen, Logs in verständlichem Deutsch). ~~🟡 Sprach-zu-Automation rendert hier den Flow-Vorschlag — die KI-Pipeline selbst liegt in P13 (R-P13 liefert das Gateway dahinter).~~ → **entfällt ([[AD-26]]).**
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `R-P12a` (Engine + Trigger/Action-Registry + Guards), `D-FLOW` (Flow-Editor-Design)
|
||||
- **Stand 2026-07-02:** R-P12a ist serverseitig umgesetzt und technisch nutzbar; blockierend fuer R-P12b bleiben die fehlenden `D-FLOW`/`D-P12`-Screens und die visuelle Editor-Endabnahme.
|
||||
- **Blocks:** ~~`R-P13` (KI-Layer / Sprach-zu-Automation-Gateway)~~ → **entfällt ([[AD-26]]: R-P13 gelöscht); R-P12b ist letztes v1-Glied.**
|
||||
- **Sequenz (Raffaels Kern-Kette):** sequenziell (`R-P12a → R-P12b`) ~~`→ R-P13`~~ — **R-P12b ist das Ketten-Ende ([[AD-26]]).**
|
||||
- **Läuft parallel zu:** Akeshans Module W4. Schema-Trennung nach **AD-21**.
|
||||
@@ -30,13 +31,19 @@ Den **visuellen Graph-/Node-Editor** über der Engine aus P12a: Knoten aus Trigg
|
||||
| Template-Katalog [`/automations/templates`] | SHK- + Tenant-Vorlagen nach Kategorie; je Template Beschreibung/Use-Case/Nutzungs-Anzahl; „Verwenden" + „Eigenes Template aus Rule anlegen" |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **Graph-Editor** aus Trigger/Action-Library: Knoten hinzufügen/konfigurieren/löschen/duplizieren, Kanten erstellen/löschen, verschieben, **Auto-Layout, Undo/Redo, Mini-Map**
|
||||
- [ ] **Klartext-Knoten-Labels** + Klartext-Validation (unverbunden, Cycle, unvollständig)
|
||||
- [ ] **Dry-Run-Vorschau** (Klartext-Wirkungsvorschau, getroffene Datensätze + Beispiele) + **Bestätigungs-Pflicht ab Schwelle**
|
||||
- [ ] **24h-Undo-Fenster:** angelegte Entitäten löschen / Status zurücksetzen / Tags rückgängig, Mail-Empfängerliste anzeigen (nicht zurückziehbar), Multi-Step-Confirm + Audit
|
||||
- [ ] ~~**Sprach-zu-Automation-Andock:** Satz → Flow-Vorschlag mit Rückfragen/Existenz-Prüfung/Risiko-Hinweisen, **Bestätigungs-Pflicht (Action-Boundary, nie Auto-Aktivierung)** — KI-Pipeline = R-P13~~ → **entfällt ([[AD-26]]: kein LLM in v1)**
|
||||
- [ ] Template-Katalog mit „aus Rule erstellen"
|
||||
- [ ] Konnektor `tenantHasModule('automation')` (Editor/Routes gated)
|
||||
- [ ] **Graph-Editor** aus Trigger/Action-Library: Knoten hinzufügen/konfigurieren/löschen/duplizieren, Kanten erstellen/löschen, verschieben, **Auto-Layout, Undo/Redo, Mini-Map** — technisch teilweise umgesetzt (Add/Delete/Duplicate/Connect/Disconnect/Auto-Layout/Undo/Redo + minimale Route); final offen: Canvas, Drag-Move, Mini-Map, Konfig-Panel nach `D-FLOW`.
|
||||
- [x] **Klartext-Knoten-Labels** + Klartext-Validation (unverbunden, Cycle, unvollständig)
|
||||
- [x] **Dry-Run-Vorschau** (Klartext-Wirkungsvorschau, getroffene Datensätze + Beispiele) + **Bestätigungs-Pflicht ab Schwelle**
|
||||
- [ ] **24h-Undo-Fenster:** angelegte Entitäten löschen / Status zurücksetzen / Tags rückgängig, Mail-Empfängerliste anzeigen (nicht zurückziehbar), Multi-Step-Confirm + Audit — Reverse-Plan + Confirm-Phrase umgesetzt; echte destructive Reverse-Adapter/Audit-Ausführung offen, sobald Action-Side-Effects konkret verdrahtet sind.
|
||||
- [x] ~~**Sprach-zu-Automation-Andock:** Satz → Flow-Vorschlag mit Rückfragen/Existenz-Prüfung/Risiko-Hinweisen, **Bestätigungs-Pflicht (Action-Boundary, nie Auto-Aktivierung)** — KI-Pipeline = R-P13~~ → **entfällt ([[AD-26]]: kein LLM in v1)**
|
||||
- [x] Template-Katalog mit „aus Rule erstellen"
|
||||
- [x] Konnektor `tenantHasModule('automation')` (Editor/Routes gated)
|
||||
|
||||
## Umsetzungs-Notiz
|
||||
- **2026-07-02:** R-P12b ohne Screens technisch maximal vorgezogen: reiner Editor-Kern (`automation.editor.ts`) fuer Flow-Normalisierung, Graph-Operationen, Cycle-/Reachability-/Unvollständig-Validation, Undo/Redo-History, Auto-Layout, Dry-Run-Preview mit Schwellenwert-Confirm und 24h-Reverse-Plan. Server-Wiring in `automation.server.ts` fuer Editor-VM, Save/Activate/Pause/Dry-Run/Template-aus-Rule und Template-aus-Platform-Template. Neue Routen: `/automations/:id/edit` und `/automations/templates`; bestehendes Execution-Detail zeigt Reverse-Plan.
|
||||
- **Proof:** `pnpm typecheck`; `pnpm exec prisma validate`; `pnpm lint`; `pnpm vitest run apps/web/app/services/automation/automation.editor.test.ts apps/web/app/services/automation/automation.registry.test.ts scripts/verify-route-inventory.test.mjs apps/web/app/application/sidebar/AppSidebar.test.tsx`.
|
||||
- **Plane:** Kommentar mit Proof hinterlegt; Ticket auf `Blocked / On Hold` gesetzt.
|
||||
- **DoD-Stand:** 4/6 aktive DoD-Punkte vollständig erledigt = ~67 % done. Zusätzlich sind 2/6 Punkte technisch teilweise erledigt, aber final blockiert durch `D-FLOW`/`D-P12` bzw. echte Reverse-Adapter/Audit-Ausführung. Sprach-Andock ist per AD-26 erledigt/entfallen und wird nicht als offener v1-Punkt gezählt. Ticket bleibt **On Hold**, nicht Done.
|
||||
|
||||
## Technische Bausteine
|
||||
- **Erweitert `prisma/schema/automation.prisma`** (keine neuen Kern-Entities — Editor persistiert `flow_data` JSON + `AutomationRuleStep`-Graph aus R-P12a; Template-CRUD).
|
||||
@@ -58,4 +65,4 @@ Den **visuellen Graph-/Node-Editor** über der Engine aus P12a: Knoten aus Trigg
|
||||
## Dev-Nachzug (nach Davids `D-FLOW`/`D-P12`-Delta)
|
||||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
- [ ] Plane-Ticket `R-P12b` aktualisiert
|
||||
- [x] Plane-Ticket `R-P12b` aktualisiert
|
||||
@@ -0,0 +1,158 @@
|
||||
# R-P14C-T2 · Entity-Builder-native Module typisiert ablösen (Teil 2) — Übersicht
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Dev (Code) — **Meta/Übersicht** (verteilt auf Child-Tickets) |
|
||||
| **Owner** | Raffael (+ Agent) |
|
||||
| **Phase** | P6 / P14 (Entity-Builder-Ablösung, AD-2) |
|
||||
| **Plane** | neu · Teil 2 von `R-P14C` (#169) |
|
||||
| **Status** | **ENTSCHIEDEN (Raffael 2026-06-30, §Abnahme):** `R-P14D` (+`R-P14F`) baubar · `R-P14E`+`R-P14G` = Cut mit β |
|
||||
|
||||
> **Diese Datei ist die Übersicht.** Die eigentlichen Bau-Tickets sind die Child-Docs `R-P14D` (WorkflowEngine), `R-P14E` (formulas), `R-P14F` (onboarding), `R-P14G` (codeGenerator). Hier steht das gemeinsame Problem, die geteilte Vorbedingung und die zentrale offene Entscheidung, die alle vier blockiert.
|
||||
|
||||
## Kontext (warum dieses Ticket existiert)
|
||||
`R-P14C` (Teil 1, **fertig** auf Branch `feat/R-P14C`) hat **EmailMarketing** typisiert und den `CrmService`-Legacy-Reader entfernt (Variante A — Editor entfernt, nicht migriert). Damit ist der **erste** Schritt der R-P6B-Migrationskette durch. **Teil 2** nimmt die übrigen, in R-P6B §Rückwirkungs-Audit gelisteten gebauten Entity-Builder-Konsumenten dran, damit anschließend **R-P6B-β** (`EntitiesSingleton`-Removal + `modules/rows`/`utils/db/entities` + `entityBuilder.prisma` löschen) entsperrt werden kann.
|
||||
|
||||
## Befund aus dem Teil-2-Audit (2026-06-30)
|
||||
Anders als EmailMarketing (peripherer Konsument) sind diese vier Module **im Kern Entity-Builder-Maschinerie** — sie konsumieren den Builder nicht nur, sie operieren auf dem *generischen Entity-Begriff*:
|
||||
|
||||
| Modul | Was es im Kern tut | EB-Berührung (nicht-Test) | Routen-Status | Größe |
|
||||
|---|---|---|---|---|
|
||||
| **workflowEngine** | Pro-Blöcke `rowGet/rowCreate/rowUpdate/rowDelete` CRUDen **beliebige generische Entities** per Name (`EntitiesSingleton.getEntity` + `RowsApi`) | 2 Dateien (`WorkflowBlockProService`, `WorkflowsTemplatesService`) | Public-Slug disabled, `admin/__workflows/**` disabled, `app.$tenant/__workflows/**` registriert (nav-versteckt) | **L** |
|
||||
| **formulas** | Formel-Evaluation **über Entity/Property/Row** (`RowHelper.getPropertyValue`, `getAllEntities`) | 3 Dateien (`FormulaService`, `FormulaRowService`, `FormulaVariableValueDto`) | lebt in `admin/entities/**` + `settings/entities/**` (= EB-UI, die β löscht) | **M** |
|
||||
| **codeGenerator** | **generiert Code AUS Entity-Definitionen** (Prisma/DTO/Routes-Templates) — Meta-Werkzeug | 27 von 29 (Template-Input `EntityWithDetails`) | nur `admin/entities/code-generator/**` (EB-Admin) | **M** (aber Sonderfall, s.u.) |
|
||||
| **onboarding** | `getAllEntities` (Onboarding-Config) + `RowsApi.count` (Filter-Vorschau) | 2 Dateien (`OnboardingService`, `OnboardingFiltersService`) | Slug disabled; `admin/onboarding/**` + public `/onboarding/$id` | **S–M** |
|
||||
|
||||
**Belege:** `WorkflowBlockProService.ts:7,62,99,138,182` · `FormulaService.ts:8-10,173,187` · `OnboardingService.ts:3,225` · `OnboardingFiltersService.ts` (`RowsApi.count`) · `CodeGeneratorService.ts:1` (`EntityWithDetails`). Routen-Disabled: `routes.ts` `defaultDisabledPluginRouteFilePatterns` (`admin/__workflows/**`), `PublicRouteSegments.ts` `disabledPluginRouteSlugs` (`workflow-engine`, `onboarding`).
|
||||
|
||||
## 🔴 Quer-Entscheidung (blockiert ALLE vier Child-Tickets)
|
||||
„Typisiert neu bauen" (Richtungsentscheid Raffael, 2026-06-30) heißt für diese Module **nicht** „ein paar Imports tauschen". Es fehlt das **typisierte Ziel**, auf dem die Engines laufen sollen. Ein Workflow-`rowCreate`-Block braucht ein konkretes Ziel-Modell; eine Formel braucht typisierte Felder. Zwei Entscheidungen, die in den Specs als offen markiert sind und vor dem Bau fallen müssen:
|
||||
|
||||
1. **Welche typisierten Modelle sind „adressierbar"?** (Workflows + Formeln müssen wissen, auf welchen Modellen sie operieren dürfen — Kontakt, Projekt, Auftrag, … aus dem ENTITY-MODEL). Daraus folgt der gemeinsame Baustein **typisierte Modell-Registry** (§Geteilte Vorbedingung).
|
||||
2. **Feld-Adressierung typisiert** — wie referenziert ein Workflow/eine Formel ein Feld eines Modells, wenn es keine generischen `Property`-Zeilen mehr gibt? (statisches Feld-Schema je Modell vs. Code-generierte Metadaten).
|
||||
|
||||
> Solange (1)+(2) offen sind, ist kein Child-Ticket autonom baubar — sonst würde der Agent Produkt-/Architektur-Richtung **erfinden** (AGENTS.md §Ticket-Treue: PR-Block). Die Specs liefern Optionen + Empfehlung; die Auswahl ist Raffaels Call.
|
||||
|
||||
## Geteilte Vorbedingung: typisierte Modell-Registry (neuer Baustein)
|
||||
`EntitiesSingleton.getEntity({name})` liefert generische Entity-Metadaten (Properties als Zeilen). Der typisierte Ersatz ist eine **Modell-Registry**: `name → { read(id), create(data), update(id,data), delete(id), fieldSchema }` über die **typisierten** Prisma-Modelle (R-P6-`Kontakt` etc.). Diese Registry ist:
|
||||
- die **gemeinsame** Grundlage für `R-P14D` (Workflows) **und** `R-P14E` (Formeln),
|
||||
- der erste Baustein der späteren `EntitiesSingleton`-Ablösung in **R-P6B-β** (49 appweite Konsumenten) — sollte also so entworfen werden, dass β darauf aufbaut,
|
||||
- **neu zu spezifizieren** (Umfang der Registry = Quer-Entscheidung 1).
|
||||
|
||||
Empfehlung: Registry als eigenes kleines Ticket **vor** R-P14D/E ziehen (Vorbedingung), damit beide darauf aufsetzen. (Als `R-P14D` Slice 0 oder eigenes `R-P6B-REG` — Owner-Entscheid.)
|
||||
|
||||
## Reihenfolge (Migrationskette, Teil 2)
|
||||
1. **Quer-Entscheidung (1)+(2)** klären (Raffael) → typisierte Modell-Registry spezifizieren/bauen.
|
||||
2. **R-P14E (formulas)** und **R-P14D (workflowEngine)** auf die Registry migrieren (parallelisierbar, sobald Registry steht).
|
||||
3. **R-P14F (onboarding)** entkoppeln (klein, peripher, kann früh/parallel).
|
||||
4. **R-P14G (codeGenerator)** Disposition entscheiden (Cut vs. Rebuild — Sonderfall, s. Doc).
|
||||
5. Erst wenn Teil 1 (R-P14C) **und** Teil 2 (D/E/F/G) durch sind → **R-P6B-β** entsperrt.
|
||||
|
||||
## Definition of Done (dieses Übersichts-Tickets)
|
||||
- [x] Teil-2-Audit durchgeführt (aktiv/dead, EB-Kopplungstiefe, Größenklassen) — siehe Tabelle oben.
|
||||
- [x] Child-Specs entworfen: `R-P14D`, `R-P14E`, `R-P14F`, `R-P14G`.
|
||||
- [x] Geteilte Vorbedingung (typisierte Modell-Registry) + zentrale Quer-Entscheidung benannt.
|
||||
- [x] **Quer-Entscheidung (1)+(2) von Raffael getroffen** (2026-06-30): adressierbar = `Kontakt` über wachsende Registry; Feld-Adressierung über `fieldSchema`.
|
||||
- [x] Child-Tickets umgesetzt (autonomer Lauf 2026-06-30): `R-P14D` (Workflows → Registry) + `R-P14F` (onboarding entkoppelt) gebaut; `R-P14E` (formulas) + `R-P14G` (codeGenerator) = **Cut mit β**. → **R-P6B-β entsperrt UND umgesetzt** (`feat/R-P6B-beta`, voller CI-Scope grün).
|
||||
|
||||
## Quellen
|
||||
- `R-P6B.md` §Migrationskette & Ownership + §Rückwirkungs-Audit (Konsumenten-Matrix).
|
||||
- `R-P14C.md` §Umsetzung (Teil 1 fertig, Variante A).
|
||||
- `docs/ARCHITECTURE-DECISIONS.md` AD-2 (Entity-Builder raus, „Migration durch Neubau"), AD-20 (projekt-zentrisch), AD-21 (Prisma-Schema/Migration).
|
||||
- `.planning/ENTITY-MODEL.md` (welche typisierten Modelle adressierbar sind — Quer-Entscheidung 1).
|
||||
- Teil-2-Audit 2026-06-30 (Codebase-Kartierung, oben).
|
||||
|
||||
## 🟢 Konkreter Vorschlag zur Abnahme (2026-06-30, Option B)
|
||||
Ausgearbeitet aus dem ENTITY-MODEL + Codebase-Stand. **Raffael: abnicken oder korrigieren** — danach ist der Bau entsperrt.
|
||||
|
||||
### Befund, der alles vereinfacht
|
||||
- Die **WorkflowEngine ist bereits typisiert** (`prisma/schema/workflows.prisma`: `Workflow`/`WorkflowBlock`/`WorkflowExecution`/…). Die **einzige** Entity-Builder-Kopplung sind die `rowGet/Create/Update/Delete`-Blöcke, die auf *generische* Entities zeigen.
|
||||
- Typisiert **gebaut** ist heute nur **`Kontakt`** (R-P6, `crm.prisma`) + **`Lead`** (`marketingLeads.prisma`). `Projekt`/`Rechnung`/`Termin`/`Aufgabe`/… kommen erst mit R-P7/R-P8+.
|
||||
- **Formeln** stehen **nicht** als eigene v1-Entität im ENTITY-MODEL (Domäne 7 = Automation/AutomationRule; keine „Formula"). → Sie sind reine Entity-Builder-Funktion (berechnete Properties).
|
||||
|
||||
### Vorschlag 1 — Adressierbares Modell-Set = „was typisiert gebaut ist", über eine wachsende Registry
|
||||
Nicht alle theoretischen Modelle auf einmal. Die **Modell-Registry** startet mit dem, was typisiert existiert, und wächst, wenn R-P7/R-P8+ neue Modelle bauen:
|
||||
- **Jetzt adressierbar:** `Kontakt` (+ `Lead`).
|
||||
- **Später (registrieren, sobald gebaut):** `Projekt`, `Rechnung`, `Termin`, `Aufgabe`, `Checkliste` … (Kern-Kette).
|
||||
- Konsequenz: **R-P14D wird viel kleiner** als die Audit-Schätzung (4–6 Wo) — kein generischer Voll-Parität-Nachbau, sondern „row-Blöcke an die Registry hängen, Registry mit Kontakt seeden". Realistisch **S–M** statt L.
|
||||
|
||||
### Vorschlag 2 — Die typisierte Modell-Registry (geteilter Baustein)
|
||||
Ein kleiner Adapter-Registry-Layer (analog zu Such-Index-/Sidebar-Registries), der `EntitiesSingleton.getEntity(name)` + `RowsApi.*` ersetzt:
|
||||
|
||||
```ts
|
||||
// packages/… oder apps/web/app/services/typed-model-registry/
|
||||
interface TypedModelAdapter<T> {
|
||||
key: string; // "kontakt" — stabiler Adress-Schlüssel
|
||||
label: string; // i18n-Key
|
||||
read(id: string, ctx: ModelCtx): Promise<T | null>;
|
||||
create(data: unknown, ctx: ModelCtx): Promise<T>;
|
||||
update(id: string, data: unknown, ctx: ModelCtx): Promise<T>;
|
||||
delete(id: string, ctx: ModelCtx): Promise<void>;
|
||||
fieldSchema: FieldSchema; // { name, type, required, … } je Feld — ersetzt PropertyWithDetails
|
||||
}
|
||||
type ModelCtx = { tenantId: string | null; userId?: string };
|
||||
// registry.get("kontakt") → Adapter ; alle Ops über withTenantScope()/withPermission() (M004) + Audit (M001)
|
||||
```
|
||||
|
||||
- **Kontakt** registriert seinen Adapter aus `crm.prisma`/`utils/integrations/crm`. Neue Modelle registrieren beim Bau (R-P7+).
|
||||
- Diese Registry ist **auch die Grundlage für R-P6B-β** (die ~49 appweiten `EntitiesSingleton`-Konsumenten für Entity-Metadaten migrieren später auf `fieldSchema`/Modell-Liste).
|
||||
- **Empfehlung:** Registry als eigenen kleinen Vor-Slice (`R-P14D` Slice 0) bauen.
|
||||
|
||||
### Vorschlag 3 — Empfehlung pro Modul
|
||||
| Modul | Empfehlung | Warum |
|
||||
|---|---|---|
|
||||
| **workflowEngine** (`R-P14D`) | **Generischer `row*`-Block über die Registry** (Modell per Parameter), adressierbares Set = registrierte Modelle (Kontakt jetzt) | Engine schon typisiert; nur 4 Blöcke umhängen; minimaler Definition-/UI-Bruch; wächst mit den Modellen |
|
||||
| **formulas** (`R-P14E`) | **CUT mit β** (kein typisierter Neubau) | Keine v1-Entität im ENTITY-MODEL; reine Entity-Builder-Funktion (berechnete Properties); stirbt sauber mit dem Builder |
|
||||
| **codeGenerator** (`R-P14G`) | **CUT mit β** | Meta-Werkzeug, generiert Code aus Entity-Defs; ohne Builder kein Input/Nutzen |
|
||||
| **onboarding** (`R-P14F`) | **EB-Touchpoints entfernen** (nicht typisieren) | onboarding hat eigenes typ. Schema; `getAllEntities`/`RowsApi.count` sind Boilerplate-Reste, in v1 ohne Funktion |
|
||||
|
||||
**Netto wenn so abgenickt:** Nur **ein** echtes Bau-Ticket bleibt aktiv (`R-P14D` workflows, jetzt S–M dank Registry + kleinem Modell-Set) + die triviale onboarding-Entkopplung (`R-P14F`). `R-P14E` (formulas) + `R-P14G` (codeGenerator) werden **kein eigener Bau**, sondern wandern in `R-P6B-β`s Lösch-Scope. Das schrumpft Teil 2 drastisch.
|
||||
|
||||
### Abnahme (Raffael, 2026-06-30) — ✅ ENTSCHIEDEN
|
||||
- [x] **V1:** Adressierbares Set startet mit **`Kontakt`** (wächst per Registry mit R-P7+). Bedingung „Kontakt nutzt den Entity-Builder nicht mehr" **bestätigt** (`utils/integrations/crm` = 0 EB-Importe, `Kontakt` echte Prisma-Tabelle). `Lead` optional mitnehmen, wenn billig.
|
||||
- [x] **V2:** Modell-Registry als geteilter Baustein bauen (Adapter-Interface oben), Slice = `R-P14D` Slice 0.
|
||||
- [x] **V3a:** workflows = generischer `row*`-Block über Registry, nur `Kontakt` adressierbar (vorerst). → **`R-P14D` baubar.**
|
||||
- [x] **V3b:** formulas = **Cut mit β** (kein Rebuild). → `R-P14E` wird Cut-Ticket.
|
||||
- [x] **V3c:** codeGenerator = **Cut mit β**. → `R-P14G` wird Cut-Ticket.
|
||||
- [x] **V3d:** onboarding = **entity-basierte Filter-Bedingungen entfernen** (`entity.hasCreated`/`hasNotCreated` + `entities`-Metadata), Rest von onboarding bleibt. Diese Bedingungen sind ohne Entity-Builder bedeutungslos. → `R-P14F` (klein). *(Falls „Nutzer hat Kontakt angelegt" später als Onboarding-Bedingung gewünscht ist: neuer typisierter Filter, eigenes Mini-Ticket.)*
|
||||
|
||||
## 🟩 Ebene-1 Mega-Plan — entschieden 2026-06-30 (für einen autonomen Lauf)
|
||||
Vollständiger, rückfragefreier Plan: Entity-Builder bis zum Ende ablösen = **Teil 2 + R-P6B-β** in *einem* autonomen Lauf.
|
||||
|
||||
### Gesetzte Entscheidungen (keine Rückfragen mehr nötig)
|
||||
- **Daten:** keine echten Tenants (Prod existiert, aber 0 echte Tenants) → β = Tabellen **droppen**, forward-only Migration, **kein Export/keine Daten-Migration**. Größter R-P6B-Blocker entfällt.
|
||||
- **Lauf-Umfang:** Teil 2 **und** β in einem Lauf (Raffael: ja).
|
||||
- **Workflow-Engine:** nur **entkoppeln**; Status bleibt wie jetzt (nav-versteckt/`disabledPluginRouteSlugs`), **NICHT** für v1 freischalten.
|
||||
- **Adressierbar:** nur **`Kontakt`** (Registry wächst später). `Lead` optional, wenn billig.
|
||||
- **formulas + codeGenerator:** **Cut mit β** (kein Rebuild).
|
||||
- **onboarding:** nur die entity-basierten Filter-Bedingungen entfernen (`entity.hasCreated`/`hasNotCreated` + `entities`-Metadata), Rest bleibt.
|
||||
- **Collab/hocuspocus:** **behalten** — ist der „novel"-Rich-Text-Editor + typisierte `CollabDoc`, NICHT Entity-Builder (Agent verifiziert: `api.collab.token` hat keinen `Row`-Bezug; sonst flaggen).
|
||||
- **Generische Entity-Row-Public-API** (`apps/api/.../entity-row-routes.ts`): **mit β löschen** (Public-API ist eh v2).
|
||||
- **Formular-Eingang** (Worker `form-submission-route`, falls er generische Entity-Rows schreibt): **generischen Schreibpfad mit β entfernen, KEIN typisiertes Ziel erfinden.** Wenn dadurch der Formular-Eingang ohne Ziel dasteht → sauber deaktivieren + **CR/TODO für Raffael flaggen** („typisiertes Formular-Capture-Ziel, z.B. Lead, offen"). Pre-Launch unkritisch.
|
||||
- **EntitiesSingleton:** nur 12 Konsumenten (nicht 49); 8 im Builder-Kern (sterben mit β), außerhalb nur `useAppData`/`useAdminData` (drop `entities`-Feld) + Workflows (Phase A).
|
||||
- **entityLinks.prisma ≠ entityBuilder.prisma:** Agent prüft; `entityLinks`/`FileEntityLink` (typisierte polymorphe Links) **behalten**, nur `entityBuilder.prisma` löschen.
|
||||
|
||||
### Ablauf (Slices, jeder grün, Subagenten für Audits)
|
||||
**Phase A — Teil 2 (Branch `feat/R-P14C-teil2`):**
|
||||
- **A0** Modell-Registry bauen (Adapter-Interface oben) + Kontakt-Adapter registrieren.
|
||||
- **A1** `R-P14D`: Workflow-`row*`-Blöcke (`WorkflowBlockProService`, `WorkflowsTemplatesService`) auf Registry (Kontakt-only); `EntitiesSingleton`/`RowsApi` raus; Tests umstellen.
|
||||
- **A2** `R-P14F`: onboarding entity-Filter-Bedingungen + `entities`-Metadata entfernen.
|
||||
|
||||
**Phase B — R-P6B-β (neuer Branch `feat/R-P6B-beta` auf `feat/R-P14C-teil2`):**
|
||||
- **B0** Audit (Subagent): exakte Lösch-/Nachzug-Liste (Inventar in `R-P6B.md` §Umfang).
|
||||
- **B1** EB-UI/Routen löschen: `modules/rows`, `components/entities`, `admin/entities/**`, `settings/entities/**`, `$entity.__autogenerated`/`g.$group`, `routes/admin/__workflows` (disabled), `formulas`, `codeGenerator`.
|
||||
- **B2** API-Layer löschen: `utils/api/.server/{Entities,Rows,Properties,RowRelationships,RowPermissions}Api`, `utils/db/entities/**`, `apps/api` entity-row-routes, Worker form-submission generischer Pfad.
|
||||
- **B3** `EntitiesSingleton` raus: `useAppData`/`useAdminData` `entities`-Feld droppen (Konsumenten des Feldes prüfen → es sind nur EB-UI-Teile, die in B1 weg sind).
|
||||
- **B4** Schema: `entityBuilder.prisma` löschen → `prisma db push` (AD-21, kein Migration-File am Branch) + `generate`; `TENANT_SCOPED_MODELS` (entityBuilder-Modelle raus) + RLS nachziehen.
|
||||
- **B5** Cross-Refs/Registries: `routes.ts` disabled-Patterns, `disabledPluginRouteSlugs`, Sidebar, Such-Index (`packages/search`), Permissions (`admin.formulas.*` etc.), Manifeste (`plugin-candidates.json`, `rows-entities-runtime.json`), Decision-Report-Verifier (`scripts/verify-*`), `routes.test.ts`, `admin-route-targets.test.ts` — alle nachziehen.
|
||||
- **B6** Voller CI-Scope grün + `prisma migrate deploy` gegen leere DB reproduzierbar (Migration entsteht beim Merge, forward-only + Inverse-SQL-Kommentar, `DO $$ … IF EXISTS … $$`-Guards).
|
||||
|
||||
### PR-/Merge-Strategie (3 gestapelte PRs, in Reihenfolge mergebar)
|
||||
1. `R-P14C` (Teil 1, Branch `feat/R-P14C`) — liegt fertig.
|
||||
2. `R-P14C-teil2` (Phase A) — auf Teil 1.
|
||||
3. `R-P6B-β` (Phase B, Branch `feat/R-P6B-beta`) — auf Teil 2.
|
||||
Jeder Branch eigenständig grün; CI so vorbereitet, dass die drei PRs **jederzeit in dieser Reihenfolge** mergebar sind.
|
||||
|
||||
## Umsetzung
|
||||
- 2026-06-30: Teil-2-Audit + Spec-Entwürfe erstellt (Branch `feat/R-P14C-teil2`). **Kein Migrations-Code** — der typisierte Ziel-Layer ist Produkt-/Architektur-Entscheidung (Quer-Entscheidung), die vor dem Bau fallen muss. Diese Doc + die vier Child-Docs sind der ausführungsreife Ausgangspunkt.
|
||||
- 2026-06-30: **Konkreter Vorschlag (Option B) ergänzt** (§oben) — wachsende Modell-Registry, adressierbares Set startet mit Kontakt, formulas+codeGenerator → Cut mit β. Wartet auf Raffaels Abnahme (V1–V3d), dann ist `R-P14D` (+`R-P14F`) baubar.
|
||||
@@ -0,0 +1,63 @@
|
||||
# R-P14C · EmailMarketing-Typisierung + rückwirkende Entity-Builder-Ablösung
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Dev (Code) |
|
||||
| **Owner** | **Raffael (+ Agent)** — übernimmt das EmailMarketing-Modul von Akeshan |
|
||||
| **Phase** | P14 / P6 (Entity-Builder-Ablösung, AD-2) |
|
||||
| **Plane** | HIVEGRID-169 · **blocked-by `AK-P14a` (#42) + `AK-P14b` (#43)** |
|
||||
| **Status** | erledigt · 7/7 DoD = 100 % done |
|
||||
|
||||
## Plan-Entscheidung (2026-06-29, Raffael)
|
||||
Akeshan baut **AK-P14a (#42)** + **AK-P14b (#43)** planmäßig auf dem bestehenden Entity-Builder fertig (das ist OK — sie werden hier ohnehin migriert). Danach **stoppt Akeshan kurz**, und **Raffael (+ Agent) übernimmt das EmailMarketing-Modul** mit diesem Ticket. R-P14C ist der gebündelte Migrations-Schritt: EmailMarketing typisieren **und** die übrigen rückwirkenden Builder-Konsumenten gleich „im Vorhinein" mitnehmen, damit die nächsten Tickets sauber typisiert aufsetzen.
|
||||
|
||||
## Was wir bauen
|
||||
**Teil 1 — EmailMarketing typisiert (löst die `CrmService`-Legacy ab):**
|
||||
- Contact-Repo-Template: typisierte Lese-API (`getContactsByIds(ids, tenantId): Kontakt[]` o.ä.) auf dem R-P6-`Kontakt`-Modell.
|
||||
- `modules/emailMarketing/services/EmailMarketingService.ts` (+ email-marketing-Routes) von `CrmService.getContact`/`getContactsInRowIds`/`validate` auf die typisierte API umstellen.
|
||||
- **Daten:** prüfen, ob bestehende Kampagnen contact-**Row-IDs** referenzieren → ggf. kleine Daten-Migration (Row-ID → Kontakt-ID), nicht nur Code.
|
||||
- Danach: `modules/crm/CrmService` (Legacy-Reader) entfernbar.
|
||||
|
||||
**Teil 2 — rückwirkende Migration der übrigen gebauten Builder-Konsumenten** (siehe R-P6B §Rückwirkungs-Audit):
|
||||
- **WorkflowEngine** (`modules/workflowEngine`): `EntitiesSingleton.getEntity()` → typisierte Workflow-Registry.
|
||||
- **formulas** (`modules/formulas`): `EntityWithDetails`/`PropertyWithDetails` → typisiertes Evaluations-Modell.
|
||||
- **codeGenerator** / **onboarding**: prüfen, ob noch aktiv/nötig; sonst typisieren oder entfernen.
|
||||
|
||||
Erst wenn Teil 1+2 durch sind, kann **R-P6B-β** (`EntitiesSingleton` raus → `modules/rows`/`utils/db/entities`/Routen/Schema löschen) gefahren werden.
|
||||
|
||||
## Definition of Done
|
||||
- [x] Typisierte Contact-Lese-API auf dem `Kontakt`-Modell (ersetzt die `CrmService`-Reader). — **Variante A:** erfüllt durch *Entfernung* statt Neubau. Die `CrmService`-Reader-Konsumenten (EmailMarketingService) wurden gelöscht; Akeshans typisierte Segment-/Send-Engine (CampaignSendService liest `tx.kontakt` direkt) deckt den Versand ab. `getKontakteByIds` wurde **nicht** hinzugefügt, da keine verbleibende Stelle einen typisierten Batch-Kontakt-Lookup braucht (nichts erfinden, AD-2).
|
||||
- [x] EmailMarketing nutzt keine Entity-Builder-/`CrmService`-Reader mehr; Kampagnen-Empfänger typisiert. — Empfänger über `OutboundEmail.kontaktId` (+ `RecipientSegment`). **Keine Daten-Migration nötig** (Pre-Launch, keine `contactRowId`-Kampagnen in Prod/Staging; Demo-Seed legt keine an).
|
||||
- [x] WorkflowEngine + formulas (+ codeGenerator/onboarding nach Prüfung) nutzen `EntitiesSingleton`/`Entity`/`Property` nicht mehr. — Erfüllt über R-P14C-T2 + R-P6B-β: WorkflowEngine läuft über die typisierte Modell-Registry (`Kontakt` als erster Adapter), onboarding ist entkoppelt, formulas + codeGenerator wurden bewusst mit β geschnitten.
|
||||
- [x] `modules/crm/CrmService`-Legacy entfernt. — `modules/crm` **vollständig gelöscht** (CrmService.ts + ProductCoreCrmEntities.server.ts + Tests); 0-Konsumenten-Beweis per repo-weitem grep.
|
||||
- [x] Keine neuen Entity-Builder-Konsumenten eingeführt (AD-2).
|
||||
- [x] Voller CI-Test-Scope grün (typecheck + lint + test:foundation/packages/mobile + test + verify:i18n + verify:cross-cutting-models).
|
||||
- [x] R-P6B-β danach entsperrt (EntitiesSingleton-Removal + Schema-Löschung möglich). — Entsperrt und umgesetzt; `feat/R-P6B-beta` ist in `main`, der aktuelle Branch `feat/R-P6B-drop-migration` ergänzt die forward-only DROP-Migration.
|
||||
|
||||
## Koordination / Sperre
|
||||
- Solange R-P14C läuft, ruht/abgestimmt: `modules/emailMarketing`, `modules/workflowEngine`, `modules/formulas` (Akeshan baut dort nicht parallel).
|
||||
- Akeshan wird bei Änderungen an seinen Modulen eingebunden.
|
||||
|
||||
## Quellen
|
||||
- `R-P6B.md` §Migrationskette & Ownership + §Rückwirkungs-Audit (Konsumenten-Liste, Reihenfolge).
|
||||
- `docs/ARCHITECTURE-DECISIONS.md` AD-2 (verbindlich: keine neuen Konsumenten, Ablöse-Pflicht).
|
||||
|
||||
## Umsetzung
|
||||
- 2026-06-29: Ticket angelegt (Plan-Entscheidung Raffael). Bau startet, sobald AK-P14a/b fertig + Akeshan stoppt.
|
||||
- 2026-06-30: **Teil 1 (EmailMarketing) gebaut — Variante A (alten Entity-Builder-Editor-Pfad ENTFERNEN, nicht migrieren).** Branch `feat/R-P14C` (auf `main` HEAD nach AK-P14b #21). **Noch KEIN Push/PR/Merge** (Raffael reviewt lokal, entscheidet über PR).
|
||||
|
||||
**Stand: 5/7 DoD = ~71 % des Gesamt-Tickets R-P14C.** Der **Teil-1-EmailMarketing-Scope dieses Durchlaufs ist zu 100 % erfüllt.** Offen sind nur DoD-3 (WorkflowEngine/formulas/codeGenerator/onboarding) + DoD-7 (R-P6B-β-Entsperrung) = **R-P14C Teil 2**, ausdrücklich separater Durchlauf → in diesem Variante-A-Auftrag **0 selbst machbar**.
|
||||
|
||||
**Begründung Variante A:** Der alte Editor ist Boilerplate-Legacy, den David (D-KAMP) ohnehin durch einen bespoke Editor ersetzt; ihn zu migrieren wäre Wegwerf-Arbeit. Das typisierte Backend (Versand via `CampaignSendService` liest `tx.kontakt` direkt, Empfänger via `RecipientSegment`) steht schon → keine Funktionalität geht verloren, nur die alte UI-Hülle.
|
||||
|
||||
**Slices/Commits (5):**
|
||||
- `ebef2ea17` S2: Entity-Builder-Kampagnen-Editor entfernt — `EmailMarketingService` (CrmService/EntityViewsApi/contactRow), `Campaigns_New/Edit/List` + Components + `campaignDefaults`, app- **und** admin-Kampagnen-Routen, Campaigns-Nav-Tab (app+admin). Overview-Summary auf typisierte `countOutboundEmails` umgestellt. **Activity-Log behalten** und vom Entity-Builder befreit (`getAllEntities`/`contactRow`/`RowHelper` raus, Empfänger über `email`-Feld, Kampagnen-Spalte de-linkt). Decision-Report-Verifier (crm/email-marketing) + `plugin-candidates.json` + beide Reports nachgezogen.
|
||||
- `0368ffc3b` S3: `CrmService.validate`-Gate aus app- + admin-`email-marketing.tsx` entfernt → `CrmService` ohne Runtime-Konsumenten.
|
||||
- `d866ca767` S4: `contactRow`-Joins aus `campaigns.db.server` + `outboundEmails.db.server` entfernt; recipients über `kontaktId`; orphaned `createOutboundEmail` gelöscht.
|
||||
- `95f65f85a` S5: `OutboundEmail.contactRowId` + `contactRow`-Relation aus `email.prisma` gedroppt + Row-Back-Relation in `entityBuilder.prisma`; AD-21 `prisma db push` (kein Migration-File), Client regeneriert + mitcommittet.
|
||||
- `3b654597a` S6: `modules/crm` (CrmService + ProductCoreCrmEntities + Tests) vollständig gelöscht (0-Konsumenten-Beweis); `users.mfa.test` vi.mock + `visible-shell-copy-i18n.test`-Listeneintrag + CRM-Verifier nachgezogen.
|
||||
|
||||
**Verifikation (voller CI-Scope, pro Slice grün):** `pnpm typecheck` + `lint` + `test:foundation` (404) + `test:packages` (452) + `test:mobile` (62) + `pnpm test` (Core, 3663 nach Entfernung der CrmService-Tests) + `verify:i18n` + `verify-cross-cutting-models` (112/112) — alle grün.
|
||||
|
||||
**Übergangs-Vorbehalt (D-KAMP):** Bis Davids bespoke Kampagnen-Editor (D-KAMP) da ist, gibt es im Übergang **keine grafische Kampagnen-ERSTELL-UI**; Segmente-Route + Backend-Versand (CampaignSendService) bleiben. Pre-Launch unkritisch (keine echten Kampagnen; Demo-Seed legt keine `contactRowId`-Kampagnen an). `modules/crm` konnte **vollständig** gelöscht werden.
|
||||
- 2026-06-30: **HIVEGRID-169 Abschluss nachgezogen — 7/7 DoD = 100 % done.** Teil 2 wurde über `R-P14C-T2` abgeschlossen: `R-P14D` (WorkflowEngine → typisierte Modell-Registry) + `R-P14F` (onboarding entkoppelt) sind erledigt; `R-P14E` (formulas) + `R-P14G` (codeGenerator) wurden mit `R-P6B-β` bewusst entfernt. `R-P6B-β` ist via PR #25 auf `main`; aktueller Proof-Zusatz: `e6a7252ed` ergänzt die forward-only DROP-Migration `20260630120000_drop_entity_builder`. Verifikation laut R-P14C-T2/R-P6B: voller CI-Scope grün; Gitea-Actions für T1, R-P14C-teil2 und R-P6B-beta grün. Selbst machbar offen: 0.
|
||||
@@ -0,0 +1,61 @@
|
||||
# R-P14D · WorkflowEngine vom Entity-Builder typisiert ablösen
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Dev (Code) |
|
||||
| **Owner** | Raffael (+ Agent) |
|
||||
| **Phase** | P6 / P14 (Entity-Builder-Ablösung, AD-2) — **Teil 2** |
|
||||
| **Plane** | neu · Child von `R-P14C-T2` |
|
||||
| **Größe** | **L** (Audit-Schätzung ~4–6 Wochen, abhängig vom Registry-Umfang) |
|
||||
| **Status** | **ENTSPERRT (Raffael 2026-06-30):** Kontakt-only adressierbar, generischer Block über Registry. Größe damit eher **S–M** (kein Voll-Parität-Nachbau). Slice 0 = Modell-Registry bauen. |
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **blocked-by:** `R-P14C-T2` Quer-Entscheidung (welche typisierten Modelle adressierbar, Feld-Adressierung) + die **typisierte Modell-Registry** (geteilter Baustein, s. T2).
|
||||
- **blocks:** `R-P6B-β` (EntitiesSingleton-Removal) — solange die Pro-Blöcke `EntitiesSingleton`/`RowsApi` nutzen, kann β nicht löschen.
|
||||
- **koordiniert mit:** `R-P14E` (formulas) teilt die Modell-Registry. Akeshan einbinden (Modul ruhte unter R-P14C).
|
||||
|
||||
## Was wir bauen
|
||||
Die **vier Pro-Workflow-Blöcke** `rowGet / rowCreate / rowUpdate / rowDelete` (in `WorkflowBlockProService.ts`) operieren heute auf **beliebigen generischen Entities per Name**: der Workflow-JSON nennt `entity: "<name>"`, der Block löst ihn via `EntitiesSingleton.getEntity({name})` auf und CRUDt über `RowsApi.get/create/update/del`. Das ist die einzige zentrale Entity-Builder-Kopplung im Modul (die übrigen Blöcke `waitForInput`/`email` sind builder-frei).
|
||||
|
||||
Ziel: Diese vier Blöcke auf die **typisierte Modell-Registry** umstellen — ein Workflow adressiert ein **typisiertes** Modell (Kontakt/Projekt/… laut ENTITY-MODEL) statt einer generischen Entity, und das CRUD läuft über typisiertes Prisma statt `RowsApi`. Semantik (Block-Input/Output, Variablen-Substitution, `eventContext: { source: "workflow" }`) bleibt erhalten, damit bestehende Workflow-Definitionen weiter funktionieren — soweit sie ein adressierbares Modell treffen.
|
||||
|
||||
`WorkflowsTemplatesService.ts` (zweite EB-Stelle) muss mitgezogen werden (Template-Workflows referenzieren Entities).
|
||||
|
||||
## Benötigte Screens
|
||||
Keine neuen — Workflow-Editor-UI bleibt. **Aber:** der Block-Editor muss statt freier `entity`-Strings die **adressierbaren Modelle** als Auswahl anbieten (Davids Delta klären, falls die UI eine Liste braucht). Solange das Modell-Set klein/fest ist, evtl. nur ein Dropdown statt Freitext.
|
||||
|
||||
## Definition of Done
|
||||
- [x] `rowGet/rowCreate/rowUpdate/rowDelete` nutzen die **typisierte Modell-Registry** statt `EntitiesSingleton`/`RowsApi`; kein Import aus `~/utils/api/.server/RowsApi`, `~/modules/rows/**`, `~/utils/db/entities/**` mehr im Modul.
|
||||
- [x] Block-Input-Validierung (`WorkflowsValidationService`) auf typisierte Felder/Modelle angepasst; unbekanntes/nicht-adressierbares Modell → Klartext-Fehler (M002), nicht stiller Fail.
|
||||
- [x] `WorkflowsTemplatesService` builder-frei; Template-Workflows referenzieren nur adressierbare Modelle.
|
||||
- [x] `WorkflowBlockProService.test.ts` (mockt heute `RowsApi`/`EntitiesSingleton`) auf die Registry umgestellt; `workflow-producer-inventory.test.ts`-Fixtures nachgezogen. Workflow-Block-Execution voll getestet (rowGet/Create/Update/Delete gegen typisiertes Modell).
|
||||
- [x] **Bestehende Workflow-Definitionen:** Pre-Launch existieren keine produktiven Workflow-Daten (0 echte Tenants) → reiner Code-Umbau, keine Daten-Migration. Alte generische `entity`-Referenzen, die kein adressierbares Modell treffen, liefern jetzt einen Klartext-Fehler im Block.
|
||||
- [x] Reachability: `app.$tenant/__workflows/**` Routen + (disabled) Admin bleiben konsistent; Block-Typen unverändert (`entity`-Feld bleibt ein String, der jetzt auf einen Registry-Key auflöst).
|
||||
- [x] Voller CI-Scope grün (typecheck + lint + test:foundation/packages/mobile + test + verify:i18n + verify-cross-cutting-models + verify:workflow-outbox-native).
|
||||
- [x] AD-2: keine neuen Entity-Builder-Konsumenten; `EntitiesSingleton`/`RowsApi`-Importe im Modul = 0.
|
||||
|
||||
## Umsetzung
|
||||
- 2026-06-30 (autonomer Lauf, Branch `feat/R-P14C-teil2`): **Slice A0 + A1 umgesetzt, 8/8 DoD = 100 %.**
|
||||
- **A0 (geteilter Baustein):** `apps/web/app/services/typed-model-registry/` neu — `types.ts` (`TypedModelAdapter`/`FieldSchema`/`ModelCtx`/`TypedModelError`), `registry.server.ts` (`getModelAdapter`/`getModelAdapterOrThrow`/`listModelKeys`, statisches Objekt-Literal analog `indexedEntities`), `kontaktAdapter.server.ts` (read/create/update/delete über `crmService.server` + Audit/Activity via `crmAudit`). Adressierbar: nur `Kontakt` (Registry wächst mit R-P7+). 9 Unit-Tests.
|
||||
- **A1 (Workflow):** Die vier `row*`-Blöcke in `WorkflowBlockProService.ts` lösen `entity:"<key>"` jetzt über die Registry auf; `EntitiesSingleton`/`RowsApi`/`ApiHelper`-Importe raus. `WorkflowsTemplatesService` validiert Template-Entities gegen `listModelKeys()` statt `getAllEntities`. Tests (`WorkflowBlockProService.test.ts`, `WorkflowsTemplatesService.import.test.ts`) auf Registry-Mock umgestellt; `workflow-producer-inventory.test.ts` + `outbox-pattern.md`/`worker-queues.md` nachgezogen (Workflow-Blöcke produzieren keine generischen `row.*`-Outbox-Events mehr, sondern Audit/Activity des typisierten Modells).
|
||||
- Workflow bleibt **nav-versteckt/disabled** (nur entkoppelt, NICHT für v1 freigeschaltet — gesetzte Entscheidung).
|
||||
- Proof: voller CI-Scope lokal grün (35 Workflow-Tests, 284 workflow-outbox-native-Tests, 3672 Core-Tests).
|
||||
|
||||
## Technische Bausteine
|
||||
- **Modell-Registry** (aus `R-P14C-T2`): `name → { read, create, update, delete, fieldSchema }` über typisierte Prisma-Modelle. Ersetzt `EntitiesSingleton.getEntity` (Metadaten) + `RowsApi.*` (CRUD).
|
||||
- **`ApiHelper`-Ersatz:** `ApiHelper.getApiFormat(entity, item)` / `getRowPropertiesFromJson(...)` formen heute generische Row↔JSON. Typisiert: Mapper Modell↔JSON je adressierbarem Modell (oder generisch über das Registry-`fieldSchema`).
|
||||
- **Variablen-Substitution** (`parseVariable`/`WorkflowsVariablesService`) bleibt; nur die Datenquelle wechselt.
|
||||
- **Tenant-Scope:** `RowsApi`-Calls trugen `tenantId`/`userId`; typisiert über `withTenantScope()`/`withPermission()` (M004) bzw. RLS — kein manueller Filter.
|
||||
- **Audit/Activity:** `eventContext: { source: "workflow" }` → typisiert via M001-Middleware/`auditEvent` + ggf. `logActivity` (DoD §C).
|
||||
- AD-21: kein eigenes neues Schema nötig (operiert auf bestehenden typisierten Modellen); falls Workflow-eigene Tabellen angefasst werden, eigene `prisma/schema/workflows.prisma`.
|
||||
|
||||
## Offene Entscheidungen (vor Bau klären)
|
||||
1. **Adressierbares Modell-Set** = Quer-Entscheidung T2 (welche ENTITY-MODEL-Modelle dürfen Workflows CRUDen?).
|
||||
2. **Generischer vs. fester Block:** Bleibt ein *generischer* „row*"-Block (Modell per Parameter, über Registry) oder werden es **pro Modell** typisierte Blöcke (`kontaktCreate`, …)? Generisch = näher am Bestand, fest = sauberer typisiert. **Empfehlung:** generisch über Registry (minimaler UI-/Definition-Bruch).
|
||||
3. **Alt-Daten:** Existieren produktive Workflow-Definitionen mit generischen `entity`-Referenzen? Wenn ja: Mapping nötig. Wenn nein (Pre-Launch): reiner Code-Umbau.
|
||||
|
||||
## Quellen
|
||||
- `R-P14C-T2.md` (Übersicht + Quer-Entscheidung + Registry).
|
||||
- `WorkflowBlockProService.ts` (Bestands-Implementierung der vier Blöcke).
|
||||
- `R-P6B.md` §Rückwirkungs-Audit (WorkflowEngine kritisch).
|
||||
- `docs/ARCHITECTURE-DECISIONS.md` AD-2 · AGENTS.md §Querschnitt-Hülle (M001/M002/M004).
|
||||
@@ -0,0 +1,53 @@
|
||||
# R-P14E · formulas vom Entity-Builder typisiert ablösen
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Dev (Code) |
|
||||
| **Owner** | Raffael (+ Agent) |
|
||||
| **Phase** | P6 / P14 (Entity-Builder-Ablösung, AD-2) — **Teil 2** |
|
||||
| **Plane** | neu · Child von `R-P14C-T2` |
|
||||
| **Größe** | **M** (Audit-Schätzung ~3–4 Wochen; Risiko: 0 Unit-Tests im Modul) |
|
||||
| **Status** | **ENTSCHIEDEN: CUT mit β (Raffael 2026-06-30)** — kein typisierter Rebuild; formulas wird mit dem Entity-Builder in R-P6B-β entfernt. |
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **blocked-by:** `R-P14C-T2` Quer-Entscheidung + typisierte **Modell-Registry** (geteilt mit `R-P14D`).
|
||||
- **blocks:** `R-P6B-β`.
|
||||
- **eng gekoppelt an:** die Entity-Builder-UI — `formulas` wird heute aus `admin/entities/**` + `app.$tenant/settings/entities/**` gerendert (Property-Config einer Entity). Diese Routen löscht β. ⇒ **Klärungsbedarf:** Bleiben Formeln als Feature der **typisierten** Modelle (berechnete Felder auf Kontakt/Projekt) erhalten, oder sterben sie mit der Entity-Builder-UI? (siehe §Offene Entscheidungen).
|
||||
|
||||
## Was wir bauen
|
||||
`FormulaService` evaluiert heute Formeln **über die generische Entity-Struktur**: lädt `getAllEntities()`, iteriert `EntityWithDetails`/`PropertyWithDetails`, liest Werte aus `RowWithDetails` via `RowHelper.getPropertyValue(...)`. `FormulaRowService` zieht Komponenten-Inputs ebenso. `FormulaVariableValueDto` typt die Variablen auf `EntityWithDetails`/`RowWithDetails`.
|
||||
|
||||
Ziel (sofern Formeln v1-Feature bleiben, §Offene Entscheidungen): Evaluation auf **typisierte Modelle** umstellen — Formel-Variablen referenzieren typisierte Felder (über die Modell-Registry-`fieldSchema`), Werte werden direkt aus typisierten Prisma-Records gelesen statt aus `RowValue`-Zeilen.
|
||||
|
||||
## Benötigte Screens
|
||||
Abhängig von der Disposition: Wenn Formeln als „berechnete Felder" auf typisierten Modellen bleiben, braucht es eine Stelle, sie zu konfigurieren (heute Teil der EB-Property-UI, die β entfernt). **Davids Delta** klären — evtl. eigener kleiner Formel-Editor je Modell, oder Cut.
|
||||
|
||||
## Definition of Done
|
||||
> **Disposition CUT mit β (Raffael 2026-06-30):** Kein typisierter Rebuild. Die typisierten DoD-Punkte unten sind damit **gegenstandslos** (n/a) — relevant ist nur der Cut-Punkt.
|
||||
- [n/a] ~~`FormulaService` + `FormulaRowService` auf typisierte Modelle/Registry~~ — Cut, kein Rebuild.
|
||||
- [n/a] ~~`FormulaVariableValueDto` auf typisierte Feld-Referenzen~~ — Cut.
|
||||
- [n/a] ~~Unit-Tests neu für die Evaluation~~ — Cut.
|
||||
- [n/a] ~~Klartext-Fehler bei unbekanntem Feld/Modell~~ — Cut.
|
||||
- [n/a] ~~Formel-Route-Tests angepasst~~ — Routen mit β gelöscht.
|
||||
- [x] **AD-2: keine Entity-Builder-Importe im Modul** — Modul ist entfernt.
|
||||
- [x] **CUT:** `apps/web/app/modules/formulas/**` + die zugehörigen `admin/entities/formulas*`-Routen (Teil des gelöschten `admin/entities/**`-Baums) sauber entfernt; Permissions `admin.formulas.*` aus allen 4 Registries + i18n nachgezogen; Konsumenten/Tests grün. Voller CI-Scope grün.
|
||||
|
||||
## Umsetzung
|
||||
- 2026-06-30 (autonomer Lauf, Branch `feat/R-P6B-beta`): **CUT mit β umgesetzt.** `modules/formulas` (14 Dateien) gelöscht; die `admin/entities/formulas*`-Routen fielen mit dem `admin/entities/**`-Baum; Formula/FormulaComponent/FormulaLog-Modelle mit `entityBuilder.prisma` entfernt; `admin.formulas.*`-Default-Permissions aus `DefaultPermissions.ts` + `roleDisplay.ts` + `permissions-seed.server.ts` + `translations.json` (de+en) entfernt. Kein typisierter Rebuild (Formeln sind keine v1-Entität im ENTITY-MODEL; reine Entity-Builder-Funktion). Falls „berechnete Felder" auf typisierten Modellen später gewünscht sind → neues Ticket. Teil von R-P6B-β; voller CI-Scope grün.
|
||||
|
||||
## Technische Bausteine
|
||||
- **Modell-Registry** `fieldSchema` (aus T2) liefert typisierte Feld-Metadaten je Modell — ersetzt `PropertyWithDetails` + `RowHelper.getPropertyValue`.
|
||||
- **Wert-Zugriff:** statt `RowHelper.getPropertyValue({entity,item,property})` → direkter typisierter Feldzugriff (`record[field]`) mit Typ-Coercion über das `fieldSchema`.
|
||||
- **FormulaLog** (falls vorhanden, `prisma/schema`): prüfen, ob an `Row`/`Property` gebunden; ggf. auf typisierte Referenzen umstellen oder belassen.
|
||||
- Querschnitt: M001-Audit, M002-Klartext, M004-Tenant-Scope.
|
||||
|
||||
## Offene Entscheidungen (vor Bau klären)
|
||||
1. **Bleiben Formeln v1?** Formeln sind heute eine **Entity-Builder-Funktion** (berechnete Properties auf generischen Entities). Wenn der Entity-Builder stirbt (β) und es keine „berechneten Felder" auf typisierten Modellen geben soll → **Cut** (mit β löschen), kein Rebuild. Wenn doch → Rebuild als berechnete Felder auf adressierbaren Modellen. **Das ist die Kern-Produktfrage dieses Tickets.**
|
||||
2. **Welche Modelle** dürfen berechnete Felder haben (= Quer-Entscheidung T2).
|
||||
3. **Persistenz:** Werden Formel-Ergebnisse gespeichert (heute `FormulaLog`/RowValue) oder on-read berechnet?
|
||||
|
||||
## Quellen
|
||||
- `R-P14C-T2.md` (Übersicht + Quer-Entscheidung + Registry).
|
||||
- `FormulaService.ts`, `FormulaRowService.ts`, `FormulaVariableValueDto.ts` (Bestand).
|
||||
- `R-P6B.md` §Rückwirkungs-Audit (formulas kritisch).
|
||||
- `docs/ARCHITECTURE-DECISIONS.md` AD-2 · `.planning/ENTITY-MODEL.md`.
|
||||
@@ -0,0 +1,50 @@
|
||||
# R-P14F · onboarding vom Entity-Builder entkoppeln
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Dev (Code) |
|
||||
| **Owner** | Raffael (+ Agent) |
|
||||
| **Phase** | P6 / P14 (Entity-Builder-Ablösung, AD-2) — **Teil 2** |
|
||||
| **Plane** | neu · Child von `R-P14C-T2` |
|
||||
| **Größe** | **S–M** (peripher; nur 2 Touchpoints) |
|
||||
| **Status** | **ENTSCHIEDEN (Raffael 2026-06-30): entity-basierte Filter-Bedingungen entfernen** (kein Rebuild). Baubar. |
|
||||
|
||||
> **Entscheidung 2026-06-30:** Die EB-Kopplung ist die Onboarding-Filter-Bedingung „Nutzer hat (k)eine Reihe einer generischen Entität angelegt" (`entity.hasCreated`/`entity.hasNotCreated` in `OnboardingFiltersService` + die `entities`-Liste in `OnboardingService.getMetadata`). Ohne Entity-Builder ist das bedeutungslos → **diese Bedingungen + die `entities`-Metadata entfernen**, der Rest von onboarding (Flows, andere Filter: user/tenant/role/subscription/apiKeyLogs) bleibt unverändert. Falls später „Nutzer hat Kontakt angelegt" als Bedingung gewünscht ist → neuer typisierter Filter über die Registry (eigenes Mini-Ticket).
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **blocked-by:** ggf. `R-P14C-T2` Quer-Entscheidung — nur, falls onboarding weiter „Entities" auflisten/zählen können soll (dann braucht es das adressierbare Modell-Set). Falls die Touchpoints schlicht entfernt/ersetzt werden können, **früh + parallel baubar**.
|
||||
- **blocks:** `R-P6B-β` (mit-blockierend, solange `getAllEntities`/`RowsApi` im Modul).
|
||||
- Slug `onboarding` ist in `disabledPluginRouteSlugs` (nav-versteckt); `admin/onboarding/**` + public `/onboarding/$id` existieren.
|
||||
|
||||
## Was wir bauen
|
||||
Nur **zwei** periphere Entity-Builder-Stellen entkoppeln:
|
||||
1. **`OnboardingService.ts:3,225`** — `getAllEntities({ tenantId: null })` füllt ein `entities`-Feld der Onboarding-Config (Liste der verfügbaren Entities, vermutlich für Step-/Filter-Auswahl).
|
||||
2. **`OnboardingFiltersService.ts`** — `RowsApi.count({...})` zählt generische Reihen für die Filter-Vorschau.
|
||||
|
||||
Beide hängen am generischen Entity-Begriff. Optionen je Stelle: durch die typisierte Modell-Registry ersetzen (adressierbare Modelle/Counts) **oder** entfernen, falls onboarding den Entity-Bezug in v1 gar nicht braucht.
|
||||
|
||||
## Definition of Done
|
||||
- [x] `OnboardingService` ohne `getAllEntities`/`~/utils/db/entities`-Import; `entities`-Metadata aus `getMetadata()` + `OnboardingFilterMetadataDto` entfernt.
|
||||
- [x] `OnboardingFiltersService` ohne `RowsApi`; die `entity.hasCreated`/`hasNotCreated`-Filter-Cases entfernt (statt Count-Vorschau).
|
||||
- [x] `OnboardingFiltersService.test.ts` + die onboarding-Modul-Tests grün (35 Tests); `verify-onboarding-flow.mjs` grün.
|
||||
- [x] Public `/onboarding/$id` + `admin/onboarding/**` bleiben konsistent (entity-InputSelector in `filters.tsx` + `OnboardingFilterUtils`-Parse-Zweig entfernt; `appOrAdminData.entities` nicht mehr referenziert).
|
||||
- [x] Voller CI-Scope grün; AD-2: 0 Entity-Builder-Importe im Modul.
|
||||
|
||||
## Umsetzung
|
||||
- 2026-06-30 (autonomer Lauf, Branch `feat/R-P14C-teil2`): **Slice A2 umgesetzt, 5/5 DoD = 100 %.** Die zwei Filter-Typen `tenant.user.entity.hasCreated`/`hasNotCreated` (Enum `OnboardingFilterTypes`), der `RowsApi.count`-Case (`OnboardingFiltersService`), das `entities`-Metadata-Feld (`OnboardingService.getMetadata` + `OnboardingFilterMetadataDto`), der Parse-Zweig (`OnboardingFilterUtils`) und der entity-InputSelector (`onboardings.$id/filters.tsx`) entfernt; Filter-Beschreibung in `translations.json` (de+en) nachgezogen. Restliche onboarding-Filter (user/tenant/role/subscription/apiKeyLogs) unverändert. Test-Mocks für `RowsApi`/`getAllEntities` aus den zwei Suites entfernt. Proof: 35 onboarding-Tests grün, `verify:onboarding-flow` EXIT 0, voller CI-Scope grün.
|
||||
- *(Hinweis: Falls „Nutzer hat Kontakt angelegt" später als Onboarding-Bedingung gewünscht ist → neuer typisierter Filter über die Modell-Registry, eigenes Mini-Ticket.)*
|
||||
|
||||
## Technische Bausteine
|
||||
- Modell-Registry (T2) für „verfügbare Modelle/Counts", falls onboarding diese Auswahl behält.
|
||||
- Tenant-Scope: `RowsApi.count` trug Tenant-Kontext → typisierter Count via `withTenantScope()`/RLS.
|
||||
- Querschnitt M001/M002/M004 wie üblich.
|
||||
|
||||
## Offene Entscheidungen (vor Bau klären)
|
||||
1. **Braucht onboarding den Entity-Bezug überhaupt?** Wenn die Onboarding-Flows in v1 keine generischen Entities mehr referenzieren (typisierte Modelle reichen / Bezug war Boilerplate), → beide Stellen **entfernen** (kleinster Pfad). Sonst über Registry typisieren.
|
||||
2. Modell-Set = Quer-Entscheidung T2 (nur relevant bei Option „typisieren").
|
||||
|
||||
## Quellen
|
||||
- `R-P14C-T2.md` (Übersicht + Registry).
|
||||
- `OnboardingService.ts:3,225`, `OnboardingFiltersService.ts` (Bestand).
|
||||
- `R-P6B.md` §Rückwirkungs-Audit (onboarding low-prio).
|
||||
- `docs/ARCHITECTURE-DECISIONS.md` AD-2.
|
||||
@@ -0,0 +1,42 @@
|
||||
# R-P14G · codeGenerator-Disposition (Entity-Builder-Werkzeug)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Dev (Code) — **Disposition/Entscheidung** |
|
||||
| **Owner** | Raffael (+ Agent) |
|
||||
| **Phase** | P6 / P14 (Entity-Builder-Ablösung, AD-2) — **Teil 2** |
|
||||
| **Plane** | neu · Child von `R-P14C-T2` |
|
||||
| **Größe** | **S** (bei Cut) / **L** (bei Rebuild — nicht empfohlen) |
|
||||
| **Status** | **ENTSCHIEDEN: CUT mit β (Raffael 2026-06-30)** — Option 1; codeGenerator wird mit dem Entity-Builder in R-P6B-β entfernt, kein eigener Bau. |
|
||||
|
||||
## ⚠️ Sonderfall: „typisiert neu bauen" passt hier nicht 1:1
|
||||
`codeGenerator` ist **kein Runtime-Konsument**, sondern ein **Meta-Werkzeug**: es generiert Quellcode (Prisma-Schema, DTOs, API, Routes, Views) **aus Entity-Builder-Definitionen** (`EntityWithDetails`/`PropertyWithDetails` als Template-Input — 27 von 29 Dateien sind Templates). Erreichbar nur über die Entity-Builder-Admin-UI (`admin/entities/code-generator/**`), die `R-P6B-β` löscht.
|
||||
|
||||
Konsequenz: Wenn der Entity-Builder stirbt, hat der Generator **keinen Input mehr** (es gibt keine generischen Entity-Definitionen, aus denen er generiert). „Typisiert neu bauen" hieße, ein Werkzeug zu bauen, das *typisierten Code aus typisiertem Code* generiert — das ergibt keinen Produktnutzen. Deshalb ist die realistische Entscheidung **Cut**, nicht Rebuild.
|
||||
|
||||
## Disposition-Optionen
|
||||
1. **Cut mit β (empfohlen):** `modules/codeGenerator` + `admin/entities/code-generator/**`-Routen werden zusammen mit dem Entity-Builder in `R-P6B-β` entfernt. Hier kein eigener Bau — nur als „gehört zu β" markieren. **Kein separater Teil-2-Aufwand.**
|
||||
2. **Jetzt schon entfernen:** Falls nachweislich 0 produktive Nutzung (interne Boilerplate-Devtool), kann es vorgezogen gelöscht werden (grep-Beweis 0 externe Konsumenten nötig, analog R-P14C S6). Spart β etwas Arbeit.
|
||||
3. **Rebuild (nicht empfohlen):** Nur falls es eine konkrete Produktanforderung „Code-Gen aus typisierten Modellen" gibt (unwahrscheinlich, nicht im Pflichtenheft).
|
||||
|
||||
## Definition of Done (bei Option 1 — Cut mit β) ✅ GEWÄHLT & ERLEDIGT
|
||||
- [x] In `R-P6B-β`-Scope aufgenommen: `modules/codeGenerator` (29 Dateien) + `admin/entities/code-generator/**` (Teil des gelöschten `admin/entities/**`-Baums) mit dem Entity-Builder entfernt.
|
||||
- [x] Keine eigene Migration nötig; in `R-P14C-T2`-Übersicht als „→ β" vermerkt.
|
||||
|
||||
## Umsetzung
|
||||
- 2026-06-30 (autonomer Lauf, Branch `feat/R-P6B-beta`): **CUT mit β umgesetzt.** `modules/codeGenerator` (29 Dateien) gelöscht; die `admin/entities/code-generator/**`-Routen fielen mit dem `admin/entities/**`-Baum. Ohne Entity-Builder-Definitionen hat das Meta-Werkzeug keinen Input mehr. Cross-Refs nachgezogen. Teil von R-P6B-β; voller CI-Scope grün.
|
||||
|
||||
## Definition of Done (bei Option 2 — jetzt entfernen)
|
||||
- [ ] grep-Beweis: 0 Konsumenten von `modules/codeGenerator` außerhalb der EB-Admin-Routen.
|
||||
- [ ] `modules/codeGenerator` + `admin/entities/code-generator/**` gelöscht; `rows-entities-runtime.json` (listet codeGenerator) + `code-generator-i18n.test.ts` + Cross-Refs nachgezogen.
|
||||
- [ ] Voller CI-Scope grün.
|
||||
|
||||
## Offene Entscheidungen (vor Bau klären)
|
||||
1. **Cut (β oder jetzt) vs. Rebuild** — Produktentscheidung Raffael. **Empfehlung: Cut mit β (Option 1)** — geringster Aufwand, kein Datenrisiko, passt zum Wegfall des Entity-Builders.
|
||||
2. Bei Option 2: ist codeGenerator wirklich rein intern (kein Kunden-Feature)?
|
||||
|
||||
## Quellen
|
||||
- `R-P14C-T2.md` (Übersicht).
|
||||
- `CodeGeneratorService.ts:1` (`EntityWithDetails` als Template-Input).
|
||||
- `docs/feature-manifests/rows-entities-runtime.json` (listet codeGenerator als `mayMoveToPlugin`).
|
||||
- `R-P6B.md` §Inventar (`modules/rows`/EB-Kern → löschen) · AD-2.
|
||||
@@ -25,7 +25,7 @@ Kein fachlicher Screen. P1 ist Plattform-Fundament; der UI-Anteil liegt komplett
|
||||
- [x] GA + ConvertKit-Einbindungen entfernt (Externals D3) *(inkl. Drop der verwaisten GA-Spalte, s.u.)*
|
||||
- [x] Kein US-Kern im Auth-Pfad (EU-Sterilität nachweisbar)
|
||||
- [x] URL-Schemata dokumentiert in `docs/INTEGRATION-CONTRACTS.md`: App, Admin (`admin.hivegrid.de`), Portal, Forms, Booking, Help, API
|
||||
- [x] Repo baut lokal durch; upstream-Remote bleibt mergebar (AD-10)
|
||||
- [x] Repo baut lokal durch; HiveGrid-Naming-Contracts ohne Alt-Aliase (AD-10)
|
||||
|
||||
## Technische Bausteine
|
||||
- **Keine neuen Entities** — nur Felder entfernen (`User.githubId/googleId` aus `accounts.prisma`/`core.prisma`). Schema-Eingriffe minimal; **db push auf Branch, Migration erst beim Merge** (AD-21).
|
||||
@@ -65,4 +65,4 @@ Kein fachlicher Screen. P1 ist Plattform-Fundament; der UI-Anteil liegt komplett
|
||||
- `staging-web.hivegrid.de/healthz` → revision `fe428e1b`; `/healthcheck` → 200 (DB erreichbar, DROP COLUMN hat nichts gebrochen); `/` → 302 (rootData lädt `AppConfiguration` ohne die Spalte fehlerfrei → Schema/Code konsistent).
|
||||
- **Infra-Lernpunkt:** Der erste Deploy-Versuch von `fe428e1b` schlug fehl — **nicht** wegen Code/Migration, sondern transientes `429 Too Many Requests` der Gitea-Docker-Registry beim Layer-Push (Build-Cache). Migration lief dabei gar nicht erst (Build brach davor ab), Staging blieb stabil auf `c2a31a2b`. Ein **Rerun** löste es. Gleiches Muster traf zuvor `2f740f2a`. Wiederkehrend → Registry-Rate-Limit/Build-Cache ist ein Infra-Thema (Akeshan), kein App-/P1-Code-Problem.
|
||||
|
||||
**Proof:** `@toolctrl/config` 101/101 grün · Web-Typecheck grün · ESLint `--max-warnings=0` grün · alle betroffenen Tests grün · volle Suite 3698 grün · **Staging live auf `fe428e1b`, healthcheck 200**.
|
||||
**Proof:** `@hivegrid/config` 101/101 grün · Web-Typecheck grün · ESLint `--max-warnings=0` grün · alle betroffenen Tests grün · volle Suite 3698 grün · **Staging live auf `fe428e1b`, healthcheck 200**.
|
||||
@@ -53,7 +53,7 @@ Kein fachlicher Screen — reine Service-Kerne (Backend). Die Bedien-Oberfläche
|
||||
- **Audit + SHA-256-Hash-Kette:** `packages/db/audit-hash.ts` (`computeAuditHash`/`verifyAuditChain`/`canonicalizeAuditPayload`) + `audit-events.server.ts` (`createAuditEvent`/`publishAuditEventViaOutbox`), getestet (`audit-hash.test.ts`, `audit-events.server.test.ts`).
|
||||
- **`notify()`** Kanal-Abstraktion (In-App/Email, Push-Stub) in `packages/foundation/notifications.ts`.
|
||||
- **i18n + `verify:i18n`-Gate:** `packages/i18n` + `pnpm run verify:i18n` (i18n-check + hardcoded-strings + eslint auf ui-Paketen), grün.
|
||||
- **`logActivity()`** (`@toolctrl/activity`), **Search-Registry** (`indexedEntities`/`listIndexedEntities`, `@toolctrl/search`), **Subframe-Adapter** (`defineAdapter`, `@toolctrl/ui-app`), **Mass-Action-Schutz** (`previewMassAction`/`assertMassActionAllowed`, `@toolctrl/foundation`) — alle exportiert/callable.
|
||||
- **`logActivity()`** (`@hivegrid/activity`), **Search-Registry** (`indexedEntities`/`listIndexedEntities`, `@hivegrid/search`), **Subframe-Adapter** (`defineAdapter`, `@hivegrid/ui-app`), **Mass-Action-Schutz** (`previewMassAction`/`assertMassActionAllowed`, `@hivegrid/foundation`) — alle exportiert/callable.
|
||||
|
||||
**Neu gebaut = der Konnektor (die eigentliche Lücke):**
|
||||
- `apps/web/app/utils/connector/tenantConnector.server.ts` mit dem kanonischen Pflicht-Gate:
|
||||
@@ -66,3 +66,16 @@ Kein fachlicher Screen — reine Service-Kerne (Backend). Die Bedien-Oberfläche
|
||||
- **Default-on Auto-Audit-Prisma-Middleware:** Die Hash-Kette + explizites `auditEvent`/`createAuditEvent` sind vorhanden und der **richtige** Pfad. Eine auto-Middleware am geteilten Prisma-Client ohne request-scoped Actor-Kontext (AsyncLocalStorage) erzeugt actor-lose Events (schlechter als die expliziten Aufrufe mit vollem Kontext) und ist ohne lokalen DB-Zugriff nicht validierbar. Querschnitt-Tabelle erlaubt explizit „auto via Middleware **oder** manuell auditEvent". → ALS/Auto-Audit als separater Infra-Schritt.
|
||||
|
||||
**Proof:** Konnektor 6/6 · Web-Typecheck grün · `verify:i18n` Exit 0 · volle Suite grün (siehe R-P1c-Abschluss).
|
||||
|
||||
## Querbezug AK-P3 (dependency-aware, 2026-07-07 — Akeshan)
|
||||
|
||||
AK-P3 (DoD 2, Diff-Detail-Drawer) hat die im LOCKED `ENTITY-MODEL.md` §Domäne 2 geforderten Spalten
|
||||
**`beforeDiff`/`afterDiff` (Json?) + `summaryText` (String?)** additiv an `AuditEvent` (`core.prisma`) ergänzt
|
||||
(Branch `akeshan/ak-p3-interim-ui`; Owner-Freigabe für die core.prisma-Berührung liegt vor, 2026-07-06):
|
||||
- **Additiv/nullable** — bestehende Rows/Caller bleiben gültig; `buildAuditEventCreateData` nimmt die Felder
|
||||
optional entgegen (gleicher Metadata-Sanitizer, Redaction at write time) und der Outbox-Pfad reicht sie durch.
|
||||
- **Bewusst NICHT im `eventHash`-Digest:** das Chain-Payload-Format ist eingefroren; eine Aufnahme würde
|
||||
`verifyAuditChain` für alle Bestandszeilen brechen. **Offen bei R-P1b/Raffael:** Diffs in die Hash-Kette
|
||||
binden (Chain-Format-Versionierung) + flächige Befüllung der Diffs über die Schreibpfade
|
||||
(Auto-Audit-Middleware, siehe „Bewusst aufgeschoben" oben).
|
||||
- Konsumenten-Tests grün (audit-events 12/12, worker persist 11/11 + bootstrap 6/6, outbox-e2e).
|
||||
@@ -56,14 +56,14 @@ Die **Hot-Swap-Maschine** (VM-Konvention + Action-Callback-Contract + Subframe-A
|
||||
|
||||
**Ausgangslage:** Hot-Swap-Maschine + ui-mock + Visual-Regression-Gate lagen schon vor und sind grün
|
||||
(`pnpm run test:hot-swap` → „UI hot-swap drill verified", `pnpm run verify:ui-visual` → 7 passed).
|
||||
VM-/Action-Callback-/Subframe-Adapter-Typen existieren in `@toolctrl/view-models` + `defineAdapter` in `@toolctrl/ui-app`.
|
||||
VM-/Action-Callback-/Subframe-Adapter-Typen existieren in `@hivegrid/view-models` + `defineAdapter` in `@hivegrid/ui-app`.
|
||||
|
||||
**Neu gebaut:**
|
||||
- **VM-Konvention exemplarisch (M013):** `packages/view-models/src/walking-skeleton/walking-skeleton.vm.ts` — reine `buildWalkingSkeletonVM()`, `*.vm.ts`, `VMState`, nur i18n-Keys (kein Klartext). + Tests.
|
||||
- **Konnektor→Sidebar-3-Zustände:** `apps/web/app/utils/connector/connectorNavState.ts` (`resolveConnectorNavState` → `active`/`locked`/`hidden`) + Tests für alle drei.
|
||||
- **Walking-Skeleton-Route:** `apps/web/app/routes/app.$tenant/walking-skeleton.tsx` — Loader baut das VM **im Loader** und wendet das Konnektor-Pflicht-Gate `tenantHasModule()` (aus R-P1b) exemplarisch an; Component rendert minimal je Zustand (`data-ui-id="ui.walkingSkeleton.page"`, `data-connector-state`). + Loader-/Component-Tests.
|
||||
- **Sidebar-Registrierung:** `AppSidebar.tsx`-Eintrag, gegated über `resolveConnectorNavState` auf Basis der productAccess-Entscheidung; `appData.ts` wertet das Demo-Modul `walking-skeleton` mit aus. Für reale Tenants `blueprint-disabled` → Zustand **hidden** (kein Clutter), bis das Modul bewusst einem Blueprint zugeordnet wird.
|
||||
- **PWA-Manifest:** `apps/web/public/manifest.webmanifest` von „Toolctrl Boilerplate" auf **HiveGrid** umgebrandet (`lang: de`), installierbar (PWA-only v1, AD-17).
|
||||
- **PWA-Manifest:** `apps/web/public/manifest.webmanifest` von „HiveGrid Boilerplate" auf **HiveGrid** umgebrandet (`lang: de`), installierbar (PWA-only v1, AD-17).
|
||||
- **Smoke gegen ui-mock:** `apps/web/app/modules/walkingSkeleton/walkingSkeleton.hot-swap.test.ts` (VM als ui-mock-Drop-in via `generateMockArtifacts` — beweist Hot-Swap-Tauglichkeit). + e2e-Smoke `tests/e2e/walking-skeleton.spec.ts` (Login→Route→Seite, skippt ohne E2E-Creds; läuft im CI/Staging-e2e-Job, lokal kein Playwright-Server).
|
||||
- **i18n:** `walkingSkeleton.*`-Keys in `de` + `en` (Parität, `verify:i18n` grün).
|
||||
|
||||
|
||||
@@ -8,6 +8,8 @@
|
||||
| **Cycle/Fenster** | W1 — Fundament & Identität · fällig 2026-06-19 · Gate W1 |
|
||||
| **Status** | geplant |
|
||||
|
||||
**🎨 design-nachzug: offen** (seit 2026-07-06) — Interim-UI (`new-account` „Workspace anlegen / ohne Tenant") aus `~/ui` steht; finale Subframe-Optik aus `D-P2` (Signup/2FA/Geräteliste/Tenant-Auswahl/new-account) ausstehend, nicht Done-blockierend (AD-28).
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `R-P1b` (Service-Kerne + Konnektor), `EXT-12` (Geo-IP + HIBP anbinden), `AK-INFRA2` (mCaptcha per ENV)
|
||||
- **Blocks:** `R-P2b` (RLS-Härtung baut auf dem Auth-/Tenant-Kern auf)
|
||||
@@ -31,12 +33,13 @@ Den **Auth- und Mandanten-Kern**: Self-Service-Signup, der Tenant + auto-generie
|
||||
*(Davids P2-Screens werden über das Ticket `D-P2` geliefert — komponiert aus `D-D0a`/`D-D0b`.)*
|
||||
|
||||
## Definition of Done
|
||||
- [ ] Self-Service-Signup + Auto-Slug (Reserved-Words geblockt) + Auto-SHK-Seed
|
||||
- [ ] Login Email/PW + **HIBP-Breach-Block** (NIST) + Brute-Force (mCaptcha ab 3. Fehlversuch) + Magic-Link-Alternative
|
||||
- [ ] **TOTP-2FA** (RFC 6238, QR-Setup + Trust-Device)
|
||||
- [ ] **Sessions Postgres-SoT + Redis-Cache** (AD-4): Geräte-Liste, Revoke einzeln, „überall abmelden"
|
||||
- [ ] Multi-Tenant-Membership + Tenant-Auswahl-Screen
|
||||
- [ ] Konnektor: alle Auth-/Settings-Routen sitzen im App-Shell-Gating (R-P1c)
|
||||
> Alle Bausteine code-seitig gebaut + getestet (3741 Tests grün, Branch `p2a-auth-tenant`). Haken = umgesetzt; finale Screen-Optik/Abnahme läuft über `D-P2` (Ticket steht daher auf **Blocked / wartet-auf-screen**, nicht Done).
|
||||
- [x] Self-Service-Signup + Auto-Slug (Reserved-Words geblockt) + Auto-SHK-Seed *(Signup+Slug fertig; Auto-SHK-Seed bewusst → P6, da CRM-Entitäten erst dort existieren)*
|
||||
- [x] Login Email/PW + **HIBP-Breach-Block** (NIST) + Brute-Force (mCaptcha ab 3. Fehlversuch) + Magic-Link-Alternative
|
||||
- [x] **TOTP-2FA** (RFC 6238, QR-Setup + Trust-Device)
|
||||
- [x] **Sessions Postgres-SoT + Redis-Cache** (AD-4): Geräte-Liste, Revoke einzeln, „überall abmelden"
|
||||
- [x] Multi-Tenant-Membership + Tenant-Auswahl-Screen *(Backend + Routen fertig; finale Screen-Optik via `D-P2`)*
|
||||
- [x] Konnektor: alle Auth-/Settings-Routen sitzen im App-Shell-Gating (R-P1c)
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (eigene `prisma/schema/accounts.prisma` bzw. `auth.prisma`): `Tenant` (slug, status trial/active/past_due/frozen/suspended/deletion_pending, default_language), `User` (email, language, timezone, theme_preference — **global, kein RLS**), `TenantUser`, `Session` (Postgres-SoT + Redis-Cache, browser_fingerprint), `TenantUserInvitation` (48h, Anlage hier vorbereitet). Boilerplate-`ApiKey`-Modell bleibt **ungenutzt** (Scope-Schnitt → v2, nicht in Sidebar).
|
||||
@@ -52,9 +55,20 @@ Den **Auth- und Mandanten-Kern**: Self-Service-Signup, der Tenant + auto-generie
|
||||
- `_bmad-output/specs/M27-auth-multi-tenancy.md`
|
||||
|
||||
## Dev-Nachzug (nach Davids `D-P2`-Delta)
|
||||
- [x] **Interim-UI aus `~/ui` gebaut (AD-28, 2026-07-06, Akeshan-Beitrag).** Der bisher einzige
|
||||
handgeschriebene Auth-Screen `new-account` („Workspace anlegen / ohne Tenant") ist jetzt aus `~/ui`
|
||||
komponiert (`apps/web/app/components/screens/auth/CreateWorkspacePage.tsx`, `AuthShell` + `~/ui`,
|
||||
VM/Props als Prop, kein handgeschriebenes Tailwind, Fehler als inline `Alert` statt Legacy-`ErrorModal`);
|
||||
die Route rendert nur noch `<CreateWorkspacePage … />`, die Legacy-`TenantNew` wurde abgelöst/gelöscht.
|
||||
Die übrigen sechs Auth-Screens (Signup/Login/2FA/Forgot/Tenant-Auswahl/Security/Profil) liefen bereits
|
||||
auf `~/ui` (Davids WF-P2/D-P2). Zusätzlich M015/M017-Hot-Swap-Stack für die zwei VM-Screens nachgezogen
|
||||
(session-list, select-tenant): view-models-Mapper + ui-subframe/ui-mock-Renderer + ui-app-Adapter + Tests.
|
||||
Stabile Marker (`ui.account.create.*`) erhalten, Smoke `tests/e2e/new-account.spec.ts` ergänzt.
|
||||
- [ ] **Finale Subframe-Optik aus `D-P2`** (Signup/2FA/Geräteliste/Tenant-Auswahl/new-account) — Swap hinter
|
||||
der stabilen VM/Loader-Grenze; `design-nachzug: offen`, Plane-Label `design-nachzug`. Nicht Done-blockierend (AD-28).
|
||||
- [ ] Auth-Flows an Davids UI-Entscheidungen angepasst (Signup-Felder, 2FA-Flow)
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
- [ ] Plane-Ticket `R-P2a` aktualisiert
|
||||
- [x] Plane-Ticket `R-P2a` aktualisiert (Kommentar + Label `design-nachzug`)
|
||||
|
||||
## Umsetzungsstand (Claude, 2026-06-18 — Code-seitig, finale Abnahme mit Davids `D-P2` morgen)
|
||||
|
||||
@@ -147,6 +161,32 @@ Den **Auth- und Mandanten-Kern**: Self-Service-Signup, der Tenant + auto-generie
|
||||
war nicht erreichbar, daher db push offen — Migration ohnehin beim Merge). Branch `p2a-auth-tenant`
|
||||
(10 Commits), noch nicht nach `main` gemergt (finale Abnahme mit `D-P2`).
|
||||
|
||||
## Umsetzungsstand (Akeshan, 2026-07-06 — Interim-UI aus `~/ui` (AD-28) + Hot-Swap-Layer)
|
||||
|
||||
> Branch `p2a-newaccount-interim-ui` (Akeshan-Beitrag auf Raffaels Ticket). Bestandsaufnahme: die in
|
||||
> der 06-19-Notiz als „minimale Inline-UI als Swap-Ziel" beschriebenen Auth-Screens waren im Arbeitsbaum
|
||||
> **bereits auf `~/ui` gehoben** (Davids WF-P2/D-P2) — Signup/Login/2FA/Forgot/Tenant-Auswahl/Security/
|
||||
> Profil. Einziger echter handgeschriebener Rest: `new-account`.
|
||||
|
||||
**Gebaut:**
|
||||
- **Interim-Screen `CreateWorkspacePage`** (`apps/web/app/components/screens/auth/`) aus `AuthShell` + `~/ui`
|
||||
(`TextInput`/`Button`/`Alert`/`LinkButton`), VM/Props als Prop, kein handgeschriebenes Tailwind. Route
|
||||
`new-account.tsx` verschlankt (Loader/Action unverändert), Legacy `TenantNew` abgelöst/gelöscht. Fehler
|
||||
jetzt inline `Alert` statt `ErrorModal`; e2e-Fehlerpfad + Smoke `tests/e2e/new-account.spec.ts` nachgezogen.
|
||||
- **M015/M017-Hot-Swap-Stack** für die zwei VM-Screens: `toSessionListModel`/`toSelectTenantModel` +
|
||||
Model-Typen (view-models), `renderSessionList`/`renderSelectTenant` (ui-subframe), `…Mock` (ui-mock),
|
||||
`sessionListAdapter`/`selectTenantAdapter` (ui-app) + `.hot-swap.test.ts`. Schließt DoD D18/D20 für die
|
||||
zwei VM-gestützten Auth-Screens (session-list, select-tenant).
|
||||
|
||||
**Proof (2026-07-06):** isolierte vitest-Suiten grün (39/39: CreateWorkspacePage 3 · adapter hot-swap 6 ·
|
||||
model-mapper 8 · VM 14 · ui-subframe/ui-mock index 4 · acquisition 4) · Typecheck `web`/`view-models`/
|
||||
`ui-subframe`/`ui-mock`/`ui-app` grün (ui-app-Fixture `filterOptions` nachgezogen) · `verify:i18n` 0 ·
|
||||
`verify:cross-cutting-models` 178/178 · `verify:sidebar-routes` 27/27 · Lint grün, keine neuen Escape-Hatches.
|
||||
Windows-Umgebung: `test:hot-swap` (tsx-ESM) + einige undici-`new Request`-Tests fallen environmental (Node
|
||||
22.15) → CI (Node 22.12) grün. Nicht nach `main` gemergt (PR-Review folgt).
|
||||
|
||||
**Offen (nicht Done-blockierend, AD-28):** finale Subframe-Optik aus `D-P2` (`design-nachzug: offen`).
|
||||
|
||||
## Status (Stand 2026-06-19)
|
||||
**Backend ~100 % · Ticket-Abschluss wartet auf `D-P2` (David).** Alle eigenständig baubaren Bausteine
|
||||
(Signup, Login+HIBP+Brute-Force, Server-Sessions+Revoke, TOTP-Enrollment, 2FA-Login-Gate, Trust-Device
|
||||
|
||||
@@ -8,6 +8,8 @@
|
||||
| **Cycle/Fenster** | W1 — Fundament & Identität · fällig 2026-06-19 · **Gate W1 (RLS-Gate-Beweis)** |
|
||||
| **Status** | geplant |
|
||||
|
||||
**🎨 design-nachzug: offen** (seit 2026-07-07) — RBAC-Screens nach Davids `D-P2`-Review-Stand (2026-06-26) umgesetzt; offen: Gruppen-Bulk-Optik (Interim aus `~/ui`, David-Backlog RBAC V2), Abteilung-Spalte (S01) und Bereich/Kategorie-Feld (M04, keine Modell-Felder) sowie evtl. Deltas aus Davids D-P2-Review.
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `R-P2a` (Auth/Tenant/Sessions)
|
||||
- **Blocks:** **Gate W1** + **alle Tenant-Daten-Module** (ohne nachgewiesene RLS-Isolation darf kein Fach-Modul tenant-bezogen ausliefern)
|
||||
@@ -125,3 +127,61 @@ RLS-Gate-Beweis, 6 SHK-Rollen (Partner-final, geseedet), Gruppen+Bulk, Lifecycle
|
||||
(2026-06-19). **Selbst machbar offen: 0.** **Blockiert:** Davids `D-P2`-Screens (Rollen-Editor mit
|
||||
Advanced-Einzelrechte, Gruppen, Mitarbeiter, Lösch-Wizard) + screen-abhängige generische DoD
|
||||
(Reachability/Visual-Regression/Smoke). **Nicht R-P2b-Scope:** app-weiter RLS-Rollout (P5+).
|
||||
|
||||
## Umsetzungs-Notiz 2026-07-07 (Akeshan, Zulieferung) — D-P2-Screens eingebaut, Screen-DoD geschlossen
|
||||
|
||||
> Davids `D-P2`-Handoff (2026-06-26, `WF-P2 Admin RBAC` „In Subframe/Review") hat die Screen-Blockade
|
||||
> aufgelöst. Branch `akeshan/r-p2b-rbac-screens` (off main), Commits `22e9923a9`…`3fcbbfb6e`.
|
||||
> Ich habe die offenen UI-Teile nach Davids Wireframes/Design-Standards gebaut; Backend blieb unverändert
|
||||
> (einzige Ergänzung: Bulk-Intents an der bestehenden Gruppen-Action).
|
||||
|
||||
**Gebaut (David-Optik, `WF-P2 Admin RBAC`):**
|
||||
- **S01 Mitarbeiterliste** (`components/screens/users/MembersPage.tsx`): Suche + Rolle/Status/2FA-Filter,
|
||||
Eingeladene inline mit Status „Eingeladen", **D01 Inline-Rollen-Dropdown** (nutzt den bestehenden
|
||||
`edit`-Intent inkl. SuperUser-Guard), deaktivierte Mitglieder bleiben sichtbar (`includeInactive`).
|
||||
- **M03 Deaktivieren** + **V01 Letzter-Admin-Blocker**: `deactivateTenantUser`/`reactivateTenantUser`
|
||||
endlich verdrahtet (neue Intents `deactivate`/`reactivate`); Last-Admin-Guard kommt als Code
|
||||
`last-admin` zurück und öffnet den V01-Dialog (Copy wörtlich aus dem Wireframe). **Ohne Reassign** —
|
||||
Davids v1-Entscheidung; das Backend-Reassign bleibt als API bestehen.
|
||||
- **M01 Einladen** als echter Dialog (S 560) statt Slide-Over (`InviteMemberForm`), Invite-Contract
|
||||
(Felder/CSRF/48h/`data-ui-id`s) unverändert. Rolle-bei-Einladung NICHT gebaut (Invitation speichert
|
||||
keine Rolle — Rollen kommen nach Annahme via D01).
|
||||
- **S02 Rollen und Berechtigungen** (`RolesPage.tsx`): zusammengelegter Tab (alte `/users`-Matrix →
|
||||
Redirect auf Mitarbeiter, `/permissions` → Redirect auf Rollen), Typ-Spalte (System/Eigene),
|
||||
Mitglieder-/Berechtigungs-Zähler; Settings-Icon-Tab „Rollen" nur noch als Fallback ohne
|
||||
`members.view` (sonst Tab-Leiste in S01/S02).
|
||||
- **M04A Rolle anlegen / M04B Rolle duplizieren → M02 Rollen-Editor** (L 1200): Sidebar-Sections aus
|
||||
reiner Scope→Section-Map (`role-editor.vm.ts`, KEINE neuen Permission-Keys), Suche, Toggle-Zeilen;
|
||||
speichert über die unveränderten `new`/`$id`-Action-Contracts. **Duplizieren = Create mit vorgeladenem
|
||||
Permission-Set der Quelle** (gleicher auditierter `createWorkspaceRole`-Pfad, kein neues Backend).
|
||||
Löschen mit **D03-Blocker** bei Mitgliedern > 0. Damit ist der Nachtrag vom 2026-06-22 (Editor
|
||||
deferred bis P6–P9) durch Davids geliefertes M02-Design überholt — bitte im Review bestätigen.
|
||||
- **Gruppen Bulk-Add/Remove** (Interim, AD-28 — David-Backlog): `GroupMembersDialog` (M 720) an
|
||||
`settings/groups`, neue idempotente Intents `bulk-add`/`bulk-remove` auf
|
||||
`addUsersToGroup`/`removeUsersFromGroup` (Tenant-Membership validiert, `createLog`-Audit).
|
||||
- **VMs** `packages/view-models/src/users/` (members-list/roles-list/role-editor/groups-detail, pure,
|
||||
27 Unit-Tests) · **Hot-Swap-Kette** `membersList`/`rolesList` (Adapter + Subframe-/Mock-Renderer,
|
||||
M015/M017) · **Smoke** `tests/e2e/members-roles.spec.ts` (nicht-mutierend) · a11y-Specs
|
||||
(`tenant-members`, `tenant-roles-permissions.*`) auf die neue Struktur nachgezogen · i18n de/en.
|
||||
|
||||
**Proof:** Typecheck (web/view-models/ui-app/ui-mock/ui-subframe) grün · `verify:i18n`/`verify:sidebar-routes`/
|
||||
`verify:cross-cutting-models` Exit 0 · 376 Tests grün über die betroffenen Suiten (members-Route 13/13 neu;
|
||||
`roles.test.tsx`-Restfehler = bekannter Node-22.15-undici-Umgebungsfehler, identisch auf main) ·
|
||||
KEIN Prisma-Schema-Change (Abteilung/Kategorie/Rollen-Status bewusst weggelassen statt Spalten zu erfinden).
|
||||
|
||||
**Offen / geflaggt:**
|
||||
- **Bewusst NICHT gebaut:** Konto-Lösch-Wizard (Davids jüngere Entscheidung 2026-06-26: Backlog bis
|
||||
Workspace-Settings; DSGVO-Self-Service existiert unter `/settings/privacy`) · Reassign-Panel (V2) ·
|
||||
„Einladung erneut senden" (kein Backend) · Rolle-bei-Einladung (kein Invitation-Feld).
|
||||
- **Produkt-Widerspruch SHK-Seeds vs. „nur Admin" — ENTSCHIEDEN 2026-07-07 (Akeshan, → AD-29):** Die 6
|
||||
SHK-Seed-Rollen bleiben auf **Staging/Dev als Test-Komfort**; auf **Produktion startet ein frischer
|
||||
Tenant nur mit der Admin-Systemrolle** (Davids validierte D-P2-Entscheidung). Umgesetzt als Gate in
|
||||
`seedShkRolesForTenant` (`shouldSeedShkRoles`): `SENTRY_ENVIRONMENT=production` ⇒ kein Seed
|
||||
(NODE_ENV ist auf Staging-Containern auch „production", daher entscheidet die deploy-scoped Variable);
|
||||
Override per `SEED_SHK_ROLES=true|false`, falls der Partner die Seeds produktiv doch will. 8 Tests.
|
||||
- Alt-Komponenten (`MembersListView`, `RolesListView`, `NewMember`, `RolesAndPermissionsMatrix`,
|
||||
`MemberInvitationsListAndTable`) sind jetzt verwaist — Aufräumen als Folge-Cleanup.
|
||||
|
||||
**%-Stand: fachliche DoD 5/5 = 100 % · screen-abhängige generische DoD (B6–10, D18–21) jetzt erfüllt**
|
||||
(Visual über die deterministischen Renderer-/Hot-Swap-Snapshots wie bei AK-P3; Gruppen-Optik als
|
||||
`design-nachzug` markiert, s. Header-Tag). Done-Status nur mit Freigabe/Review durch Raffael.
|
||||
@@ -8,7 +8,9 @@
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | P5 — Apps-Engine & Integrations-Framework |
|
||||
| **Cycle/Fenster** | W2 — Plattform & CRM (Demo 1) · fällig 2026-06-21 · Gate W2 (Noah-Demo #1) |
|
||||
| **Status** | geplant |
|
||||
| **Status** | **done (2026-07-07)** — 10/10 DoD = 100 %; Backend seit 2026-06-28, Interim-UI (AD-28) + Run-Detail + Katalog-Seed via PR #50, Sidebar-Reachability-Fix via PR #51; Plane auf Done, Label `design-nachzug` gesetzt |
|
||||
|
||||
**🎨 design-nachzug: offen** (seit 2026-07-07) — Interim-UI aus `~/ui` steht; finale Subframe-Optik aus `D-P5` ausstehend.
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `R-P2b` (RLS + Permissions — DataConnection ist tenant-bezogen + verschlüsselt)
|
||||
@@ -17,7 +19,7 @@
|
||||
- **Konflikt-Risiko:** gering — db push auf Branch, Migration erst beim Merge.
|
||||
|
||||
## Was wir bauen
|
||||
Das **eine, typsichere Integrations-Framework**, über das später Gmail, Outlook, AirCall, PandaDoc, Stripe und KWP laufen. Ein Admin stellt eine `DataConnection` über **OAuth2-Connect** oder **API-Key-Connect** in der Settings-UI her; die **type-safe Adapter-Registry** erlaubt neue Connection-Typen ohne Kern-Änderung (Build-Time-Scan, Drift-Check); `AppSyncRun`/`AppSyncItem`/`AppSyncRunLog` protokollieren Sync-Läufe in Klartext; **Connection-Health-Monitoring** zeigt active/degraded/broken/revoked/pending mit Klartext + Lösungs-Hinweisen; **OAuth-Tokens per-Tenant-DEK-verschlüsselt** (AD-8). Mehrere Connections pro App pro Tenant (z.B. drei Gmail-Mailboxen).
|
||||
Das **eine, typsichere Integrations-Framework**, über das später Gmail, Outlook, AirCall, Signatur-Adapter (SES-Default/PandaDoc-BYOK), Legacy-Provider und KWP laufen. Ein Admin stellt eine `DataConnection` über **OAuth2-Connect** oder **API-Key-Connect** in der Settings-UI her; die **type-safe Adapter-Registry** erlaubt neue Connection-Typen ohne Kern-Änderung (Build-Time-Scan, Drift-Check); `AppSyncRun`/`AppSyncItem`/`AppSyncRunLog` protokollieren Sync-Läufe in Klartext; **Connection-Health-Monitoring** zeigt active/degraded/broken/revoked/pending mit Klartext + Lösungs-Hinweisen; **OAuth-Tokens per-Tenant-DEK-verschlüsselt** (AD-8). Mehrere Connections pro App pro Tenant (z.B. drei Gmail-Mailboxen).
|
||||
|
||||
> ⚙️ **Recut (KWP → v2):** KWP = `DataConnection type='rest-api'` (API-Key-Connect) — **kein `kwpsync.exe`-Windows-Client-Flow** (Scope-Schnitt #12). `windows_client` bleibt im Datenmodell, hat in v1 keinen UI-Flow. Apps selbst werden erst in ihren Modul-Phasen (P14/P15/P16/P20) angedockt — P5 liefert nur das Framework + die generische Katalog-/Wizard-UI.
|
||||
|
||||
@@ -32,16 +34,16 @@ Das **eine, typsichere Integrations-Framework**, über das später Gmail, Outloo
|
||||
*Davids P5-Screens über `D-P5` (Compose aus D0; Connection-Card als wiederverwendbares Element).*
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **DataConnection** per OAuth2-Connect (Gmail/Outlook/AirCall/PandaDoc/Google Calendar) **oder** API-Key-Connect (KWP/Stripe) in Settings-UI herstellbar
|
||||
- [ ] **Type-safe Adapter-Registry** (Build-Time-Scan von `app/integrations/`, Drift-Check → Klartext-Warnung im Plattform-Admin) — neue Typen ohne Kern-Änderung
|
||||
- [ ] **AppSyncRun/AppSyncItem/AppSyncRunLog** mit Klartext-Summary
|
||||
- [ ] **Connection-Health-Monitoring** (active/degraded/broken/revoked/pending) + Token-Refresh-Worker + degraded/broken → `notify()` an Tenant-Admin
|
||||
- [ ] **OAuth-Tokens per-Tenant-DEK-verschlüsselt** (AD-8)
|
||||
- [ ] Lifecycle: Connect-Wizard / Reconnect (gleiche ID, kein History-Verlust) / Disconnect (Multi-Step-Confirm, Status revoked statt Hard-Delete)
|
||||
- [ ] Mehrere DataConnections pro App pro Tenant (mit User-Label)
|
||||
- [ ] Manueller Re-Sync + Schema-Drift-Sentinel + Webhook-Storm-Schutz
|
||||
- [ ] Permissions: `integrations.read/.connect/.disconnect/.manual_sync/.view_logs/.admin`
|
||||
- [ ] *(→ v2)* `kwpsync.exe`-Windows-Client-Flow ausgeschlossen (KWP = rest-api)
|
||||
- [x] **DataConnection** per OAuth2-Connect oder API-Key-Connect — *Backend (createConnection: Adapter-Validierung + Envelope-Crypto) + funktionale Route-Action fertig; finale Wizard-Optik = Davids D-P5.*
|
||||
- [x] **Type-safe Adapter-Registry** (Drift-Check → Klartext-Warnung) — neue Typen ohne Kern-Änderung
|
||||
- [x] **AppSyncRun/AppSyncItem/AppSyncRunLog** mit Klartext-Summary
|
||||
- [x] **Connection-Health-Monitoring** + Token-Refresh-Worker + degraded/broken → `notify()` — *Health-Probe + notify + Worker-Crons (token-refresh 5m, health-sweep 15m) über geteiltes @hivegrid/integrations-Paket.*
|
||||
- [x] **OAuth-Tokens per-Tenant-DEK-verschlüsselt** (AD-8)
|
||||
- [x] Lifecycle: Connect / Reconnect (gleiche ID, kein History-Verlust) / Disconnect (Status revoked statt Hard-Delete) — *Backend + Route-Actions; finale Wizard-Optik = D-P5.*
|
||||
- [x] Mehrere DataConnections pro App pro Tenant (mit User-Label)
|
||||
- [x] Manueller Re-Sync + Schema-Drift-Sentinel + Webhook-Storm-Schutz (`triggerWebhookSync` via `withIdempotency`)
|
||||
- [x] Permissions: `integrations.read/.connect/.disconnect/.manual_sync/.view_logs/.admin`
|
||||
- [x] *(→ v2)* `kwpsync.exe`-Windows-Client-Flow ausgeschlossen (KWP = rest-api)
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (eigene `prisma/schema/apps.prisma`): `App` (key, category, connection_type oauth2/api_key, connection_schema, phase — **global, kein RLS**), `DataConnection` (tenant_id, app_id, credentials **verschlüsselt**, connection_status, last_health_check), `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem` (entity_type/id ↔ external_id, polymorph). `core.prisma` nur für Tenant-Relationen berühren (AD-21).
|
||||
@@ -59,7 +61,71 @@ Das **eine, typsichere Integrations-Framework**, über das später Gmail, Outloo
|
||||
- `_bmad-output/specs/M33a-apps-engine.md` (⚠ alte Drei-Komponenten-KWP-Architektur **nicht** bauen — Recut)
|
||||
- `docs/ARCHITECTURE-DECISIONS.md` → AD-8 (per-Tenant-DEK)
|
||||
|
||||
## Umsetzungs-Notiz
|
||||
|
||||
> **✅ Stand 2026-06-28 — auf `main` gemergt.** R-P5 lief über den gemeinsamen Branch `feat/AK-P17a` und ging mit **PR #5** (squash, Merge-Commit `b0fae1af8`, Base `main`, 2026-06-28 17:50) auf `main`. Nachzug-Fix `packages/integrations/package.json` im Docker-deps-Target via **PR #8** (`0b9d2e46`, 18:05). Alle R-P5-Artefakte (`appsEngineService`, `@hivegrid/integrations`, `crypto.prisma`/`appsEngine.prisma`, Worker-Crons, Admin-Routen-Hülle) liegen im `main`-Tree. *Die älteren „Branch lokal, nicht gepusht"-Notizen unten sind damit überholt.* **Backend 9/9 DoD grün.** Extern offen bleibt nur: Davids `D-P5`-Optik, RLS-Live/Visual-Regression gegen Staging-DB, ~~App-Tabellen-Katalog-Seed (deferred)~~ *(Seed am 2026-07-07 nachgezogen, s.u.)*, Plane-Ticket auf Done.
|
||||
|
||||
**2026-06-27 (Akeshan) — Backend-Kern + Crypto-Fundament, Branch `feat/R-P5` (lokal, nicht gepusht).**
|
||||
|
||||
R-P5 an Akeshan übergeben (Plane: Assignee Akeshan). Gebaut in 6 Commits, jeweils mit grünem lefthook:
|
||||
- `b5aa98b` **Per-Tenant-DEK-Envelope-Crypto (DoD #5)** — `packages/foundation/crypto` (seal/open + KeyWrapper, CRYPTO_SECRET jetzt, Vault später swappbar) + `packages/db/crypto/tenant-envelope.server.ts` (DEK je Tenant, Crypto-Shredding) + `crypto.prisma`. 16 Tests grün. **Entsperrt AK-P17a** (dort nur noch Seam-Rebind).
|
||||
- `aed2a8b` **Schema an ENTITY-MODEL Domäne 4** — App global, DataConnection (+Status/Token/Label/credentialsCiphertext/is_demo_data), Sync-Modelle; RLS-SQL deferred; Consumer (cli/dsgvo) nachgezogen.
|
||||
- `51b6b59` **Permissions + Entitlements (DoD #9)** — `integrations.*` + Grants + DefaultPermissions-Union; `integrations`-Feature/Blueprint/Plan; `tenantHasModule('integrations')`.
|
||||
- `50bb9dd` **Adapter-Registry + Drift (DoD #2)** — `IntegrationAdapter`-Contract + Registry + `checkCatalogDrift` (foundation) + Katalog + `sample-data-sync`-Referenz-Adapter + Drift-Gate-Test.
|
||||
- `f2ea4d2` **Domain-Service (DoD #1/#3/#6/#7 + #4-Health + #8-Re-Sync)** — Lifecycle connect/reconnect/disconnect (Envelope-Crypto + Adapter-Validierung + Audit), Sync-Run/Item/Log, Health-Probe + notify; `withTenantRLS`, Credentials nie in List-VMs. Pure `aggregateSyncOutcome` getestet.
|
||||
- `0ab0f3a` **RLS-Gate-Test (env-gegatet) + i18n** (de+en).
|
||||
|
||||
**DoD-Stand: 6/9 voll grün** (#2, #3, #5, #6, #7, #9) + Schema + v2-Ausschluss (KWP `windows_client` nur Datenmodell). **Backend von #1 fertig** (UI-Wizard blockiert durch D-P5). **Teil-offen:**
|
||||
- **#4 Token-Refresh-Worker** — *architektonisch blockiert:* der Worker hängt nur an `@hivegrid/db`, erreicht die Adapter (in `apps/web/app/integrations`) nicht. Provider-seitiger Token-Refresh braucht ein **geteiltes Adapter-Paket** (web+worker). Health-Probe + notify (web-seitig) ist fertig; die zeitbasierte Degradierung-Cron (ohne Adapter) ist selbst machbar.
|
||||
- **#8 Webhook-Storm-Schutz** — `withIdempotency()`-Wiring an einem Webhook-Ingest noch offen (Schema-Drift-Sentinel via Registry-Drift ist da).
|
||||
- **Reachability (DoD B/#10):** VMs + Admin-Routen-Hülle + Sidebar — selbst machbar (finale Optik wartet auf Davids D-P5).
|
||||
- **Katalog-Seed** (`INTEGRATION_CATALOG` → `App`-Tabelle upserten) — selbst machbar.
|
||||
- `db push` + RLS-Live-Verifikation env-gegatet (kein lokales PG); Merge-Migration beim main-Merge (AD-21).
|
||||
|
||||
**Pre-existing rot (nicht von R-P5):** cli/dsgvo „covers every"-Tests für File/Task/AdminTenantNote/EntityLink (merged AK-P4a/b/P19 haben die Registries nie nachgezogen); permissions-seed Windows-fileURL-Flake; roleDisplay i18n. Alle environmental/Fremd-Ticket.
|
||||
|
||||
**Update 2026-06-28 (Akeshan) — beide Entscheidungen umgesetzt, DoD jetzt 9/9 backend.** Co-Dev-Abstimmung: Akeshan macht R-P5. Entscheidungen: (1) geteiltes Adapter-Paket extrahieren, (2) funktionale UI-Hülle jetzt. 4 weitere Commits:
|
||||
- `f6272c1` **@hivegrid/integrations extrahiert** (catalog + adapters + registry/drift + worker-tasks) — web+worker importierbar; Contract bleibt in foundation. **Worker-Crons** integrations-token-refresh (5m) + integrations-health-sweep (15m) pro Tenant via withTenantRLS → **DoD #4 komplett**.
|
||||
- `52b6113` **VMs + Admin-Route-Hülle + Sidebar + i18n** — `app.$tenant/integrations.*` (Katalog, Connection-Verwaltung mit connect/disconnect/manual-sync-Actions, Sync-History); Konnektor- + Permission-Gate (404); Credentials nie im VM. DataConnection.appId = bare Katalog-Key (AD-21, kein App-FK).
|
||||
- `a49d998` **Webhook-Storm-Schutz** (`triggerWebhookSync` via `withIdempotency`, 60s-Dedup) → **DoD #8 komplett**.
|
||||
|
||||
**Stand: 9/9 DoD backend grün** + Reachability-Hülle. Verifiziert: typecheck alle Pakete + web (0 Fehler, Turbo-Cache-Falle 2x umgangen via direktem tsc), 30 neue Tests grün (Crypto/Registry/Worker-Sweep/VMs/Aggregate), RLS-Gate-Tests skippen sauber, verify:i18n Exit 0. **Nur noch offen:** finale Subframe-Optik (Davids D-P5), `db push` + RLS-Live + Visual-Regression/Smoke (env/Staging), App-Tabellen-Katalog-Seed (deferred — Tenant-Flow nutzt Code-Katalog), Merge-Migration (beim main-Merge, AD-21). Branch `feat/R-P5`, 11 Commits, lokal, nicht gepusht.
|
||||
|
||||
**Abgleich/Review 2026-06-28 (Akeshan) — Branch gegen Ticket + DoD unabhängig nachgeprüft.** Auslöser: R-P5 von Raffael übernommen, vollständiger Soll/Ist-Abgleich vor Übergabe-Doku. Ergebnis bestätigt den Stand oben:
|
||||
- **Code-Inventar:** alle 9 DoD-relevanten Artefakte vorhanden (crypto.prisma/appsEngine.prisma, RLS-SQL crypto+apps-engine, foundation/crypto envelope+key-wrapper, db/crypto tenant-envelope, foundation integration-adapters, Paket @hivegrid/integrations inkl. worker-tasks, appsEngineService, Worker-Maintenance-Cron, apps-engine VMs, Admin-Routen-Hülle, AppSidebar-Eintrag). `git diff main..feat/R-P5`: 74 Dateien, +6722/-5779.
|
||||
- **Gates frisch gefahren:** `pnpm typecheck` (alle Pakete + web, react-router typegen + Prisma-Client-Regen) **Exit 0, 0 TS-Fehler**; gezielte vitest (foundation/crypto + integration-adapters + @hivegrid/integrations registry/worker-tasks + apps-engine VMs) **24/24 grün**; `verify:i18n` **Exit 0**. Working Tree sauber.
|
||||
- **Plane abgeglichen:** Ticket `R-P5` = State **In Progress**, Assignee **Akeshan**, blocked-by R-P2b+D-P5, 0 Kommentare → Status-Kommentar mit diesem Stand gesetzt. Identität des Keys via `users/me` = akeshan (kein Mismatch).
|
||||
- **Kein Statuswechsel auf Done:** Backend ist 9/9, aber DoD #1/#6 tragen den UI-Wizard-Teil (D-P5 blockiert) und mehrere Reachability/Verifikations-Punkte hängen an Staging-DB/David → Ticket bleibt **In Progress**, bis das D-P5-Delta + Live-DB-Verifikation durch sind.
|
||||
- **Selbst machbar noch offen:** nichts (alle Rest-Punkte extern blockiert: D-P5-Optik, Staging-DB für `db push`/RLS-Live/Visual-Regression, plus Merge-Migration beim main-Merge). → backend-seitig **100 % der selbst machbaren DoD**, gesamt **9/9 backend grün**.
|
||||
|
||||
**2026-07-07 (Akeshan) — Interim-UI (AD-28) + Sync-Run-Detail + Katalog-Seed, Branch `akeshan/r-p5-interim-ui`.**
|
||||
|
||||
Die „Baseline functional UI" (nacktes Tailwind in den Routen) wurde durch **AD-28-konforme Interim-Screens aus `~/ui`** ersetzt; damit sind die UI-Anteile von DoD #1/#6 sowie DoD D19/D20 jetzt real erfüllt statt nur „Backend fertig":
|
||||
- **Screens** `apps/web/app/components/screens/integrations/`: `IntegrationsCatalogPage` (A6, Karten-Grid nach Kategorie + Suche), `ConnectionDetailPage` (A6+A2, Banner bei degraded/broken mit Reconnect-Knopf), wiederverwendbare **`ConnectionCard`** (Status-Ampel/Klartext/letzter Check/Re-Sync/Reconnect/Trennen), **`ConnectWizardDialog`** (echter `Dialog` M 720 + `StepperHorizontal`: Voraussetzungen → auto-generiertes Credential-Formular aus `connection_schema` mit Secret-Reveal → Prüfen & Verbinden; OAuth2-Apps mit Interim-Hinweis), Disconnect-Confirm (XS 420, Klartext „Sync-Jobs gestoppt, History bleibt"), `SyncHistoryPage` (A2, Status/Kind-Filter + Re-Sync), `SyncRunDetailPage` (A3). Routen rendern nur noch `<XPage vm={} actions={} />`, Fetcher/closeSignal in der Route (Layer-DoD A eingehalten).
|
||||
- **Neu: Sync-Run-Detail** — Route `integrations.$app.$connectionId.syncs.$runId.tsx` + `sync-run-detail.vm.ts` (Items + Logs, `view_logs`-gegated, 404-Pattern) — schließt die vierte Screen-Zeile der Tabelle oben.
|
||||
- **Reconnect-Intent** in der `$app`-Route-Action ergänzt (Service `reconnectConnection` existierte; UI/Action-Pfad fehlte → DoD #6 jetzt komplett bedienbar).
|
||||
- **Hot-Swap (D20):** Adapter `integrationsCatalog` (`packages/ui-app/src/adapters/`) + `renderIntegrationsCatalog` (ui-subframe) + `renderIntegrationsCatalogMock` (ui-mock) + `integrationsCatalog.hot-swap.test.ts` nach `rolesList`-Muster.
|
||||
- **Smoke (D19):** `tests/e2e/integrations.spec.ts` — Login → Katalog → sample-data-sync → Wizard öffnet (Schritt 1) → Sync-History; non-mutierend, skippt ohne E2E-Creds.
|
||||
- **Katalog-Seed (bisher deferred, jetzt drin):** `buildCatalogSeedPlan()` (pur, `packages/integrations/src/catalog-seed.ts` + Test) + idempotentes `App`-Upsert im SeedService (global, kein RLS; Tenant-Flow liest weiter den Code-Katalog, `DataConnection.appId` bleibt bare Key).
|
||||
- **i18n:** ~50 neue Keys de+en (wizard/disconnect/runDetail/syncItem*/syncLogSeverity/Filter), chirurgisch gespliced.
|
||||
|
||||
**Verifiziert (lokal, Windows):** typecheck web+view-models+ui-app+ui-mock+ui-subframe+integrations je 0 Fehler · 434 Tests der 5 angefassten Pakete grün (inkl. 5 neue VM-, 3 Seed-, 5 Hot-Swap-/Mock-Tests; SeedService 19/19) · `verify:i18n` Exit 0 · `verify:sidebar-routes`, `verify:cross-cutting-models` (178/178), `verify:phase-c-boundaries`, `verify:test-density`, `verify:production-seed-artifact` grün · eslint-staged 0 Findings. Kein Prisma-Schema-Delta → keine Migration nötig. **Visual-Baseline deferred** wie AK-P3/R-P2a/AK-P4b (keine Screen-Snapshot-Harness) — Interim-Baseline wird beim David-Nachzug gezogen.
|
||||
|
||||
**Nachtrag 2026-07-07 (Browser-Verifikation lokal + Staging):** Der Sidebar-Eintrag war trotz Code + Plan-Entitlement nie sichtbar, weil `integrations` in `tenantNavigationFeatureKeys` (`appData.ts`) fehlte (Alt-Bug seit R-P5-Merge, betraf auch dashboard/leads/hr/calendar/emails/booking/forms/automation). Gefixt auf Branch `akeshan/verify-fixups` inkl. Registry-Guard-Test (`sidebarFeatureAccess.test.ts`); dazu EmptyState-Dead-Button-Wrapper (DoD B10/E23) und Klartext beim Disconnect (`healthMessageKey` -> `integrations.health.notConnected`). Reachability B6/B7 damit real erfüllt und im Browser verifiziert (Sidebar-Eintrag, kompletter Lifecycle inkl. Reconnect-Submit E2E).
|
||||
|
||||
**Offen (extern):** finale Subframe-Optik aus `D-P5` (→ Tag oben; Plane-Label `design-nachzug` gesetzt 2026-07-07). **Selbst machbar offen: nichts.**
|
||||
|
||||
**Abschluss 2026-07-07:** PR #50 (Interim-UI) und PR #51 (Verifikations-Fixups: Sidebar-productAccess-Keys + Guard-Test, EmptyState-Wrapper, Disconnect-Klartext, Dev-Host-Ports) auf `main` gemergt und auf Staging deployed; Katalog/Wizard auf Staging verifiziert, kompletter Lifecycle inkl. Reconnect-Submit lokal E2E. Plane: Kommentar + Label `design-nachzug` + Status **Done** (Freigabe Akeshan, Chat 2026-07-07).
|
||||
|
||||
## Dev-Nachzug (nach Davids `D-P5`-Delta)
|
||||
|
||||
**Interim-UI (Vorschau, Stand 2026-07-07):** Alle vier Flächen aus `~/ui` gebaut (AD-28) —
|
||||
`apps/web/app/components/screens/integrations/{IntegrationsCatalogPage,ConnectionDetailPage,ConnectionCard,ConnectWizardDialog,SyncHistoryPage,SyncRunDetailPage}.tsx`.
|
||||
Proof: Smoke `tests/e2e/integrations.spec.ts`, Hot-Swap-Adapter `integrationsCatalog`
|
||||
(`packages/ui-app/src/adapters/integrationsCatalog.hot-swap.test.ts`) grün; Visual-Baseline deferred wie
|
||||
R-P2a/AK-P3/AK-P4b (keine Snapshot-Harness — Interim-Baseline wird beim David-Nachzug gezogen).
|
||||
Refactor-Nachzug offen: finale Subframe-Optik aus `D-P5` (Plane-Label `design-nachzug`).
|
||||
|
||||
- [ ] Katalog/Wizard/Connection-Card an Davids UI angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
- [ ] Plane-Ticket `R-P5` aktualisiert
|
||||
@@ -26,14 +26,14 @@ Den CRM-Kern: **Kontakte, Firmen/Organisationen und Leads als typisierte First-C
|
||||
| Custom-Felder [`/admin/custom-fields`] · Tag-Verwaltung [`/admin/tags`] · Duplikat-Tool [`/admin/duplicates`] | Admin-Verwaltung + Side-by-Side-Merge |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] Entitäten typisiert + **RLS** auf allem Tenant-bezogenen; Entity-Builder raus (AD-2)
|
||||
- [ ] Listen server-seitig: filter / sort / paginate / bulk / CSV
|
||||
- [ ] Detail: Inline-Edit + **Activity-Stream** (append-only Event-Sourcing) + Custom-Felder
|
||||
- [ ] **Live-Duplikat-Check** beim Anlegen
|
||||
- [ ] **Lead → Projekt** Extension-Point vorbereitet (AD-20; volle Konvertierung in P7/P8)
|
||||
- [ ] SHK-Branchen-Custom-Felder als Template geseedet (`is_demo_data`)
|
||||
- [ ] Konnektor `tenantHasModule('crm')` (Sidebar + Routes + Actions gated)
|
||||
- [ ] `crm.*`-Permission-Bundle (read_own/read_all/write/delete/admin) + serverseitiger Owner-Filter
|
||||
- [x] Entitäten typisiert + **RLS** auf allem Tenant-bezogenen; Entity-Builder raus (AD-2)
|
||||
- [x] Listen server-seitig: filter / sort / paginate / bulk / CSV
|
||||
- [x] Detail: Inline-Edit + **Activity-Stream** (append-only Event-Sourcing) + Custom-Felder
|
||||
- [x] **Live-Duplikat-Check** beim Anlegen
|
||||
- [x] **Lead → Projekt** Extension-Point vorbereitet (AD-20; volle Konvertierung in P7/P8)
|
||||
- [x] SHK-Branchen-Custom-Felder als Template geseedet (`is_demo_data`)
|
||||
- [x] Konnektor `tenantHasModule('crm')` (Sidebar + Routes + Actions gated)
|
||||
- [x] `crm.*`-Permission-Bundle (read_own/read_all/write/delete/admin) + serverseitiger Owner-Filter
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (eigene `prisma/schema/crm.prisma`): `Kontakt`, `KontaktRelation` (self-ref Rolle haupt/sekundär), `KontaktEmail`/`KontaktTelefon` (1:N), `Activity` (polymorph `subject_type/id`, append-only), `CustomFieldDefinition`/`CustomFieldValue`, `Tag`/`TagAssignment` (polymorph). `core.prisma`/`accounts.prisma` nur für Relationen zu Tenant/User berühren (AD-21).
|
||||
@@ -48,6 +48,43 @@ Den CRM-Kern: **Kontakte, Firmen/Organisationen und Leads als typisierte First-C
|
||||
- `designer-briefs/P06-crm-kern.md` (Screens + UI-Elemente, Pivot-Vorrang-Hinweis)
|
||||
- `_bmad-output/specs/M01-crm-kern.md` (⚠ teils pre-pivot — ENTITY-MODEL hat Vorrang)
|
||||
|
||||
## Scope-Entscheidung Entity-Builder-Ablösung (2026-06-29)
|
||||
Der Entity-Builder ist tiefer verankert als nur CRM (auch `settings/entities`, `new-account`-Tenant-Seed, Hocuspocus-Row-Collab). Aufteilung:
|
||||
- **R-P6 (dieses Ticket, Variante A):** CRM-scoped Ablösung — typisierte Kontakte bauen + `modules/crm` (CrmService/ProductCoreCrmEntities/crmContactSearch) + autogenerierte `admin/crm/$entity`-Routes raus + `new-account`-CRM-Seed auf typisiert umstellen.
|
||||
- **R-P6B (Folge-Ticket, Plane #166, Variante B):** generischer Entity-Builder-Vollausbau — `settings/entities`, Row-Collab, `utils/db/entities`, `modules/rows`, `entityBuilder.prisma` entfernen. **blocked-by R-P6.** **Verbindlich (AD-2, 2026-06-29):** die volle Ablösung ist Pflicht (kein „optional"); ab sofort KEINE neuen Entity-Builder-Konsumenten (PR-Block) — siehe AGENTS.md + R-P6B.md §Rückwirkungs-Audit.
|
||||
- E2: Backend + minimale Inline-Swap-UI, finale Optik via `D-CRM`. E3: SHK-Custom-Felder-Template später mit Geerkens (nur Mechanik + leeres Template). E4: ein PR am Ende. Activity wird genutzt (nicht neu gebaut).
|
||||
|
||||
## Umsetzung (2026-06-29) — 8/8 DoD = 100 % done (selbst machbar)
|
||||
|
||||
Gebaut in 6 Slices auf `feat/R-P6` (Branch von `origin/main`), Pre-Flight grün, jeder Slice lokal typecheck+lint+test+i18n grün:
|
||||
|
||||
- **Slice 1** `prisma/schema/crm.prisma` (`28699ac4a`): Kontakt, KontaktRelation, KontaktEmail, KontaktTelefon, Adresse, CustomFieldDefinition, CustomFieldValue, Tag, TagAssignment (AD-21: bare String-Scalars, soft-delete `archivedAt`, `isDemoData`, polymorphe `entityType` tragen `lead`/`projekt`/`rechnung` → **Lead→Projekt-Extension-Point**, DoD 5). RLS-Rollout-Artefakt `prisma/rls/crm-isolation.sql` (deferred/fail-closed/FORCE, analog task/file). `prisma validate` + `db push` (kein Migration-File, AD-21) + `generate` grün. Activity NICHT neu gebaut (nutzt `activity.prisma` + `logActivity`).
|
||||
- **Slice 2** Services `apps/web/app/utils/integrations/crm/*` (`b7bdb7b4e`): CRUD + `withTenantRLS`, server-seitige Liste (filter/sort/paginate) mit **Owner-Scope** (DoD 8), **Live-Duplikat-Check** hard(email/telefon)/soft(name) (DoD 4), Bulk, Custom-Fields, Tags, Audit+Activity-Wiring. SHK-Seed-Mechanik + bewusst **leeres** Template (E3).
|
||||
- **Slice 3** View-Models `packages/view-models/src/crm/*` (`a73aaf948`): pure, i18n-Keys, VMState; 15 Fixture-Tests. (+ href-Konsistenz-Fix `a695b2c2d`.)
|
||||
- **Slice 4** Routes `app.$tenant/contacts.*` + minimale Inline-UI + i18n (`2e89b5898`): Liste (server-seitig filter/sort/paginate/bulk/CSV, DoD 2), Detail (Inline-Edit + Activity-Stream + Custom-Felder, DoD 3), `/contacts/new` mit Live-Dup-Check, Admin custom-fields/tags/duplicates (crm.admin-gated). Klartext Empty/Permission-Denied=404.
|
||||
- **Slice 5a** Permissions + Sidebar (`78a000b9d`): `crm.*`-Bundle in DefaultPermissions + permissions-seed (DoD 8), Sidebar `/crm`→`/contacts` + Permission-Gate (DoD 6/7), roleDisplay-Scope-i18n.
|
||||
- **Slice 5b** Entity-Builder-CRM-Pfad abgelöst + SHK-Seed verdrahtet (`677b23e1e`): autogenerierte/admin/dashboard CRM-Routes gelöscht, SeedService→`seedShkCustomFieldTemplate` (DoD 6), RowsApi-contact-Spezialfall nachgezogen (DoD 1).
|
||||
|
||||
**Proof:** Voller Test grün (3646 passed / 0 failed, 616 Test-Files); `pnpm typecheck` + `pnpm lint` + `pnpm verify:i18n` (parity 7488 keys, 0 forbidden) exit 0; 9 CRM-Tabellen in DB; decision-report-Check grün. **PR #13** (`git.tool-ctrl.de/.../pulls/13`) → **CI grün, alle 11 Jobs**. CI-Footgun gefixt: 9 neue tenantId-Modelle mussten in `packages/cli` `TENANT_SCOPED_MODELS` registriert werden (lokaler `pnpm test` deckt nur Core ab, CI fährt zusätzlich `test:packages`).
|
||||
|
||||
**Dokumentierte Default-Entscheidungen (Lücken, kein Scope-Konflikt):**
|
||||
1. **Module-Key** = registrierter `crm-basic` (Ticket sagt `'crm'`; ein ungeseedeter `'crm'`-Key → `tenantHasModule`=false → Modul unsichtbar).
|
||||
2. **ID/Naming**: `cuid()` + camelCase ohne `@@map` (Codebase-Konvention; ENTITY-MODEL „UUID/snake_case" ist konzeptionell).
|
||||
3. **EmailMarketing-Kopplung (wichtig):** `modules/crm/CrmService` (Entity-Builder-contact-Reader `getContact`/`getContactsInRowIds`) wird von **EmailMarketingService (AK-P14, ausserhalb R-P6-Scope)** konsumiert. Vollständiges Löschen würde EmailMarketing brechen (AGENTS.md „Abhängige nicht brechen"); eine Migration wäre vorgezogene Fremdarbeit (verboten). → CRM-Entity-Builder-**Pfad** abgelöst, `CrmService` als markiertes **Legacy** behalten; vollständige Entfernung erst bei EmailMarketing→Kontakt-Migration (Folge-Ticket).
|
||||
4. **Admin-Routes** unter `/contacts/admin/*` (tenant-scoped, crm.admin-gated) statt Plattform-Admin-Host.
|
||||
5. **UI**: minimale Inline-Swap-UI (kein Subframe) — finale Optik via Davids `D-CRM` (Designer-first).
|
||||
6. Boilerplate-`crm-decision-report` (CRM-als-Plugin-Kandidat) an AD-2/AD-20-Pivot nachgezogen (R-P6 = der vom Report vorgesehene removal-Slice).
|
||||
|
||||
**💡 Vorschläge (ausserhalb Scope, OK abwarten):** (a) Folge-Ticket EmailMarketing→typisiertes Kontakt-Modell migrieren, dann `modules/crm` ganz entfernen + verwaiste CrmService-Exports (getSummary/getUsersInCrm…) löschen. (b) SHK-Custom-Felder-Template mit Geerkens füllen (E3). (c) pre-existing `route_inventory tenant`-Overage (114>78, von main) separat sanieren.
|
||||
|
||||
## Querbezug AK-P3 (dependency-aware, 2026-07-07 — Akeshan)
|
||||
|
||||
AK-P3 (DoD 6, Sprach-Settings) hat das im LOCKED `ENTITY-MODEL.md` (§Domäne 2, i18n-Felder) vorgesehene Feld
|
||||
**`Kontakt.language String?`** additiv in `crm.prisma` ergänzt (Branch `akeshan/ak-p3-interim-ui`;
|
||||
Owner-Freigabe für die crm.prisma-Berührung liegt vor, 2026-07-06). Nullable, kein Default-Backfill
|
||||
(null = Tenant-Default), **kein UI-Editor in v1** — Outbound-Nutzung kommt erst mit v2 (`REQ-i18n-outbound`).
|
||||
Bestehende CRM-Services/VMs bleiben unberührt (Feld wird nicht selektiert/geschrieben).
|
||||
|
||||
## Dev-Nachzug (nach Davids `D-CRM`-Delta)
|
||||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
|
||||
@@ -0,0 +1,98 @@
|
||||
# R-P6B · Entity-Builder-Vollausbau (generischer Rest raus, AD-2)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Dev (Code) |
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | P6 — CRM-Kern (Folge von R-P6) |
|
||||
| **Plane** | #166 · blocked-by `R-P6` (✅ erledigt 2026-06-29) |
|
||||
| **Status** | geplant — **Scope-Klärung offen** (siehe §Blocker) |
|
||||
|
||||
## Was wir bauen
|
||||
Die **vollständige Entfernung des generischen Entity-Builders** aus HiveGrid (AD-2). R-P6 (Variante A) hat den CRM-Teil bereits typisiert und den CRM-Entity-Builder-**Pfad** abgelöst. R-P6B (Variante B) entfernt den **generischen Rest**: `apps/web/app/modules/rows/**`, `apps/web/app/utils/db/entities/**`, die Entity-Builder-Settings/Admin-Routes, die autogenerierten `$entity.__autogenerated`-Routen, Row-Collab (Hocuspocus/`api.collab.token`) und schließlich das `prisma/schema/entityBuilder.prisma`-Schema.
|
||||
|
||||
> **🔴 VERBINDLICH (2026-06-29, Raffael):** Diese Ablösung ist **Pflicht, kein „optional"** (AD-2, jetzt auch in AGENTS.md verankert). Zwei Teile: **(a) Ab sofort KEINE neuen Entity-Builder-Konsumenten** — jedes neue Modul/Feature nutzt typisierte Prisma-Tabellen (PR-Block). **(b) Die bereits gebauten Konsumenten werden rückwirkend typisiert abgelöst** — organisch, sobald das jeweilige Modul ohnehin angefasst wird (Liste in §Rückwirkungs-Audit). Raffael + Agent nehmen das Akeshan ab; Ownership-Detail offen (§Migrationskette & Ownership).
|
||||
|
||||
## Umfang (Inventar — aus Codebase-Analyse 2026-06-29)
|
||||
| Bereich | Pfad | ~Dateien | Aktion |
|
||||
|---|---|---|---|
|
||||
| Schema | `prisma/schema/entityBuilder.prisma` | 1 (21 Modelle) | löschen + Forward-Migration |
|
||||
| UI-Builder | `apps/web/app/modules/rows/**` | ~50 | löschen |
|
||||
| DB-Query-Layer | `apps/web/app/utils/db/entities/**` | ~19 | löschen |
|
||||
| Admin-Builder-UI | `apps/web/app/routes/admin/entities/**` | ~72 | löschen |
|
||||
| Tenant-Settings | `apps/web/app/routes/app.$tenant/settings/entities/**` | ~7 | löschen |
|
||||
| Auto-CRUD-Routen | `app.$tenant/$entity.__autogenerated/**` + `g.$group/...` | ~40 | löschen |
|
||||
| API-Layer | `utils/api/.server/{Entities,Rows,Properties,RowRelationships,RowPermissions}Api.ts` | 5 | löschen |
|
||||
| Components | `apps/web/app/components/entities/**` | ~20 | löschen |
|
||||
| Row-Collab | `apps/hocuspocus/**` + `routes/api.collab.token.ts` | ~13 | klären (Y.js-Collab) |
|
||||
| **Summe** | | **~240+** | |
|
||||
|
||||
## 🔴 Blocker & Abhängigkeiten (Scope-Klärung erforderlich)
|
||||
Der generische Entity-Builder wird **nicht nur von CRM** genutzt. Vor der Entfernung des strukturellen Kerns (`modules/rows`, `utils/db/entities`, `EntitiesSingleton`, `entityBuilder.prisma`) müssen folgende Konsumenten auf typisierte Modelle migriert werden:
|
||||
|
||||
1. **EmailMarketing** (ursprünglich Akeshans Track AK-P14) — nutzt `CrmService` (R-P6-Legacy: `getContact`/`getContactsInRowIds`) + `RowWithDetails`/`EntityWithDetails`. Kampagnen referenzieren contact-Row-IDs. **Harter Blocker.** Ownership der Migration in Klärung (siehe §Migrationskette & Ownership).
|
||||
2. **`CrmService` (R-P6-Legacy)** — hängt direkt an `utils/db/entities` + `entityBuilder`. Entfällt erst mit (1).
|
||||
3. **workflows / formulas** — `EntitiesSingleton`, `Entity`/`Property`/`FormulaLog` (Workflow-Blocks + Formula-Evaluation an Entity/Property gebunden). **Eigene Migration nötig.**
|
||||
4. **`EntitiesSingleton`** — von **~49 Dateien** appweit genutzt (Entity-Metadaten/Cache: `useAppData`/`useAdminData`). Muss durch typisierte Registries je Modul ersetzt werden.
|
||||
5. **Datenverlust:** `entityBuilder.prisma` enthält `Row` (= **alle** generischen Entity-Daten der Tenants) + `Property`/`EntityView`/`RowPermission`/`TenantSettingsRow` (alle tenant-scoped, in `TENANT_SCOPED_MODELS`). Schema-Löschung = **irreversibler Tenant-Datenverlust** → braucht Produkt-/Migrations-Entscheidung (welche Tenants betroffen? Vorab-Export? v2-only-Garantie?).
|
||||
|
||||
**Konsequenz:** Solange (1)–(4) leben, kann **kein** Kern-Teil entfernt werden — auch die Admin-/Auto-Routes nicht, weil sie die noch laufenden Entities verwalten/rendern. R-P6B ist damit **derzeit nicht autonom baubar**; es ist die Spitze der Migrationskette unten.
|
||||
|
||||
## Migrationskette & Ownership (Stand 2026-06-29)
|
||||
„Die Kette" = die voneinander abhängigen Migrations-Schritte, die VOR der Kern-Entfernung (β) erledigt sein müssen. Geordnet (jeder Schritt setzt den vorigen voraus):
|
||||
|
||||
1. **EmailMarketing** weg von Entity-Builder-`contact`-Rows → typisiertes `Kontakt`-Modell (hält die R-P6-`CrmService`-Legacy am Leben).
|
||||
2. **WorkflowEngine** weg von `EntitiesSingleton` → typisierte Registry.
|
||||
3. **apps/api + apps/worker**: generische Entity-Row-Handler (`findLegacyEntityByName("contact")` etc.) typisieren.
|
||||
4. **Dann β (Raffael):** `EntitiesSingleton` komplett raus → `modules/rows`/`utils/db/entities`/Admin-/Auto-Routen löschen → `entityBuilder.prisma` + Forward-Migration (+ Tenant-Daten-Entscheidung).
|
||||
|
||||
**Ownership: GEKLÄRT (2026-06-29).** Akeshan baut **AK-P14a (#42) + AK-P14b (#43)** planmäßig auf dem bestehenden Builder fertig und **stoppt dann kurz**; **Raffael (+ Agent) übernimmt das EmailMarketing-Modul** und fährt die Migration gebündelt via **`R-P14C`** — EmailMarketing typisieren **plus** die übrigen rückwirkenden Konsumenten (WorkflowEngine, formulas, …) „im Vorhinein" mitnehmen. `R-P14C` ist **blocked-by #42/#43**. Erst danach wird **R-P6B-β** (EntitiesSingleton-Removal + Schema-Löschung) entsperrt. Akeshan wird bei Änderungen an seinen Modulen eingebunden. Solange R-P14C läuft, ruht/abgestimmt: `modules/emailMarketing`, `modules/workflowEngine`, `modules/formulas`.
|
||||
|
||||
## Rückwirkungs-Audit (2026-06-29) — was ist gebaut + nutzt den Builder
|
||||
**Ergebnis: 7 bereits gebaute Module nutzen den Entity-Builder aktiv → rückwirkend typisiert abzulösen.** Noch nicht gebaute Module werden gleich typisiert gebaut (kein Rückwirkungsbedarf).
|
||||
|
||||
| Modul | Builder-Nutzung | Dringlichkeit | Ticket/Herkunft |
|
||||
|---|---|---|---|
|
||||
| EmailMarketing (`modules/emailMarketing`) | `CrmService.getContact`/`getContactsInRowIds` (contact-Row-IDs in Kampagnen) | **DRINGEND** (Daten wachsen, Akeshan aktiv) | AK-P14a #42 / AK-P14b #43 |
|
||||
| WorkflowEngine (`modules/workflowEngine`) | `EntitiesSingleton.getEntity()` (Block-Metadaten, 4 Stellen) | kritisch | Boilerplate-Bestand |
|
||||
| formulas (`modules/formulas`) | `EntityWithDetails`/`PropertyWithDetails`/`RowWithDetails` | kritisch | Boilerplate-Bestand |
|
||||
| codeGenerator (`modules/.../codeGenerator`) | `EntityWithDetails` (Template-Gen) | prüfen ob noch aktiv/nötig | Boilerplate-Bestand |
|
||||
| onboarding (`OnboardingService`) | `getAllEntities()` | low-prio | Boilerplate-Bestand |
|
||||
| `CrmService`-Legacy (`modules/crm`) | `getEntityByName`/`getRowById`/`getRowsInIds` | blockiert (hängt an EmailMarketing) | R-P6 (done) |
|
||||
| Entity-Builder selbst (`modules/rows`, `components/entities/**`, Auto-Routes, `*Api.server`-Layer) | — | wird gelöscht | R-P6B-β |
|
||||
|
||||
**Nicht rückwirkend (noch nicht gebaut → von Anfang typisiert):** AK-P14b-Versand, AK-P15a/b, AK-P16c/d, AK-DEMO1, AK-P17/P19 (eigene typisierte Module, nutzen Builder ohnehin nicht).
|
||||
|
||||
**Kritischer Pfad:** EmailMarketing + WorkflowEngine + formulas müssen typisiert sein, bevor `EntitiesSingleton` / `modules/rows` / Schema fallen können. EmailMarketing zuerst (löst die `CrmService`-Legacy ab).
|
||||
|
||||
## Empfohlener Scope-Split
|
||||
- **R-P6B-α (jetzt, nach Verifikation):** nur Teile entfernen, die nach R-P6 **nachweislich verwaist** sind (grep-belegt 0 Konsumenten). Realistisch klein, da der Builder breit genutzt wird.
|
||||
- **R-P6B-β (nach AK-P14 + workflows/formulas-Migration):** `EntitiesSingleton` → typisierte Registries, dann `utils/db/entities` + `modules/rows` + Admin/Auto-Routen + Schema. Mit dokumentierter Forward-Migration (Inverse-SQL) + Tenant-Daten-Entscheidung.
|
||||
|
||||
## Definition of Done (Voll-Scope, β eingeschlossen)
|
||||
- [x] EmailMarketing/CrmService-Legacy (R-P14C Teil 1) + WorkflowEngine (R-P14D) typisiert abgelöst; formulas + codeGenerator = **Cut mit β** (kein Rebuild); onboarding (R-P14F) entkoppelt.
|
||||
- [x] `EntitiesSingleton` entfernt: die 8 Builder-Kern-Konsumenten starben mit `modules/rows`; die bleibenden (`useAppData`/`useAdminData`/`useAppOrAdminData`) verloren das `entities`/`entityGroups`-Feld; WorkflowEngine läuft über die typisierte Modell-Registry.
|
||||
- [x] `modules/rows`, `utils/db/entities`, `admin/entities` (inkl. der Layout-Route `admin/entities.tsx`), `settings/entities`, `$entity.__autogenerated`, `g.$group`, Entity-API-Layer (`utils/api/.server/{Entities,Rows,Properties,Row*}Api`), `components/entities`, `modules/formulas`, `modules/codeGenerator` + die EB-Helper entfernt; `apps/api` `/v1/entities` + `/v1/relationships` + `packages/db/src/{entities,rows,relationships,settings}.server.ts` entfernt; Worker-Formular-`entity-row`-Pfad entfernt; Such-Indizes `rows`/`entities` entfernt; CRM-Such-Reindexer auf die typisierte `Kontakt`-Tabelle umgestellt.
|
||||
- [x] Row-Collab: `api.collab.token` generischer `row`-Resource-Type entfernt (kb-article-Collab bleibt, alles andere fail-closed); Collab-Editor/hocuspocus bleiben. (CR: s.u.)
|
||||
- [~] `entityBuilder.prisma` gelöscht + `prisma db push` (AD-21: kein Migrations-File am Branch); `TENANT_SCOPED_MODELS` (8 EB-Modelle raus) + `PLATFORM_CATALOG_GLOBALS` (Entity/EntityGroup/Formula/RowComment raus) + Cross-Schema-Relationen (accounts/core/permissions) nachgezogen. **Offen: forward-only DROP-Migration beim Merge** (s. §Umsetzung).
|
||||
- [x] Tenant-Daten-Strategie dokumentiert: **keine echten Tenants** (Prod 0 echte Tenants) → Tabellen droppen, **kein Export/keine Daten-Migration** (Entscheidung Raffael 2026-06-30).
|
||||
- [x] typecheck (web/worker/api/db) + lint + i18n + voller CI-Test-Scope grün; alle EB-bezogenen Tests angepasst/entfernt.
|
||||
|
||||
## Quellen
|
||||
- `R-P6.md` §Scope-Entscheidung (Abgrenzung A/B) — die R-P6B-Definition
|
||||
- `docs/ARCHITECTURE-DECISIONS.md` AD-2 (Entity-Builder raus), AD-20 (projekt-zentrisch)
|
||||
- Codebase-Analyse 2026-06-29 (Konsumenten-Matrix, oben)
|
||||
|
||||
## Umsetzung
|
||||
- 2026-06-29: Branch `feat/R-P6B` angelegt, Ticket-Doc + Konsumenten-/Blocker-Analyse erstellt. Diese Doc als eigenständiger **Doc-PR #14**.
|
||||
- 2026-06-29: Scope-Entscheidung (Raffael): **R-P6B-α jetzt** (nur nachweislich verwaiste Teile), struktureller Rest (β) nach AK-P14. **α umgesetzt** (Branch `feat/R-P6B-alpha`, **PR #15**): die konsumentenlosen Entity-Builder-Reader aus dem R-P6-Legacy-`CrmService` entfernt (550→185 Zeilen, grep-belegt 0 externe Konsumenten, kein Datenverlust). Voller CI-Test-Scope grün. EmailMarketing-Reader (validate/getContact/getContactsInRowIds) bleiben.
|
||||
- **β bleibt blockiert** (AK-P14/workflows/formulas + Tenant-Daten-Entscheidung) — kein destruktives Löschen des Kerns ohne Vorab-Migrationen + Go.
|
||||
- **2026-06-30: β ENTSPERRT.** Teil 1 (EmailMarketing, R-P14C) fertig; Teil 2 (workflows/onboarding) entschieden + formulas/codeGenerator = Cut mit β. **Tenant-Daten-Entscheidung gefallen:** keine echten Tenants (Prod hat 0 echte Tenants) → β = Tabellen droppen, forward-only Migration, **kein Export**. Ausführungsreifer Gesamtplan + alle gesetzten Entscheidungen: **`R-P14C-T2.md` §Ebene-1 Mega-Plan**. β läuft als 3. gestapelter PR (`feat/R-P6B-beta` auf `feat/R-P14C-teil2`).
|
||||
- **2026-06-30: β UMGESETZT** (autonomer Lauf, Branch `feat/R-P6B-beta`). Der generische Entity-Builder ist **vollständig entfernt**. Proof: ~370+ Dateien gelöscht; `EntitiesSingleton`/`RowsApi`/`entityBuilder.prisma` weg (grep 0 in Quell-Code, nur noch Doku-Kommentare in `services/typed-model-registry/`); `entityLinks.prisma` (typisierte polymorphe Links) bewusst behalten. **Voller CI-Scope lokal grün:** typecheck (web/worker/api/db), lint, test:foundation/packages/mobile, Core-Test (3500 grün), verify:i18n, verify:cross-cutting-models (104/104 tenantId-Modelle, 8 EB-Modelle raus), verify:workflow-outbox-native (282), verify:onboarding-flow, verify:sidebar-routes, verify:feature-manifest-baseline, verify:removed-modules, verify:source-health, verify:ci-baseline. *(Advisory `verify:route-inventory` ist NICHT im CI-Gate und war schon vor β über Budget — β hat tenant-Routen von ~125 auf 83 reduziert, weiterer Abbau = Folge-Arbeit.)*
|
||||
- **2026-06-30: Remote-CI grün gezogen** (3 Fix-Commits auf `feat/R-P6B-beta`, nachdem die Gitea-Actions-CI Folgefehler der EB-Entfernung zeigte, die der lokale Scope nicht abdeckte). Behoben: (a) **OpenAPI-Spec + generierter API-Client** (`apps/api/src/openapi.ts`, `packages/api-client-ts/*`) ohne die 5 `/v1/entities`+`/v1/relationships`-Pfade; **Security-Inventare** `route-access-inventory.*` + `csrf-inventory` + generierter `tenant-isolation-report` nachgezogen; EB-Contract-Tests entfernt (`permission-matrix.test` gelöscht, `openapi.test`/`app.test`/`csrf-inventory.test`/`openapi-guard.test` bereinigt). (b) **Coverage** der kritischen apps/api-Module wiederhergestellt (neuer `auth/scope.test.ts` + Fixture-Branch — die gelöschten EB-Tests deckten auch behaltene Funktionen ab; auth 99.7 %, isolation 100 %). (c) **Production-Seed** `permissions-seed.server`: `entityId:null` aus `permission.createMany` raus (mit `Permission.entityId` weg; loser Client-Typ ließ es durch den Typecheck, brach erst zur Laufzeit im Docker-Smoke). (d) **Docker-Runtime-Smokes** prüfen nicht mehr hart auf den Entity-Pfad. Zwei CI-Ausfälle waren reine Flakes/Transient (Plugin-Sandbox-Test auf T1; paralleler Docker-Build) → per Re-Run grün. Endstand: **T1, R-P14C-teil2, R-P6B-beta alle grün** in Gitea-Actions.
|
||||
- **Migration (AD-21):** Am Branch nur `prisma db push` (kein Migrations-File). Die **forward-only DROP-Migration** entsteht **beim Merge nach `main`** — sie muss alle `entityBuilder.prisma`-Tabellen droppen (DO $$ IF EXISTS $$-Guards) **und** die mit-entfernten Spalten/Relationen: `Log.rowId`/`Log.commentId` (+ FKs `Log.row`/`Log.comment`), `Permission.entityId` (+ FK), `ApiKey↔ApiKeyEntity`, sowie die Rück-Relationen auf User/Tenant/Role/Group. Inverse-SQL als Kommentar (DoD 28), reproduzierbar gegen leere DB (CI `migrate deploy`).
|
||||
- **Offene CR-Flags (M176-Doc fehlt noch → hier vermerkt):**
|
||||
1. **Collab generischer `row`-Resource-Type entfernt** (`api.collab.token`): Echtzeit-Collab für generische Rows weg; kb-article bleibt. Falls Collab auf typisierten Datensätzen gewünscht → typisierter resource-type-Zweig (neues Ticket).
|
||||
2. **Formular-Eingang `entity-row`-Ziel entfernt** (Worker): `generic` (nur speichern) + `crm-contact` bleiben als Ziele. `packages/form-widget` `SubmissionTargetType` listet `entity-row` noch (Worker lehnt es ab) → Follow-up: aus dem Enum entfernen.
|
||||
3. **REGRESSION (Pre-Launch unkritisch): Formular-Ziel `crm-contact` im Worker nicht mehr verdrahtet** (MISSING_CRM_ADAPTER). Der bisherige CRM-Creator war EB-basiert; es gibt keinen typisierten Kontakt-Creator in einem worker-erreichbaren Paket. Handler-Zweig existiert, ist aber unverdrahtet → crm-contact-Submissions schlügen zur Laufzeit fehl, bis ein typisierter Kontakt-Creator (packages/db oder shared) ergänzt wird.
|
||||
4. **Workflow `rowGet`-Block = No-op** (`workflow-trigger-native-executor`): liefert `{row:null}`; rowGet bleibt unterstützter Block-Typ (Guard-Test grün), row-getriggerte Workflows bekommen aber null bis ein typisierter Ersatz verdrahtet ist.
|
||||
@@ -0,0 +1,39 @@
|
||||
# R-P6C · CRM-Querschnitt-Nachzüge (projektweite Verdrahtung)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Dev (Code) |
|
||||
| **Owner** | Raffael (+ Agent) — **nur wir, kein Akeshan** |
|
||||
| **Phase** | P6 — CRM-Kern (Zwischenticket R-P6 → R-P6B) |
|
||||
| **Status** | geplant |
|
||||
|
||||
## Warum dieses Ticket
|
||||
R-P6 hat die typisierten CRM-Modelle eingeführt und ist querschnittlich zu ~80 % verdrahtet (Audit 2026-06-29). Drei projektweite Cross-Cutting-Stellen sind aber noch offen — sie gehören NICHT in die große Entity-Builder-Ablösung (R-P6B, durch AK-P14 blockiert), sondern sind kleine, nicht-blockierte CRM-Nachzüge, die wir selbst bündeln. Auslöser war u.a. der `TENANT_SCOPED_MODELS`-CI-Bruch (ein Symptom der projektweiten Registry-Pflicht).
|
||||
|
||||
**Abgrenzung:** Dies ist KEIN Entity-Builder-Abbau (das ist R-P6B-β). Hier wird nur die fehlende Querschnitt-Verdrahtung der NEUEN typisierten CRM-Entitäten ergänzt.
|
||||
|
||||
## Was bereits erledigt ist (R-P6, nur zur Abgrenzung)
|
||||
✅ `TENANT_SCOPED_MODELS`, Tenant-Snapshot, Audit (auditCrmEvent), Activity-Stream (contact/company + contact_*), Notifications-fähig, Sidebar + Permission-Gate, Command-Registry, Such-**Schema** (`crm-contacts` in `ALL_SEARCH_INDEXES`).
|
||||
|
||||
## Definition of Done
|
||||
- [x] **Such-Index Registry verdrahtet (AGENTS DoD 16, Teilerfüllung):** `contact` in `packages/search/src/indexed-entities.ts` registriert (Tabelle `Kontakt`, Index `crm-contacts`, permission-gated `crm.read_all`; EIN Eintrag deckt Privatperson + Organisation ab, da `Kontakt` Oberbegriff ist — kein separater Company-Index). **Befund:** Die *funktionale* Indexierung der typisierten Kontakte ist NICHT trivial isolierbar — der `crm-contacts`-Index wird aktuell noch vom Entity-Builder-`Row`-Feeder (`rowSearchOutbox` + Row-`createCrmContactsPager`) befüllt, nicht vom typisierten `Kontakt`-Modell. Den Feeder auf typisiert umzustellen löst den Row-Feeder ab → gehört zu **R-P6B-β** (siehe unten). Die Registry-Zeile ist vorbereitend + harmlos (gated nur, triggert keine kollidierende Indexierung).
|
||||
- [x] **DSGVO-Verdrahtung entschieden + umgesetzt:** Konsistenter, dokumentierter Verzicht (Option 1) — `Kontakt.createdByUserId`/`zustaendigerUserId` sind bare Scalars (kein `@relation`), wie tasks/hr repo-weit; KEIN `user-fk-map`-Eintrag (Sonderweg vermieden). Entscheidung sichtbar im Kopfkommentar von `packages/db/src/dsgvo/user-fk-map.ts` dokumentiert; projektweite Pseudonymisierung bare-scalar-User-FKs als separates Querschnitt-Härtungs-Thema (wenn DSGVO-Lösch-Flow live geht) geparkt.
|
||||
- [x] **Footgun-Prävention:** `scripts/verify-cross-cutting-models-complete.mjs` (+ `.test.mjs` + `verify:cross-cutting-models` npm-Script + ci.yml „Quality Static Verify 2/2"). Erzwingt: jedes tenantId-Prisma-Modell ist in `TENANT_SCOPED_MODELS` — klare Fehlermeldung statt kryptischem packages/cli-Test. Aktuell `104/104 models, 0 missing`.
|
||||
- [x] Lokal grün inkl. **vollem CI-Test-Scope** (typecheck + lint + test:foundation + test:packages + test:mobile + test + verify:i18n + verify:cross-cutting-models) — alle exit 0; PR mit grüner CI nach main.
|
||||
|
||||
## Out of Scope (→ R-P6B-β + dessen Migrationskette)
|
||||
> Die Entity-Builder-Ablösung ist **verbindlich** (AD-2): kein „optional", und ab sofort keine neuen Konsumenten — siehe AGENTS.md + R-P6B.md §Rückwirkungs-Audit.
|
||||
|
||||
- Entity-Builder-Abbau (modules/rows, utils/db/entities, entityBuilder.prisma, EntitiesSingleton).
|
||||
- Die Migrationskette davor (EmailMarketing/Workflows/API/Worker weg von Entity-Builder-`contact` → typisiert; Ownership in Klärung, siehe R-P6B.md §Migrationskette & Ownership).
|
||||
- **Funktionale typisierte-Kontakt-Indexierung** (incremental emit in `crmService` + Kontakt-Bulk-Pager + DE→EN-Feld-Projektion, Ablösung des Row-Feeders auf `crm-contacts`) — gehört zur Entity-Builder-Ablösung, da es den Row-Feeder ersetzt. → **R-P6B-β** (z.B. zusammen mit β2).
|
||||
- Mobile-Tab-Bar / Customer-Portal-Sichtbarkeit für CRM (separat, falls überhaupt Phase-1-relevant).
|
||||
|
||||
## Quellen
|
||||
- Cross-Cutting-Audit der R-P6-CRM-Modelle (2026-06-29) — siehe Konversation/Plane #21.
|
||||
- `AGENTS.md` DoD B (Reachability) + C (Querschnitt-Wiring), insb. DoD 16 (Search-Index).
|
||||
- Memory `feedback-ci-test-scope-gap` (TENANT_SCOPED_MODELS-Footgun).
|
||||
|
||||
## Umsetzung
|
||||
- 2026-06-29: Ticket angelegt nach Cross-Cutting-Audit. Scope-Entscheidung (Raffael): nur wir zwei, ein Zwischenticket, kein Akeshan.
|
||||
- 2026-06-29: **Umgesetzt.** DSGVO-Entscheidung (konsistenter Verzicht, dokumentiert) + Footgun-Verify-Check (`verify:cross-cutting-models`, in ci.yml) + Such-Index-Registry-Eintrag. **Such-Index-Erkenntnis:** die funktionale typisierte-Kontakt-Indexierung ist an die Entity-Builder-Row-Feeder-Ablösung gekoppelt (R-P6B-β) — Registry-Zeile ist vorbereitend gesetzt, Indexierung dort geflaggt. Voller CI-Test-Scope lokal grün.
|
||||
@@ -9,13 +9,13 @@
|
||||
| **Status** | geplant |
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `R-P6` (CRM-Kern — Kontakt/Activity/Tag/CustomFields), `R-REFIT` (ER-Modell-Re-Fit, Pivot AD-20 — ✅ erledigt 16.06.)
|
||||
- **Blocks:** `R-P8a` (Auto-Verkaufsfall verbraucht `lead.qualified`), `AK-P16c` (Form → Lead), **Demo 1**
|
||||
- **Blocked by:** `R-P6` (CRM-Kern — Kontakt/Activity/Tag/CustomFields; Code fertig, Plane temporär On Hold), `R-REFIT` (ER-Modell-Re-Fit, Pivot AD-20 — ✅ erledigt 16.06.), `D-P7` (Screens fehlen; Backend-only-Slice erlaubt)
|
||||
- **Blocks:** `R-P8a` (Auto-Projekt verbraucht `lead.qualified`), `AK-P16c` (Form → Lead), **Demo 1**
|
||||
- **Sequenz (Raffaels Kern-Kette):** strikt sequenziell — `R-P6 → R-P7 → R-P8 → R-P9 → R-P11/P12/P13`. P7 ist Glied 2.
|
||||
- **Läuft parallel zu:** Akeshans Module dieses Fensters (`AK-P14`/`AK-P15`/`AK-P16` Email/Telefonie/Forms — liefern später Lead-Quellen-Adapter). Schema-Trennung nach **AD-21**: jedes Modul eigene `prisma/schema/*.prisma`, `db push` lokal, Migration beim Merge.
|
||||
|
||||
## 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, werden gegen Spam/Anomalien geschützt, sind auswertbar und per Workflow weiterverarbeitbar. **Pivot-Vorrang (AD-20):** Lead ist die **Vorstufe des `Projekt`-Kerns** — bei `weiterverarbeitung_freigabe = ja` entsteht **Lead → Projekt** (kein Contact-Promotion, **kein 4-Optionen-Modal**). Relevante Lead-Daten werden ins Projekt vererbt (`konvertiert_projekt_id`); der **Kontakt wird separat verknüpft** (`verknuepfter_kontakt_id` — neuer oder bestehender). Das `lead.qualified`-Event ist Extension-Point für P8 (Auto-Verkaufsfall M049).
|
||||
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, werden gegen Spam/Anomalien geschützt, sind auswertbar und per Workflow weiterverarbeitbar. **Pivot-Vorrang (AD-20):** Lead ist die **Vorstufe des `Projekt`-Kerns** — bei `weiterverarbeitung_freigabe = ja` entsteht **Lead → Projekt** (kein Contact-Promotion, **kein 4-Optionen-Modal**). Relevante Lead-Daten werden ins Projekt vererbt (`konvertiert_projekt_id`); der **Kontakt wird separat verknüpft** (`verknuepfter_kontakt_id` — neuer oder bestehender). Das `lead.qualified`-Event ist Extension-Point für P8 (Auto-Projekt M049).
|
||||
|
||||
## Benötigte Screens (Backend bedient — Design liefert `D-CRM`, Lead-Cluster im selben Paket wie P6 → Demo #1)
|
||||
| Screen [Route] | Kern-Inhalt |
|
||||
@@ -27,15 +27,15 @@ Den **Lead-Triage-Arbeitsplatz**: eingehende Leads aus allen Quellen (Form, eing
|
||||
| Quellen-Verwaltung [`/admin/lead-sources`] · Anti-Spam-Settings [`/admin/lead-anti-spam`] · Manueller Eintrag [`/leads/new`] | Custom-Quelle + Webhook-URL/Token; Rate-Limits/Anomalie/Quarantäne/Auto-Lösch-Frist; manuelle Anlage mit Inline-Match-Check |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] Triage-Liste server-seitig: filter / sort / cursor-paginate (50/Page) + Quick-Actions + Bulk + Realtime-Refresh (SSE)
|
||||
- [ ] **Multi-Quellen-Auto-Anlage** (Form/Email/AirCall/manuell/Custom) mit `lead.created`- + `lead.qualified`-Events
|
||||
- [ ] **Lead → Projekt** bei `weiterverarbeitung_freigabe=ja` (Daten-Vererbung `konvertiert_projekt_id`, Kontakt separat via `verknuepfter_kontakt_id`, **kein Promotion-Modal**, AD-20/E4)
|
||||
- [ ] Status-Workflow (new|qualified|converted|lost|spam) mit definierten Übergängen + **DSGVO-Auto-Lösch-Cron** (spam 30 T, lost konfigurierbar, 0 = nie)
|
||||
- [ ] Anti-Spam: Rate-Limiting/Anomalie-Detection (10×-Spike → Auto-Pause), Quarantäne-Modus, Tenant-Admin-Notification bei Auto-Pause
|
||||
- [ ] `lead.qualified`-Event als Extension-Point für P8 (Auto-Verkaufsfall M049)
|
||||
- [ ] Statistiken-Page (KPI-Kacheln, Quellen-Aufschlüsselung, Trends) — permission-aware
|
||||
- [ ] Konnektor `tenantHasModule('leads')` (Sidebar + Routes + Actions gated)
|
||||
- [ ] `leads.*`-Permission-Bundle (read_own/read_all/write/delete/admin) + serverseitiger Owner-Filter (nicht-eigene Leads bei `read_own` → **404 statt 403**)
|
||||
- [x] Triage-Liste server-seitig: filter / sort / cursor-paginate (50/Page) + Quick-Actions + Bulk + Realtime-Refresh (SSE)
|
||||
- [x] **Multi-Quellen-Auto-Anlage** (Form/Email/AirCall/manuell/Custom) mit `lead.created`- + `lead.qualified`-Events
|
||||
- [x] **Lead → Projekt** bei `weiterverarbeitung_freigabe=ja` (Daten-Vererbung `konvertiert_projekt_id`, Kontakt separat via `verknuepfter_kontakt_id`, **kein Promotion-Modal**, AD-20/E4)
|
||||
- [x] Status-Workflow (new|qualified|converted|lost|spam) mit definierten Übergängen + **DSGVO-Auto-Lösch-Cron** (spam 30 T, lost konfigurierbar, 0 = nie)
|
||||
- [x] Anti-Spam: Rate-Limiting/Anomalie-Detection (10×-Spike → Auto-Pause), Quarantäne-Modus, Tenant-Admin-Notification bei Auto-Pause
|
||||
- [x] `lead.qualified`-Event als Extension-Point für P8 (Auto-Projekt M049)
|
||||
- [x] Statistiken-Page (KPI-Kacheln, Quellen-Aufschlüsselung, Trends) — permission-aware
|
||||
- [x] Konnektor `tenantHasModule('leads')` (Sidebar + Routes + Actions gated)
|
||||
- [x] `leads.*`-Permission-Bundle (read_own/read_all/write/delete/admin) + serverseitiger Owner-Filter (nicht-eigene Leads bei `read_own` → **404 statt 403**)
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (eigene `prisma/schema/leads.prisma`): `Lead` (quelle, quelle_detail, status, **weiterverarbeitung_freigabe**, vorname/nachname/email/telefon, rohdaten JSONB, spam_score, `konvertiert_projekt_id`, `verknuepfter_kontakt_id`), `LeadSource` (System/Custom, Webhook-Token), Anti-Spam-Konfig. `crm.prisma` (Kontakt/Activity/Tag/CustomField) und später `projekt.prisma` nur über Relationen berühren (AD-21).
|
||||
@@ -55,4 +55,35 @@ Den **Lead-Triage-Arbeitsplatz**: eingehende Leads aus allen Quellen (Form, eing
|
||||
## Dev-Nachzug (nach Davids `D-CRM`-Delta)
|
||||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
- [ ] Plane-Ticket `R-P7` aktualisiert
|
||||
- [x] Plane-Ticket `R-P7` aktualisiert
|
||||
|
||||
## Umsetzung (2026-07-01) — Backend-only ohne D-P7-Screens
|
||||
|
||||
Arbeitsstand auf `feat/R-P7-lead-inbox`: Ohne finale Subframe-/David-Screens wurde der technisch selbst machbare Kern vorgezogen, bewusst mit funktionaler Minimal-UI statt finaler Optik.
|
||||
|
||||
**Gebaut:**
|
||||
- `prisma/schema/leads.prisma` mit `InboxLead`, `LeadSource`, `LeadAntiSpamConfig`; Name bewusst `InboxLead`, weil `marketingLeads.prisma` bereits ein operator-seitiges `Lead`/`LeadStatus` besitzt.
|
||||
- RLS-Rollout-Artefakt `prisma/rls/leads-isolation.sql` + `TENANT_SCOPED_MODELS`-Nachzug.
|
||||
- `leads.*` Permission-Bundle + explizite Default-Rollen, Feature-Gate `leads`, Blueprint/Sidebar/Route-Handles.
|
||||
- Lead-Service mit tenant-scoped `withTenantRLS()`, `read_own` Owner-Filter, Cursor-Liste, Status/Bulk, manuelle Anlage, Quellen-Verwaltung, Statusmaschine, Workflow-Outbox-Events, Anti-Spam-Konfig, Rate-/Spike-Erkennung, Quarantäne/Spam-Markierung, Auto-Pause + Admin-Notification, Statistik-Aggregate.
|
||||
- Ingestion-Adapter für Form, E-Mail, AirCall und Custom (`leadIngestionAdapters.server.ts`) plus manuelle Route.
|
||||
- Minimal-Routes: `/leads`, `/leads/new`, `/leads/:id`, `/leads/statistics`, `/leads/events`, `/admin/lead-sources`, `/admin/lead-anti-spam`.
|
||||
- Worker-Retention-Cron `lead-retention-sweep` für `autoDeleteAt` (spam 30 Tage; lost per Tenant-Konfig; 0 = nie).
|
||||
- Pure View-Model `packages/view-models/src/leads/lead-list.vm.ts` + Unit-Test.
|
||||
|
||||
**DoD-Stand:** 9/9 = 100 % done auf R-P7-Code-/Contract-Ebene ohne finale D-P7-Screens.
|
||||
- [x] Triage-Liste: serverseitig filter/sort/cursor + Status-Quick-/Bulk-Actions + SSE-Endpoint gebaut; finale Screen-Optik bleibt D-P7-Nachzug.
|
||||
- [x] Multi-Quellen: dedizierte Adapter für Form/E-Mail/AirCall/Custom + manuell; `lead.created` und `lead.qualified` gehen über Workflow-Outbox.
|
||||
- [x] Lead → Projekt: Conversion-Request + Abschluss-Contract `completeLeadProjectConversion(projectId)` setzt `konvertiertProjektId` und `verknuepfterKontaktId`; echte Projektanlage bleibt bewusst P8, keine P7-Schema-Vorwegnahme.
|
||||
- [x] Status-Workflow: definierte Übergänge, terminale Status geschützt, Spam-30T und Lost-Retention-Konfig via `autoDeleteAt`, Worker-Cron gebaut.
|
||||
- [x] Anti-Spam: Heuristik + Rate-Limits + IP-/Source-Limits + 10x-Spike-Auto-Pause + Tenant-Admin-Notification + Quarantäne/Spam-Modus.
|
||||
- [x] `lead.qualified`: Workflow-Outbox-Event als P8-Extension-Point gebaut.
|
||||
- [x] Statistiken-Page basisfähig und permission-aware.
|
||||
- [x] Konnektor `tenantHasModule('leads')` mit Sidebar + Routes + Actions gated.
|
||||
- [x] `leads.*` Permission-Bundle + Owner-Filter (`read_own` → nicht sichtbare Leads via 404).
|
||||
|
||||
**Proof aktuell:** `pnpm typecheck`, `pnpm lint`, `pnpm test` (545 Testdateien / 3509 Tests grün), `pnpm verify:i18n`, `pnpm verify:cross-cutting-models`, `pnpm exec prisma validate`, Worker-/Queue-Typecheck und gezielte Tests grün (`leadService`, `lead-retention-cron`, `lead-list.vm`, `queue producers`, Entitlements, Blueprint, Permission-Seed, Sidebar, indexed-entities). `pnpm exec prisma db push` lokal blockiert, weil die Dev-DB auf `localhost:6432` nicht erreichbar war (P1001).
|
||||
|
||||
**Plane:** Kommentar `14f9e801-b02a-42ac-acb4-d861cea49926` geschrieben und Ticket auf `Blocked / On Hold` gesetzt, weil finale D-P7-Screens und echte Projektanlage in P8 außerhalb des R-P7-Code-DoD liegen.
|
||||
|
||||
**Offen außerhalb R-P7-Code-DoD:** D-P7 Screens/Subframe-Delta und echte Projektanlage im P8-Projektmodell. P7 greift P8 nicht per eigener Projekttabelle vor.
|
||||
@@ -1,4 +1,4 @@
|
||||
# R-P8a · P8 Pipeline-Engine + Projekt-CRUD (Sales-Sicht) + Auto-Verkaufsfall
|
||||
# R-P8a · P8 Pipeline-Engine + Projekt-CRUD (Sales-Sicht) + Auto-Projekt
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
@@ -6,7 +6,7 @@
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | P8 — Projekt & Pipelines (Kern + Pipeline-Engine) |
|
||||
| **Cycle/Fenster** | W3 — Kern-Kette & Kommunikation (Demo 2) · 2026-06-27 → 2026-06-28 · Gate W3 |
|
||||
| **Status** | geplant |
|
||||
| **Status** | On Hold — serverseitig umgesetzt, Screen-Delta `D-KANBAN`/`D-P8` offen |
|
||||
|
||||
> 🔴 **Pivot-Vorrang (AD-20):** Das Snapshot-Ticket heißt noch „Deal-CRUD". Korrekt projekt-zentrisch: Es gibt **EINEN `Projekt`-Kern** (typisierte Superset-Tabelle, Deal- + Auftrags-Felder in einer Tabelle). **„Deal" ist ein Pipeline-Typ** (`Pipeline.typ_hint = sales`), **KEINE eigene Entität**. „Projekt-CRUD in Sales-Pipeline-Sicht" statt „Deal-CRUD". `Status` ist immer pipeline-intern (`PipelineStage.stage_kind = offen/gewonnen/verloren`) — kein globaler Projektstatus.
|
||||
|
||||
@@ -17,7 +17,7 @@
|
||||
- **Läuft parallel zu:** Akeshans Module W3 (`AK-P14`/`AK-P15` Email/Telefonie u.a.). Schema-Trennung nach **AD-21** (Modul = eigene `.prisma`, `db push` lokal, Migration beim Merge).
|
||||
|
||||
## Was wir bauen
|
||||
Den **`Projekt`-Kern als eine typisierte Tabelle** (Superset der Felder + `CustomFieldValue`) und die **Pipeline-Engine** als frei konfigurierbare Views: Pipeline anlegen/benennen/duplizieren/archivieren (`typ_hint` sales/auftrag/custom), Stages je Pipeline (= die Statuswerte), Zugriff je Rolle/User/Gruppe (`PipelineAccess`), Feld-Sichtbarkeit + Pflichtfelder pro Pipeline+Status (`PipelineFieldConfig`) und **Field-Level-Rechte** je Principal (`PipelineFieldVisibility` — z.B. Auftragsvolumen nur für Vertrieb). Dazu fortlaufende Projekt-Nummern (HiveNumberSeq, lückenlos), Lost-Reason-CRUD und der **Auto-Verkaufsfall** (M049): `lead.qualified` → Projekt in Sales-Pipeline. Kanban/Listen-View + Forecast folgen in P8b.
|
||||
Den **`Projekt`-Kern als eine typisierte Tabelle** (Superset der Felder + `CustomFieldValue`) und die **Pipeline-Engine** als frei konfigurierbare Views: Pipeline anlegen/benennen/duplizieren/archivieren (`typ_hint` sales/auftrag/custom), Stages je Pipeline (= die Statuswerte), Zugriff je Rolle/User/Gruppe (`PipelineAccess`), Feld-Sichtbarkeit + Pflichtfelder pro Pipeline+Status (`PipelineFieldConfig`) und **Field-Level-Rechte** je Principal (`PipelineFieldVisibility` — z.B. Auftragsvolumen nur für Vertrieb). Dazu fortlaufende Projekt-Nummern (HiveNumberSeq, lückenlos), Lost-Reason-CRUD und das **Auto-Projekt** (M049): `lead.qualified` → Projekt in Sales-Pipeline. Kanban/Listen-View + Forecast folgen in P8b.
|
||||
|
||||
## Benötigte Screens (Backend bedient — Design liefert `D-KANBAN` + `D-P8`)
|
||||
| Screen [Route] | Kern-Inhalt |
|
||||
@@ -27,15 +27,23 @@ Den **`Projekt`-Kern als eine typisierte Tabelle** (Superset der Felder + `Custo
|
||||
| Lost-Reasons [`/admin/pipelines/lost-reasons`] | Liste + Add/Edit/Archive (kein Hard-Delete — Reporting), SHK-Default 5 Reasons geseedet |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **EIN `Projekt`-Kern** (typisierte Superset-Tabelle: Deal- + Auftrags-Felder + `CustomFieldValue`) mit fortlaufenden Projekt-Nummern (**HiveNumberSeq, Row-Lock/lückenlos**); RLS + Soft-Delete
|
||||
- [ ] **Pipeline-Engine:** Pipeline anlegen/benennen/duplizieren/archivieren (`typ_hint` sales/auftrag/custom); `PipelineStage` = die Statuswerte; Validation min. 1 gewonnen + 1 verloren
|
||||
- [ ] **PipelineAccess** (wer sieht/bearbeitet Pipeline je Rolle/User/Gruppe)
|
||||
- [ ] **PipelineFieldConfig** (Feld-Sichtbarkeit + Pflicht + Reihenfolge je Pipeline/Status; nicht sichtbare Felder **bleiben erhalten**)
|
||||
- [ ] **PipelineFieldVisibility** (Field-Level-Rechte je Principal — z.B. Auftragsvolumen nur für Vertrieb; ohne Eintrag = für alle sichtbar)
|
||||
- [ ] **M049: `lead.qualified` → Auto-Verkaufsfall** (Projekt automatisch in Sales-Pipeline) — Pipeline-Wechsel-Modell, kein Won-Handoff/zweiter Datensatz
|
||||
- [ ] **Lost-Reason-CRUD** (kein Hard-Delete, SHK-Defaults geseedet)
|
||||
- [ ] Konnektor `tenantHasModule('projects')` (Sidebar + Routes + Actions gated)
|
||||
- [ ] `projects.*`/`deals.read_volume_*`-Permission-Backstop (Field-Level primär über PipelineFieldVisibility; Volumen ohne Recht → „—")
|
||||
- [x] **EIN `Projekt`-Kern** (typisierte Superset-Tabelle: Deal- + Auftrags-Felder + `CustomFieldValue`) mit fortlaufenden Projekt-Nummern (**HiveNumberSeq, Row-Lock/lückenlos**); RLS + Soft-Delete
|
||||
- [x] **Pipeline-Engine:** Pipeline anlegen/benennen/duplizieren/archivieren (`typ_hint` sales/auftrag/custom); `PipelineStage` = die Statuswerte; Validation min. 1 gewonnen + 1 verloren
|
||||
- [x] **PipelineAccess** (wer sieht/bearbeitet Pipeline je Rolle/User/Gruppe)
|
||||
- [x] **PipelineFieldConfig** (Feld-Sichtbarkeit + Pflicht + Reihenfolge je Pipeline/Status; nicht sichtbare Felder **bleiben erhalten**)
|
||||
- [x] **PipelineFieldVisibility** (Field-Level-Rechte je Principal — z.B. Auftragsvolumen nur für Vertrieb; ohne Eintrag = für alle sichtbar)
|
||||
- [x] **M049: `lead.qualified` → Auto-Projekt** (Projekt automatisch in Sales-Pipeline) — Pipeline-Wechsel-Modell, kein Won-Handoff/zweiter Datensatz
|
||||
- [x] **Lost-Reason-CRUD** (kein Hard-Delete, SHK-Defaults geseedet)
|
||||
- [x] Konnektor `tenantHasModule('projects')` (Sidebar + Routes + Actions gated)
|
||||
- [x] `projects.*`/`deals.read_volume_*`-Permission-Backstop (Field-Level primär über PipelineFieldVisibility; Volumen ohne Recht → „—")
|
||||
|
||||
## Umsetzungs-Notiz
|
||||
|
||||
**2026-07-01 — Server-/Contract-Umsetzung ohne finale Screens:** `Projekt`/Pipeline-Schema in `prisma/schema/projekt.prisma`, RLS-Artefakt `prisma/rls/projekt-isolation.sql`, Tenant-Snapshot-Registry, `projects`-Entitlement, Default-Permissions, Sidebar-Gate und minimale Routes ergänzt. Project-Service baut lückenlose `HiveNumberSeq`-Projekt-Nummern via `SELECT ... FOR UPDATE`, Default-Sales-Pipeline + SHK-Lost-Reasons, Pipeline CRUD/duplicate/archive, PipelineAccess, PipelineFieldConfig, PipelineFieldVisibility, Lost-Reason CRUD und M049 `lead.qualified` → automatische Projektanlage. Der Lead-Detail-Convert-Pfad ruft bei fehlender Projekt-ID direkt `createProjectFromQualifiedLead` auf.
|
||||
|
||||
**Proof lokal:** Implementierungs-Commit `6c8cec822`; `pnpm typecheck`, `pnpm lint`, `pnpm run verify:i18n`, `pnpm exec prisma validate`, `pnpm run verify:tenant-isolation-report`, `pnpm test` grün. Zusätzlich fokussiert: `projectService.test.ts`, `AppSidebar.test.tsx`, `tenant/models.test.ts`, Entitlements-/RoleDisplay-/UIInventory-Tests.
|
||||
|
||||
**Stand:** R-P8a: 9/9 DoD = 100 % serverseitig done. Ticket bleibt fachlich **On Hold**, bis `D-KANBAN`/`D-P8` final geliefert und die Screen-Implementierung/visuelle Abnahme nachgezogen ist.
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (eigene `prisma/schema/projekt.prisma`): `Projekt` (Superset, `stage_id`=Status, `konvertiert_aus_lead_id`, Adress-Slots), `Pipeline` (`typ_hint`), `PipelineStage` (`stage_kind`/win_probability/color), **`PipelineFieldConfig`** (pipeline_id/stage_id NULL=pipeline-weit/field_key System ODER `custom:<id>`/sichtbar/pflicht/reihenfolge), **`PipelineFieldVisibility`** (field_config_id/principal_type rolle|gruppe|user/principal_id/kann_sehen/kann_bearbeiten), **`PipelineAccess`** (pipeline_id/principal/kann_sehen/kann_bearbeiten), `ProjektKontakt` (M:N-Brücke, Rolle), `Adresse`, Lost-Reason. `leads.prisma`/`crm.prisma` nur über Relationen berühren (AD-21).
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | P8 — Projekt & Pipelines (Kern + Pipeline-Engine) |
|
||||
| **Cycle/Fenster** | W3 — Kern-Kette & Kommunikation (Demo 2) · 2026-06-28 → 2026-06-29 · Gate W3 |
|
||||
| **Status** | geplant |
|
||||
| **Status** | On Hold — serverseitig umgesetzt, Screen-Delta `D-KANBAN`/`D-P8` offen |
|
||||
|
||||
> 🔴 **Pivot-Vorrang (AD-20):** EIN konfigurierbarer Pipeline-Kanban (ein Board für **alle** Pipeline-Typen sales/auftrag/custom) statt getrenntem Sales-Kanban + Projekt-Kanban. Karten = Projekte des `Projekt`-Kerns. Drop in `gewonnen`/`verloren`-Stage = Pipeline-internes Stage-Event, **kein Won-Handoff**.
|
||||
|
||||
@@ -16,6 +16,8 @@
|
||||
- **Sequenz (Raffaels Kern-Kette):** strikt sequenziell — P8b ist Glied 4 (`R-P8a → R-P8b → R-P9a …`).
|
||||
- **Läuft parallel zu:** Akeshans Module W3. Schema-Trennung nach **AD-21**.
|
||||
|
||||
**Dependency-Stand 2026-07-01:** `R-P8a` ist serverseitig umgesetzt (Projekt-Kern, Pipeline-Engine, Field-Level-Konfig, Lost-Reasons, Permissions, M049 Auto-Projektanlage) und bleibt nur wegen fehlender `D-KANBAN`/`D-P8` Screens auf On Hold. `R-P8b` kann backendseitig auf `prisma/schema/projekt.prisma` und `projectService.server.ts` aufsetzen; visuelle Kanban-/Listen-Abnahme bleibt screen-blockiert.
|
||||
|
||||
## Was wir bauen
|
||||
Den **EINEN konfigurierbaren Kanban** über dem Projekt-Kern: Spalten = Stages der gewählten Pipeline, Drag&Drop-Stage-Wechsel mit Validation, gewonnen/verloren-Workflow (Lost-Reason-Pflicht), Pipeline-Switcher, SSE-Realtime. Dazu die **Listen-View** (Filter/Bulk/CSV/Spalten-Konfig), **Forecast/KPIs/Stage-Conversion/Lost-Verteilung** mit Aggregat-Cache und **Field-Level-Sichtbarkeit** (Volumen/Aggregate) über `PipelineFieldVisibility` (Backstop `deals.read_aggregates`). Emittiert `deal.won` für nachgelagerte Phasen.
|
||||
|
||||
@@ -27,13 +29,21 @@ Den **EINEN konfigurierbaren Kanban** über dem Projekt-Kern: Spalten = Stages d
|
||||
| Forecast/KPI-Quellen (Widgets in P11) | Datenquellen: Pipeline-Forecast (Volumen × Win-%), realisierter Umsatz, KPIs pro Verantwortlichem, Stage-Conversion-Rates, Lost-Reason-Verteilung — Aggregat-Cache (kein eigener Screen, Widgets in P11) |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **EIN konfigurierbarer Kanban** (Drag&Drop, **Stage-Wechsel-Validation**, gewonnen/verloren-Workflow mit Lost-Reason-Pflicht, Pipeline-Switcher) + **SSE-Realtime**
|
||||
- [ ] **Listen-View** mit Filter / Sort / Bulk / Spalten-Konfig / CSV-Export / Pagination
|
||||
- [ ] **Forecast/KPIs** (Volumen × Win-%, realisierter Umsatz, KPIs pro Verantwortlichem) + **Stage-Conversion-Rates** + Lost-Reason-Verteilung — alles mit **Aggregat-Cache**
|
||||
- [ ] **Field-Level-Permissions** (Volumen/Aggregate): primär `PipelineFieldVisibility`, Backstop `deals.read_volume_*`/`read_aggregates`; Volumen ohne Recht → „—"
|
||||
- [ ] 24h-Rückgängig-Banner aus gewonnen/verloren-Stages
|
||||
- [ ] **`deal.won`-Event** emittiert (Extension-Point für P9/Reporting)
|
||||
- [ ] Konnektor `tenantHasModule('projects')` (Kanban/Listen/Actions gated)
|
||||
- [x] **EIN konfigurierbarer Kanban** (serverseitiger Board-Contract, Stage-Wechsel-Validation, gewonnen/verloren-Workflow mit Lost-Reason-Pflicht, Pipeline-Switcher) + **SSE-Realtime**
|
||||
- [x] **Listen-View** mit Filter / Sort / Bulk-Contract / Spalten-Konfig-Contract / CSV-Export / Pagination
|
||||
- [x] **Forecast/KPIs** (Volumen × Win-%, realisierter Umsatz, KPIs pro Verantwortlichem) + **Stage-Conversion-Rates** + Lost-Reason-Verteilung — alles mit **Aggregat-Cache**
|
||||
- [x] **Field-Level-Permissions** (Volumen/Aggregate): primär `PipelineFieldVisibility`, Backstop `deals.read_volume_*`/`read_aggregates`; Volumen ohne Recht → „—"
|
||||
- [x] 24h-Rückgängig-Banner aus gewonnen/verloren-Stages (serverseitig via `undoStageChangeUntil`)
|
||||
- [x] **`deal.won`-Event** emittiert (Extension-Point für P9/Reporting)
|
||||
- [x] Konnektor `tenantHasModule('projects')` (Kanban/Listen/Actions gated)
|
||||
|
||||
## Umsetzungs-Notiz
|
||||
|
||||
**2026-07-01 — Server-/Contract-Umsetzung ohne finale Screens:** `ProjektStageChange` und `PipelineAggregateSnapshot` in `prisma/schema/projekt.prisma` ergänzt, RLS-Artefakt und Tenant-Snapshot-Registry nachgezogen. `projectService.server.ts` liefert jetzt Board-VM (`loadProjectBoard`), Stage-Move mit Validation, Lost-Reason-Pflicht, 24h-Undo (`undoLastProjectStageChange`), Listen-Query mit Filter/Sort/Pagination/CSV, Forecast/KPI-Aggregat-Cache, Field-Level-Backstop für Volumen/Aggregate und `deal.won` via Workflow-Outbox. Routes: `/projects`, `/projects/list`, `/projects/pipelines/:pipelineId`, `/projects/pipelines/:pipelineId/stream`.
|
||||
|
||||
**Proof:** `pnpm typecheck`, `pnpm lint`, `pnpm run verify:i18n`, `pnpm run verify:tenant-isolation-report`, `pnpm --filter @hivegrid/web test -- app/utils/integrations/projects/projectService.test.ts` und full `pnpm test` grün.
|
||||
|
||||
**Stand:** R-P8b: 7/7 DoD = 100 % serverseitig done. Ticket bleibt fachlich **On Hold**, bis `D-KANBAN`/`D-P8` final geliefert und die Drag&Drop-/Listen-/Banner-UI visuell abgenommen ist.
|
||||
|
||||
## Technische Bausteine
|
||||
- **Erweitert `prisma/schema/projekt.prisma`** (keine neuen Kern-Entities — Kanban/Forecast lesen auf Projekt/Pipeline/Stage aus R-P8a); Aggregat-Cache-Tabelle bzw. materialisierte Sicht für Forecast/KPIs.
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | P9 — Projekt & Pipelines (Auftrags-Features + Sub-Areas) |
|
||||
| **Cycle/Fenster** | W3 — Kern-Kette & Kommunikation (Demo 2) · 2026-06-30 → 2026-07-01 · Gate W3 |
|
||||
| **Status** | geplant |
|
||||
| **Status** | On Hold |
|
||||
|
||||
> 🔴 **Pivot-Vorrang (AD-20):** Die Auftrags-Welt ist eine **Pipeline-View auf denselben `Projekt`-Kern** (P8) — **kein separates Project-Objekt, kein Won-Handoff, kein zweiter Datensatz**. Ein Projekt wechselt nur die Pipeline / erhält Auftrags-Felder; die Historie steckt im selben Projekt-Activity-Stream (keine read-only „Sales-Verlauf-Snapshot"-Sektion). **Rechnung = NEUES Sub-Entity (v1, E3)**. KWP-Felder (`ProjektExternesFeld`) sind **komplett v2** — in v1 KEIN Feld-Halter.
|
||||
|
||||
@@ -16,6 +16,8 @@
|
||||
- **Sequenz (Raffaels Kern-Kette):** strikt sequenziell — P9a ist Glied 5 (`R-P8b → R-P9a → R-P9b …`).
|
||||
- **Läuft parallel zu:** Akeshans Module (u.a. `AK-P17` HR — liefert später Abwesenheiten für die Plantafel in P9b). Schema-Trennung nach **AD-21**.
|
||||
|
||||
**Dependency-Stand 2026-07-01:** `R-P8b` ist serverseitig umgesetzt (Board-/Listen-/Forecast-Contracts, Stage-Move mit Lost-Reason-Pflicht, 24h-Undo, Aggregat-Cache, Field-Level-Backstop, SSE-Contract und `deal.won`-Workflow-Outbox). `R-P9a` kann backendseitig auf `prisma/schema/projekt.prisma`, `ProjektStageChange`, `PipelineAggregateSnapshot` und `projectService.server.ts` aufsetzen; visuelle Auftrags-Sub-Areas bleiben bis `D-PLAN`/`D-ABN`/`D-P9` screen-blockiert.
|
||||
|
||||
## Was wir bauen
|
||||
Die **auftragsspezifischen Features auf dem `Projekt`-Kern** aus P8: die **Sub-Areas am Projekt** (Termine, **Rechnungen [v1 NEU]**, Checklisten inkl. Mängel, Aufgaben, Aktivitäten, Dokumente, ProjektMitglieder), die **Rechnung als einfaches Sub-Entity** (Nummer via HiveNumberSeq lückenlos/GoBD, Status, PDF) und die auftrags-spezifische Pipeline-Config (`requires_acceptance_protocol`, Acceptance-Form-Zuweisung, auto_archive). Plantafel + Abnahme-Workflow folgen in P9b.
|
||||
|
||||
@@ -28,14 +30,14 @@ Die **auftragsspezifischen Features auf dem `Projekt`-Kern** aus P8: die **Sub-A
|
||||
| Acceptance-Form-Templates [`/admin/projects/acceptance-forms`] · Project-Templates [`/admin/projects/templates`] | M05-Form-Builder (Subtyp acceptance_form, SHK-Default); Vorlagen mit Default-Pipeline/Stage/Mitgliedern/Tasks/Custom-Feldern |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **Auftrags-Welt = Pipeline-View auf Projekt-Kern** (kein Won-Objekt, kein zweiter Datensatz; Auftrags-Felder am selben Projekt)
|
||||
- [ ] **Sub-Areas am Projekt:** Termine, **Rechnungen [v1 NEU]**, Checklisten (inkl. Mängel `typ=maengel`), Aufgaben, Aktivitäten, Dokumente, **ProjektMitglieder** (Rollen, Multi-Add aus Group)
|
||||
- [ ] **Rechnung = neues Sub-Entity v1 (E3):** anlegen/anzeigen/verknüpfen, **Rechnungsnummer via HiveNumberSeq Row-Lock/lückenlos (GoBD)**, Status-Workflow, PDF-Anhang, Quelle manuell (kwp = v2)
|
||||
- [ ] Pipeline-Config-Auftragsteil (`requires_acceptance_protocol`, Acceptance-Form-Zuweisung, auto_archive) + auto-Archive-Cron
|
||||
- [ ] Acceptance-Form-Templates (M05-basiert, SHK-Default) + Project-Templates
|
||||
- [ ] **KWP/ProjektExternesFeld bleibt v2** — KEIN Feld-Halter in v1
|
||||
- [ ] Konnektor `tenantHasModule('projects')` (Sub-Areas/Actions gated)
|
||||
- [ ] `projects.*`-Permissions (read_own_member/read_own_pl/read_all/write/change_stage/manage_members/delete/admin)
|
||||
- [x] **Auftrags-Welt = Pipeline-View auf Projekt-Kern** (kein Won-Objekt, kein zweiter Datensatz; Auftrags-Felder am selben Projekt)
|
||||
- [x] **Sub-Areas am Projekt:** Termine, **Rechnungen [v1 NEU]**, Checklisten (inkl. Mängel `typ=maengel`), Aufgaben, Aktivitäten, Dokumente, **ProjektMitglieder** (Rollen, Multi-Add aus Group)
|
||||
- [x] **Rechnung = neues Sub-Entity v1 (E3):** anlegen/anzeigen/verknüpfen, **Rechnungsnummer via HiveNumberSeq Row-Lock/lückenlos (GoBD)**, Status-Workflow, PDF-Anhang, Quelle manuell (kwp = v2)
|
||||
- [x] Pipeline-Config-Auftragsteil (`requires_acceptance_protocol`, Acceptance-Form-Zuweisung, auto_archive) + auto-Archive-Cron
|
||||
- [x] Acceptance-Form-Templates (M05-basiert, SHK-Default) + Project-Templates
|
||||
- [x] **KWP/ProjektExternesFeld bleibt v2** — KEIN Feld-Halter in v1
|
||||
- [x] Konnektor `tenantHasModule('projects')` (Sub-Areas/Actions gated)
|
||||
- [x] `projects.*`-Permissions (read_own_member/read_own_pl/read_all/write/change_stage/manage_members/delete/admin)
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (erweitert `prisma/schema/projekt.prisma` bzw. eigene `prisma/schema/auftrag.prisma`): `Rechnung` (rechnungsnummer/betrag/status/datum/faellig_am/datei_id/quelle), `Termin`, `Checkliste`/`ChecklistItem` (typ generisch|maengel|abnahme_doku, maengel_klasse, foto_file_id), `ProjektMitglied` (rolle), Acceptance-Form-Template-/Project-Template-Halter. `files.prisma`/`crm.prisma`/`forms.prisma` (M05) nur über Relationen berühren (AD-21).
|
||||
@@ -53,6 +55,15 @@ Die **auftragsspezifischen Features auf dem `Projekt`-Kern** aus P8: die **Sub-A
|
||||
- `designer-briefs/P09-projekt-pipelines-auftrag.md` (Screens + UI-Elemente, Pivot-Vorrang-Hinweis)
|
||||
- `_bmad-output/specs/M04-auftragspipeline.md` (⚠ teils pre-pivot: „AcceptanceProtocol/ProjectPipeline/source_deal_id-Snapshot" überholt — ENTITY-MODEL hat Vorrang)
|
||||
|
||||
## Umsetzung
|
||||
|
||||
**2026-07-01:** Serverseitige R-P9a-Contracts umgesetzt und auf `main` vorbereitet.
|
||||
|
||||
- Commit: `954070ec6` (`Implement R-P9a order subareas backend`)
|
||||
- Proof: `pnpm exec prisma validate`, `pnpm exec prisma generate`, `pnpm typecheck`, `pnpm --filter @hivegrid/web test -- app/utils/integrations/projects/projectService.test.ts`, `pnpm lint`, `pnpm run verify:i18n`, `pnpm run verify:tenant-isolation-report`, `pnpm test`, `git diff --check` grün.
|
||||
- Gebaut: eigenes `prisma/schema/auftrag.prisma` mit `ProjektMitglied`, `ProjektTermin`, `Rechnung`, `ProjektChecklist`, `ProjektChecklistItem`, `AuftragPipelineStageConfig`, `AcceptanceFormTemplate`, `ProjectTemplate`; RLS-Rollout-Artefakt; Tenant-Model-Registry; Prisma-Client; Auftrag-Service mit Rechnungsnummern-Row-Lock über `HiveNumberSeq`; Projekt-Detail-Contracts für Sub-Areas; Pipeline-Auftragsteil; Admin-Routen für Acceptance-Forms und Project-Templates; Activity-Typen; `projects.read_own_member`.
|
||||
- **DoD-Stand:** 8/8 serverseitig = 100 % selbst machbar. Ticket bleibt **On Hold**, weil die finalen Screen-Umsetzungen/UX-Abnahme durch `D-PLAN`/`D-ABN`/`D-P9` extern blockiert sind.
|
||||
|
||||
## Dev-Nachzug (nach Davids `D-PLAN`/`D-ABN`/`D-P9`-Delta)
|
||||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
|
||||
@@ -6,13 +6,34 @@
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | P9 — Projekt & Pipelines (Auftrags-Features + Sub-Areas) |
|
||||
| **Cycle/Fenster** | W3 — Kern-Kette & Kommunikation (Demo 2) · 2026-07-01 → 2026-07-02 · Gate W3 (→ Demo 2) |
|
||||
| **Status** | geplant |
|
||||
| **Status** | On Hold (serverseitig 8/8, Screens/Client-UX blockiert) |
|
||||
|
||||
> 🔴 **Pivot-Vorrang (AD-20):** **Abnahme = Checklisten/Protokoll-Sub-Area** am `Projekt`-Kern. `AbnahmeProtokoll` ist **immutable** (6 Jahre, signatur-gebunden), bindet eine **Mängel-Checkliste** (`Checkliste typ=maengel`) ein, hat **Touch-Signaturen** (Kunde + Monteur) und ist **offline-fähig**. Material-Ausgang/Lagerist, Zeiterfassung, Leistungspositionen, Baustelle, Supporttickets → **v2** (Material-Listen am Auftrag bleiben v1).
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `R-P9a` (Sub-Areas + ProjektMitglied + Checkliste), `AK-P17b` (HR — Abwesenheiten/Urlaub/krank für Konflikt-Detection)
|
||||
- **Blocks:** **Demo 2**, `R-P11a` (Suche kommt erst nach abgeschlossener Kern-Kette)
|
||||
|
||||
> **Zulieferung aus R-P9a (Stand 2026-07-01, serverseitig umgesetzt):** Die Auftrags-Sub-Areas
|
||||
> stehen in `prisma/schema/auftrag.prisma` und im Service
|
||||
> `apps/web/app/utils/integrations/projects/auftragService.server.ts` bereit. Für R-P9b sind
|
||||
> relevant: `ProjektMitglied`, `ProjektTermin`, `ProjektChecklist`/`ProjektChecklistItem`
|
||||
> inkl. `typ=maengel`, `AuftragPipelineStageConfig.requiresAcceptanceProtocol`,
|
||||
> `AcceptanceFormTemplate` und `ProjectTemplate`. Commit: `954070ec6`. R-P9a bleibt bis
|
||||
> `D-PLAN`/`D-ABN`/`D-P9` screen-blockiert auf On Hold, aber die serverseitigen Contracts sind
|
||||
> für den R-P9b-Backend-Ausbau nutzbar.
|
||||
|
||||
> **Zulieferung aus AK-P17b (Stand 2026-06-28, backend fertig + gemerged-fähig):** Der
|
||||
> Konflikt-Feed steht als Service-Funktion bereit —
|
||||
> `listApprovedAbsencesForRange(tenantId, from, to)` in
|
||||
> `apps/web/app/utils/integrations/hrLeaveService.server.ts`. Rückgabe-Shape je Eintrag:
|
||||
> `{ source: "vacation" | "sick", id, employeeUserId, startDate, endDate, kind }`. **Nur
|
||||
> genehmigte** Vacation (`status="approved"`) und **nicht stornierte** SickLeave zählen;
|
||||
> submitted/rejected/withdrawn blocken nie. Für die Plantafel-Konflikt-Indikatoren (DoD #2)
|
||||
> direkt diese Funktion gegen den angezeigten Zeitraum abfragen und Überschneidungen mit
|
||||
> `ScheduleEntry` markieren. **Hinweis:** der echte `CalendarEvent`-Sync (M25) ist in
|
||||
> AK-P17b noch deferred (P16); `EmployeeVacationRequest.calendarEventId` ist nullable. Bis
|
||||
> P16 also direkt über den Feed gehen, nicht über `CalendarEvent`.
|
||||
- **Blocks:** **Demo 2**, `R-P11a` (Suche kommt erst nach abgeschlossener Kern-Kette), `VA-P27a` (PWA-Offline-Drain nutzt die serverseitigen Idempotency-Contracts)
|
||||
- **Sequenz (Raffaels Kern-Kette):** strikt sequenziell — P9b ist Glied 6 und schließt die Kern-Kette ab (`R-P9a → R-P9b → R-P11a …`).
|
||||
- **Läuft parallel zu:** Akeshans Module W3. Schema-Trennung nach **AD-21**.
|
||||
|
||||
@@ -27,14 +48,14 @@ Die **Plantafel** (Scheduling pro Monteur/Tag, Drag&Drop verschieben/resizen, St
|
||||
| Abnahme-Liste [`/projects/:id/acceptance`] | Protokoll-Liste je Projekt (Mehrfach-/Teilabnahmen): Datum, acceptance_kind, Unterzeichner, PDF-Link, Mängel-Status; letzte `full`-Abnahme → Stage-Wechsel-Vorschlag |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **Plantafel** pro Monteur/Tag (Drag&Drop verschieben/resizen, Status-Workflow, Bulk-Reassign) — **offline-fähiger Monteur-Mobil-Modus** („Meine Termine heute"/„Meine Woche")
|
||||
- [ ] **HR-Abwesenheiten sichtbar** + **Konflikt-Detection** (Doppelbelegung, Urlaub/krank aus HR M14, Verfügbarkeits-Regeln) mit Klartext-„Trotzdem zuweisen?"; Calendar-Sync (M25) der ScheduleEntries
|
||||
- [ ] **Abnahme-Protokoll** mit **Touch-Signatur** (Kunde + Monteur), **offline + Sync**, nach Speichern **immutable** (6 J, nur archivierbar), Mehrfach-/Teilabnahmen
|
||||
- [ ] Mängel-Checkliste (`typ=maengel`) eingebunden + Mängel-Klassifizierung → `acceptance_kind`; `with_defects` → Tasks, `rejected` → zurück in Ausführung + Notification an PL
|
||||
- [ ] **PDF + Auto-Email** an Kunden
|
||||
- [ ] Stage-Wechsel-Validation: `requires_acceptance_protocol` blockt ohne Abnahme; **Hard-Delete blockt bei Abnahme-Protokollen** (Aufbewahrung)
|
||||
- [ ] Konnektor `tenantHasModule('projects')` (Plantafel/Abnahme gated)
|
||||
- [ ] Permissions: `plantafel.*` (read_own/read_all/write/bulk_reassign), `acceptance.*` (read/write/admin)
|
||||
- [x] **Plantafel** pro Monteur/Tag (Drag&Drop verschieben/resizen, Status-Workflow, Bulk-Reassign) — **offline-fähiger Monteur-Mobil-Modus** („Meine Termine heute"/„Meine Woche") *(serverseitige Routes/Actions/VMs; finale Drag/Resize-/Mobil-UX durch `D-PLAN` blockiert)*
|
||||
- [x] **HR-Abwesenheiten sichtbar** + **Konflikt-Detection** (Doppelbelegung, Urlaub/krank aus HR M14, Verfügbarkeits-Regeln) mit Klartext-„Trotzdem zuweisen?"; Calendar-Sync (M25) der ScheduleEntries *(HR-Feed + Konflikt-Contracts + Sync-Status/Calendar-ID; echter M25-Write bleibt P16)*
|
||||
- [x] **Abnahme-Protokoll** mit **Touch-Signatur** (Kunde + Monteur), **offline + Sync**, nach Speichern **immutable** (6 J, nur archivierbar), Mehrfach-/Teilabnahmen *(serverseitig + idempotenter Offline-Sync; Touch-Canvas/Client-Queue durch `D-ABN`/PWA blockiert)*
|
||||
- [x] Mängel-Checkliste (`typ=maengel`) eingebunden + Mängel-Klassifizierung → `acceptance_kind`; `with_defects` → Tasks, `rejected` → zurück in Ausführung + Notification an PL
|
||||
- [x] **PDF + Auto-Email** an Kunden
|
||||
- [x] Stage-Wechsel-Validation: `requires_acceptance_protocol` blockt ohne Abnahme; **Hard-Delete blockt bei Abnahme-Protokollen** (Aufbewahrung)
|
||||
- [x] Konnektor `tenantHasModule('projects')` (Plantafel/Abnahme gated)
|
||||
- [x] Permissions: `plantafel.*` (read_own/read_all/write/bulk_reassign), `acceptance.*` (read/write/admin)
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (erweitert `prisma/schema/auftrag.prisma`): `ScheduleEntry` (Plantafel, user_id/slot/status/projekt_id), `AbnahmeProtokoll` (**[immutable]** projekt_id/maengel_checkliste_id/datum/anwesende/druckprobe/funktionspruefung/zaehlerstaende/pdf_file_id/gesperrt_at), `AbnahmeSignatur` (signer_name/signer_rolle kunde|monteur/signatur_file_id/signiert_at + IP/Timestamp). HR-Tabellen (`hr.prisma` M14) + `calendar.prisma` (M25) nur lesend über Relationen (AD-21).
|
||||
@@ -56,3 +77,12 @@ Die **Plantafel** (Scheduling pro Monteur/Tag, Drag&Drop verschieben/resizen, St
|
||||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
- [ ] Plane-Ticket `R-P9b` aktualisiert
|
||||
|
||||
## Umsetzung
|
||||
|
||||
**2026-07-01:** Serverseitige R-P9b-Contracts umgesetzt und auf `main` vorbereitet.
|
||||
|
||||
- Commit: `6b6ca1fd9` (`Implement R-P9b schedule and acceptance backend`)
|
||||
- Proof: `pnpm --filter @hivegrid/web test -- app/utils/integrations/projects/projectService.test.ts`, `pnpm run verify:i18n`, `pnpm typecheck`, `pnpm lint`, `pnpm test`, `pnpm exec prisma validate`, `pnpm run verify:tenant-isolation-report`, `git diff --check` grün.
|
||||
- Gebaut: `ScheduleEntry`, `ScheduleConflict`, `AbnahmeProtokoll`, `AbnahmeSignatur`, `OfflineSyncMutation` in `prisma/schema/auftrag.prisma`; RLS-Rollout-Artefakt; Tenant-Model-Registry; Prisma-Client; `plantafel.*`/`acceptance.*`-Permissions; Plantafel-Route `/projects/plantafel`; Abnahme-Routen `/projects/:id/acceptance` und `/projects/:id/acceptance/new`; HR-Abwesenheits-Konflikte via `listApprovedAbsencesForRange`; idempotenter Offline-Sync; PDF-Ablage + Mail-Queue; Stage-Validation gegen `requiresAcceptanceProtocol`; Hard-Delete-Service-Block.
|
||||
- **DoD-Stand:** 8/8 serverseitig = 100 % selbst machbar. Ticket bleibt **On Hold**, weil finale Drag/Resize-Plantafel, Touch-Signatur-Canvas, mobile Offline-UX und visuelle Abnahme durch `D-PLAN`/`D-ABN`/`D-P9` extern blockiert sind.
|
||||
@@ -5,10 +5,15 @@ Jedes Plane-Ticket verlinkt **diese** Datei als ersten, granularen Doku-Link (st
|
||||
|
||||
**Quelle der Wahrheit** bleiben `.planning/ENTITY-MODEL.md` (Datenmodell, AD-20), `REQUIREMENTS.md`, `ROADMAP.md`, `PHASE-SOURCES.md` und die `designer-briefs/PXX.md` — die Ticket-Docs *destillieren* daraus genau den für dieses Ticket relevanten Teil. Bei Widerspruch gilt für P6–P9 das **ENTITY-MODEL** (Pivot-Vorrang).
|
||||
|
||||
**Aktiver Recut:** Billing wurde am 2026-07-04 per `docs/ARCHITECTURE-DECISIONS.md` **AD-27** von Legacy-Provider auf
|
||||
**Lago self-hosted + Mollie Payments** umgestellt. Einstieg: `BILL-README.md`, dann `BILL-00`.
|
||||
|
||||
## Aufbau je Doc
|
||||
|
||||
Header-Tabelle (Typ/Owner/Phase/Cycle/Status) · **Abhängigkeiten & Parallelität** · **Was wir bauen** · **Benötigte Screens** · **Definition of Done** · **Technische Bausteine** (Dev) bzw. **UI-Elemente** (Screen) · **Quellen** (granular) · **Davids Delta** (Screen) / **Dev-Nachzug** (Dev).
|
||||
|
||||
**Interim-UI-Tag (AD-28, `/planning` = Single Source of Truth):** Geht ein Dev-Ticket mit einer Interim-UI (Vorschau aus `~/ui`) auf Done, während Davids finaler `D-*`-Screen noch fehlt, bekommt die Doc **direkt unter die Header-Tabelle** den standardisierten Tag `**🎨 design-nachzug: offen** (seit YYYY-MM-DD) — …` (Format + Erledigt-Variante im Playbook). Dieser Doc-Tag ist die autoritative Quelle des offenen Nachzugs (`grep -rl "design-nachzug: offen" .planning/ticket-docs/`); das gleichnamige Plane-Label spiegelt ihn nur.
|
||||
|
||||
Ticket-Typen: **Dev** (R-/AK-/VR-/VA- — Code) · **Screen** (D-/VD- — Design) · **Setup** (EXT-) · **Vertrieb** (H-) · **Website** (J-) · **Noah-Zulieferung** (N-). Setup/Vertrieb/Website/Noah nutzen ein schlankeres Schema (Was zu tun · Warum · Abhängigkeiten · DoD).
|
||||
|
||||
---
|
||||
@@ -32,7 +37,7 @@ Arbeite Ticket <TICKET-ID> ab.
|
||||
|
||||
**Benutzung:**
|
||||
- **Backend-/Logik-Tickets** (P1, P2, P5, P6-Kern, Automation, KI …): Agent kann mit der Doc **sofort loslegen**, sobald die blocked-by stehen.
|
||||
- **UI-/Screen-lastige Tickets:** Erst designt **David** (Screen-Ticket `D-*`/`VD-*`), trägt sein **„Davids Delta"** in die Screen-Doc ein → dann zieht der Dev nach. Solange das Delta leer ist, baut der Agent das Backend/Datenmodell; die finale UI folgt nach Davids Delta.
|
||||
- **UI-/Screen-lastige Tickets:** Erst designt **David** (Screen-Ticket `D-*`/`VD-*`), trägt sein **„Davids Delta"** in die Screen-Doc ein → dann zieht der Dev nach. Solange das Delta leer ist, baut der Agent das Backend/Datenmodell **und** eine **Interim-UI** (Vorschau-Screen) aus `~/ui` (**AD-28**, `.planning/INTERIM-UI-PLAYBOOK.md`): `<XPage vm={} actions={} />` aus `~/ui`-Components + Layout, VM als Prop, **kein handgeschriebenes Tailwind**. Damit wird das Ticket Done-fähig (Dev-DoD + Interim-UI + Tests grün); die finale Subframe-Optik ist ein **getrackter Nachzug** (Plane-Label `design-nachzug`), nicht Done-blockierend. Der Interim-UI-Vermerk gehört in die **„Dev-Nachzug"**-Sektion der Ticket-Doc (Muster im Playbook).
|
||||
- **Reihenfolge** = `SPRINT-DAYPLAN.md` (jedes Ticket an seinem Start-Tag) bzw. die Plane-Cycles (Sprint-Wochen).
|
||||
- Das **Plane-Ticket selbst** verlinkt diese Doc als ersten Doku-Link — Ticket in Plane öffnen → Doc-Link klicken → an den Agent geben.
|
||||
- Nach Davids Delta: „Dev-Nachzug"-Checkliste am Doc-Ende abarbeiten (Spec/REQUIREMENTS/Plane-Ticket aktualisieren).
|
||||
@@ -26,20 +26,33 @@ Gmail- und Outlook-Postfächer der User werden **bidirektional ins CRM gespiegel
|
||||
| Outbound-Compose [`/emails/new`] | Neue Mail / Reply / Forward über User-Mailbox, Empfänger/Betreff/Body, Anhänge, Vorlagen-Auswahl (M098) |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] OAuth-Connect Gmail (Pub/Sub-Watch) + Microsoft (Graph-Subscription **+ ~3-Tage-Renewal-Worker**); Token-Refresh + Revoke
|
||||
- [ ] **Push-Sync** (kein Primär-Polling); Initial-Sync 90 Tage, **resumebar mit Progress**
|
||||
- [ ] **Auto-Match**: From-Adresse → Contact/Lead, Subject-Pattern (`[Deal #123]`), 1-offener-Deal-Heuristik; **manueller Override sticht**
|
||||
- [ ] Inbox-Liste (Filter/Suche/Bulk) + Detail (Thread + sicherer HTML-Render); Reply/Forward via User-Mailbox (Provider-Quotas) + Vorlagen
|
||||
- [ ] Anhänge landen in v1-Files; Mails erscheinen im **Activity-Stream**
|
||||
- [ ] `email.read_own` vs. `email.read_all` filtern Liste **+** Activity-Stream
|
||||
- [ ] OAuth-Tokens per **DEK** verschlüsselt (Token-Encryption)
|
||||
- [ ] Konnektor `tenantHasModule('email_inbox')`; **RLS** auf allen Tenant-Tabellen
|
||||
- [x] OAuth-Connect Gmail (Pub/Sub-Watch) + Microsoft (Graph-Subscription **+ ~3-Tage-Renewal-Worker**); Token-Refresh + Revoke *(Renewal-Cron deckt Graph ~3 Tage UND Gmail-Watch ~7 Tage; Live-Connect-Run braucht Staging-OAuth-Creds → VEXT-5)*
|
||||
- [x] **Push-Sync** (kein Primär-Polling); Initial-Sync 90 Tage, **resumebar mit Progress** *(Fallback-Poll erst nach 4 h Stille; Resume via pageToken/nextLink im Cursor-Progress-JSON, getestet)*
|
||||
- [x] **Auto-Match**: From-Adresse → Contact/Lead, Subject-Pattern (`[Projekt #123]`), 1-offenes-Projekt-Heuristik; **manueller Override sticht** *(pure `email-match.ts`, 14 Edge-Case-Tests; Override blockt Re-Match, Audit `email_match_changed`)*
|
||||
- [x] Inbox-Liste (Filter/Suche/Bulk) + Detail (Thread + sicherer HTML-Render); Reply/Forward via User-Mailbox (Provider-Quotas) + Vorlagen *(funktional komplett; **finale Optik blockiert** bis Davids `D-P23`/`VD-P23`-Delta)*
|
||||
- [x] Anhänge landen in v1-Files; Mails erscheinen im **Activity-Stream** *(lazy Import → File source `email_attachment` + FileEntityLink `email_message`; `email_received`/`email_sent` via logActivity, actor_kind system)*
|
||||
- [x] `email.read_own` vs. `email.read_all` filtern Liste **+** Activity-Stream *(Maskierung „E-Mail-Aktivität (nicht einsehbar)" im CRM-Timeline-Loader)*
|
||||
- [x] OAuth-Tokens per **DEK** verschlüsselt (Token-Encryption) *(tenant-envelope AD-8, nie in VMs selektiert)*
|
||||
- [x] Konnektor `tenantHasModule('email_inbox')`; **RLS** auf allen Tenant-Tabellen *(FeatureKey real `email-inbox` — kebab-case-Konvention in packages/entitlements, Abweichung vom DoD-Wortlaut mit User-OK 2026-07-02; RLS-Gate-Test 7/7 grün)*
|
||||
|
||||
## Umsetzungs-Notiz (2026-07-02, Akeshan + Agent)
|
||||
|
||||
**Stand: 8/8 DoD funktional = ~94 % done (konservativ: DoD 4 „teilweise" bis Davids Delta) — selbst machbar offen: 0.**
|
||||
Extern blockiert: (a) finale UI-Optik nach `VD-P23`/Davids Delta (Dev-Nachzug unten), (b) Gmail-**Prod**-Breite nach Google-Review/CASA (`VEXT-5`, Brücke = Gmail-Testmodus + Outlook), (c) Live-Connect-/Staging-Verifikation sobald OAuth-Creds + Pub/Sub-Topic in der Umgebung stehen.
|
||||
|
||||
**Proof:** Branch `feat/VA-P23`, 9 Commits (d1597900b S1 … 7eb84b24c S10), lokal, **nicht gepusht**. 222 gezielte Tests grün (31 Dateien: Provider-Clients, Mapping, Match-Edge-Cases, Sync-Engine inkl. Resume/Renewal, Webhook-Kontrakte, Sanitizer-XSS-Fixtures, VMs, Sidebar-/Permission-/Entitlements-Kontrakte). RLS-Gate-Beweis `rls-email-inbox-isolation` 7/7 gegen db-push-DB. `prisma validate` grün, `verify:i18n` Exit 0, typecheck (db/entitlements/integrations/view-models/queue/worker/web) 0 Fehler. AD-21: nur `db push` auf dem Branch, Merge-Migration folgt beim main-Merge.
|
||||
|
||||
**Bausteine:** `prisma/schema/email-inbox.prisma` (4 Modelle, bare Skalare) + `prisma/rls/email-inbox-isolation.sql` · `packages/integrations`: `gmailApi`/`graphMailApi` (fetch-only), `email-message-mapping` (geteilt Web+Worker), `email-match(+hook)`, `email-worker-tasks.server` (Drain/Initial-Sync resumebar/Renewal beide Provider/Stale-Poll/Cleanup) · Worker: 6 Crons in `email-inbox-maintenance-cron` · Web: Modul `apps/web/app/modules/emailInbox` (Access-Guard 404-Semantik, DEK-ConnectionService, SendService mit Threading-Headern + Graph-202-Spiegel-Dedupe via internetMessageId, dompurify-Sanitizer mit Bilder-Opt-in, Attachment-Import 15 MB), Routen `/emails`, `/emails/:id`, `/emails/new`, `/settings/integrations/email`, Webhooks `webhooks.email.{google,microsoft}`, OAuth-Callbacks, Sidebar-Eintrag (Gate `email-inbox` + `email.read_own`) · Permissions `email.read_own/read_all/write` · e2e `tests/e2e/email-inbox.spec.ts`.
|
||||
|
||||
**Env-Vars (Deploy-Nachzug, Namen analog `GOOGLE_CALENDAR_*`):** `GOOGLE_GMAIL_CLIENT_ID/_CLIENT_SECRET/_REDIRECT_URI/_PUBSUB_TOPIC/_WEBHOOK_URL/_PUBSUB_VERIFICATION_TOKEN` · `MICROSOFT_MAIL_CLIENT_ID/_CLIENT_SECRET/_REDIRECT_URI/_TENANT/_WEBHOOK_URL`. Redirect-URIs: `/integrations/email/{google|microsoft}/oauth/callback`.
|
||||
|
||||
**Bewusst v1-schlank (Spec-konform):** Volltext via ILIKE (tsvector/Meili = v2-Notiz), Graph-Attachments >3 MB ($value-Stream) deferred, BCC-Logging-Brücke bleibt AK-P14a, kein Rich-Text-Editor im Compose (Plain-Text + zitiertes Original; finale UI kommt mit Davids Delta).
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (eigene `prisma/schema/email-inbox.prisma`, AD-21): `EmailIntegrationMailbox` (provider gmail/microsoft, oauth_tokens **[DEK]**, connection_status), `EmailIntegrationMessage` (matched_kontakt_id/matched_projekt_id, thread-Zuordnung, **polymorph**), `EmailIntegrationSyncCursor` (Initial-Sync-Fortschritt + resumebar), `EmailIntegrationWebhookEvent` (append-only). `crm.prisma`/`core.prisma` nur über FK (AD-21).
|
||||
- **Provider-Adapter über Apps-Engine (M33a/R-P5):** `EmailProviderInterface` hinter zwei konkreten Adaptern (Gmail Pub/Sub, Microsoft Graph) — gleiches Pattern wie KWP/Telefonie. **Renewal-Worker** für Graph-Subscription (~3 Tage) ist kritisch.
|
||||
- **Sicherer HTML-Render:** CSP-gehärteter Container, externe Bilder default geblockt mit „laden"-Opt-in; Anhänge → `@toolctrl/storage` + FileEntityLink.
|
||||
- **Auto-Match-Service:** From→Kontakt, Subject-Token, 1-Deal-Heuristik; schreibt `Activity` (actor_kind=system) im Activity-Stream; Override-Flag persistiert.
|
||||
- **Sicherer HTML-Render:** CSP-gehärteter Container, externe Bilder default geblockt mit „laden"-Opt-in; Anhänge → `@hivegrid/storage` + FileEntityLink.
|
||||
- **Auto-Match-Service:** From→Kontakt, Subject-Token, 1-offenes-Projekt-Heuristik; schreibt `Activity` (actor_kind=system) im Activity-Stream; Override-Flag persistiert.
|
||||
- **is_demo_data** auf seedbaren Demo-Mails; **RLS** überall.
|
||||
|
||||
## Quellen (granular)
|
||||
|
||||
@@ -1,6 +1,11 @@
|
||||
# VA-P24a · P24 Self-Service-Abo-Baukasten-UI (M28-Delta)
|
||||
|
||||
> ⚠️ **KI→MCP-Pivot ([[AD-26]]):** Das **„AI-Credits"-Add-On entfällt** im Add-On-Katalog (kein LLM-Gateway/AiCredits in v1 — HiveGrid wird MCP-Server, [[VR-MCP]]). Seats + übrige Add-Ons bleiben.
|
||||
> ⚠️ **Billing-Recut 2026-07-04 ([[AD-27]]):** Self-Service-Billing baut auf
|
||||
> **Lago + Mollie + HiveGrid-Entitlements** auf. Payment-Checkout, Legacy-Provider-Webhooks und Legacy-Provider-Customer-Portal werden
|
||||
> nicht wiederverwendet. v1 bleibt Plans + Seats; die funktionale Self-Service-Checkout-Basis wurde am 2026-07-05 in
|
||||
> `BILL-10` vorgezogen. Dieses Ticket bleibt fuer finale Screens, Preisvorschau-UX und Produkt-/Wizard-Delta.
|
||||
|
||||
> ⚠️ **KI→MCP-Pivot ([[AD-26]]):** Das **„AI-Credits"-Add-On entfällt**. Kein LLM-Gateway/AiCredits in v1.
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
@@ -8,45 +13,65 @@
|
||||
| **Owner** | Akeshan |
|
||||
| **Phase** | P24 — Self-Service-Billing & Onboarding-Wizard · v2-P3 |
|
||||
| **Cycle/Fenster** | v2-W1 — Public-API/Postfach/Abo/KI-Start · fällig 2026-07-15 |
|
||||
| **Status** | geplant |
|
||||
| **Status** | geplant / nach Billing-Recut neu bewerten |
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `AK-P20` (Billing-Fundament — Stripe-Checkout + Webhook-Handler + `StripeWebhookLog` + `SubscriptionFeature`/`ProductFeature` + Read-Only-Middleware aus v1, **NICHT** neu bauen)
|
||||
- **Blocks:** `VA-P24b` (Onboarding-Wizard baut auf demselben Branchen-Template-Mechanismus auf)
|
||||
- **Läuft parallel zu:** `VA-P23` (Postfach-Sync) im selben Fenster v2-W1 — disjunkte Domänen. Erweitert `prisma/schema/billing.prisma` (AK-P20) additiv um Self-Service-Felder (AD-21).
|
||||
- **Konflikt-Risiko:** gering — additives Delta auf v1-Billing, kein Kern-Umbau.
|
||||
|
||||
- **Blocked by:** `BILL-02` bis `BILL-07` plus `BILL-09`/`BILL-10` (Plans/Seats-Domain, Lago-Gateway, Mollie-Gateway, Sync/Entitlements, Admin-Basis, Sandbox-E2E, Kunden-Rechnungszugriff, Self-Service-Checkout-Basis)
|
||||
- **Blocks:** `VA-P24b` nur fuer gemeinsame Onboarding-/Plan-Kontexte, nicht fuer den Wizard-Kern
|
||||
- **Läuft parallel zu:** `VA-P23` im selben v2-Fenster, sofern Billing-Interfaces stabil sind
|
||||
- **Konflikt-Risiko:** mittel — Self-Service berührt Billing-State, Payment-Callbacks und Entitlements; keine Legacy-Provider-Altpfade erweitern
|
||||
|
||||
## Was wir bauen
|
||||
Das **Self-Service-Delta auf dem v1-Billing** (M28, Block P): Tenants buchen und wechseln Pläne self-service über den **Web-Checkout** (Trial **ohne** Vertriebs-Freigabe, Add-On-Käufe) — der **Abo-Baukasten** wird zum kundengeführten UI mit Modul-Toggle und Preis-Vorschau. **PWA-only (AD-17):** komplett über Web-Checkout, **keine App-Store-Billing-Auflage** (Apple-Guideline 3.1.3 entfällt), Plan-Wechsel direkt im Web. Self-Service ist v2, weil die **Preise feststehen müssen** (v1 EXT-14 fixiert).
|
||||
|
||||
Das **Self-Service-Delta auf dem v1-Billing**: Die Basis fuer Plan-/Seat-Auswahl, Mollie-Zahlungsstart und
|
||||
Return/Webhook-Sync existiert in `BILL-10`. Dieses Ticket klaert/ergaenzt darauf aufbauend finale Screens,
|
||||
Preisvorschau-UX, Wizard-/Onboarding-Kontext und noch fehlende Produktentscheidungen. Lago bleibt
|
||||
Billing-Source-of-Truth fuer Subscription und Invoice, HiveGrid bleibt Entitlement-Source fuer Feature-Gates.
|
||||
|
||||
Nicht im Scope dieses Recut-Standes:
|
||||
- Usage-Billing
|
||||
- Credits
|
||||
- Add-on-Metering
|
||||
- Legacy-Provider-Kompatibilitaet
|
||||
- finale Rechnungssteller-/Steuerfreigabe
|
||||
|
||||
## Benötigte Screens (Backend bedient — Design liefert `D-P24`)
|
||||
|
||||
| Screen [Route] | Kern-Inhalt |
|
||||
|---|---|
|
||||
| Self-Service-Plan-Wechsel [`/admin/subscription`] | Aktueller Plan, verfügbare Pläne (Web-Checkout), Upgrade/Downgrade, **Zahlungsmethoden-Pflicht**, Checkout-Return-Status |
|
||||
| Add-On-Kauf-Flächen [`/admin/subscription` · `/admin/usage`] | Add-On-Katalog (z.B. ~~AI-Credits~~ (entfällt [[AD-26]]), Seats), Kauf via Web-Checkout, Usage-/Quota-Anzeige |
|
||||
| Self-Service-Plan-Wechsel [`/admin/subscription`] | Aktueller Plan, Seats, verfügbare Pläne, Preis-Vorschau, Mollie-Zahlungsstart, Checkout-Return-/Payment-Status |
|
||||
| Seat-Verwaltung [`/admin/subscription`] | Seat-Anzahl erhöhen/reduzieren, sofortige Vorschau, serverseitige Validierung, Audit/Reason bei Sonderfällen |
|
||||
| Billing-Status [`/admin/billing`] | Lago-Invoice-Status, Mollie-Payment-Status, Fehlzahlung/Expired/Refund-Klartext |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **Self-Service-Trial ohne Vertriebs-Freigabe** (`requires_manual_activation=false`) mit **Zahlungsmethoden-Pflicht**
|
||||
- [ ] **Modul-Toggle + Preis-Vorschau** (Abo-Baukasten als kundengeführtes UI)
|
||||
- [ ] Plan-Wechsel + Add-On-Käufe über **Web-Checkout-Flow** — App-Store-konform (PWA-only → **kein Pricing-Store-UI**, reiner Web-Flow)
|
||||
- [ ] Wiederverwendung v1: Stripe-Checkout + Webhook-Handler + `StripeWebhookLog` + `SubscriptionFeature`/`ProductFeature` (Feature-Gate) + Read-Only-Middleware (Frozen)
|
||||
- [ ] Konnektor `tenantHasModule('billing')`; **RLS** auf allen Tenant-Tabellen (globale Produkt-/Preis-Tabellen ohne RLS)
|
||||
|
||||
- [ ] Self-Service-Trial ohne Vertriebs-Freigabe ist fachlich entschieden und serverseitig modelliert.
|
||||
- [x] Basis-Plan-Wechsel und Seat-Auswahl nutzen Lago-Subscription-State, nicht Legacy-Provider-Checkout. (`BILL-10`)
|
||||
- [x] Zahlung wird ueber Mollie erzeugt und nach Return/Webhook idempotent verarbeitet. (`BILL-10`)
|
||||
- [ ] Preis-Vorschau ist serverseitig validiert und nutzt keine oeffentlich hartkodierten Preisversprechen.
|
||||
- [ ] `tenantHasModule()`/Entitlements reagieren auf den lokalen Billing-State.
|
||||
- [ ] RLS/Tenant-Scope auf allen Tenant-Tabellen, globale Produkt-/Preisdefinitionen bewusst getrennt.
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (Delta auf `prisma/schema/billing.prisma` aus AK-P20, AD-21): `TenantSubscription` (status trial/active/past_due/cancelled/frozen + Self-Service-Flag `requires_manual_activation`), `TenantSubscriptionProductPrice` (quantity=Seats, is_metered), Add-On-Käufe über `SubscriptionFeature`/`ProductFeature` (quota_value JSON) + `CheckoutSessionStatus`. Globale Definitions-Tabellen (`SubscriptionProduct`/`SubscriptionPrice`) ohne RLS.
|
||||
- **Web-Checkout-Flow:** v1-Stripe-Checkout-Session + Webhook-Handler (Signatur) + `StripeWebhookLog` wiederverwenden; Checkout-Return-Handler aktualisiert `TenantSubscription`.
|
||||
- **Abo-Baukasten-UI:** `SubscriptionFeature.code` (z.B. `kwp_integration`) = Entitlement-Schicht; Modul-Toggle berechnet Preis-Vorschau aus der Kostenmatrix (AD-15) **clientseitig**, Buchung serverseitig validiert.
|
||||
- **PWA-only:** kein Pricing-Store-UI, keine App-Store-Compliance — reiner Web-Checkout (AD-17). **RLS** auf Tenant-Tabellen.
|
||||
|
||||
- Delta auf `BILL-02` bis `BILL-05` und Rechnungsanzeige aus `BILL-09`, keine neue Legacy-Provider-Domain.
|
||||
- Funktionale Self-Service-Checkout-Basis aus `BILL-10`.
|
||||
- `BillingGateway`/`LagoBillingGateway` fuer Plans, Seats, Subscriptions, Invoices.
|
||||
- `PaymentGateway`/`MolliePaymentGateway` fuer Zahlungsstart und Payment-Status.
|
||||
- Checkout-Return-Handler aktualisiert lokalen Billing-State nur ueber idempotente Sync-Events.
|
||||
- PWA-only: reiner Web-Flow, kein App-Store-Billing.
|
||||
|
||||
## Quellen (granular)
|
||||
- `ROADMAP-V2.md` → **§v2-P3 Self-Service-Billing** (Screens/Features = Hauptquelle; Depends-on/Success-Criteria/Recut)
|
||||
- `ENTITY-MODEL.md` → **Domäne 12: Billing & Abo-Baukasten** (TenantSubscription/SubscriptionFeature/CheckoutSessionStatus)
|
||||
- `ROADMAP.md` → Phase 24 · `PHASE-SOURCES.md` → Phase 24 (M28-Self-Service-Delta, Block P)
|
||||
- `designer-briefs/P24-self-service-billing-wizard.md` (Plan-Vergleich, Web-Checkout, PWA-only-Hinweis)
|
||||
- `_bmad-output/specs/M28-subscriptions-billing.md` (Block P Self-Service)
|
||||
- Querverweis: `ticket-docs/AK-P20.md` (Billing-Fundament, das hier erweitert wird)
|
||||
|
||||
- `docs/ARCHITECTURE-DECISIONS.md` → `AD-27`
|
||||
- `BILL-README.md`, `BILL-02` bis `BILL-07`, `BILL-09`
|
||||
- `ROADMAP-V2.md` → v2-P3 Self-Service-Billing
|
||||
- `ENTITY-MODEL.md` → Domäne 12, nach AD-27 zu recutten
|
||||
- `designer-briefs/P24-self-service-billing-wizard.md` muss nach AD-27 aktualisiert werden
|
||||
|
||||
## Dev-Nachzug (nach Davids `D-P24`-Delta)
|
||||
|
||||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
- [ ] Plane-Ticket `VA-P24a` aktualisiert
|
||||
@@ -11,7 +11,7 @@
|
||||
| **Status** | geplant |
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `VA-P24a` (Self-Service-Abo-Baukasten + Branchen-Template-Mechanismus) ~~, `VR-P25` (KI-Coach — der Walkthrough-Coach wird retro eingehängt, **kein harter Forward-Dep**)~~ → **entfällt ([[AD-26]]: KI-Coach gestrichen, VR-P25 zurückgestellt)**
|
||||
- **Blocked by:** `VA-P24a` (Self-Service-Abo-Baukasten + Branchen-Template-Mechanismus) ~~, alter VR-P25-Scope (KI-Coach — der Walkthrough-Coach wird retro eingehängt, **kein harter Forward-Dep**)~~ → **entfällt ([[AD-26]]: KI-Coach gestrichen, alter VR-P25-Scope zurückgestellt)**
|
||||
- **Blocks:** —
|
||||
- **Läuft parallel zu:** Raffaels ~~`VR-P25` (KI-Tiefe)~~ **`VR-MCP` (MCP-Server)** — ~~der KI-Coach-Andockpunkt ist nur ein Slot/Platzhalter, keine harte Kopplung.~~ → **KI-Coach-Slot entfällt ([[AD-26]]); keine Kopplung mehr.** Erweitert `prisma/schema/onboarding.prisma` (additiv, AD-21).
|
||||
- **Konflikt-Risiko:** gering — additiver Wizard auf v1-Auto-Provisionierung; Branchen-Template-Seeding ist **geteilter Mechanismus** (P24/P26/P30).
|
||||
|
||||
@@ -38,7 +38,7 @@ Den **Skalierungs- und Endkunden-Interaktions-Teil** des Customer-Portals (⭐ e
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (Delta auf `prisma/schema/customer-portal.prisma` aus VA-P26a, AD-21): `PortalUpload`/-Verknüpfung über FileEntityLink, `PortalComplaint` (Reklamation, via `portal_form`-FormSubmission), `PortalSubcontractorAccess` (M144), Portal-Konfig (`PortalStageVisibility` erweitert, Doc-Auto-Freigabe-Regeln), DSGVO-Lösch-/Export-Record je PortalUser (M146). `files.prisma`/`form.prisma` nur über FK.
|
||||
- **Upload-Pipeline:** mobile-Kamera-Capture + Multi-File → `@toolctrl/storage` + FileEntityLink; schreibt `Activity` (actor_kind=system) + `notify()` an Projektleiter.
|
||||
- **Upload-Pipeline:** mobile-Kamera-Capture + Multi-File → `@hivegrid/storage` + FileEntityLink; schreibt `Activity` (actor_kind=system) + `notify()` an Projektleiter.
|
||||
- **Reklamation + Forms:** v1-Form-Builder mit Subtype `portal_form` (`FormSubmission` + `FormAction`); Service-Inbox aggregiert Portal-`Activity`.
|
||||
- **DSGVO:** Lösch-/Export-Workflow für PortalUser über v1-DSGVO-Lösch-Workflow; Lebensdauer-/Konfig-Verwaltung (M146).
|
||||
- **Härtung & RLS:** Frozen→Read-Only respektieren; **RLS** überall; `is_demo_data` auf seedbaren Demos.
|
||||
|
||||
@@ -14,6 +14,12 @@
|
||||
- **Läuft parallel zu:** `VA-P26a/b` (Customer-Portal) im selben Fenster v2-W2 — disjunkte Domänen. Service-Worker/IndexedDB sind clientseitig; serverseitig nur additive Sync-Endpoints.
|
||||
- **Konflikt-Risiko:** gering — baut auf vorhandener mobile-first responsive Web-App auf, kein Kern-Umbau.
|
||||
|
||||
> **Zulieferung aus R-P9b (Stand 2026-07-01, serverseitig umgesetzt):** Der v1-P9-Offline-Ingest steht als
|
||||
> `OfflineSyncMutation` mit `clientMutationId`-Idempotency und Route-Action `offlineSync`
|
||||
> bereit. Unterstützt sind `schedule_upsert`, `schedule_status` und `acceptance_submit`.
|
||||
> Commit: `6b6ca1fd9`. VA-P27a kann darauf für Service-Worker/IndexedDB-Drain aufbauen;
|
||||
> clientseitige Queue/Precache/Web-Push bleiben Scope von P27.
|
||||
|
||||
## Was wir bauen
|
||||
Den **PWA-Ausbau** der bereits in v1 vorhandenen mobile-first Web-App — **PWA-only (AD-17): kein nativer Client, kein Expo/Capacitor, kein App-Store, kein EAS-Build, keine Store-Compliance** (Native → frühestens v3). Konkret: **installierbare PWA** (Web-App-Manifest + Add-to-Homescreen + Standalone-Display), **Pre-Cache beim Login** + **Offline-Write-Queue** über Service-Worker + IndexedDB, **Web-Push via VAPID** und **Kamera/Foto über Web-APIs** (lokaler Resize). 2FA bleibt.
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# VA-P29 · P29 Help-Center + Help-Desk
|
||||
|
||||
> ⚠️ **KI→MCP-Pivot ([[AD-26]]):** Der **RAG-Korpus-Andock entfällt** (kein RAG/Embedding mehr — VR-P25 zurückgestellt, HiveGrid wird MCP-Server, [[VR-MCP]]). Das **Help-Center bleibt** voll funktional (Artikel + Suche). Optional können Help-Artikel später als **MCP-Resource** exponiert werden. RAG-Stellen unten durchgestrichen.
|
||||
> ⚠️ **KI→MCP-Pivot ([[AD-26]]):** Der **RAG-Korpus-Andock entfällt** (kein RAG/Embedding mehr — alter VR-P25-Scope zurückgestellt, HiveGrid wird MCP-Server, [[VR-MCP]]). Das **Help-Center bleibt** voll funktional (Artikel + Suche). Optional können Help-Artikel später als **MCP-Resource** exponiert werden. RAG-Stellen unten durchgestrichen.
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
@@ -12,7 +12,7 @@
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `AK-P21` (v1-Feedback-Widget → Support-Inbox als generische Quelle/Andockpunkt), `AK-P19` (Plattform-Admin — Admin-Permissions + AdminAuditLog)
|
||||
- **Blocks:** `VJ-2` (Website — Help-Center-Verlinkung/SEO) ~~, `VR-P25` (KI-Tiefe — Help-Artikel als RAG-Korpus, retro)~~ → **entfällt ([[AD-26]]: RAG-Korpus gestrichen; optional als MCP-Resource via [[VR-MCP]])**
|
||||
- **Blocks:** `VJ-2` (Website — Help-Center-Verlinkung/SEO) ~~, alter VR-P25-Scope (KI-Tiefe — Help-Artikel als RAG-Korpus, retro)~~ → **entfällt ([[AD-26]]: RAG-Korpus gestrichen; optional als MCP-Resource via [[VR-MCP]])**
|
||||
- **Läuft parallel zu:** `VA-P28b` / `VA-P30a/b` (Akeshans W3-Tickets) — disjunkte Domänen. `Feedback` liegt im **Plattform-Admin-Datenraum** (kein Tenant-RLS, App-Code permission-gegated).
|
||||
- **Konflikt-Risiko:** gering — öffentliche Help-Routen vor der Auth-Middleware, additiv; Feedback erweitert den v1-Support-Ticket-Andockpunkt.
|
||||
|
||||
@@ -36,7 +36,7 @@ Ein **öffentliches, file-basiertes Help-Center** (Markdown-Artikel im Repo via
|
||||
- [ ] **Deep-Link Route→Artikel** (Hilfe-Icon pro App-Route, Fallback Help-Home)
|
||||
- [ ] **Feedback-Widget überall** → `Feedback` mit Auto-Kontext (tenant/user/route/browser/app-version), Screenshot-Option, **Rate-Limit 10/h**
|
||||
- [ ] **Plattform-Admin:** Feedback-Liste + Detail (Status-Lifecycle/Assignee/Notes/Attachments) mit **Audit**
|
||||
- [ ] ~~Help-Artikel als **RAG-Korpus** an `VR-P25`/v2-P4 registrierbar (Embedding-Quelle)~~ → **entfällt ([[AD-26]]); optional später als MCP-Resource ([[VR-MCP]])**
|
||||
- [ ] ~~Help-Artikel als **RAG-Korpus** an alten v2-P4-KI-Scope registrierbar (Embedding-Quelle)~~ → **entfällt ([[AD-26]]); optional später als MCP-Resource ([[VR-MCP]])**
|
||||
|
||||
## Technische Bausteine
|
||||
- **Help-Center (file-basiert, keine eigene .prisma):** Markdown + Frontmatter im Repo; **Build-Time-Index** (Volltext/Kategorien/Sitemap) mit Build-Fail bei kaputten `related_slug`-Referenzen. Öffentliche Routen vor der Auth-Middleware + **IP-Rate-Limiting**.
|
||||
|
||||
@@ -12,18 +12,31 @@
|
||||
KI→MCP-Pivot: keine HiveMind/RAG-UI. HiveGrid wird MCP-Server, an den externe KI-Clients andocken. Dieses Screen-Ticket
|
||||
liefert die **Verwaltungs-UI** dafür. Ersetzt [[VD-P25]] (zurückgestellt).
|
||||
|
||||
## Host-/Connector-Contract
|
||||
|
||||
- Connector-URL in der UI ist **`https://mcp.hivegrid.de`** (staging: `https://staging-mcp.hivegrid.de`).
|
||||
- MCP ist ein eigener Service/Container `hivegrid-mcp`, nicht Teil von `app.hivegrid.de` oder `api.hivegrid.de`.
|
||||
- OAuth-/Scope-Verwaltung nutzt die Public-API-Key-/Scope-Mechanik aus `VR-P22b` als Backend-Grundlage, aber der primäre
|
||||
Nutzerflow ist **OAuth Connect** statt API-Key-Copy. Die UI muss klar zwischen API-Verbindungen (`api.hivegrid.de`) und
|
||||
MCP-Verbindungen (`mcp.hivegrid.de`) unterscheiden.
|
||||
|
||||
## Benötigte Screens (A6 Settings-Archetyp)
|
||||
- **MCP-Verbindungen / Settings:**
|
||||
- **API-Key-Flow:** generieren → **einmalig** anzeigen → rotieren → widerrufen; **Scope-Auswahl** (read/write je
|
||||
Domäne: Leads/Kontakte/Projekte/Pipeline/Aufgaben)
|
||||
- **OAuth-Connect-Flow:** Client auswählen (Claude/ChatGPT/Cursor/VS Code/manuell) → Berechtigungen wählen →
|
||||
HiveGrid-Consent → erfolgreich verbunden; API-Key-Copy nur als Advanced-/Fallback-Modus
|
||||
- **Scope-Auswahl:** Presets „Nur lesen", „Lesen + schreiben", „Erweitert" (read/write je Domäne:
|
||||
Leads/Kontakte/Projekte/Pipeline/Aufgaben)
|
||||
- **Aktive Verbindungen:** Liste (Client/Bezeichnung, vergebene Scopes, letzte Nutzung), einzeln trennbar
|
||||
- **Setup-Anleitung:** Connector-URL + Key für Claude Desktop/Cursor (Copy-Buttons), Klartext-Schritte
|
||||
- **Setup-Anleitung:** Connector-URL `https://mcp.hivegrid.de`, OAuth-fähige Client-Schritte, Copy-Buttons nur für
|
||||
Clients ohne automatische Discovery/Connect-Unterstützung
|
||||
- **MCP-Audit:** Verlauf der Tool-Aufrufe (wer/welcher Client, welches Tool, wann, Read/Write) — Lesezugriff auf den
|
||||
M001-Audit-Trail, gefiltert auf MCP-Actor
|
||||
- **Hinweis zur Reihenfolge:** Screens finalisieren erst nach funktionalem OAuth-Proof aus [[VR-MCP]]; bis dahin ist dieser
|
||||
Screen-Scope ein Design-Zielbild.
|
||||
|
||||
## Definition of Done
|
||||
- [ ] Connection-Settings-Screen (Subframe-Pflicht, A6) — Sidebar-Eintrag + Permission-Gate
|
||||
- [ ] API-Key-Flow (Generieren → einmalig anzeigen → Rotieren → Widerrufen) + Scope-Auswahl
|
||||
- [ ] OAuth-Connect-Flow (Client-Auswahl → Consent → Success/Error) + Scope-Auswahl; API-Key-Fallback als Advanced-Modus
|
||||
- [ ] Aktive-Verbindungen-Liste + MCP-Audit-Ansicht
|
||||
- [ ] Setup-Anleitung + Empty-State/Loading-State mit Klartext; i18n-Keys für alle Texte
|
||||
|
||||
|
||||
@@ -19,17 +19,20 @@
|
||||
## Was wir bauen
|
||||
Die **Verwaltungs-Oberfläche der Public-API**: Tenant-API-Keys (Scopes, Rate-Limit, Tarif-Gate), eingehende Lead-Webhooks (Payload-Mapping + Auto-Match), ausgehende signierte WebhookSubscriptions (Delivery-Log, Replay), API-Request-/Usage-Logs sowie die auto-generierte OpenAPI/Swagger-Doku. Secrets folgen dem **Copy-once-Muster** (einmalig sichtbar). Read-only-REST + Webhooks — bewusst kein Voll-CRUD/GraphQL/OAuth.
|
||||
|
||||
**Host-Contract:** Public API läuft nur auf `api.hivegrid.de` (staging: `staging-api.hivegrid.de`) mit `/v1/...`.
|
||||
Keine Public-API-Routen unter `app.hivegrid.de/api`.
|
||||
|
||||
## Benötigte Screens
|
||||
| Screen [Route] | Kern-Inhalt | Archetyp |
|
||||
|---|---|---|
|
||||
| API-Key-Verwaltung [`/admin/api-keys`] | Key-Liste (Name, Scopes, letzte Nutzung, Status, Tarif-Gate); Key erstellen (Scope-Auswahl, Secret einmal sichtbar); Rotieren/Widerrufen | A2 + A5 (Erweiterung v1) |
|
||||
| Incoming-Webhook-Verwaltung [`/admin/api-keys/incoming-webhooks`] | Slug-Endpoints, Auth-Modus (API-Key/HMAC/URL-Token), Payload-Mapping, Auto-Match-Regeln; Ingestion-Log (Eingang/Match/Fehler) | A2 + A3 |
|
||||
| Incoming-Webhook-Verwaltung [`/admin/api-keys/incoming-webhooks`] | Slug-Endpoints auf `api.hivegrid.de/v1/webhooks/...`, Auth-Modus (API-Key/HMAC/URL-Token), Payload-Mapping, Auto-Match-Regeln; Ingestion-Log (Eingang/Match/Fehler) | A2 + A3 |
|
||||
| Outgoing-Subscription-Liste [`/admin/webhooks`] | Ziel-URL, abonnierte Event-Typen, Status (aktiv/auto-disabled), letzte Zustellung, Fehlerzähler | A2 |
|
||||
| Outgoing-Subscription-Detail [`/admin/webhooks/:id`] | Secret (einmal sichtbar), Delivery-Stats, Delivery-Log mit Retry-Status, Replay/Test-senden, Aktivieren/Pausieren | A3 |
|
||||
| API-Request-Logs + Usage [`/admin/api-keys/usage`] | Request-Log (Endpoint, Key, Status, Latenz, Rate-Limit-Treffer); Usage-Aggregat (Calls/h pro Key + Tenant, Quota-Auslastung) | A2 |
|
||||
| OpenAPI/Swagger-UI [`/api/v1/openapi` · Swagger] | Auto-generierte OpenAPI-3.1-Doku + interaktiver Try-it-out (entwickler-gerichtet, evtl. eingebettete Drittanbieter-UI) | A6/extern |
|
||||
| OpenAPI/Swagger-UI [`api.hivegrid.de/v1/openapi.json` · Swagger auf API-Host] | Auto-generierte OpenAPI-3.1-Doku + interaktiver Try-it-out (entwickler-gerichtet, evtl. eingebettete Drittanbieter-UI) | A6/extern |
|
||||
|
||||
*(Die REST-Endpoints `/api/v1/contacts|companies|deals|projects|tasks|leads` sind serverseitig — kein eigener Screen außer Swagger-UI.)*
|
||||
*(Die REST-Endpoints `api.hivegrid.de/v1/contacts|companies|deals|projects|tasks|leads` sind serverseitig — kein eigener Screen außer Swagger-UI.)*
|
||||
|
||||
## Features (muss abgedeckt sein)
|
||||
- [ ] API-Key-Verwaltung als Erweiterung der v1-`ApiKey`-Fläche (Scope-Auswahl, Secret Copy-once, Rotieren/Widerrufen)
|
||||
|
||||
@@ -17,20 +17,20 @@
|
||||
- **Subframe:** Pflicht je Route (A2 Liste, A3 Detail, A5 Modal, A6 Settings)
|
||||
|
||||
## Was wir bauen
|
||||
Die **Email-Inbox-Oberfläche**: User verbinden ihr Gmail-/Outlook-Postfach per OAuth, das CRM spiegelt Threads **bidirektional**, matcht **auto** auf Contact/Lead/Deal/Project und zeigt sie im Activity-Stream. User lesen Threads mit **sicherem HTML-Render**, antworten/leiten weiter über die **eigene Mailbox**. Permission-getrennt über `email.read_own` vs. `email.read_all`. Nur OAuth-Sync/Inbox/Threading-Teil — die v1-Sende-Domain (DKIM/SPF/DMARC) wird NICHT neu gebaut.
|
||||
Die **Email-Inbox-Oberfläche**: User verbinden ihr Gmail-/Outlook-Postfach per OAuth, das CRM spiegelt Threads **bidirektional**, matcht **auto** auf Contact/Lead/Projekt und zeigt sie im Activity-Stream. User lesen Threads mit **sicherem HTML-Render**, antworten/leiten weiter über die **eigene Mailbox**. Permission-getrennt über `email.read_own` vs. `email.read_all`. Nur OAuth-Sync/Inbox/Threading-Teil — die v1-Sende-Domain (DKIM/SPF/DMARC) wird NICHT neu gebaut.
|
||||
|
||||
## Benötigte Screens
|
||||
| Screen [Route] | Kern-Inhalt | Archetyp |
|
||||
|---|---|---|
|
||||
| Mailbox-Connect-Settings [`/settings/integrations/email`] | Postfach verbinden (Gmail/Microsoft OAuth), Sync-Status (Initial-Sync-Progress, letzter Sync, Fehler), Reconnect/Token-Refresh, Trennen/Revoke | A6 |
|
||||
| Inbox-Liste [`/emails`] | Mail-Liste (Absender, Betreff, Snippet, Datum, Verknüpfung-Badge, gelesen/ungelesen); Filter (Mailbox/verknüpft/unverknüpft/Datum); Volltext-Suche; Bulk-Actions | A2 |
|
||||
| Mail-Detail [`/emails/:id`] | Thread-Ansicht (chronologisch), sicherer HTML-Render (externe Bilder blockiert/optional laden), Anhänge (→ Files), Verknüpfungs-Editor (Contact/Lead/Deal/Project, manueller Override), Reply/Forward | A3 |
|
||||
| Mail-Detail [`/emails/:id`] | Thread-Ansicht (chronologisch), sicherer HTML-Render (externe Bilder blockiert/optional laden), Anhänge (→ Files), Verknüpfungs-Editor (Contact/Lead/Projekt, manueller Override), Reply/Forward | A3 |
|
||||
| Outbound-Compose [`/emails/new`] | Neue Mail / Reply / Forward über User-Mailbox, Empfänger, Betreff, Body, Anhänge, Vorlagen-Auswahl | A5/A3 |
|
||||
|
||||
## Features (muss abgedeckt sein)
|
||||
- [ ] OAuth-Connect Gmail (Pub/Sub-Watch) + Microsoft (Graph-Subscription); Token-Refresh + Revoke; Re-Auth-Hinweis
|
||||
- [ ] Push-Sync (kein Primär-Polling); Initial-Sync 90 Tage resumebar mit Progress-Anzeige
|
||||
- [ ] Auto-Match (From→Contact/Lead, Subject-Pattern `[Deal #123]`, 1-offener-Deal-Heuristik); manueller Override sticht
|
||||
- [ ] Auto-Match (From→Contact/Lead, Subject-Pattern `[Projekt #123]`, 1-offenes-Projekt-Heuristik); manueller Override sticht
|
||||
- [ ] Inbox-Liste mit Filter/Suche/Bulk; Detail mit Thread + sicherem HTML-Render (CSP, externe Bilder blockiert)
|
||||
- [ ] Reply/Forward via User-Mailbox + Vorlagen (M098)
|
||||
- [ ] Anhänge → v1-Files; Mails erscheinen im Activity-Stream
|
||||
@@ -41,7 +41,7 @@ Provider-Connect-Buttons (Gmail/Microsoft mit Logo); Sync-Status-Panel (Progress
|
||||
|
||||
## Quellen (granular)
|
||||
- `designer-briefs/P23-postfach-sync.md` (vollständiger Brief — diese Doc ist sein Ticket-Destillat)
|
||||
- `ENTITY-MODEL.md` → **Domäne 8: Kommunikation (Email M09/M10)** + Activity-Stream/Contact-Deal-Project-FKs
|
||||
- `ENTITY-MODEL.md` → **Domäne 8: Kommunikation (Email M09/M10)** + Activity-Stream/Contact/Lead/Projekt-FKs
|
||||
- `ROADMAP-V2.md` §v2-P2 (Screens/Features = Hauptquelle) · `ROADMAP.md` §Phase 23 · `_bmad-output/specs/M09-email-inbox.md`
|
||||
- Plane-Snapshot: ersetzt Teil von `VD-1`; bedient `VA-P23` (v2-W1, 13.–17.07.)
|
||||
|
||||
|
||||
@@ -1,54 +1,74 @@
|
||||
# VD-P24 · Screens P24 — Abo-Baukasten-UI + Onboarding-Wizard
|
||||
|
||||
> ⚠️ **KI→MCP-Pivot ([[AD-26]]):** Der **KI-Coach-Slot entfällt** (war weiche Kopplung an das zurückgestellte VR-P25/VD-P25; v2-P4 ist jetzt der MCP-Server, [[VR-MCP]]/[[VD-MCP]]). Wizard- und Billing-Flächen bleiben unverändert; KI-Coach-Stellen unten durchgestrichen.
|
||||
> ⚠️ **Billing-Recut 2026-07-04 ([[AD-27]]):** Self-Service-Billing-Screens muessen auf
|
||||
> **Lago + Mollie + HiveGrid-Entitlements** neu geschnitten werden. Payment-Checkout-/Customer-Portal-Flächen werden
|
||||
> nicht wiederverwendet.
|
||||
|
||||
> ⚠️ **KI→MCP-Pivot ([[AD-26]]):** Der KI-Coach-Slot entfällt. Wizard- und Billing-Flächen bleiben, aber ohne
|
||||
> KI-Credits-/LLM-Gateway-Bezug.
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Typ** | Screen (Design) |
|
||||
| **Owner** | David |
|
||||
| **Phase** | P24 — Self-Service-Billing & Onboarding-Wizard (v2-P3) · bedient `VA-P24a`/`VA-P24b` |
|
||||
| **Cycle/Fenster** | v2-W1 — Public-API/Postfach/Abo/KI-Start · Abo-UI 13.–17., Wizard 18.–20.07. → fällig 2026-07-20 |
|
||||
| **Status** | geplant (NEU — Phasen-Ticket) |
|
||||
| **Cycle/Fenster** | v2-W1 — Public-API/Postfach/Abo/KI-Start · fällig 2026-07-20 |
|
||||
| **Status** | geplant / nach Billing-Recut neu bewerten |
|
||||
|
||||
> ♻️ **Löst Sammel-Ticket auf:** Dieses Phasen-Ticket ersetzt — zusammen mit `VD-P23` — das alte Sammel-Ticket **`VD-1`** („Abo-Baukasten-UI + Wizard + Postfach-Inbox"). VD-P24 = der Abo-Baukasten-/Onboarding-Wizard-Anteil.
|
||||
> ♻️ **Löst Sammel-Ticket auf:** Dieses Phasen-Ticket ersetzt zusammen mit `VD-P23` das alte Sammel-Ticket `VD-1`.
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** D0-Baseline (`D-D0a` App-Shell, `D-D0b` Archetypen A2/A3/A5/A6 + Vollbild-Flow) — Wizard und Plan-Wechsel komponieren aus den D0-Archetypen; Stripe-Checkout-Flächen aus v1 wiederverwenden
|
||||
- **Bedient (Dev):** `VA-P24a` (Self-Service-Abo-Baukasten-UI, M28-Delta, 13.–15.07.), `VA-P24b` (Onboarding-Wizard-UI, M157, 18.–20.07.)
|
||||
- **Läuft parallel zu:** `VD-P22`, `VD-P23` — gleiche v2-W1
|
||||
- **Subframe:** Pflicht je Route (A2, A3, A5, A6 + Vollbild-Flow für den Wizard)
|
||||
|
||||
- **Blocked by:** D0-Baseline (`D-D0a`, `D-D0b`) und fuer Self-Service-Billing `BILL-02` bis `BILL-07`
|
||||
- **Bedient (Dev):** `VA-P24a` (Self-Service-Abo-Baukasten-UI) und `VA-P24b` (Onboarding-Wizard-UI)
|
||||
- **Läuft parallel zu:** `VD-P22`, `VD-P23`, sofern Billing-Screens nicht vor `BILL-*` finalisiert werden
|
||||
- **Subframe:** Pflicht je Route (A2, A3, A5, A6 + Vollbild-Flow fuer den Wizard)
|
||||
|
||||
## Was wir bauen
|
||||
Zwei Flächen: (1) **Self-Service-Billing** — Tenants buchen/wechseln Pläne über **Web-Checkout** (v1-Stripe wiederverwenden), kaufen Add-Ons, sehen Usage/Quota. **PWA-only (AD-17)** → keine App-Store-Billing-Auflage, Plan-Wechsel direkt im Web. (2) **Onboarding-Wizard** — resumebarer, branchen-getriebener 10-Step-Vollbild-Flow (State-Machine), der das SHK-Branchen-Template deklarativ aus YAML seedet, plus Erste-Schritte-Checkliste (Detection-Rules) und Demo-Daten-Bulk-Löschung. ~~KI-Coach-Andockpunkt (von P25 rückwirkend befüllt).~~ → **KI-Coach entfällt ([[AD-26]]).**
|
||||
|
||||
Zwei Flächen:
|
||||
|
||||
1. **Self-Service-Billing:** Tenants sehen Plan/Seats, starten Plan-/Seat-Aenderungen ueber einen Web-Flow, zahlen ueber
|
||||
Mollie und sehen Return-/Payment-/Invoice-Status. Lago bleibt Billing-Engine, HiveGrid zeigt Entitlements.
|
||||
2. **Onboarding-Wizard:** resumebarer, branchen-getriebener 10-Step-Vollbild-Flow, der das SHK-Branchen-Template
|
||||
deklarativ seedet, plus Erste-Schritte-Checkliste und Demo-Daten-Bulk-Löschung.
|
||||
|
||||
## Benötigte Screens
|
||||
|
||||
| Screen [Route] | Kern-Inhalt | Archetyp |
|
||||
|---|---|---|
|
||||
| Onboarding-Wizard [`/onboarding/setup/step/:n`] | 10-Step-Vollbild-Flow (Branchen-Wahl, Pipelines/Rollen/Felder, Forms, Demo-Daten, Team-Einladung etc.); Step-Validierung; Rückwärts-Block nach irreversiblen Actions; resumebar | Vollbild-Flow |
|
||||
| Erste-Schritte-Checkliste [`/onboarding/checklist`] | Checklisten-Widget (Detection-Rules: erledigt/offen) + Detail-Sicht mit Deep-Links zu den Aufgaben | A2/Widget |
|
||||
| Demo-Daten-Verwaltung [`/admin/onboarding/demo-data`] | Übersicht geseedete Demo-Daten + Bulk-Löschung (Bestätigung) | A6 |
|
||||
| Self-Service-Plan-Wechsel [`/admin/subscription`] | Aktueller Plan, verfügbare Pläne (Web-Checkout), Plan-Wechsel/Upgrade/Downgrade, Zahlungsmethoden-Pflicht, Checkout-Return | A6 + Web-Checkout |
|
||||
| Add-On-Kauf-Flächen [`/admin/subscription` · `/admin/usage`] | Add-On-Katalog (~~AI-Credits~~ (entfällt [[AD-26]]), Seats), Kauf via Web-Checkout, Usage-/Quota-Anzeige | A6 |
|
||||
| Onboarding-Wizard [`/onboarding/setup/step/:n`] | 10-Step-Vollbild-Flow, Step-Validierung, Rückwärts-Block nach irreversiblen Actions, resumebar | Vollbild-Flow |
|
||||
| Erste-Schritte-Checkliste [`/onboarding/checklist`] | Checklisten-Widget + Detail-Sicht mit Deep-Links zu Aufgaben | A2/Widget |
|
||||
| Demo-Daten-Verwaltung [`/admin/onboarding/demo-data`] | Übersicht geseedete Demo-Daten + Bulk-Löschung | A6 |
|
||||
| Self-Service-Plan-/Seat-Wechsel [`/admin/subscription`] | Aktueller Plan, Seats, verfügbare Pläne, Preis-Vorschau, Mollie-Zahlungsstart, Return-/Payment-Status | A6 + Web-Flow |
|
||||
| Billing-Status [`/admin/billing`] | Lago-Invoices, Mollie-Payments, Fehlzahlung/Expired/Refund-Klartext | A6 |
|
||||
|
||||
## Features (muss abgedeckt sein)
|
||||
- [ ] Self-Service-Trial ohne Vertriebs-Freigabe (`requires_manual_activation=false`) mit Zahlungsmethoden-Pflicht
|
||||
- [ ] Plan-Wechsel + Add-On-Käufe über Web-Checkout (PWA-only → kein App-Store, keine Store-Billing-Auflage)
|
||||
- [ ] Onboarding-Wizard resumebar nach Signup, Step-Validierung, Block der Rückwärts-Navigation nach irreversiblen Actions
|
||||
- [ ] SHK-Branchen-Template (Pipelines/Rollen/Custom-Felder/Forms/Demo/Checkliste) deklarativ aus YAML geseedet; weitere Branchen „coming soon"
|
||||
- [ ] Erste-Schritte-Checkliste mit Detection-Rules + Demo-Daten-Bulk-Löschung
|
||||
- [ ] ~~KI-Walkthrough-Coach-Andockpunkt (Slot — von P25 rückwirkend eingehängt, kein harter Forward-Dep)~~ → **entfällt ([[AD-26]])**
|
||||
- [ ] Wiederverwendung v1: Stripe-Checkout + Webhook-Handler, SubscriptionFeature/ProductFeature (Feature-Gate), Read-Only-Middleware, TenantUserInvitation
|
||||
|
||||
- [ ] Plan-/Seat-Wechsel ueber Lago/Mollie-Web-Flow, nicht Legacy-Provider.
|
||||
- [ ] Zahlungspflicht/Payment-Status klar sichtbar, inklusive Return- und Fehlerzustand.
|
||||
- [ ] Keine Usage-/AI-Credits-/Add-on-Metering-Fläche.
|
||||
- [ ] Onboarding-Wizard resumebar nach Signup, Step-Validierung, Block der Rückwärts-Navigation nach irreversiblen Actions.
|
||||
- [ ] SHK-Branchen-Template aus YAML geseedet; weitere Branchen „coming soon".
|
||||
- [ ] Erste-Schritte-Checkliste mit Detection-Rules + Demo-Daten-Bulk-Löschung.
|
||||
- [ ] Wiederverwendung aus v1 nur fuer Entitlements, Read-only/Frozen-State, TenantUserInvitation und Onboarding-Grundlagen.
|
||||
|
||||
## UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)
|
||||
Step-Progress-Indikator (10 Steps, Vollbild); Step-Inhalts-Container mit Validierungs-Feedback; „Zurück gesperrt"-Hinweis nach irreversiblen Actions; Branchen-Auswahl-Karten (SHK aktiv, andere „coming soon"-disabled); Plan-Vergleichs-Karten/Tabelle (Features pro Plan, aktueller Plan markiert); Web-Checkout-Trigger-Button + Checkout-Return-Status; Zahlungsmethoden-Pflicht-Hinweis; Add-On-Katalog-Karten mit Preis + Kauf-Button; Usage-/Quota-Auslastungs-Anzeige (Balken); Erste-Schritte-Checklisten-Widget (abhakbare Items mit Deep-Link); Demo-Daten-Lösch-Bestätigung (mit Folgen-Hinweis); Resume-Banner („Onboarding fortsetzen"); ~~KI-Coach-Slot/Platzhalter (von P25 befüllt)~~ (entfällt [[AD-26]]); Empty-/Loading-/Permission-Denied-States (Klartext).
|
||||
|
||||
Step-Progress-Indikator; Step-Inhalts-Container mit Validierungs-Feedback; „Zurück gesperrt"-Hinweis; Branchen-
|
||||
Auswahl-Karten; Plan-Vergleichs-Karten/Tabelle; Seat-Stepper; Preis-Vorschau; Mollie-Zahlungsstart-Button; Return-/
|
||||
Payment-Status; Billing-Status-Badges; Usage-/Quota-Auslastung nur fuer nicht abrechenbare Limits; Erste-Schritte-
|
||||
Checklisten-Widget; Demo-Daten-Lösch-Bestätigung; Resume-Banner; Empty-/Loading-/Permission-Denied-States.
|
||||
|
||||
## Quellen (granular)
|
||||
- `designer-briefs/P24-self-service-billing-wizard.md` (vollständiger Brief — diese Doc ist sein Ticket-Destillat)
|
||||
- `ENTITY-MODEL.md` → **Domäne 12: Billing & Abo-Baukasten (M28, Recut-Modell)** + **Domäne 13: Onboarding (M29)**
|
||||
- `ROADMAP-V2.md` §v2-P3 (Screens/Features = Hauptquelle) · `ROADMAP.md` §Phase 24 · `_bmad-output/specs/M28-subscriptions-billing.md` (Block P) · `_bmad-output/specs/M29-onboarding.md`
|
||||
- Plane-Snapshot: ersetzt Teil von `VD-1`; bedient `VA-P24a`/`VA-P24b` (v2-W1, 13.–20.07.)
|
||||
|
||||
- `docs/ARCHITECTURE-DECISIONS.md` → `AD-27`, `AD-26`
|
||||
- `BILL-README.md`, `BILL-02` bis `BILL-07`
|
||||
- `designer-briefs/P24-self-service-billing-wizard.md` muss nach AD-27 aktualisiert werden
|
||||
- `ROADMAP-V2.md` §v2-P3 · `ENTITY-MODEL.md` Domäne 12/13 nach AD-27 recutten
|
||||
|
||||
## Davids Delta (David füllt aus)
|
||||
|
||||
- [ ] Überschriebene/geänderte Spec-Punkte:
|
||||
- [ ] Neue UI/UX-Entscheidungen:
|
||||
- [ ] Subframe-Screen-Link(s):
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# VD-P29 · Screens P29 — Help-Center (Public-Content-Site) & Help-Desk
|
||||
|
||||
> ⚠️ **KI→MCP-Pivot ([[AD-26]]):** Der **RAG-Korpus-Andock entfällt** (VR-P25/VD-P25 zurückgestellt; kein RAG/Embedding — HiveGrid wird MCP-Server, [[VR-MCP]]/[[VD-MCP]]). Das **Help-Center bleibt** unverändert; Help-Artikel optional später als MCP-Resource. RAG-Stellen unten durchgestrichen.
|
||||
> ⚠️ **KI→MCP-Pivot ([[AD-26]]):** Der **RAG-Korpus-Andock entfällt** (alter VR-P25/VD-P25-Scope zurückgestellt; kein RAG/Embedding — HiveGrid wird MCP-Server, [[VR-MCP]]/[[VD-MCP]]). Das **Help-Center bleibt** unverändert; Help-Artikel optional später als MCP-Resource. RAG-Stellen unten durchgestrichen.
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
@@ -16,7 +16,7 @@
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** D0-Baseline (`D-D0a` App-Shell + Public-Layout-Token, `D-D0b` Archetypen A2/A3/A5) — öffentliche Help-Routen liegen **vor der Auth-Middleware**, ohne Tenant-Context; Admin-Flächen unter `admin.hivegrid.de`
|
||||
- **Bedient (Dev):** `VA-P29` (Help-Center + Help-Desk, M172–175) — v2-W3 (28.–30.07.)
|
||||
- ~~**Retro-Dep:** Help-Artikel werden rückwirkend **RAG-Korpus für `VD-P25`/v2-P4** (Embedding-Quelle)~~ → **entfällt ([[AD-26]]); optional als MCP-Resource ([[VD-MCP]])**
|
||||
- ~~**Retro-Dep:** Help-Artikel werden rückwirkend **RAG-Korpus für alten VD-P25/v2-P4-Scope** (Embedding-Quelle)~~ → **entfällt ([[AD-26]]); optional als MCP-Resource ([[VD-MCP]])**
|
||||
- **Läuft parallel zu:** `VD-P28`, `VD-P30`, `VD-P31` — v2-W3
|
||||
- **Subframe:** Pflicht je Route (öffentliche A-Public/A2-Public/A3-Public + In-App-Widget A5 + interne Admin A2/A3)
|
||||
|
||||
@@ -40,7 +40,7 @@ Ein **öffentliches, file-basiertes Help-Center** mit SEO-Routen (`/help/{lang}/
|
||||
- [ ] Deep-Link Route→Artikel (Hilfe-Icon pro App-Route, Fallback Help-Home)
|
||||
- [ ] Feedback-Widget überall → `Feedback` mit Auto-Kontext (tenant/user/route/browser/app-version), Screenshot-Option, Rate-Limit 10/h
|
||||
- [ ] Plattform-Admin: Feedback-Liste + Detail (Status-Lifecycle/Assignee/Notes/Attachments) mit Audit
|
||||
- [ ] ~~Help-Artikel als RAG-Korpus an `VD-P25`/v2-P4 registrierbar (Embedding-Quelle)~~ → **entfällt ([[AD-26]]); optional als MCP-Resource ([[VD-MCP]])**
|
||||
- [ ] ~~Help-Artikel als RAG-Korpus an alten VD-P25/v2-P4-Scope registrierbar (Embedding-Quelle)~~ → **entfällt ([[AD-26]]); optional als MCP-Resource ([[VD-MCP]])**
|
||||
- [ ] **Externer Polish** der öffentlichen Help-Routen (SEO, Responsive, Hell/Dunkel)
|
||||
|
||||
## UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)
|
||||
|
||||
@@ -6,9 +6,9 @@
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | Phase 32 (v2-P5) — KWP-Integration (Vorlauf) |
|
||||
| **Cycle/Fenster** | v2-W2 — KWP/Portal/Mobile-Start · fällig 2026-07-20 |
|
||||
| **Status** | geplant · 🟠 **block-2 (Partner-API offen, agil)** |
|
||||
| **Status** | in Arbeit · 🟢 **Zugang aktiv seit 2026-06-25** (~3–4 Wochen früher als geplant) |
|
||||
|
||||
> 🟠 **block-2 — Partner-API offen, agil:** Dies ist der Vorlauf-Task, der den block-2-Zustand der gesamten KWP-Phase **auflöst**. KWP-API-Zugang lt. Hersteller ~**19./20.07.** — der härteste Kalender-Anker des v2-Sprints (KWP = das v2-Hauptverkaufsargument). Ohne diesen Task keine belastbare Recut-Detailplanung.
|
||||
> 🟢 **Update 2026-06-25 — Zugang eingetroffen (früher als ~19./20.07.):** KWP hat den OAuth2-Zugang für den Mandanten `geerkens2` freigeschalten. Der block-2-Zustand der KWP-Phase ist damit faktisch **aufgelöst** — VR-P32a/b/c bleiben aber `blocked-by R-P5` (Apps-Engine M33a). Stand der 7 Vertrags-Fragen siehe Umsetzungs-Notiz unten. **KWP bleibt v2-Scope** (kein v1-Vorziehen — Big-Bang-Launch v1 zuerst, AD-19); der frühe Zugang wird genutzt, um die Vertrags-Fragen vorab gegen die echte API zu klären (Spike), nicht um den v1-Sprint aufzureißen.
|
||||
|
||||
## Was zu tun
|
||||
KWP-API-Zugang aktivieren und die **Recut-Detailplanung pro Milestone gegen die echte API-Doku** durchführen — nicht gegen Annahmen. Konkret die 7 offenen Vertrags-Fragen aus dem bindenden Recut klären und je Milestone (M089–M095) entscheiden:
|
||||
@@ -41,3 +41,82 @@ Ohne aktiven Zugang + Detailplanung gegen die echte Doku ist der KWP-Bau (VR-P32
|
||||
- `ROADMAP-V2.md` → §v2-P5 + §Offene Vorlauf-Tasks #1 (KWP-API-Vertrag ~20.07.)
|
||||
- `ROADMAP.md` → Phase 32 · `PHASE-SOURCES.md` → Phase 32 (Callback-URL gemeldet, bnWin.net-8.1-N3, Andockpunkte v1)
|
||||
- abhängig-für: `ticket-docs/VR-P32a.md`/`VR-P32b.md`/`VR-P32c.md`
|
||||
|
||||
## Umsetzung (2026-06-25, Owner Raffael) — Zugang aktiv, Vertrags-Fragen teil-beantwortet
|
||||
|
||||
**Geliefert von KWP (Mandant `geerkens2`):** OAuth2-Zugang via **Keycloak-OIDC, Realm `kwp-federated`**
|
||||
(`id.kwp-online.de`). Confidential Client (`offline_access`), ClientId-Schema `_extern-<tenant>`, Tenant-Kürzel
|
||||
als URL-Param `tenant=geerkens2` am Authorization-Endpoint. **Secret NICHT in Repo/Doc** — gehört in
|
||||
Coolify-Secret-Store bzw. später per-Tenant-DEK in `DataConnection.config` (AD-8); da es per Mail/Chat lief →
|
||||
bei KWP **Rotation vor Prod** einplanen.
|
||||
|
||||
**OIDC-Discovery verifiziert** (`…/realms/kwp-federated/.well-known/openid-configuration`):
|
||||
Auth `…/protocol/openid-connect/auth` · Token `…/token` · Userinfo · JWKS `…/certs` · Logout · Introspection ·
|
||||
Revocation. `grant_types`: authorization_code, **refresh_token**, client_credentials, device_code, token-exchange u.a.
|
||||
`code_challenge_methods`: **plain, S256** (PKCE ✓). Token-Auth: client_secret_basic/-post, private_key_jwt, mTLS.
|
||||
`scopes_supported` global nur `openid, email` → die fachlichen Scopes sind **Client-zugewiesene Keycloak-Scopes**
|
||||
(die aus der Mail sind maßgeblich für unseren Token-Request).
|
||||
|
||||
**Resource-API gefunden** (vom Partner geliefert): Swagger-UI
|
||||
`https://kwp3.app02.kwp-online.de/relay/kwp3/pwa/swagger/index.html`, OpenAPI-JSON unter
|
||||
`…/swagger/v1/swagger.json`. Title „KWP Api" v1, basePath **`/relay/kwp3/pwa`**, Security = OAuth2.
|
||||
**Charakter: RPC-artige Action-API** (nicht REST-CRUD): `/api/Adresse/LoadAdressKomplett|Add|Save|Search|…`,
|
||||
`/api/Aktivitaet/AddAktivitaet|SaveInfoEintrag|…`, `/api/Abteilung/…`. Description: „respecting permissions and
|
||||
user context" → User-gebunden (deshalb Auth-Code-Flow, nicht reines client_credentials).
|
||||
|
||||
**Stand der 7 Vertrags-Fragen:**
|
||||
1. **Auth-Methode → ✅ geklärt:** OAuth2/OIDC (Keycloak), Auth-Code + PKCE (S256), Confidential Client +
|
||||
`offline_access`/Refresh → `DataConnection.type='oauth2'` (NICHT `rest-api`). Pro HiveGrid-Tenant eigene
|
||||
ClientId/Secret/`tenant`-Kürzel in DEK-`config`.
|
||||
2. **Endpoints/Capabilities → 🟠 teilweise:** Adresse (Kontakte/Ansprechpartner/Custom-Felder/Geo/Anrufer-Info),
|
||||
Aktivität, Abteilung bestätigt. **`Vorgang` (=Projekt-Kern!), `Termin`, `Archiv` noch zu erfassen** — in der
|
||||
`pwa`-Spec nicht im (gekürzten) WebFetch-Ausschnitt sichtbar; evtl. eigene Relay-Module. → **Spike** (echter
|
||||
HTTP-Client, volle JSON laden).
|
||||
3. **Webhook-Support → 🟠 offen:** in der abgerufenen `pwa`-Spec keine `webhooks`/`callbacks` gesehen (Sicht war
|
||||
gekürzt) → Arbeitshypothese **Pull-Modell**; final im Spike/bei KWP bestätigen. Steuert M094 (Trigger- vs.
|
||||
Cron-Pull) + M092.
|
||||
4. **Rate-Limits → ❓ offen** (nicht in Discovery/Swagger-Übersicht) → bei KWP erfragen; steuert Replay-Rate M091.
|
||||
5. **Versionierung → 🟢 teilweise:** API `v1`, basePath `/relay/kwp3/pwa`. Changelog-Politik bei KWP erfragen.
|
||||
6. **Dokumenten-API → 🟠 offen:** Scope `archiv-extern` existiert, Endpoints noch zu erfassen (Spike) → M095.
|
||||
7. **Konflikt-Felder → ❓ offen:** Response-Schema je Entität auf `version_hash`/`last_modified` prüfen (Spike) → M093/M094.
|
||||
|
||||
**NEU — offene Frage (Scope-Mapping):** Mail-Scopes sind `adresse-extern archiv-extern termin-extern
|
||||
vorgang-extern aktivitaet-extern offline_access`; die Swagger-Security nennt interne Scope-Namen
|
||||
(`adressverwaltung`, `aktivitaetenverwaltung`, `projektampel`, `wartungswesen`, `mobmont`, …). Klären, ob die
|
||||
`*-extern`-Scopes intern gemappt werden und alle benötigten Endpoints abdecken.
|
||||
|
||||
**Noch zu tun (Rest dieses Tickets):** Spike gegen die echte API (Token holen → 1 Resource-Call →
|
||||
`Vorgang`/`Termin`/`Archiv`-Endpoints + Konflikt-Felder + Webhook/Rate-Limit erfassen); Staging-Redirect-URI bei
|
||||
KWP registrieren; AVV/Subprozessor-Vermerk an VR-P31/M166. **Bleibt v2** — Spike erst sinnvoll nach/mit R-P5.
|
||||
|
||||
### Rückfragen an KWP (Entwurf, 2026-06-25 — via Noah/Geerkens weiterleiten)
|
||||
|
||||
> Betreff: Rückfragen zur KWP-API-Anbindung (Mandant `geerkens2`)
|
||||
|
||||
vielen Dank für die Freischaltung des API-Zugangs. Den OAuth2-Flow (Keycloak, Realm `kwp-federated`,
|
||||
Auth-Code + PKCE) und die OpenAPI-Doku unter `…/relay/kwp3/pwa/swagger/v1/swagger.json` konnten wir bereits
|
||||
einsehen. Für die saubere Anbindung haben wir noch einige Rückfragen:
|
||||
|
||||
1. **Daten-Endpunkte/Umfang:** Die uns vorliegende `pwa`-Swagger zeigt vor allem Adresse, Aktivität und
|
||||
Abteilung. Über welche Endpunkte bzw. welche weiteren Relay-Module erreichen wir die Bereiche **Vorgang,
|
||||
Termin und Archiv** (unsere Scopes `vorgang-/termin-/archiv-extern`)? Gibt es eine vollständige/aggregierte
|
||||
OpenAPI-Spezifikation?
|
||||
2. **Scope-Mapping:** Zugewiesen sind `adresse-/archiv-/termin-/vorgang-/aktivitaet-extern` (+ `offline_access`).
|
||||
In der Swagger-Security stehen interne Scope-Namen (`adressverwaltung`, `aktivitaetenverwaltung`,
|
||||
`projektampel`, …). Werden die `*-extern`-Scopes intern darauf gemappt, und decken sie alle benötigten
|
||||
Endpunkte ab?
|
||||
3. **Synchronisation:** Gibt es **Webhooks/Push** bei Änderungen (KWP → uns), oder ist die Sync rein **Pull**?
|
||||
Falls Pull: gibt es Delta-/„geändert seit"-Parameter (Zeitstempel/Cursor)?
|
||||
4. **Konflikt-/Versionsfelder:** Liefern die Antworten je Datensatz ein Änderungsdatum bzw. eine Version
|
||||
(`last_modified`/`version`/ETag) für Delta-Sync und Konflikt-Erkennung?
|
||||
5. **Rate-Limits:** Welche Limits gelten (Requests/Minute, parallele Verbindungen)? Empfohlene Poll-Intervalle?
|
||||
6. **Token-Lebensdauer:** Gültigkeit Access-/Refresh-Token; rotieren die Refresh-Token bei Nutzung? (Relevant für
|
||||
den dauerhaften Hintergrund-Sync mit `offline_access`.)
|
||||
7. **Schreibzugriff:** Die Endpunkte enthalten Add/Save/Remove. Sind die externen Scopes lesend **und** schreibend
|
||||
nutzbar, und gibt es Einschränkungen, was ein externer Client schreiben darf?
|
||||
8. **Test-/Sandbox-Mandant:** Gibt es einen Test-/Sandbox-Tenant zum Entwickeln und für unsere Staging-Umgebung,
|
||||
statt gegen den Produktiv-Mandanten `geerkens2`?
|
||||
9. **Versionierung:** Wie wird die API versioniert (aktuell `/v1`) und wie werden Breaking Changes angekündigt?
|
||||
|
||||
Klein: Im Authorization-Beispiel stand `client_id=der-oauth-client` als Platzhalter — bestätigen Sie bitte, dass
|
||||
für uns `client_id=_extern-geerkens2` zu verwenden ist.
|
||||
@@ -6,7 +6,7 @@
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | v2-P4 — MCP (ersetzt „KI-Tiefe", [[AD-26]]) |
|
||||
| **Cycle/Fenster** | v2-W1 — Public-API/Postfach/Abo/KI-Start · Start 18.07. · fällig 2026-07-20 |
|
||||
| **Status** | geplant (NEU — KI→MCP-Pivot) |
|
||||
| **Status** | In Arbeit — MCP-Runtime + OAuth 2.1 live; **E2E-DoD erfüllt** (Claude Code als Produkt-Client per OAuth verbunden, Read+Write-Tool + Audit/Activity auf Staging verifiziert, s. Notizen 2026-07-03); Schema-Drift behoben (PR #32) und Native-Client-Origin-Fix deployed; offen: Prod-Rollout `mcp.hivegrid.de` + [[VD-MCP]]-Screens |
|
||||
|
||||
## Entscheidung / Kontext ([[AD-26]])
|
||||
KI→MCP-Pivot: HiveGrid hostet **kein** eigenes LLM/RAG mehr. Statt KI-App wird HiveGrid **KI-anschließbar** über einen
|
||||
@@ -14,13 +14,24 @@ KI→MCP-Pivot: HiveGrid hostet **kein** eigenes LLM/RAG mehr. Statt KI-App wird
|
||||
HiveGrid-Daten und führen **Aktions-Tools** aus — die Inferenz liegt beim Client. Ersetzt [[VR-P25]] (HiveMind/RAG,
|
||||
zurückgestellt). Baut auf der Public-API-Fläche ([[VR-P22a]]/[[VR-P22b]]) auf — **keine Doppelarbeit**.
|
||||
|
||||
## Host-/Runtime-Contract (verbindlich)
|
||||
|
||||
- MCP läuft ausschließlich auf **`mcp.hivegrid.de`** (staging: `staging-mcp.hivegrid.de`).
|
||||
- MCP läuft als eigener Coolify-Service/Container **`hivegrid-mcp`** mit eigener Runtime (`apps/mcp`), nicht im Web-
|
||||
oder Public-API-Container.
|
||||
- Public API bleibt auf `api.hivegrid.de`; MCP-Routen werden nicht unter `app.hivegrid.de` oder `api.hivegrid.de`
|
||||
bereitgestellt. Auth/Scopes/Rate-Limit werden aus VR-P22b wiederverwendet, aber die Host-/Runtime-Surface bleibt getrennt.
|
||||
- MCP nutzt den Host selbst als Connector-URL; es gibt keinen zusätzlichen `/mcp`-Pfad.
|
||||
|
||||
## Was zu bauen ist
|
||||
Remote MCP-Server, der die **mandanten-gescopte** HiveGrid-Daten-/Aktions-Fläche als MCP-**Tools** exponiert:
|
||||
- **Transport:** Streamable HTTP (stateless Start), eigener Service-Bereich; **SDK `@modelcontextprotocol/sdk`** (das
|
||||
Gerüst `apps/web/app/modules/mcp/` existiert bereits). Kein stdio, kein deprecated SSE.
|
||||
- **Auth Stufe 1:** **API-Key-Bearer** (aus [[VR-P22b]] — Key → Tenant + User + Scopes). 401 mit `WWW-Authenticate`
|
||||
bei Fehlschlag. **Stufe 2 (später, eigenes Ticket/CR):** OAuth 2.1 (PKCE, RFC 9728 Protected-Resource-Metadata,
|
||||
RFC 8707 Resource-Indicators) für „Connect-in-Minutes".
|
||||
- **Transport:** Streamable HTTP (stateless Start) auf `https://mcp.hivegrid.de`; **SDK `@modelcontextprotocol/sdk`**.
|
||||
Kein stdio, kein deprecated SSE.
|
||||
- **Auth v1:** **OAuth 2.1 Authorization Code + PKCE** für „Connect-in-Minutes" aus Claude/Cursor/ChatGPT.
|
||||
MCP ist Resource Server auf `https://mcp.hivegrid.de`; HiveGrid Web ist Authorization Server auf `https://app.hivegrid.de`.
|
||||
Pflicht: RFC 9728 Protected-Resource-Metadata, RFC 8414 Authorization-Server-Metadata, Resource-Indicator/Audience-Bindung,
|
||||
kurzlebige Access Tokens, rotierende Refresh Tokens, Consent + Widerruf. API-Key-Bearer bleibt nur als Operator-/Fallback-Pfad,
|
||||
nicht als primärer User-Connect-Flow.
|
||||
- **Read-Tools:** `hg_lead_search`/`hg_lead_get`, `hg_contact_search`, `hg_project_get`, `hg_pipeline_list`
|
||||
(`readOnlyHint`). (Tools statt Resources — breiterer Client-Support.)
|
||||
- **Write-Tools:** `hg_lead_create`, `hg_project_set_stage`, `hg_activity_add` — je mit `withPermission()` +
|
||||
@@ -33,27 +44,194 @@ Remote MCP-Server, der die **mandanten-gescopte** HiveGrid-Daten-/Aktions-Fläch
|
||||
## Benötigte Screens (Backend bedient — Design liefert [[VD-MCP]])
|
||||
| Screen [Route] | Kern-Inhalt |
|
||||
|---|---|
|
||||
| MCP-Verbindungen [Settings] | API-Key generieren/rotieren/widerrufen + Scopes; aktive Verbindungen; Setup-Anleitung für Clients (Connector-URL + Key); Audit der MCP-Tool-Aufrufe |
|
||||
| MCP-Verbindungen [Settings] | OAuth-Connect-Flow je Client (Claude/ChatGPT/Cursor/VS Code/manuell), Consent + Scopes, aktive Verbindungen, Widerruf/Rotation, Setup-Hinweise, Audit der MCP-Tool-Aufrufe |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] Remote-MCP-Server (Streamable HTTP) erreichbar; Session-Handling; Origin- + Protocol-Version-Checks
|
||||
- [ ] **Auth Stufe 1** (API-Key-Bearer → Tenant/User/Scopes aus [[VR-P22b]]); 401+`WWW-Authenticate`
|
||||
- [ ] **Read-Tools** (Lead/Contact/Project/Pipeline) tenant-gescopt via `withTenantScope()` + RLS
|
||||
- [ ] **Write-Tools** mit `withPermission()` + Client-Confirmation + `auditEvent` + `logActivity`; Annotations gesetzt
|
||||
- [ ] Rate-Limit pro Tenant; Output-Limits + Pagination; Zod-Validierung; Prompt-Injection-Härtung; kein Token-Passthrough
|
||||
- [ ] Konnektor `tenantHasModule('mcp')`; RLS auf allen Tenant-Tabellen
|
||||
- [ ] E2E: echter Client (Claude Desktop Custom Connector) verbunden + je 1 Read-/Write-Tool ausgeführt
|
||||
- [ ] (Stufe 2 OAuth 2.1 → Folge-Ticket/CR, nicht in diesem Scope)
|
||||
- [ ] Remote-MCP-Server (Streamable HTTP) auf `mcp.hivegrid.de` erreichbar; eigener `hivegrid-mcp` Container; Session-Handling; Origin- + Protocol-Version-Checks
|
||||
- Code/Container/CI/Staging erledigt: `apps/mcp`, Docker-Target `mcp`, root-only Streamable HTTP, `/mcp` bewusst 404, Origin/Host-Allowlist via `MCP_ALLOWED_*`, Coolify-Ressource `hivegrid-mcp`, `https://staging-mcp.hivegrid.de/healthz` und `/.well-known/oauth-protected-resource` live. Prod-Domain `mcp.hivegrid.de` bleibt als Produktions-Rollout/Promote offen.
|
||||
- [x] **OAuth 2.1 v1-Auth**: Protected-Resource-Metadata auf `mcp.hivegrid.de`, Authorization-Server-Metadata auf
|
||||
`app.hivegrid.de`, Authorization Code + PKCE, Token/Refresh/Revocation, DCR-fähiger Public-Client-Flow, Consent,
|
||||
Audience/Resource-Bindung, `WWW-Authenticate` Discovery
|
||||
- [x] **Fallback/Operator-Auth** (API-Key-Bearer → Tenant/User/Scopes aus [[VR-P22b]]); 401+`WWW-Authenticate`
|
||||
- [x] **Read-Tools** (Lead/Contact/Project/Pipeline) tenant-gescopt via `withTenantScope()` + RLS
|
||||
- [x] **Write-Tools** mit `withPermission()` + Client-Confirmation + `auditEvent` + `logActivity`; Annotations gesetzt
|
||||
- [x] Rate-Limit pro Tenant; Output-Limits + Pagination; Zod-Validierung; Prompt-Injection-Härtung; kein Token-Passthrough
|
||||
- [x] Konnektor `tenantHasModule('mcp')`; RLS auf allen Tenant-Tabellen
|
||||
- [x] E2E: echter Client per OAuth (Claude/Cursor/ChatGPT oder MCP Inspector) verbunden + je 1 Read-/Write-Tool ausgeführt — **erfüllt 2026-07-03 mit Claude Code** (s. Proof-Notizen unten)
|
||||
- Teilproof 2026-07-03: Dynamic Client Registration + Authorization Code + PKCE + Token Exchange auf Staging erfolgreich; offizieller MCP SDK Client verbindet gegen `https://staging-mcp.hivegrid.de/` und listet 8 Tools. Offen: Read-/Write-Tool mit fachlichem Ergebnis; `hg_pipeline_list` scheiterte an fehlender Staging-DB-Tabelle `public.Pipeline` — **aufgelöst 2026-07-03 (Akeshan, s. Notiz unten)**: Migration manuell per `prisma migrate deploy` nachgezogen, Tabelle vorhanden.
|
||||
- **Funktionaler Voll-Proof 2026-07-03 abends (Akeshan, s. Notiz unten):** kompletter OAuth-Flow (DCR mit Scopes + Browser-Consent + PKCE) + `tools/list` (8 Tools) + Read-Tool `hg_pipeline_list` (Sales-Pipeline mit 5 Stages) + Write-Tool `hg_lead_create` mit `confirm=true` (InboxLead angelegt) + `AuditEvent` (`mcp.lead.create`, sourceModule `mcp`, outcome `success`) + `Activity` (`lead_created`, „Lead per MCP erstellt.") in der Staging-DB verifiziert. Für den formalen Haken fehlt nur noch der Connect mit einem der **benannten** Produkt-Clients (Claude/Cursor/ChatGPT/MCP Inspector) — funktional ist nichts mehr offen.
|
||||
|
||||
**Stand 2026-07-03:** Scope-Update: MCP-Runtime/Tools/Deploy sind live und serverseitig verifiziert, aber OAuth 2.1 ist
|
||||
ab sofort v1-Pflicht und ersetzt den API-Key-Copy-Flow als primären User-Connect. Screens bleiben Folgearbeit aus [[VD-MCP]];
|
||||
zuerst muss der OAuth-Flow funktional und per echtem Client testbar sein.
|
||||
|
||||
## Technische Bausteine
|
||||
- `@modelcontextprotocol/sdk` (Server), `StreamableHTTPServerTransport`; eigener Service (`apps/mcp` oder Bereich in
|
||||
`apps/api`) — **nicht** in RR7-Loader/Action quetschen.
|
||||
- Auth/Scopes/Rate-Limit aus [[VR-P22b]] wiederverwenden; Tenant-Context-Middleware (Reihenfolge: TLS → Origin →
|
||||
Protocol-Version → Token+Audience → Tenant-Context → Rate-Limit → Zod → `withPermission` → Handler → Output-Truncation
|
||||
→ Audit).
|
||||
- `@modelcontextprotocol/sdk` (Server), `StreamableHTTPServerTransport`; eigener Service **`apps/mcp` → `hivegrid-mcp`**.
|
||||
**Nicht** in `apps/web`, `apps/api` oder RR7-Loader/Action quetschen.
|
||||
- Auth/Scopes/Rate-Limit aus [[VR-P22b]] wiederverwenden, aber als OAuth-Access-Token-Validierung kapseln; Tenant-Context-Middleware
|
||||
(Reihenfolge: TLS → Origin → Protocol-Version → OAuth Token + Audience/Resource → Tenant-Context → Rate-Limit → Zod →
|
||||
`withPermission` → Handler → Output-Truncation → Audit).
|
||||
- Querschnitt-Hülle: `withTenantScope`/`withPermission` (M004), `auditEvent` (M001), `logActivity`, `notify` (M011),
|
||||
Klartext-Fehler (M002) auch in Tool-`isError`-Texten.
|
||||
- Ausgangspunkt: vorhandenes `apps/web/app/modules/mcp/` (mcp.server.ts / mcp-tools.server.ts / fetch-transport.server.ts).
|
||||
2026-07-03 bereinigt: der alte Web-`/mcp`-Code wurde entfernt; MCP lebt jetzt ausschließlich in `apps/mcp`.
|
||||
|
||||
## Umsetzungs-Notiz
|
||||
|
||||
**2026-07-03:** MCP als eigene Runtime umgesetzt:
|
||||
- Neues Workspace-Paket `apps/mcp` mit Streamable-HTTP-Server am Host-Root, `McpServer` + `StreamableHTTPServerTransport`, stateless JSON responses, DNS-Rebinding-Protection, Health/Ready-Endpunkten.
|
||||
- Tool-Fläche implementiert: `hg_lead_search`, `hg_lead_get`, `hg_contact_search`, `hg_project_get`, `hg_pipeline_list`, `hg_lead_create`, `hg_project_set_stage`, `hg_activity_add`.
|
||||
- Auth/Scopes/Rate-Limit umgesetzt: Bearer-API-Key, Tenant/User aus Key, `WWW-Authenticate` bei 401, MCP-Scope-Checks, Tenant/API-Key-Limits über Shared Store.
|
||||
- Sicherheits- und Cross-Cutting-Wiring umgesetzt: Tenant aus Token, Zod-Inputs, Cursor-Pagination, kompakte Outputs, `confirm=true` für Writes, `withPermission`, `withTenantScope`, `auditEvent`, `logActivity`, Prompt-Injection-Hinweise in Tool-Beschreibungen/Output.
|
||||
- Deploy/Runtime vorbereitet: Docker-Target `mcp`, `verify:docker-mcp-runtime-smoke`, Gitea-CI Job für MCP, Deploy-Workflow baut/pusht `web/api/worker/mcp` und deployt `hivegrid-mcp` als abhängige HTTP-Ressource.
|
||||
- Web-Altlast entfernt: `apps/web/app/modules/mcp/**` und `apps/web/app/routes/mcp/**` gelöscht; `mcp/**` bleibt nur als disabled/reserved route tree, nicht als aktive Web-Route.
|
||||
- Env/Doku aktualisiert: `MCP_HOST`, `MCP_PORT`, `MCP_ALLOWED_HOSTS`, `MCP_ALLOWED_ORIGINS`, `API_KEY_HASH_SECRET`, Env-Katalog, Deployment-Doku.
|
||||
|
||||
**2026-07-03 Scope-Entscheidung:** OAuth 2.1 wird nicht mehr als spätere Stufe behandelt, sondern als v1-Funktionsscope.
|
||||
Begründung: Der gewünschte „Mit Claude/ChatGPT verbinden"-Flow braucht Discovery + Browser-Consent; statische API-Key-Config ist
|
||||
nur Fallback/Operator-Modus. Screens werden erst nach funktionalem OAuth-Proof finalisiert.
|
||||
|
||||
**2026-07-03 OAuth-Implementierung:** OAuth 2.1 serverseitig umgesetzt:
|
||||
- Neue Prisma-Modelle/Migration `mcpOAuth.prisma` + `20260703110500_vr_mcp_oauth`: `McpOAuthClient`,
|
||||
`McpOAuthAuthorizationCode`, `McpOAuthAccessToken`, `McpOAuthRefreshToken`; Codes/Tokens nur hash-only.
|
||||
- Authorization Server im Web: `/.well-known/oauth-authorization-server`, `/oauth/register`, `/oauth/authorize`,
|
||||
`/oauth/authorize/approve`, `/oauth/token`, `/oauth/revoke`.
|
||||
- MCP Resource Server: `/.well-known/oauth-protected-resource`, `WWW-Authenticate` mit Resource-Metadata, OAuth-Bearer-
|
||||
Validierung mit Audience/Resource-Bindung; API-Key bleibt Fallback/Operator-Pfad.
|
||||
- Staging/Prod-Config ergänzt: `MCP_RESOURCE_URL`, `MCP_AUTHORIZATION_SERVER_URL`, optional
|
||||
`MCP_OAUTH_TOKEN_HASH_SECRET`; Staging muss `https://staging-mcp.hivegrid.de` und
|
||||
`https://staging-app.hivegrid.de` setzen.
|
||||
|
||||
**Aktueller Proof lokal (OAuth-Änderung):**
|
||||
- `pnpm --dir . exec prisma validate`
|
||||
- `pnpm --filter @hivegrid/db typecheck`
|
||||
- `pnpm --filter @hivegrid/db test -- --run src/api-keys.server.test.ts` (Vitest-Wrapper lief paketweit: 57 Files, 437 Tests grün, 8 skipped)
|
||||
- `pnpm --filter @hivegrid/web typecheck`
|
||||
- `pnpm --filter @hivegrid/mcp typecheck`
|
||||
- `pnpm --filter @hivegrid/mcp test`
|
||||
|
||||
**2026-07-03 Staging-/MCP-Client-Proof und aktueller Übergabestand:**
|
||||
- Commits auf `main`:
|
||||
- `368533436` `ci(deploy): stop exporting registry build cache` — behebt Registry-Build-Cache-Export-Timeouts im CI.
|
||||
- `646f815b4` `fix(mcp): expose oauth metadata route` — `/.well-known/oauth-authorization-server` als echte Web-Route registriert.
|
||||
- `fede041de` `fix(mcp): clarify missing bearer token error` — 401-Text spricht korrekt von OAuth-Bearer-Access-Token.
|
||||
- `2663e019b` / `6b97ebf96` — MCP-Transport-Lifecycle gefixt; Server bleibt bis zum HTTP-Response-Finish offen.
|
||||
- `ee4c9a394` `fix(db): add project pipeline core migration` — fehlende P8-Projekt-/Pipeline-Core-Migration ergänzt.
|
||||
- Manuell verifiziert auf Staging:
|
||||
- `https://staging-app.hivegrid.de/.well-known/oauth-authorization-server` liefert `200` inkl. Authorization-/Token-/Registration-Endpunkten.
|
||||
- `https://staging-mcp.hivegrid.de/.well-known/oauth-protected-resource` liefert `200` inkl. Resource `https://staging-mcp.hivegrid.de`.
|
||||
- Unauthentifizierter MCP-Request liefert `401` mit `WWW-Authenticate` und `resource_metadata`.
|
||||
- Dynamic Client Registration (`/oauth/register`) + Browser-Authorize + PKCE-Code-Exchange (`/oauth/token`) funktionieren; Token-Werte wurden nicht dokumentiert.
|
||||
- Offizieller `@modelcontextprotocol/sdk` Client verbindet mit OAuth-Bearer-Token und listet Tools:
|
||||
`hg_lead_search`, `hg_lead_get`, `hg_contact_search`, `hg_project_get`, `hg_pipeline_list`,
|
||||
`hg_lead_create`, `hg_project_set_stage`, `hg_activity_add`.
|
||||
- Offen bei Übergabe an Akeshan:
|
||||
- Gitea-Deploy-Run `9168` für `ee4c9a394` wurde grün; `https://staging-app.hivegrid.de/healthz` und
|
||||
`https://staging-mcp.hivegrid.de/healthz` zeigen beide Revision `ee4c9a394032b66ad8e76895157a0c2527983a81`.
|
||||
- Trotzdem scheitert `hg_pipeline_list` weiter mit `The table public.Pipeline does not exist in the current database`.
|
||||
Nächster Check: Hat Coolify die Web-Pre-Deployment-Migration wirklich ausgeführt, gegen welche `DATABASE_URL`/`DIRECT_URL`
|
||||
lief sie, und nutzt `hivegrid-mcp` dieselbe Staging-DB wie `hivegrid-web`?
|
||||
- Nach erfolgreichem Deploy/Migrate erneut testen:
|
||||
1. Mit dem bestehenden oder neuem OAuth-Token per MCP SDK `client.listTools()` prüfen.
|
||||
2. `client.callTool({ name: "hg_pipeline_list", arguments: {} })` muss nach Migration nicht mehr mit `public.Pipeline does not exist` scheitern.
|
||||
3. Für vollständigen E2E danach ein Write-Tool mit `confirm=true` in einem geeigneten Test-Tenant ausführen und Audit/Activity prüfen.
|
||||
- Lokaler Proof für die Migration:
|
||||
- `pnpm exec prisma validate --config prisma.config.ts`
|
||||
- isolierter Postgres-16-Container: Migration `20260703123000_p8_project_pipeline_core/migration.sql` mit `psql -v ON_ERROR_STOP=1` erfolgreich angewendet; Tabellen `Pipeline`, `PipelineStage`, `Projekt` vorhanden.
|
||||
|
||||
**2026-07-03 (Akeshan) — Staging-Migrations-Blocker aufgelöst (manuell nachgezogen):**
|
||||
- **Befund:** `prisma migrate status` im Staging-Web-Container zeigte `20260703123000_p8_project_pipeline_core` als
|
||||
einzige nicht angewandte Migration (166/167 applied), obwohl Deploy-Run `9168` grün war und Revision `ee4c9a394`
|
||||
lief. **Ursache = wie beim Befund in [[AK-P4a]] (2026-06-23):** Coolify führt den per Deploy-Workflow gesetzten
|
||||
`pre_deployment_command` (`prisma migrate deploy`) **nicht zuverlässig** aus — die beiden früheren Migrationen vom
|
||||
selben Tag (07:01/09:33 UTC) kamen an, die von Run `9168` nicht. Der Deploy verifiziert auf Staging nur
|
||||
Health/Revision, keinen Migrations-Status → das Loch fällt erst beim ersten fachlichen Query auf.
|
||||
- **Fix (bewusst nur manueller Trigger, Hook-Reparatur separat):** `pnpm exec prisma migrate deploy --config
|
||||
prisma.config.ts` im Staging-Web-Container ausgeführt; Migration sauber angewandt (`_prisma_migrations` 14:25 UTC).
|
||||
- **Verifiziert:** `migrate status` → „Database schema is up to date" (167/167); `SELECT count(*)` auf
|
||||
`Pipeline`/`PipelineStage`/`Projekt` liefert 3/15/0 statt `TableDoesNotExist`. **Raffaels DB-Frage geklärt:**
|
||||
`hivegrid-web` und `hivegrid-mcp` nutzen dieselbe DB (`DATABASE_URL` = `DIRECT_URL` = selbe Postgres-Instanz,
|
||||
DB `hivegrid`) — kein URL-Mismatch.
|
||||
- **Nächster Schritt E2E:** `client.callTool({ name: "hg_pipeline_list" })` erneut testen (sollte jetzt Daten liefern),
|
||||
danach Write-Tool mit `confirm=true` + Audit/Activity-Check.
|
||||
- **⚠️ Separater Befund (blockiert Teile des E2E, eigenes Follow-up nötig):** Die Staging-DB hat darüber hinaus
|
||||
**massiven Schema-Drift**: `prisma migrate diff` (DB → Schema) zeigt **93 fehlende Tabellen**, für die **gar keine
|
||||
Migrations-Files existieren** (AD-21-Muster: Feature-Branch `db push`, Merge-Migration nie erzeugt) — u.a. `Kontakt`,
|
||||
`InboxLead`, `Dashboard`, Auftrag-/Automation-/Kalender-/HR-/Forms-Domänen. Konsequenz hier: `hg_contact_search`/
|
||||
`hg_lead_search`/`hg_lead_create` laufen auf Staging weiter in `TableDoesNotExist`, bis die fehlenden
|
||||
Merge-Migrationen erzeugt sind; sichtbares Symptom in der Web-App: 500 auf `/demo-pro-crm/dashboard`
|
||||
(`prisma.dashboard.upsert` → `public.Dashboard` fehlt). Der CI-Gate „migrate deploy gegen leere DB"
|
||||
(`infra/LESSONS.md §9`) fängt das nicht — er prüft nur vorhandene Migrations-Files, nicht Schema↔Migrations-Parität
|
||||
(dafür bräuchte es `prisma migrate diff --from-migrations --to-schema --exit-code` als Gate).
|
||||
|
||||
**2026-07-03 abends (Akeshan) — Schema-Drift behoben + funktionaler E2E-Tool-Proof:**
|
||||
- **Drift-Befund von heute Mittag ist behoben:** PR #32 (`akeshan/schema-parity-catchup`, gemerged als `cf2d4d678`)
|
||||
liefert die AD-21-Aufhol-Migration `20260703150000_ak_schema_parity_catchup` (93 Tabellen/88 Enums, idempotent nach
|
||||
P8-Muster) **plus** den neuen CI-Gate `verify:migrations-parity` (Migrations-Replay in ephemeren Postgres, Diff gegen
|
||||
`prisma/schema`, verdrahtet im `database`-Job beider CI-Workflows) — „Schema geändert, Merge-Migration vergessen"
|
||||
bricht ab jetzt den PR statt erst Staging. Coolify-Hook hat die Migration beim Deploy erneut NICHT ausgeführt →
|
||||
manuell nachgezogen, `migrate status` 168/168 up to date, 262 Tabellen; `/demo-pro-crm/dashboard` und `/contacts`
|
||||
rendern (vom User im Browser bestätigt).
|
||||
- **E2E-Tool-Proof gegen `https://staging-mcp.hivegrid.de/`** (standards-konformer OAuth-2.1-Client, Streamable HTTP):
|
||||
1. DCR `/oauth/register` — wichtig: `scope` muss im Registration-Request mitgegeben werden, sonst wird der Client
|
||||
nur mit Default-Scope registriert und `/oauth/authorize` lehnt mit „Scope not registered for this client" ab.
|
||||
2. Browser-Authorize + Consent (User-Session) + PKCE-S256-Code-Exchange → Access-Token mit allen 9 Scopes (1h).
|
||||
3. MCP-Requests brauchen einen **erlaubten `Origin`-Header** (`MCP_ALLOWED_ORIGINS` = `https://staging-app.hivegrid.de`,
|
||||
`https://staging-web.hivegrid.de`) — sonst 403 „Invalid Origin header".
|
||||
4. `initialize` + `tools/list` → 8 Tools; **Read:** `hg_pipeline_list` liefert die Sales-Pipeline mit 5 Stages
|
||||
(tenant-gescopt, Tenant `demo-business-crm`); **Write:** `hg_lead_create` mit `confirm=true` legt
|
||||
`InboxLead cmr57zk0f000001mptutf1qf8` an (E2E Proof / vr-mcp-e2e-proof@example.test, status `new`, quelle `custom`).
|
||||
5. Querschnitt verifiziert in der Staging-DB: `AuditEvent` (`action=mcp.lead.create`, `targetType=lead`,
|
||||
`sourceModule=mcp`, `outcome=success`) + `Activity` (`activityType=lead_created`, `actorKind=automation`,
|
||||
„Lead per MCP erstellt.") — beide mit der Lead-Id als Target/Subject.
|
||||
- **Rest für den formalen DoD-Haken:** einmaliger Connect mit einem benanntem Produkt-Client
|
||||
(Claude/Cursor/ChatGPT/MCP Inspector) — funktional ist der Pfad komplett bewiesen. Danach Prod-Rollout
|
||||
(`mcp.hivegrid.de`) + [[VD-MCP]]-Screens.
|
||||
|
||||
**2026-07-03 spät (Akeshan) — Produkt-Client-Connect (Claude Code) blockiert durch Origin-Check, Fix auf diesem Branch:**
|
||||
- **Befund:** Claude Code als benannter Produkt-Client (`claude mcp add --transport http hivegrid-staging
|
||||
https://staging-mcp.hivegrid.de`) durchläuft OAuth vollständig (DCR + Consent + Token „authentication successful"),
|
||||
wird aber beim Reconnect abgelehnt („Got new credentials, but hivegrid-staging rejected them on reconnect").
|
||||
Ursache: die DNS-Rebinding-Protection des MCP-SDK (`StreamableHTTPServerTransport`) lehnt bei konfigurierten
|
||||
`allowedOrigins` jeden Request **ohne** `Origin`-Header ab (`Invalid Origin header: undefined`, SDK
|
||||
`streamableHttp.js` Origin-Validierung). Native MCP-Clients (Claude Code/Desktop, Cursor, Inspector-CLI) senden
|
||||
prinzipbedingt keinen Origin-Header → **kein benannter Produkt-Client konnte verbinden**; der Auth-Check läuft
|
||||
vorher und war erfolgreich (deshalb wirkte es wie ein Token-Problem).
|
||||
- **Fix (dieser Branch, `apps/mcp/src/transport.ts`):** `buildOriginAllowlist()` — die `allowedOrigins`-Allowlist wird
|
||||
nur noch an das SDK durchgereicht, wenn der Request tatsächlich einen `Origin`-Header trägt (Browser-Kontext,
|
||||
z.B. browser-basierter MCP Inspector); ohne Origin-Header entfällt nur der Origin-Check, der Host-Check
|
||||
(`allowedHosts`) bleibt für jeden Request aktiv. DNS-Rebinding ist ein Browser-Angriff — für native Clients ohne
|
||||
Origin ist die Prüfung gegenstandslos. Unit-Test `apps/mcp/src/transport.test.ts`. Proof lokal:
|
||||
`pnpm --filter @hivegrid/mcp typecheck` + `test` (9 Tests) + `build` grün.
|
||||
- **Rückbau der Client-Anbindung beim Testenden (falls gewünscht):** `claude mcp remove hivegrid-staging -s local`
|
||||
entfernt Server + gespeicherte Credentials aus der lokalen Claude-Code-Config (nichts davon liegt im Repo);
|
||||
Access-Tokens laufen nach 1h ab. Test-Leads aus `hg_lead_create` sind normale InboxLeads im Tenant und können
|
||||
in der Lead-Inbox archiviert/gelöscht werden (z.B. `cmr57zk0f000001mptutf1qf8`, „E2E Proof").
|
||||
- **Nach Merge/Deploy:** in Claude Code `/mcp` → `hivegrid-staging` → re-authenticate; danach sollten die 8
|
||||
`hg_*`-Tools nutzbar sein → formaler DoD-Haken.
|
||||
|
||||
**2026-07-03 (Akeshan) — formaler Produkt-Client-Proof mit Claude Code (DoD-Haken gesetzt):**
|
||||
- Nach Deploy des Origin-Fixes: Claude Code (`claude mcp add --transport http hivegrid-staging
|
||||
https://staging-mcp.hivegrid.de`) verbindet per OAuth (Consent im Browser durch den User), alle 8 `hg_*`-Tools
|
||||
verfügbar.
|
||||
- **Read:** `hg_pipeline_list` → Sales-Pipeline mit 5 Stages (tenant-gescopt). **Write:** `hg_activity_add` mit
|
||||
`confirm=true` auf dem E2E-Test-Lead → Activity `cmr59h3wu000001ji93ee3f6a` („note_added").
|
||||
- **Querschnitt in der Staging-DB verifiziert:** `AuditEvent` `action=mcp.activity.add`, `targetType=lead`,
|
||||
`sourceModule=mcp`, `outcome=success` + `Activity`-Zeile mit Proof-Text.
|
||||
- Damit ist der DoD-Punkt „echter Client per OAuth + je 1 Read-/Write-Tool" vollständig erfüllt. Offen am Ticket:
|
||||
Prod-Rollout `mcp.hivegrid.de` (DoD 1) + [[VD-MCP]]-Screens (Raffael/David).
|
||||
|
||||
**Früherer Proof lokal (MCP-Runtime vor OAuth-Nachzug):**
|
||||
- `pnpm --filter @hivegrid/mcp build`
|
||||
- `pnpm --filter @hivegrid/config test`
|
||||
- `pnpm --filter @hivegrid/web test -- app/routes.test.ts app/modules/i18n/visible-shell-copy-i18n.test.ts app/utils/app/PublicRouteSegments.test.ts app/utils/app/HostRouting.server.test.ts`
|
||||
- `pnpm typecheck`
|
||||
- `pnpm run verify:env-drift`
|
||||
- `pnpm run verify:deploy-readiness`
|
||||
- `pnpm run verify:deploy-workflow`
|
||||
- `pnpm run verify:docker-baseline`
|
||||
- `docker build --target mcp --build-arg APP_REVISION=ci-smoke-revision -t hivegrid-mcp:smoke .`
|
||||
- `bash scripts/docker-mcp-runtime-smoke.sh hivegrid-mcp:smoke`
|
||||
|
||||
## Abhängigkeiten
|
||||
- **blocked-by:** [[VR-P22a]] (Read-Endpoints + OpenAPI-Vertrag), [[VR-P22b]] (API-Key-Auth/Scopes/Rate-Limit) — beide
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | Phase 22 (v2-P1) — Public-API & Webhooks |
|
||||
| **Cycle/Fenster** | v2-W1 — Public-API/Postfach/Abo/KI-Start · fällig 2026-07-15 |
|
||||
| **Status** | geplant |
|
||||
| **Status** | umgesetzt |
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `R-P2b` (v1-`ApiKey`-Modell — lag aus v1/M027 ungenutzt bereit, wird hier erstmals genutzt; RLS via `app.tenant_id`)
|
||||
@@ -14,23 +14,47 @@
|
||||
- **Läuft parallel zu:** `VA-P23` (Postfach-Sync, Akeshan) — teilen sich später die **Webhook-Ingest-Infra** (in VR-P22b), hier aber kein Schema-Konflikt: Read-API ist rein lesend über bestehende Entitäten. Eigene `prisma/schema/publicApi.prisma` (AD-21) für API-eigene Tabellen, fremde Domänen nur lesend berührt.
|
||||
- **Konflikt-Risiko:** keines (Read-only).
|
||||
|
||||
## Host-/Surface-Contract (verbindlich)
|
||||
|
||||
- **Public API nur auf `api.hivegrid.de`** (staging: `staging-api.hivegrid.de`), nicht unter `app.hivegrid.de/api`.
|
||||
- Versionierungs-Prefix ist **`/v1/...`**: `https://api.hivegrid.de/v1/contacts`, `https://api.hivegrid.de/v1/openapi.json`.
|
||||
- Die Web-App (`app.hivegrid.de`) darf API-Links/Docs anzeigen, hostet aber keine Public-API-Routen.
|
||||
- Spätere Modul-Tickets muessen beim Bau bewusst entscheiden: `public_api_surface = none | read | write | webhook` und bei `read/write/webhook` Scope, Serializer, OpenAPI, RLS und Tests ergaenzen.
|
||||
|
||||
## Was wir bauen
|
||||
Den **lesenden Teil der versionierten Public-REST-API** (`/api/v1/…`): externe Systeme lesen die HiveGrid-Hauptentitäten **Kontakte, Firmen/Organisationen, Deals, Projekte, Tasks, Leads** cursor-paginiert, mit Filter/Sort/Sparse-Fieldsets/Embed (Tiefe 1). Dazu eine **auto-generierte OpenAPI-3.1-Spezifikation** (`/api/v1/openapi.json`) plus Swagger-UI. Bewusster Recut: **Read-only**, kein Voll-CRUD, kein GraphQL, kein 3-Legged-OAuth (alles später). Auth/Scopes/Rate-Limit folgen in VR-P22b — diese Teilphase liefert die Endpoint-Struktur, Serialisierung und Doku-Generierung.
|
||||
Den **lesenden Teil der versionierten Public-REST-API** (`https://api.hivegrid.de/v1/…`): externe Systeme lesen die HiveGrid-Hauptentitäten **Kontakte, Firmen/Organisationen, Deals, Projekte, Tasks, Leads** cursor-paginiert, mit Filter/Sort/Sparse-Fieldsets/Embed (Tiefe 1). Dazu eine **auto-generierte OpenAPI-3.1-Spezifikation** (`https://api.hivegrid.de/v1/openapi.json`) plus Swagger-UI auf dem API-Host. Bewusster Recut: **Read-only**, kein Voll-CRUD, kein GraphQL, kein 3-Legged-OAuth (alles später). Auth/Scopes/Rate-Limit folgen in VR-P22b — diese Teilphase liefert die Endpoint-Struktur, Serialisierung und Doku-Generierung.
|
||||
|
||||
## Benötigte Screens (Backend bedient — Design liefert `D-P22`)
|
||||
| Screen [Route] | Kern-Inhalt |
|
||||
|---|---|
|
||||
| OpenAPI/Swagger-UI [`/api/v1/openapi` · Swagger] | Auto-generierte OpenAPI-3.1-Doku + interaktiver Try-it-out (entwickler-gerichtet) |
|
||||
| OpenAPI/Swagger-UI [`api.hivegrid.de/v1/openapi.json` · Swagger auf API-Host] | Auto-generierte OpenAPI-3.1-Doku + interaktiver Try-it-out (entwickler-gerichtet) |
|
||||
|
||||
*(Die REST-Endpoints `/api/v1/contacts\|companies\|deals\|projects\|tasks\|leads` sind serverseitig — kein eigener Screen außer Swagger-UI. API-Key-Verwaltungs-Screens liegen in VR-P22b.)*
|
||||
*(Die REST-Endpoints `https://api.hivegrid.de/v1/contacts|companies|deals|projects|tasks|leads` sind serverseitig — kein eigener Screen außer Swagger-UI. API-Key-Verwaltungs-Screens liegen in VR-P22b.)*
|
||||
|
||||
## Definition of Done
|
||||
- [ ] `GET /api/v1/{contacts,companies,deals,projects,tasks,leads}` — **cursor-paginiert** + Filter + Sort + **Sparse-Fieldsets** + Embed (Tiefe 1)
|
||||
- [ ] `read_only`-Scope **blendet sensible Felder aus** (Feld weglassen, **nicht 403**)
|
||||
- [ ] **OpenAPI-3.1 auto-generiert** (`/api/v1/openapi.json`) + Swagger-UI
|
||||
- [ ] Antworten respektieren **RLS** (`app.tenant_id` pro Transaktion gesetzt) — kein Cross-Tenant-Leck
|
||||
- [ ] Konnektor `tenantHasModule('public_api')` gated die API-Verfügbarkeit (Tarif-Gate-Vollausbau in VR-P22b)
|
||||
- [ ] Versionierungs-Präfix `/api/v1/` etabliert (Breaking-Changes → `/api/v2/`)
|
||||
- [x] `GET https://api.hivegrid.de/v1/{contacts,companies,deals,projects,tasks,leads}` — **cursor-paginiert** + Filter + Sort + **Sparse-Fieldsets** + Embed (Tiefe 1)
|
||||
- [x] `read_only`-Scope **blendet sensible Felder aus** (Feld weglassen, **nicht 403**)
|
||||
- [x] **OpenAPI-3.1 auto-generiert** (`https://api.hivegrid.de/v1/openapi.json`, staging `https://staging-api.hivegrid.de/v1/openapi.json`) + Swagger-UI auf API-Host
|
||||
- [x] Antworten respektieren **RLS** (`app.tenant_id` pro Transaktion gesetzt) — kein Cross-Tenant-Leck
|
||||
- [x] Konnektor `tenantHasModule('public_api')` gated die API-Verfügbarkeit (Tarif-Gate-Vollausbau in VR-P22b)
|
||||
- [x] Versionierungs-Präfix `/v1/` auf `api.hivegrid.de` etabliert (Breaking-Changes → `/v2/`); keine Public-API unter `app.hivegrid.de/api`
|
||||
|
||||
## Umsetzung 2026-07-03
|
||||
|
||||
**Stand:** 6/6 DoD = 100 % done.
|
||||
|
||||
**Proof:** `pnpm typecheck` grün; `pnpm lint` grün; `pnpm test` grün (572 Test-Dateien passed, 8 skipped; 3639 Tests passed, 46 skipped); `pnpm run verify:api-inventory` grün (17 Tests); `pnpm --filter @hivegrid/api typecheck` grün; `pnpm exec vitest run apps/api/src/public-api/resources.test.ts apps/api/src/app.test.ts apps/api/src/openapi.test.ts apps/api/src/route-access-inventory.test.ts` grün (140 Tests); `git grep -nE "@ai-sdk/openai[^-]|@ai-sdk/anthropic|remix-auth-google" -- "*.ts"` leer.
|
||||
|
||||
**Umgesetzt:**
|
||||
- Neue Public-API-Resource-Registry + Read-Service unter `apps/api/src/public-api/`.
|
||||
- Routen `GET /v1/contacts`, `/v1/companies`, `/v1/deals`, `/v1/projects`, `/v1/tasks`, `/v1/leads` unter `api.hivegrid.de`-Runtime registriert, nicht in der Web-App.
|
||||
- API-Key-Validierung, API-Key-Log, IP-Log, Tarif-/Modul-Gate über den vorhandenen Entitlement-Key `api`, Cursor-Pagination, Filter, Sort, Sparse-Fieldsets und Embed Tiefe 1.
|
||||
- RLS pro Read-Transaktion via `set_config('app.tenant_id', tenantId, true)`.
|
||||
- OpenAPI-3.1-Pfade werden aus der Registry generiert und in `/v1/openapi.json` eingebunden.
|
||||
- `/v1/docs` ist ein self-contained Swagger-style OpenAPI-Explorer mit Try-request-Funktion.
|
||||
- Route-Access-Inventar + OpenAPI-Security-Tests für alle neuen Routen nachgezogen.
|
||||
|
||||
**Hinweis:** Die Ticket-Doc nennt `tenantHasModule('public_api')`; im aktuellen Entitlements-Modell ist der bestehende Feature-/Modul-Key fuer Public-API `api` (`packages/entitlements`). Die Runtime gate't daher bewusst gegen `api`; ein separater Scope-/Rate-Limit-/Webhook-Vollausbau bleibt VR-P22b.
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (eigene `prisma/schema/publicApi.prisma`, AD-21): `ApiKey` ([v2]-markiert im ENTITY-MODEL: `key_hash`, `scope`, `expires_at`, [RLS][Soft-Delete]) — in dieser Teilphase nur **lesend referenziert** (Scope-Filter), Auth-Logik kommt in VR-P22b. Lesende Entitäten (`Kontakt`, `Projekt`/Pipeline-Views „deals"/„projects", `Task`, Lead) werden über ihre Domänen-Schemata gelesen, **nicht** verändert.
|
||||
@@ -39,6 +63,7 @@ Den **lesenden Teil der versionierten Public-REST-API** (`/api/v1/…`): externe
|
||||
- **`is_demo_data`:** nicht relevant (kein Seeding eigener Daten), aber Read-API muss `is_demo_data`-Datensätze normal ausliefern (Demo-Tenant-tauglich).
|
||||
- **Serialisierung:** Sparse-Fieldsets + Embed-Resolver (Tiefe 1) als Query-Layer; `read_only`-Scope filtert sensible Felder serverseitig vor der Serialisierung.
|
||||
- **OpenAPI-Tooling:** vor Bau wählen (z.B. zod-to-openapi für 3.1) — Spec aus den Endpoint-Schemata generieren, nicht manuell pflegen.
|
||||
- **API-Extension-Pattern fuer Folgemodule:** Jedes neue Modul dokumentiert `public_api_surface = none | read | write | webhook`. Wenn exponiert wird: Resource-Pfad unter `api.hivegrid.de/v1`, Scope(s), Serializer/Redaction, RLS/Tenant-Scope, OpenAPI-Schema, Rate-Limit/Usage-Logging und Tests sind Pflicht.
|
||||
|
||||
## Quellen (granular)
|
||||
- `ROADMAP-V2.md` → §v2-P1 (Success-Criteria 1/4, Screens) — **Hauptquelle**
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | Phase 22 (v2-P1) — Public-API & Webhooks |
|
||||
| **Cycle/Fenster** | v2-W1 — Public-API/Postfach/Abo/KI-Start · fällig 2026-07-17 |
|
||||
| **Status** | geplant |
|
||||
| **Status** | On Hold — serverseitig umgesetzt, Admin-Screens/UX aus `D-P22` fehlen |
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `VR-P22a` (Read-Endpoints + OpenAPI), `R-P12a` (v1-Automation: `external_event`-Trigger + ausgehende Webhook-Action)
|
||||
@@ -15,25 +15,32 @@
|
||||
- **Konflikt-Risiko:** gering — nur die geteilte Webhook-Ingest-Infra braucht Koordination (Owner = Raffael, Akeshan dockt an).
|
||||
|
||||
## Was wir bauen
|
||||
Den **Auth-, Scope-, Rate-Limit- und Webhook-Teil** der Public-API. API-Keys authentifizieren Requests mit **Scopes** und **Rate-Limit** (1k/h pro Key, 10k/h pro Tenant, `X-RateLimit-*`-Header + Klartext-429). **Eingehende Lead-Webhooks** (`POST /webhooks/incoming/{tenant}/{slug}`) legen Leads an (API-Key/HMAC/URL-Token + Payload-Mapping + Auto-Match). **Ausgehende `WebhookSubscriptions`** senden Events HMAC-SHA256-signiert mit Idempotenz-ID, Retry mit exp. Backoff (max 5) und Auto-Disable nach 10 Fehlern; die ausgehende Webhook-**Action** dockt an die v1-Automation (`external_event`-Trigger) an. Tarif-Gates (M027) machen API-Keys/Webhooks abo-abhängig.
|
||||
Den **Auth-, Scope-, Rate-Limit- und Webhook-Teil** der Public-API auf **`api.hivegrid.de`** (staging:
|
||||
`staging-api.hivegrid.de`). Es gibt keine Public-API- oder Public-Webhook-Routen unter `app.hivegrid.de/api`.
|
||||
API-Keys authentifizieren Requests mit **Scopes** und **Rate-Limit** (1k/h pro Key, 10k/h pro Tenant,
|
||||
`X-RateLimit-*`-Header + Klartext-429). **Eingehende Lead-Webhooks**
|
||||
(`POST https://api.hivegrid.de/v1/webhooks/incoming/{tenant}/{slug}`) legen Leads an (API-Key/HMAC/URL-Token +
|
||||
Payload-Mapping + Auto-Match). **Ausgehende `WebhookSubscriptions`** senden Events HMAC-SHA256-signiert mit
|
||||
Idempotenz-ID, Retry mit exp. Backoff (max 5) und Auto-Disable nach 10 Fehlern; die ausgehende Webhook-**Action**
|
||||
dockt an die v1-Automation (`external_event`-Trigger) an. Tarif-Gates (M027) machen API-Keys/Webhooks abo-abhängig.
|
||||
|
||||
## Benötigte Screens (Backend bedient — Design liefert `D-P22`)
|
||||
| Screen [Route] | Kern-Inhalt |
|
||||
|---|---|
|
||||
| API-Key-Verwaltung [`/admin/api-keys`] | Key-Liste (Name/Scopes/letzte Nutzung/Status/Tarif-Gate) · Key erstellen (Scope-Auswahl, **Secret einmal sichtbar**) · Rotieren/Widerrufen — Erweiterung der v1-Fläche |
|
||||
| Incoming-Webhook-Verwaltung [`/admin/api-keys/incoming-webhooks`] | Slug-Endpoints, Auth-Modus (API-Key/HMAC/URL-Token), Payload-Mapping, Auto-Match-Regeln · Ingestion-Log |
|
||||
| Incoming-Webhook-Verwaltung [`/admin/api-keys/incoming-webhooks`] | Slug-Endpoints auf `api.hivegrid.de/v1/webhooks/...`, Auth-Modus (API-Key/HMAC/URL-Token), Payload-Mapping, Auto-Match-Regeln · Ingestion-Log |
|
||||
| Outgoing-Subscription-Liste [`/admin/webhooks`] | Ziel-URL, Event-Typen, Status (aktiv/auto-disabled), letzte Zustellung, Fehlerzähler |
|
||||
| Outgoing-Subscription-Detail [`/admin/webhooks/:id`] | **Secret einmal sichtbar**, Delivery-Stats, Delivery-Log mit Retry-Status, Replay/Test-senden, Aktivieren/Pausieren |
|
||||
| API-Request-Logs + Usage [`/admin/api-keys/usage`] | Request-Log (Endpoint/Key/Status/Latenz/Rate-Limit-Treffer) · Usage-Aggregat (Calls/h pro Key + Tenant, Quota) |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **API-Key-Auth** + **Scopes** + **Rate-Limit** (1k/h Key, 10k/h Tenant) + `X-RateLimit-*`-Header + Klartext-429
|
||||
- [ ] **Eingehende Lead-Webhooks** (API-Key/HMAC/URL-Token) + Payload-Mapping + **Auto-Match** (From/Pattern → Contact/Lead)
|
||||
- [ ] **Ausgehende `WebhookSubscriptions`** HMAC-SHA256-signiert, Idempotenz-ID, Retry exp. Backoff (max 5), **Auto-Disable nach 10 Fehlern**
|
||||
- [ ] **Tarif-Gates (M027):** API-Keys/Webhooks nur im passenden Abo verfügbar (`tenantHasModule('public_api')`)
|
||||
- [ ] **Writes** durch v1-Frozen/past_due-Middleware geblockt (**402**)
|
||||
- [ ] Secret/Webhook-Signing-Secret **einmalig sichtbar** (Copy-once-Muster), nur Hash persistiert
|
||||
- [ ] Ausgehende Webhook-Action an v1-Automation (`external_event`-Trigger) angedockt
|
||||
- [x] **API-Key-Auth** + **Scopes** + **Rate-Limit** (1k/h Key, 10k/h Tenant) + `X-RateLimit-*`-Header + Klartext-429
|
||||
- [x] **Eingehende Lead-Webhooks** auf `api.hivegrid.de/v1/webhooks/...` (API-Key/HMAC/URL-Token) + Payload-Mapping + **Auto-Match** (From/Pattern → Contact/Lead)
|
||||
- [x] **Ausgehende `WebhookSubscriptions`** HMAC-SHA256-signiert, Idempotenz-ID, Retry exp. Backoff (max 5), **Auto-Disable nach 10 Fehlern**
|
||||
- [x] **Tarif-Gates (M027):** API-Keys/Webhooks nur im passenden Abo verfügbar (`tenantHasModule('public_api')`)
|
||||
- [x] **Writes** durch v1-Frozen/past_due-Middleware geblockt (**402**)
|
||||
- [x] Secret/Webhook-Signing-Secret **einmalig sichtbar** (Copy-once-Muster), nur Hash persistiert
|
||||
- [x] Ausgehende Webhook-Action an v1-Automation (`external_event`-Trigger) angedockt
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (eigene `prisma/schema/publicApi.prisma`, AD-21): `ApiKey` (`key_hash`, `scope`, `expires_at`, [RLS][Soft-Delete] — Auth-Pfad hier vollständig), `WebhookSubscription` (Ziel-URL, abonnierte Event-Typen, Signing-Secret-Hash, Status, Fehlerzähler), Incoming-Webhook-Endpoint (Slug, Auth-Modus, Payload-Mapping), Delivery-/Ingestion-Log (append-only). Lead-Anlage über die CRM-Domäne (Lead-Entity), nur referenziert.
|
||||
@@ -41,6 +48,8 @@ Den **Auth-, Scope-, Rate-Limit- und Webhook-Teil** der Public-API. API-Keys aut
|
||||
- **Rate-Limit:** Redis-Token-Bucket (geteilt mit v1-Redis), Key- und Tenant-Bucket getrennt.
|
||||
- **HMAC:** SHA256 für ein- und ausgehend; Signatur-Header + dokumentiertes Format (Code-Snippet für Verifizierung im UI).
|
||||
- **Webhook-Ingest-Infra:** geteilter Layer mit VA-P23 (Postfach-Sync) — einmal robust, idempotent.
|
||||
- **Host-Surface:** Public API und Public-Webhooks laufen nur im `hivegrid-api`-Service (`api.hivegrid.de` /
|
||||
`staging-api.hivegrid.de`), nie im Web-Service (`app.hivegrid.de/api` ist verboten).
|
||||
- **Konnektor:** `tenantHasModule('public_api')` + Tarif-Gate (M027, `SubscriptionFeature.code`).
|
||||
- **`is_demo_data`:** ggf. Demo-Webhook-Subscriptions geseedet (Bulk-Löschung beim Echt-Start).
|
||||
|
||||
@@ -55,4 +64,18 @@ Den **Auth-, Scope-, Rate-Limit- und Webhook-Teil** der Public-API. API-Keys aut
|
||||
## Dev-Nachzug (nach Davids `D-P22`-Delta)
|
||||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
- [ ] Plane-Ticket `VR-P22b` aktualisiert
|
||||
- [x] Plane-Ticket `VR-P22b` aktualisiert
|
||||
|
||||
## Umsetzungsnotiz
|
||||
|
||||
**2026-07-03 — Server-DoD umgesetzt, Ticket auf On Hold bis `D-P22`:**
|
||||
- API-Key-Scopes, Legacy-Read-Kompatibilität, Key-/Tenant-Rate-Limits und `X-RateLimit-*`-Header für `GET /v1/...` ergänzt.
|
||||
- `POST /v1/webhooks/incoming/{tenant}/{slug}` auf dem API-Service (`api.hivegrid.de`) ergänzt: URL-Token, HMAC und API-Key-Auth, Payload-Mapping, Lead-Anlage, Kontakt-Auto-Match, Ingestion-Log, Tarif-Gate und 402 bei `frozen`/`past_due`.
|
||||
- `prisma/schema/publicApi.prisma`, Migration `20260703090000_vr_p22b_public_api_webhooks` und RLS-Rollout-Datei für Incoming-Endpoints, Ingestion-Logs, Outgoing-Subscriptions und Delivery-Logs ergänzt.
|
||||
- Outgoing-Subscription-Service ergänzt: Copy-once Signing-Secret, Hash-only-Persistenz, HMAC-Signatur, Idempotenz-Key, Delivery-Log, exponential Backoff bis 5 Versuche und Auto-Pause nach 10 Fehlern.
|
||||
- v1-Automation ist angebunden: eingehende Webhooks erzeugen `AutomationExecution` für `webhook.received` mit `triggerPayload.source = "external_event"`; die bestehende `http.request`-Action bleibt der ausgehende Webhook-Action-Pfad.
|
||||
- OpenAPI, Route-Access-Inventar, Security-Doku, Tenant-Registry und Tests nachgezogen.
|
||||
|
||||
**Proof:** `pnpm exec prisma validate`; `pnpm --filter @hivegrid/api typecheck`; `pnpm --filter @hivegrid/db typecheck`; `pnpm --filter @hivegrid/cli typecheck`; fokussierte Vitest-Suite für Public-API/OpenAPI/Route-Inventar/DB; `pnpm run verify:api-inventory`; `pnpm run verify:openapi-security`; `node scripts/verify-cross-cutting-models-complete.mjs`; `pnpm typecheck`; `pnpm lint`; `pnpm test`.
|
||||
|
||||
**Stand:** 7/7 Server-DoD = 100 % serverseitig. Gesamtticket bleibt **On Hold**, weil die Verwaltungs-Screens aus `D-P22` noch fehlen: API-Key-Verwaltung, Incoming-Webhooks, Outgoing-Subscriptions, Detail/Replay und Usage-Logs.
|
||||
@@ -41,11 +41,12 @@ Den **DSGVO-Vollausbau** (M166): aus dem manuellen v1-Playbook werden echte Self
|
||||
- [ ] **Tenant-Lösch-Workflow** (30-Tage-Grace + **Hard-Delete-Cron**, ~~inkl. **pgvector-Embedding-Löschung** beim Hard-Delete~~ → **No-op ([[AD-26]]: TenantEmbedding nie befüllt)**)
|
||||
- [ ] **Admin-Legal-Verwaltung** (Subprozessoren + AVV-Versionen) mit **AdminAuditLog**
|
||||
- [ ] KWP-Subprozessor-Vermerk übernommen (Creds liegen ab v2-P5 verschlüsselt in der Cloud — aus VR-P32a)
|
||||
- [ ] **Lösch-Strategien der offenen `USER_FK_MAP`-Einträge fachlich/rechtlich bestätigt** — `AdminTenantNote.authorUserId` + `SupportTicket.assignedToUserId` + `SupportTicketMessage.authorUserId` → `retain-tombstone`/Export-Ausschluss abnehmen. Code-Strategie ist gewählt + begründet (`packages/db/src/dsgvo/user-fk-map.ts`); offen ist nur das DSGVO-Confirm — verlagert aus dem dortigen `TODO`.
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (eigene `prisma/schema/dsgvo.prisma`, AD-21): `AvvAcceptance` (v1: `avv_version`, `accepted_by`, `pdf_file_id`, `signer_name`, [RLS]) + AVV-Versions-Entity (global/admin-seitig: Versionen + Veröffentlichung), `Subprocessor` (v1/global: `name`, `country`, `is_eu_eea`, `data_categories`, `dpa_url`) + Widerspruchs-Entity (Tenant-bezogen, 14-Tage-Frist), `TenantDeletionRequest` (v1: `reason`, `grace_period_ends_at` (+30d), `status`, [RLS], Slug-Confirm), Export-Job-Entity (async, ZIP, 7-Tage-Window).
|
||||
- **AVV:** dynamisches PDF aus Template + Tenant-Daten; elektronische Akzeptanz speichert `avv_version` + `accepted_by` + `signer_name` + `pdf_file_id`; Re-Akzeptanz-Resolver setzt Tenant nach 14 Tagen auf Read-Only.
|
||||
- **Hard-Delete-Cron:** nach 30-Tage-Grace löscht der Cron alle Tenant-Daten. ~~**inkl. pgvector-`TenantEmbedding`** (Andockpunkt an VR-P25)~~ → **`TenantEmbedding`-Löschung = No-op ([[AD-26]]: nie befüllt, VR-P25 zurückgestellt).**
|
||||
- **Hard-Delete-Cron:** nach 30-Tage-Grace löscht der Cron alle Tenant-Daten. ~~**inkl. pgvector-`TenantEmbedding`** (Andockpunkt an alten VR-P25-Scope)~~ → **`TenantEmbedding`-Löschung = No-op ([[AD-26]]: nie befüllt, alter VR-P25-Scope zurückgestellt).**
|
||||
- **RLS:** Tenant-bezogene DSGVO-Daten mit `app.tenant_id`; `Subprocessor`/AVV-Versionen global; Admin-Legal-Verwaltung via AdminAuditLog (VR-P28a, kein BYPASSRLS).
|
||||
- **Wiederverwendung:** v1-DSGVO-Export/-Lösch-Fundament (AK-P21), v1-Files (Export-ZIP, AVV-PDF), BullMQ-Worker (async Export), v1-Frozen→Deletion.
|
||||
- **`is_demo_data`:** nicht relevant (Compliance-Daten).
|
||||
|
||||
@@ -9,6 +9,8 @@
|
||||
| **Status** | geplant · 🟠 **block-2 (Partner-API offen, agil)** |
|
||||
|
||||
> 🟠 **block-2 — Partner-API offen, agil:** Der konkrete KWP-API-Vertrag (Auth/Endpoints/Webhook-Support/Rate-Limits/Versionierung/Doc-API) ist noch offen — **KWP-API-Zugang ~19./20.07.** ist der härteste Kalender-Anker (das v2-Hauptverkaufsargument). Detail-Planung pro Milestone erst gegen die echte API-Doku (→ `VEXT-1`). Bau startet, sobald der Zugang aktiv ist; Reihenfolge/Umfang sind agil. **`kwpsync.exe` wird NICHT gebaut** (3→2-Komponenten, Recut bindend, M089 obsolet als Windows-Client).
|
||||
>
|
||||
> 🟢 **Update 2026-06-25 — Zugang eingetroffen (früher):** Auth-Frage geklärt → **`type='oauth2'`** (Keycloak-OIDC `kwp-federated`, Auth-Code + PKCE/S256, Confidential Client + `offline_access`/Refresh; Multi-Tenant über `tenant`-Param + ClientId/Secret je Mandant). Resource-API = RPC-artige Action-API, basePath `/relay/kwp3/pwa` (Swagger `…/swagger/v1/swagger.json`). Endpoint-/Webhook-/Rate-Limit-Details + `Vorgang`/`Termin`/`Archiv` laufen weiter in `VEXT-1` (Spike). **Bleibt v2; `blocked-by R-P5` (M33a-Interface) unverändert.**
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `R-P5` (v1-Apps-Engine M33a-Adapter-Interface `connect/disconnect/validateConnection/syncPull/syncPush/handleWebhook` — KWP ist der **erste konkrete Adapter** dahinter), `VEXT-1` (KWP-API-Zugang aktiv + Recut-Detailplanung gegen die echte Doku)
|
||||
@@ -32,7 +34,7 @@ Den **KWP-API-Connector** als ersten konkreten Adapter hinter dem M33a-Interface
|
||||
- [ ] **Connection-Health-Probe** (generisch, statt Heartbeat) + Re-Connect
|
||||
- [ ] **Push-Queue** via Cloud-Outbox + **Rate-Limited-Replay** (Replay-Rate aus KWP-Rate-Limits), idempotent über `AppSyncItem`
|
||||
- [ ] Push „Won→Auftrag" als Automation-Action (`kwp.push_auftrag`) andockbar
|
||||
- [ ] DataConnection `type='rest-api'`/`'oauth2'` je nach realer KWP-Auth-Methode (aus VEXT-1)
|
||||
- [ ] DataConnection **`type='oauth2'`** (geklärt 2026-06-25: Keycloak-OIDC Auth-Code + PKCE, Confidential Client + `offline_access`)
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (eigene `prisma/schema/appsEngine.prisma` — aus v1 übernommen, AD-21): `App{type:"kwp"}`, `DataConnection{type:"rest-api"|"oauth2", config:<DEK-verschlüsselt>, connection_status, last_health_check}`, `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem` (`entity_type`/`id` HiveGrid ↔ `external_id`, `operation`, `status` — inkl. `rolledBackData` für den M093-Restore in VR-P32b). `KwpErrorReport` für Sync-Log-Fehler.
|
||||
|
||||
@@ -13,11 +13,11 @@
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `VR-P32b` (abgesicherte Sync-Schicht: Sentinel + Konflikt), `R-P9b` (v1-Plantafel/Auftrag-Extension-Points + Material — KWP dockt rückwirkend an)
|
||||
- **Blocks:** `VN-2` (E2E-Validierung mit Geerkens Fr 24.07.)
|
||||
- **Läuft parallel zu:** `VA-P27` (Mobile-PWA, Akeshan) — kein Schema-Konflikt; nutzt v1-`@toolctrl/storage` + FileEntityLink (Doku-Archiv) und die Task-Domäne (M074).
|
||||
- **Läuft parallel zu:** `VA-P27` (Mobile-PWA, Akeshan) — kein Schema-Konflikt; nutzt v1-`@hivegrid/storage` + FileEntityLink (Doku-Archiv) und die Task-Domäne (M074).
|
||||
- **Konflikt-Risiko:** keines auf Schema-Ebene.
|
||||
|
||||
## Was wir bauen
|
||||
Die **Sync-Familie**: **Plantafel-Sync** (bidirektional über die API — `syncPush` + Webhook/Cron-Pull), **Dokumenten-Archiv-Sync** (KWP-Doc → `@toolctrl/storage`) und **Task-ERP-Sync (M074)**. Alles idempotent über `AppSyncItem`, abgesichert durch den Contract-Sentinel und die „KWP gewinnt"-Regel aus VR-P32b. Im Recut laufen alle drei über die API (kein Client-Dateizugriff mehr). Abschluss-Beweis ist die **E2E-Validierung mit Geerkens am Fr 24.07.**
|
||||
Die **Sync-Familie**: **Plantafel-Sync** (bidirektional über die API — `syncPush` + Webhook/Cron-Pull), **Dokumenten-Archiv-Sync** (KWP-Doc → `@hivegrid/storage`) und **Task-ERP-Sync (M074)**. Alles idempotent über `AppSyncItem`, abgesichert durch den Contract-Sentinel und die „KWP gewinnt"-Regel aus VR-P32b. Im Recut laufen alle drei über die API (kein Client-Dateizugriff mehr). Abschluss-Beweis ist die **E2E-Validierung mit Geerkens am Fr 24.07.**
|
||||
|
||||
## Benötigte Screens (Backend bedient — Design liefert `D-P32`/Akeshan)
|
||||
| Screen [Route] | Kern-Inhalt |
|
||||
@@ -28,15 +28,15 @@ Die **Sync-Familie**: **Plantafel-Sync** (bidirektional über die API — `syncP
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **Plantafel-Sync bidirektional** über die API (`syncPush` + Webhook-Pull falls KWP-Support, sonst Cron-Pull)
|
||||
- [ ] **Dokumenten-Archiv-Sync** KWP → `@toolctrl/storage` (FileEntityLink an Auftrag/Projekt)
|
||||
- [ ] **Dokumenten-Archiv-Sync** KWP → `@hivegrid/storage` (FileEntityLink an Auftrag/Projekt)
|
||||
- [ ] **Task-ERP-Sync (M074)**, idempotent über `AppSyncItem`
|
||||
- [ ] **E2E mit Geerkens Fr 24.07.** grün (Won→Auftrag→KWP, Plantafel, Doku, Tasks durchgespielt)
|
||||
- [ ] Material-Listen am Auftrag mit KWP-Daten befüllt (v1-Extension-Point genutzt)
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (`prisma/schema/appsEngine.prisma` + Domänen-Schemata, AD-21): `AppSyncItem` (idempotente Mappings für Plantafel/Doku/Task), `ProjektExternesFeld` [v2] (`projekt_id`, `system='kwp'`, `feld_key`, `wert` — KWP-Felder am Projekt, in v1 NICHT vorhanden). Doku über v1-`@toolctrl/storage` + `FileEntityLink`; Tasks über die v1-Task-Domäne (M074, Task-ERP-Sync).
|
||||
- **Entities** (`prisma/schema/appsEngine.prisma` + Domänen-Schemata, AD-21): `AppSyncItem` (idempotente Mappings für Plantafel/Doku/Task), `ProjektExternesFeld` [v2] (`projekt_id`, `system='kwp'`, `feld_key`, `wert` — KWP-Felder am Projekt, in v1 NICHT vorhanden). Doku über v1-`@hivegrid/storage` + `FileEntityLink`; Tasks über die v1-Task-Domäne (M074, Task-ERP-Sync).
|
||||
- **Plantafel-Sync:** bidirektional via API — `syncPush` für HiveGrid→KWP, Webhook-Pull (falls KWP-Support) oder Cron-Pull für KWP→HiveGrid; idempotent über `AppSyncItem`.
|
||||
- **Dokumenten-Archiv-Sync:** KWP-Dokumenten-Endpoint (Listing + Download, aus VEXT-1) → `@toolctrl/storage`; FileEntityLink an Auftrag/Projekt.
|
||||
- **Dokumenten-Archiv-Sync:** KWP-Dokumenten-Endpoint (Listing + Download, aus VEXT-1) → `@hivegrid/storage`; FileEntityLink an Auftrag/Projekt.
|
||||
- **Task-ERP-Sync (M074):** Tasks ↔ KWP-Aufträge idempotent über `AppSyncItem`; nutzt v1-Task-Entity-Links (M071↔M042, in P6 nachverdrahtet).
|
||||
- **RLS:** alles Tenant-bezogene mit `app.tenant_id`.
|
||||
- **Konnektor:** `tenantHasModule('kwp_integration')`.
|
||||
@@ -45,7 +45,7 @@ Die **Sync-Familie**: **Plantafel-Sync** (bidirektional über die API — `syncP
|
||||
## Quellen (granular)
|
||||
- `ROADMAP-V2.md` → §v2-P5 (Success-Criteria 5, E2E Geerkens Fr 24.07.) — **Hauptquelle**
|
||||
- `ROADMAP.md` → Phase 32
|
||||
- **`docs/milestones/M19-KWP-API-RECUT.md` (bindend)** → M094 (Plantafel via API, Webhook/Cron-Pull), M095 (Doku-Endpoint → `@toolctrl/storage`), offene Vertrags-Fragen 2/3/6 (Capabilities/Webhook/Doku-API)
|
||||
- **`docs/milestones/M19-KWP-API-RECUT.md` (bindend)** → M094 (Plantafel via API, Webhook/Cron-Pull), M095 (Doku-Endpoint → `@hivegrid/storage`), offene Vertrags-Fragen 2/3/6 (Capabilities/Webhook/Doku-API)
|
||||
- `PHASE-SOURCES.md` → Phase 32 (M094/095/074); M074 → Phase 32 verschoben (braucht Apps-Engine + KWP-Foundation); Retro-Integrationen wandern mit (Auftrag-Archiv/Material/Task-ERP)
|
||||
- `ENTITY-MODEL.md` → `ProjektExternesFeld` [v2], `AppSyncItem`, Material-Listen am Auftrag (v1)
|
||||
- `designer-briefs/P32-kwp-integration.md` (Sync-Log, Recut)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# VR-P33 · Telefonie-Erweiterung HalloPetra (M105)
|
||||
|
||||
> ⚠️ **KI→MCP-Pivot ([[AD-26]]):** Der **Whisper-Voicemail-Transkriptions-Andock entfällt** (kein Whisper/LLM mehr — VR-P25 zurückgestellt, HiveGrid wird MCP-Server, [[VR-MCP]]). Der restliche Telefonie-Teil (HalloPetra-Provider hinter `TelephonyProviderInterface`) ist unberührt. Whisper-Stellen unten durchgestrichen.
|
||||
> ⚠️ **KI→MCP-Pivot ([[AD-26]]):** Der **Whisper-Voicemail-Transkriptions-Andock entfällt** (kein Whisper/LLM mehr — alter VR-P25-Scope zurückgestellt, HiveGrid wird MCP-Server, [[VR-MCP]]). Der restliche Telefonie-Teil (HalloPetra-Provider hinter `TelephonyProviderInterface`) ist unberührt. Whisper-Stellen unten durchgestrichen.
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
@@ -19,20 +19,20 @@
|
||||
- **Konflikt-Risiko:** keines auf Schema-Ebene.
|
||||
|
||||
## Was wir bauen
|
||||
Bindet **HalloPetra als zusätzlichen Provider** hinter dem bestehenden `TelephonyProviderInterface` an — **ohne Kern-Umbau** (zweiter Adapter neben AirCall). Eingehende Webhooks werden auto-gematcht (auf Contact/Lead/Deal), landen im Activity-Stream und triggern Automationen (`call.*`). Click-to-Call, Inbound und Logging bleiben providerunabhängig: E.164-Normalisierung, Match-Confidence, Notiz-Editor. Aus Tenant-Sicht ist HalloPetra einfach eine weitere wählbare Telefonie-Anbindung neben AirCall.
|
||||
Bindet **HalloPetra als zusätzlichen Provider** hinter dem bestehenden `TelephonyProviderInterface` an — **ohne Kern-Umbau** (zweiter Adapter neben AirCall). Eingehende Webhooks werden auto-gematcht (auf Contact/Lead/Projekt), landen im Activity-Stream und triggern Automationen (`call.*`). Click-to-Call, Inbound und Logging bleiben providerunabhängig: E.164-Normalisierung, Match-Confidence, Notiz-Editor. Aus Tenant-Sicht ist HalloPetra einfach eine weitere wählbare Telefonie-Anbindung neben AirCall.
|
||||
|
||||
## Benötigte Screens (Backend bedient — Design liefert `D-P33`/`D-Telefonie-Erw.`)
|
||||
| Screen [Route] | Kern-Inhalt |
|
||||
|---|---|
|
||||
| Telefonie-Setup [`/settings/telephony`] | Provider-Connect (HalloPetra **neben** AirCall), Credential-/OAuth-Eingabe (maskiert), Verbindungs-Test |
|
||||
| User-Bindings [`/settings/telephony/bindings`] | Zuordnung User ↔ Telefonie-Nummer/-Account, providerunabhängig |
|
||||
| Call-Session-Detail [`/calls/:id`] | Anruf-Daten (Richtung/Dauer/Match auf Contact/Lead/Deal + Match-Confidence), Aufnahme-Link, Notiz-Editor |
|
||||
| Call-Session-Detail [`/calls/:id`] | Anruf-Daten (Richtung/Dauer/Match auf Contact/Lead/Projekt + Match-Confidence), Aufnahme-Link, Notiz-Editor |
|
||||
|
||||
*(Click-to-Call ist ein Quick-Action-Element auf Contact/Lead/Deal-Detail aus v1 — providerunabhängig, kein neuer Screen.)*
|
||||
*(Click-to-Call ist ein Quick-Action-Element auf Contact/Lead/Projekt-Detail aus v1 — providerunabhängig, kein neuer Screen.)*
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **HalloPetra-Adapter** implementiert `TelephonyProviderInterface` (`connect`/`triggerOutboundCall`/`subscribeToWebhooks`/`verifyWebhookSignature`/`parseWebhookEvent`/`getRecordingUrl`) **ohne Kern-Umbau**
|
||||
- [ ] **Webhook-Auto-Match** auf Contact/Lead/Deal → Activity + Automation-Trigger (`call.*`)
|
||||
- [ ] **Webhook-Auto-Match** auf Contact/Lead/Projekt → Activity + Automation-Trigger (`call.*`)
|
||||
- [ ] Click-to-Call + Inbound + Logging providerunabhängig (E.164-Normalisierung, Match-Confidence, Notiz-Editor)
|
||||
- [ ] Provider-Auswahl/-Wechsel im Setup (HalloPetra neben AirCall)
|
||||
- [ ] Recording-Abruf über `getRecordingUrl` (sofern HalloPetra-API liefert)
|
||||
@@ -41,9 +41,9 @@ Bindet **HalloPetra als zusätzlichen Provider** hinter dem bestehenden `Telepho
|
||||
## Technische Bausteine
|
||||
- **Entities** (v1-Telefonie-Domäne, AD-21 — kein neues Schema nötig): `TelephonyConnection` (v1: `provider` (aircall → **+hallopetra**), `oauth_token` (verschlüsselt), `webhook_secret`, max. 1 aktiv/Tenant, [RLS]), `TelephonyCallSession` (v1: `direction`, `status`, `from`/`to_number` (E.164), `matched_kontakt`/`lead`/`projekt_id`, `note`, `recording_url`, [RLS][Soft-Delete][polymorph match]), `TelephonyWebhookEvent` (v1: `event_type`, `signature_valid`, `processing_status`, [append-only][30d]).
|
||||
- **Provider-Pattern:** HalloPetra = neuer Adapter hinter dem v1-`TelephonyProviderInterface`; **kein Kern-Umbau** — nur Adapter-Implementierung + `provider`-Enum-Erweiterung.
|
||||
- **Auto-Match:** Webhook → E.164-Normalisierung → Match auf Contact/Lead/Deal (Match-Confidence) → Activity-Stream + Automation-Trigger (`call.*`).
|
||||
- **Auto-Match:** Webhook → E.164-Normalisierung → Match auf Contact/Lead/Projekt (Match-Confidence) → Activity-Stream + Automation-Trigger (`call.*`).
|
||||
- **Konnektor:** `tenantHasModule('telephony')`; Provider-Auswahl im Setup.
|
||||
- ~~**Whisper-Kopplung:** Voicemail-Transkription via VR-P25 (Whisper-EU), optional/später.~~ → **entfällt ([[AD-26]]: kein Whisper/LLM; VR-P25 zurückgestellt).**
|
||||
- ~~**Whisper-Kopplung:** Voicemail-Transkription via altem VR-P25-Scope (Whisper-EU), optional/später.~~ → **entfällt ([[AD-26]]: kein Whisper/LLM; alter VR-P25-Scope zurückgestellt).**
|
||||
- **`is_demo_data`:** Demo-Call-Sessions seedbar.
|
||||
|
||||
## Quellen (granular)
|
||||
|
||||
Reference in new issue
Block a user