Leopoldadmin/erp-nutzfahrzeuge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1620a35d713d294745ea4302eddbee13ed2f6066
erp-nutzfahrzeuge/docs/requirements.md
T

38 KiB
Raw Blame History

ERP-System für Nutzfahrzeug-/Baumaschinen-Handel

Requirements Specification

Version: 1.0.0
Datum: 2026-07-10
Status: Final – Discovery abgeschlossen
Analyst: Requirements Analyst (A0)

1. Projektüberblick

Ein webbasiertes ERP-System für Händler von Nutzfahrzeugen und Baumaschinen (~10 Nutzer). Das System verwaltet Fahrzeugbestände mit Baumaschinen-spezifischen Feldern, Kundenkontakte, Verkaufsprozesse mit Rechtsdokumenten, OCR-basierte Datenerfassung via Vision-Modellen, mobile.de Push-Sync, KI-Copilot (Text + Sprache) und KI-Bildretusche. Alle KI-Funktionen laufen über OpenRouter.

Domain Knowledge

  • Domain: Nutzfahrzeug- und Baumaschinenhandel (B2B/B2C)
  • Zulassungsdokumente: Zulassungsbescheinigung Teil I (ZB I = Fahrzeugschein) und Teil II (ZB II = Fahrzeugbrief), EU-einheitlich seit 2005
  • mobile.de: Deutschlands größter Fahrzeugmarkt mit Seller API (REST) für Händler
  • Baumaschinen-spezifisch: LKW-Typ, Art (Bagger, Radlader, etc.), Aufbau, Betriebsstunden statt Kilometerstand, Leistung in kW/PS
  • USt-IdNr.-Prüfung: Gesetzlich vorgeschrieben bei innergemeinschaftlichen Lieferungen (§ 6a UStG, § 27a UStG). BZSt eVatR API-Zugang aktuell NICHT vorhanden – manuelle Prüfung im MVP
  • Geldwäsche-Prävention: Identifikation, Meldepflichten bei Barzahlungen > 10.000 € (GwG)
  • Kaufverträge/Rechnungen: Unterscheidung EU-Inland, EU-Ausland, Dritland
  • DATEV: Standard-Exportformat für Steuerberater-Übergabe

2. Tech-Stack Entscheidungen

Komponente Entscheidung Begründung
Backend Python / FastAPI Async, OpenAPI-Auto-Docs, Python-Ökosystem für KI/OCR-Integration, schnell zu entwickeln
Frontend React / Next.js SSR, große Community, TypeScript-Support, Component-Ökosystem
Datenbank PostgreSQL Relational, robust, JSON-Support für flexible Felder, Full-Text-Search
Hosting Coolify self-hosted (Docker) Bereits vorhanden, keine Cloud-Abhängigkeit, volle Kontrolle
OCR OpenRouter Vision-Modell (Qwen2.5-VL) Keine Spezial-API nötig, DSGVO: Cloud-Verarbeitung akzeptiert
KI-Copilot OpenRouter (bestes Modell, z.B. Claude/GPT-4) Flexibel, kein Vendor-Lock-in, KI darf selbstständig handeln
KI-Bildretusche OpenRouter Flux.1-Pro Hintergrund entfernen, Spiegelungen retuschieren
KI-Vision/Analyse OpenRouter Qwen2.5-VL Fahrzeugfoto-Analyse, ZB I/II Felderkennung
i18n Deutsch + Englisch Beide Sprachen von Anfang an
DATEV-Export CSV/DATEV-kompatibel Für Steuerberater-Übergabe

Coding Guidelines

  • Naming: snake_case (Python), camelCase (JS/TS), PascalCase (React Components)
  • Struktur: Modulare Feature-Ordner, Shared-Libraries für Common-Logic
  • Linting: ruff (Python), eslint + prettier (TypeScript)
  • Tests: pytest (Backend), jest/playwright (Frontend), Coverage-Target ≥80%
  • API-Stil: RESTful, OpenAPI 3.0, versionierte Endpoints (/api/v1/...)

Deployment

  • Environments: Dev + Prod via Coolify (Docker Compose)
  • CI/CD: Forgejo Actions → Docker Build → Coolify Deploy
  • Secrets: Umgebungsvariablen in Coolify, niemals im Code

3. Module und Features

Modul M1: Fahrzeugbestand + mobile.de Push-Sync

[F-M1-01] Fahrzeugbestand verwalten

Anforderung: Vollständige Verwaltung des Fahrzeugbestands mit Standard- und Baumaschinen-spezifischen Feldern. Standardfelder: Marke, Modell/Typ, FIN (Fahrgestellnummer), Baujahr, Erstzulassung, Leistung (kW/PS), Kraftstoffart, Getriebe, Farbe, Zustand, Standort, Verfügbarkeit, Preis. Baumaschinen-spezifische Felder: LKW-Typ, Art (Bagger, Radlader, Kran, etc.), Aufbau, Betriebsstunden (statt KM-Stand), Betriebsstunden-Einheit (h/min).

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: Neues Baumaschinen-Fahrzeug wird mit allen Pflichtfeldern inkl. Betriebsstunden angelegt. Erwartet: Fahrzeug erscheint in Bestandsliste, FIN validiert (17 Zeichen), Betriebsstunden-Feld sichtbar, alle Felder gespeichert.
  2. Edge Case: Fahrzeug mit doppelter FIN wird angelegt. Erwartet: Fehlermeldung „FIN bereits vorhanden“, kein Speichern.
  3. Integration: Fahrzeug wird angelegt und danach über die Suchfunktion gefunden. Erwartet: Fahrzeug erscheint in Suchergebnissen mit allen eingegebenen Daten inkl. Baumaschinen-Felder.

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • Fahrzeugbestand-Seite lädt, Formular mit Baumaschinen-Feldern, Bestandsliste zeigt alle Fahrzeuge

[F-M1-02] mobile.de Push-Sync (nur Push)

Anforderung: Fahrzeuge aus dem Bestand können auf mobile.de gelistet/aktualisiert werden. Über die mobile.de Seller API (REST) werden Fahrzeugdaten übertragen (Push-Only, NICHT bidirektional). Feldmapping zwischen ERP-Feldern und mobile.de-Feldern. Sync-Status wird pro Fahrzeug angezeigt (Entwurf → gelistet → aktualisiert → verkauft/entfernt). Preisänderungen im ERP können gepusht werden.

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: Fahrzeug mit vollständigen Daten wird an mobile.de gesendet. Erwartet: API-Response 200/201, Fahrzeug erscheint auf mobile.de, Status im ERP wird auf „gelistet" aktualisiert.
  2. Edge Case: Fahrzeug mit unvollständigen mobile.de-Pflichtfeldern wird gesendet. Erwartet: API-Fehlermeldung wird im ERP angezeigt, Fahrzeug wird nicht gelistet, Status bleibt „Entwurf".
  3. Integration: Fahrzeug wird auf mobile.de gelistet, dann im ERP Preis geändert, Push-Sync erneut ausgeführt. Erwartet: Preis auf mobile.de aktualisiert, Sync-Status „aktualisiert".

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • API-Verbindung zu mobile.de konfigurierbar, Push-Listing funktioniert, Status-Tracking korrekt

[F-M1-03] mobile.de Listing-Verwaltung

Anforderung: Übersicht aller Fahrzeuge mit mobile.de-Status. Filterung nach Status (nicht gelistet, gelistet, Fehler). Batch-Push für mehrere Fahrzeuge. Fehler-Logs pro Fahrzeug einsehbar. Entfernen von Listings auf mobile.de (Delisting).

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: 3 Fahrzeuge werden per Batch-Push an mobile.de gesendet. Erwartet: Alle 3 erhalten Status „gelistet", Fortschrittsanzeige während Sync.
  2. Edge Case: Ein Fahrzeug von 3 hat fehlende Pflichtfelder. Erwartet: 2 erfolgreich gepusht, 1 mit Fehlermeldung, Fehler-Log einsehbar.
  3. Integration: Fahrzeug wird auf mobile.de delisted. Erwartet: Listing auf mobile.de entfernt, Status im ERP „entfernt".

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • Batch-Push, Status-Übersicht, Fehler-Logs und Delisting funktionieren

Modul M2: OCR Fahrzeugdaten-Erfassung

[F-M2-01] OCR-Erfassung Zulassungsbescheinigung Teil I (ZB I / Fahrzeugschein)

Anforderung: Foto des Fahrzeugscheins (ZB I) hochladen, OpenRouter Vision-Modell (Qwen2.5-VL) erkennt Felder automatisch (Felder A–K gemäß KBA-Standard): Marke, Modell, FIN, Erstzulassung, Kennzeichen, Leistung, Hubraum, Kraftstoffart, Schadstoffklasse, etc. Daten werden in Fahrzeugformular eingetragen, User kann korrigieren.

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: Gut belichtetes Foto einer ZB I wird hochgeladen. Erwartet: Qwen2.5-VL erkennt alle relevanten Felder mit >90% Genauigkeit, Daten werden in Fahrzeugformular eingetragen, User kann korrigieren.
  2. Edge Case: Verschmutztes oder schiefes Foto wird hochgeladen. Erwartet: System gibt Warnung „Bildqualität niedrig", best-effort Erkennung, alle Felder editierbar.
  3. Integration: OCR-Daten werden ins Fahrzeugformular eingetragen, User speichert. Erwartet: Fahrzeug wird mit OCR-Daten angelegt, Felder korrekt übernommen.

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • Upload funktioniert, Qwen2.5-VL via OpenRouter erkennt Felder, Daten fließen in Formular

[F-M2-02] OCR-Erfassung Zulassungsbescheinigung Teil II (ZB II / Fahrzeugbrief)

Anforderung: Foto des Fahrzeugbriefs (ZB II) hochladen, OpenRouter Qwen2.5-VL erkennt Felder: FIN, Hersteller, Typ, Variante, Fahrzeugklasse, Antriebsart, Leistung, Hubraum, zul. Gesamtgewicht, Datum der Erstzulassung, Previous Owner, etc. Daten werden in Fahrzeugformular eingetragen.

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: Gut belichtetes Foto einer ZB II wird hochgeladen. Erwartet: Alle relevanten Felder werden erkannt, Daten ins Fahrzeugformular eingetragen.
  2. Edge Case: ZB II mit Stempeln/Aufklebern die Teile des Textes verdecken. Erwartet: System warnt, best-effort Erkennung, manuelle Korrektur möglich.
  3. Integration: ZB I und ZB II für dasselbe Fahrzeug hochgeladen. Erwartet: Daten werden zusammengeführt, FIN-Abgleich zwischen ZB I und ZB II, Warnung bei Diskrepanz.

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • Upload funktioniert, Qwen2.5-VL erkennt ZB II-Felder, Zusammenführung mit ZB I

Modul M3: Kontakt- & Kundenverwaltung

[F-M3-01] Kontakt- und Kundenverwaltung

Anforderung: Verwaltung von Firmen und Ansprechpartnern. Felder: Firmenname, Rechtsform, Ansprechpartner (Name, Funktion), Adresse (Straße, PLZ, Ort, Land), USt-IdNr., Telefon, E-Mail, Website. Unterscheidung Käufer/Verkäufer. EU-International und Inland. ~10 Nutzer arbeiten mit den Daten.

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: Neue Firma mit Ansprechpartner wird angelegt als „Käufer". Erwartet: Firma erscheint in Kontaktliste mit Rolle „Käufer", alle Felder gespeichert.
  2. Edge Case: Firma ohne USt-IdNr. (Privatkunde/Dritland) wird angelegt. Erwartet: USt-IdNr. optional, Firma wird gespeichert, Rolle „Käufer" zugewiesen.
  3. Integration: Firma wird als Käufer angelegt, dann Verkauf an diese Firma gestartet. Erwartet: Firmendaten fließen in Kaufvertrag ein.

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • Kontaktliste zeigt Firmen mit Rollen, Anlegen/Editieren funktioniert

[F-M3-02] Kundensuche und Filter

Anforderung: Kunden/Kontakte können gesucht und gefiltert werden nach: Name, Land, Rolle (Käufer/Verkäufer), USt-IdNr.-Status (geprüft/ungeprüft/manuell bestätigt).

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: Suche nach „Müller" in Kontakten. Erwartet: Alle Kontakte mit „Müller" im Namen erscheinen.
  2. Edge Case: Filter „Land = Deutschland" und „Rolle = Käufer" kombiniert. Erwartet: Nur deutsche Käufer-Firmen erscheinen.
  3. Integration: Gefundener Kontakt wird für Verkauf ausgewählt. Erwartet: Kontakt wird in Verkaufsformular übernommen.

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • Such- und Filterfunktion liefert korrekte Ergebnisse

Modul M4: Dateiablage pro Fahrzeug

[F-M4-01] Dateiablage pro Fahrzeug

Anforderung: Jedes Fahrzeug hat einen eigenen Dateibereich. Dokumente (PDF, Verträge, Rechnungen), Fotos (JPG/PNG) und andere Dateien können hochgeladen, kategorisiert, umbenannt und gelöscht werden. Dateivorschau für Bilder und PDFs. Max 50 MB pro Datei. Kategorien: Vertrag, Rechnung, ZB I, ZB II, Foto, Sonstiges.

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: PDF-Vertrag wird zu Fahrzeug hochgeladen. Erwartet: Datei erscheint in Fahrzeug-Dateibereich, Vorschau sichtbar, Datei kategorisierbar als „Vertrag".
  2. Edge Case: Datei > 50 MB wird hochgeladen. Erwartet: Fehlermeldung „Datei zu groß", kein Upload.
  3. Integration: Foto wird hochgeladen und für KI-Bildretusche (M8) verwendet. Erwartet: Foto ist in Dateiablage sichtbar und für Retusche-Modul auswählbar.

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • Datei-Upload, Vorschau, Kategorisierung und Löschung funktionieren

Modul M5: Verkaufsmodul mit Rechtsdokumenten

[F-M5-01] Kaufvertrag erstellen

Anforderung: Verkauf eines Fahrzeugs an einen Kunden. Kaufvertrag wird aus Vertragsvorlagen generiert mit: Fahrzeugdaten, Käufer-/Verkäuferdaten, Preis, Zahlungsbedingungen, Übergabedatum. PDF-Generierung. Unterscheidung EU-Inland, EU-Ausland, Dritland. Vertragsvorlagen basieren auf Stammdaten aus Einstellungen.

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: Verkauf an deutsche Firma (EU-Inland). Erwartet: Kaufvertrag-PDF wird generiert mit allen Daten, USt ausgewiesen, Vertragsvorlage korrekt angewendet.
  2. Edge Case: Verkauf an Schweizer Firma (Dritland). Erwartet: Kaufvertrag mit 0% USt (Ausfuhrlieferung), Hinweis auf Ausfuhr, andere Vorlage.
  3. Integration: Verkauf startet USt-IdNr.-Prüfung für EU-Ausland-Kunde. Erwartet: Manuelle Prüfung wird angeboten, Ergebnis im Vertrag dokumentiert.

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • Kaufvertrag-PDF generiert, alle Varianten (Inland/EU/Dritland) korrekt, Vorlagen aus Stammdaten

[F-M5-02] USt-IdNr.-Überprüfung (manuell)

Anforderung: Manuelle USt-IdNr.-Prüfung im MVP (kein BZSt eVatR API-Zugang vorhanden). User gibt Prüfergebnis manuell ein (gültig/ungültig, Prüdatum, Art der Prüfung). Prüfergebnis wird dokumentiert. BZSt API-Integration als „später" markiert. System warnt bei EU-Ausland-Verkauf ohne gültige USt-IdNr.

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: User prüft USt-IdNr. manuell (extern) und trägt Ergebnis „gültig" ein. Erwartet: Prüfergebnis mit Datum gespeichert, Status „geprüft".
  2. Edge Case: EU-Ausland-Verkauf ohne geprüfte USt-IdNr. Erwartet: Warnung „USt-IdNr. nicht geprüft", Verkauf kann erst nach Bestätigung fortgesetzt werden.
  3. Integration: USt-IdNr.-Prüfung wird im Verkaufsprozess angefordert. Erwartet: Prüfung angefordert, User trägt Ergebnis ein, Vertrag wird fortgesetzt.

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • Manuelle Prüfung dokumentiert, Warnung bei fehlender Prüfung, BZSt API als „später" markiert

[F-M5-03] Geldwäsche-Prävention

Anforderung: Identifikation des Vertragspartners (Ausweisdaten: Typ, Nummer, Ausstellungsland). Meldepflicht bei Barzahlungen > 10.000 € (GwG). System warnt automatisch bei Überschreitung. Dokumentation der Identifikation und etwaiger Meldungen. Ausweisdaten werden DSGVO-konform gespeichert (verschlüsselt, Zugriffsbeschränkung auf Admin/Buchhaltung).

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: Verkauf mit Barzahlung 8.000 €. Erwartet: Keine Warnung, Identifikation wird erfasst aber keine Meldepflicht.
  2. Edge Case: Verkauf mit Barzahlung 12.000 €. Erwartet: Warnung „Meldepflicht nach GwG", Meldedokument wird vorbereitet, Verkauf kann erst nach Bestätigung fortgesetzt werden.
  3. Integration: Identifikation wird im Kaufvertrag dokumentiert. Erwartet: Ausweisdaten (Typ, Nummer, Ausstellungsland) im Vertrag enthalten, verschlüsselt in DB gespeichert.

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • GwG-Warngrenze funktioniert, Identifikation erfasst, DSGVO-konforme Speicherung

[F-M5-04] Rechnung und Lieferbescheinigung

Anforderung: Rechnung wird aus Verkauf generiert (PDF). Lieferbescheinigung für EU-Innergemeinschaftliche Lieferungen. Rechnungsnummer fortlaufend, steuerrechtlich korrekt für Inland/EU-Ausland/Dritland.

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: Rechnung für EU-Inland-Verkauf wird generiert. Erwartet: Rechnungs-PDF mit USt, fortlaufende Nummer, Lieferbescheinigung beiliegend.
  2. Edge Case: Rechnung für Dritland-Verkauf (Ausfuhrlieferung). Erwartet: Rechnung mit 0% USt, Ausfuhrvermerke, Lieferbescheinigung.
  3. Integration: Rechnung wird aus abgeschlossenem Kaufvertrag generiert. Erwartet: Alle Daten aus Vertrag übernommen, Nummer inkrementiert.

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • Rechnungs-PDF generiert, Nummerierung korrekt, alle Varianten

[F-M5-05] DATEV-Export

Anforderung: Export von Verkaufs- und Rechnungsdaten im DATEV-kompatiblen Format (CSV) für die Übergabe an den Steuerberater. Filterung nach Zeitraum. Export enthält: Belegnummer, Datum, Konto, Betrag, USt, Gegenkonto, Kundennummer.

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: DATEV-Export für Januar 2026 wird ausgeführt. Erwartet: CSV-Datei mit allen Verkäufen des Monats, DATEV-Format korrekt, herunterladbar.
  2. Edge Case: Export für Zeitraum ohne Verkäufe. Erwartet: Leere CSV mit Headern, Hinweis „Keine Daten im Zeitraum".
  3. Integration: DATEV-Export nach Verkaufsabschluss. Erwartet: Verkauf erscheint im nächsten Export, Beträge korrekt.

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • DATEV-CSV korrekt formatiert, Filterung funktioniert, Download verfügbar

[F-M5-06] Vertragsvorlagen-Verwaltung (Stammdaten)

Anforderung: Vertragsvorlagen werden in den Einstellungen als Stammdaten hinterlegt. Pro Vertragsart (Kaufvertrag Inland, EU-Ausland, Dritland, Rechnung, Lieferbescheinigung) wird eine Vorlage definiert. Variablen werden markiert ({{fahrzeug}}, {{kaeufer}}, {{preis}}, etc.). Admin kann Vorlagen editieren.

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: Admin erstellt neue Vertragsvorlage für EU-Ausland-Verkauf. Erwartet: Vorlage wird gespeichert, Variablen markiert, bei Verkauf automatisch angewendet.
  2. Edge Case: Vorlage ohne Variablen wird gespeichert. Erwartet: Warnung „Keine Variablen gefunden", Vorlage speicherbar aber nicht funktional.
  3. Integration: Vorlage wird geändert, danach neuer Kaufvertrag erstellt. Erwartet: Neue Vorlage wird verwendet, Variablen korrekt ersetzt.

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • Vorlagen-Editor funktioniert, Variablen werden ersetzt, pro Vertragsart zuweisbar

Modul M6: Responsive UI (Querschnitt)

[F-M6-01] Responsive Web-UI

Anforderung: Web-UI funktioniert auf Desktop (≥1280px), Tablet (768–1279px) und Mobile (<768px). Alle Formulare sind touch-optimiert. Navigation passt sich an Bildschirmgröße an (Hamburger-Menü auf Mobile). Gilt für alle Module (Querschnitt).

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: Desktop-Ansicht bei 1920px Breite. Erwartet: Alle Navigationselemente sichtbar, Formulare nebeneinander angeordnet.
  2. Edge Case: Mobile-Ansicht bei 375px Breite. Erwartet: Hamburger-Menü, Formulare untereinander, Buttons groß genug für Touch.
  3. Integration: Fahrzeugformular auf Mobile ausgefüllt. Erwartet: Alle Felder zugänglich, OCR-Upload funktioniert, Speichern funktioniert.

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • UI funktioniert auf allen 3 Breakpoints

[F-M6-02] Internationalisierung (i18n: Deutsch + Englisch)

Anforderung: Alle UI-Texte, Labels, Fehlermeldungen und Systemmeldungen sind auf Deutsch und Englisch verfügbar. Sprache kann pro User eingestellt werden. Default: Deutsch. Datums-/Zahlenformate passen sich an Sprache an.

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: User stellt Sprache auf Englisch um. Erwartet: Alle UI-Texte auf Englisch, Datumsformat MM/DD/YYYY, Dezimaltrennzeichen Punkt.
  2. Edge Case: Fehlende Übersetzung für ein Label. Erwartet: Fallback auf Deutsch, Warnung im Dev-Log.
  3. Integration: Sprache wird umgestellt, neues Fahrzeug angelegt. Erwartet: Formular-Labels auf Englisch, Daten werden sprachunabhängig gespeichert.

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • DE + EN vollständig, Sprache pro User einstellbar, Formate passen sich an

Modul M7: KI-Copilot

[F-M7-01] KI-Copilot – Fahrzeug anlegen

Anforderung: KI-Assistent versteht natürlichsprachliche Befehle (Text/Sprache). Beispiel: „Lege ein neues Fahrzeug an: Mercedes Actros, Baujahr 2019, 150.000 km, 45.000 Euro". KI extrahiert Daten und füllt Fahrzeugformular aus. KI darf selbstständig handeln (Auto-Save nach Bestätigung). LLM via OpenRouter.

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: „Neues Fahrzeug: MAN TGL 2018, 120000 km, 32000 €". Erwartet: Fahrzeugformular wird vorausgefüllt mit Marke=MAN, Modell=TGL, Baujahr=2018, KM=120000, Preis=32000. KI speichert nach Bestätigung.
  2. Edge Case: „Füge ein Fahrzeug hinzu" ohne weitere Daten. Erwartet: KI fragt nach fehlenden Pflichtfeldern.
  3. Integration: KI legt Fahrzeug an und listet es gleichzeitig auf mobile.de. Erwartet: Fahrzeug wird gespeichert und mobile.de Push-Sync wird ausgelöst.

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • KI versteht Befehl via OpenRouter, füllt Formular, speichert nach Bestätigung

[F-M7-02] KI-Copilot – Suchen und Verkaufen

Anforderung: KI kann Fahrzeuge suchen („Finde alle LKW unter 30.000 €") und Verkaufsprozesse starten („Verkaufe Fahrzeug FIN XYZ123 an Müller GmbH"). KI darf selbstständig handeln – führt Aktionen nach Bestätigung aus.

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: „Finde alle Fahrzeuge über 50.000 €". Erwartet: Gefilterte Bestandsliste mit Fahrzeugen > 50.000 €.
  2. Edge Case: „Verkaufe Fahrzeug an Müller GmbH" ohne FIN. Erwartet: KI fragt nach Fahrzeug-Identifikation.
  3. Integration: „Verkaufe FIN XYZ an Müller GmbH, Barzahlung 15000 €". Erwartet: Verkaufsprozess startet, GwG-Warnung erscheint (unter 10.000 → keine, über 10.000 → Warnung).

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • KI führt Suchen aus und startet Verkaufsprozesse nach Bestätigung

[F-M7-03] KI-Copilot – Dokumente erstellen

Anforderung: KI kann Dokumente erstellen („Erstelle Kaufvertrag für Fahrzeug FIN XYZ an Müller GmbH"). KI sammelt alle nötigen Daten und generiert PDF. KI darf selbstständig handeln.

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: „Erstelle Rechnung für letzten Verkauf". Erwartet: Rechnungs-PDF wird generiert mit Daten aus letztem Verkauf.
  2. Edge Case: „Erstelle Kaufvertrag" ohne Kunden- oder Fahrzeugdaten. Erwartet: KI fragt nach fehlenden Daten.
  3. Integration: KI erstellt Kaufvertrag und löst USt-IdNr.-Prüfung aus. Erwartet: Vertrag generiert, manuelle Prüfung angefordert, Ergebnis im Vertrag.

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • KI generiert Dokumente korrekt via OpenRouter

[F-M7-04] KI-Copilot – Spracheingabe

Anforderung: KI-Assistent akzeptiert Spracheingabe (Microphone-Input) zusätzlich zu Text. Sprache wird zu Text transkribiert (via OpenRouter oder Browser Web Speech API) und dann als Befehl verarbeitet.

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: User spricht „Lege neues Fahrzeug an: Volvo FH16, Baujahr 2020, 80000 Stunden, 55000 Euro". Erwartet: Sprache wird transkribiert, Fahrzeugformular vorausgefüllt.
  2. Edge Case: Unverständliche Spracheingabe. Erwartet: KI fragt „Konnte Sie nicht verstehen, bitte wiederholen".
  3. Integration: Spracheingabe wird genutzt um Verkauf zu starten. Erwartet: Transkribierter Text wird als Befehl verarbeitet, Verkaufsprozess startet.

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • Spracheingabe funktioniert, Transkription korrekt, Befehl wird ausgeführt

Modul M8: KI Bildretusche & Preisvergleich

[F-M8-01] KI Bildretusche – Hintergrund entfernen

Anforderung: Fahrzeugfoto hochladen, OpenRouter Flux.1-Pro entfernt Hintergrund und ersetzt durch neutralen (weiß/grau). Ergebnis kann gespeichert werden. Foto wird in Fahrzeug-Dateiablage abgelegt.

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: Foto eines LKW vor einer Werkstatt wird hochgeladen. Erwartet: Flux.1-Pro entfernt Hintergrund, neutraler Hintergrund, Fahrzeug klar erkennbar.
  2. Edge Case: Foto mit sehr geringer Auflösung. Erwartet: Warnung „Niedrige Auflösung", best-effort Retusche, User kann Original behalten.
  3. Integration: Retuschiertes Foto wird in Fahrzeug-Dateiablage gespeichert. Erwartet: Foto erscheint in Dateiablage, kann für mobile.de-Listing verwendet werden.

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • Bildretusche via Flux.1-Pro funktioniert, Ergebnis speicherbar

[F-M8-02] KI Bildretusche – Spiegelungen entfernen

Anforderung: Spiegelungen und Reflexionen auf Fahrzeugoberfläche werden durch OpenRouter Flux.1-Pro reduziert/entfernt. Batch-Verarbeitung für mehrere Fotos eines Fahrzeugs.

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: Foto mit starker Spiegelung wird hochgeladen. Erwartet: Flux.1-Pro reduziert Spiegelung, Fahrzeugoberfläche klarer.
  2. Edge Case: Foto ohne Spiegelungen. Erwartet: Foto bleibt unverändert, Hinweis „Keine Retusche nötig".
  3. Integration: Batch von 5 Fotos wird verarbeitet. Erwartet: Alle 5 Fotos retuschiert, Fortschrittsanzeige, alle speicherbar.

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • Spiegelungs-Retusche und Batch-Verarbeitung via Flux.1-Pro funktionieren

[F-M8-03] Preisvergleich mobile.de für ähnliche Fahrzeuge

Anforderung: Für ein Fahrzeug im Bestand werden ähnliche Inserate auf mobile.de gesucht (gleiche Marke/Modell, ähnliches Baujahr/KM/Stunden). Vergleichspreise werden grafisch aufbereitet (Durchschnitt, Median, Preisverteilung). Read-Only (kein Import).

Test Scenarios (Pflicht, mind. 2):

  1. Happy Path: Für Mercedes Actros 2019 werden mobile.de-Vergleichspreise abgerufen. Erwartet: Liste mit 5-20 vergleichbaren Fahrzeugen, Durchschnittspreis berechnet.
  2. Edge Case: Sehr seltenes Fahrzeug, keine Vergleiche auf mobile.de. Erwartet: Hinweis „Keine Vergleichsfahrzeuge", Empfehlung basierend auf weiter gefassten Kriterien.
  3. Integration: Preisvergleich wird angezeigt, User entscheidet Preisanpassung. Erwartet: Preis wird im ERP aktualisiert, optional mobile.de Push-Sync.

Akzeptanzkriterium:

  • Build erfolgreich
  • Alle 3 Tests grün
  • Preisvergleich zeigt mobile.de-Daten, grafische Aufbereitung, Read-Only

4. Rollen & Berechtigungen

Rollen-Definition

Rolle Beschreibung
Admin Vollzugriff auf alle Module, Einstellungen, Vorlagen, Benutzer-Verwaltung
Verkäufer Fahrzeugbestand, mobile.de Sync, Kontakte, Verkauf, Dateiablage, KI-Copilot, Bildretusche
Buchhaltung Verkauf (Lesen), Rechnungen, DATEV-Export, Ausweisdaten (GwG), USt-IdNr.-Prüfung

Berechtigungs-Matrix

Modul / Feature Admin Verkäufer Buchhaltung
M1: Fahrzeugbestand (CRUD) ✅ ✅ 📖
M1: mobile.de Push-Sync ✅ ✅ ❌
M2: OCR Erfassung ✅ ✅ ❌
M3: Kontaktverwaltung (CRUD) ✅ ✅ 📖
M4: Dateiablage ✅ ✅ 📖
M5: Kaufvertrag erstellen ✅ ✅ 📖
M5: USt-IdNr.-Prüfung ✅ ❌ ✅
M5: Geldwäsche-Prävention ✅ 📖 ✅
M5: Rechnung & Lieferbescheinigung ✅ 📖 ✅
M5: DATEV-Export ✅ ❌ ✅
M5: Vertragsvorlagen-Verwaltung ✅ ❌ ❌
M6: Responsive UI ✅ ✅ ✅
M6: i18n (Sprache wählen) ✅ ✅ ✅
M7: KI-Copilot ✅ ✅ 📖
M8: KI Bildretusche ✅ ✅ ❌
M8: Preisvergleich ✅ ✅ 📖
Einstellungen / Stammdaten ✅ ❌ ❌
Benutzer-Verwaltung ✅ ❌ ❌

✅ = Vollzugriff | 📖 = Nur Lesen | ❌ = Kein Zugriff

5. mobile.de Seller API – Push-Only Felder

Sync-Richtung: Push-Only (ERP → mobile.de, NICHT bidirektional)

Feldmapping ERP → mobile.de

ERP-Feld mobile.de Seller API Feld Anmerkung
Marke make Pflichtfeld
Modell/Typ model Pflichtfeld
FIN vin 17 Zeichen
Baujahr firstRegistration YYYY-MM
Kilometerstand / Betriebsstunden mileage Einheit: km oder h (mobile.de supported hours für Baumaschinen)
Preis price EUR, netto/brutto kennzeichnen
Leistung kW powerKw Pflichtfeld für LKW
Leistung PS powerHp Berechnet aus kW
Kraftstoffart fuelType diesel, petrol, electric, etc.
Getriebe transmission manual, automatic
Farbe color
Zustand condition new, used
LKW-Typ category LKW-spezifische Kategorie
Art (Bagger, Radlader, etc.) bodyType Baumaschinen-spezifisch
Aufbau equipment Freitext
Standort sellerLocation PLZ, Ort
Fotos images URLs oder Base64
Beschreibung description Freitext, multi-language
Verfügbarkeit availabilityStatus available, reserved, sold

API-Endpunkte (Push)

  • Listing erstellen: POST /api/seller/listings
  • Listing aktualisieren: PUT /api/seller/listings/{listingId}
  • Listing entfernen: DELETE /api/seller/listings/{listingId}
  • Listing-Status: GET /api/seller/listings/{listingId}/status

6. OpenRouter Modell-Empfehlungen

Use Case Modell OpenRouter ID Begründung
KI-Copilot (Text + Sprache) Bestes verfügbares Modell openrouter/auto oder claude-3.5-sonnet, gpt-4o Flexibel, Auto-Routing wählt bestes Modell
OCR ZB I/II (Vision) Qwen2.5-VL qwen/qwen-2.5-vl-72b-instruct Spezialisiert auf Dokumenterkennung, Multilingual
Bildretusche (Hintergrund/Spiegelungen) Flux.1-Pro black-forest-labs/flux-1.1-pro State-of-the-art Bildgenerierung/-bearbeitung
Fahrzeugfoto-Analyse Qwen2.5-VL qwen/qwen-2.5-vl-72b-instruct Vision-Modell für Bildverständnis

DSGVO-Hinweis

  • OpenRouter verarbeitet Daten in der Cloud (User hat zugestimmt)
  • Keine sensiblen Personendaten an OpenRouter senden (Ausweisdaten NICHT an KI übertragen)
  • Fahrzeugdaten und Fotos werden an OpenRouter gesendet (keine Ausweisdaten auf Fotos)

7. MVP-Phasen-Vorschlag

Phase Module Inhalt Priorität
Phase 1 M1 Fahrzeugbestand + mobile.de Push-Sync Höchste – Kernfunktion
Phase 2 M3 Kontakt- & Kundenverwaltung Hoch – Voraussetzung für Verkauf
Phase 3 M4 Dateiablage pro Fahrzeug Hoch – Voraussetzung für OCR/Bildretusche
Phase 4 M2 OCR Fahrzeugdaten-Erfassung Mittel – Effizienz-Feature
Phase 5 M5 Verkaufsmodul mit Rechtsdokumenten Hoch – Geschäftsprozess
Phase 6 M7 KI-Copilot Mittel – Automatisierung
Phase 7 M8 KI Bildretusche & Preisvergleich Niedrig – Optimierung
Querschnitt M6 Responsive UI + i18n Alle Phasen – gilt überall

Phasen-Abhängigkeiten

Phase 1 (M1) → Phase 2 (M3) → Phase 3 (M4) → Phase 4 (M2)
                                                  ↓
Phase 5 (M5) ←Phase 2 (M3) ←Phase 1 (M1)
      ↓
Phase 6 (M7) → Phase 7 (M8)

M6 (Responsive UI + i18n) läuft parallel zu allen Phasen.

8. Sicherheit & Compliance

DSGVO-Konformität

  • Ausweisdaten: Verschlüsselt in PostgreSQL gespeichert (AES-256), Zugriff nur Admin + Buchhaltung
  • Personendaten: DSGVO-konform, Löschkonzept für Kunden-Daten (Aufbewahrungsfristen beachten)
  • OpenRouter: Cloud-Verarbeitung akzeptiert, keine Ausweisdaten an KI senden
  • Audit-Log: Alle Änderungen an Kundendaten werden protokolliert (Wer, Was, Wann)

Geldwäsche-Prävention (GwG)

  • Identifikation bei Barzahlungen > 10.000 € (Ausweisdaten erfassen)
  • Meldepflicht wird systemseitig angezeigt
  • Meldedokument wird vorbereitet
  • Dokumentation der Identifikation im Kaufvertrag

Technische Sicherheit

  • CSRF: Token-basiert (FastAPI + Next.js)
  • XSS: Input-Sanitization, CSP-Headers
  • SQL-Injection: ORM (SQLAlchemy), keine raw SQL queries
  • File-Upload-Validation: MIME-Type-Check, Größenlimit 50MB, Virenscan empfohlen
  • Auth: JWT-basiert, Session-Timeout 30min, Refresh-Token
  • HTTPS: Via Coolify/Traefik (Let's Encrypt)

9. Constraints (Technische Rahmenbedingungen)

Tech-Stack (finalisiert)

  • Backend: Python 3.12+ / FastAPI
  • Frontend: React 18+ / Next.js 14+ / TypeScript
  • Datenbank: PostgreSQL 16+
  • ORM: SQLAlchemy 2.0 (async)
  • KI/OCR/Bild: OpenRouter API (Qwen2.5-VL, Flux.1-Pro, Claude/GPT-4)
  • Auth: JWT (python-jose) + bcrypt
  • PDF-Generierung: WeasyPrint oder ReportLab
  • DATEV-Export: CSV (Python csv module)
  • i18n: next-intl (Next.js) + FastAPI gettext

Hosting

  • Plattform: Coolify self-hosted auf eigenem Server
  • Container: Docker Compose (app, db, redis optional)
  • SSL: Let's Encrypt via Traefik
  • Domain: Zu klären (Coolify verwaltet)

Externe APIs

  • mobile.de Seller API: REST API (Push-Only)
  • OpenRouter: LLM + Vision + Bildgenerierung
  • BZSt eVatR API: NICHT verfügbar im MVP (manuelle Prüfung)
  • DATEV: Keine API, CSV-Export

Budget/Timeline

  • API-Kosten: OpenRouter (pay-per-use), mobile.de (Händleraccount)
  • Timeline: MVP-Phasen sequenziell, keine harten Deadlines

10. Non-Goals (Explizit nicht Teil des Systems)

  • Kein komplettes Buchhaltungssystem (Fibu, Bilanz, Steuererklärung)
  • Kein Werkstatt-/Reparatur-Auftragsmanagement
  • Kein Ersatzteil-/Lagerverwaltung
  • Kein Fuhrparkmanagement / Telematik
  • Kein eigenes Zahlungs-Gateway (Zahlungsabwicklung extern)
  • Kein mobile App (nur responsive Web-UI)
  • Kein eigenes KI-Modell-Training (Nutzung externer APIs via OpenRouter)
  • Kein Marketing-/Newsletter-System
  • Kein Versandlogistik-/Transportmanagement
  • Kein mobile.de Import (nur Push, NICHT bidirektional)
  • Kein BZSt eVatR API-Integration im MVP (manuelle Prüfung)
  • Keine Datenmigration (keine Bestandsdaten zu importieren)

11. Annahmen (Assumptions)

  1. Der User hat einen aktiven mobile.de Händleraccount mit Seller API-Zugang
  2. Der User verfügt über deutsche Zulassungsbescheinigungen (ZB I und ZB II) für OCR-Erfassung
  3. Der User ist umsatzsteuerpflichtig und benötigt USt-IdNr.-Prüfung für EU-Lieferungen
  4. Der User verkauft an B2B (Firmen) und ggf. B2C (Privatkunden)
  5. Der User hat Budget für OpenRouter API-Kosten (pay-per-use)
  6. Das System wird von ~10 Nutzern im Büro genutzt (kein Massen-System)
  7. Rechtsdokumente basieren auf deutschem/EU-Recht
  8. KI-Copilot benötigt Internetverbindung (OpenRouter Cloud)
  9. DSGVO: Cloud-Verarbeitung via OpenRouter ist akzeptiert
  10. BZSt eVatR API-Zugang ist NICHT vorhanden – manuelle Prüfung im MVP
  11. Keine Datenmigration von Altsystemen nötig
  12. Vertragsvorlagen werden als Stammdaten vom Admin gepflegt
  13. KI darf selbstständig handeln (nach User-Bestätigung)
  14. ~10 Nutzer mit Rollen Admin/Verkäufer/Buchhaltung
  15. i18n: Deutsch + Englisch von Anfang an

12. Discovery Checklist (20 Kategorien)

# Kategorie Status Anmerkung
1 Auth ja JWT-Auth, 3 Rollen (Admin/Verkäufer/Buchhaltung), ~10 Nutzer, Session-Timeout 30min
2 Daten ja Validierung, Pagination, Search/Filter in M1/M3 definiert, Soft-Delete für Fahrzeuge/Kontakte
3 Fehler ja Toast-Notifications, Error-Pages (404/500), API-Fehler-Handling, Error-Logging
4 Skalierung nein ~10 Nutzer, keine Skalierungsanforderungen, keine Caching/Rate-Limiting nötig
5 Sicherheit ja CSRF, XSS, SQL-Injection-Schutz, File-Upload-Validation, DSGVO, Ausweisdaten verschlüsselt
6 UX ja Responsive (M6), Loading-States, Empty-States, Confirmation-Dialogs, i18n DE+EN
7 Infrastruktur später Backup/Restore via Coolify, Monitoring/Alerting später, Health-Checks via FastAPI
8 Multi-User ja ~10 Nutzer, 3 Rollen, Concurrency via DB-Locking (optimistic), keine Real-time-Updates nötig
9 Migration nein Keine Datenmigration nötig (keine Altsysteme)
10 Mobile ja Responsive Web-UI (M6), keine native App, Touch-optimiert
11 Integration ja mobile.de Seller API (Push), OpenRouter (LLM/Vision/Bild), DATEV-Export (CSV)
12 Compliance ja DSGVO, Geldwäsche-Prävention (GwG), USt-IdNr.-Prüfung (manuell), Audit-Log
13 Performance später Standard-Optimierung, PostgreSQL-Indizes, Lazy Loading, keine speziellen Anforderungen
14 i18n ja Deutsch + Englisch, Datums-/Zahlenformate, Sprache pro User einstellbar
15 Accessibility später Grundlegende WCAG-Konformität (Keyboard-Nav, Kontrast), Standard-Implementation
16 Analytics/Tracking nein Kein Usage-Tracking im MVP
17 Environments ja Dev + Prod via Coolify (Docker), Env-Variablen in Coolify, Secrets-Management via Coolify
18 Dokumentation später User-Docs/API-Docs nach MVP, OpenAPI-Auto-Docs via FastAPI verfügbar
19 Testing-Strategie ja pytest (Backend), jest/playwright (Frontend), Coverage-Target ≥80%, E2E für Kernprozesse
20 Naming/Branding später Projektname/Branding – zu klären mit User, Domain via Coolify
21 Scheduling/Background-Jobs später mobile.de Sync ggf. als Cron-Job – MVP: manuell, OpenRouter API-Calls async

Status: 21/21 Kategorien beantwortet (Kategorie 21 = Scheduling, optional)

13. Test Coverage Summary

Feature ID Feature Test Scenarios Status
F-M1-01 Fahrzeugbestand verwalten 3 ✅
F-M1-02 mobile.de Push-Sync 3 ✅
F-M1-03 mobile.de Listing-Verwaltung 3 ✅
F-M2-01 OCR ZB I (Qwen2.5-VL) 3 ✅
F-M2-02 OCR ZB II (Qwen2.5-VL) 3 ✅
F-M3-01 Kontakt- und Kundenverwaltung 3 ✅
F-M3-02 Kundensuche und Filter 3 ✅
F-M4-01 Dateiablage pro Fahrzeug 3 ✅
F-M5-01 Kaufvertrag erstellen 3 ✅
F-M5-02 USt-IdNr.-Überprüfung (manuell) 3 ✅
F-M5-03 Geldwäsche-Prävention 3 ✅
F-M5-04 Rechnung und Lieferbescheinigung 3 ✅
F-M5-05 DATEV-Export 3 ✅
F-M5-06 Vertragsvorlagen-Verwaltung 3 ✅
F-M6-01 Responsive Web-UI 3 ✅
F-M6-02 Internationalisierung (i18n) 3 ✅
F-M7-01 KI-Copilot – Fahrzeug anlegen 3 ✅
F-M7-02 KI-Copilot – Suchen und Verkaufen 3 ✅
F-M7-03 KI-Copilot – Dokumente erstellen 3 ✅
F-M7-04 KI-Copilot – Spracheingabe 3 ✅
F-M8-01 KI Bildretusche – Hintergrund (Flux.1-Pro) 3 ✅
F-M8-02 KI Bildretusche – Spiegelungen (Flux.1-Pro) 3 ✅
F-M8-03 Preisvergleich mobile.de 3 ✅

Test Coverage: 23/23 Features mit Test-Szenarien (100%)

14. Handoff Summary

  • Requirements Status: Final – Discovery abgeschlossen
  • Discovery Checklist: 21/21 Kategorien beantwortet
  • Test Coverage: 23/23 Features mit je 3 Test-Szenarien (100%)
  • Module: 8 (M1-M8)
  • Features: 23
  • MVP-Phasen: 7 Phasen + 1 Querschnitt (M6)
  • Open Questions: Siehe open_questions.md (alle resolved oder als „später" markiert)
  • Ready for UI Design: YES
  • Ready for Architecture: NO (erst nach UI Design Approval)

15. Offene Fragen

Siehe open_questions.md für kategorisierte Klärungsfragen mit resolved/unresolved Status.

Reference in New Issue View Git Blame Copy Permalink