docs(04): create phase plan

2026-06-22 14:20:01 +02:00
parent 0470d500b2
commit fb6e90d78e
5 changed files with 510 additions and 6 deletions
@@ -19,10 +19,11 @@ autonomous: true
 requirements: [MRKT-01, MRKT-02, MRKT-04]
 must_haves:
  truths:
-    - "User can navigate to /marketplace and see a card grid of all available modules with name, description and category badge"
-    - "Each card shows whether the module is activated (green status badge) or available for the current tenant"
+    - "User can navigate to /marketplace and see a card grid of all available modules with name, description and category badge (D-01)"
+    - "Each card shows whether the module is activated (green status badge) or available for the current tenant (D-01)"
    - "Admin can click the activate button on an available module card and it becomes activated (POST /modules/:id/activate)"
-    - "Modules are grouped/labelled by category via a category badge on each card"
+    - "Modules are grouped/labelled by category via a category badge on each card (D-01)"
+    - "Empty state shows friendly illustration + text when no modules available (D-03)"
  artifacts:
    - path: "apps/web/src/app/(portal)/marketplace/page.tsx"
      provides: "Marketplace grid page with parallel fetch of /modules + /modules/active, activation map, role gate"
@@ -18,8 +18,8 @@ autonomous: true
 requirements: [MRKT-01, MRKT-02, MRKT-04]
 must_haves:
  truths:
-    - "User can type in the marketplace search box and the card grid live-filters by module name and description (debounced)"
-    - "User can filter the grid by category chip and by status tab (Alle / Aktiviert / Verfuegbar)"
+    - "User can type in the marketplace search box and the card grid live-filters by module name and description (debounced) (D-02)"
+    - "User can filter the grid by category chip and by status tab (Alle / Aktiviert / Verfuegbar) (D-02)"
    - "Super-Admin sees a tenant-context dropdown; switching tenant re-fetches activation status for that tenant and activation targets that tenant (D-04)"
    - "Deactivating a module shows a confirmation dialog before the deactivate call; activation shows a success toast (no dialog)"
    - "User can open a module detail page at /marketplace/[slug] showing the full description, status, and an activation button"
@@ -0,0 +1,422 @@
+# Phase 4: Marketplace & Portal Navigation - Pattern Map
+
+**Mapped:** 2026-06-22
+**Files analyzed:** 12 new/modified files
+**Analogs found:** 12 / 12
+
+## File Classification
+
+| New/Modified File | Role | Data Flow | Closest Analog | Match Quality |
+|-------------------|------|-----------|----------------|---------------|
+| `apps/web/src/app/(portal)/marketplace/page.tsx` | component (page) | request-response | `apps/web/src/app/(portal)/admin/modules/page.tsx` | exact |
+| `apps/web/src/app/(portal)/marketplace/[slug]/page.tsx` | component (page) | request-response | `apps/web/src/app/(portal)/modules/[category]/page.tsx` | role-match |
+| `apps/web/src/app/(portal)/marketplace/components/MarketplaceCard.tsx` | component | CRUD | `apps/web/src/app/(portal)/modules/[category]/components/ModuleCard.tsx` | exact |
+| `apps/web/src/app/(portal)/marketplace/components/MarketplaceSearch.tsx` | component | event-driven | (no direct analog) | -- |
+| `apps/web/src/app/(portal)/marketplace/components/CategoryFilter.tsx` | component | event-driven | (no direct analog) | -- |
+| `apps/web/src/app/(portal)/marketplace/components/StatusFilter.tsx` | component | event-driven | (no direct analog) | -- |
+| `apps/web/src/app/(portal)/marketplace/components/TenantContextSelector.tsx` | component | request-response | `apps/web/src/app/(portal)/admin/tenants/page.tsx` | partial |
+| `apps/web/src/app/(portal)/marketplace/components/ActivationDialog.tsx` | component | event-driven | `apps/web/src/app/(portal)/admin/tenants/page.tsx` (delete confirm modal) | role-match |
+| `apps/web/src/app/(portal)/marketplace/components/Toast.tsx` | component | event-driven | (no direct analog) | -- |
+| `apps/web/src/lib/stores/marketplace-store.ts` | store | event-driven | `apps/web/src/lib/stores/sidebar-store.ts` | role-match |
+| `apps/web/src/components/layout/sidebar.tsx` | component (MODIFY) | request-response | self | exact |
+| `apps/web/src/components/layout/sidebar-search.tsx` | component | event-driven | (no direct analog) | -- |
+
+## Pattern Assignments
+
+### `apps/web/src/app/(portal)/marketplace/page.tsx` (page, request-response)
+
+**Analog:** `apps/web/src/app/(portal)/admin/modules/page.tsx`
+
+**Imports pattern** (lines 1-6):
+```typescript
+'use client';
+
+import { useCallback, useEffect, useState } from 'react';
+import { useTranslations } from 'next-intl';
+import { useAuthStore } from '@/lib/stores/auth-store';
+```
+
+**API fetch pattern** (lines 39-64) -- parallel fetch of all modules + active modules, building activation map:
+```typescript
+const fetchModules = useCallback(async () => {
+  try {
+    const [allRes, activeRes] = await Promise.all([
+      fetch(`${API_URL}/modules`, { credentials: 'include' }),
+      fetch(`${API_URL}/modules/active`, { credentials: 'include' }),
+    ]);
+
+    if (allRes.ok) {
+      const allModules: Module[] = await allRes.json();
+      setModules(allModules);
+    }
+
+    if (activeRes.ok) {
+      const activeModules: (Module & { activations?: TenantActivation[] })[] = await activeRes.json();
+      const map = new Map<string, boolean>();
+      for (const mod of activeModules) {
+        map.set(mod.id, true);
+      }
+      setActivations(map);
+    }
+  } catch {
+    // silently fail
+  } finally {
+    setLoading(false);
+  }
+}, []);
+```
+
+**Toggle activation pattern** (lines 74-103):
+```typescript
+const toggleModule = async (moduleId: string, currentlyActive: boolean) => {
+  setToggling(moduleId);
+  setError(null);
+  try {
+    const action = currentlyActive ? 'deactivate' : 'activate';
+    const res = await fetch(`${API_URL}/modules/${moduleId}/${action}`, {
+      method: 'POST',
+      credentials: 'include',
+    });
+
+    if (res.ok) {
+      setActivations((prev) => {
+        const next = new Map(prev);
+        if (currentlyActive) {
+          next.delete(moduleId);
+        } else {
+          next.set(moduleId, true);
+        }
+        return next;
+      });
+    } else {
+      const body = await res.text().catch(() => '');
+      setError(`${res.status}: ${body}`);
+    }
+  } catch (err) {
+    setError(String(err));
+  } finally {
+    setToggling(null);
+  }
+};
+```
+
+**Role-gated access pattern** (lines 37, 110-116):
+```typescript
+const isAdmin = currentUser?.role === 'ADMIN' || currentUser?.role === 'SUPER_ADMIN';
+
+if (!isAdmin) {
+  return (
+    <div className="flex items-center justify-center min-h-[60vh]">
+      <p className="text-lg text-muted-foreground">{tCommon('accessDenied')}</p>
+    </div>
+  );
+}
+```
+
+**Error display pattern** (lines 126-129):
+```typescript
+{error && (
+  <div className="rounded-md border border-destructive/50 bg-destructive/10 p-3 text-sm text-destructive">
+    {error}
+  </div>
+)}
+```
+
+**Page layout pattern** (lines 118-124):
+```typescript
+<div className="space-y-6">
+  <div>
+    <h1 className="text-2xl font-bold text-foreground">{t('title')}</h1>
+    <p className="mt-1 text-sm text-muted-foreground">{t('description')}</p>
+  </div>
+  {/* content */}
+</div>
+```
+
+---
+
+### `apps/web/src/app/(portal)/marketplace/[slug]/page.tsx` (detail page, request-response)
+
+**Analog:** `apps/web/src/app/(portal)/modules/[category]/page.tsx`
+
+**Dynamic params pattern** (lines 1-5):
+```typescript
+'use client';
+
+import { useTranslations } from 'next-intl';
+import { useParams } from 'next/navigation';
+import { useEffect, useState } from 'react';
+```
+
+**Loading + empty state pattern** (lines 104-143):
+```typescript
+{isLoading && (
+  <div className="flex items-center justify-center py-12">
+    <div className="h-8 w-8 animate-spin rounded-full border-4 border-primary border-t-transparent" />
+  </div>
+)}
+
+{!isLoading && modules.length === 0 && (
+  <div className="flex flex-col items-center justify-center py-16 text-center">
+    <div className="rounded-lg bg-muted p-4 mb-4">
+      {/* SVG icon */}
+    </div>
+    <p className="text-lg text-muted-foreground">{t('noModules')}</p>
+  </div>
+)}
+```
+
+---
+
+### `apps/web/src/app/(portal)/marketplace/components/MarketplaceCard.tsx` (component, CRUD)
+
+**Analog:** `apps/web/src/app/(portal)/modules/[category]/components/ModuleCard.tsx`
+
+**Card structure pattern** (lines 70-107):
+```typescript
+export function ModuleCard({ name, slug, description, icon, category }: ModuleCardProps) {
+  const t = useTranslations('modules');
+  const locale = (typeof window !== 'undefined' && document.documentElement.lang) || 'de';
+  const localizedDescription = description[locale] || description.en || description.de || '';
+
+  return (
+    <Link href={`/modules/${category}/${slug}`} className="group block">
+      <div className="rounded-lg border border-border bg-card p-5 shadow-sm transition-all hover:shadow-md hover:border-primary/30 group-focus-visible:ring-2 group-focus-visible:ring-ring group-focus-visible:ring-offset-2">
+        <div className="flex items-start gap-3 mb-3">
+          <div className="rounded-md bg-muted p-2.5 shrink-0">
+            <ModuleIcon icon={icon} />
+          </div>
+          <div className="min-w-0">
+            <h3 className="font-semibold text-base leading-tight truncate">{name}</h3>
+          </div>
+        </div>
+        <p className="text-sm text-muted-foreground line-clamp-2 mb-4">{localizedDescription}</p>
+      </div>
+    </Link>
+  );
+}
+```
+
+**Locale extraction pattern** (line 72-73):
+```typescript
+const locale = (typeof window !== 'undefined' && document.documentElement.lang) || 'de';
+const localizedDescription = description[locale] || description.en || description.de || '';
+```
+
+**Responsive grid pattern** (from category page, line 112):
+```typescript
+<div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
+```
+
+---
+
+### `apps/web/src/app/(portal)/marketplace/components/TenantContextSelector.tsx` (component, request-response)
+
+**Analog:** `apps/web/src/app/(portal)/admin/tenants/page.tsx`
+
+**Tenant fetch pattern** (lines 44-57):
+```typescript
+const fetchTenants = useCallback(async () => {
+  try {
+    const res = await fetch(`${API_URL}/tenants`, {
+      credentials: 'include',
+    });
+    if (res.ok) {
+      setTenants(await res.json());
+    }
+  } catch {
+    // silently fail
+  } finally {
+    setLoading(false);
+  }
+}, []);
+```
+
+**Tenant interface** (lines 9-16):
+```typescript
+interface Tenant {
+  id: string;
+  name: string;
+  slug: string;
+  isActive: boolean;
+  createdAt: string;
+  userCount: number;
+}
+```
+
+**Super-Admin guard pattern** (line 42):
+```typescript
+const hasAccess = currentUser?.role === 'SUPER_ADMIN';
+```
+
+---
+
+### `apps/web/src/app/(portal)/marketplace/components/ActivationDialog.tsx` (component, event-driven)
+
+**Analog:** `apps/web/src/app/(portal)/admin/tenants/page.tsx` (delete confirm modal)
+
+**Modal pattern** (lines 301-323):
+```typescript
+{deleteConfirm && (
+  <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50">
+    <div className="w-full max-w-sm rounded-lg border border-border bg-card p-6 shadow-lg">
+      <p className="text-sm text-foreground mb-4">{t('deleteConfirm')}</p>
+      <div className="flex justify-end gap-3">
+        <button
+          onClick={() => setDeleteConfirm(null)}
+          className="rounded-md border border-border px-4 py-2 text-sm text-foreground hover:bg-muted transition-colors"
+        >
+          {tCommon('cancel')}
+        </button>
+        <button
+          onClick={() => handleDelete(deleteConfirm)}
+          className="rounded-md bg-destructive px-4 py-2 text-sm font-medium text-destructive-foreground hover:opacity-90 transition-opacity"
+        >
+          {tCommon('delete')}
+        </button>
+      </div>
+    </div>
+  </div>
+)}
+```
+
+---
+
+### `apps/web/src/lib/stores/marketplace-store.ts` (store, event-driven)
+
+**Analog:** `apps/web/src/lib/stores/sidebar-store.ts`
+
+**Zustand store pattern** (lines 1-21):
+```typescript
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+
+interface SidebarState {
+  isCollapsed: boolean;
+  isMobileOpen: boolean;
+  toggle: () => void;
+  setMobileOpen: (open: boolean) => void;
+}
+
+export const useSidebarStore = create<SidebarState>()(
+  persist(
+    (set) => ({
+      isCollapsed: false,
+      isMobileOpen: false,
+      toggle: () => set((state) => ({ isCollapsed: !state.isCollapsed })),
+      setMobileOpen: (open) => set({ isMobileOpen: open }),
+    }),
+    { name: 'tessera-sidebar' }
+  )
+);
+```
+
+**Non-persisted store pattern** (from auth-store, lines 22-26):
+```typescript
+export const useAuthStore = create<AuthState>()((set) => ({
+  user: null,
+  setUser: (user) => set({ user }),
+  clearUser: () => set({ user: null }),
+}));
+```
+
+---
+
+### `apps/web/src/components/layout/sidebar.tsx` (MODIFY -- add search, Link, usePathname)
+
+**Self-analog.** Key modification points:
+
+**Replace `<a>` with `<Link>`** -- current pattern (lines 54-56, 81-82, etc.):
+```typescript
+// CURRENT (replace all instances):
+<a href="/" className="...">
+// REPLACE WITH:
+<Link href="/" className="...">
+```
+
+**Add usePathname for active state** -- insert after existing imports:
+```typescript
+import { usePathname } from 'next/navigation';
+import Link from 'next/link';
+
+// Inside component:
+const pathname = usePathname();
+const isActive = (href: string) => {
+  if (href === '/') return pathname === '/';
+  return pathname.startsWith(href);
+};
+```
+
+**Sidebar link CSS classes** -- current active pattern (line 57):
+```typescript
+// Active: 'bg-sidebar-accent text-sidebar-accent-foreground font-medium'
+// Inactive: 'text-sidebar-foreground hover:bg-muted'
+```
+
+**Categories accordion structure** (lines 106-176) -- extend with SidebarSearch component insertion point before the accordion.
+
+**Module items in categories** (lines 156-165) -- already renders per-module links under each category. These `<a>` tags need `<Link>` replacement.
+
+---
+
+## Shared Patterns
+
+### API Fetch Convention
+**Source:** All page components
+**Apply to:** All new page/component files that fetch data
+```typescript
+const API_URL = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3001';
+
+// Always use credentials: 'include' for cookie-based auth
+fetch(`${API_URL}/endpoint`, { credentials: 'include' });
+
+// For Super-Admin tenant context, add x-tenant-id header:
+headers: selectedTenantId ? { 'x-tenant-id': selectedTenantId } : {}
+```
+
+### Translations Convention
+**Source:** All components
+**Apply to:** All new components
+```typescript
+import { useTranslations } from 'next-intl';
+const t = useTranslations('marketplace');  // namespace key
+const tCommon = useTranslations('common');
+```
+
+### CSS Token Convention
+**Source:** All components
+**Apply to:** All new components
+```
+// Semantic color tokens (NOT raw colors):
+text-foreground, text-muted-foreground, bg-card, bg-muted, border-border,
+bg-primary, text-primary-foreground, bg-destructive, text-destructive,
+bg-sidebar, text-sidebar-foreground, bg-sidebar-accent, text-sidebar-accent-foreground
+
+// Status colors (only exception to semantic tokens):
+// Active: 'text-green-600 dark:text-green-400' or 'bg-green-100 text-green-700 dark:bg-green-900/30 dark:text-green-400'
+```
+
+### Role Check Convention
+**Source:** `auth-store.ts` + all admin pages
+**Apply to:** TenantContextSelector, marketplace activation controls
+```typescript
+const currentUser = useAuthStore((s) => s.user);
+const isAdmin = currentUser?.role === 'ADMIN' || currentUser?.role === 'SUPER_ADMIN';
+const isSuperAdmin = currentUser?.role === 'SUPER_ADMIN';
+```
+
+## No Analog Found
+
+| File | Role | Data Flow | Reason |
+|------|------|-----------|--------|
+| `MarketplaceSearch.tsx` | component | event-driven | No search input components exist yet. Use standard `<input>` with debounced `onChange` + project CSS conventions from form inputs in tenants page (line 259: `flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm`). |
+| `CategoryFilter.tsx` | component | event-driven | No chip/filter-row components exist. Build as horizontal button row using badge styling from admin/modules (line 157-159: `rounded-full bg-muted px-2 py-0.5 text-xs text-muted-foreground`). |
+| `StatusFilter.tsx` | component | event-driven | No tab-bar components exist. Build as segmented button row following same badge/button conventions. |
+| `Toast.tsx` | component | event-driven | No toast system exists. Build with Zustand store pattern (see RESEARCH.md Pattern 4). |
+| `sidebar-search.tsx` | component | event-driven | No sidebar search exists. Use input styling from tenants page form fields. |
+
+## Metadata
+
+**Analog search scope:** `apps/web/src/`
+**Files scanned:** 30 source files (excluding node_modules, .next, dist)
+**Pattern extraction date:** 2026-06-22
@@ -0,0 +1,81 @@
+---
+phase: 04
+slug: marketplace-portal-navigation
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: 2026-06-22
+---
+
+# Phase 04 — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | vitest |
+| **Config file** | apps/web/vitest.config.ts, apps/api/vitest.config.ts |
+| **Quick run command** | `pnpm --filter @tessera/api test -- --run` |
+| **Full suite command** | `pnpm test` |
+| **Estimated runtime** | ~30 seconds |
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run `pnpm --filter @tessera/api test -- --run`
+- **After every plan wave:** Run `pnpm test`
+- **Before `/gsd-verify-work`:** Full suite must be green
+- **Max feedback latency:** 30 seconds
+
+---
+
+## Per-Task Verification Map
+
+| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
+|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------|
+| 04-01-01 | 01 | 1 | MRKT-01 | — | N/A | integration | `pnpm --filter @tessera/api test` | ❌ W0 | ⬜ pending |
+| 04-01-02 | 01 | 1 | MRKT-02 | T-04-01 | Admin-only activation | integration | `pnpm --filter @tessera/api test` | ❌ W0 | ⬜ pending |
+| 04-02-01 | 02 | 1 | PRTAL-02 | — | N/A | e2e | browser check | ❌ W0 | ⬜ pending |
+| 04-02-02 | 02 | 1 | PRTAL-03 | — | N/A | e2e | browser check | ❌ W0 | ⬜ pending |
+| 04-02-03 | 02 | 1 | PRTAL-05 | — | N/A | e2e | browser check | ❌ W0 | ⬜ pending |
+| 04-03-01 | 03 | 2 | MRKT-03 | — | N/A | integration | `pnpm --filter @tessera/api test` | ❌ W0 | ⬜ pending |
+| 04-03-02 | 03 | 2 | MRKT-04 | — | N/A | e2e | browser check | ❌ W0 | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+---
+
+## Wave 0 Requirements
+
+- [ ] Test stubs for marketplace API endpoints
+- [ ] Test stubs for sidebar navigation behavior
+
+*Existing infrastructure covers framework setup — only test files needed.*
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| Marketplace grid layout responsive | MRKT-01 | Visual layout check | Open marketplace at 320px, 768px, 1024px widths |
+| Sidebar module grouping by category | PRTAL-02 | Visual grouping check | Activate modules from different categories, verify sidebar groups |
+| Module opens in main content area | PRTAL-03 | Navigation flow | Click module in sidebar, verify content renders in main area |
+
+---
+
+## Validation Sign-Off
+
+- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
+- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
+- [ ] Wave 0 covers all MISSING references
+- [ ] No watch-mode flags
+- [ ] Feedback latency < 30s
+- [ ] `nyquist_compliant: true` set in frontmatter
+
+**Approval:** pending