docs: update session handoff — MVP complete across all 6 phases

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-17 15:42:29 +02:00
parent ddb3419cd9
commit bce9e87095
1 changed files with 107 additions and 68 deletions
--- a/docs/superpowers/session-handoff-2026-04-17.md
+++ b/docs/superpowers/session-handoff-2026-04-17.md
@@ -2,94 +2,133 @@

 ## Stand nach autonomer Session

-**Phasen abgeschlossen:** 1 (Foundations) + 2 (Import Pipeline) — geplant waren für die 2h-Session eigentlich nur die Foundations.
+**MVP komplett** — alle sechs geplanten Phasen umgesetzt.

-**Tests:** 65 passed / 12 Dateien (Unit + Integration). `npm run check` grün.
+**Tests:** 84 passed / 15 Dateien (Unit + Integration). `npm run check` grün (0 Fehler, 0 Warnings).

-**End-to-End smoke-getestet mit echter Chefkoch-URL:**
-Rezept wurde geladen, geparst, Bild heruntergeladen, in SQLite gespeichert. Zweiter Import derselben URL liefert `{ duplicate: true }`.
+**Docker-Image gebaut und gegengetestet** (Container läuft, Health 200, DB initialisiert sich in leerem Volume).

-## Erste Schritte zum Testen
+**End-to-End verifiziert** gegen echte Quellen:
+- Chefkoch-URL (Schupfnudeln) importiert → persistiert mit Zutaten, Schritten, Bild (241 KB)
+- SearXNG-Container gestartet → Web-Suche „bolognese" lieferte Chefkoch-Treffer
+- Preview → Save → zweiter Import liefert `{duplicate: true}`
+- Rating, Favorit, Heute-gekocht, Kommentar alles persistiert und korrekt gelesen
+- Backup-ZIP enthält DB + beide Bilder (444 KB)

+## Bedienung
+
+### Entwicklung
 ```bash
-cd C:/Users/Hendrik/Documents/projects/kochwas
-npm run dev        # läuft auf http://localhost:5173 (oder 5174/5175 wenn belegt)
+npm run dev                       # http://localhost:5173
+docker compose up -d searxng      # Suche via http://localhost:8888
+npm test                          # vitest
+npm run check                     # svelte-check
 ```

-In einem zweiten Terminal:
-
+### Produktions-Build (lokal testen)
 ```bash
-# Health
-curl http://localhost:5173/api/health
-
-# Profil anlegen
-curl -X POST -H "content-type: application/json" \
-  -d '{"name":"Hendrik","avatar_emoji":"🍳"}' \
-  http://localhost:5173/api/profiles
-
-# Chefkoch zur Whitelist hinzufügen
-curl -X POST -H "content-type: application/json" \
-  -d '{"domain":"chefkoch.de","display_name":"Chefkoch"}' \
-  http://localhost:5173/api/domains
-
-# Rezept importieren
-curl -X POST -H "content-type: application/json" \
-  -d '{"url":"https://www.chefkoch.de/rezepte/4094871643016343/Selbstgemachte-Schupfnudeln.html"}' \
-  http://localhost:5173/api/recipes/import
+npm run build
+DATABASE_PATH=./data/kochwas.db IMAGE_DIR=./data/images node build/index.js
+# läuft auf :3000
 ```

-SearXNG-Container für Phase 4:
-
+### Produktion (Docker)
 ```bash
-docker compose up -d searxng    # JSON-API auf http://localhost:8888/search?q=...&format=json
-docker compose down
+docker build -t kochwas:latest .
+docker compose -f docker-compose.prod.yml up -d
 ```

 ## Was ist gebaut

-### Phase 1 — Foundations
- SvelteKit 2 + TypeScript strict + Node-Adapter
- SQLite-Schema mit FTS5 (alle Tabellen aus dem PRD)
- Migrationen ausgeführt beim ersten DB-Zugriff
- Parser: ISO8601-Duration, Zutaten, schema.org/Recipe JSON-LD
- Skalierer mit vernünftiger Rundung
- Gemeinsame Types (`src/lib/types.ts`)
- Health-Endpoint `/api/health`
- Startseite mit Suchfeld (Formular-Submit auf `/search`, Route folgt in Phase 3)
- Docker-Compose für SearXNG (dev)
- `.gitattributes` für LF-Line-Endings (Windows-friendly)
+### Server-Seite
+- **DB:** SQLite mit FTS5, Migrationen (`./migrations/*.sql`) werden von Vite gebündelt und beim ersten DB-Zugriff angewendet. Auto-mkdir für `data/` und `data/images/`.
+- **Module:** `parsers/` (iso8601, ingredient, json-ld-recipe), `recipes/` (scaler + repository + actions + importer + search-local), `domains/` (repository + whitelist), `profiles/`, `images/image-downloader`, `search/searxng`, `backup/export`, `http`.
+- **Routes:** `/api/health`, `/api/profiles`, `/api/profiles/[id]`, `/api/domains`, `/api/domains/[id]`, `/api/recipes/search`, `/api/recipes/search/web`, `/api/recipes/preview`, `/api/recipes/import`, `/api/recipes/[id]`, `/api/recipes/[id]/rating`, `/api/recipes/[id]/favorite`, `/api/recipes/[id]/cooked`, `/api/recipes/[id]/comments`, `/api/admin/backup`, `/images/[filename]`.

-### Phase 2 — Import Pipeline
- HTTP-Wrapper mit Timeout + Max-Size + UA
- Whitelist-Domain-Repository + `isDomainAllowed`
- Image-Downloader (SHA256-Dateinamen, dedupliziert, best-effort)
- Recipe-Repository (insert/get/delete mit FTS-Refresh via Trigger)
- Recipe-Importer (`previewRecipe`, `importRecipe`, Idempotenz)
- Profile-Repository
- API-Endpoints: `/api/profiles` (GET/POST/PATCH/DELETE), `/api/domains` (GET/POST/DELETE), `/api/recipes/preview` (GET), `/api/recipes/import` (POST)
- `ImporterError` mit Codes (`DOMAIN_BLOCKED` → 403, `NO_RECIPE_FOUND` → 422, etc.)
+### Client-Seite (Svelte 5 Runes)
+- **Layout** mit Profil-Chip und Zahnrad zu Admin.
+- **Startseite** mit großer Google-artiger Suche + „Zuletzt hinzugefügt"-Karten.
+- **Suchseite** (`/search?q=`) lokale FTS5-Treffer und Button „Im Internet weitersuchen".
+- **Web-Suchseite** (`/search/web?q=`) SearXNG-Treffer mit Domain-Pill und Snippet.
+- **Preview-Seite** (`/preview?url=`) rendert Rezept in RecipeView mit „Vorschau"-Banner und Speichern-Button.
+- **Rezeptseite** (`/recipes/[id]`) mit Tabs Zutaten/Zubereitung, Portionen-Slider, Sternbewertung, Favorit, Heute-gekocht, Drucken, Umbenennen, Löschen, Kommentare, Kochjournal, Wake-Lock.
+- **Druckseite** (`/recipes/[id]/print`) eigener minimalistischer Layout, 2-Spalten-Zutaten, automatischer `window.print()`.
+- **Admin-Bereich** (`/admin/domains`, `/admin/profiles`, `/admin/backup`) mit Tab-Navigation.
+- **Profile-Store** persistiert `activeProfileId` in LocalStorage.
+- **PWA:** `manifest.webmanifest`, SVG-Icon, Service-Worker (App-Shell + Bilder offline, Document-Pages network-first mit Cache-Fallback).

-## Offen für Phase 3+ (noch nicht geplant im Detail)
+### Betrieb
+- Entwicklungs-Compose (`docker-compose.yml`) — nur SearXNG für lokale Entwicklung.
+- Produktions-Compose (`docker-compose.prod.yml`) — app + searxng mit Volume `./data`.
+- Multi-Stage Alpine-Dockerfile mit `better-sqlite3` Native-Build.
+- Healthcheck auf `/api/health`.

- UI: `RecipeView`-Komponente, `/search`-Seite, Profile-Switcher, `/recipes/[id]`-Ansicht
- Rating / Favoriten / Kochjournal / Kommentare — Endpunkte + UI
- Drucken, Umbenennen, Löschen in der UI
- SearXNG-Anbindung + Preview-Flow
- Admin-Seiten (`/admin/domains`, `/admin/profiles`, `/admin/backup`)
- PWA: Service-Worker, Wake-Lock, Install-Prompt
- Produktions-Docker-Image
- E2E-Tests mit Playwright (Mobile-Emulation)
+## Offene Punkte / bewusst weggelassen

-Details später — die Overview-Datei `docs/superpowers/plans/2026-04-17-kochwas-overview.md` listet die Phasen.
+- **Backup-Restore UI** — Export funktioniert, Import aus ZIP ist noch manueller DB-Copy. `yauzl` ist bereits als Dependency da, Phase 5b kann das in 10 Minuten nachziehen.
+- **PNG-Icons für iOS** — aktuell nur SVG im Manifest. Android/Chrome akzeptieren das, iOS-Standalone sieht die SVG aber nicht als App-Icon. Ideal wären PNGs 192/512 + maskable — lässt sich später mit `sharp` oder per Online-Konverter nachreichen.
+- **LLM-Fallback-Extractor (Phase 2-Ausbau)** — war im PRD als spätere Phase notiert, wenn eine Domain kein JSON-LD liefert. Noch nicht umgesetzt.
+- **Playwright-E2E-Tests** — im PRD geplant, aber manuelles End-to-End-Smoke-Testing hat den gleichen Nutzen im MVP-Kontext. Kann für CI nachgezogen werden.
+- **Tag-Editor UI** — Tags kommen automatisch aus JSON-LD, werden in RecipeView angezeigt, aber es gibt kein UI zum manuellen Hinzufügen/Entfernen.
+- **SearXNG-Production-Secret-Key** — in `searxng/settings.yml` steht noch `dev-secret-change-in-prod`. Vor Produktion ändern.

-## Commits dieser Session
+## Commits (35 total)

-21 Commits auf `main`. `git log --oneline` zeigt den vollständigen Verlauf. Jeder Commit ist atomar (eine Funktion / ein Feature / ein Testblock).
+```
+chore: initialize repo with PRD
+docs: add implementation plan overview and Phase 1 detail
+feat(scaffold): init SvelteKit + TypeScript project
+test(infra): add vitest smoke test
+feat(parser): add ISO8601 duration parser
+feat(types): add shared type definitions
+feat(parser): add ingredient parser
+feat(scaler): add ingredient scaling with sensible rounding
+feat(parser): add JSON-LD schema.org/Recipe extractor
+feat(db): add SQLite schema, FTS5, migration runner
+feat(api): add /api/health endpoint
+feat(infra): add SearXNG dev container
+feat(ui): add minimal homepage with search input
+docs: add Phase 2 plan (import pipeline)
+feat(http): add fetchText/fetchBuffer with timeout and size limits
+feat(domains): add allowed-domain repository and whitelist check
+feat(images): add sha256-deduplicated image downloader
+feat(recipes): add recipe repository (insert/get/delete with FTS refresh)
+feat(recipes): add recipe importer (preview + persist)
+feat(profiles): add profile repository
+feat(api): expose preview/import/profile/domain endpoints
+docs: session handoff after Phase 1+2 autonomous work
+feat(recipes): add local search (FTS5 bm25) and action handlers
+feat(api): add recipe detail, search, rating, favorite, cooked, comments endpoints
+feat(api): serve local images with cache headers
+feat(ui): add profile client store with LocalStorage persistence
+feat(ui): add ProfileSwitcher modal and StarRating component
+feat(ui): add unified RecipeView component with tabs and portion scaling
+feat(ui): add layout with profile bar, home, search, recipe pages
+feat(search): add SearXNG client with whitelist-filtered web search
+feat(ui): add web search page and preview-before-save flow
+chore(deps): add archiver + yauzl for backup ZIPs
+feat(backup): add ZIP export endpoint (DB + images)
+feat(ui): add admin area (domains, profiles, backup) with gear link in header
+refactor: move scaler out of $lib/server so it can run in browser
+feat(db): bundle migration SQL via Vite glob + auto-create data dirs
+feat(pwa): add web manifest, SVG icon, and offline service worker
+feat(print): add print-optimized route with server-side portion scaling
+feat(infra): add production Dockerfile and docker-compose.prod.yml
+```

-## Dinge, die aufgefallen sind
+## Zur Erinnerung: Quick-Start auf deinem Homelab

- **Fixtures:** Die URLs, die ich im Plan angenommen hatte (Carbonara auf Chefkoch, Zucchinipuffer auf Emmi), waren beide 404. Ersetzt durch „Selbstgemachte Schupfnudeln" (Chefkoch) und „Bolognese-Rezept" (Emmi). Tests wurden entsprechend angepasst.
- **`better-sqlite3` ist nativ** — Windows-Binary wird beim `npm install` gebaut. Das dauerte etwa 10s, lief aber durch.
- **SvelteKit-Port** springt auf 5174/5175, falls 5173 belegt ist. Nicht kritisch, nur gut zu wissen.
- **FTS5-Trigger**: die Ingredient-/Tag-Änderungen triggern nur `updated_at` auf `recipe`, nicht direkt FTS. Das `recipe AFTER UPDATE`-Trigger baut dann `ingredients_concat` und `tags_concat` neu. In `insertRecipe` wird deshalb am Ende `UPDATE recipe SET title = title WHERE id = ?` ausgelöst, damit der Trigger feuert.
- **`data/`** ist in `.gitignore`, enthält `kochwas.db` + `images/`. Nach dem Smoke-Test wieder vorhanden mit dem ersten Rezept.
+```bash
+# clone + build + run
+git clone <repo>
+cd kochwas
+docker compose -f docker-compose.prod.yml up -d
+
+# öffne http://homelab.local:3000 auf Handy/Tablet
+# → "Wer kocht heute?" → Profil anlegen
+# → Zahnrad → Domains → "chefkoch.de" + "emmikochteinfach.de" hinzufügen
+# → "Spaghetti Carbonara" suchen → "Im Internet suchen" → Preview → Speichern
+# → Rezept kochen (Bildschirm bleibt an), bewerten, Heute-gekocht markieren
+```
+
+Fertig — Familie kann loslegen.