BuyingAgent/.specs/buying-agent-frontend-mvp-spec-v0.1.md

# Buying Agent – Frontend MVP Specification v0.1

**Status:** implementierungsbereit  
**Spezifikationsversion:** 0.1  
**Stand:** 2026-10-04  

**Ergänzt verbindlich:**
1. `buying-agent-v0.1-spec-v1.1.md`
2. `buying-agent-architecture-addendum-v1.md`
3. `buying-agent-source-discovery-spec-v0.1.md`

Diese Frontend-Spezifikation hebt für den nutzbaren MVP die frühere Aussage „kein Frontend in diesem Slice“ auf.  
Sie ändert keine fachliche Backend-Logik; sie definiert die Benutzeroberfläche und die dafür notwendigen API-Verträge.

---

## 1. Ziel

Der Buying Agent soll als **nutzbare PWA** einen vollständigen vertikalen Ablauf unterstützen:

```text
BuyingProject anlegen
    ↓
Produktkategorie wählen
    ↓
dynamische Kriterien aus Source-Taxonomie auswählen
    ↓
Kriterien konfigurieren
    ↓
Geizhals-Suche generieren
    ↓
SearchRun starten / Status verfolgen
    ↓
Kandidaten sehen
    ↓
Ranking + Shortlist sehen
    ↓
Kandidat öffnen
    ↓
Status, Historie, bisherige Ergebnisse und Empfehlungen sehen
    ↓
Kriterien bei Bedarf anpassen
```

Der MVP muss diesen Flow über die Oberfläche vollständig nutzbar machen.

---

## 2. Technologiestack

Frontend:

- React
- TypeScript
- Vite
- PWA
- TanStack Query für Server-State / Data Fetching
- React Router oder äquivalente schlanke Routing-Lösung
- schlanke komponentenbasierte UI
- kein Next.js
- kein SSR
- keine SEO-Anforderungen

Das Frontend liegt im bestehenden Monorepo:

```text
buying-agent/
├── backend/
├── frontend/
├── docs/
└── docker-compose.yml
```

Backend bleibt System of Record.

---

## 3. Gestaltungsprinzipien

1. **Einfach für Standardnutzer, leistungsfähig im Hintergrund.**
2. Keine technische Datenbank-/Engine-Sicht in der Standardoberfläche.
3. Dynamische Kriterien statt fest verdrahteter Notebook-Felder.
4. Responsive von Anfang an.
5. Zwei bewusst gestaltete Hauptlayouts:
   - Desktop
   - Mobile
6. Nüchternes, klares Design.
7. Bedienbarkeit vor visueller Komplexität.
8. Admin-/Source-Themen von der normalen Nutzung trennen.
9. Keine Businesslogik im Frontend.
10. Frontend konsumiert ausschließlich die versionierte Backend-API.

---

## 4. PWA und Responsive Layout

### Desktop

Desktop verwendet primär:

```text
Sidebar
+ Hauptinhalt
+ optionaler Detailbereich
```

Beispiel:

```text
┌───────────────┬──────────────────────────────────────┐
│ Buying Agent  │ Projekt: Mobiler Entwicklungsrechner│
│               │                                      │
│ Projekte      │ Status / Suche / Ranking / Shortlist│
│ Admin         │                                      │
│ Einstellungen │                                      │
└───────────────┴──────────────────────────────────────┘
```

### Mobile

Mobile verwendet primär:

- Bottom Navigation oder kompakte Hauptnavigation
- Vollbild-Detailseiten
- Tabs innerhalb eines BuyingProjects
- keine verkleinerte Desktop-Sidebar

Beispiel:

```text
Projekt
────────────────
Übersicht
Kandidaten
Shortlist
Kriterien
Historie

[ Projekte ] [ Suche ] [ Admin ]
```

### Mitai-Bezug

Falls im bestehenden Mitai-Code wiederverwendbare Layout-, PWA-, Responsive- oder Navigationsmuster vorhanden sind, sollen diese bevorzugt übernommen oder konsistent nachgebildet werden.

Keine fachliche Kopplung an Mitai.

---

## 5. Hauptnavigation

Der MVP benötigt mindestens:

```text
Projekte
Admin
```

Optional:

```text
Systemstatus
```

Noch nicht erforderlich:

- Benutzerverwaltung
- Warenkorb
- Benachrichtigungseinstellungen
- Account-/Profilverwaltung

---

## 6. Screen 1 – BuyingProject-Liste

Route:

```text
/projects
```

Funktionen:

- aktive BuyingProjects anzeigen
- Projektname
- Kategorie
- Status
- letzter erfolgreicher SearchRun
- Anzahl Kandidaten
- Anzahl Shortlist-Kandidaten
- aktueller Discovery-Status
- Button „Neues Projekt“

Mögliche Status:

```text
ACTIVE
PURCHASED
ARCHIVED
OUT_OF_SYNC
BLOCKED
TOO_BROAD
```

Die Liste darf keine produktkategoriespezifischen Felder voraussetzen.

---

## 7. Screen 2 – BuyingProject anlegen

Route:

```text
/projects/new
```

### Schritt 1 – Basisdaten

Mindestens:

```text
name
source
source_category
market
currency
shortlist_size
schedule_interval
```

Default:

```text
shortlist_size = 5
schedule_interval_minutes = 180
```

### Schritt 2 – Kriterien

Nach Auswahl der Source-Kategorie lädt das Frontend dynamisch:

- Canonical Criteria
- Source Filter Definitions
- CriterionMappings
- Mapping-Status

Das Frontend erzeugt daraus dynamisch die Eingabefelder.

Es gibt **keine fest codierten Notebook-Felder**.

---

## 8. Dynamische Kriterien

Verfügbare Kriterien entstehen aus:

```text
SourceCategory
    ↓
SourceFilterDefinitions
    ↓
CriterionDefinitions
    ↓
CriterionMappings
```

Das Frontend rendert Controls anhand des Typs.

### Unterstützte Control-Typen

```text
BOOLEAN
ENUM
MULTI_ENUM
NUMERIC_RANGE
NUMERIC_THRESHOLD
TEXT
```

Für ein Kriterium sollen mindestens konfigurierbar sein:

```text
operator
value
mandatory / optional
```

Wenn vom Scoring unterstützt zusätzlich:

```text
weight
preference strategy
acceptable
ideal
direction
```

### Sichtbarer Mapping-Status

Pro Kriterium:

```text
VERIFIED
LEARNED_UNVERIFIED
INTERNAL_ONLY
BROKEN
DISABLED
```

Standardnutzer sollen primär verständliche Hinweise sehen:

- „Wird direkt bei Geizhals gefiltert“
- „Wird erst intern bewertet“
- „Filter derzeit nicht verfügbar“

Technische IDs bleiben im Admin-Bereich.

---

## 9. Kriterienänderungen

Wenn Kriterien geändert werden:

```text
criteria_version++
```

Die bestehende DiscoverySearch wird:

```text
OUT_OF_SYNC
```

Danach muss das Backend eine neue Query aus den aktuellen:

```text
Criteria
+
VERIFIED Mappings
```

erzeugen.

Das Frontend zeigt klar:

```text
Suchkriterien wurden geändert.
Die externe Suche muss aktualisiert werden.
```

Aktion:

```text
Suche aktualisieren
```

Danach:

```text
generate-query
→ optional run
→ neuer SearchRun
→ neues Ranking
```

---

## 10. Screen 3 – BuyingProject-Detail

Route:

```text
/projects/:projectId
```

Desktop: strukturierte Detailansicht.

Mobile: Tabs.

Mindestens folgende Bereiche:

### Übersicht

- Projektstatus
- Kategorie
- letzter SearchRun
- Discovery-Status
- Trefferzahl
- Kandidatenzahl
- Shortlist-Größe
- Zeitpunkt nächste geplante Suche
- wichtige Warnungen

### Kandidaten

- aktuelle Kandidaten
- ProductScore
- product_eligibility
- aktueller best_price, sofern vorhanden
- Diff-Status
- Lifecycle-Status
- Shortlist-Markierung

### Shortlist

Top-N gemäß Projektkonfiguration.

### Kriterien

Dynamische Kriterien anzeigen und bearbeiten.

### Historie

- SearchRuns
- wichtige Statusänderungen
- bisherige Rankings
- soweit vorhanden frühere Bewertungen / Empfehlungen

---

## 11. Screen 4 – Kandidatenliste

Route:

```text
/projects/:projectId/candidates
```

Darstellung:

- sortierbare Liste/Tabelle auf Desktop
- Cards/List Items auf Mobile

Mindestens:

```text
Produktname
Hersteller
wichtige dynamische Attribute
best_price
ProductScore
product_eligibility
diff_status
lifecycle_status
shortlist_status
last_seen
```

### Dynamische Attribute

Welche Eigenschaften sichtbar sind, darf nicht notebook-spezifisch hart codiert sein.

Mögliche Strategie:

1. Source-/Category-Definition liefert relevante display attributes.
2. Projekt kann später bevorzugte sichtbare Attribute konfigurieren.
3. MVP darf zunächst die wichtigsten vorhandenen normalisierten Attribute anzeigen.

---

## 12. Screen 5 – Kandidatendetail

Route:

```text
/projects/:projectId/candidates/:candidateId
```

Der Nutzer soll in ein Produkt „hineinspringen“ können.

Mindestens:

### Aktueller Status

- Name
- Hersteller
- Source-Link
- ProductScore
- product_eligibility
- Shortlist-Status
- aktueller best_price
- letzte Sichtung

### Attribute

Alle verfügbaren normalisierten dynamischen Produktattribute.

Keine notebook-spezifische Feldliste.

### Historie

- Preisentwicklung aus ProductObservations
- relevante Attributänderungen
- NEW / CHANGED / MISSING / DISAPPEARED
- SearchRun-Bezug

### Bewertungen / Ergebnisse

- aktuelle Bewertung
- frühere gespeicherte Bewertungen, soweit Backend vorhanden
- Gründe / Constraint-Ergebnisse
- Coverage / fehlende Daten

### Spätere Erweiterbarkeit

Dieser Screen wird später Zielort für:

- Deep Enrichment
- Tests
- Reviews
- Benchmarks
- Händlervergleich
- Kaufempfehlung

Diese Funktionen sind noch nicht Bestandteil dieses MVP-Slices.

---

## 13. Screen 6 – Shortlist

Route:

```text
/projects/:projectId/shortlist
```

Zweck:

Nur die aktuell relevantesten Produkte zeigen.

Mindestens:

- Rang
- Produkt
- ProductScore
- Product Eligibility
- aktueller Preis
- relevante Stärken
- relevante Schwächen / fehlende Daten
- letzter Änderungsstatus

Default:

```text
Top 5
```

konfigurierbar am BuyingProject.

---

## 14. Screen 7 – Search Runs / Historie

Route:

```text
/projects/:projectId/history
```

Anzeige:

```text
Zeitpunkt
Status
Trefferzahl
Page Count
NEW
CHANGED
MISSING
DISAPPEARED
TOO_BROAD
Fehler / BLOCKED
```

Ein SearchRun muss geöffnet werden können, um Detailinformationen zu sehen.

Kein HTML anzeigen oder archivieren.

---

## 15. Screen 8 – Admin: Taxonomie & Mapping

Route:

```text
/admin/sources
/admin/sources/:source/categories/:category
```

Dieser Bereich darf technischer sein.

Funktionen:

- gelernte Kategorien sehen
- SourceFilterDefinitions sehen
- SourceFilterOptions/Ranges sehen
- Canonical Criteria sehen
- CriterionMappings sehen
- Mapping-Status ändern
- fehlerhafte kleine Mapping-Änderungen direkt korrigieren
- BROKEN / DISABLED erkennen
- Taxonomie neu einlesen
- Query-Mapping nachvollziehen

### Wichtig

Das Frontend darf kein URL-Encoding selbst erfinden.

Es editiert/pflegt nur persistierte Mapping-Daten.

Backend bleibt für Validierung und Query-Generation verantwortlich.

---

## 16. Server State und Data Fetching

Empfehlung:

```text
TanStack Query
```

für:

- Projekte
- Kriterien
- Taxonomie
- Mappings
- SearchRuns
- Kandidaten
- Shortlist
- Produktdetails

Client-State nur für:

- UI-Zustände
- Formulare
- Tabs
- lokale Filter

Keine fachlich relevante Server-Wahrheit ausschließlich im Browser halten.

---

## 17. API-Verträge

Das Frontend nutzt mindestens:

### Projekte

```text
GET  /api/v1/buying-projects
POST /api/v1/buying-projects
GET  /api/v1/buying-projects/{id}
PATCH /api/v1/buying-projects/{id}
```

### Projektkriterien

```text
GET  /api/v1/buying-projects/{id}/criteria
PUT  /api/v1/buying-projects/{id}/criteria
```

Falls Backend intern versionierte Ressourcen bevorzugt, kann PUT eine neue Version erzeugen.

### Taxonomie

```text
POST /api/v1/sources/{source}/categories/{category}/discover-taxonomy
GET  /api/v1/sources/{source}/categories/{category}/filters
```

### Criterion Definitions / Mappings

```text
GET   /api/v1/criterion-definitions
GET   /api/v1/criterion-mappings
POST  /api/v1/criterion-mappings
PATCH /api/v1/criterion-mappings/{id}
```

### Discovery Search

```text
GET  /api/v1/buying-projects/{id}/discovery-search
POST /api/v1/discovery-searches/{id}/generate-query
POST /api/v1/discovery-searches/{id}/run
```

### Search Runs

```text
GET /api/v1/discovery-searches/{id}/runs
GET /api/v1/search-runs/{id}
```

### Candidates

```text
GET /api/v1/buying-projects/{id}/candidates
GET /api/v1/buying-projects/{id}/shortlist
GET /api/v1/buying-projects/{id}/candidates/{candidateId}
```

---

## 18. Status- und Fehlerdarstellung

Frontend muss mindestens folgende Zustände sichtbar machen:

### Discovery

```text
SUCCESS
PARTIAL
FAILED
BLOCKED
TOO_BROAD
OUT_OF_SYNC
```

### Candidate Diff

```text
NEW
CHANGED
UNCHANGED
MISSING
DISAPPEARED
```

### Matching

```text
MATCHED
MATCH_UNCERTAIN
```

### Mapping

```text
DISCOVERED
LEARNED_UNVERIFIED
VERIFIED
BROKEN
DISABLED
INTERNAL_ONLY
```

Fehlertexte für Standardnutzer verständlich formulieren.

Technische Details optional aufklappbar.

---

## 19. Loading / Empty / Error States

Jeder Screen braucht explizit:

- Loading
- Empty
- Error
- Retry

Beispiele:

```text
Noch keine Kandidaten gefunden.
Noch kein SearchRun ausgeführt.
Taxonomie wurde noch nicht geladen.
Diese Suche ist derzeit BLOCKED.
Die Kriterien wurden geändert; Suche ist OUT_OF_SYNC.
```

---

## 20. PWA-Grundgerüst

Mindestens:

- installierbare PWA
- Manifest
- Icons / App-Metadaten
- responsive shell
- app-like navigation
- sinnvolle Offline-Fallback-Seite

Keine Offline-Businesslogik erforderlich.

Keine komplexe Synchronisationslogik in v0.1.

---

## 21. Tests

### Unit / Component

- dynamischer Criterion Renderer je Filtertyp
- Mapping-Status-Darstellung
- Candidate Status-Darstellung
- responsive Komponenten
- Formvalidierung

### API Integration

- Projektliste
- Projektanlage
- Kriterien laden/speichern
- SearchRun starten
- Kandidaten laden
- Shortlist laden
- Admin-Mapping aktualisieren

### E2E

Mindestens ein vollständiger Notebook-Pilot:

```text
Projekt anlegen
→ Kategorie Notebooks
→ dynamische Kriterien laden
→ Kriterien setzen
→ Geizhals Query generieren
→ SearchRun starten
→ Kandidaten erscheinen
→ Ranking sichtbar
→ Shortlist sichtbar
→ Kandidat öffnen
→ Historie sichtbar
→ Kriterium ändern
→ OUT_OF_SYNC sichtbar
→ Query neu erzeugen
```

### Responsive E2E

Mindestens:

- Desktop-Viewport
- Mobile-Viewport

---

## 22. Nicht implementieren

In diesem Slice weiterhin nicht:

- Login/Auth
- RBAC
- Einladungen
- Multi-User-UI
- Keepa
- Idealo
- WhatsApp
- Warenkorb
- Kaufautomatisierung
- LLM-Automation
- Deep Enrichment
- finale Decision Engine

Die Architektur darf diese Erweiterungen nicht verbauen.

---

## 23. Definition of Done

- [ ] React + TypeScript + Vite Frontend existiert im Monorepo.
- [ ] PWA ist installierbar.
- [ ] Desktop- und Mobile-Layouts sind bewusst getrennt gestaltet.
- [ ] BuyingProjects können über die UI angelegt und geöffnet werden.
- [ ] Produktkategorie kann ausgewählt werden.
- [ ] Kriterien werden dynamisch aus Taxonomie / CriterionDefinitions erzeugt.
- [ ] Keine notebook-spezifischen Criteria-Felder im Frontend-Core.
- [ ] Kriterien können bearbeitet und gespeichert werden.
- [ ] Mapping-Status ist sichtbar.
- [ ] INTERNAL_ONLY-Kriterien können gespeichert werden.
- [ ] Discovery Search kann generiert werden.
- [ ] SearchRun kann aus der UI gestartet werden.
- [ ] SearchRun-Status ist sichtbar.
- [ ] Kandidatenliste funktioniert.
- [ ] Ranking ist sichtbar.
- [ ] Shortlist funktioniert.
- [ ] Kandidatendetail zeigt dynamische Attribute und Historie.
- [ ] Projekt-Historie zeigt SearchRuns und relevante Änderungen.
- [ ] Kriterienänderung setzt/zeigt OUT_OF_SYNC und ermöglicht Regeneration.
- [ ] Admin-Bereich erlaubt Prüfung/Korrektur von Source-Taxonomie und Mappings.
- [ ] Loading-/Empty-/Error-Zustände existieren.
- [ ] E2E-Test des vollständigen Notebook-Piloten ist grün.
- [ ] Desktop- und Mobile-E2E sind grün.
- [ ] Backend bleibt alleinige Quelle fachlicher Wahrheit.

---

# Coding-Agent-Arbeitsauftrag

Verwende als verbindliche Anforderungen:

1. `buying-agent-v0.1-spec-v1.1.md`
2. `buying-agent-architecture-addendum-v1.md`
3. `buying-agent-source-discovery-spec-v0.1.md`
4. `buying-agent-frontend-mvp-spec-v0.1.md`

Die Frontend-MVP-Spec hebt für den nutzbaren MVP die frühere Scope-Aussage „kein Frontend“ auf.

## 1. Vor Implementierung

Prüfe den aktuellen Repository-Stand gegen alle vier Dokumente.

Berichte kurz:

- welche Backend-APIs für den Frontend-Flow bereits existieren,
- welche Endpunkte fehlen,
- ob aktuelle DTOs dynamische Kriterien und Produktattribute vollständig tragen,
- ob bestehender Code notebook-spezifische Felder enthält,
- welche Änderungen rein additiv möglich sind.

Keine größere strukturelle Abweichung ohne Rückfrage.

## 2. Vertikalen MVP implementieren

Nicht Backend und Frontend getrennt in langen Phasen bauen.

Stattdessen vertikal:

```text
Projektliste
→ Projektanlage
→ dynamische Kriterien
→ Query Generation
→ SearchRun
→ Kandidaten
→ Ranking
→ Shortlist
→ Kandidatendetail
```

Jeder Schritt soll nach Implementierung unmittelbar über die UI prüfbar sein.

## 3. Dynamik sicherstellen

Keine festen Felder wie:

```text
ram_gb
storage_gb
weight_kg
display_inches
```

in generischen Frontend-Komponenten hardcoden.

Controls und sichtbare Produktattribute werden metadata-driven erzeugt.

Notebook-spezifische Werte dürfen nur als gelernte/gespeicherte Daten vorkommen.

## 4. UI

- React + TypeScript + Vite
- PWA
- TanStack Query
- einfache, nüchterne Bedienung
- Desktop: Sidebar + Content/Detail
- Mobile: kompakte Navigation / Bottom Navigation + Vollbild-Details
- vorhandene Mitai-Muster wiederverwenden, falls im zugänglichen Repo vorhanden und passend

## 5. Tests

Führe aus:

- Frontend Unit/Component Tests
- API Integration Tests
- E2E vollständiger Notebook-Pilot
- Desktop E2E
- Mobile E2E

## 6. Abschlussbericht

Dokumentiere:

- implementierte Screens
- neue/angepasste Backend-Endpunkte
- verwendete Frontend-Bibliotheken
- responsive Verhalten
- ausgeführte Tests und Ergebnisse
- offene Abweichungen
- Risiken für spätere Multi-User-, Deep-Enrichment- und Decision-Erweiterungen