Lars/BuyingAgent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
BuyingAgent/.specs/buying-agent-frontend-mvp-spec-v0.1.md
Lars b276758ee1
All checks were successful
Deploy Development / deploy (push) Successful in 1m19s
Details
Test Suite / pytest-backend (push) Successful in 31s
Details
Test Suite / smoke-dev (push) Successful in 0s
Details
Test Suite / frontend-checks (push) Successful in 28s
Details
Stelle den Frontend-MVP und die v0.3-API auf develop bereit, damit Dev API und PWA zusammen deployen. 
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-04 13:04:59 +02:00

17 KiB
Raw Permalink Blame History

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:

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:

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:

Sidebar
+ Hauptinhalt
+ optionaler Detailbereich

Beispiel:

┌───────────────┬──────────────────────────────────────┐
│ 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:

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:

Projekte
Admin

Optional:

Systemstatus

Noch nicht erforderlich:

  • Benutzerverwaltung
  • Warenkorb
  • Benachrichtigungseinstellungen
  • Account-/Profilverwaltung

6. Screen 1 – BuyingProject-Liste

Route:

/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:

ACTIVE
PURCHASED
ARCHIVED
OUT_OF_SYNC
BLOCKED
TOO_BROAD

Die Liste darf keine produktkategoriespezifischen Felder voraussetzen.

7. Screen 2 – BuyingProject anlegen

Route:

/projects/new

Schritt 1 – Basisdaten

Mindestens:

name
source
source_category
market
currency
shortlist_size
schedule_interval

Default:

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:

SourceCategory
    ↓
SourceFilterDefinitions
    ↓
CriterionDefinitions
    ↓
CriterionMappings

Das Frontend rendert Controls anhand des Typs.

Unterstützte Control-Typen

BOOLEAN
ENUM
MULTI_ENUM
NUMERIC_RANGE
NUMERIC_THRESHOLD
TEXT

Für ein Kriterium sollen mindestens konfigurierbar sein:

operator
value
mandatory / optional

Wenn vom Scoring unterstützt zusätzlich:

weight
preference strategy
acceptable
ideal
direction

Sichtbarer Mapping-Status

Pro Kriterium:

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:

criteria_version++

Die bestehende DiscoverySearch wird:

OUT_OF_SYNC

Danach muss das Backend eine neue Query aus den aktuellen:

Criteria
+
VERIFIED Mappings

erzeugen.

Das Frontend zeigt klar:

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

Aktion:

Suche aktualisieren

Danach:

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

10. Screen 3 – BuyingProject-Detail

Route:

/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:

/projects/:projectId/candidates

Darstellung:

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

Mindestens:

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:

/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:

/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:

Top 5

konfigurierbar am BuyingProject.

14. Screen 7 – Search Runs / Historie

Route:

/projects/:projectId/history

Anzeige:

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:

/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:

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

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

Projektkriterien

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

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

Criterion Definitions / Mappings

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

Discovery Search

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

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

Candidates

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

SUCCESS
PARTIAL
FAILED
BLOCKED
TOO_BROAD
OUT_OF_SYNC

Candidate Diff

NEW
CHANGED
UNCHANGED
MISSING
DISAPPEARED

Matching

MATCHED
MATCH_UNCERTAIN

Mapping

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:

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:

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:

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:

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