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>
This commit is contained in:
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
|
||||
Reference in new issue
Block a user