diff --git a/cannamanage-frontend/e2e/test-results/authenticated-tour-Authent-9bae5--screenshot-all-admin-pages-chromium/test-finished-1.png b/cannamanage-frontend/e2e/test-results/authenticated-tour-Authent-9bae5--screenshot-all-admin-pages-chromium/test-finished-1.png new file mode 100644 index 0000000..6bdb204 Binary files /dev/null and b/cannamanage-frontend/e2e/test-results/authenticated-tour-Authent-9bae5--screenshot-all-admin-pages-chromium/test-finished-1.png differ diff --git a/cannamanage-frontend/messages/de.json b/cannamanage-frontend/messages/de.json index 460eafb..7923ac6 100644 --- a/cannamanage-frontend/messages/de.json +++ b/cannamanage-frontend/messages/de.json @@ -292,5 +292,17 @@ "allMonths": "Alle Monate", "footerText": "Cannabis-Anbauverein — Sichere Mitgliederverwaltung", "adminLogin": "Zum Admin-Login" + }, + "api": { + "loading": "Wird geladen...", + "error": "Fehler beim Laden der Daten.", + "retry": "Erneut versuchen", + "offline": "Keine Verbindung zum Server — Daten könnten veraltet sein.", + "networkError": "Netzwerkfehler. Bitte prüfe deine Verbindung.", + "unauthorized": "Sitzung abgelaufen. Bitte erneut anmelden.", + "forbidden": "Keine Berechtigung für diese Aktion.", + "notFound": "Ressource nicht gefunden.", + "quotaExceeded": "Kontingent überschritten.", + "serverError": "Serverfehler. Bitte versuche es später erneut." } } diff --git a/cannamanage-frontend/messages/en.json b/cannamanage-frontend/messages/en.json index 3218f21..8ffe64b 100644 --- a/cannamanage-frontend/messages/en.json +++ b/cannamanage-frontend/messages/en.json @@ -292,5 +292,17 @@ "allMonths": "All months", "footerText": "Cannabis cultivation club — Secure member management", "adminLogin": "Go to Admin Login" + }, + "api": { + "loading": "Loading...", + "error": "Failed to load data.", + "retry": "Try again", + "offline": "No connection to server — data may be outdated.", + "networkError": "Network error. Please check your connection.", + "unauthorized": "Session expired. Please sign in again.", + "forbidden": "You do not have permission for this action.", + "notFound": "Resource not found.", + "quotaExceeded": "Quota exceeded.", + "serverError": "Server error. Please try again later." } } diff --git a/cannamanage-frontend/package.json b/cannamanage-frontend/package.json index 1247706..09c103f 100644 --- a/cannamanage-frontend/package.json +++ b/cannamanage-frontend/package.json @@ -36,6 +36,7 @@ "@radix-ui/react-slot": "1.1.1", "@radix-ui/react-toast": "1.2.1", "@radix-ui/react-tooltip": "1.1.5", + "@tanstack/react-query": "^5.101.0", "@tanstack/react-table": "^8.21.3", "class-variance-authority": "0.7.1", "clsx": "2.1.1", diff --git a/cannamanage-frontend/pnpm-lock.yaml b/cannamanage-frontend/pnpm-lock.yaml index 6209c85..6ec7e99 100644 --- a/cannamanage-frontend/pnpm-lock.yaml +++ b/cannamanage-frontend/pnpm-lock.yaml @@ -53,6 +53,9 @@ importers: '@radix-ui/react-tooltip': specifier: 1.1.5 version: 1.1.5(@types/react-dom@19.0.4(@types/react@19.0.12))(@types/react@19.0.12)(react-dom@19.1.3(react@19.1.3))(react@19.1.3) + '@tanstack/react-query': + specifier: ^5.101.0 + version: 5.101.0(react@19.1.3) '@tanstack/react-table': specifier: ^8.21.3 version: 8.21.3(react-dom@19.1.3(react@19.1.3))(react@19.1.3) @@ -1642,6 +1645,14 @@ packages: peerDependencies: tailwindcss: '>=3.0.0 || insiders || >=4.0.0-alpha.20' + '@tanstack/query-core@5.101.0': + resolution: {integrity: sha512-cQetA74EB+seWySv1TTKr828TnP0u39m6LykwDXIo84SNortpDkp30TMEjkqtYCNP9c40uT/iwl6MLiufEt0Ow==} + + '@tanstack/react-query@5.101.0': + resolution: {integrity: sha512-rLlJXSpkqfizLWgkR5+eLeIk0MvTx/meEIR7LRjxic+qxiQP8zVjq7BqQkiCMNLQBlLfuOLqqr6KO5GtrDlmSg==} + peerDependencies: + react: ^18 || ^19 + '@tanstack/react-table@8.21.3': resolution: {integrity: sha512-5nNMTSETP4ykGegmVkhjcS8tTLW6Vl4axfEGQN3v0zdHYbK4UfoqfPChclTrJ4EoK9QynqAu9oUf8VEmrpZ5Ww==} engines: {node: '>=12'} @@ -4918,6 +4929,13 @@ snapshots: postcss-selector-parser: 6.0.10 tailwindcss: 4.1.3 + '@tanstack/query-core@5.101.0': {} + + '@tanstack/react-query@5.101.0(react@19.1.3)': + dependencies: + '@tanstack/query-core': 5.101.0 + react: 19.1.3 + '@tanstack/react-table@8.21.3(react-dom@19.1.3(react@19.1.3))(react@19.1.3)': dependencies: '@tanstack/table-core': 8.21.3 diff --git a/cannamanage-frontend/src/components/api-error-boundary.tsx b/cannamanage-frontend/src/components/api-error-boundary.tsx new file mode 100644 index 0000000..f318f5b --- /dev/null +++ b/cannamanage-frontend/src/components/api-error-boundary.tsx @@ -0,0 +1,75 @@ +"use client" + +import { Component } from "react" +import { AlertCircle, RefreshCw } from "lucide-react" + +import type { ErrorInfo, ReactNode } from "react" + +import { ApiError } from "@/lib/api-client" + +import { Button } from "@/components/ui/button" +import { Card, CardContent } from "@/components/ui/card" + +interface ApiErrorBoundaryProps { + children: ReactNode + fallbackMessage?: string +} + +interface ApiErrorBoundaryState { + hasError: boolean + error: Error | null +} + +export class ApiErrorBoundary extends Component< + ApiErrorBoundaryProps, + ApiErrorBoundaryState +> { + constructor(props: ApiErrorBoundaryProps) { + super(props) + this.state = { hasError: false, error: null } + } + + static getDerivedStateFromError(error: Error): ApiErrorBoundaryState { + return { hasError: true, error } + } + + componentDidCatch(error: Error, errorInfo: ErrorInfo) { + console.error("[ApiErrorBoundary]", error, errorInfo) + } + + handleRetry = () => { + this.setState({ hasError: false, error: null }) + } + + render() { + if (this.state.hasError) { + const error = this.state.error + const isApiError = error instanceof ApiError + const message = isApiError + ? error.message + : this.props.fallbackMessage || "An unexpected error occurred." + + return ( + + + +
+

{message}

+ {isApiError && error.code !== "NETWORK_ERROR" && ( +

+ Code: {error.code} (HTTP {error.status}) +

+ )} +
+ + + + ) + } + + return this.props.children + } +} diff --git a/cannamanage-frontend/src/components/offline-banner.tsx b/cannamanage-frontend/src/components/offline-banner.tsx new file mode 100644 index 0000000..88497e7 --- /dev/null +++ b/cannamanage-frontend/src/components/offline-banner.tsx @@ -0,0 +1,46 @@ +"use client" + +import { useEffect, useState } from "react" +import { onlineManager } from "@tanstack/react-query" +import { useTranslations } from "next-intl" +import { WifiOff } from "lucide-react" + +import type { ReactNode } from "react" + +export function OfflineBanner() { + const t = useTranslations("api") + const [isOnline, setIsOnline] = useState(true) + + useEffect(() => { + // Subscribe to online manager state changes + const unsubscribe = onlineManager.subscribe((online) => { + setIsOnline(online) + }) + // Set initial state + setIsOnline(onlineManager.isOnline()) + return () => unsubscribe() + }, []) + + if (isOnline) return null + + return ( +
+ + {t("offline")} +
+ ) +} + +/** + * Wrapper that prevents hydration mismatch for online/offline state. + */ +export function OfflineBannerWrapper({ children }: { children: ReactNode }) { + const [mounted, setMounted] = useState(false) + useEffect(() => setMounted(true), []) + if (!mounted) return null + return <>{children} +} diff --git a/cannamanage-frontend/src/components/ui/data-skeleton.tsx b/cannamanage-frontend/src/components/ui/data-skeleton.tsx new file mode 100644 index 0000000..3f4b30b --- /dev/null +++ b/cannamanage-frontend/src/components/ui/data-skeleton.tsx @@ -0,0 +1,82 @@ +import { Skeleton } from "@/components/ui/skeleton" + +/** + * Skeleton for KPI stat cards on the dashboard. + */ +export function CardSkeleton() { + return ( +
+ + + +
+ ) +} + +/** + * Skeleton for a data table (header + rows). + */ +export function TableSkeleton({ + rows = 5, + columns = 4, +}: { + rows?: number + columns?: number +}) { + return ( +
+ {/* Header */} +
+ {Array.from({ length: columns }).map((_, i) => ( + + ))} +
+ {/* Rows */} + {Array.from({ length: rows }).map((_, rowIdx) => ( +
+ {Array.from({ length: columns }).map((_, colIdx) => ( + + ))} +
+ ))} +
+ ) +} + +/** + * Skeleton for chart / Recharts areas. + */ +export function ChartSkeleton() { + return ( +
+ + +
+ ) +} + +/** + * Skeleton for a single form field. + */ +export function FormFieldSkeleton() { + return ( +
+ + +
+ ) +} + +/** + * Grid of card skeletons for the dashboard. + */ +export function DashboardSkeleton() { + return ( +
+ + + + +
+ ) +} diff --git a/cannamanage-frontend/src/lib/api-client.ts b/cannamanage-frontend/src/lib/api-client.ts new file mode 100644 index 0000000..2d63817 --- /dev/null +++ b/cannamanage-frontend/src/lib/api-client.ts @@ -0,0 +1,193 @@ +/** + * Typed fetch wrapper for the CannaManage API. + * + * Routes through the Next.js rewrite proxy: + * /api/backend/... → BACKEND_URL/api/v1/... + */ + +export class ApiError extends Error { + constructor( + public status: number, + public code: string, + message: string + ) { + super(message) + this.name = "ApiError" + } + + /** True for 401/403 — session likely expired or insufficient permissions */ + get isAuthError(): boolean { + return this.status === 401 || this.status === 403 + } + + /** True for 5xx — server-side failure */ + get isServerError(): boolean { + return this.status >= 500 + } + + /** True for network failures (status 0) */ + get isNetworkError(): boolean { + return this.status === 0 + } +} + +export interface ApiClientOptions extends Omit { + token?: string + body?: unknown + params?: Record +} + +/** + * Core fetch wrapper that targets the Next.js rewrite proxy. + * + * @param endpoint - API path without the prefix, e.g. `/members` or `/members/123` + * @param options - Fetch options + optional token and typed body + * @returns Parsed JSON response of type T + * @throws ApiError on non-2xx responses + */ +export async function apiClient( + endpoint: string, + options: ApiClientOptions = {} +): Promise { + const { + token, + body, + params, + headers: extraHeaders, + ...fetchOptions + } = options + + // Build URL with optional query params + let url = `/api/backend${endpoint}` + if (params) { + const searchParams = new URLSearchParams() + for (const [key, value] of Object.entries(params)) { + if (value !== undefined) { + searchParams.set(key, String(value)) + } + } + const qs = searchParams.toString() + if (qs) url += `?${qs}` + } + + const headers: Record = { + "Content-Type": "application/json", + ...(token && { Authorization: `Bearer ${token}` }), + ...(extraHeaders as Record), + } + + // Don't set Content-Type for GET/HEAD (no body) + const method = (fetchOptions.method || "GET").toUpperCase() + if (method === "GET" || method === "HEAD") { + delete headers["Content-Type"] + } + + try { + const res = await fetch(url, { + ...fetchOptions, + method, + headers, + body: body ? JSON.stringify(body) : undefined, + }) + + if (!res.ok) { + // Try to parse application/problem+json or standard error body + const errorBody = await res.json().catch(() => ({ + code: `HTTP_${res.status}`, + message: res.statusText || "Request failed", + })) + + throw new ApiError( + res.status, + errorBody.code || `HTTP_${res.status}`, + errorBody.message || errorBody.detail || res.statusText + ) + } + + // 204 No Content — return undefined as T + if (res.status === 204) { + return undefined as T + } + + return res.json() as Promise + } catch (error) { + if (error instanceof ApiError) { + throw error + } + // Network errors (fetch throws TypeError for network failures) + throw new ApiError( + 0, + "NETWORK_ERROR", + "Network error — unable to reach the server." + ) + } +} + +/** + * Download a file (PDF, CSV) from the API as a Blob. + * Used for report downloads where we don't parse JSON. + */ +export async function apiDownload( + endpoint: string, + options: ApiClientOptions = {} +): Promise<{ blob: Blob; filename: string }> { + const { + token, + body, + params, + headers: extraHeaders, + ...fetchOptions + } = options + + let url = `/api/backend${endpoint}` + if (params) { + const searchParams = new URLSearchParams() + for (const [key, value] of Object.entries(params)) { + if (value !== undefined) { + searchParams.set(key, String(value)) + } + } + const qs = searchParams.toString() + if (qs) url += `?${qs}` + } + + const headers: Record = { + Accept: "application/octet-stream", + ...(token && { Authorization: `Bearer ${token}` }), + ...(extraHeaders as Record), + } + + try { + const res = await fetch(url, { + ...fetchOptions, + headers, + body: body ? JSON.stringify(body) : undefined, + }) + + if (!res.ok) { + const errorBody = await res.json().catch(() => ({ + code: `HTTP_${res.status}`, + message: res.statusText, + })) + throw new ApiError( + res.status, + errorBody.code || `HTTP_${res.status}`, + errorBody.message || res.statusText + ) + } + + const blob = await res.blob() + const disposition = res.headers.get("Content-Disposition") || "" + const filenameMatch = disposition.match(/filename="?([^";\n]+)"?/) + const filename = filenameMatch?.[1] || "download" + + return { blob, filename } + } catch (error) { + if (error instanceof ApiError) throw error + throw new ApiError( + 0, + "NETWORK_ERROR", + "Network error — unable to reach the server." + ) + } +} diff --git a/cannamanage-frontend/src/providers/index.tsx b/cannamanage-frontend/src/providers/index.tsx index 7928a7b..7734c80 100644 --- a/cannamanage-frontend/src/providers/index.tsx +++ b/cannamanage-frontend/src/providers/index.tsx @@ -1,5 +1,7 @@ "use client" +import { useState } from "react" +import { QueryClient, QueryClientProvider } from "@tanstack/react-query" import { SessionProvider } from "next-auth/react" import type { LocaleType } from "@/types" @@ -17,15 +19,34 @@ export function Providers({ locale: LocaleType children: ReactNode }>) { + const [queryClient] = useState( + () => + new QueryClient({ + defaultOptions: { + queries: { + staleTime: 30 * 1000, + gcTime: 5 * 60 * 1000, + retry: 1, + refetchOnWindowFocus: true, + }, + mutations: { + retry: 0, + }, + }, + }) + ) + return ( - - - - {children} - - - + + + + + {children} + + + + ) } diff --git a/cannamanage-frontend/src/services/dashboard.ts b/cannamanage-frontend/src/services/dashboard.ts new file mode 100644 index 0000000..0b32738 --- /dev/null +++ b/cannamanage-frontend/src/services/dashboard.ts @@ -0,0 +1,25 @@ +import { useQuery } from "@tanstack/react-query" + +import type { ClubStats, Distribution } from "@/types/api" + +import { apiClient } from "@/lib/api-client" + +// --- Query Hooks --- + +export function useClubStatsQuery() { + return useQuery({ + queryKey: ["dashboard", "stats"], + queryFn: () => apiClient("/dashboard/stats"), + refetchInterval: 60 * 1000, // auto-refresh every 60s + }) +} + +export function useRecentDistributionsQuery(limit = 5) { + return useQuery({ + queryKey: ["dashboard", "recent-distributions", limit], + queryFn: () => + apiClient("/distributions/recent", { + params: { limit }, + }), + }) +} diff --git a/cannamanage-frontend/src/services/distributions.ts b/cannamanage-frontend/src/services/distributions.ts new file mode 100644 index 0000000..b4245bb --- /dev/null +++ b/cannamanage-frontend/src/services/distributions.ts @@ -0,0 +1,97 @@ +import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query" + +import type { + AvailableBatch, + Distribution, + DistributionRecord, + QuotaStatus, +} from "@/types/api" + +import { apiClient } from "@/lib/api-client" + +// --- Types --- + +export interface DistributionsPage { + content: DistributionRecord[] + totalElements: number + totalPages: number + number: number + size: number +} + +export interface CreateDistributionRequest { + memberId: string + batchId: string + amountGrams: number +} + +// --- Query Hooks --- + +export function useDistributionsQuery(params?: { + page?: number + size?: number + memberId?: string + from?: string + to?: string +}) { + return useQuery({ + queryKey: ["distributions", params], + queryFn: () => + apiClient("/distributions", { + params: { + page: params?.page, + size: params?.size ?? 20, + memberId: params?.memberId || undefined, + from: params?.from || undefined, + to: params?.to || undefined, + }, + }), + }) +} + +export function useRecentDistributionsQuery(limit = 5) { + return useQuery({ + queryKey: ["distributions", "recent", limit], + queryFn: () => + apiClient("/distributions/recent", { + params: { limit }, + }), + }) +} + +export function useQuotaQuery(memberId: string) { + return useQuery({ + queryKey: ["members", memberId, "quota"], + queryFn: () => apiClient(`/members/${memberId}/quota`), + enabled: !!memberId, + }) +} + +export function useAvailableBatchesQuery() { + return useQuery({ + queryKey: ["batches", "available"], + queryFn: () => apiClient("/batches/available"), + }) +} + +// --- Mutation Hooks --- + +export function useCreateDistributionMutation() { + const queryClient = useQueryClient() + return useMutation({ + mutationFn: (data: CreateDistributionRequest) => + apiClient("/distributions", { + method: "POST", + body: data, + }), + onSuccess: (_data, variables) => { + // Invalidate distribution list + member quota + queryClient.invalidateQueries({ queryKey: ["distributions"] }) + queryClient.invalidateQueries({ + queryKey: ["members", variables.memberId, "quota"], + }) + queryClient.invalidateQueries({ queryKey: ["batches"] }) + queryClient.invalidateQueries({ queryKey: ["dashboard"] }) + }, + }) +} diff --git a/cannamanage-frontend/src/services/members.ts b/cannamanage-frontend/src/services/members.ts new file mode 100644 index 0000000..3d57047 --- /dev/null +++ b/cannamanage-frontend/src/services/members.ts @@ -0,0 +1,102 @@ +import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query" + +import type { Member, QuotaStatus } from "@/types/api" + +import { apiClient } from "@/lib/api-client" + +// --- Types --- + +export interface MembersPage { + content: Member[] + totalElements: number + totalPages: number + number: number + size: number +} + +export interface CreateMemberRequest { + firstName: string + lastName: string + email: string + dateOfBirth: string + phone?: string + notes?: string +} + +export interface UpdateMemberRequest extends Partial { + status?: "ACTIVE" | "SUSPENDED" | "EXPELLED" +} + +// --- Query Hooks --- + +export function useMembersQuery(params?: { + page?: number + size?: number + search?: string + status?: string +}) { + return useQuery({ + queryKey: ["members", params], + queryFn: () => + apiClient("/members", { + params: { + page: params?.page, + size: params?.size ?? 20, + search: params?.search || undefined, + status: params?.status || undefined, + }, + }), + }) +} + +export function useMemberQuery(id: string) { + return useQuery({ + queryKey: ["members", id], + queryFn: () => apiClient(`/members/${id}`), + enabled: !!id, + }) +} + +export function useMemberQuotaQuery(id: string) { + return useQuery({ + queryKey: ["members", id, "quota"], + queryFn: () => apiClient(`/members/${id}/quota`), + enabled: !!id, + }) +} + +// --- Mutation Hooks --- + +export function useCreateMemberMutation() { + const queryClient = useQueryClient() + return useMutation({ + mutationFn: (data: CreateMemberRequest) => + apiClient("/members", { method: "POST", body: data }), + onSuccess: () => { + queryClient.invalidateQueries({ queryKey: ["members"] }) + }, + }) +} + +export function useUpdateMemberMutation(id: string) { + const queryClient = useQueryClient() + return useMutation({ + mutationFn: (data: UpdateMemberRequest) => + apiClient(`/members/${id}`, { method: "PUT", body: data }), + onSuccess: () => { + queryClient.invalidateQueries({ queryKey: ["members"] }) + queryClient.invalidateQueries({ queryKey: ["members", id] }) + }, + }) +} + +export function useDeleteMemberMutation() { + const queryClient = useQueryClient() + return useMutation({ + mutationFn: (id: string) => + apiClient(`/members/${id}`, { method: "DELETE" }), + onSuccess: () => { + queryClient.invalidateQueries({ queryKey: ["members"] }) + }, + }) +} diff --git a/cannamanage-frontend/src/services/portal.ts b/cannamanage-frontend/src/services/portal.ts new file mode 100644 index 0000000..b76698c --- /dev/null +++ b/cannamanage-frontend/src/services/portal.ts @@ -0,0 +1,83 @@ +import { useQuery } from "@tanstack/react-query" + +import { apiClient } from "@/lib/api-client" + +// --- Types --- + +export interface PortalDashboardData { + memberName: string + memberNumber: string + quotaStatus: { + dailyUsedGrams: number + dailyLimitGrams: number + monthlyUsedGrams: number + monthlyLimitGrams: number + isUnder21: boolean + } + lastDistribution?: { + strainName: string + amountGrams: number + recordedAt: string + } +} + +export interface PortalHistoryEntry { + id: string + strainName: string + amountGrams: number + recordedAt: string +} + +export interface PortalHistoryPage { + content: PortalHistoryEntry[] + totalElements: number + totalPages: number + number: number + size: number +} + +export interface PortalProfileData { + firstName: string + lastName: string + email: string + phone?: string + dateOfBirth: string + memberNumber: string + memberSince: string + status: "ACTIVE" | "SUSPENDED" | "EXPELLED" +} + +// --- Query Hooks --- + +export function usePortalDashboardQuery() { + return useQuery({ + queryKey: ["portal", "dashboard"], + queryFn: () => apiClient("/portal/dashboard"), + }) +} + +export function usePortalHistoryQuery(params?: { + page?: number + size?: number + month?: string +}) { + return useQuery({ + queryKey: ["portal", "history", params], + queryFn: () => + apiClient("/portal/history", { + params: { + page: params?.page, + size: params?.size ?? 20, + month: params?.month || undefined, + }, + }), + }) +} + +export function usePortalProfileQuery() { + return useQuery({ + queryKey: ["portal", "profile"], + queryFn: () => apiClient("/portal/profile"), + staleTime: 5 * 60 * 1000, // profile rarely changes + }) +} diff --git a/cannamanage-frontend/src/services/reports.ts b/cannamanage-frontend/src/services/reports.ts new file mode 100644 index 0000000..b25de97 --- /dev/null +++ b/cannamanage-frontend/src/services/reports.ts @@ -0,0 +1,113 @@ +import { useQuery } from "@tanstack/react-query" + +import { apiClient, apiDownload } from "@/lib/api-client" + +// --- Types --- + +export interface MonthlyReportData { + month: string // YYYY-MM + totalDistributions: number + totalGrams: number + uniqueMembers: number + averagePerDistribution: number + topStrains: { name: string; grams: number }[] +} + +export interface MemberListReportData { + totalMembers: number + activeMembers: number + suspendedMembers: number + expelledMembers: number + members: { id: string; name: string; status: string; joinedAt: string }[] +} + +export interface RecallReportData { + totalRecalls: number + batches: { + id: string + strainName: string + recalledAt: string + reason: string + gramsAffected: number + }[] +} + +// --- Query Hooks (preview data) --- + +export function useMonthlyReportQuery(month?: string) { + return useQuery({ + queryKey: ["reports", "monthly", month], + queryFn: () => + apiClient("/reports/monthly", { + params: { month: month || undefined }, + }), + enabled: !!month, + }) +} + +export function useMemberListReportQuery(status?: string) { + return useQuery({ + queryKey: ["reports", "member-list", status], + queryFn: () => + apiClient("/reports/member-list", { + params: { status: status || undefined }, + }), + }) +} + +export function useRecallReportQuery(dateRange?: { from: string; to: string }) { + return useQuery({ + queryKey: ["reports", "recalls", dateRange], + queryFn: () => + apiClient("/reports/recalls", { + params: { + from: dateRange?.from, + to: dateRange?.to, + }, + }), + enabled: !!dateRange, + }) +} + +// --- Download Functions (imperative, not hooks) --- + +export async function downloadMonthlyReportPdf(month: string) { + const { blob, filename } = await apiDownload("/reports/monthly/pdf", { + params: { month }, + }) + triggerDownload(blob, filename || `monthly-report-${month}.pdf`) +} + +export async function downloadMonthlyReportCsv(month: string) { + const { blob, filename } = await apiDownload("/reports/monthly/csv", { + params: { month }, + }) + triggerDownload(blob, filename || `monthly-report-${month}.csv`) +} + +export async function downloadMemberListPdf(status?: string) { + const { blob, filename } = await apiDownload("/reports/member-list/pdf", { + params: { status: status || undefined }, + }) + triggerDownload(blob, filename || "member-list.pdf") +} + +export async function downloadRecallReportPdf(from: string, to: string) { + const { blob, filename } = await apiDownload("/reports/recalls/pdf", { + params: { from, to }, + }) + triggerDownload(blob, filename || `recall-report-${from}-${to}.pdf`) +} + +// --- Helpers --- + +function triggerDownload(blob: Blob, filename: string) { + const url = URL.createObjectURL(blob) + const a = document.createElement("a") + a.href = url + a.download = filename + document.body.appendChild(a) + a.click() + document.body.removeChild(a) + URL.revokeObjectURL(url) +} diff --git a/cannamanage-frontend/src/services/staff.ts b/cannamanage-frontend/src/services/staff.ts new file mode 100644 index 0000000..721c356 --- /dev/null +++ b/cannamanage-frontend/src/services/staff.ts @@ -0,0 +1,75 @@ +import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query" + +import { apiClient } from "@/lib/api-client" + +// --- Types --- + +export interface StaffMember { + id: string + email: string + displayName: string + role: "ADMIN" | "MANAGER" | "STAFF" + permissions: string[] + status: "ACTIVE" | "INVITED" | "REVOKED" + lastLoginAt?: string + createdAt: string +} + +export interface InviteStaffRequest { + email: string + displayName: string + role: "ADMIN" | "MANAGER" | "STAFF" + permissions: string[] +} + +export interface UpdateStaffPermissionsRequest { + role?: "ADMIN" | "MANAGER" | "STAFF" + permissions?: string[] +} + +// --- Query Hooks --- + +export function useStaffListQuery() { + return useQuery({ + queryKey: ["staff"], + queryFn: () => apiClient("/staff"), + }) +} + +// --- Mutation Hooks --- + +export function useInviteStaffMutation() { + const queryClient = useQueryClient() + return useMutation({ + mutationFn: (data: InviteStaffRequest) => + apiClient("/staff/invite", { method: "POST", body: data }), + onSuccess: () => { + queryClient.invalidateQueries({ queryKey: ["staff"] }) + }, + }) +} + +export function useUpdateStaffPermissionsMutation(id: string) { + const queryClient = useQueryClient() + return useMutation({ + mutationFn: (data: UpdateStaffPermissionsRequest) => + apiClient(`/staff/${id}/permissions`, { + method: "PUT", + body: data, + }), + onSuccess: () => { + queryClient.invalidateQueries({ queryKey: ["staff"] }) + }, + }) +} + +export function useRevokeStaffMutation() { + const queryClient = useQueryClient() + return useMutation({ + mutationFn: (id: string) => + apiClient(`/staff/${id}/revoke`, { method: "POST" }), + onSuccess: () => { + queryClient.invalidateQueries({ queryKey: ["staff"] }) + }, + }) +} diff --git a/cannamanage-frontend/src/services/stock.ts b/cannamanage-frontend/src/services/stock.ts new file mode 100644 index 0000000..8e47e92 --- /dev/null +++ b/cannamanage-frontend/src/services/stock.ts @@ -0,0 +1,95 @@ +import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query" + +import type { Batch, BatchSummary, Strain } from "@/types/api" + +import { apiClient } from "@/lib/api-client" + +// --- Types --- + +export interface BatchesPage { + content: Batch[] + totalElements: number + totalPages: number + number: number + size: number +} + +export interface CreateBatchRequest { + strainName: string + thcPercent: number + cbdPercent: number + totalGrams: number + supplier: string + harvestDate: string + notes?: string +} + +// --- Query Hooks --- + +export function useBatchesQuery(params?: { + page?: number + size?: number + status?: string +}) { + return useQuery({ + queryKey: ["batches", params], + queryFn: () => + apiClient("/batches", { + params: { + page: params?.page, + size: params?.size ?? 20, + status: params?.status || undefined, + }, + }), + }) +} + +export function useBatchQuery(id: string) { + return useQuery({ + queryKey: ["batches", id], + queryFn: () => apiClient(`/batches/${id}`), + enabled: !!id, + }) +} + +export function useStrainsQuery() { + return useQuery({ + queryKey: ["strains"], + queryFn: () => apiClient("/strains"), + staleTime: 5 * 60 * 1000, // strains rarely change — 5 min stale + }) +} + +export function useStockSummaryQuery() { + return useQuery({ + queryKey: ["batches", "summary"], + queryFn: () => apiClient("/batches/summary"), + }) +} + +// --- Mutation Hooks --- + +export function useCreateBatchMutation() { + const queryClient = useQueryClient() + return useMutation({ + mutationFn: (data: CreateBatchRequest) => + apiClient("/batches", { method: "POST", body: data }), + onSuccess: () => { + queryClient.invalidateQueries({ queryKey: ["batches"] }) + queryClient.invalidateQueries({ queryKey: ["dashboard"] }) + }, + }) +} + +export function useRecallBatchMutation() { + const queryClient = useQueryClient() + return useMutation({ + mutationFn: (id: string) => + apiClient(`/batches/${id}/recall`, { method: "POST" }), + onSuccess: (_data, id) => { + queryClient.invalidateQueries({ queryKey: ["batches"] }) + queryClient.invalidateQueries({ queryKey: ["batches", id] }) + queryClient.invalidateQueries({ queryKey: ["dashboard"] }) + }, + }) +} diff --git a/docs/sprint-5/cannamanage-sprint5-plan-review.md b/docs/sprint-5/cannamanage-sprint5-plan-review.md new file mode 100644 index 0000000..66c413a --- /dev/null +++ b/docs/sprint-5/cannamanage-sprint5-plan-review.md @@ -0,0 +1,288 @@ +# CannaManage Sprint 5 Plan — Multi-Persona Review Panel + +**Date:** 2026-06-12 +**Reviewed Document:** `docs/sprint-5/cannamanage-sprint5-plan.md` (v2, ~840 lines) +**Review Method:** 6-persona stakeholder simulation, scoring on 4 dimensions (0–100%) +**Iteration:** 1 + +--- + +## v2 Decisions Incorporated + +The Sprint 5 plan v2 incorporates all Q&A decisions from the planning session: + +1. ✅ **@tanstack/react-query** — caching, refetch, optimistic updates (Q1) +2. ✅ **Per-component loading** — independent card/table loading, no full-page blocking (Q2) +3. ✅ **Stale-while-revalidate + "Offline" banner** — graceful degradation (Q3) +4. ✅ **Full CRUD staff management** — list, invite, edit perms, revoke (Q4) +5. ✅ **Dual seed data strategy** — SQL for dev/test + API-driven for system E2E (Q5) +6. ✅ **Next.js 15.2.8 → 15.5.18 upgrade** — addresses 8+ Snyk CVEs in Phase 1 (Bonus) + +--- + +## 1. 👤 Club Member (End User) + +*"I'm a regular member of a cannabis social club. I want to see my quota, pick up my cannabis, and check my history — now with real data instead of fake numbers."* + +### Findings + +| # | Type | Observation | +|---|------|-------------| +| 1 | ✅ Positive | **Real-time quota data** — my portal dashboard now shows actual usage from the database, not mock numbers. I can trust the "28g remaining" display because it's coming from the real backend with server-authoritative calculations. | +| 2 | ✅ Positive | **Stale-while-revalidate** — if my phone briefly loses signal in the club, I still see my last-known quota instead of a blank page. The "Offline" banner is unobtrusive. | +| 3 | ✅ Positive | **Per-component loading** — when I open the portal, I see my quota radial load first (fast), then history loads separately. No frozen full-page spinner. | +| 4 | ✅ Positive | **Distribution history is live** — I can see a distribution appear in my history immediately after the staff records it. No manual refresh needed. | +| 5 | ⚠️ Minor | **No push notification for distributions** — I still won't get notified when a distribution is recorded against my account. I have to check manually. (Acknowledged as Sprint 6+ scope.) | +| 6 | ✅ Positive | **Portal auth is explicitly planned** — Phase 5 specifically calls out wiring the portal login flow with session-based auth. My separate login experience is preserved. | + +### Scores + +| Dimension | Score | Rationale | +|-----------|-------|-----------| +| Precision | 92% | Portal integration is explicitly scoped in Phase 5 with specific endpoint mappings (`/portal/dashboard`, `/portal/history`). Loading patterns and offline handling are precisely defined. | +| Correctness | 94% | React Query's stale-while-revalidate behavior correctly serves cached data during network issues. Quota calculations remain server-authoritative. Session-based portal auth is appropriate for member-facing UI. | +| Usability | 88% | Per-component loading and offline resilience significantly improve my experience. Only gap: no proactive notifications when distributions are recorded or quotas reset. | +| Usefulness | 90% | The transition from mock to real data is exactly what I need — my portal becomes trustworthy and useful for tracking my actual consumption. | + +**Composite Score: 91%** + +### Remaining Gaps (minor, Sprint 6+) +- Push/email notifications for distributions and quota resets +- PWA manifest for mobile home-screen shortcut + +--- + +## 2. 🏢 Club Owner / Vorstand (Business Owner) + +*"I run the Anbauvereinigung. I need staff management, real reports for the Behörde, and confidence that the system works end-to-end."* + +### Findings + +| # | Type | Observation | +|---|------|-------------| +| 1 | ✅ Positive | **Full CRUD staff management** — Phase 6 covers list, invite, edit permissions, revoke. All 8 granular permissions are specified. This is exactly what I need to delegate work to my team without giving everyone full access. | +| 2 | ✅ Positive | **Real report downloads** — Phase 5 wires PDF/CSV report generation from actual database data. Monthly reports for the Behörde will contain real distribution records, not mock data. | +| 3 | ✅ Positive | **System test harness** — Phase 7 proves the full stack works end-to-end with a deterministic test flow. This gives me confidence that deployments won't break critical workflows. | +| 4 | ✅ Positive | **Docker Compose full stack** — I can run the entire system locally with one command for demos to my Vorstand or to show the Behörde during audits. | +| 5 | ✅ Positive | **Seed data for dev/test** — the dual strategy (SQL + API-driven) means I can quickly spin up a realistic environment for training new staff. | +| 6 | ⚠️ Minor | **Staff activity log deferred** — I can't yet see *what* actions my staff performed (who recorded which distribution). Deferred to Sprint 6. | +| 7 | ⚠️ Minor | **Club settings UI still pending** — email whitelist, prevention officer limits, and other club-level configuration isn't in Sprint 5 scope. | +| 8 | ✅ Positive | **Permission chips are color-coded** — the plan specifies visual badges per permission, making it easy to scan who has what access at a glance. | + +### Scores + +| Dimension | Score | Rationale | +|-----------|-------|-----------| +| Precision | 93% | Staff management is thoroughly specified: 8 named permissions, invite flow, pending status handling, revoke confirmation. API endpoints are concrete. | +| Correctness | 91% | Permission model matches the existing `StaffPermission` enum in the backend. RBAC enforcement (403 for unauthorized) is explicitly tested. Report generation uses established PDF/CSV generation code. | +| Usability | 85% | Full CRUD staff management covers my daily needs. Missing activity log means I can't audit staff behavior yet. Club settings require direct backend config. | +| Usefulness | 92% | This sprint delivers the #1 missing piece: staff management. Combined with real reports and system tests, I can now operate the club with confidence. | + +**Composite Score: 90%** + +### Remaining Gaps (Sprint 6) +- Staff activity log (who did what, when) +- Club settings UI (email whitelist, prevention officer limits) + +--- + +## 3. 💻 Developer (Technical Implementer) + +*"I'm the one building this. Is the integration architecture sound? Are dependencies clear? Is the testing strategy robust?"* + +### Findings + +| # | Type | Observation | +|---|------|-------------| +| 1 | ✅ Positive | **React Query architecture is well-designed** — two-layer client (server-side `apiServer()` + client-side `apiFetch()`) with Next.js rewrite proxy keeps auth tokens server-side. Clean separation of concerns. | +| 2 | ✅ Positive | **Service hooks pattern is consistent** — every domain gets the same structure: `useQuery` for reads, `useMutation` with `invalidateQueries` for writes. Easy to replicate across 7 service files. | +| 3 | ✅ Positive | **Next.js upgrade in Phase 1** — doing the security upgrade *before* integration work prevents debugging whether issues come from the upgrade or new code. Smart sequencing. | +| 4 | ✅ Positive | **Docker Compose is production-like** — multi-stage Maven build, PostgreSQL health checks, proper service dependencies. Build cache optimization mentioned for developer experience. | +| 5 | ✅ Positive | **Error handling is comprehensive** — API error → status-specific German toast message mapping is precisely defined (401/403/409/500). Offline detection returns "Verbindungsfehler" toast. | +| 6 | ✅ Positive | **Dual test strategy preserved** — mock E2E tests (<30s) for rapid iteration, system tests (minutes) for full-stack confidence. Both have clear value and separate configs. | +| 7 | ⚠️ Minor | **No API versioning strategy discussed** — if backend DTOs change, there's no contract test or OpenAPI schema validation to catch frontend/backend drift. Currently relies on manual verification during Phase 3. | +| 8 | ✅ Positive | **Risk assessment is realistic** — acknowledges Docker build slowness, CORS container issues, Playwright startup flakiness, and provides concrete mitigations for each. | +| 9 | ✅ Positive | **Seed data with `ON CONFLICT DO NOTHING`** — idempotent SQL ensures repeatable migrations don't fail on re-runs. Correct Flyway pattern. | +| 10 | ⚠️ Minor | **Optimistic update complexity** — Phase 4 mentions optimistic updates for distributions, but doesn't detail rollback behavior when the backend rejects (e.g., quota exceeded after optimistic decrement). React Query's `onMutate`/`onError` rollback pattern should be specified. | + +### Scores + +| Dimension | Score | Rationale | +|-----------|-------|-----------| +| Precision | 91% | Code examples for every pattern (React Query, CORS, Docker, error handling, seeds). File paths are explicit. Only missing: optimistic update rollback detail. | +| Correctness | 93% | Architecture decisions are technically sound. React Query + Next.js rewrite proxy is the established pattern. Docker multi-stage build is correct. Flyway repeatable migration is appropriate for seed data. | +| Usability | 88% | Developer experience is considered: DevTools in dev, skeleton components pre-built, one-command Docker startup. Phase sequencing is logical. Slightly high effort estimate (10.5 days single worker) may compress. | +| Usefulness | 92% | This plan is immediately actionable. Every phase has acceptance criteria checkboxes. Directory structure shows exact file placement. Minimal ambiguity in implementation order. | + +**Composite Score: 91%** + +### Remaining Gaps (nice-to-have) +- OpenAPI contract tests or schema validation between frontend types and backend DTOs +- Explicit optimistic update rollback pattern documentation + +--- + +## 4. 🛡️ Compliance Officer (CanKG / BfArM Regulatory) + +*"I ensure the system meets CanKG regulatory requirements. Distribution records must be immutable, quotas enforced, and audit trails available."* + +### Findings + +| # | Type | Observation | +|---|------|-------------| +| 1 | ✅ Positive | **Quota enforcement is server-authoritative** — the plan explicitly routes quota checks through the backend (`GET /compliance/quota/{memberId}`), not client-side calculations. The 409 response for exceeded limits prevents frontend manipulation. | +| 2 | ✅ Positive | **Under-21 differentiation preserved** — Phase 4 acceptance criteria explicitly states "Under-21 members see 30g monthly limit enforced." The reduced quota is backend-enforced. | +| 3 | ✅ Positive | **System test validates compliance flow** — the test harness (Phase 7) includes a distribution → quota update verification step, proving the enforcement pipeline works end-to-end. | +| 4 | ✅ Positive | **Real PDF reports for Behörde** — the monthly report is generated from actual database records via the established `PdfReportGenerator`. No more mock data in regulatory documents. | +| 5 | ✅ Positive | **Staff permission model controls access** — only users with `RECORD_DISTRIBUTIONS` permission can create distributions. `MANAGE_COMPLIANCE` controls compliance dashboard access. Least-privilege principle applied. | +| 6 | ⚠️ Minor | **No mention of distribution record immutability in Sprint 5** — Sprint 4 established audit trail and 🔒 indicators. Sprint 5 should confirm these survive the integration (i.e., the real backend enforces immutability, not just the frontend). | +| 7 | ✅ Positive | **Seed data includes realistic compliance scenarios** — 5 members with varying ages (including one born 2005 = under-21), 3 batches with different strains. Good for testing age-based quota differentiation. | + +### Scores + +| Dimension | Score | Rationale | +|-----------|-------|-----------| +| Precision | 88% | Quota enforcement endpoints and error codes are precisely specified. Under-21 handling is explicit. Minor gap: immutability guarantee from backend not re-confirmed for Sprint 5. | +| Correctness | 92% | Server-authoritative quota checks with 409 response is the correct enforcement pattern. Staff permissions align with CanKG operational requirements. Age calculation from `date_of_birth` in seed data is testable. | +| Usability | 86% | Compliance officers benefit from real reports and system tests proving the workflow. Missing: no dedicated compliance dashboard enhancements in Sprint 5 (existing dashboard from Sprint 3 carries forward). | +| Usefulness | 90% | The transition to real data makes compliance reporting meaningful. System tests provide regulatory confidence. Staff permissions enable proper access control documentation for Behörde audits. | + +**Composite Score: 89%** + +### Remaining Gaps (Sprint 6) +- Explicit immutability confirmation at the API level (backend `@PreAuthorize` + DB trigger or soft-delete pattern) +- Monthly report auto-sealing (cryptographic timestamp) +- Compliance dashboard enhancements (violation alerts, trend charts) + +--- + +## 5. 🔒 Security Auditor + +*"I review the system for security vulnerabilities. Authentication, authorization, data protection, and secure communication are my focus."* + +### Findings + +| # | Type | Observation | +|---|------|-------------| +| 1 | ✅ Positive | **Next.js upgrade 15.2.8 → 15.5.18** — proactively addresses 8+ known CVEs including SSRF, authentication bypass, and resource exhaustion. Doing this in Phase 1 before integration work is the correct priority. | +| 2 | ✅ Positive | **JWT stays server-side** — the proxy architecture (`/api/backend/*` rewrite) means JWT tokens never touch the browser. Client-side fetches use `credentials: "include"` with session cookies only. Reduced token theft surface. | +| 3 | ✅ Positive | **CORS configuration is restrictive** — only `localhost:3000` and `frontend:3000` (Docker) are whitelisted. `allowCredentials: true` with explicit origins (not `*`). `maxAge: 3600L` limits preflight cache. | +| 4 | ✅ Positive | **Permission-based authorization** — 8 granular permissions with enforcement at API level (403 for insufficient permissions). Only ADMIN + MANAGE_STAFF holders can modify staff. Defense in depth. | +| 5 | ✅ Positive | **Error messages don't leak internals** — the `useApiErrorHandler` maps status codes to generic German messages. No stack traces, no internal paths, no SQL errors exposed to the client. | +| 6 | ⚠️ Minor | **Seed data contains plaintext password placeholders** — `$2a$10$...bcrypt...` in the SQL is obviously a placeholder, but the plan should note that real bcrypt hashes must be generated during implementation. Password `admin123` is acceptable for test-seed profile only. | +| 7 | ✅ Positive | **Docker secrets in environment variables** — `JWT_SECRET` and `POSTGRES_PASSWORD` are in docker-compose with clear "change-in-prod" suffixes. The plan acknowledges these are dev-only values. | +| 8 | ⚠️ Minor | **No rate limiting mentioned** — the API endpoints (especially `/auth/login`, `/staff/invite`) should have rate limiting to prevent brute-force attacks. Not Sprint 5 scope but worth noting. | +| 9 | ✅ Positive | **Portal uses session auth (not JWT)** — member portal correctly uses a separate auth mechanism (session cookies + CSRF) appropriate for public-facing user interfaces. | +| 10 | ✅ Positive | **System test validates auth flows** — the test harness logs in as both admin and member, confirming both auth paths work correctly and are isolated from each other. | + +### Scores + +| Dimension | Score | Rationale | +|-----------|-------|-----------| +| Precision | 90% | CORS config is exact (origins, methods, headers, maxAge). Auth architecture is clearly layered (server-side JWT, client-side session). Permission model is enumerated. | +| Correctness | 92% | Next.js upgrade addresses real CVEs. Server-side token handling is the security best practice. CORS with explicit origins + credentials is correctly restrictive. bcrypt for passwords is appropriate. | +| Usability | 87% | Security measures don't impede development (CORS allows localhost, DevTools in dev mode, test-seed profile for easy setup). Good security/DX balance. | +| Usefulness | 91% | Proactive CVE remediation, server-side token architecture, and granular permissions provide a solid security foundation. Rate limiting and 2FA are reasonable Sprint 6+ deferrals. | + +**Composite Score: 90%** + +### Remaining Gaps (Sprint 6+) +- Rate limiting on auth endpoints +- 2FA (TOTP) for admin accounts +- CSRF token handling for portal session auth (not explicitly mentioned) +- Content Security Policy headers (carried forward from Sprint 4) + +--- + +## 6. 🎨 UX Designer + +*"I focus on user experience, interaction design, accessibility, and visual consistency across the application."* + +### Findings + +| # | Type | Observation | +|---|------|-------------| +| 1 | ✅ Positive | **Per-component skeleton loaders** — the plan includes specific skeleton components (`skeleton-card.tsx`, `skeleton-table.tsx`) that show shimmer during loading. This is better than a full-page spinner — users see progressive content appear. | +| 2 | ✅ Positive | **Offline banner is non-blocking** — "Stale-while-revalidate + banner" means users can still interact with cached data while the banner communicates status. No modal or blocking overlay. | +| 3 | ✅ Positive | **Error states have retry actions** — `error-state.tsx` component includes a retry button. Users aren't stuck — they can attempt recovery without navigating away. | +| 4 | ✅ Positive | **Permission chips are color-coded** — staff permissions displayed as visual badges make the permission grid scannable at a glance. Pattern is consistent with existing UI components (shadcn Badge). | +| 5 | ✅ Positive | **i18n for staff management** — Phase 6 explicitly includes adding German + English strings. Language consistency maintained across the new feature. | +| 6 | ⚠️ Minor | **No loading animation specification** — skeleton components are mentioned but no design tokens for shimmer timing, color, or animation duration. Should match existing shadcn skeleton defaults. | +| 7 | ⚠️ Minor | **Optimistic update UX not detailed** — when a distribution is recorded optimistically, what does the user see? Immediate list update with a subtle "saving..." indicator? Or just instant appearance? The undo pattern for failed optimistic updates needs visual design. | +| 8 | ✅ Positive | **Toast messages are in German** — error toasts use natural German ("Sitzung abgelaufen", "Kontingent überschritten", "Verbindungsfehler"). Consistent with the i18n-first approach from Sprint 4. | +| 9 | ✅ Positive | **Staff invite dialog with checkboxes** — the permission editor uses checkbox grid (8 permissions), which is the appropriate control for multi-select binary options. Familiar pattern. | +| 10 | ⚠️ Minor | **No empty state illustrations** — empty states get messages but no visual illustrations. Sprint 4 defined empty state messages; Sprint 5 should carry them forward with real API responses. | + +### Scores + +| Dimension | Score | Rationale | +|-----------|-------|-----------| +| Precision | 87% | Loading patterns (skeletons, error state, retry) are specified as components. Toast messages have exact copy. Minor gap: no animation timing or optimistic update visual feedback details. | +| Correctness | 90% | Per-component loading is the UX best practice for data-heavy dashboards. Stale-while-revalidate preserves user context during connectivity issues. Checkbox grid for permissions is appropriate. | +| Usability | 86% | Progressive loading, offline resilience, and German error messages create a polished experience. Gaps: optimistic update visual feedback and empty state illustrations not specified. | +| Usefulness | 88% | The UX improvements make the transition from mock to real data transparent to users. Loading and error states prevent confusion. Staff management UI follows established patterns. | + +**Composite Score: 88%** + +### Remaining Gaps (nice-to-have) +- Optimistic update visual feedback pattern (saving indicator, rollback animation) +- Empty state illustrations (consistent with shadcn/ui style) +- Loading animation design tokens (shimmer timing, colors) +- Accessibility audit for new staff management components (focus management in dialogs) + +--- + +## Summary & Composite Scores + +| # | Persona | Composite Score | Top Concern | +|---|---------|-----------------|-------------| +| 1 | 👤 Club Member | **91%** | No push notifications for distributions | +| 2 | 🏢 Club Owner | **90%** | Staff activity log deferred | +| 3 | 💻 Developer | **91%** | Optimistic update rollback pattern unspecified | +| 4 | 🛡️ Compliance Officer | **89%** | Immutability re-confirmation at API level | +| 5 | 🔒 Security Auditor | **90%** | Rate limiting on auth endpoints | +| 6 | 🎨 UX Designer | **88%** | Optimistic update visual feedback unspecified | + +### Overall Score: **90%** ✅ + +**Verdict: APPROVED — exceeds 85% threshold on first pass.** + +--- + +## Dimension Averages + +| Dimension | Average | Min | Max | +|-----------|---------|-----|-----| +| **Precision** | 90% | 87% (UX) | 93% (Owner) | +| **Correctness** | 92% | 90% (UX) | 94% (Member) | +| **Usability** | 87% | 85% (Owner) | 88% (Dev/Member) | +| **Usefulness** | 91% | 88% (UX) | 92% (Dev/Owner) | + +--- + +## Consolidated Improvement Suggestions (Non-Blocking) + +These are recommendations for implementation-time refinement, not plan revisions: + +| # | Category | Suggestion | Priority | +|---|----------|------------|----------| +| 1 | Technical | Add explicit optimistic update rollback pattern (React Query `onMutate`/`onError`) | Medium | +| 2 | Security | Add rate limiting to `/auth/login` and `/staff/invite` endpoints | Medium | +| 3 | Compliance | Re-confirm distribution immutability at API level (not just UI lock icons) | Medium | +| 4 | UX | Define visual feedback for optimistic updates (saving indicator, error rollback) | Low | +| 5 | Technical | Consider OpenAPI schema validation for frontend/backend DTO contract | Low | +| 6 | UX | Carry forward empty state illustrations from Sprint 4 design system | Low | +| 7 | Security | Document CSRF token handling for portal session auth | Low | + +--- + +## Comparison with Sprint 4 Review + +| Metric | Sprint 4 (Iteration 1) | Sprint 4 (Iteration 2) | Sprint 5 (This Review) | +|--------|------------------------|------------------------|------------------------| +| Overall Score | 78% | 88% | **90%** | +| Iterations Needed | 2 | — | **1** ✅ | +| Blocking Gaps | 8 | 0 | **0** | +| Non-Blocking Gaps | 5 | 3 | **7** (minor) | + +Sprint 5 plan achieves a higher first-pass score than Sprint 4's final iteration, demonstrating that learnings from the Sprint 4 review process were incorporated into the planning methodology. All non-blocking gaps are implementation-time refinements rather than plan-level deficiencies. diff --git a/docs/sprint-5/cannamanage-sprint5-plan.md b/docs/sprint-5/cannamanage-sprint5-plan.md new file mode 100644 index 0000000..2067b03 --- /dev/null +++ b/docs/sprint-5/cannamanage-sprint5-plan.md @@ -0,0 +1,890 @@ +# CannaManage — Sprint 5 Implementation Plan + +**Date:** 2026-06-12 +**Author:** Patrick Plate / Lumen (Planner) +**Status:** Draft v2 +**Base Branch:** `main` +**Sprint Branch:** `sprint/5-integration` +**Sprint Goal:** Wire frontend to real backend — full-stack integration, Docker Compose test harness, staff management UI + +> **Sprint Structure:** Sprint 5 is split into two sub-sprints: +> - **Sprint 5.a** — Phases 1–5: Full-stack integration (~7 days) +> - **Sprint 5.b** — Phases 6–7: Staff management + system tests (~3 days) +> +> Both are delivered within Sprint 5, organized as sequential sub-sprints (~10 days total). + +--- + +## 0. Decisions (Confirmed ✅) + +| # | Decision | Detail | Status | +|---|----------|--------|--------| +| D1 | API client library | **@tanstack/react-query** — caching, refetch, optimistic updates, loading/error states. Wraps the existing server-side `apiClient()` with client-side hooks. | ✅ Confirmed (Q1) | +| D2 | Loading strategy | **Per-component loading** — each card/table loads independently with shimmer skeleton. No full-page blocking. | ✅ Confirmed (Q2) | +| D3 | Offline resilience | **Stale-while-revalidate + "Offline" banner** — React Query serves stale cached data while attempting refetch. A persistent banner shows "Offline" status when backend is unreachable. No hard crash. | ✅ Confirmed (Q3) | +| D4 | Staff UI scope | **Full CRUD** — list, invite, edit permissions, revoke. Activity log deferred to Sprint 6. | ✅ Confirmed (Q4) | +| D5 | Seed data strategy | **SQL for dev/test** (Flyway repeatable migration `R__test_seed.sql` activated by Spring profile `test-seed`) + **API-driven for system E2E** (Playwright calls API to set up test state). Dual approach: deterministic SQL for fast local dev, API-driven for realistic integration coverage. | ✅ Confirmed (Q5) | +| D6 | CORS approach | **Spring Boot `@CrossOrigin` + `CorsConfigurationSource` bean** — allows `localhost:3000` in dev, configurable per environment. Needed when running frontend outside Docker (dev mode). | ✅ Carried from v1 | +| D7 | Docker profiles | Remove `profiles: [full]` from backend/frontend services → always-on. Add `docker-compose.test.yml` overlay for Playwright + seed data. | ✅ Carried from v1 | +| D8 | Next.js upgrade | **Upgrade 15.2.8 → 15.5.18** in Phase 1. Addresses 8+ Snyk CVEs (SSRF, auth bypass, resource allocation). Performed early to surface breaking changes before integration work. | ✅ Confirmed (Bonus) | + +--- + +## 1. Sprint 4 Recap (Context) + +| Delivered | Status | +|-----------|--------| +| Next.js 15 + shadcn/ui frontend (12 pages, 23K lines) | ✅ | +| Admin dashboard with KPIs, chart, sidebar nav | ✅ | +| Member management (TanStack Table, add/edit forms) | ✅ | +| Distribution recording (multi-step form + quota check) | ✅ | +| Stock/batch management (chart, recall, add batch) | ✅ | +| Reports page (PDF/CSV download triggers) | ✅ | +| Member portal (quota radial, history, profile) | ✅ | +| i18n (de/en), dark+light mode, Docker multi-stage | ✅ | +| Playwright E2E (66+ tests with mock backend) | ✅ | + +**Critical gap from Sprint 4:** Frontend uses local mock data (`src/data/mock/*`). No real API calls. Frontend and backend are completely disconnected. + +--- + +## 2. Sprint 5 Scope + +### ✅ IN Scope — Sprint 5.a (Full-Stack Integration) + +| # | Feature | Priority | Effort | +|---|---------|----------|--------| +| 1 | **Docker Compose full stack + Next.js upgrade** — upgrade Next.js 15.2.8→15.5.18, remove `full` profile, add CORS, health checks, Backend Dockerfile fix | P0 | 1 day | +| 2 | **API client layer (@tanstack/react-query)** — React Query provider, typed service hooks with caching/refetch/optimistic updates, per-component loading skeletons, error/offline patterns | P0 | 1 day | +| 3 | **Wire dashboard + members** — replace mock data with real API calls | P0 | 1.5 days | +| 4 | **Wire distributions + stock** — real distribution recording with quota check | P0 | 1.5 days | +| 5 | **Wire reports + portal** — real report downloads, portal dashboard with live data | P1 | 1.5 days | + +**Sprint 5.a effort:** ~6.5 days + +### ✅ IN Scope — Sprint 5.b (Staff UI + System Tests) + +| # | Feature | Priority | Effort | +|---|---------|----------|--------| +| 6 | **Staff management UI** — list, invite, permissions editor, revoke | P1 | 2 days | +| 7 | **System test harness** — seed data, Docker Compose test profile, E2E against real stack | P1 | 2 days | + +**Sprint 5.b effort:** ~4 days + +**Total estimated effort:** ~10 days (single worker, sequential) + +### ❌ OUT of Scope (Sprint 6+) + +- WebSocket notifications (email + in-app) +- Inspector read-only mode +- DSGVO consent management UI +- PWA manifest + service worker +- Micro-interactions (Framer Motion) +- Monthly report auto-sealing +- Cryptographic hash chain +- 2FA (TOTP) + +--- + +## 3. Architecture Decisions + +### 3.1 CORS Configuration (Decision D6) + +The frontend runs on `localhost:3000` in dev, but the backend is on `localhost:8080`. While Next.js rewrites (`/api/backend/:path*`) avoid CORS for server-side calls, client-side fetches (React Query) go directly. We add a proper CORS bean: + +```java +// SecurityConfig.java — add to existing configuration +@Bean +public CorsConfigurationSource corsConfigurationSource() { + CorsConfiguration config = new CorsConfiguration(); + config.setAllowedOrigins(List.of( + "http://localhost:3000", // dev + "http://frontend:3000" // Docker network + )); + config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "PATCH")); + config.setAllowedHeaders(List.of("*")); + config.setAllowCredentials(true); + config.setMaxAge(3600L); + + UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource(); + source.registerCorsConfiguration("/api/**", config); + return source; +} +``` + +Apply to the API filter chain: +```java +http.cors(cors -> cors.configurationSource(corsConfigurationSource())) +``` + +### 3.2 TanStack React Query Setup (Decision D1) + +```typescript +// src/lib/query-client.ts +import { QueryClient } from "@tanstack/react-query" + +export const queryClient = new QueryClient({ + defaultOptions: { + queries: { + staleTime: 30_000, // 30s before refetch + gcTime: 5 * 60_000, // 5min garbage collection + retry: 1, // retry once on failure + refetchOnWindowFocus: true, + }, + }, +}) +``` + +Provider setup in root layout: +```typescript +// app/[locale]/providers.tsx +"use client" +import { QueryClientProvider } from "@tanstack/react-query" +import { queryClient } from "@/lib/query-client" + +export function Providers({ children }: { children: React.ReactNode }) { + return ( + + {children} + + ) +} +``` + +### 3.3 API Client Architecture (Server + Client) + +Two layers — server-side for SSR/RSC, client-side for interactive pages: + +```typescript +// src/lib/api-client.ts (SERVER-SIDE — used in Server Components + Route Handlers) +import { auth } from "@/lib/auth" + +const BACKEND_BASE = process.env.BACKEND_URL || "http://localhost:8080" + +export async function apiServer(path: string, options: RequestInit = {}): Promise { + const session = await auth() + if (!session?.user) throw new Error("Unauthorized") + + const res = await fetch(`${BACKEND_BASE}/api/v1${path}`, { + ...options, + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${session.accessToken}`, + ...options.headers, + }, + next: { revalidate: 30 }, // ISR-style caching + }) + + if (!res.ok) { + const error = await res.json().catch(() => ({ message: res.statusText })) + throw new ApiError(res.status, error.message) + } + return res.json() +} +``` + +```typescript +// src/lib/api-client-browser.ts (CLIENT-SIDE — used with React Query hooks) +export async function apiFetch(path: string, options: RequestInit = {}): Promise { + // Uses Next.js rewrite proxy → /api/backend/* → backend:8080/api/v1/* + const res = await fetch(`/api/backend${path}`, { + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + credentials: "include", // sends session cookie for auth + }) + + if (!res.ok) { + const error = await res.json().catch(() => ({ message: res.statusText })) + throw new ApiError(res.status, error.message) + } + return res.json() +} + +export class ApiError extends Error { + constructor(public status: number, message: string) { + super(message) + this.name = "ApiError" + } +} +``` + +### 3.4 Service Hooks Pattern + +Each domain gets a service file with typed React Query hooks: + +```typescript +// src/services/members.ts +import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query" +import { apiFetch } from "@/lib/api-client-browser" +import type { Member } from "@/types/api" + +export function useMembers() { + return useQuery({ + queryKey: ["members"], + queryFn: () => apiFetch("/members"), + }) +} + +export function useMember(id: string) { + return useQuery({ + queryKey: ["members", id], + queryFn: () => apiFetch(`/members/${id}`), + enabled: !!id, + }) +} + +export function useCreateMember() { + const queryClient = useQueryClient() + return useMutation({ + mutationFn: (data: CreateMemberRequest) => + apiFetch("/members", { method: "POST", body: JSON.stringify(data) }), + onSuccess: () => { + queryClient.invalidateQueries({ queryKey: ["members"] }) + }, + }) +} +``` + +### 3.5 Error Handling + Toast Pattern + +```typescript +// src/hooks/use-api-error.ts +import { useToast } from "@/hooks/use-toast" +import { ApiError } from "@/lib/api-client-browser" + +export function useApiErrorHandler() { + const { toast } = useToast() + + return (error: unknown) => { + if (error instanceof ApiError) { + switch (error.status) { + case 401: + toast({ title: "Sitzung abgelaufen", description: "Bitte erneut anmelden.", variant: "destructive" }) + break + case 403: + toast({ title: "Zugriff verweigert", description: "Fehlende Berechtigung.", variant: "destructive" }) + break + case 409: + toast({ title: "Kontingent überschritten", description: error.message, variant: "destructive" }) + break + default: + toast({ title: "Fehler", description: error.message, variant: "destructive" }) + } + } else { + toast({ title: "Verbindungsfehler", description: "Backend nicht erreichbar.", variant: "destructive" }) + } + } +} +``` + +### 3.6 Loading Skeleton Pattern + +```typescript +// src/components/cannamanage/skeleton-card.tsx +import { Skeleton } from "@/components/ui/skeleton" +import { Card, CardContent, CardHeader } from "@/components/ui/card" + +export function SkeletonCard() { + return ( + + + + + + + + + + ) +} +``` + +### 3.7 Docker Compose — Full Stack (Decision D7) + +```yaml +# docker-compose.yml (updated — no profile gates) +version: '3.9' + +services: + db: + image: postgres:16-alpine + container_name: cannamanage-db + environment: + POSTGRES_DB: cannamanage + POSTGRES_USER: cannamanage + POSTGRES_PASSWORD: dev_password_change_in_prod + ports: + - "5432:5432" + volumes: + - pgdata:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U cannamanage"] + interval: 5s + timeout: 3s + retries: 5 + + backend: + build: + context: . + dockerfile: cannamanage-api/Dockerfile + container_name: cannamanage-backend + ports: + - "8080:8080" + environment: + - SPRING_DATASOURCE_URL=jdbc:postgresql://db:5432/cannamanage + - SPRING_DATASOURCE_USERNAME=cannamanage + - SPRING_DATASOURCE_PASSWORD=dev_password_change_in_prod + - SPRING_PROFILES_ACTIVE=docker + - JWT_SECRET=dev-secret-change-in-prod-minimum-32-chars + depends_on: + db: + condition: service_healthy + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:8080/actuator/health"] + interval: 10s + timeout: 5s + retries: 5 + start_period: 30s + + frontend: + build: + context: ./cannamanage-frontend + dockerfile: Dockerfile + container_name: cannamanage-frontend + ports: + - "3000:3000" + environment: + - BACKEND_URL=http://backend:8080 + - NEXTAUTH_URL=http://localhost:3000 + - NEXTAUTH_SECRET=dev-nextauth-secret-32-chars-min + - AUTH_TRUST_HOST=true + depends_on: + backend: + condition: service_healthy + +volumes: + pgdata: +``` + +### 3.8 Test Compose Overlay + +```yaml +# docker-compose.test.yml (overlay for system tests) +services: + backend: + environment: + - SPRING_PROFILES_ACTIVE=docker,test-seed + + playwright: + image: mcr.microsoft.com/playwright:v1.52.0-noble + container_name: cannamanage-playwright + working_dir: /app + volumes: + - ./cannamanage-frontend:/app + environment: + - BASE_URL=http://frontend:3000 + - CI=true + command: npx playwright test e2e/system-test.spec.ts + depends_on: + frontend: + condition: service_started +``` + +Run: `docker compose -f docker-compose.yml -f docker-compose.test.yml up --abort-on-container-exit --exit-code-from playwright` + +### 3.9 Backend Dockerfile (if not exists / needs update) + +```dockerfile +# cannamanage-api/Dockerfile +FROM maven:3.9-eclipse-temurin-17 AS builder +WORKDIR /build +COPY pom.xml . +COPY cannamanage-domain/pom.xml cannamanage-domain/ +COPY cannamanage-service/pom.xml cannamanage-service/ +COPY cannamanage-api/pom.xml cannamanage-api/ +RUN mvn dependency:go-offline -B + +COPY cannamanage-domain/src cannamanage-domain/src +COPY cannamanage-service/src cannamanage-service/src +COPY cannamanage-api/src cannamanage-api/src +RUN mvn package -pl cannamanage-api -am -DskipTests -B + +FROM eclipse-temurin:17-jre-alpine +WORKDIR /app +COPY --from=builder /build/cannamanage-api/target/*.jar app.jar +EXPOSE 8080 +ENTRYPOINT ["java", "-jar", "app.jar"] +``` + +### 3.10 Seed Data Script (Decision D5) + +```sql +-- src/main/resources/db/migration/R__test_seed.sql +-- Repeatable migration: only runs when profile = test-seed + +-- Club +INSERT INTO clubs (id, name, status, city, max_members, created_at) +VALUES ('club-001', 'Grüner Daumen e.V.', 'ACTIVE', 'Berlin', 500, NOW()) +ON CONFLICT (id) DO NOTHING; + +-- Admin user (password: admin123) +INSERT INTO users (id, email, password_hash, role, club_id, created_at) +VALUES ('user-admin', 'admin@gruener-daumen.de', '$2a$10$...bcrypt...', 'ADMIN', 'club-001', NOW()) +ON CONFLICT (id) DO NOTHING; + +-- Staff user (password: staff123) +INSERT INTO users (id, email, password_hash, role, club_id, created_at) +VALUES ('user-staff', 'staff@gruener-daumen.de', '$2a$10$...bcrypt...', 'STAFF', 'club-001', NOW()) +ON CONFLICT (id) DO NOTHING; + +-- 5 Members +INSERT INTO members (id, first_name, last_name, email, date_of_birth, member_number, status, club_id, joined_at) +VALUES + ('m-001', 'Max', 'Müller', 'max@example.com', '1990-03-15', 'GD-001', 'ACTIVE', 'club-001', NOW()), + ('m-002', 'Lisa', 'Weber', 'lisa@example.com', '1988-07-22', 'GD-002', 'ACTIVE', 'club-001', NOW()), + ('m-003', 'Jonas', 'Fischer', 'jonas@example.com', '2005-11-01', 'GD-003', 'ACTIVE', 'club-001', NOW()), + ('m-004', 'Sarah', 'Braun', 'sarah@example.com', '1995-01-30', 'GD-004', 'ACTIVE', 'club-001', NOW()), + ('m-005', 'Kai', 'Hoffmann', 'kai@example.com', '1992-09-10', 'GD-005', 'ACTIVE', 'club-001', NOW()) +ON CONFLICT (id) DO NOTHING; + +-- Strains +INSERT INTO strains (id, name, default_thc_percent, default_cbd_percent, club_id) +VALUES + ('s-001', 'Amnesia Haze', 22.0, 0.5, 'club-001'), + ('s-002', 'White Widow', 18.0, 1.0, 'club-001'), + ('s-003', 'Northern Lights', 20.0, 0.8, 'club-001') +ON CONFLICT (id) DO NOTHING; + +-- Batches +INSERT INTO batches (id, strain_id, total_grams, available_grams, thc_percent, cbd_percent, supplier, status, club_id, received_at) +VALUES + ('b-001', 's-001', 1000, 520, 22.0, 0.5, 'GreenGrow GmbH', 'AVAILABLE', 'club-001', NOW()), + ('b-002', 's-002', 800, 430, 18.0, 1.0, 'BioHemp AG', 'AVAILABLE', 'club-001', NOW()), + ('b-003', 's-003', 600, 380, 20.0, 0.8, 'GreenGrow GmbH', 'AVAILABLE', 'club-001', NOW()) +ON CONFLICT (id) DO NOTHING; +``` + +### 3.11 Optimistic Update with Rollback (for Phase 4) + +When recording a distribution, we optimistically update the UI (instant feedback) but roll back if the server rejects (e.g., quota exceeded): + +```typescript +// src/services/distributions.ts — optimistic mutation pattern +export function useCreateDistribution() { + const queryClient = useQueryClient() + + return useMutation({ + mutationFn: (data: CreateDistributionRequest) => + apiFetch("/distributions", { method: "POST", body: JSON.stringify(data) }), + + // Optimistic update: immediately reflect in UI + onMutate: async (newDistribution) => { + await queryClient.cancelQueries({ queryKey: ["distributions"] }) + const previous = queryClient.getQueryData(["distributions"]) + queryClient.setQueryData(["distributions"], (old = []) => [ + { ...newDistribution, id: "optimistic-temp", createdAt: new Date().toISOString() } as Distribution, + ...old, + ]) + return { previous } // context for rollback + }, + + // Rollback on error + onError: (_err, _variables, context) => { + if (context?.previous) { + queryClient.setQueryData(["distributions"], context.previous) + } + }, + + // Always refetch after success or error to sync with server state + onSettled: () => { + queryClient.invalidateQueries({ queryKey: ["distributions"] }) + queryClient.invalidateQueries({ queryKey: ["dashboard"] }) // refresh KPIs + }, + }) +} +``` + +**Key points:** +- `onMutate` saves the previous state and applies the optimistic change +- `onError` restores the previous state if the server returns 409 (quota exceeded) or 500 +- `onSettled` always re-fetches the truth from the server regardless of success/failure +- The toast handler (from Section 3.5) shows the specific error message ("Kontingent überschritten: noch 12g verfügbar") + +--- + +## 4. Directory Structure (New/Modified Files) + +``` +cannamanage-frontend/ +├── src/ +│ ├── lib/ +│ │ ├── api-client.ts # MODIFIED — server-side apiServer() +│ │ ├── api-client-browser.ts # NEW — client-side apiFetch() +│ │ └── query-client.ts # NEW — React Query configuration +│ ├── services/ # NEW — domain service hooks +│ │ ├── auth.ts # useLogin, useLogout +│ │ ├── dashboard.ts # useClubStats +│ │ ├── members.ts # useMembers, useMember, useCreateMember, useUpdateMember +│ │ ├── distributions.ts # useDistributions, useCreateDistribution, useQuotaCheck +│ │ ├── stock.ts # useBatches, useCreateBatch, useRecallBatch +│ │ ├── reports.ts # useDownloadReport +│ │ ├── portal.ts # usePortalDashboard, usePortalHistory +│ │ └── staff.ts # useStaff, useInviteStaff, useUpdatePermissions +│ ├── components/cannamanage/ +│ │ ├── skeleton-card.tsx # NEW — loading skeleton +│ │ ├── skeleton-table.tsx # NEW — table loading skeleton +│ │ ├── error-state.tsx # NEW — error boundary component +│ │ └── staff/ # NEW — staff management components +│ │ ├── staff-list.tsx +│ │ ├── invite-dialog.tsx +│ │ ├── permissions-editor.tsx +│ │ └── revoke-dialog.tsx +│ ├── hooks/ +│ │ └── use-api-error.ts # NEW — error handler hook +│ ├── app/[locale]/(dashboard)/ +│ │ ├── page.tsx # MODIFIED — real API data +│ │ ├── members/page.tsx # MODIFIED — real API data +│ │ ├── distributions/page.tsx # MODIFIED — real API data +│ │ ├── stock/page.tsx # MODIFIED — real API data +│ │ ├── reports/page.tsx # MODIFIED — real API data +│ │ └── settings/ +│ │ └── staff/page.tsx # NEW — staff management page +│ ├── app/[locale]/(portal)/ +│ │ ├── page.tsx # MODIFIED — real API data +│ │ └── history/page.tsx # MODIFIED — real API data +│ └── app/[locale]/providers.tsx # NEW — QueryClientProvider wrapper +├── e2e/ +│ └── system-test.spec.ts # NEW — full-stack E2E test +└── package.json # MODIFIED — add @tanstack/react-query + +cannamanage-api/ +├── Dockerfile # NEW or MODIFIED +└── src/main/java/de/cannamanage/api/ + ├── security/SecurityConfig.java # MODIFIED — add CORS + └── config/CorsConfig.java # NEW (alternative: inline in SecurityConfig) + +cannamanage-service/ +└── src/main/resources/ + └── db/migration/ + └── R__test_seed.sql # NEW — repeatable test data migration + +docker-compose.yml # MODIFIED — remove profiles, add healthchecks +docker-compose.test.yml # NEW — test overlay with Playwright +``` + +--- + +## 5. Implementation Phases + +### Phase 1: Docker Compose Full Stack + Next.js Upgrade (1 day) + +**Goal:** `docker compose up` brings up PostgreSQL + Spring Boot + Next.js, all healthy and communicating. Next.js upgraded to 15.5.18 for security. + +**Tasks:** +1. **Next.js upgrade 15.2.8 → 15.5.18** — addresses 8+ Snyk CVEs (SSRF, auth bypass, resource exhaustion). Run `pnpm up next@15.5.18`, fix any breaking changes in `next.config.mjs`, verify all pages render. +2. Remove `profiles: [full]` from backend/frontend in `docker-compose.yml` +3. Add backend health check (curl actuator/health) +4. Add frontend dependency on `backend: condition: service_healthy` +5. Add NEXTAUTH environment variables to frontend service +6. Create/update `cannamanage-api/Dockerfile` (multi-stage Maven build) +7. Add CORS configuration to `SecurityConfig.java` +8. Add rate limiting to auth endpoints — Bucket4j or Spring `@RateLimiter` on `/api/v1/auth/login` (max 5 attempts/min per IP) and `/api/v1/staff/invite` (max 10/hour per user). Prevents brute-force attacks. +9. Verify: `docker compose up` → all 3 containers healthy → `curl http://localhost:8080/actuator/health` returns UP +10. Run existing Playwright E2E suite to confirm no regressions from Next.js upgrade + +**Acceptance Criteria:** +- [ ] Next.js upgraded to 15.5.18 — `pnpm list next` shows correct version +- [ ] All 66+ existing Playwright E2E tests still pass after upgrade +- [ ] `docker compose up` starts all 3 services without errors +- [ ] Backend responds to `/actuator/health` within 30s of start +- [ ] Frontend loads at `http://localhost:3000` and displays login page +- [ ] CORS allows `localhost:3000` to call `localhost:8080/api/v1/auth/login` +- [ ] No `profiles` gate — services start by default + +--- + +### Phase 2: API Client Layer (1 day) + +**Goal:** Typed, reusable API layer with React Query for client-side data fetching. + +**Tasks:** +1. `pnpm add @tanstack/react-query @tanstack/react-query-devtools` +2. Create `src/lib/query-client.ts` with default options +3. Create `src/lib/api-client-browser.ts` — client-side fetch via Next.js rewrite proxy +4. Refactor existing `src/lib/api-client.ts` → rename to server-side usage (`apiServer()`) +5. Create `src/app/[locale]/providers.tsx` with `QueryClientProvider` +6. Wire providers into root layout +7. Create `src/hooks/use-api-error.ts` — error → toast mapping +8. Create service files: `src/services/dashboard.ts`, `members.ts`, `distributions.ts`, `stock.ts`, `reports.ts`, `portal.ts` +9. Create skeleton components: `skeleton-card.tsx`, `skeleton-table.tsx`, `error-state.tsx` +10. Add React Query DevTools (dev only) + +**Acceptance Criteria:** +- [ ] `@tanstack/react-query` installed and provider mounted +- [ ] `apiFetch()` calls go through `/api/backend/*` rewrite to Spring Boot +- [ ] Each domain has typed React Query hooks (queryKey, queryFn, types) +- [ ] Error handler shows German toast messages for 401/403/409/500 +- [ ] Skeleton components render during loading state +- [ ] React Query DevTools visible in dev mode (bottom-left panel) + +--- + +### Phase 3: Wire Dashboard + Members (1.5 days) + +**Goal:** Dashboard shows real KPIs from backend. Member list fetches from real API. + +**Tasks:** +1. **Dashboard page** — Replace `mockClubStats` with `useClubStats()` hook → `GET /clubs/stats` +2. **Dashboard recent distributions** — `useRecentDistributions()` → `GET /distributions?limit=5` +3. **Dashboard stock chart** — `useStockSummary()` → `GET /stock/batches/summary` +4. **Member list** — Replace `mockMembers` with `useMembers()` → `GET /members` +5. **Member detail** — `useMember(id)` → `GET /members/{id}` +6. **Add member form** — `useCreateMember()` → `POST /members` +7. **Edit member form** — `useUpdateMember()` → `PUT /members/{id}` +8. Add loading skeletons to dashboard KPI cards and member table +9. Add error states with retry button +10. Handle empty states (no members yet, no distributions today) + +**Backend adjustments needed:** +- Add `GET /api/v1/clubs/stats` endpoint if not existing (or adapt `ClubController`) +- Ensure `GET /api/v1/members` returns paginated response compatible with TanStack Table +- Verify `GET /api/v1/distributions` supports `?limit=N` query param + +**Acceptance Criteria:** +- [ ] Dashboard loads real data — KPI cards show numbers from DB +- [ ] Member list shows real members from PostgreSQL +- [ ] Add member form creates a real member (visible after page refresh) +- [ ] Edit member form persists changes +- [ ] Loading skeletons appear during fetch +- [ ] Error state shows when backend is down (not a blank page) +- [ ] Empty state message when no data exists +- [ ] No mock data imports remain in dashboard or members pages + +--- + +### Phase 4: Wire Distributions + Stock (1.5 days) + +**Goal:** Distribution recording hits real backend with quota enforcement. Stock management is live. + +**Tasks:** +1. **Distribution list** — `useDistributions()` → `GET /distributions` +2. **New distribution form** — `useCreateDistribution()` → `POST /distributions` +3. **Quota check (real-time)** — `useQuotaCheck(memberId)` → `GET /compliance/quota/{memberId}` +4. Wire member search in distribution form to `GET /members?search=...` +5. Wire batch selection to `GET /stock/batches?status=AVAILABLE` +6. **Stock/batch list** — `useBatches()` → `GET /stock/batches` +7. **Add batch form** — `useCreateBatch()` → `POST /stock/batches` +8. **Recall batch** — `useRecallBatch()` → `PUT /stock/batches/{id}/recall` +9. Handle quota exceeded error (409) → show specific toast with remaining grams +10. Optimistic update: after recording distribution, immediately update local cache + +**Key integration points:** +- Distribution form must pass `batchId` + `memberId` + `amountGrams` +- Backend returns `409 Conflict` with `QuotaExceededException` details when over limit +- Stock chart re-fetches after batch creation or recall + +**Acceptance Criteria:** +- [ ] Distribution recording persists to DB (verifiable via `GET /distributions`) +- [ ] Quota check prevents over-limit distribution (shows remaining grams in error) +- [ ] Under-21 members see 30g monthly limit enforced +- [ ] Batch creation adds real stock (visible in stock page) +- [ ] Batch recall changes status to RECALLED +- [ ] Stock chart updates after mutations +- [ ] No mock data imports remain in distributions or stock pages + +--- + +### Phase 5: Wire Reports + Portal (1.5 days) + +**Goal:** Report downloads generate real PDFs. Member portal shows live personal data. + +**Tasks:** +1. **Monthly report** — `useDownloadReport("monthly")` → `GET /reports/monthly?format=pdf` +2. **Member list report** — `GET /reports/member-list?format=csv` +3. **Recall report** — `GET /reports/recall?format=pdf` +4. Handle binary download (PDF/CSV) — create blob URL, trigger download +5. **Portal dashboard** — `usePortalDashboard()` → `GET /portal/dashboard` +6. **Portal history** — `usePortalHistory()` → `GET /portal/history` +7. Portal auth: wire session-based login (`/portal/login` form submit) +8. Show real quota radial with live monthly usage percentage +9. Add date range picker for report generation (month selector) + +**Special handling:** +- Report endpoints return binary (PDF) or text (CSV), not JSON — fetch with `responseType: blob` +- Portal uses session auth (not JWT) — different fetch pattern (cookies, CSRF token) +- Portal API calls go to `/portal/*` endpoints, not `/api/v1/*` + +**Acceptance Criteria:** +- [ ] PDF report downloads as file (opens in browser/downloads) +- [ ] CSV report downloads correctly formatted +- [ ] Portal login with member credentials works +- [ ] Portal dashboard shows real quota (used/remaining from DB) +- [ ] Portal distribution history shows actual past distributions +- [ ] No mock data imports remain in reports or portal pages + +--- + +### Phase 6: Staff Management UI (2 days) + +**Goal:** Admin can invite staff, configure permissions, and revoke access through the UI. + +**Tasks:** +1. Create staff settings page at `/settings/staff` +2. Add navigation entry in sidebar (under Settings section) +3. **Staff list component** — table with name, email, permissions, status, actions +4. **Invite dialog** — email input + permission checkboxes (8 granular permissions) +5. **Permissions editor** — inline permission toggle grid per staff member +6. **Revoke dialog** — confirmation dialog → `DELETE /staff/{id}` +7. Wire to backend: + - `GET /api/v1/staff` → list staff + - `POST /api/v1/staff/invite` → send invite + - `PUT /api/v1/staff/{id}/permissions` → update permissions + - `DELETE /api/v1/staff/{id}` → revoke +8. Show pending invites (status: PENDING) with resend option +9. Add i18n strings for staff management (de.json + en.json) +10. Permission chips: visual badges for each permission (color-coded) + +**Permissions (from backend `StaffPermission` enum):** +- `MANAGE_MEMBERS` — add/edit/suspend members +- `RECORD_DISTRIBUTIONS` — record cannabis distributions +- `MANAGE_STOCK` — add batches, recall +- `VIEW_REPORTS` — download reports +- `MANAGE_CLUB_SETTINGS` — edit club configuration +- `MANAGE_COMPLIANCE` — compliance dashboard access +- `INVITE_STAFF` — can invite other staff +- `MANAGE_STAFF` — full staff CRUD (admin-like) + +**Acceptance Criteria:** +- [ ] Staff list page accessible from sidebar navigation +- [ ] Invite form sends email invite (or shows success if email service is stubbed) +- [ ] Permission editor shows 8 checkboxes per staff member +- [ ] Saving permissions persists to DB +- [ ] Revoke removes staff access (deleted from list) +- [ ] Pending invites shown with "Resend" action +- [ ] Only ADMIN role can access staff settings (403 for STAFF role without MANAGE_STAFF) +- [ ] i18n: all labels in both German and English + +--- + +### Phase 7: System Test Harness (2 days) + +**Goal:** One command runs the full stack with seed data and executes E2E tests against real backend. + +**Tasks:** +1. Create `R__test_seed.sql` — repeatable Flyway migration with deterministic test data +2. Configure Spring profile `test-seed` to activate repeatable migration +3. Create `docker-compose.test.yml` overlay (Playwright container + test-seed profile) +4. Create `e2e/system-test.spec.ts` — full integration flow: + - Login as admin → verify dashboard loads with seed data + - Navigate to members → verify 5 seed members visible + - Add new member → verify appears in list + - Record distribution → verify quota updates + - Check stock decreases after distribution + - Download monthly report (verify PDF response) + - Login as member (portal) → verify personal quota visible +5. Add npm script: `"test:system": "docker compose -f ... up --abort-on-container-exit"` +6. Verify CI-readiness: exit code 0 on success, non-zero on failure +7. Add GitHub Actions workflow stub (`.github/workflows/system-test.yml`) + +**Test flow (happy path):** +``` +1. Admin login (admin@gruener-daumen.de / admin123) +2. Dashboard → verify KPIs match seed data (5 members, 3 batches) +3. Members → see "Max Müller", "Lisa Weber", etc. +4. Add member "Test Neuzugang" → verify appears +5. Distributions → record 10g Amnesia Haze to Max Müller +6. Verify quota check shows updated usage +7. Stock → verify Amnesia Haze batch decreased by 10g +8. Reports → download monthly PDF → verify 200 response + content-type +9. Portal login (max@example.com / member123) +10. Portal dashboard → verify quota shows 10g used +``` + +**Acceptance Criteria:** +- [ ] `docker compose -f docker-compose.yml -f docker-compose.test.yml up --abort-on-container-exit` runs full test +- [ ] Seed data creates club + admin + staff + 5 members + 3 batches +- [ ] System test covers: login → CRUD → quota → report → portal +- [ ] Test passes in < 3 minutes on clean start +- [ ] Exit code 0 on success, non-zero on any test failure +- [ ] Test is deterministic (no flaky timing issues) +- [ ] GitHub Actions workflow file created (can be enabled when GitHub repo is set up) + +--- + +## 6. Risk Assessment + +| Risk | Probability | Impact | Mitigation | +|------|-------------|--------|------------| +| Backend API mismatch (frontend expects fields that don't exist) | Medium | High | Read actual controller code before wiring; add DTO type assertions | +| NextAuth session timeout during system test | Medium | Medium | Set long session expiry in test profile (24h) | +| Docker build slow (Maven + Node rebuild each time) | High | Low | Use Docker build cache, `.dockerignore` excludes target/ | +| CORS issues between containers | Medium | Medium | Test CORS early in Phase 1; add integration test for preflight | +| React Query cache stale data after mutation | Low | Medium | Explicit `invalidateQueries` after every mutation | +| Seed data conflicts with Hibernate DDL auto | Medium | High | Ensure `spring.jpa.hibernate.ddl-auto=validate` in Docker profile (Flyway handles schema) | +| Playwright flaky on container startup timing | High | Medium | Add `waitForURL` + health check polling before test start | +| Backend Dockerfile missing (never existed) | Medium | Low | Create from scratch in Phase 1 — straightforward multi-stage Maven | + +--- + +## 7. Open Questions — RESOLVED ✅ + +All questions resolved in v2 planning session (2026-06-12): + +| # | Question | Decision | Rationale | +|---|----------|----------|-----------| +| Q1 | API client library? | ✅ **@tanstack/react-query** | Caching, refetch, optimistic updates built-in. Eliminates `useEffect` + `useState` boilerplate. DevTools for debugging. | +| Q2 | Loading strategy? | ✅ **Per-component loading** | Each card/table loads independently — no full-page blocking. Better perceived performance. | +| Q3 | Offline resilience? | ✅ **Stale-while-revalidate + "Offline" banner** | React Query serves cached data while retrying. Persistent banner communicates status without blocking interaction. | +| Q4 | Staff UI scope? | ✅ **Full CRUD** (list + invite + edit perms + revoke) | Activity log deferred to Sprint 6. Full CRUD is the minimum viable staff management. | +| Q5 | Seed data strategy? | ✅ **SQL for dev/test + API-driven for system E2E** | Dual approach: fast deterministic SQL seed for local dev, API-driven setup in system tests for realistic coverage. | +| Q6 (Bonus) | Next.js upgrade? | ✅ **Yes — 15.2.8 → 15.5.18 in Phase 1** | Addresses 8+ Snyk CVEs. Done early to catch breaking changes before integration work begins. | + +Previously resolved (from v1): +| # | Question | Decision | +|---|----------|----------| +| Q-v1-1 | Proxy vs direct CORS? | **Proxy** (Next.js rewrite) + CORS for dev flexibility | +| Q-v1-2 | Activity log timing? | **Defer to Sprint 6** | +| Q-v1-3 | System test config? | **Separate Playwright config** for Docker-based system tests | +| Q-v1-4 | Keep mock data files? | **Yes** — fast E2E (<30s) coexists with system tests (minutes) | + +--- + +## 8. Dependencies & Prerequisites + +| Prerequisite | Status | Action | +|-------------|--------|--------| +| Backend compiles and starts on current `main` | ✅ Done | Sprint 3 verified | +| Backend `Dockerfile` exists | ❓ Check | Create in Phase 1 if missing | +| Backend `actuator/health` endpoint enabled | ✅ Done | Spring Boot default | +| Frontend `types/api.ts` matches backend DTOs | ⚠️ Partial | Verify during Phase 3; add missing types | +| PostgreSQL 16 compatible with Hibernate schema | ✅ Done | Testcontainers use PG 16 | +| `pnpm` and Node 22 available locally | ✅ Done | Sprint 4 verified | +| Docker Desktop running | Required | Developer responsibility | + +--- + +## 9. Success Metrics (End of Sprint 5) + +| Metric | Target | +|--------|--------| +| Pages using real API data | 12/12 (all pages, zero mock) | +| Docker Compose startup → healthy | < 60 seconds | +| System test pass rate | 100% (deterministic) | +| System test duration | < 3 minutes | +| API error handling coverage | 401, 403, 404, 409, 500 all handled | +| Staff management operations | List, Invite, Edit Permissions, Revoke | +| Remaining mock data files | Kept for fast E2E (not used in production pages) | + +--- + +## 10. References + +- Sprint 4 Plan: `docs/sprint-4/cannamanage-sprint4-plan.md` (v3) +- Sprint 5 Backlog: `docs/sprint-5/cannamanage-sprint5-backlog.md` +- Sprint 4 Persona Review: `docs/sprint-4/cannamanage-sprint4-plan-persona-review.md` +- Backend Security Config: `cannamanage-api/src/main/java/de/cannamanage/api/security/SecurityConfig.java` +- Frontend API Types: `cannamanage-frontend/src/types/api.ts` +- Docker Compose: `docker-compose.yml` diff --git a/docs/sprint-5/cannamanage-sprint5-testplan.md b/docs/sprint-5/cannamanage-sprint5-testplan.md new file mode 100644 index 0000000..d8af631 --- /dev/null +++ b/docs/sprint-5/cannamanage-sprint5-testplan.md @@ -0,0 +1,640 @@ +# CannaManage — Sprint 5 Test Plan + +**Date:** 2026-06-12 +**Author:** Patrick Plate / Lumen (Planner) +**Status:** Draft v1 +**Basis:** cannamanage-sprint5-plan.md v1 + +--- + +## Test Overview + +| ID | Description | Type | Target | Status | +|----|-------------|------|--------|--------| +| T-01 | Docker Compose full stack starts healthy | System | docker-compose.yml | ⬜ | +| T-02 | CORS preflight allows localhost:3000 | Integration | SecurityConfig | ⬜ | +| T-03 | Backend health endpoint responds | Integration | /actuator/health | ⬜ | +| T-04 | React Query provider mounts without error | Unit | providers.tsx | ⬜ | +| T-05 | apiFetch uses rewrite proxy correctly | Unit | api-client-browser.ts | ⬜ | +| T-06 | ApiError formats toast messages | Unit | use-api-error.ts | ⬜ | +| T-07 | Dashboard loads real club stats | Integration | dashboard/page.tsx | ⬜ | +| T-08 | Member list renders from API | Integration | members/page.tsx | ⬜ | +| T-09 | Create member persists to database | Integration | POST /members | ⬜ | +| T-10 | Edit member updates in database | Integration | PUT /members/{id} | ⬜ | +| T-11 | Distribution form records to backend | Integration | POST /distributions | ⬜ | +| T-12 | Quota exceeded returns 409 with details | Integration | ComplianceService | ⬜ | +| T-13 | Under-21 member enforces 30g limit | Integration | ComplianceService | ⬜ | +| T-14 | Batch creation adds stock | Integration | POST /stock/batches | ⬜ | +| T-15 | Batch recall changes status | Integration | PUT /stock/batches/{id}/recall | ⬜ | +| T-16 | PDF report downloads as binary | Integration | GET /reports/monthly?format=pdf | ⬜ | +| T-17 | CSV report downloads correctly | Integration | GET /reports/member-list?format=csv | ⬜ | +| T-18 | Portal login with session auth | Integration | POST /portal/login | ⬜ | +| T-19 | Portal dashboard shows real quota | Integration | GET /portal/dashboard | ⬜ | +| T-20 | Staff list loads for ADMIN | Integration | GET /staff | ⬜ | +| T-21 | Staff invite sends email | Integration | POST /staff/invite | ⬜ | +| T-22 | Permission update persists | Integration | PUT /staff/{id}/permissions | ⬜ | +| T-23 | Staff revoke removes access | Integration | DELETE /staff/{id} | ⬜ | +| T-24 | Non-ADMIN gets 403 on staff endpoints | Security | SecurityConfig | ⬜ | +| T-25 | Seed data creates deterministic test state | System | R__test_seed.sql | ⬜ | +| T-26 | Full E2E: login → distribute → verify quota | System | system-test.spec.ts | ⬜ | +| T-27 | System test exit code 0 on success | System | docker-compose.test.yml | ⬜ | +| T-28 | Error state renders when backend down | Unit | error-state.tsx | ⬜ | +| T-29 | Loading skeleton appears during fetch | Unit | skeleton-card.tsx | ⬜ | +| T-30 | Empty state shown when no data | Unit | dashboard/members pages | ⬜ | + +Status: ⬜ Open | ✅ Passed | ❌ Failed | ⏭️ Skipped + +--- + +## Test Cases (Detail) + +### T-01: Docker Compose full stack starts healthy + +**Type:** System +**Target:** `docker-compose.yml` + +**Preconditions:** +- Docker Desktop running +- No port conflicts (5432, 8080, 3000) +- Images buildable (Maven + Node available) + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | `docker compose up -d` | All 3 containers reach "healthy" within 60s | +| b | `docker compose ps` | db=healthy, backend=healthy, frontend=running | +| c | `curl http://localhost:3000` | Returns HTML (login page) | +| d | `curl http://localhost:8080/actuator/health` | Returns `{"status":"UP"}` | + +**Post-conditions:** +- All containers stable for 30s without restart loops + +--- + +### T-02: CORS preflight allows localhost:3000 + +**Type:** Integration +**Target:** `SecurityConfig.java` CORS bean + +**Preconditions:** +- Backend running on port 8080 + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | OPTIONS /api/v1/members with Origin: http://localhost:3000 | 200 + Access-Control-Allow-Origin: http://localhost:3000 | +| b | OPTIONS /api/v1/members with Origin: http://evil.com | No Access-Control-Allow-Origin header (or 403) | +| c | GET /api/v1/members with Origin: http://localhost:3000 + valid JWT | 200 + CORS headers present | + +--- + +### T-03: Backend health endpoint responds + +**Type:** Integration +**Target:** Spring Boot Actuator + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | GET /actuator/health (no auth) | 200 `{"status":"UP"}` | +| b | Backend with DB down | 503 `{"status":"DOWN"}` | + +--- + +### T-04: React Query provider mounts without error + +**Type:** Unit +**Class:** `providers.tsx` + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | Render providers with children | No console errors, children visible | +| b | Check React Query DevTools in dev mode | DevTools panel accessible (floating button) | + +--- + +### T-05: apiFetch uses rewrite proxy correctly + +**Type:** Unit +**Class:** `api-client-browser.ts` + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | `apiFetch("/members")` | Fetches `/api/backend/members` | +| b | Backend returns 401 | Throws `ApiError` with status 401 | +| c | Backend returns 500 | Throws `ApiError` with status 500, message from body | +| d | Backend returns non-JSON error | Throws `ApiError` with statusText as message | +| e | Network error (backend down) | Throws TypeError (fetch failure) | + +--- + +### T-06: ApiError formats toast messages + +**Type:** Unit +**Class:** `use-api-error.ts` + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | ApiError(401, "Unauthorized") | Toast: "Sitzung abgelaufen" (destructive) | +| b | ApiError(403, "Forbidden") | Toast: "Zugriff verweigert" (destructive) | +| c | ApiError(409, "Quota exceeded: 5g remaining") | Toast: "Kontingent überschritten" with message | +| d | TypeError (network) | Toast: "Verbindungsfehler — Backend nicht erreichbar" | +| e | ApiError(500, "Internal error") | Toast: "Fehler" with generic message | + +--- + +### T-07: Dashboard loads real club stats + +**Type:** Integration +**Target:** Dashboard page + `GET /clubs/stats` (or equivalent) + +**Preconditions:** +- Backend running with seed data +- User logged in as ADMIN + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | Navigate to dashboard | KPI cards show numbers matching DB (5 members from seed) | +| b | Refresh page | Data reloads (React Query refetch) | +| c | Backend returns error | Error state shown with retry button | +| d | Slow response (>2s) | Skeleton cards visible during loading | + +--- + +### T-08: Member list renders from API + +**Type:** Integration +**Target:** Members page + `GET /members` + +**Preconditions:** +- Seed data loaded (5 members) + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | Navigate to /members | Table shows 5 seed members | +| b | Search "Müller" | Filtered to Max Müller only | +| c | Empty DB (no members) | Empty state: "Keine Mitglieder vorhanden" | +| d | Loading state | Skeleton table rows visible | + +--- + +### T-09: Create member persists to database + +**Type:** Integration +**Target:** `POST /api/v1/members` + +**Preconditions:** +- Logged in as ADMIN or STAFF with MANAGE_MEMBERS permission + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | Valid member data (name, email, DOB, phone) | 201 Created, member appears in list | +| b | Duplicate email | 409 Conflict with error message | +| c | Missing required field (firstName blank) | 400 Bad Request with validation errors | +| d | Future date of birth | 400 Bad Request (validation) | +| e | Under-18 date of birth | 400 Bad Request (CanKG minimum age) | + +--- + +### T-10: Edit member updates in database + +**Type:** Integration +**Target:** `PUT /api/v1/members/{id}` + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | Change phone number | 200 OK, phone updated in DB | +| b | Change status to SUSPENDED | 200 OK, member shows suspended badge | +| c | Invalid member ID | 404 Not Found | +| d | Unauthorized role | 403 Forbidden | + +--- + +### T-11: Distribution form records to backend + +**Type:** Integration +**Target:** `POST /api/v1/distributions` + +**Preconditions:** +- Available batch exists (≥ requested grams) +- Member is ACTIVE +- Quota not exceeded + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | 10g Amnesia Haze to Max Müller | 201 Created, distribution ID returned | +| b | Batch available_grams decreases by 10g | GET /stock/batches/{id} shows -10g | +| c | Member quota updates | Compliance endpoint shows 10g used today | +| d | Stock chart updates after mutation | React Query invalidates batch cache | + +--- + +### T-12: Quota exceeded returns 409 with details + +**Type:** Integration +**Target:** `ComplianceService` quota enforcement + +**Preconditions:** +- Member already at 24g today (daily limit = 25g) + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | Request 5g distribution | 409: "Daily quota exceeded. Remaining: 1g" | +| b | Request 1g distribution | 201 Created (exactly at limit) | +| c | Request 26g in single distribution | 409: "Daily limit is 25g" | + +--- + +### T-13: Under-21 member enforces 30g monthly limit + +**Type:** Integration +**Target:** `ComplianceService` age-based quota + +**Preconditions:** +- Member Jonas Fischer (DOB: 2005-11-01, age 20 in 2026) in seed data + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | Check quota for Jonas | `monthlyLimitGrams: 30`, `isUnder21: true` | +| b | Distribute 29g across month | Success | +| c | Distribute 1g more (total 30g) | Success (at limit) | +| d | Distribute 1g more (total 31g) | 409: "Monthly quota exceeded for under-21 member" | + +--- + +### T-14: Batch creation adds stock + +**Type:** Integration +**Target:** `POST /api/v1/stock/batches` + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | New batch: 500g Blue Dream, THC 19%, supplier "BioHemp" | 201 Created | +| b | Stock total increases by 500g | Dashboard total_stock reflects increase | +| c | Missing strain name | 400 Bad Request | +| d | Negative grams | 400 Bad Request | + +--- + +### T-15: Batch recall changes status + +**Type:** Integration +**Target:** `PUT /api/v1/stock/batches/{id}/recall` + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | Recall batch b-001 | Status changes to RECALLED | +| b | Recalled batch not available for distribution | Distribution form excludes recalled batches | +| c | Recall already-recalled batch | 400 Bad Request (or idempotent 200) | +| d | Invalid batch ID | 404 Not Found | + +--- + +### T-16: PDF report downloads as binary + +**Type:** Integration +**Target:** `GET /api/v1/reports/monthly?format=pdf` + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | Request monthly report (current month) | 200, Content-Type: application/pdf | +| b | Response body is valid PDF | First bytes = `%PDF-` | +| c | Browser triggers file download | Content-Disposition: attachment | +| d | No data for requested month | 200 with empty report (or 204 No Content) | + +--- + +### T-17: CSV report downloads correctly + +**Type:** Integration +**Target:** `GET /api/v1/reports/member-list?format=csv` + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | Request member list CSV | 200, Content-Type: text/csv | +| b | CSV has header row | First line: column names | +| c | 5 seed members in CSV body | 6 lines total (header + 5 data) | +| d | German umlauts preserved | "Müller" renders correctly (UTF-8 or ISO-8859-1) | + +--- + +### T-18: Portal login with session auth + +**Type:** Integration +**Target:** `POST /portal/login` + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | Valid member credentials (max@example.com / member123) | 200 `{"status":"ok"}` + Set-Cookie session | +| b | Invalid password | 401 `{"error":"Invalid credentials"}` | +| c | Non-member email (admin@...) | 401 (not a member) | +| d | Subsequent /portal/* requests with session cookie | 200 (authenticated) | + +--- + +### T-19: Portal dashboard shows real quota + +**Type:** Integration +**Target:** `GET /portal/dashboard` + +**Preconditions:** +- Member logged into portal session +- Some distributions recorded for this member + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | Fresh member (no distributions) | Quota: 0g used / 50g limit (≥21 years) | +| b | After 10g distribution recorded | Quota: 10g used / 50g limit | +| c | Radial chart shows correct percentage | 20% filled (10/50) | + +--- + +### T-20: Staff list loads for ADMIN + +**Type:** Integration +**Target:** `GET /api/v1/staff` + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | ADMIN requests staff list | 200 with array of staff accounts | +| b | Includes permissions array per staff | Each item has `permissions: [...]` | +| c | STAFF without MANAGE_STAFF permission | 403 Forbidden | +| d | MEMBER role | 403 Forbidden | + +--- + +### T-21: Staff invite sends email + +**Type:** Integration +**Target:** `POST /api/v1/staff/invite` + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | Valid email + permissions selection | 201 Created, invite token generated | +| b | Email already registered as staff | 409 Conflict | +| c | Invalid email format | 400 Bad Request | +| d | No permissions selected | 400 Bad Request (at least one required) | + +--- + +### T-22: Permission update persists + +**Type:** Integration +**Target:** `PUT /api/v1/staff/{id}/permissions` + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | Set permissions to [MANAGE_MEMBERS, VIEW_REPORTS] | 200, permissions saved | +| b | Staff can now access members but not stock | GET /members → 200, GET /stock → 403 | +| c | Empty permissions array | 200 (staff has no capabilities, effectively read-only) | +| d | Invalid permission name | 400 Bad Request | + +--- + +### T-23: Staff revoke removes access + +**Type:** Integration +**Target:** `DELETE /api/v1/staff/{id}` + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | Delete staff account | 204 No Content | +| b | Revoked staff can no longer login | 401 on next auth attempt | +| c | Staff disappears from list | GET /staff excludes deleted | +| d | Delete non-existent staff ID | 404 Not Found | + +--- + +### T-24: Non-ADMIN gets 403 on staff endpoints + +**Type:** Security +**Target:** SecurityConfig authorization rules + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | STAFF (no MANAGE_STAFF) → GET /staff | 403 | +| b | STAFF (no MANAGE_STAFF) → POST /staff/invite | 403 | +| c | MEMBER → GET /staff | 403 | +| d | Unauthenticated → GET /staff | 401 | +| e | ADMIN → GET /staff | 200 | +| f | STAFF with MANAGE_STAFF → GET /staff | 200 | + +--- + +### T-25: Seed data creates deterministic test state + +**Type:** System +**Target:** `R__test_seed.sql` + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | Backend starts with profile=test-seed | Seed data inserted on startup | +| b | `SELECT COUNT(*) FROM members WHERE club_id='club-001'` | Returns 5 | +| c | `SELECT COUNT(*) FROM batches WHERE club_id='club-001'` | Returns 3 | +| d | Second startup with same profile | No duplicate insert errors (ON CONFLICT DO NOTHING) | +| e | Admin user can login with seed credentials | JWT returned successfully | + +--- + +### T-26: Full E2E: login → distribute → verify quota + +**Type:** System +**Class:** `e2e/system-test.spec.ts` + +**Preconditions:** +- Full Docker stack running with seed data + +**Scenarios:** + +| # | Step | Expected Result | +|---|------|-----------------| +| a | Login as admin@gruener-daumen.de | Dashboard loads with KPIs | +| b | Navigate to Members | 5 seed members visible in table | +| c | Navigate to Distributions | Distribution list renders | +| d | Record 10g Amnesia Haze → Max Müller | Success toast, distribution in list | +| e | Navigate to Stock | Amnesia Haze batch shows -10g available | +| f | Navigate to Reports → download monthly PDF | File downloads (200 response) | +| g | Logout, login as member (max@example.com) | Portal dashboard loads | +| h | Portal quota shows 10g used | Radial chart at 20% | + +--- + +### T-27: System test exit code 0 on success + +**Type:** System +**Target:** `docker-compose.test.yml` + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | All tests pass | Playwright container exits with code 0, compose exits 0 | +| b | A test fails | Playwright exits non-zero, compose exits non-zero | +| c | Backend fails to start | Tests timeout, compose exits non-zero | + +--- + +### T-28: Error state renders when backend down + +**Type:** Unit +**Target:** `error-state.tsx` + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | API fetch throws network error | Error component visible with message | +| b | Click "Retry" button | Query refetches | +| c | Multiple errors on same page | Each section shows own error independently | + +--- + +### T-29: Loading skeleton appears during fetch + +**Type:** Unit +**Target:** `skeleton-card.tsx`, `skeleton-table.tsx` + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | Query in `isLoading` state | Skeleton shimmer visible | +| b | Query resolves | Skeleton replaced with real content | +| c | Query in `isFetching` (background refetch) | No skeleton (data still shown) | + +--- + +### T-30: Empty state shown when no data + +**Type:** Unit +**Target:** Dashboard, Members, Distributions pages + +**Scenarios:** + +| # | Input | Expected Result | +|---|-------|-----------------| +| a | Members list empty (API returns []) | "Keine Mitglieder vorhanden" + Add button | +| b | Distributions list empty | "Keine Ausgaben erfasst" message | +| c | Stock empty (no batches) | "Kein Bestand vorhanden" + Add batch button | +| d | Dashboard with 0 members | KPI cards show 0, no chart data placeholder | + +--- + +## Test Data Requirements + +| Entity | Count | Source | Notes | +|--------|-------|--------|-------| +| Club | 1 | `R__test_seed.sql` | "Grüner Daumen e.V.", Berlin | +| Admin user | 1 | Seed | admin@gruener-daumen.de / admin123 | +| Staff user | 1 | Seed | staff@gruener-daumen.de / staff123 | +| Members | 5 | Seed | Including 1 under-21 (Jonas Fischer) | +| Strains | 3 | Seed | Amnesia Haze, White Widow, Northern Lights | +| Batches | 3 | Seed | 520g, 430g, 380g available | +| Distributions | 0 | Fresh | Tests create distributions during execution | + +--- + +## Test Coverage Matrix + +| Component | Unit | Integration | System | Total | +|-----------|------|-------------|--------|-------| +| Docker/Infra | 0 | 1 | 2 | 3 | +| CORS/Security | 0 | 2 | 0 | 2 | +| API Client | 3 | 0 | 0 | 3 | +| Dashboard | 0 | 1 | 1 | 2 | +| Members | 0 | 2 | 1 | 3 | +| Distributions | 0 | 3 | 1 | 4 | +| Stock | 0 | 2 | 1 | 3 | +| Reports | 0 | 2 | 1 | 3 | +| Portal | 0 | 2 | 1 | 3 | +| Staff | 0 | 5 | 0 | 5 | +| UI States | 3 | 0 | 0 | 3 | +| **Total** | **6** | **20** | **4** | **30** | + +--- + +## Execution Strategy + +### Fast feedback loop (during development): +```bash +# Frontend unit tests (Vitest — if configured) +cd cannamanage-frontend && pnpm test + +# Backend integration tests (existing Testcontainers suite) +cd cannamanage-api && mvn test + +# Existing Playwright E2E (mock backend, ~30s) +cd cannamanage-frontend && pnpm exec playwright test +``` + +### Full system test (before merge): +```bash +docker compose -f docker-compose.yml -f docker-compose.test.yml up \ + --build --abort-on-container-exit --exit-code-from playwright +``` + +### Manual smoke test checklist: +1. `docker compose up` → all healthy +2. Open http://localhost:3000 → login page +3. Login as admin → dashboard with real data +4. Add member → appears in list +5. Record distribution → quota updates +6. Download PDF report → valid file +7. Login as member (portal) → see personal quota + +--- + +## References + +- Implementation Plan: `docs/sprint-5/cannamanage-sprint5-plan.md` (v1) +- Backend Controllers: `cannamanage-api/src/main/java/de/cannamanage/api/controller/` +- Frontend Types: `cannamanage-frontend/src/types/api.ts` +- Security Config: `cannamanage-api/src/main/java/de/cannamanage/api/security/SecurityConfig.java` +- Existing E2E: `cannamanage-frontend/e2e/`