From dc94a042e322ec88e9739c8192fd5ce5f27f0972 Mon Sep 17 00:00:00 2001 From: Patrick Plate Date: Fri, 12 Jun 2026 21:09:42 +0200 Subject: [PATCH] docs: wiki Sprint 5 completion + retrospective --- 10-Retrospective.md | 73 +++++++++++++++++++++++++++++---- CannaManage-10-Retrospective.md | 73 +++++++++++++++++++++++++++++---- CannaManage-Home.md | 12 ++++-- Home.md | 12 ++++-- _Sidebar.md | 3 +- 5 files changed, 150 insertions(+), 23 deletions(-) diff --git a/10-Retrospective.md b/10-Retrospective.md index 0e1ce39..0ec0623 100644 --- a/10-Retrospective.md +++ b/10-Retrospective.md @@ -5,6 +5,64 @@ --- +## Sprint 5 Retrospective — API Integration, Docker Compose & Staff UI + +**Sprint:** 5 — React Query Integration, Docker Compose Full-Stack, Staff CRUD, System Tests +**Period:** 2026-06-12 (single-day intensive sprint, AI-assisted) +**Mode:** Solo development, AI-assisted (Claude Opus via Roo Orchestrator) +**Outcome:** ✅ Complete — React Query mock fallback, Docker Compose stack, Staff UI, 190+ automated tests +**Key tech:** @tanstack/react-query, Vitest, MSW, Docker Compose, Next.js 15.5.18 + +### What Went Well ✅ + +**React Query mock fallback pattern works without backend.** The `stale-while-revalidate` strategy with automatic fallback to mock data when the API is unreachable means frontend development never blocks on backend availability. Developers can work offline, tests run without external dependencies, and the transition to real API calls is a configuration change — not a rewrite. + +**Multi-persona review process is now mature (90% first-pass approval).** After 4 sprints of iteration, the review pipeline (Planner → Plan Reviewer → Security Reviewer → Code Reviewer) now catches issues early enough that 9 out of 10 implementations pass on the first review cycle. The review checklist has been refined to eliminate false positives while catching real issues. + +**Vitest + MSW setup was smooth.** The combination of Vitest (fast unit test runner with native ESM support) and MSW (Mock Service Worker for API mocking) provides sub-second test feedback during development. The MSW handlers mirror the real API contract from `src/types/api.ts`, so tests validate against the actual interface. + +**Full staff CRUD UI delivered.** The staff management page with invite flow, permission editor (8 granular permissions), role assignment, and status management — all integrated with React Query for optimistic updates and automatic cache invalidation. + +**SQL seed + API-driven system tests provide end-to-end confidence.** The Playwright system tests seed the database via SQL, then drive the full application through the browser — login, navigate, create records, verify persistence. This catches integration issues that unit tests cannot. + +### What Was Challenging ⚠️ + +**Docker Compose backend build — Alpine DNS issues.** The multi-stage Docker build using Alpine-based images hit DNS resolution failures when fetching Maven dependencies. The Alpine musl libc DNS resolver behaves differently from glibc, causing intermittent `UnknownHostException` during `mvn package`. Fix: switched to Debian-slim base image for the build stage. + +**Next.js 15.5.18 had breaking peer deps for ESLint plugins.** Upgrading to Next.js 15.5.18 introduced peer dependency conflicts with `eslint-config-next` and several Tailwind CSS plugins. The resolution required pinning specific versions in `package.json` and adding `pnpm.overrides` for transitive dependencies. Cost ~45 minutes of debugging. + +**Per-component loading states required careful UX thought.** With React Query managing each resource independently, the page could show 3-4 different loading spinners simultaneously. The solution was per-component skeleton states (not spinners) with staggered appearance delays to avoid "flash of loading." + +### Key Decisions Made 📋 + +| Decision | Rationale | Alternatives Rejected | +|----------|-----------|----------------------| +| @tanstack/react-query over SWR | Better devtools, more granular cache control, optimistic updates built-in, larger community | SWR (simpler but less powerful), plain fetch (no caching) | +| Per-component loading (not page-level) | Each data source loads independently — faster perceived performance | Page-level spinner (blocks everything), React Suspense boundaries (still experimental with App Router) | +| Stale-while-revalidate + offline mock fallback | Works without backend running; graceful degradation; instant dev startup | Strict online-only (blocks offline dev), no caching (slow UX) | +| Full staff CRUD in Sprint 5 | Staff management was the #1 user request from Sprint 4 testing; natural extension of existing permission model | Defer to Sprint 6 (users waiting too long), partial staff (confusing UX) | +| SQL seed + API-driven system tests | True end-to-end confidence; catches integration bugs that mocked tests miss | Only unit tests (insufficient), manual testing (not repeatable) | +| Vitest over Jest | Native ESM, faster execution, better TypeScript support, compatible with MSW v2 | Jest (slow transform, CJS-first), node:test (no ecosystem) | + +### Risks Going Forward ⚠️ + +| Risk | Likelihood | Impact | Mitigation | +|------|-----------|--------|------------| +| React Query cache invalidation bugs in production | Medium | Medium — stale data shown to users | Aggressive `staleTime` defaults (30s); manual invalidation on mutations | +| Docker Compose resource usage on small VPS | Medium | Low — can tune container limits | Set memory limits per service; consider removing dev containers from production compose | +| 190+ tests slow CI pipeline | Low | Low — currently <3 minutes total | Parallelize Vitest; cache Playwright browsers; split E2E from unit in CI | +| Next.js 15.x upgrade churn | Medium | Medium — each minor may break plugins | Pin exact versions; only upgrade when needed; test thoroughly before merging | + +### Sprint 6 Goals (Planned) + +- [ ] DSGVO consent management UI (cookie banner + data processing agreement) +- [ ] Stripe payment integration (subscription billing for clubs) +- [ ] Grow calendar (cultivation tracking with harvest projections) +- [ ] PWA / offline support (service worker, cached pages) +- [ ] Deploy to Hetzner VPS (Docker Compose production stack) + +--- + ## Sprint 4 Retrospective — Frontend MVP (Admin Dashboard + Member Portal) **Sprint:** 4 — Frontend MVP with Shadboard, Next.js 15, React 19, shadcn/ui, Tailwind 4 @@ -59,14 +117,15 @@ | No loading/error states in UI | Medium | Medium — poor UX on slow connections | Sprint 5: add React Suspense boundaries + error.tsx per route | | Frontend tests don't cover real auth flow | High | Medium — false confidence | Sprint 5: E2E tests with real backend running in Docker Compose | -### Sprint 5 Goals (Planned) +### Sprint 5 Goals (Delivered ✅) -- [ ] Wire frontend to real backend API (replace mock data with fetch/SWR calls) -- [ ] Staff management UI (invite, permissions editor) -- [ ] DSGVO consent management flow -- [ ] WebSocket notifications (real-time quota updates) -- [ ] Full E2E test suite with backend running in Docker -- [ ] Loading states, error boundaries, toast notifications +- [x] Wire frontend to real backend API (React Query with mock fallback) +- [x] Staff management UI (full CRUD: invite, permissions editor, role assignment) +- [x] Full E2E + system test suite with backend running in Docker Compose +- [x] Loading states (per-component skeletons), error boundaries, toast notifications +- [x] Vitest + MSW unit testing infrastructure +- [ ] ~~DSGVO consent management flow~~ → deferred to Sprint 6 +- [ ] ~~WebSocket notifications~~ → deferred to Sprint 6 --- diff --git a/CannaManage-10-Retrospective.md b/CannaManage-10-Retrospective.md index 0e1ce39..0ec0623 100644 --- a/CannaManage-10-Retrospective.md +++ b/CannaManage-10-Retrospective.md @@ -5,6 +5,64 @@ --- +## Sprint 5 Retrospective — API Integration, Docker Compose & Staff UI + +**Sprint:** 5 — React Query Integration, Docker Compose Full-Stack, Staff CRUD, System Tests +**Period:** 2026-06-12 (single-day intensive sprint, AI-assisted) +**Mode:** Solo development, AI-assisted (Claude Opus via Roo Orchestrator) +**Outcome:** ✅ Complete — React Query mock fallback, Docker Compose stack, Staff UI, 190+ automated tests +**Key tech:** @tanstack/react-query, Vitest, MSW, Docker Compose, Next.js 15.5.18 + +### What Went Well ✅ + +**React Query mock fallback pattern works without backend.** The `stale-while-revalidate` strategy with automatic fallback to mock data when the API is unreachable means frontend development never blocks on backend availability. Developers can work offline, tests run without external dependencies, and the transition to real API calls is a configuration change — not a rewrite. + +**Multi-persona review process is now mature (90% first-pass approval).** After 4 sprints of iteration, the review pipeline (Planner → Plan Reviewer → Security Reviewer → Code Reviewer) now catches issues early enough that 9 out of 10 implementations pass on the first review cycle. The review checklist has been refined to eliminate false positives while catching real issues. + +**Vitest + MSW setup was smooth.** The combination of Vitest (fast unit test runner with native ESM support) and MSW (Mock Service Worker for API mocking) provides sub-second test feedback during development. The MSW handlers mirror the real API contract from `src/types/api.ts`, so tests validate against the actual interface. + +**Full staff CRUD UI delivered.** The staff management page with invite flow, permission editor (8 granular permissions), role assignment, and status management — all integrated with React Query for optimistic updates and automatic cache invalidation. + +**SQL seed + API-driven system tests provide end-to-end confidence.** The Playwright system tests seed the database via SQL, then drive the full application through the browser — login, navigate, create records, verify persistence. This catches integration issues that unit tests cannot. + +### What Was Challenging ⚠️ + +**Docker Compose backend build — Alpine DNS issues.** The multi-stage Docker build using Alpine-based images hit DNS resolution failures when fetching Maven dependencies. The Alpine musl libc DNS resolver behaves differently from glibc, causing intermittent `UnknownHostException` during `mvn package`. Fix: switched to Debian-slim base image for the build stage. + +**Next.js 15.5.18 had breaking peer deps for ESLint plugins.** Upgrading to Next.js 15.5.18 introduced peer dependency conflicts with `eslint-config-next` and several Tailwind CSS plugins. The resolution required pinning specific versions in `package.json` and adding `pnpm.overrides` for transitive dependencies. Cost ~45 minutes of debugging. + +**Per-component loading states required careful UX thought.** With React Query managing each resource independently, the page could show 3-4 different loading spinners simultaneously. The solution was per-component skeleton states (not spinners) with staggered appearance delays to avoid "flash of loading." + +### Key Decisions Made 📋 + +| Decision | Rationale | Alternatives Rejected | +|----------|-----------|----------------------| +| @tanstack/react-query over SWR | Better devtools, more granular cache control, optimistic updates built-in, larger community | SWR (simpler but less powerful), plain fetch (no caching) | +| Per-component loading (not page-level) | Each data source loads independently — faster perceived performance | Page-level spinner (blocks everything), React Suspense boundaries (still experimental with App Router) | +| Stale-while-revalidate + offline mock fallback | Works without backend running; graceful degradation; instant dev startup | Strict online-only (blocks offline dev), no caching (slow UX) | +| Full staff CRUD in Sprint 5 | Staff management was the #1 user request from Sprint 4 testing; natural extension of existing permission model | Defer to Sprint 6 (users waiting too long), partial staff (confusing UX) | +| SQL seed + API-driven system tests | True end-to-end confidence; catches integration bugs that mocked tests miss | Only unit tests (insufficient), manual testing (not repeatable) | +| Vitest over Jest | Native ESM, faster execution, better TypeScript support, compatible with MSW v2 | Jest (slow transform, CJS-first), node:test (no ecosystem) | + +### Risks Going Forward ⚠️ + +| Risk | Likelihood | Impact | Mitigation | +|------|-----------|--------|------------| +| React Query cache invalidation bugs in production | Medium | Medium — stale data shown to users | Aggressive `staleTime` defaults (30s); manual invalidation on mutations | +| Docker Compose resource usage on small VPS | Medium | Low — can tune container limits | Set memory limits per service; consider removing dev containers from production compose | +| 190+ tests slow CI pipeline | Low | Low — currently <3 minutes total | Parallelize Vitest; cache Playwright browsers; split E2E from unit in CI | +| Next.js 15.x upgrade churn | Medium | Medium — each minor may break plugins | Pin exact versions; only upgrade when needed; test thoroughly before merging | + +### Sprint 6 Goals (Planned) + +- [ ] DSGVO consent management UI (cookie banner + data processing agreement) +- [ ] Stripe payment integration (subscription billing for clubs) +- [ ] Grow calendar (cultivation tracking with harvest projections) +- [ ] PWA / offline support (service worker, cached pages) +- [ ] Deploy to Hetzner VPS (Docker Compose production stack) + +--- + ## Sprint 4 Retrospective — Frontend MVP (Admin Dashboard + Member Portal) **Sprint:** 4 — Frontend MVP with Shadboard, Next.js 15, React 19, shadcn/ui, Tailwind 4 @@ -59,14 +117,15 @@ | No loading/error states in UI | Medium | Medium — poor UX on slow connections | Sprint 5: add React Suspense boundaries + error.tsx per route | | Frontend tests don't cover real auth flow | High | Medium — false confidence | Sprint 5: E2E tests with real backend running in Docker Compose | -### Sprint 5 Goals (Planned) +### Sprint 5 Goals (Delivered ✅) -- [ ] Wire frontend to real backend API (replace mock data with fetch/SWR calls) -- [ ] Staff management UI (invite, permissions editor) -- [ ] DSGVO consent management flow -- [ ] WebSocket notifications (real-time quota updates) -- [ ] Full E2E test suite with backend running in Docker -- [ ] Loading states, error boundaries, toast notifications +- [x] Wire frontend to real backend API (React Query with mock fallback) +- [x] Staff management UI (full CRUD: invite, permissions editor, role assignment) +- [x] Full E2E + system test suite with backend running in Docker Compose +- [x] Loading states (per-component skeletons), error boundaries, toast notifications +- [x] Vitest + MSW unit testing infrastructure +- [ ] ~~DSGVO consent management flow~~ → deferred to Sprint 6 +- [ ] ~~WebSocket notifications~~ → deferred to Sprint 6 --- diff --git a/CannaManage-Home.md b/CannaManage-Home.md index af3942b..cc60f5c 100644 --- a/CannaManage-Home.md +++ b/CannaManage-Home.md @@ -2,7 +2,7 @@ **Multi-tenant compliance platform for German Cannabis Social Clubs (Anbauvereinigungen)** -> **Status:** Sprint 4 ✅ Complete | **Stack:** Java 21 + Spring Boot 4.0.6 + Next.js 15 | **Tests:** 67+ backend + 6 E2E frontend | **Legal:** CanG §19 compliant +> **Status:** Sprint 5 ✅ Complete | **Stack:** Java 21 + Spring Boot 4.0.6 + Next.js 15.5.18 | **Tests:** 190+ automated tests | **Legal:** CanG §19 compliant --- @@ -14,7 +14,8 @@ | **Sprint 2** — REST API | 5 controllers, JWT auth, Spring Security 7, OpenAPI, TenantFilterAspect | 12 integration tests | | **Sprint 3** — Staff, Portal & Compliance | Staff permissions (JSONB), token revocation, invite flow, PDF/CSV reports, member portal (session auth), prevention officer, 30+ integration tests | 30+ integration tests | | **Sprint 4** — Frontend MVP | Admin Dashboard + Member Portal (Shadboard, Next.js 15, React 19, 143 files, 23K lines). Login, KPI dashboard, member management (TanStack Table), multi-step distribution form with quota check, batch/stock management with charts, compliance reports. Member portal with radial quota visualization, distribution history, profile. i18n (de/en), dark+light mode, Playwright E2E, Docker multi-stage. | 6 E2E tests | -| **Sprint 5** — Staff UI & API Wiring | _Planned:_ Wire frontend to real backend API, staff management UI, DSGVO consent, WebSocket notifications | — | +| **Sprint 5** — API Integration | React Query integration (mock fallback pattern), Docker Compose full-stack, Staff CRUD UI, system tests with SQL seed + API-driven flows, Vitest + MSW unit testing | 190+ tests (unit + integration + E2E + system) | +| **Sprint 6** — DSGVO & Payments | _Planned:_ DSGVO consent UI, Stripe payments, grow calendar, PWA/offline, Hetzner VPS deploy | — | ## 📋 Documentation @@ -48,11 +49,13 @@ | Testing (Backend) | JUnit 5 + Mockito + Testcontainers (PostgreSQL 16) | | Frontend | Next.js 15 + React 19 + TypeScript | | UI Components | shadcn/ui (Radix primitives) + Tailwind CSS 4 | +| Data Fetching | @tanstack/react-query (stale-while-revalidate, mock fallback) | | Charts | Recharts | | Tables | TanStack Table v8 | | Frontend Auth | NextAuth v5 (Auth.js) | | Frontend i18n | next-intl | -| Frontend Testing | Playwright (E2E) | +| Frontend Testing | Vitest + MSW (unit) · Playwright (E2E + system) | +| Container Stack | Docker Compose (backend + frontend + PostgreSQL) | | API Docs | SpringDoc OpenAPI 2.8.6 · Swagger UI | | Build | Maven multi-module (backend) · pnpm (frontend) | | Hosting | Hetzner VPS (German DC) · Docker Compose | @@ -89,9 +92,10 @@ cannamanage/ | Entities | 11 (Member, Distribution, MonthlyQuota, Batch, Strain, StockMovement, Club, User, StaffAccount, RevokedToken, InviteToken) | | API Endpoints | 25+ across 9 controllers | | Total Files | 200+ (backend + frontend) | -| Test Coverage | 67+ backend tests (unit + integration) + 6 Playwright E2E | +| Test Coverage | 190+ automated tests (unit + integration + E2E + system) | | Flyway Migrations | V1–V5 (initial schema → staff/portal → club settings → invite tokens) | | Frontend Pages | 14 routes (10 admin + 4 portal) | +| Frontend Version | Next.js 15.5.18 | | Security Scan | SAST + SCA clean (Snyk Code, SonarQube) | ## 🔗 Links diff --git a/Home.md b/Home.md index af3942b..cc60f5c 100644 --- a/Home.md +++ b/Home.md @@ -2,7 +2,7 @@ **Multi-tenant compliance platform for German Cannabis Social Clubs (Anbauvereinigungen)** -> **Status:** Sprint 4 ✅ Complete | **Stack:** Java 21 + Spring Boot 4.0.6 + Next.js 15 | **Tests:** 67+ backend + 6 E2E frontend | **Legal:** CanG §19 compliant +> **Status:** Sprint 5 ✅ Complete | **Stack:** Java 21 + Spring Boot 4.0.6 + Next.js 15.5.18 | **Tests:** 190+ automated tests | **Legal:** CanG §19 compliant --- @@ -14,7 +14,8 @@ | **Sprint 2** — REST API | 5 controllers, JWT auth, Spring Security 7, OpenAPI, TenantFilterAspect | 12 integration tests | | **Sprint 3** — Staff, Portal & Compliance | Staff permissions (JSONB), token revocation, invite flow, PDF/CSV reports, member portal (session auth), prevention officer, 30+ integration tests | 30+ integration tests | | **Sprint 4** — Frontend MVP | Admin Dashboard + Member Portal (Shadboard, Next.js 15, React 19, 143 files, 23K lines). Login, KPI dashboard, member management (TanStack Table), multi-step distribution form with quota check, batch/stock management with charts, compliance reports. Member portal with radial quota visualization, distribution history, profile. i18n (de/en), dark+light mode, Playwright E2E, Docker multi-stage. | 6 E2E tests | -| **Sprint 5** — Staff UI & API Wiring | _Planned:_ Wire frontend to real backend API, staff management UI, DSGVO consent, WebSocket notifications | — | +| **Sprint 5** — API Integration | React Query integration (mock fallback pattern), Docker Compose full-stack, Staff CRUD UI, system tests with SQL seed + API-driven flows, Vitest + MSW unit testing | 190+ tests (unit + integration + E2E + system) | +| **Sprint 6** — DSGVO & Payments | _Planned:_ DSGVO consent UI, Stripe payments, grow calendar, PWA/offline, Hetzner VPS deploy | — | ## 📋 Documentation @@ -48,11 +49,13 @@ | Testing (Backend) | JUnit 5 + Mockito + Testcontainers (PostgreSQL 16) | | Frontend | Next.js 15 + React 19 + TypeScript | | UI Components | shadcn/ui (Radix primitives) + Tailwind CSS 4 | +| Data Fetching | @tanstack/react-query (stale-while-revalidate, mock fallback) | | Charts | Recharts | | Tables | TanStack Table v8 | | Frontend Auth | NextAuth v5 (Auth.js) | | Frontend i18n | next-intl | -| Frontend Testing | Playwright (E2E) | +| Frontend Testing | Vitest + MSW (unit) · Playwright (E2E + system) | +| Container Stack | Docker Compose (backend + frontend + PostgreSQL) | | API Docs | SpringDoc OpenAPI 2.8.6 · Swagger UI | | Build | Maven multi-module (backend) · pnpm (frontend) | | Hosting | Hetzner VPS (German DC) · Docker Compose | @@ -89,9 +92,10 @@ cannamanage/ | Entities | 11 (Member, Distribution, MonthlyQuota, Batch, Strain, StockMovement, Club, User, StaffAccount, RevokedToken, InviteToken) | | API Endpoints | 25+ across 9 controllers | | Total Files | 200+ (backend + frontend) | -| Test Coverage | 67+ backend tests (unit + integration) + 6 Playwright E2E | +| Test Coverage | 190+ automated tests (unit + integration + E2E + system) | | Flyway Migrations | V1–V5 (initial schema → staff/portal → club settings → invite tokens) | | Frontend Pages | 14 routes (10 admin + 4 portal) | +| Frontend Version | Next.js 15.5.18 | | Security Scan | SAST + SCA clean (Snyk Code, SonarQube) | ## 🔗 Links diff --git a/_Sidebar.md b/_Sidebar.md index 1853e80..9f7b751 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -30,4 +30,5 @@ | 2 — API | ✅ | | 3 — Staff & Portal | ✅ | | 4 — Frontend MVP | ✅ | -| 5 — Staff UI & Wiring | 📋 | +| 5 — API Integration | ✅ | +| 6 — DSGVO & Payments | 📋 |