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
+3
-2
@@ -5,8 +5,9 @@
|
||||
**Runner:** Gitea Actions (`/home/lars/gitea-runner/`, Label `ubuntu-latest` → Host)
|
||||
**Repo:** `http://192.168.2.144:3000/Lars/BuyingAgent.git`
|
||||
|
||||
Fachliche Grundlage: `.specs/buying-agent-v0.1-spec.md` bzw. `docs/buying-agent-v0.1-spec-v1.1.md`.
|
||||
v0.1 hat keine Web-UI; öffentlich wird nur die API bereitgestellt.
|
||||
Fachliche Grundlage: `docs/buying-agent-v0.1-spec-v1.1.md`.
|
||||
Architektur: `docs/buying-agent-architecture-addendum-v1.md` (Monorepo `backend/` + `frontend/`-Platzhalter).
|
||||
v0.1 hat keine Web-UI; öffentlich wird nur die API bereitgestellt. Der Image-Build-Kontext ist `./backend`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user