Stelle den Frontend-MVP und die v0.3-API auf develop bereit, damit Dev API und PWA zusammen deployen.
Deploy Development / deploy (push) Successful in 1m19s
Test Suite / pytest-backend (push) Successful in 31s
Test Suite / smoke-dev (push) Successful in 0s
Test Suite / frontend-checks (push) Successful in 28s

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
LarsandCursor committed 2026-10-04 13:04:59 +02:00
1 parent 827e6a2a11
commit b276758ee1
152 files changed
+25846 -34

No files matched your search

@@ -0,0 +1,377 @@
# Buying Agent – Architecture Addendum v1
**Status:** ergänzende Architekturvorgabe
**Gültig zusammen mit:** `buying-agent-v0.1-spec-v1.1.md`
**Stand:** 2026-10-03
## 1. Zweck
Dieses Addendum ergänzt die bestehende Spezifikation um übergreifende Architekturentscheidungen für das spätere Zielsystem.
Es ersetzt **nicht** die fachliche Spezifikation `buying-agent-v0.1-spec-v1.1.md`.
Bei Konflikten zwischen beiden Dokumenten hat dieses Addendum für die hier behandelten Architekturthemen Vorrang.
Ziel ist, den aktuellen v0.1-Slice schlank zu halten, ohne spätere Erweiterungen auf Frontend, mehrere Kaufprojekte und mehrere Benutzer unnötig zu erschweren.
---
## 2. Zielstruktur des Repositories
Das Projekt wird als Monorepo strukturiert:
```text
buying-agent/
├── README.md
├── docker-compose.yml
├── .env.example
├── .gitignore
├── docs/
│ ├── buying-agent-v0.1-spec-v1.1.md
│ └── buying-agent-architecture-addendum-v1.md
├── backend/
│ ├── Dockerfile
│ ├── pyproject.toml
│ ├── uv.lock
│ ├── alembic.ini
│ ├── migrations/
│ ├── app/
│ ├── rules/
│ ├── profiles/
│ ├── fixtures/
│ ├── scripts/
│ └── tests/
└── frontend/
└── README.md
```
### Regeln
- `docker-compose.yml` bleibt im Repository-Root.
- Das Backend ist der aktuell implementierte v0.1-Scope.
- `frontend/` wird in v0.1 **nicht implementiert**.
- `frontend/README.md` dokumentiert lediglich, dass dort später die Benutzeroberfläche entsteht.
- Keine zusätzliche `infra/`-Struktur in v0.1, solange sie nicht konkret benötigt wird.
---
## 3. Backend-/Frontend-Grenze
Das Backend bleibt das **System of Record** und besitzt:
- Domain-Modell
- Constraints
- Scoring
- Evaluation
- Persistenz
- Preis- und Produktlogik
- zukünftige Kaufentscheidungslogik
Das spätere Frontend konsumiert ausschließlich die versionierte Backend-API, primär unter:
```text
/api/v1
```
Das Frontend enthält keine fachlich verbindliche Business-Logik.
---
## 4. Zukünftige Multi-User-Architektur
Das Zielsystem soll später von Familie und gegebenenfalls engen Freunden genutzt werden können.
Die Architektur darf daher nicht von einem impliziten Single-User-Modell ausgehen.
Zielmodell:
```text
User
↕
WorkspaceMember
↕
Workspace
↓
BuyingProject
↓
ProjectCandidate
↓
ProductVariant
```
Ein Benutzer kann Mitglied in mehreren Workspaces sein.
Beispiele:
```text
Lars
├── Privat
├── Familie
└── Freunde
```
### Noch nicht Bestandteil von v0.1
Nicht implementieren:
- Login
- Authentifizierung
- Passwortverwaltung
- Einladungen
- RBAC
- komplexe ACLs
- Sharing-UI
- Workspace-Administration
Die aktuelle Architektur darf deren spätere Einführung aber nicht unnötig erschweren.
---
## 5. Globale versus Workspace-bezogene Daten
### Global wiederverwendbare Daten
Diese Entitäten bleiben systemweit gemeinsam nutzbar:
- Product
- ProductVariant
- Offer
- PriceObservation
- AttributeDefinition
- Source
Sie erhalten **keine** `user_id` oder `workspace_id`.
Ein Produkt oder Angebot darf nicht pro Benutzer oder Workspace dupliziert werden.
### Workspace-bezogene Daten
Spätere benutzerbezogene Beschaffungskontexte gehören zu einem Workspace:
- BuyingProject
- ProjectCandidate
- projektspezifische Profil-/Anforderungsauswahl
- Notification Preferences
- Beschaffungsdeadline
- Zielpreis
- Kaufentscheidungsstatus
- gegebenenfalls spätere Warenkorb-/Beschaffungsinformationen
Diese Objekte werden erst in späteren Slices implementiert.
---
## 6. BuyingProject als zukünftiges Kernobjekt
Ein `BuyingProject` repräsentiert ein konkretes Beschaffungsvorhaben.
Beispiele:
- Mobiler Entwicklungsrechner
- Lokaler LLM-Server
- Fernseher
- Kamera
Ein Workspace kann mehrere BuyingProjects parallel besitzen.
Ein BuyingProject kann mehrere ProjectCandidates beobachten.
```text
BuyingProject
├── Candidate A → ProductVariant
├── Candidate B → ProductVariant
└── Candidate C → ProductVariant
```
### Wichtig für v0.1
`BuyingProject` und `ProjectCandidate` müssen in v0.1 noch nicht implementiert werden.
Die aktuelle Implementierung darf jedoch nicht annehmen:
- es existiert genau ein aktives Profil,
- es existiert genau ein Kaufvorhaben,
- es gibt globale Singleton-Konfiguration für einen aktuellen Kauf,
- alle Daten gehören automatisch demselben Benutzer,
- es existiert nur eine gleichzeitig relevante Evaluation.
Mehrere unabhängige Profile und Evaluationen müssen bereits parallel koexistieren können.
---
## 7. Rolle von n8n
n8n bleibt eine externe Orchestrierungsschicht.
Spätere mögliche Aufgaben:
- Scheduler
- Preisabfragen
- Datenimport
- Benachrichtigungen
- externe Integrationen
- volatile oder häufig veränderte Workflows
Kern-Business-Logik bleibt im Programmcode, insbesondere wenn sie:
- deterministisch sein soll,
- versioniert werden muss,
- getestet werden muss,
- fachliche Entscheidungen reproduzierbar machen soll.
n8n darf für veränderliche Prozesslogik eingesetzt werden, aber nicht zur Voraussetzung für das Funktionieren der Buying Engine werden.
---
## 8. Zukünftiges Frontend
Das Zielsystem soll später eine einfach bedienbare Oberfläche erhalten.
Die Standardoberfläche soll auch für nichttechnische Familienmitglieder verständlich bleiben.
Die Engine darf gleichzeitig deutlich leistungsfähiger sein als die Oberfläche.
Voraussichtliche spätere Kernbereiche:
- Übersicht laufender Kaufprojekte
- Kandidaten je Projekt
- aktueller bester Deal
- Preisverlauf
- Produkt-Fit
- Offer-Fit
- DealScore
- verständliche Gründe
- Beobachtungsstatus
- konkrete Kaufempfehlung
- ggf. spätere Benachrichtigungs- und Warenkorbfunktionen
Keine dieser UI-Funktionen ist Bestandteil von v0.1.
---
## 9. Kaufentscheidungslogik
Langfristig soll das System nicht nur Scores liefern, sondern auch konfigurierbare Kaufentscheidungen unterstützen.
Beispiele möglicher Einflussfaktoren:
- Zielpreis
- Maximalpreis
- spätestes Beschaffungsdatum
- aktueller Preis
- Preisentwicklung der letzten Tage/Wochen/Monate
- Abstand zu historischem Median
- Produkt-Fit
- Offer-Fit
- Verfügbarkeit
- Lieferzeit
- Händlerqualität
- alternative Kandidaten
- Beschaffungsdringlichkeit
Die Kaufentscheidung soll nachvollziehbar und möglichst deterministisch bleiben.
LLMs dürfen später Erklärungen, Normalisierung oder qualitative Interpretation unterstützen, sollen aber keine nicht nachvollziehbare Blackbox-Entscheidung erzwingen.
---
## 10. Datenquellen
Das Zielsystem muss mehrere Produkt- und Preisquellen unterstützen können.
Mögliche spätere Quellen:
- Amazon / Keepa
- Preisvergleichsportale
- Hersteller
- Händler
- weitere APIs
v0.1 implementiert weiterhin **keine reale externe Quelle**.
Die bestehende Source-Adapter-Grenze bleibt die vorgesehene Erweiterungsstelle.
---
## 11. Scope-Grenze für die laufende v0.1-Implementierung
Dieses Addendum darf nicht als Anlass dienen, v0.1 unnötig zu vergrößern.
Insbesondere **nicht jetzt implementieren**:
- echtes Frontend
- Authentifizierung
- User Management
- Workspace Management
- RBAC
- Einladungen
- BuyingProject
- ProjectCandidate
- Notifications
- n8n
- externe Preisquellen
- automatische Produktsuche
- Warenkorbmanagement
Ziel ist Architekturkompatibilität, nicht vorgezogene Feature-Entwicklung.
---
## 12. Arbeitsauftrag für die laufende Implementierung
Der Coding-Agent soll vor Fortsetzung des laufenden Builds einen kurzen Architecture-Alignment-Check durchführen.
### Prüfen
1. Entspricht die Repository-Struktur bereits der Monorepo-Struktur mit:
- `backend/`
- `frontend/`
- `docs/`
- Root-`docker-compose.yml`
2. Gibt es Annahmen über:
- genau einen Benutzer,
- genau ein aktives Profil,
- genau ein Kaufprojekt,
- globale Singleton-Zustände?
3. Sind Product, ProductVariant, Offer und PriceObservation weiterhin global und unabhängig von späteren Workspaces modelliert?
4. Ist das Backend klar von zukünftiger Frontend- und n8n-Logik getrennt?
### Änderungen
Nur notwendige strukturelle Anpassungen durchführen.
Keine vorgezogene Multi-User- oder Frontend-Funktionalität implementieren.
Die fachlichen Anforderungen aus `buying-agent-v0.1-spec-v1.1.md` bleiben vollständig gültig.
### Abschlussbericht
Dokumentieren:
- geänderte oder verschobene Dateien,
- notwendige Architekturänderungen,
- Änderungen an Datenbank/Migrationen,
- ausgeführte Tests,
- Testergebnisse,
- verbleibende Risiken für spätere Workspace-/BuyingProject-Erweiterung.
---
## 13. Vorrang und Weiterentwicklung
Dieses Dokument ist ein Architektur-Addendum zur v0.1-Spezifikation.
Nach Abschluss von v0.1 sollen die Erkenntnisse aus:
- `buying-agent-v0.1-spec-v1.1.md`
- diesem Addendum
- der realen Implementierung
in eine konsolidierte Folgespezifikation für den nächsten Slice übernommen werden.
Die Kernregel lautet:
> Nicht vorzeitig bauen, aber bekannte Zielanforderungen nicht architektonisch verbauen.
@@ -0,0 +1,987 @@
# 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
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,986 @@
# Buying Agent – Source & Discovery Specification v0.1
**Status:** implementierungsbereit
**Spezifikationsversion:** 0.1
**Stand:** 2026-10-04
**Ergänzt:** `buying-agent-v0.1-spec-v1.1.md` und `buying-agent-architecture-addendum-v1.md`
## 1. Zweck
Diese Spezifikation definiert den ersten real nutzbaren Discovery-Slice des Buying Agents.
Ziel ist, externe Produktsuchen automatisiert aus den Kriterien eines BuyingProjects abzuleiten, regelmäßig auszuführen, Ergebnisse dauerhaft zu verwalten, Veränderungen zu erkennen und die Treffer anschließend durch die eigene Buying-Engine zu bewerten.
Der erste Pilot erfolgt mit **Geizhals, Kategorie Notebooks**. Die Architektur darf jedoch nicht notebook-spezifisch sein.
```text
BuyingProject
↓
Canonical Criteria
↓
Source Taxonomy + Mapping
↓
generierte Geizhals-Suche
↓
periodischer SearchRun
↓
persistierte Produkte + Beobachtungen
↓
Diff zum vorherigen Lauf
↓
NEW / CHANGED / MISSING / DISAPPEARED
↓
interne Constraints + Ranking
↓
Shortlist
↓
später Deep Enrichment
↓
später Decision
```
## 2. Fachliche Leitprinzipien
1. Geizhals ist Discovery-Quelle, nicht Decision Engine.
2. Die eigenen BuyingProject-Kriterien bleiben die fachliche Quelle der Wahrheit.
3. Geizhals wird als möglichst starker Vorfilter genutzt.
4. Nicht auf Geizhals abbildbare Kriterien bleiben interne Kriterien.
5. Discovery, Ranking und Decision bleiben getrennte fachliche Stufen.
6. Externe Filtertaxonomien werden **on demand** gelernt, nicht vollständig vorab katalogisiert.
7. URL-Encoding und Filtersyntax dürfen nicht vom LLM erfunden werden.
8. Produktidentität wird zunächst konservativ und pragmatisch behandelt.
9. Bei Unsicherheit erfolgt keine automatische Zusammenführung.
10. Suchläufe speichern strukturierte Zustände, keine HTML-Archive.
## 3. Scope v0.1
### Enthalten
- Geizhals als erste Discovery-Quelle
- Pilotkategorie Notebooks
- On-Demand-Erfassung der Geizhals-Filtertaxonomie
- Speicherung von Source-Kategorien, Filterdefinitionen, Optionen und Wertebereichen
- Mapping zwischen Canonical Criteria und Source-Filtern
- reproduzierbare Generierung von Geizhals-Such-URLs
- periodische SearchRuns
- vollständige Ergebnisaufnahme einer aktiven Suche
- persistierte SourceProductReferences
- Historisierung sichtbarer Attribute und Preise
- Diffing zwischen Suchläufen
- Status `NEW`, `CHANGED`, `UNCHANGED`, `MISSING`, `DISAPPEARED`
- interne Bewertung der Kandidaten
- konfigurierbare Shortlist, Default 5
- defensives Fehler-/Backoff-Verhalten
- Tests
### Nicht enthalten
- Frontend-Implementierung
- Keepa
- Idealo
- LLM-Automation
- automatische Kaufentscheidung
- Kaufautomatisierung
- Warenkorbmanagement
- Authentifizierung / RBAC
- Multi-User-UI
- automatische Deep-Enrichment-Quellen
- Umgehung von Schutzmechanismen externer Websites
## 4. Source Taxonomy
### 4.1 SourceCategory
Repräsentiert eine Kategorie einer externen Quelle.
```json
{
"source": "geizhals",
"external_category_key": "nb",
"name": "Notebooks",
"source_url": "https://geizhals.de/?cat=nb",
"status": "ACTIVE",
"last_verified_at": "2026-10-04T10:00:00Z"
}
```
### 4.2 SourceFilterDefinition
Beschreibt einen von Geizhals angebotenen Filter.
```json
{
"source": "geizhals",
"category_key": "nb",
"external_filter_key": "17023",
"label": "Arbeitsspeicher",
"filter_type": "NUMERIC_THRESHOLD",
"canonical_unit": "GB",
"status": "VERIFIED"
}
```
Mögliche `filter_type`-Werte:
```text
BOOLEAN
ENUM
MULTI_ENUM
NUMERIC_RANGE
NUMERIC_THRESHOLD
TEXT
UNKNOWN
```
### 4.3 SourceFilterOption
Für diskrete Filterwerte:
```json
{
"filter_key": "17023",
"source_value": "ab 24GB",
"normalized_value": 24,
"operator": ">=",
"unit": "GB"
}
```
### 4.4 SourceFilterRange
Für Bereiche bzw. frei parametrisierbare Werte:
```json
{
"filter_key": "price",
"minimum": 0,
"maximum": null,
"step": 1,
"unit": "EUR"
}
```
## 5. On-Demand Taxonomy Learning
Die Taxonomie wird nur für tatsächlich verwendete Kategorien gelernt.
Initial:
```text
Geizhals → Notebooks
```
Später z. B.:
```text
Monitore
Fernseher
Kameras
Rasenmäher
...
```
### Ablauf
```text
Kategorie öffnen
↓
verfügbare Filter erkennen
↓
Filterdefinitionen speichern
↓
Optionen / Bereiche erfassen
↓
URL-Verhalten beobachten
↓
Mapping erzeugen
↓
technisch verifizieren
```
### Mapping-Status
```text
DISCOVERED
LEARNED_UNVERIFIED
VERIFIED
BROKEN
DISABLED
```
Nur `VERIFIED` darf für automatische produktive Suchläufe verwendet werden.
### Änderbarkeit
Die gelernten Mappings sollen später im Frontend administrierbar sein.
v0.1 benötigt dafür noch keine UI, aber die Persistenz muss Änderungen ermöglichen, ohne Source-Code anzupassen.
## 6. Canonical Criteria
Canonical Criteria sind die interne fachliche Darstellung eines Suchkriteriums.
Sie sollen sich stark an der Source-Taxonomie orientieren, aber nicht fest an Geizhals gekoppelt sein.
```json
{
"key": "ram_gb",
"value_type": "number",
"unit": "GB",
"semantic": "working_memory"
}
```
Ein BuyingProject verwendet daraus konkrete Anforderungen:
```json
{
"criterion": "ram_gb",
"operator": ">=",
"value": 24,
"mandatory": true
}
```
### Source Mapping
```text
Canonical Criterion
ram_gb >= 24
↓
Geizhals Mapping
filter_key = 17023
source_value = "ab 24GB"
↓
URL fragment
xf=17023_ab+24GB
```
Nicht jedes Canonical Criterion muss ein Source Mapping besitzen.
Fehlt ein Mapping:
```text
Criterion → INTERNAL_ONLY
```
Das Kriterium wird dann erst nach Discovery intern bewertet.
## 7. DiscoverySearch
Eine `DiscoverySearch` gehört zu einem BuyingProject und einer Source.
Sie enthält mindestens:
```text
id
buying_project_id
source_id
source_category_id
criteria_version
mapping_version
generated_url
status
schedule_interval_minutes
broad_result_threshold
created_at
updated_at
last_successful_run_at
```
Defaults:
```text
schedule_interval_minutes = 180
shortlist_size = 5
broad_result_threshold = 300
```
## 8. Search URL Generation
Die URL wird ausschließlich aus:
```text
BuyingProject Criteria
+
VERIFIED CriterionMappings
+
SourceCategory
+
konfigurierbaren Source-Optionen
```
generiert.
Die URL ist abgeleitet, nicht die fachliche Quelle der Wahrheit.
Eine Änderung der BuyingProject-Kriterien erzeugt eine neue `criteria_version`.
Wenn die gespeicherte DiscoverySearch nicht mehr zur aktuellen Criteria-/Mapping-Version passt:
```text
status = OUT_OF_SYNC
```
Danach muss die URL neu generiert werden.
## 9. Ergebnisumfang
Aktive Suchläufe werden grundsätzlich vollständig eingelesen.
Keine stille Begrenzung auf Top-N.
Nur vollständige Ergebnismengen erlauben belastbare Erkennung von:
```text
NEW
CHANGED
MISSING
DISAPPEARED
```
### TOO_BROAD
Überschreitet die Treffermenge den konfigurierten Schwellwert:
```text
result_count > broad_result_threshold
```
wird die Suche markiert:
```text
TOO_BROAD
```
Die Suche darf technisch weiter ausgeführt werden, erzeugt aber einen Hinweis, dass die Source-Kriterien geschärft werden sollten.
Spätere Versionen dürfen breite Suchen differenziert behandeln, etwa seltenere Full-Reconciliation.
## 10. SearchRun
Jeder Abruf erzeugt einen unveränderlichen `SearchRun`.
Felder:
```text
id
discovery_search_id
criteria_version
mapping_version
generated_url
started_at
finished_at
status
result_count
page_count
http_status_summary
error_code
```
Status:
```text
RUNNING
SUCCESS
PARTIAL
FAILED
BLOCKED
```
Es wird kein HTML-Snapshot gespeichert.
## 11. SourceProductReference
Ein Treffer einer externen Quelle wird als `SourceProductReference` dauerhaft angelegt.
Mindestens verfügbare Felder:
```text
id
source_id
source_category_id
source_url
source_title
manufacturer
model
manufacturer_sku
gtin_ean
normalized_spec_fingerprint
first_seen_at
last_seen_at
status
```
Keines dieser Felder außer der internen UUID wird pauschal als garantiert stabil betrachtet.
## 12. Produktidentität – Pilotansatz
v0.1 implementiert bewusst keine komplexe globale Identity Engine.
Für den Notebook-Pilot werden folgende Signale verwendet:
1. vorhandene stabile Source-ID, falls entdeckt
2. GTIN/EAN, falls vorhanden
3. Hersteller-SKU, falls vorhanden
4. kanonische Source-URL
5. normalisierter Titel
6. Hersteller + Modell
7. differenzierende technische Specs
Für Notebooks kann der initiale Fingerprint beispielsweise enthalten:
```text
manufacturer
model
cpu
ram
storage
display_size
gpu
```
### Matching-Regeln
- Hohe Sicherheit → existierende SourceProductReference verwenden
- Unsicherheit → `MATCH_UNCERTAIN`
- Keine sichere Übereinstimmung → neue SourceProductReference
- niemals zwei Produkte allein aufgrund ähnlicher Namen automatisch verschmelzen
Die tatsächliche Stabilität der Identitätsmerkmale wird im Notebook-Pilot beobachtet und danach verfeinert.
## 13. Produktbeobachtungen und Historie
Technische Eigenschaften und Preise werden nicht einfach überschrieben.
Jeder SearchRun kann neue Beobachtungen erzeugen.
### ProductObservation
```text
source_product_reference_id
search_run_id
observed_at
raw_title
best_price
currency
raw_attributes
normalized_attributes
availability
seller_count
```
Veränderte Werte bleiben historisch nachvollziehbar.
Beispiele:
```text
Preis: 1499 → 1299
RAM: 16 → 32
Anbieterzahl: 8 → 12
Verfügbarkeit geändert
```
Bei technischen Attributänderungen muss das System berücksichtigen, dass auch fehlerhaftes Matching vorliegen könnte.
## 14. Diffing
Jeder erfolgreiche Full SearchRun wird mit dem vorherigen erfolgreichen Full SearchRun derselben DiscoverySearch verglichen.
### Status
```text
NEW
CHANGED
UNCHANGED
MISSING
DISAPPEARED
```
### Regeln
**NEW**
Produkt war im vorherigen vollständigen Lauf nicht vorhanden.
**CHANGED**
Produkt vorhanden, aber mindestens ein relevantes beobachtetes Feld hat sich verändert.
**UNCHANGED**
Produkt vorhanden und relevante Felder unverändert.
**MISSING**
Produkt fehlt in einem vollständigen Lauf.
**DISAPPEARED**
Produkt fehlt in drei aufeinanderfolgenden vollständigen Läufen.
Produkte werden nicht gelöscht.
Historie bleibt erhalten.
Ein später erneut auftauchendes Produkt wird reaktiviert und nicht als neues Produkt dupliziert, sofern das Matching ausreichend sicher ist.
## 15. Lifecycle eines BuyingProjects
Während ein BuyingProject aktiv ist:
```text
ACTIVE
↓
DiscoverySearches laufen
↓
Produkte + Historie wachsen
↓
Ranking + Shortlist
```
Nach finalem Kauf:
```text
PURCHASED
↓
BuyingProject archivieren
↓
Discovery stoppen
```
Produkte, Beobachtungen und Evaluationen können mit dem Projekt archiviert bzw. aus aktiven Ansichten entfernt werden.
Keine physische Löschung historischer Daten als Standardverhalten.
## 16. Ranking
Nach Discovery übernimmt ausschließlich die interne Buying Engine.
```text
Source Results
↓
interne Hard Constraints
↓
ProductScore
↓
Ranking
```
Geizhals-Sortierung darf für die technische Ausgabe genutzt werden, ist aber keine fachliche Ranking-Entscheidung.
## 17. Shortlist
Nach internem Ranking wird eine Shortlist gebildet.
Default:
```text
shortlist_size = 5
```
Der Wert ist pro BuyingProject konfigurierbar.
Shortlist-Kandidaten erhalten:
```text
SHORTLISTED
```
Andere gültige Kandidaten:
```text
CANDIDATE
```
Die spätere Deep-Enrichment-Stufe arbeitet primär auf der Shortlist.
## 18. Deep Enrichment
Nicht Bestandteil dieses Implementierungsslices.
Zielbild:
```text
Shortlist
↓
Herstellerdaten
Tests
Benchmarks
Reviews
weitere Händler
Preisportale
Qualitätsinformationen
↓
erneute Bewertung
```
Discovery darf daher nicht voraussetzen, dass Geizhals alle für die finale Kaufentscheidung notwendigen Daten liefert.
## 19. Discovery, Ranking und Decision
Die drei fachlichen Stufen müssen getrennt bleiben.
### Discovery
```text
Welche Produkte kommen potenziell infrage?
```
### Ranking
```text
Welche dieser Produkte passen am besten zum BuyingProject?
```
### Decision
```text
Ist jetzt der richtige Zeitpunkt, Kandidat X zu kaufen?
```
Decision wird später u. a. berücksichtigen können:
- Zielpreis
- Deadline
- historische Preisentwicklung
- aktuelle Verfügbarkeit
- Product Fit
- Offer Fit
- Alternativen
- Beschaffungsdringlichkeit
Decision ist nicht Bestandteil dieses Slices.
## 20. Scheduling und defensiver Abruf
Default:
```text
alle 180 Minuten
```
pro DiscoverySearch konfigurierbar.
### Anforderungen
- keine parallelen Massenabrufe
- Pagination sequenziell oder stark begrenzt parallel
- Caching, wo sinnvoll
- Timeout
- Retry mit exponentiellem Backoff
- Jitter
- Stop bei wiederholten Fehlern
- keine Umgehung von Captchas oder Bot-Schutz
### Reaktion
**HTTP 429**
```text
BACKOFF
```
**HTTP 403**
```text
BLOCKED
```
**Captcha / Challenge erkannt**
```text
BLOCKED
```
Automatische weitere Abrufe der betroffenen DiscoverySearch werden pausiert.
Keine Schutzmechanismen umgehen.
## 21. Source Adapter Contract
Ein Discovery-Adapter soll mindestens folgende Fähigkeiten kapseln:
```python
class DiscoverySourceAdapter(Protocol):
def discover_taxonomy(category_ref): ...
def build_query(criteria, mappings): ...
def fetch_results(query, pagination): ...
def parse_results(response): ...
def normalize_result(result): ...
```
Taxonomy Learning und Result Retrieval dürfen intern getrennte Services sein.
Der Rest des Systems darf keine Geizhals-spezifische URL- oder HTML-Logik kennen.
## 22. Services
Mindestens:
```text
TaxonomyService
CriterionMappingService
DiscoverySearchService
SearchExecutionService
SourceProductIdentityService
SearchDiffService
CandidateRankingService
ShortlistService
```
Keine Businesslogik in n8n.
n8n kann später den Scheduler bzw. externe Events orchestrieren.
## 23. Persistenz
Neue bzw. ergänzende Tabellen können sein:
```text
source_categories
source_filter_definitions
source_filter_options
source_filter_ranges
criterion_definitions
criterion_mappings
discovery_searches
search_runs
source_product_references
product_observations
project_candidates
candidate_status_history
```
Bestehende globale Entitäten aus der Hauptspezifikation bleiben bestehen:
```text
Product
ProductVariant
Offer
PriceObservation
```
Diese dürfen nicht unnötig dupliziert werden.
Der Discovery-Slice kann zunächst mit SourceProductReference arbeiten und erst bei ausreichender Identität eine Verknüpfung zu canonical Product/ProductVariant herstellen.
## 24. API – minimaler Vertrag
### Taxonomie
```text
POST /api/v1/sources/geizhals/categories/{category}/discover-taxonomy
GET /api/v1/sources/geizhals/categories/{category}/filters
```
### Mapping
```text
GET /api/v1/criterion-mappings
POST /api/v1/criterion-mappings
PATCH /api/v1/criterion-mappings/{id}
```
### DiscoverySearch
```text
POST /api/v1/discovery-searches
GET /api/v1/discovery-searches/{id}
POST /api/v1/discovery-searches/{id}/generate-query
POST /api/v1/discovery-searches/{id}/run
```
### SearchRuns
```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
```
Falls BuyingProject im aktuellen Code noch nicht existiert, muss die Integration mit der im Architecture Addendum vorgesehenen nächsten Domain-Erweiterung abgestimmt werden.
## 25. Tests
### Taxonomy
- Notebook-Kategorie kann on demand eingelesen werden
- Filterdefinitionen werden reproduzierbar gespeichert
- Optionen werden nicht dupliziert
- Filteränderungen werden erkannt
- BROKEN-Mapping wird nicht produktiv verwendet
### Query Generation
- identische Criteria + Mapping-Version erzeugen identische URL
- RAM >= 24 erzeugt erwartetes Geizhals-Fragment
- Preisbereich korrekt
- mehrere Filter kombinierbar
- INTERNAL_ONLY-Kriterien verändern die Source-URL nicht
- veraltete Mapping-Version markiert Search als OUT_OF_SYNC
### Search Execution
- Pagination vollständig
- Ergebniszahl korrekt
- TOO_BROAD bei Überschreitung
- kein stilles Top-N-Abschneiden
- 429 → Backoff
- 403/Captcha → BLOCKED
### Identity
- identische SKU wird wiedererkannt
- identische EAN wird wiedererkannt
- gleiche URL wird wiedererkannt
- leicht geänderter Titel bei stabilen Specs wird erkannt
- unsicheres Match erzeugt MATCH_UNCERTAIN
- ähnliche Produktnamen werden nicht automatisch verschmolzen
### Diffing
- neuer Treffer → NEW
- geänderter Preis → CHANGED
- unverändert → UNCHANGED
- einmal fehlend → MISSING
- dreimal fehlend → DISAPPEARED
- Wiederauftauchen reaktiviert bestehende Referenz
### Historie
- Preisänderungen bleiben historisiert
- technische Änderungen bleiben historisiert
- alte SearchRuns bleiben unverändert
- Projektarchivierung löscht keine History
### Ranking
- nur interne Engine bestimmt Ranking
- Source-Sortierung beeinflusst ProductScore nicht
- Shortlistgröße Default 5
- Shortlistgröße konfigurierbar
## 26. Implementierungsreihenfolge
1. Bestehende Implementierung gegen diese Spec und das Architecture Addendum prüfen.
2. Notwendige BuyingProject-/ProjectCandidate-Minimalstruktur ergänzen, falls für Discovery erforderlich.
3. Source Taxonomy + Mapping persistieren.
4. Geizhals-Taxonomie-Pilot für Notebooks implementieren.
5. reproduzierbare Query Generation implementieren.
6. SearchRun + Pagination implementieren.
7. SourceProductReference + ProductObservation implementieren.
8. Identity Pilot implementieren.
9. Diffing implementieren.
10. interne Ranking-Engine anbinden.
11. Shortlist bilden.
12. Scheduling-Schnittstelle vorbereiten bzw. internen Scheduler minimal anbinden.
13. Tests vollständig ausführen.
14. Notebook-Pilot mit realer Suche validieren.
## 27. Definition of Done
- [ ] Geizhals-Notebook-Taxonomie wird on demand eingelesen und gespeichert.
- [ ] Source-Filter und Optionen werden persistiert.
- [ ] Filter-Mappings besitzen Lifecycle-Status.
- [ ] BuyingProject-Kriterien erzeugen reproduzierbar eine Geizhals-URL.
- [ ] Nicht abbildbare Kriterien bleiben INTERNAL_ONLY.
- [ ] Aktive Suche kann vollständig ausgeführt werden.
- [ ] Pagination wird vollständig verarbeitet.
- [ ] TOO_BROAD wird erkannt.
- [ ] SearchRuns werden gespeichert.
- [ ] Produkte werden dauerhaft als SourceProductReference angelegt.
- [ ] Preise und relevante Attribute werden historisiert.
- [ ] NEW / CHANGED / UNCHANGED / MISSING / DISAPPEARED funktionieren.
- [ ] DISAPPEARED erst nach drei aufeinanderfolgenden fehlenden Full Runs.
- [ ] Unsichere Produktidentität wird nicht automatisch verschmolzen.
- [ ] interne Engine bewertet Kandidaten.
- [ ] Shortlist Default 5 funktioniert.
- [ ] Suchfrequenz ist konfigurierbar, Default 180 Minuten.
- [ ] 403/429/Captcha führen zu defensivem Stop/Backoff.
- [ ] keine HTML-Archive.
- [ ] keine Notebook-spezifische Businesslogik außerhalb des Geizhals-Pilotmappings.
- [ ] Tests grün.
- [ ] Ergebnisse des Notebook-Piloten dokumentiert.
# 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`
Die neue Source-/Discovery-Spec ergänzt die bestehenden Dokumente. Bei Konflikten in ihrem Fachbereich hat sie Vorrang.
## Vorgehen
### 1. Zuerst analysieren
Prüfe den aktuellen Repository-Stand gegen alle drei Dokumente.
Berichte vor größeren Änderungen:
- welche Teile bereits kompatibel sind,
- welche Domain-/DB-/API-Erweiterungen erforderlich sind,
- ob bestehende Implementierung refaktoriert werden muss,
- welche Änderungen rein additiv möglich sind.
### 2. Minimal integrieren
Implementiere nur den beschriebenen Source-/Discovery-Slice.
Nicht implementieren:
- Frontend
- Keepa
- Idealo
- LLM-Automation
- Auth/RBAC
- Kaufautomatisierung
- Warenkorb
### 3. Besonders beachten
- nicht notebook-spezifisch modellieren
- Geizhals-spezifische Logik ausschließlich im Source Adapter / Mapping Layer
- URL-Encoding nur aus verifizierten Source-Mappings
- vollständige SearchRuns, kein stilles Top-N-Limit
- konservatives Product Matching
- keine automatische Zusammenführung bei Unsicherheit
- alle Änderungen historisieren
- Discovery, Ranking und Decision getrennt halten
### 4. Tests
Führe Unit-, Integration- und End-to-End-Tests aus.
Mindestens:
- Taxonomy Discovery
- Query Generation
- Pagination
- Identity Matching
- Diffing
- History
- Ranking
- Shortlist
- Backoff / BLOCKED
### 5. Abschlussbericht
Dokumentiere:
- geänderte Dateien
- neue Migrationen
- neue API-Endpunkte
- Testergebnisse
- real durchgeführten Notebook-Pilot
- erkannte Geizhals-Eigenheiten
- verbleibende Risiken
- insbesondere Beobachtungen zur Stabilität der Produktidentität