From bf56aa6a2d1ee55cabd118ec977feee0311ceef9 Mon Sep 17 00:00:00 2001 From: Schalli Date: Mon, 22 Jun 2026 13:48:36 +0200 Subject: [PATCH] docs(04): capture phase context --- .../04-CONTEXT.md | 105 +++++++++++++++ .../04-DISCUSSION-LOG.md | 120 ++++++++++++++++++ 2 files changed, 225 insertions(+) create mode 100644 .planning/phases/04-marketplace-portal-navigation/04-CONTEXT.md create mode 100644 .planning/phases/04-marketplace-portal-navigation/04-DISCUSSION-LOG.md diff --git a/.planning/phases/04-marketplace-portal-navigation/04-CONTEXT.md b/.planning/phases/04-marketplace-portal-navigation/04-CONTEXT.md new file mode 100644 index 0000000..b166250 --- /dev/null +++ b/.planning/phases/04-marketplace-portal-navigation/04-CONTEXT.md @@ -0,0 +1,105 @@ +# Phase 4: Marketplace & Portal Navigation - Context + +**Gathered:** 2026-06-22 +**Status:** Ready for planning + + +## Phase Boundary + +Kategorisierter Marketplace zum Browsen aller verfuegbaren Module, Aktivierung/Deaktivierung pro Mandant durch Super-Admin via Mandanten-Kontext-Wechsel, dynamische Sidebar-Integration aktivierter Module mit Suche/Filter, und Modul-Detail-Ansicht. Kein Dashboard, kein Payment, keine volle Impersonation — nur Mandanten-Kontext-Selector im Marketplace-/Modul-Bereich fuer Super-Admin. + + + + +## Implementation Decisions + +### Marketplace-Layout +- **D-01:** Marketplace als Karten-Grid (wie VS Code Extensions / App Store). Jede Karte zeigt Icon, Name, Kurzbeschreibung, Kategorie-Badge, Aktivierungs-Status. +- **D-02:** Suchleiste + Kategorie-Filter oben auf Marketplace-Seite. Live-Filter waehrend Tippen. Kategorie-Chips oder Dropdown. +- **D-03:** Empty State: Freundliche Illustration + Text ("Noch keine Module verfuegbar"). + +### Aktivierungs-Flow +- **D-04:** Super-Admin bekommt leichtgewichtigen Mandanten-Kontext-Selector im Marketplace-Bereich (Dropdown zur Mandanten-Auswahl). Aktivierung/Deaktivierung erfolgt aus Perspektive des gewaehlten Mandanten. Kein volles Impersonation-System — nur Kontext-Wechsel fuer Modul-Management (volle Impersonation bleibt v2: FEAT-V2-04). +- **D-05:** Regulaerer Admin aktiviert Module direkt fuer seinen eigenen Mandanten (kein Kontext-Wechsel noetig). + +### Claude's Discretion +- Marketplace Filter/Status-Unterscheidung: Tab-Ansicht vs. Badge-System vs. Kombination — basierend auf UX Best Practices +- Bestaetigungs-Dialog bei Aktivierung: Dialog vs. sofortige Aktion mit Undo-Toast — UX-Entscheidung +- Visuelles Feedback nach Aktivierung: Toast + Badge-Update vs. Animation — passend zum existierenden Design +- Sidebar Kategorien-Darstellung: Bestehendes Accordion beibehalten vs. flache Liste mit Gruppen-Header — basierend auf Modul-Anzahl und UX +- Sidebar collapsed Modus: Modul-Icons anzeigen vs. nur Haupt-Navigation — basierend auf existierender Sidebar-Logik +- Sidebar Suchfeld: Im Kategorien-Bereich vs. globale Header-Suche vs. beides — basierend auf PRTAL-05 und Komplexitaet +- Modul-Detail-Ansicht Tiefe: Ausfuehrlich (App-Store-Stil) vs. kompakt — passend fuer v1 Modul-Anzahl +- Marketplace-Detail vs. Modul-Nutzung Navigation: Separate Seiten vs. Tabs vs. anderes Pattern — basierend auf App Router Architektur + + + + +## Canonical References + +**Downstream agents MUST read these before planning or implementing.** + +### Projekt-Kontext +- `.planning/PROJECT.md` — Gesamtprojekt, Core Value, Constraints +- `.planning/REQUIREMENTS.md` — Phase-4-Requirements: MRKT-01..04, PRTAL-02, PRTAL-03, PRTAL-05 +- `.planning/ROADMAP.md` — Phase-Ziel und Success Criteria + +### Vorherige Phasen +- `.planning/phases/01-foundation-portal-shell/01-CONTEXT.md` — Design-Entscheidungen, OKLCH Tokens, Sidebar-Verhalten (D-01..D-06), Header (D-07..D-09), Farbschema +- `.planning/phases/02-authentication-multi-tenancy/02-CONTEXT.md` — Auth, Rollen (D-12: Super-Admin/Admin/User), Mandanten-Modell (D-08..D-11), RLS +- `.planning/phases/03-module-system-domaincheck/03-CONTEXT.md` — Module SDK, Registry, Kategorien (D-04..D-09), ModuleCard Pattern, Lazy Loading + +### Research +- `.planning/research/STACK.md` — Technologie-Stack (NestJS 11, Prisma 7, Next.js 16, shadcn/ui) +- `.planning/research/ARCHITECTURE.md` — Architektur-Patterns + + + + +## Existing Code Insights + +### Reusable Assets +- `apps/web/src/components/layout/sidebar.tsx` — Sidebar mit Kategorie-Accordion, fetcht `/modules/active`, zeigt Module gruppiert nach Kategorie. Muss erweitert werden fuer Suche/Filter. +- `apps/web/src/app/(portal)/modules/[category]/components/ModuleCard.tsx` — Bestehende ModuleCard Komponente, wiederverwendbar fuer Marketplace-Grid. +- `apps/web/src/app/(portal)/modules/[category]/page.tsx` — Kategorie-Seite mit Modulen, Pattern fuer Marketplace-Seite. +- `apps/api/src/module-registry/module-registry.controller.ts` — REST API: GET /modules (alle), GET /modules/active (aktive pro Tenant), POST activate/deactivate. Komplett vorhanden. +- `apps/api/src/module-registry/module-registry.service.ts` — Service mit findAll, findActiveForTenant, activateForTenant, deactivateForTenant, seedModule. +- `apps/api/prisma/schema.prisma` — Module Model (slug, name, version, category, description JSON, icon, isSystem) + TenantModuleActivation (tenantId, moduleId, isActive). + +### Established Patterns +- NestJS Module mit Controller + Service + DTOs +- Next.js App Router Route Groups: `(auth)` fuer Login, `(portal)` fuer authentifizierte Seiten +- Zustand Stores fuer Client-State (sidebar-store, auth-store) +- next-intl fuer alle UI-Strings +- Fetch mit `credentials: 'include'` fuer API-Aufrufe +- Rollen-basierte UI-Sichtbarkeit (isAdmin, isSuperAdmin Checks in Sidebar) + +### Integration Points +- Marketplace-Seite braucht Route `/marketplace` im `(portal)` Route Group +- Sidebar-Suche muss bestehendes Accordion-System erweitern +- Tenant-Kontext-Selector fuer Super-Admin braucht Tenant-Liste API (existiert evtl. ueber admin/tenants) +- Aktivierungs-Buttons muessen bestehende POST /modules/:id/activate API nutzen +- Module Description ist JSON (mehrsprachig) — Marketplace muss richtige Sprache anzeigen + + + + +## Specific Ideas + +- Mandanten-Kontext-Selector: Dropdown in Marketplace-Header-Bereich, nur fuer Super-Admin sichtbar. Zeigt aktuell gewaehlten Mandanten. Wechsel aktualisiert Aktivierungs-Status aller Modul-Karten. +- Marketplace-Route: `/marketplace` als Hauptseite, `/marketplace/[slug]` fuer Modul-Detail +- Karten-Grid responsive: 1 Spalte mobile, 2 Spalten Tablet, 3-4 Spalten Desktop + + + + +## Deferred Ideas + +- **FEAT-V2-04: Volle Admin-Impersonation** — Komplettes "Als Mandant agieren"-Feature kommt in v2. Phase 4 baut nur leichtgewichtigen Kontext-Selector fuer Modul-Management. + + + +--- + +*Phase: 4-Marketplace & Portal Navigation* +*Context gathered: 2026-06-22* diff --git a/.planning/phases/04-marketplace-portal-navigation/04-DISCUSSION-LOG.md b/.planning/phases/04-marketplace-portal-navigation/04-DISCUSSION-LOG.md new file mode 100644 index 0000000..b6711ed --- /dev/null +++ b/.planning/phases/04-marketplace-portal-navigation/04-DISCUSSION-LOG.md @@ -0,0 +1,120 @@ +# Phase 4: Marketplace & Portal Navigation - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered. + +**Date:** 2026-06-22 +**Phase:** 04-marketplace-portal-navigation +**Areas discussed:** Marketplace-Layout, Aktivierungs-Flow, Sidebar-Suche & Filter, Modul-Detail-Ansicht + +--- + +## Marketplace-Layout + +| Option | Description | Selected | +|--------|-------------|----------| +| Karten-Grid | Module als Karten in Grid (wie VS Code Extensions, App Store) | ✓ | +| Kategorien-Sektionen | Seite nach Kategorien unterteilt mit eigener Karten-Reihe | | +| Du entscheidest | Claude waehlt bestes Layout | | + +**User's choice:** Karten-Grid + +| Option | Description | Selected | +|--------|-------------|----------| +| Visueller Badge | Alle Module im Grid, aktivierte mit gruenem Badge | | +| Tab-Ansicht | Tabs: Alle/Aktiviert/Verfuegbar | | +| Du entscheidest | Claude waehlt passende Unterscheidung | ✓ | + +**User's choice:** Du entscheidest + +| Option | Description | Selected | +|--------|-------------|----------| +| Suchleiste + Kategorie-Filter | Suchfeld + Dropdown/Chips fuer Kategorien, Live-Filter | ✓ | +| Nur Suchleiste | Einfache Suche, Kategorien nur als Seitenstruktur | | +| Du entscheidest | Claude waehlt | | + +**User's choice:** Suchleiste + Kategorie-Filter + +| Option | Description | Selected | +|--------|-------------|----------| +| Illustration + Text | Freundliche Illustration mit Hinweistext | ✓ | +| Minimal Text | Nur Text-Hinweis | | +| Du entscheidest | Claude waehlt | | + +**User's choice:** Illustration + Text + +--- + +## Aktivierungs-Flow + +**User's free-text input:** "Es soll so etwas wie 'Kunde als Super-Admin impersonieren' geben und darüber dann Module aktivieren/deaktivieren." + +**Clarification:** User confirmed lightweight tenant context selector for Super-Admin in marketplace (not full impersonation). Claude decides implementation details (Variante B). + +| Option | Description | Selected | +|--------|-------------|----------| +| Bestaetigungs-Dialog | Dialog bei Aktivierung/Deaktivierung | | +| Direkt ohne Dialog | Sofortige Aktion, Undo per Toast | | +| Du entscheidest | Claude waehlt passende UX | ✓ | + +| Option | Description | Selected | +|--------|-------------|----------| +| Toast + Karten-Update | Erfolgs-Toast + sofortiges Badge-Update | | +| Animierter Uebergang | Karte animiert (Glow/Pulse) | | +| Du entscheidest | Claude waehlt visuelles Feedback | ✓ | + +--- + +## Sidebar-Suche & Filter + +| Option | Description | Selected | +|--------|-------------|----------| +| Suchfeld im Kategorien-Bereich | Kleines Suchfeld ueber Accordion | | +| Globale Suche im Header | Header-Suchleiste filtert auch Module | | +| Du entscheidest | Claude waehlt bestes Suchpattern | ✓ | + +| Option | Description | Selected | +|--------|-------------|----------| +| Accordion beibehalten | Bestehender aufklappbarer Stil | | +| Flache Liste mit Gruppen-Header | Alle Module sichtbar, gruppiert | | +| Du entscheidest | Claude waehlt basierend auf UX | ✓ | + +| Option | Description | Selected | +|--------|-------------|----------| +| Ja, Modul-Icons | Collapsed zeigt Modul-Icons mit Tooltip | | +| Nein, nur Haupt-Nav | Nur Dashboard/Marketplace Icons | | +| Du entscheidest | Claude waehlt | ✓ | + +--- + +## Modul-Detail-Ansicht + +| Option | Description | Selected | +|--------|-------------|----------| +| Ausfuehrlich | App-Store-Stil mit Screenshots/Vorschau | | +| Kompakt | Name, Beschreibung, Kategorie, Version, Button | | +| Du entscheidest | Claude waehlt passende Detailtiefe fuer v1 | ✓ | + +| Option | Description | Selected | +|--------|-------------|----------| +| Separate Seiten | Marketplace-Detail vs. Modul-Nutzung getrennt | | +| Gleiche Seite, Tabs | Info-Tab + Verwenden-Tab | | +| Du entscheidest | Claude waehlt bestes Pattern | ✓ | + +--- + +## Claude's Discretion + +Viele Bereiche an Claude delegiert: +- Marketplace Filter/Status-Darstellung (Tabs vs. Badges) +- Bestaetigungs-UX bei Aktivierung +- Visuelles Feedback nach Aktivierung +- Sidebar Kategorien-Stil (Accordion vs. flache Liste) +- Sidebar collapsed Modus Modul-Anzeige +- Sidebar Suchfeld Platzierung +- Modul-Detail-Ansicht Tiefe +- Marketplace-Detail vs. Modul-Nutzung Navigation + +## Deferred Ideas + +- FEAT-V2-04: Volle Admin-Impersonation (komplett als Mandant agieren) — v2