1157 lines
47 KiB
Markdown
1157 lines
47 KiB
Markdown
# Architecture – ERP-System Nutzfahrzeug-/Baumaschinen-Handel
|
||
|
||
**Version:** 1.0.0
|
||
**Datum:** 2026-07-12
|
||
**Status:** Draft – Ready for Review
|
||
**Architect:** Solution Architect (A0)
|
||
|
||
---
|
||
|
||
## 1. System-Architektur-Übersicht
|
||
|
||
### Container-Diagramm (textuell)
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ Coolify (Docker Host) │
|
||
│ coolify-01 / 46.225.91.159 │
|
||
│ │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ Traefik │──│ Frontend │ │ Backend │ │
|
||
│ │ (SSL/TLS) │ │ Next.js │ │ FastAPI │ │
|
||
│ │ Let's Enc│ │ :3000 │ │ :8000 │ │
|
||
│ └────┬─────┘ └─────┬────┘ └─────┬────┘ │
|
||
│ │ │ │ │
|
||
│ │ │ │ │
|
||
│ ┌────┴──────────────┴───────────────┴────┐ │
|
||
│ │ Docker Network (erp-net) │ │
|
||
│ └──────────────────┬─────────────────────┘ │
|
||
│ │ │
|
||
│ ┌──────────┐ ┌───┴─────┐ ┌──────────┐ │
|
||
│ │ PostgreSQL│ │ Redis │ │ Volume │ │
|
||
│ │ :5432 │ │ :6379 │ │ /data/erp │ │
|
||
│ │ (DB) │ │ (cache) │ │ (uploads) │ │
|
||
│ └──────────┘ └─────────┘ └──────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────┘
|
||
│ │
|
||
▼ ▼
|
||
OpenRouter API mobile.de Seller API
|
||
(LLM/Vision/Bild) (Push-Only REST)
|
||
```
|
||
|
||
### Container-Übersicht
|
||
|
||
| Container | Image | Port | Volume | Beschreibung |
|
||
|---|---|---|---|---|
|
||
| **frontend** | node:20-alpine → Next.js standalone build | 3000 | – | SSR/SSG React Frontend, Tailwind CSS, next-intl |
|
||
| **backend** | python:3.12-slim → FastAPI + Uvicorn | 8000 | – | REST API, SQLAlchemy async, Alembic, OpenRouter Client |
|
||
| **postgres** | postgres:16-alpine | 5432 | pgdata | Primäre Datenbank,持久化存储 |
|
||
| **redis** | redis:7-alpine | 6379 | – | Refresh-Token Store, Background Task Queue (RQ/Celery lite) |
|
||
|
||
### Netzwerk-Architektur
|
||
- **erp-net**: Internes Docker Bridge Network, isoliert von Host
|
||
- **Traefik**: Reverse Proxy mit SSL/TLS (Let's Encrypt), Routing:
|
||
- `erp.domain.tld` → Frontend (Next.js)
|
||
- `erp.domain.tld/api/*` → Backend (FastAPI)
|
||
- **Externe APIs**: Backend ruft OpenRouter + mobile.de Seller API auf (outbound HTTPS)
|
||
|
||
---
|
||
|
||
## 2. Backend-Architektur
|
||
|
||
### Projekt-Struktur
|
||
|
||
```
|
||
backend/
|
||
├── app/
|
||
│ ├── __init__.py
|
||
│ ├── main.py # FastAPI app entry point
|
||
│ ├── config.py # Settings (pydantic-settings)
|
||
│ ├── database.py # SQLAlchemy async engine + session
|
||
│ ├── deps.py # Dependency injection (DB session, current user)
|
||
│ ├── models/ # SQLAlchemy ORM models
|
||
│ │ ├── __init__.py
|
||
│ │ ├── base.py # Declarative base, mixins (TimestampMixin)
|
||
│ │ ├── user.py
|
||
│ │ ├── vehicle.py
|
||
│ │ ├── contact.py
|
||
│ │ ├── sale.py
|
||
│ │ ├── document.py
|
||
│ │ ├── mobile_de.py
|
||
│ │ ├── ai_interaction.py
|
||
│ │ ├── audit_log.py
|
||
│ │ ├── master_data.py
|
||
│ │ └── settings.py
|
||
│ ├── schemas/ # Pydantic v2 request/response schemas
|
||
│ │ ├── __init__.py
|
||
│ │ ├── auth.py
|
||
│ │ ├── vehicle.py
|
||
│ │ ├── contact.py
|
||
│ │ ├── sale.py
|
||
│ │ ├── document.py
|
||
│ │ ├── mobile_de.py
|
||
│ │ ├── ai.py
|
||
│ │ ├── settings.py
|
||
│ │ └── common.py # Pagination, filters, error responses
|
||
│ ├── routers/ # API route handlers
|
||
│ │ ├── __init__.py
|
||
│ │ ├── auth.py
|
||
│ │ ├── vehicles.py
|
||
│ │ ├── contacts.py
|
||
│ │ ├── sales.py
|
||
│ │ ├── documents.py
|
||
│ │ ├── mobile_de.py
|
||
│ │ ├── ai.py
|
||
│ │ ├── settings.py
|
||
│ │ ├── users.py
|
||
│ │ └── dashboard.py
|
||
│ ├── services/ # Business logic layer
|
||
│ │ ├── __init__.py
|
||
│ │ ├── auth_service.py
|
||
│ │ ├── vehicle_service.py
|
||
│ │ ├── contact_service.py
|
||
│ │ ├── sale_service.py
|
||
│ │ ├── document_service.py
|
||
│ │ ├── mobile_de_service.py
|
||
│ │ ├── ocr_service.py
|
||
│ │ ├── copilot_service.py
|
||
│ │ ├── image_retouch_service.py
|
||
│ │ ├── contract_service.py
|
||
│ │ ├── datev_service.py
|
||
│ │ ├── gwg_service.py
|
||
│ │ ├── ust_id_service.py
|
||
│ │ ├── price_comparison_service.py
|
||
│ │ ├── audit_service.py
|
||
│ │ └── openrouter_client.py # Shared OpenRouter HTTP client
|
||
│ ├── middleware/
|
||
│ │ ├── __init__.py
|
||
│ │ ├── auth.py # JWT verification middleware
|
||
│ │ ├── rbac.py # Role-based access control
|
||
│ │ ├── audit.py # Audit logging middleware
|
||
│ │ └── i18n.py # Accept-Language → response locale
|
||
│ ├── utils/
|
||
│ │ ├── __init__.py
|
||
│ │ ├── crypto.py # AES-256 encrypt/decrypt for ID data
|
||
│ │ ├── pdf.py # WeasyPrint PDF generation helper
|
||
│ │ └── pagination.py # Pagination helper
|
||
│ └── exceptions.py # Custom exceptions + handlers
|
||
├── alembic/ # Database migrations
|
||
│ ├── versions/
|
||
│ ├── env.py
|
||
│ └── alembic.ini
|
||
├── tests/
|
||
│ ├── conftest.py # pytest fixtures (async DB, test client)
|
||
│ ├── test_auth.py
|
||
│ ├── test_vehicles.py
|
||
│ ├── test_contacts.py
|
||
│ ├── test_sales.py
|
||
│ ├── test_documents.py
|
||
│ ├── test_mobile_de.py
|
||
│ ├── test_ocr.py
|
||
│ ├── test_copilot.py
|
||
│ ├── test_image_retouch.py
|
||
│ └── test_datev.py
|
||
├── requirements.txt
|
||
├── Dockerfile
|
||
└── pyproject.toml
|
||
```
|
||
|
||
### Layer-Architektur
|
||
|
||
```
|
||
Router (API Layer) → Service (Business Logic) → Model (ORM) → PostgreSQL
|
||
↑ ↑ ↑
|
||
Pydantic Schema Dependencies SQLAlchemy 2.0
|
||
Request/Response (DB Session, User) Async Engine
|
||
```
|
||
|
||
- **Router**: HTTP request handling, input validation (Pydantic), response serialization
|
||
- **Service**: Business logic, orchestration, external API calls, audit logging
|
||
- **Model**: SQLAlchemy ORM, database constraints, relationships
|
||
- **Schema**: Pydantic v2 models for request/response validation
|
||
|
||
---
|
||
|
||
## 3. Frontend-Architektur
|
||
|
||
### Projekt-Struktur
|
||
|
||
```
|
||
frontend/
|
||
├── src/
|
||
│ ├── app/ # Next.js 14 App Router
|
||
│ │ ├── [locale]/ # i18n routing (de, en)
|
||
│ │ │ ├── layout.tsx
|
||
│ │ │ ├── page.tsx # Dashboard
|
||
│ │ │ ├── fahrzeuge/
|
||
│ │ │ │ ├── page.tsx # Fahrzeug-Liste
|
||
│ │ │ │ ├── neu/page.tsx # Fahrzeug-Formular
|
||
│ │ │ │ └── [id]/page.tsx # Fahrzeug-Detail
|
||
│ │ │ ├── kontakte/page.tsx
|
||
│ │ │ ├── verkauf/page.tsx
|
||
│ │ │ ├── ki-copilot/page.tsx
|
||
│ │ │ └── einstellungen/page.tsx
|
||
│ │ └── api/ # Next.js API routes (BFF proxy)
|
||
│ ├── components/ # React components
|
||
│ │ ├── ui/ # Shared (Button, Card, Input, etc.)
|
||
│ │ ├── layout/ # Sidebar, Topbar, AppShell
|
||
│ │ ├── vehicles/ # Vehicle-specific components
|
||
│ │ ├── contacts/
|
||
│ │ ├── sales/
|
||
│ │ ├── ai/ # Copilot, Image retouch
|
||
│ │ └── settings/
|
||
│ ├── lib/
|
||
│ │ ├── api-client.ts # Fetch wrapper with auth
|
||
│ │ ├── auth.ts # JWT token management
|
||
│ │ └── i18n.ts # next-intl config
|
||
│ ├── messages/ # i18n translation files
|
||
│ │ ├── de.json
|
||
│ │ └── en.json
|
||
│ └── styles/
|
||
│ └── globals.css # Tailwind + design tokens
|
||
├── public/
|
||
├── next.config.js
|
||
├── tailwind.config.ts
|
||
├── package.json
|
||
├── Dockerfile
|
||
└── tsconfig.json
|
||
```
|
||
|
||
### Design-Token-System
|
||
|
||
```css
|
||
/* CSS Custom Properties → Tailwind Config */
|
||
--color-primary: #2563eb;
|
||
--color-primary-hover: #1d4ed8;
|
||
--color-success: #16a34a;
|
||
--color-warning: #d97706;
|
||
--color-error: #dc2626;
|
||
--color-neutral-50: #f8fafc;
|
||
--color-neutral-900: #0f172a;
|
||
--radius: 8px;
|
||
--shadow-sm: 0 1px 2px rgba(0,0,0,0.05);
|
||
--breakpoint-mobile: 768px;
|
||
--breakpoint-tablet: 1280px;
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Datenbank-Schema
|
||
|
||
### Übersicht: 15 Tabellen
|
||
|
||
```
|
||
users ──┬── audit_log
|
||
├── ai_interactions
|
||
├── documents (uploaded_by)
|
||
└── ust_id_checks (checked_by)
|
||
|
||
vehicles ──┬── documents
|
||
├── mobile_de_listings
|
||
└── sales (vehicle_id)
|
||
|
||
contacts ──┬── contact_persons
|
||
├── sales (buyer_id, seller_id)
|
||
└── ust_id_checks
|
||
|
||
sales ──┬── identification_data
|
||
└── ust_id_checks (sale_id)
|
||
|
||
master_data (independent)
|
||
contract_templates (independent)
|
||
settings (independent)
|
||
```
|
||
|
||
### Tabellen-Definitionen
|
||
|
||
#### 4.1 users
|
||
|
||
| Spalte | Typ | Constraints | Index |
|
||
|---|---|---|---|
|
||
| id | UUID | PK, default gen_random_uuid() | yes |
|
||
| email | VARCHAR(255) | UNIQUE, NOT NULL | yes |
|
||
| password_hash | VARCHAR(255) | NOT NULL | – |
|
||
| full_name | VARCHAR(255) | NOT NULL | – |
|
||
| role | VARCHAR(20) | NOT NULL, CHECK IN ('admin','verkaeufer','buchhaltung') | – |
|
||
| language | VARCHAR(5) | NOT NULL, DEFAULT 'de' | – |
|
||
| is_active | BOOLEAN | DEFAULT true | – |
|
||
| created_at | TIMESTAMPTZ | DEFAULT now() | – |
|
||
| updated_at | TIMESTAMPTZ | DEFAULT now() | – |
|
||
|
||
#### 4.2 vehicles
|
||
|
||
| Spalte | Typ | Constraints | Index |
|
||
|---|---|---|---|
|
||
| id | UUID | PK | yes |
|
||
| make | VARCHAR(100) | NOT NULL | yes |
|
||
| model | VARCHAR(100) | NOT NULL | yes |
|
||
| fin | VARCHAR(17) | UNIQUE, NOT NULL, CHECK(length=17) | yes |
|
||
| year | INTEGER | – | – |
|
||
| first_registration | DATE | – | – |
|
||
| power_kw | INTEGER | – | – |
|
||
| power_hp | INTEGER | – | – (computed from kW) |
|
||
| fuel_type | VARCHAR(50) | – | – |
|
||
| transmission | VARCHAR(20) | – | – |
|
||
| color | VARCHAR(50) | – | – |
|
||
| condition | VARCHAR(20) | CHECK IN ('new','used') | – |
|
||
| location | VARCHAR(255) | – | – |
|
||
| availability | VARCHAR(20) | CHECK IN ('available','reserved','sold') | yes |
|
||
| price | DECIMAL(12,2) | NOT NULL | yes |
|
||
| vehicle_type | VARCHAR(20) | NOT NULL, CHECK IN ('lkw','pkw','baumaschine','stapler','transporter') | yes |
|
||
| lkw_type | VARCHAR(50) | nullable (nur LKW) | – |
|
||
| machine_type | VARCHAR(50) | nullable (nur Baumaschine) | – |
|
||
| body_type | VARCHAR(100) | nullable | – |
|
||
| operating_hours | DECIMAL(12,1) | nullable (Baumaschine/Stapler) | – |
|
||
| operating_hours_unit | VARCHAR(5) | nullable, CHECK IN ('h','min') | – |
|
||
| mileage_km | INTEGER | nullable (LKW/PKW/Transporter) | – |
|
||
| description | TEXT | nullable | – |
|
||
| created_at | TIMESTAMPTZ | DEFAULT now() | – |
|
||
| updated_at | TIMESTAMPTZ | DEFAULT now() | – |
|
||
| deleted_at | TIMESTAMPTZ | nullable (Soft-Delete) | yes |
|
||
|
||
**Indexes:** idx_vehicles_fin (UNIQUE), idx_vehicles_type, idx_vehicles_availability, idx_vehicles_price, idx_vehicles_deleted_at
|
||
|
||
#### 4.3 contacts
|
||
|
||
| Spalte | Typ | Constraints | Index |
|
||
|---|---|---|---|
|
||
| id | UUID | PK | yes |
|
||
| company_name | VARCHAR(255) | NOT NULL | yes |
|
||
| legal_form | VARCHAR(50) | nullable | – |
|
||
| address_street | VARCHAR(255) | nullable | – |
|
||
| address_zip | VARCHAR(10) | nullable | – |
|
||
| address_city | VARCHAR(100) | nullable | – |
|
||
| address_country | VARCHAR(2) | NOT NULL, DEFAULT 'DE' (ISO 3166-1 alpha-2) | yes |
|
||
| vat_id | VARCHAR(20) | nullable | – |
|
||
| phone | VARCHAR(50) | nullable | – |
|
||
| email | VARCHAR(255) | nullable | – |
|
||
| website | VARCHAR(255) | nullable | – |
|
||
| role | VARCHAR(20) | NOT NULL, CHECK IN ('kaeufer','verkaeufer','beide') | yes |
|
||
| vat_id_status | VARCHAR(20) | DEFAULT 'ungeprueft', CHECK IN ('ungeprueft','geprueft','ungueltig','manuell_bestätigt') | – |
|
||
| is_private | BOOLEAN | DEFAULT false | – |
|
||
| created_at | TIMESTAMPTZ | DEFAULT now() | – |
|
||
| updated_at | TIMESTAMPTZ | DEFAULT now() | – |
|
||
| deleted_at | TIMESTAMPTZ | nullable (Soft-Delete) | yes |
|
||
|
||
#### 4.4 contact_persons
|
||
|
||
| Spalte | Typ | Constraints | Index |
|
||
|---|---|---|---|
|
||
| id | UUID | PK | yes |
|
||
| contact_id | UUID | FK → contacts.id, ON DELETE CASCADE | yes |
|
||
| name | VARCHAR(255) | NOT NULL | – |
|
||
| function | VARCHAR(100) | nullable | – |
|
||
| phone | VARCHAR(50) | nullable | – |
|
||
| email | VARCHAR(255) | nullable | – |
|
||
| created_at | TIMESTAMPTZ | DEFAULT now() | – |
|
||
|
||
#### 4.5 sales
|
||
|
||
| Spalte | Typ | Constraints | Index |
|
||
|---|---|---|---|
|
||
| id | UUID | PK | yes |
|
||
| vehicle_id | UUID | FK → vehicles.id, NOT NULL | yes |
|
||
| buyer_id | UUID | FK → contacts.id, NOT NULL | yes |
|
||
| seller_id | UUID | FK → contacts.id, nullable (Verkäufer = eigene Firma) | – |
|
||
| sale_type | VARCHAR(20) | NOT NULL, CHECK IN ('inland','eu_ausland','drittland') | yes |
|
||
| price_net | DECIMAL(12,2) | NOT NULL | – |
|
||
| price_gross | DECIMAL(12,2) | NOT NULL | – |
|
||
| vat_rate | DECIMAL(5,2) | NOT NULL (0, 7, 19) | – |
|
||
| payment_method | VARCHAR(20) | CHECK IN ('bar','ueberweisung','finanzierung','other') | – |
|
||
| payment_date | DATE | nullable | – |
|
||
| handover_date | DATE | nullable | – |
|
||
| status | VARCHAR(20) | DEFAULT 'entwurf', CHECK IN ('entwurf','pruefung','abgeschlossen','storniert') | yes |
|
||
| contract_number | VARCHAR(50) | nullable, UNIQUE | yes |
|
||
| invoice_number | VARCHAR(50) | nullable, UNIQUE | yes |
|
||
| notes | TEXT | nullable | – |
|
||
| created_at | TIMESTAMPTZ | DEFAULT now() | – |
|
||
| updated_at | TIMESTAMPTZ | DEFAULT now() | – |
|
||
|
||
#### 4.6 documents
|
||
|
||
| Spalte | Typ | Constraints | Index |
|
||
|---|---|---|---|
|
||
| id | UUID | PK | yes |
|
||
| vehicle_id | UUID | FK → vehicles.id, ON DELETE CASCADE | yes |
|
||
| sale_id | UUID | FK → sales.id, nullable, ON DELETE SET NULL | – |
|
||
| filename | VARCHAR(255) | NOT NULL | – |
|
||
| file_path | VARCHAR(500) | NOT NULL (relative to upload root) | – |
|
||
| file_type | VARCHAR(50) | NOT NULL (MIME type) | – |
|
||
| file_size | BIGINT | NOT NULL (bytes) | – |
|
||
| category | VARCHAR(20) | NOT NULL, CHECK IN ('vertrag','rechnung','zb1','zb2','foto','sonstiges') | yes |
|
||
| uploaded_by | UUID | FK → users.id | – |
|
||
| created_at | TIMESTAMPTZ | DEFAULT now() | – |
|
||
|
||
#### 4.7 mobile_de_listings
|
||
|
||
| Spalte | Typ | Constraints | Index |
|
||
|---|---|---|---|
|
||
| id | UUID | PK | yes |
|
||
| vehicle_id | UUID | FK → vehicles.id, UNIQUE (1 vehicle = 1 listing) | yes |
|
||
| mobile_de_id | VARCHAR(100) | nullable (mobile.de listing ID, null until listed) | – |
|
||
| sync_status | VARCHAR(20) | DEFAULT 'entwurf', CHECK IN ('entwurf','gelistet','aktualisiert','fehler','entfernt') | yes |
|
||
| last_sync_at | TIMESTAMPTZ | nullable | – |
|
||
| error_log | TEXT | nullable (last error message) | – |
|
||
| created_at | TIMESTAMPTZ | DEFAULT now() | – |
|
||
| updated_at | TIMESTAMPTZ | DEFAULT now() | – |
|
||
|
||
#### 4.8 ai_interactions
|
||
|
||
| Spalte | Typ | Constraints | Index |
|
||
|---|---|---|---|
|
||
| id | UUID | PK | yes |
|
||
| user_id | UUID | FK → users.id | yes |
|
||
| interaction_type | VARCHAR(20) | CHECK IN ('copilot_text','copilot_voice','ocr_zb1','ocr_zb2','image_retouch','price_comparison') | yes |
|
||
| input_text | TEXT | nullable | – |
|
||
| output_text | TEXT | nullable | – |
|
||
| model_used | VARCHAR(100) | nullable | – |
|
||
| tokens_used | INTEGER | nullable | – |
|
||
| metadata | JSONB | nullable (structured data: extracted fields, etc.) | – |
|
||
| created_at | TIMESTAMPTZ | DEFAULT now() | yes |
|
||
|
||
#### 4.9 audit_log
|
||
|
||
| Spalte | Typ | Constraints | Index |
|
||
|---|---|---|---|
|
||
| id | UUID | PK | yes |
|
||
| user_id | UUID | FK → users.id, nullable (system actions) | – |
|
||
| action | VARCHAR(50) | NOT NULL (e.g. 'create','update','delete','login','export') | yes |
|
||
| entity_type | VARCHAR(50) | NOT NULL (e.g. 'vehicle','contact','sale') | yes |
|
||
| entity_id | UUID | nullable | – |
|
||
| old_values | JSONB | nullable | – |
|
||
| new_values | JSONB | nullable | – |
|
||
| created_at | TIMESTAMPTZ | DEFAULT now() | yes |
|
||
|
||
#### 4.10 master_data
|
||
|
||
| Spalte | Typ | Constraints | Index |
|
||
|---|---|---|---|
|
||
| id | UUID | PK | yes |
|
||
| category | VARCHAR(50) | NOT NULL (e.g. 'steuerklasse','waehrung','incoterm','kraftstoffart','getriebe','farbe','land','rechtsform','fahrzeugtyp','lkw_typ','maschinenart','aufbau','zahlungsmethode') | yes (composite with key) |
|
||
| key | VARCHAR(100) | NOT NULL | – |
|
||
| value_de | VARCHAR(255) | NOT NULL | – |
|
||
| value_en | VARCHAR(255) | nullable | – |
|
||
| sort_order | INTEGER | DEFAULT 0 | – |
|
||
| is_active | BOOLEAN | DEFAULT true | – |
|
||
|
||
**Unique Index:** idx_master_data_category_key (category, key) UNIQUE
|
||
|
||
#### 4.11 contract_templates
|
||
|
||
| Spalte | Typ | Constraints | Index |
|
||
|---|---|---|---|
|
||
| id | UUID | PK | yes |
|
||
| template_type | VARCHAR(30) | NOT NULL, CHECK IN ('kaufvertrag_inland','kaufvertrag_eu','kaufvertrag_drittland','rechnung','lieferbescheinigung') | yes |
|
||
| name | VARCHAR(255) | NOT NULL | – |
|
||
| content_de | TEXT | NOT NULL (HTML/Markdown template with {{variables}}) | – |
|
||
| content_en | TEXT | nullable | – |
|
||
| variables | JSONB | nullable (array of variable names: ["fahrzeug","kaeufer","preis",...]) | – |
|
||
| is_active | BOOLEAN | DEFAULT true | – |
|
||
| created_at | TIMESTAMPTZ | DEFAULT now() | – |
|
||
| updated_at | TIMESTAMPTZ | DEFAULT now() | – |
|
||
|
||
#### 4.12 identification_data
|
||
|
||
| Spalte | Typ | Constraints | Index |
|
||
|---|---|---|---|
|
||
| id | UUID | PK | yes |
|
||
| sale_id | UUID | FK → sales.id, UNIQUE (1:1), ON DELETE CASCADE | yes |
|
||
| id_type | VARCHAR(30) | NOT NULL, CHECK IN ('personalausweis','reisepass','fuehrerschein','anderes') | – |
|
||
| id_number_encrypted | BYTEA | NOT NULL (AES-256-GCM encrypted) | – |
|
||
| issuing_country | VARCHAR(2) | NOT NULL (ISO 3166-1 alpha-2) | – |
|
||
| checked_by | UUID | FK → users.id | – |
|
||
| created_at | TIMESTAMPTZ | DEFAULT now() | – |
|
||
|
||
**Security:** `id_number_encrypted` wird mit AES-256-GCM verschlüsselt. Key aus Environment-Variable `ENCRYPTION_KEY`. Nur Admin + Buchhaltung können entschlüsseln.
|
||
|
||
#### 4.13 ust_id_checks
|
||
|
||
| Spalte | Typ | Constraints | Index |
|
||
|---|---|---|---|
|
||
| id | UUID | PK | yes |
|
||
| contact_id | UUID | FK → contacts.id | yes |
|
||
| sale_id | UUID | FK → sales.id, nullable | – |
|
||
| vat_id | VARCHAR(20) | NOT NULL | – |
|
||
| check_result | VARCHAR(20) | NOT NULL, CHECK IN ('gueltig','ungueltig','unbekannt') | – |
|
||
| check_method | VARCHAR(20) | NOT NULL, DEFAULT 'manuell', CHECK IN ('manuell','bzst_api') | – |
|
||
| check_date | DATE | NOT NULL | – |
|
||
| checked_by | UUID | FK → users.id | – |
|
||
| created_at | TIMESTAMPTZ | DEFAULT now() | – |
|
||
|
||
#### 4.14 settings
|
||
|
||
| Spalte | Typ | Constraints | Index |
|
||
|---|---|---|---|
|
||
| id | UUID | PK | yes |
|
||
| key | VARCHAR(100) | UNIQUE, NOT NULL | yes |
|
||
| value | JSONB | NOT NULL (flexible structure) | – |
|
||
| category | VARCHAR(50) | NOT NULL (e.g. 'firmenprofil','system','mobile_de','openrouter') | yes |
|
||
| updated_by | UUID | FK → users.id | – |
|
||
| updated_at | TIMESTAMPTZ | DEFAULT now() | – |
|
||
|
||
**Beispiel-Keys:** `firmenprofil.name`, `firmenprofil.adresse`, `firmenprofil.ust_id`, `system.datev_berater`, `system.datev_mandant`, `mobile_de.api_key_ref`, `openrouter.api_key_ref`
|
||
|
||
#### 4.15 ust_id_status_history
|
||
|
||
| Spalte | Typ | Constraints | Index |
|
||
|---|---|---|---|
|
||
| id | UUID | PK | yes |
|
||
| contact_id | UUID | FK → contacts.id, ON DELETE CASCADE | yes |
|
||
| old_status | VARCHAR(20) | nullable | – |
|
||
| new_status | VARCHAR(20) | NOT NULL | – |
|
||
| changed_by | UUID | FK → users.id | – |
|
||
| changed_at | TIMESTAMPTZ | DEFAULT now() | yes |
|
||
|
||
---
|
||
|
||
## 5. API-Design
|
||
|
||
### Konventionen
|
||
- **Base URL:** `/api/v1`
|
||
- **Format:** JSON (request + response)
|
||
- **Auth:** `Authorization: Bearer <JWT>` (alle Endpoints außer /auth/login)
|
||
- **Pagination:** `?page=1&page_size=20` → Response: `{ items: [...], total: N, page: 1, page_size: 20 }`
|
||
- **Sort:** `?sort=field` oder `?sort=-field` (descending)
|
||
- **Filter:** Module-spezifische Query-Parameter
|
||
- **Error Format:** `{ error: { code: "NOT_FOUND", message: "Vehicle not found", details: {} } }`
|
||
- **i18n:** `Accept-Language: de|en` → Fehlermeldungen in entsprechender Sprache
|
||
|
||
### Endpoint-Übersicht: 42 Endpoints
|
||
|
||
#### 5.1 Auth (4)
|
||
|
||
| Method | Path | Description | Roles |
|
||
|---|---|---|---|
|
||
| POST | /api/v1/auth/login | Login (email, password) → JWT + refresh | public |
|
||
| POST | /api/v1/auth/refresh | Refresh-Token → neuer JWT | public (refresh token) |
|
||
| POST | /api/v1/auth/logout | Logout (invalidate refresh token) | all |
|
||
| GET | /api/v1/auth/me | Aktueller User + Berechtigungen | all |
|
||
|
||
#### 5.2 Users (4)
|
||
|
||
| Method | Path | Description | Roles |
|
||
|---|---|---|---|
|
||
| GET | /api/v1/users | User-Liste (pagination) | admin |
|
||
| POST | /api/v1/users | User anlegen | admin |
|
||
| PUT | /api/v1/users/:id | User bearbeiten | admin |
|
||
| DELETE | /api/v1/users/:id | User deaktivieren (soft) | admin |
|
||
|
||
#### 5.3 Dashboard (1)
|
||
|
||
| Method | Path | Description | Roles |
|
||
|---|---|---|---|
|
||
| GET | /api/v1/dashboard/stats | KPIs, letzte Aktivitäten, Top-Fahrzeuge | all |
|
||
|
||
#### 5.4 Vehicles (5)
|
||
|
||
| Method | Path | Description | Roles |
|
||
|---|---|---|---|
|
||
| GET | /api/v1/vehicles | Fahrzeug-Liste (filter, sort, pagination, search) | all (📖 für buchhaltung) |
|
||
| POST | /api/v1/vehicles | Fahrzeug anlegen | admin, verkaeufer |
|
||
| GET | /api/v1/vehicles/:id | Fahrzeug-Detail | all (📖) |
|
||
| PUT | /api/v1/vehicles/:id | Fahrzeug bearbeiten | admin, verkaeufer |
|
||
| DELETE | /api/v1/vehicles/:id | Fahrzeug soft-delete | admin, verkaeufer |
|
||
|
||
**Query-Parameter GET /vehicles:** `?type=baumaschine&availability=available&min_price=10000&max_price=50000&search=mercedes&sort=-created_at&page=1&page_size=20`
|
||
|
||
#### 5.5 Vehicle OCR (2)
|
||
|
||
| Method | Path | Description | Roles |
|
||
|---|---|---|---|
|
||
| POST | /api/v1/vehicles/ocr/zb1 | Upload ZB I foto → OpenRouter Qwen2.5-VL → extracted fields | admin, verkaeufer |
|
||
| POST | /api/v1/vehicles/ocr/zb2 | Upload ZB II foto → OpenRouter Qwen2.5-VL → extracted fields | admin, verkaeufer |
|
||
|
||
**Request:** multipart/form-data with image file (max 10MB)
|
||
**Response:** `{ fields: { make: "Mercedes", fin: "WDF...", ... }, confidence: 0.92, warnings: [] }`
|
||
|
||
#### 5.6 Vehicle Documents (3)
|
||
|
||
| Method | Path | Description | Roles |
|
||
|---|---|---|---|
|
||
| GET | /api/v1/vehicles/:id/documents | Dokument-Liste pro Fahrzeug (filter by category) | all (📖) |
|
||
| POST | /api/v1/vehicles/:id/documents | Dokument hochladen (multipart, max 50MB) | admin, verkaeufer |
|
||
| DELETE | /api/v1/vehicles/:id/documents/:doc_id | Dokument löschen | admin, verkaeufer |
|
||
|
||
#### 5.7 mobile.de (5)
|
||
|
||
| Method | Path | Description | Roles |
|
||
|---|---|---|---|
|
||
| POST | /api/v1/vehicles/:id/mobile-de/push | Einzeln push (create/update) | admin, verkaeufer |
|
||
| DELETE | /api/v1/vehicles/:id/mobile-de/listing | Delisting auf mobile.de | admin, verkaeufer |
|
||
| GET | /api/v1/mobile-de/listings | Listing-Übersicht (filter by sync_status) | admin, verkaeufer |
|
||
| POST | /api/v1/mobile-de/batch-push | Batch-Push für mehrere Fahrzeuge | admin, verkaeufer |
|
||
| GET | /api/v1/mobile-de/listings/:id/status | Listing-Status abrufen | admin, verkaeufer |
|
||
|
||
#### 5.8 Contacts (5)
|
||
|
||
| Method | Path | Description | Roles |
|
||
|---|---|---|---|
|
||
| GET | /api/v1/contacts | Kontakt-Liste (search, filter by role/country/vat_status) | all (📖) |
|
||
| POST | /api/v1/contacts | Kontakt anlegen | admin, verkaeufer |
|
||
| GET | /api/v1/contacts/:id | Kontakt-Detail mit Ansprechpartnern | all (📖) |
|
||
| PUT | /api/v1/contacts/:id | Kontakt bearbeiten | admin, verkaeufer |
|
||
| DELETE | /api/v1/contacts/:id | Kontakt soft-delete | admin, verkaeufer |
|
||
|
||
#### 5.9 Sales (6)
|
||
|
||
| Method | Path | Description | Roles |
|
||
|---|---|---|---|
|
||
| GET | /api/v1/sales | Verkaufs-Liste (filter by status, type, date range) | all (📖) |
|
||
| POST | /api/v1/sales | Verkauf anlegen (startet Verkaufsprozess) | admin, verkaeufer |
|
||
| GET | /api/v1/sales/:id | Verkaufs-Detail | all (📖) |
|
||
| PUT | /api/v1/sales/:id | Verkauf bearbeiten (Status-Wechsel, Daten) | admin, verkaeufer (buchhaltung für status) |
|
||
| POST | /api/v1/sales/:id/contract | Kaufvertrag-PDF generieren | admin, verkaeufer |
|
||
| POST | /api/v1/sales/:id/invoice | Rechnung-PDF generieren | admin, buchhaltung |
|
||
|
||
#### 5.10 Sales – Compliance (3)
|
||
|
||
| Method | Path | Description | Roles |
|
||
|---|---|---|---|
|
||
| POST | /api/v1/sales/:id/ust-id-check | USt-IdNr.-Prüfung (manuell) eintragen | admin, buchhaltung |
|
||
| POST | /api/v1/sales/:id/identification | Identifikation (GwG) erfassen | admin, buchhaltung |
|
||
| GET | /api/v1/sales/:id/delivery-certificate | Lieferbescheinigung-PDF generieren | admin, buchhaltung |
|
||
|
||
#### 5.11 DATEV-Export (1)
|
||
|
||
| Method | Path | Description | Roles |
|
||
|---|---|---|---|
|
||
| GET | /api/v1/sales/datev-export | DATEV-CSV Export (?from=2026-01-01&to=2026-01-31) | admin, buchhaltung |
|
||
|
||
#### 5.12 KI Copilot (3)
|
||
|
||
| Method | Path | Description | Roles |
|
||
|---|---|---|---|
|
||
| POST | /api/v1/ai/copilot | Text-Befehl → OpenRouter LLM → strukturierte Aktion | admin, verkaeufer (📖 buchhaltung) |
|
||
| POST | /api/v1/ai/copilot/voice | Audio-Datei → Transkription → Befehl verarbeiten | admin, verkaeufer |
|
||
| GET | /api/v1/ai/interactions | KI-Interaktions-Historie (pagination) | admin, verkaeufer (📖) |
|
||
|
||
#### 5.13 KI Bildretusche (2)
|
||
|
||
| Method | Path | Description | Roles |
|
||
|---|---|---|---|
|
||
| POST | /api/v1/ai/image/retouch | Bild-Retusche (Hintergrund/Spiegelungen) via Flux.1-Pro | admin, verkaeufer |
|
||
| POST | /api/v1/ai/image/batch-retouch | Batch-Retusche für mehrere Fotos | admin, verkaeufer |
|
||
|
||
#### 5.14 Preisvergleich (1)
|
||
|
||
| Method | Path | Description | Roles |
|
||
|---|---|---|---|
|
||
| GET | /api/v1/vehicles/:id/price-comparison | mobile.de Vergleichspreise für ähnliche Fahrzeuge | admin, verkaeufer (📖) |
|
||
|
||
#### 5.15 Settings & Stammdaten (6)
|
||
|
||
| Method | Path | Description | Roles |
|
||
|---|---|---|---|
|
||
| GET | /api/v1/settings | Alle Settings (firmenprofil, system) | admin (alle), others: limited |
|
||
| PUT | /api/v1/settings | Settings aktualisieren | admin |
|
||
| GET | /api/v1/settings/master-data | Stammdaten-Liste (filter by category) | admin |
|
||
| POST | /api/v1/settings/master-data | Stammdatum anlegen | admin |
|
||
| PUT | /api/v1/settings/master-data/:id | Stammdatum bearbeiten | admin |
|
||
| GET | /api/v1/settings/contract-templates | Vertragsvorlagen-Liste | admin |
|
||
| POST | /api/v1/settings/contract-templates | Vorlage anlegen | admin |
|
||
| PUT | /api/v1/settings/contract-templates/:id | Vorlage bearbeiten | admin |
|
||
|
||
#### 5.16 Audit Log (1)
|
||
|
||
| Method | Path | Description | Roles |
|
||
|---|---|---|---|
|
||
| GET | /api/v1/audit-log | Audit-Log (filter by entity_type, user_id, date range) | admin |
|
||
|
||
---
|
||
|
||
## 6. Auth-Konzept
|
||
|
||
### JWT + Refresh Token Flow
|
||
|
||
```
|
||
1. POST /auth/login { email, password }
|
||
→ Validate credentials (bcrypt)
|
||
→ Generate JWT (15min TTL) + Refresh Token (7d TTL)
|
||
→ Store Refresh Token in Redis with user_id
|
||
→ Return { access_token, refresh_token, user: {...} }
|
||
|
||
2. Request: Authorization: Bearer <access_token>
|
||
→ Middleware: Verify JWT, extract user_id + role
|
||
→ Inject current_user into route
|
||
|
||
3. JWT expired → 401
|
||
→ Client: POST /auth/refresh { refresh_token }
|
||
→ Verify refresh token in Redis
|
||
→ Generate new JWT + new refresh token (rotation)
|
||
→ Return { access_token, refresh_token }
|
||
|
||
4. POST /auth/logout { refresh_token }
|
||
→ Delete refresh token from Redis
|
||
```
|
||
|
||
### JWT Payload
|
||
|
||
```json
|
||
{
|
||
"sub": "user-uuid",
|
||
"role": "admin|verkaeufer|buchhaltung",
|
||
"email": "user@example.com",
|
||
"lang": "de",
|
||
"exp": 1234567890,
|
||
"iat": 1234567890
|
||
}
|
||
```
|
||
|
||
### Rollen-Berechtigungs-Matrix (Endpoint-Level)
|
||
|
||
Implementiert via `Depends(require_role(["admin", "verkaeufer"]))` Decorator.
|
||
|
||
| Endpoint-Gruppe | Admin | Verkäufer | Buchhaltung |
|
||
|---|---|---|---|
|
||
| /auth/* | ✅ | ✅ | ✅ |
|
||
| /users (CRUD) | ✅ | ❌ | ❌ |
|
||
| /vehicles (CRUD) | ✅ RW | ✅ RW | 📖 R |
|
||
| /vehicles/ocr/* | ✅ | ✅ | ❌ |
|
||
| /vehicles/:id/documents | ✅ RW | ✅ RW | 📖 R |
|
||
| /mobile-de/* | ✅ | ✅ | ❌ |
|
||
| /contacts (CRUD) | ✅ RW | ✅ RW | 📖 R |
|
||
| /sales (CRUD) | ✅ RW | ✅ RW | 📖 R |
|
||
| /sales/:id/contract | ✅ | ✅ | ❌ |
|
||
| /sales/:id/invoice | ✅ | ❌ | ✅ |
|
||
| /sales/:id/ust-id-check | ✅ | ❌ | ✅ |
|
||
| /sales/:id/identification | ✅ | ❌ | ✅ |
|
||
| /sales/datev-export | ✅ | ❌ | ✅ |
|
||
| /ai/copilot/* | ✅ | ✅ | 📖 |
|
||
| /ai/image/* | ✅ | ✅ | ❌ |
|
||
| /vehicles/:id/price-comparison | ✅ | ✅ | 📖 |
|
||
| /settings/* | ✅ | ❌ | ❌ |
|
||
| /audit-log | ✅ | ❌ | ❌ |
|
||
|
||
---
|
||
|
||
## 7. Dateiablage-Konzept
|
||
|
||
### Architektur
|
||
|
||
```
|
||
Backend Container
|
||
├── /data/uploads/ ← Coolify Volume Mount (persistent)
|
||
│ ├── vehicles/
|
||
│ │ ├── {vehicle_id}/
|
||
│ │ │ ├── {doc_id}_{filename} ← Original-Datei
|
||
│ │ │ └── {doc_id}_thumb.jpg ← Thumbnail (Bilder)
|
||
│ └── contracts/
|
||
│ ├── {sale_id}_vertrag.pdf
|
||
│ └── {sale_id}_rechnung.pdf
|
||
```
|
||
|
||
### Upload-Flow
|
||
1. Client: multipart/form-data → POST /vehicles/:id/documents
|
||
2. Backend: MIME-Type-Check (allowlist), Size-Check (≤50MB)
|
||
3. Backend: Datei speichern unter `/data/uploads/vehicles/{vehicle_id}/{doc_id}_{filename}`
|
||
4. Backend: Thumbnail generieren (für Bilder, Pillow)
|
||
5. Backend: documents-Row in DB anlegen
|
||
6. Response: Document-Metadata
|
||
|
||
### File-Preview
|
||
- **Bilder:** Backend generiert Thumbnail beim Upload. Frontend zeigt Thumbnail + Lightbox.
|
||
- **PDFs:** Frontend nutzt `<iframe>` oder PDF.js Viewer.
|
||
- **Download:** GET /api/v1/vehicles/:id/documents/:doc_id/download (signed URL or direct)
|
||
|
||
### S3-Kompatibel (Future-Proof)
|
||
- Abstraktion via `StorageBackend` Interface (local_filesystem | s3)
|
||
- MVP: Local Filesystem mit Coolify Volume
|
||
- Später: Wechsel zu MinIO oder S3 ohne Code-Änderung (nur Config)
|
||
|
||
---
|
||
|
||
## 8. OpenRouter-Integration
|
||
|
||
### Architektur
|
||
|
||
```
|
||
Backend Service Layer
|
||
├── openrouter_client.py ← Shared HTTP Client (httpx async)
|
||
│ ├── chat_completion() ← LLM Text (Claude/GPT-4)
|
||
│ ├── vision_completion() ← Vision (Qwen2.5-VL)
|
||
│ └── image_generation() ← Bild (Flux.1-Pro)
|
||
│
|
||
├── ocr_service.py ← Nutzt vision_completion()
|
||
├── copilot_service.py ← Nutzt chat_completion()
|
||
└── image_retouch_service.py ← Nutzt image_generation()
|
||
```
|
||
|
||
### API-Calls
|
||
|
||
#### OCR (Qwen2.5-VL)
|
||
```python
|
||
POST https://openrouter.ai/api/v1/chat/completions
|
||
{
|
||
"model": "qwen/qwen-2.5-vl-72b-instruct",
|
||
"messages": [{
|
||
"role": "user",
|
||
"content": [
|
||
{"type": "text", "text": "Extract all fields from this vehicle registration document (ZB I)..."},
|
||
{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,{base64_image}"}}
|
||
]
|
||
}],
|
||
"response_format": {"type": "json_schema", "json_schema": {"name": "zb1_fields", "schema": {...}}}
|
||
}
|
||
```
|
||
|
||
#### KI-Copilot (Claude/GPT-4)
|
||
```python
|
||
POST https://openrouter.ai/api/v1/chat/completions
|
||
{
|
||
"model": "anthropic/claude-3.5-sonnet",
|
||
"messages": [
|
||
{"role": "system", "content": "You are an ERP assistant for a vehicle dealer. Parse user commands and return structured actions..."},
|
||
{"role": "user", "content": "Lege neues Fahrzeug an: Mercedes Actros, Baujahr 2019, 150000 km, 45000 Euro"}
|
||
],
|
||
"response_format": {"type": "json_schema", "json_schema": {"name": "copilot_action", "schema": {"type": "object", "properties": {"action": {"type": "string"}, "data": {"type": "object"}}}}}
|
||
}
|
||
```
|
||
|
||
#### Bildretusche (Flux.1-Pro)
|
||
```python
|
||
POST https://openrouter.ai/api/v1/images/generations
|
||
{
|
||
"model": "black-forest-labs/flux-1.1-pro",
|
||
"prompt": "Remove background from this vehicle photo, replace with neutral white background...",
|
||
"image": "data:image/jpeg;base64,{base64_image}"
|
||
}
|
||
```
|
||
|
||
### DSGVO-Konformität
|
||
- **NICHT** an OpenRouter senden: Ausweisdaten, personenbezogene Kundendaten
|
||
- **Senden erlaubt:** Fahrzeugdaten, Fahrzeugfotos (keine Ausweise auf Fotos), ZB I/ZB II Bilder
|
||
- **AI-Interactions** werden in DB protokolliert (ai_interactions Tabelle)
|
||
|
||
---
|
||
|
||
## 9. mobile.de Seller API Integration
|
||
|
||
### Push-Only Architektur
|
||
|
||
```
|
||
Backend Service Layer
|
||
├── mobile_de_service.py
|
||
│ ├── push_listing(vehicle) → POST /api/seller/listings
|
||
│ ├── update_listing(vehicle) → PUT /api/seller/listings/{id}
|
||
│ ├── delete_listing(listing_id) → DELETE /api/seller/listings/{id}
|
||
│ ├── get_listing_status(id) → GET /api/seller/listings/{id}/status
|
||
│ └── map_fields(vehicle) → ERP → mobile.de Feldmapping
|
||
```
|
||
|
||
### Feldmapping
|
||
|
||
| ERP-Feld | mobile.de Feld | Transformation |
|
||
|---|---|---|
|
||
| make | make | direkt |
|
||
| model | model | direkt |
|
||
| fin | vin | direkt (17 chars) |
|
||
| first_registration | firstRegistration | YYYY-MM Format |
|
||
| mileage_km / operating_hours | mileage | + unit: 'km' or 'h' |
|
||
| price | price | EUR, netto/brutto flag |
|
||
| power_kw | powerKw | direkt |
|
||
| power_hp | powerHp | computed (kW * 1.35962) |
|
||
| fuel_type | fuelType | lowercase mapping |
|
||
| transmission | transmission | lowercase mapping |
|
||
| color | color | direkt |
|
||
| condition | condition | 'new' or 'used' |
|
||
| vehicle_type + lkw_type | category | mapping table |
|
||
| machine_type | bodyType | direkt |
|
||
| body_type | equipment | direkt |
|
||
| location | sellerLocation | PLZ + Ort |
|
||
| documents (Fotos) | images | Base64 oder URL |
|
||
| description | description | direkt, multi-language |
|
||
| availability | availabilityStatus | mapping |
|
||
|
||
### Sync-Status-Flow
|
||
|
||
```
|
||
Entwurf → (push successful) → Gelistet → (price change + push) → Aktualisiert
|
||
↓
|
||
(delisting) → Entfernt
|
||
Entwurf → (push failed) → Fehler (error_log gespeichert)
|
||
```
|
||
|
||
---
|
||
|
||
## 10. i18n-Konzept
|
||
|
||
### Frontend (next-intl)
|
||
- **Routing:** `/de/...` und `/en/...` (Next.js App Router mit `[locale]`)
|
||
- **Translation Files:** `src/messages/de.json`, `src/messages/en.json` (250+ Keys)
|
||
- **Datumsformat:** `de` → DD.MM.YYYY, `en` → MM/DD/YYYY (via `next-intl` Formatters)
|
||
- **Zahlenformat:** `de` → 1.234,56 €, `en` → 1,234.56 €
|
||
- **Sprache pro User:** In `users.language` gespeichert, Frontend liest bei Login
|
||
|
||
### Backend
|
||
- **Fehlermeldungen:** `Accept-Language` Header → deutsche oder englische Fehlermeldungen
|
||
- **Implementierung:** Simple Dictionary in `app/exceptions.py` (kein gettext-Komplex für MVP)
|
||
- **Stammdaten:** `master_data.value_de` und `value_en` Spalten
|
||
- **Vertragsvorlagen:** `contract_templates.content_de` und `content_en`
|
||
|
||
---
|
||
|
||
## 11. Test-Strategie
|
||
|
||
### Backend (pytest)
|
||
- **Framework:** pytest + pytest-asyncio + httpx (AsyncClient)
|
||
- **Coverage-Target:** ≥80%
|
||
- **Test-DB:** Separate PostgreSQL test database (nicht SQLite – PG-spezifische Features)
|
||
- **Fixtures:** `conftest.py` mit async DB session, test client, seed data
|
||
|
||
```python
|
||
# Test-Struktur
|
||
tests/
|
||
├── conftest.py # Fixtures: async_db, client, auth_headers, seed_data
|
||
├── test_auth.py # Login, refresh, logout, RBAC
|
||
├── test_vehicles.py # CRUD, filter, validation, soft-delete
|
||
├── test_contacts.py # CRUD, search, ust-id status
|
||
├── test_sales.py # CRUD, contract, invoice, GwG, DATEV
|
||
├── test_documents.py # Upload, preview, delete, size limit
|
||
├── test_mobile_de.py # Push, batch, delisting, field mapping
|
||
├── test_ocr.py # ZB I, ZB II, merge (mocked OpenRouter)
|
||
├── test_copilot.py # Text, voice, actions (mocked OpenRouter)
|
||
├── test_image_retouch.py # Background, reflections, batch (mocked OpenRouter)
|
||
└── test_datev.py # Export, format, date range
|
||
```
|
||
|
||
### Frontend (Vitest + Playwright)
|
||
- **Unit/Component:** Vitest + React Testing Library
|
||
- **E2E:** Playwright (Kernprozesse: Fahrzeug anlegen, Verkauf starten, KI-Befehl)
|
||
- **Coverage-Target:** ≥80%
|
||
|
||
### OpenRouter Mocking
|
||
- **Tests mocken OpenRouter API** (keine realen API-Calls in CI)
|
||
- **Mock-Responses:** Vordefinierte JSON-Responses für OCR-Felder, Copilot-Actions, Bild-URLs
|
||
- **Integration Tests:** Manuell mit echtem API-Key (nicht in CI)
|
||
|
||
---
|
||
|
||
## 12. Deployment-Architektur
|
||
|
||
### Docker Compose Struktur
|
||
|
||
```yaml
|
||
# docker-compose.yml
|
||
version: '3.8'
|
||
|
||
services:
|
||
frontend:
|
||
build:
|
||
context: ./frontend
|
||
dockerfile: Dockerfile
|
||
ports:
|
||
- "3000:3000"
|
||
environment:
|
||
- NEXT_PUBLIC_API_URL=http://backend:8000/api/v1
|
||
- NEXTAUTH_SECRET=${NEXTAUTH_SECRET}
|
||
depends_on:
|
||
- backend
|
||
networks:
|
||
- erp-net
|
||
|
||
backend:
|
||
build:
|
||
context: ./backend
|
||
dockerfile: Dockerfile
|
||
ports:
|
||
- "8000:8000"
|
||
environment:
|
||
- DATABASE_URL=postgresql+asyncpg://erp_user:${DB_PASSWORD}@postgres:5432/erp_db
|
||
- REDIS_URL=redis://redis:6379/0
|
||
- JWT_SECRET=${JWT_SECRET}
|
||
- JWT_ALGORITHM=HS256
|
||
- JWT_ACCESS_TTL_MINUTES=15
|
||
- JWT_REFRESH_TTL_DAYS=7
|
||
- ENCRYPTION_KEY=${ENCRYPTION_KEY}
|
||
- OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
|
||
- MOBILE_DE_API_KEY=${MOBILE_DE_API_KEY}
|
||
- MOBILE_DE_SELLER_ID=${MOBILE_DE_SELLER_ID}
|
||
- UPLOAD_DIR=/data/uploads
|
||
- MAX_FILE_SIZE_MB=50
|
||
- CORS_ORIGINS=https://erp.domain.tld
|
||
volumes:
|
||
- erp-uploads:/data/uploads
|
||
depends_on:
|
||
- postgres
|
||
- redis
|
||
networks:
|
||
- erp-net
|
||
|
||
postgres:
|
||
image: postgres:16-alpine
|
||
ports:
|
||
- "5432:5432"
|
||
environment:
|
||
- POSTGRES_DB=erp_db
|
||
- POSTGRES_USER=erp_user
|
||
- POSTGRES_PASSWORD=${DB_PASSWORD}
|
||
volumes:
|
||
- erp-pgdata:/var/lib/postgresql/data
|
||
networks:
|
||
- erp-net
|
||
|
||
redis:
|
||
image: redis:7-alpine
|
||
ports:
|
||
- "6379:6379"
|
||
volumes:
|
||
- erp-redis:/data
|
||
networks:
|
||
- erp-net
|
||
|
||
volumes:
|
||
erp-pgdata:
|
||
erp-uploads:
|
||
erp-redis:
|
||
|
||
networks:
|
||
erp-net:
|
||
driver: bridge
|
||
```
|
||
|
||
### Coolify-Konfiguration
|
||
|
||
1. **Project:** ERP Nutzfahrzeuge
|
||
2. **Service Type:** Docker Compose (Coolify parse docker-compose.yml)
|
||
3. **Domain:** `erp.domain.tld` (via Coolify Traefik)
|
||
4. **SSL:** Let's Encrypt (automatic via Coolify)
|
||
5. **Environment Variables** (in Coolify Dashboard, NIE in Code):
|
||
- `DB_PASSWORD` – PostgreSQL password
|
||
- `JWT_SECRET` – JWT signing secret (min 32 chars)
|
||
- `ENCRYPTION_KEY` – AES-256 key for ID data encryption (32 bytes hex)
|
||
- `OPENROUTER_API_KEY` – OpenRouter API key
|
||
- `MOBILE_DE_API_KEY` – mobile.de Seller API key
|
||
- `MOBILE_DE_SELLER_ID` – mobile.de seller ID
|
||
- `NEXTAUTH_SECRET` – Next.js auth secret
|
||
- `CORS_ORIGINS` – Allowed CORS origins
|
||
6. **Health Checks:**
|
||
- Backend: `GET /api/v1/health` → 200
|
||
- Frontend: `GET /` → 200
|
||
- PostgreSQL: `pg_isready`
|
||
- Redis: `redis-cli ping`
|
||
|
||
### Backup-Strategie
|
||
|
||
1. **PostgreSQL:** Täglicher `pg_dump` → `/data/backups/erp_db_YYYY-MM-DD.sql.gz` (Coolify Cron Job)
|
||
2. **Uploads (Volume):** Wöchentliches Volume-Backup (Coolify Backup Feature)
|
||
3. **Retention:** 30 Tage für DB-Backups, 4 Wochen für Volume-Backups
|
||
4. **Restore-Test:** Monatlicher Restore-Test in Dev-Environment
|
||
|
||
### CI/CD Pipeline
|
||
|
||
```
|
||
Forgejo Actions:
|
||
1. Push to main → trigger pipeline
|
||
2. Backend: pip install → pytest → ruff → build Docker image → push to Forgejo registry
|
||
3. Frontend: npm install → vitest → eslint → build → build Docker image → push to Forgejo registry
|
||
4. Coolify: Webhook trigger → pull new images → docker-compose up -d
|
||
```
|
||
|
||
---
|
||
|
||
## 13. Architecture Decision Records (ADRs)
|
||
|
||
### ADR-001: FastAPI + Next.js + PostgreSQL
|
||
**Status:** Accepted
|
||
**Context:** ERP-System für ~10 Nutzer, Python-Ökosystem für KI/OCR, React-Frontend, relationale DB.
|
||
**Decision:** FastAPI (async, OpenAPI auto-docs) + Next.js 14 (SSR, App Router) + PostgreSQL 16 (JSONB, robust).
|
||
**Alternatives:** Django + React (heavier), Flask + Vue (less async), Node.js full-stack (weniger KI-Ökosystem).
|
||
**Rationale:** Python für KI/OpenRouter nativ, FastAPI async für I/O-heavy KI-Calls, Next.js für SSR + SEO + i18n, PostgreSQL für relationale Integrität + JSONB für flexible Felder.
|
||
|
||
### ADR-002: JWT + Refresh Token (Redis)
|
||
**Status:** Accepted
|
||
**Context:** ~10 Nutzer, keine externe Auth nötig, Statelessness gewünscht.
|
||
**Decision:** JWT (15min) + Refresh Token (7d, stored in Redis). Token Rotation bei Refresh.
|
||
**Alternatives:** Session-based (DB lookup per request), OAuth2 mit externem Provider.
|
||
**Rationale:** JWT = stateless + schnell für kleine Nutzerzahl. Redis für Refresh Token Invalidierung bei Logout. Kein Overhead für 10 Nutzer.
|
||
|
||
### ADR-003: Local Filesystem statt S3
|
||
**Status:** Accepted
|
||
**Context:** Self-hosted auf Coolify, kein S3-Budget, ~50MB max pro Datei, ~hunderte Dateien.
|
||
**Decision:** Lokales Filesystem mit Docker Volume, abstrahiert via StorageBackend Interface.
|
||
**Alternatives:** MinIO (S3-kompatibel, extra Container), direktes S3 (Cloud-Abhängigkeit).
|
||
**Rationale:** MVP-Einfachheit, Coolify Volume ist persistent. Interface erlaubt später S3-Wechsel ohne Code-Änderung. Bei Wachstum: MinIO als Sidecar.
|
||
|
||
### ADR-004: OpenRouter als einziger KI-Provider
|
||
**Status:** Accepted
|
||
**Context:** KI für OCR (Qwen2.5-VL), Copilot (Claude/GPT-4), Bildretusche (Flux.1-Pro). Kein Vendor-Lock-in gewünscht.
|
||
**Decision:** Alle KI-Calls über OpenRouter API. Modellwechsel durch Config, nicht Code.
|
||
**Alternatives:** Direkte API-Calls an Anthropic/OpenAI/Qwen (Multiple Clients), Ollama lokal (keine Vision-Modelle ausreichend). ️
|
||
**Rationale:** Single integration point, flexible Modell-Auswahl, Auto-Routing Option. DSGVO: Cloud-Verarbeitung vom User akzeptiert.
|
||
|
||
### ADR-005: Soft-Delete für Vehicles und Contacts
|
||
**Status:** Accepted ️
|
||
**Context:** Fahrzeuge/Kontakte können verkauft/archiviert werden, aber historische Verträge referenzieren sie.
|
||
**Decision:** `deleted_at` Timestamp für Soft-Delete. Queries filtern standardmäßig `WHERE deleted_at IS NULL`. ️
|
||
**Alternatives:** Hard-Delete mit referential integrity (bricht historische Verträge), separate Archiv-Tabelle. ️
|
||
**Rationale:** DSGVO-Löschkonzept möglich (hard-delete nach Aufbewahrungsfrist), aber Referenz-Integrität für Verträge erhalten.
|
||
|
||
### ADR-006: WeasyPrint für PDF-Generierung
|
||
**Status:** Accepted ️
|
||
**Context:** Kaufverträge, Rechnungen, Lieferbescheinigungen als PDF generieren. HTML-Templates mit Variablen. ️
|
||
**Decision:** WeasyPrint (HTML → PDF) mit Jinja2 Templates. ️
|
||
**Alternatives:** ReportLab (programmatic, weniger flexibel), Puppeteer (extra Chrome-Container), pdfkit (wkhtmltopdf, veraltet). ️
|
||
**Rationale:** WeasyPrint = pure Python, HTML/CSS Templates (wie Vertragsvorlagen), gut für strukturierte Dokumente. Keine externen Dependencies.
|
||
|
||
### ADR-007: Push-Only mobile.de (keine Bidirektionalität)
|
||
**Status:** Accepted ️
|
||
**Context:** User will Fahrzeuge auf mobile.de listen, aber keine Daten von dort zurück importieren. ️
|
||
**Decision:** ERP → mobile.de Push via Seller API. Keine Pull/Import-Logik. ️
|
||
**Alternatives:** Bidirektionale Sync (komplex, Konfliktlösung nötig). ️
|
||
**Rationale:** Explizites Non-Goal in Requirements. Reduziert Komplexität massiv. ERP bleibt Single Source of Truth.
|
||
|
||
### ADR-008: AES-256-GCM für Ausweisdaten
|
||
**Status:** Accepted ️
|
||
**Context:** GwG erfordert Erfassung von Ausweisdaten. DSGVO-konforme Speicherung nötig. ️
|
||
**Decision:** AES-256-GCM Verschlüsselung für `identification_data.id_number_encrypted`. Key aus `ENCRYPTION_KEY` env var. Entschlüsselung nur in Service-Layer mit RBAC-Check (Admin + Buchhaltung). ️
|
||
**Alternatives:** PostgreSQL pgcrypto (weniger flexibel), Hashing (nicht brauchbar – Daten müssen lesbar sein). ️
|
||
**Rationale:** Application-Level Verschlüsselung = volle Kontrolle, Key nicht in DB, RBAC vor Entschlüsselung. GCM-Mode = Authenticated Encryption.
|
||
|
||
---
|
||
|
||
## 14. Non-Functional Requirements
|
||
|
||
| Kategorie | Anforderung | Implementierung |
|
||
|---|---|---|
|
||
| **Performance** | API-Response < 500ms (ohne KI-Calls) | PostgreSQL Indexes, async I/O, pagination |
|
||
| **Performance** | KI-Calls: < 30s Timeout | httpx timeout=30s, async background für Batch |
|
||
| **Security** | DSGVO-konform | Audit-Log, Soft-Delete, AES-256, RBAC |
|
||
| **Security** | GwG-konform | Warnung >10.000€ Bar, Identifikation, Meldedokument |
|
||
| **Availability** | ~10 Nutzer, keine HA nötig | Single Instance, Coolify Restart bei Crash |
|
||
| **Scalability** | Nicht relevant für MVP | Horizontal scaling möglich via Docker, aber nicht nötig |
|
||
| **Maintainability** | ≥80% Test-Coverage | pytest + Vitest, CI/CD pipeline |
|
||
| **i18n** | DE + EN von Anfang an | next-intl + Backend dictionary |
|
||
| **Accessibility** | WCAG 2.1 AA Basics | Semantic HTML, ARIA-Labels, Keyboard-Nav, Kontrast |
|
||
|
||
---
|
||
|
||
## 15. Risiken
|
||
|
||
| Risiko | Wahrscheinlichkeit | Impact | Mitigation |
|
||
|---|---|---|---|
|
||
| OpenRouter API-Ausfall | Mittel | Hoch (KI-Features nicht verfügbar) | Graceful degradation, manuelle Eingabe als Fallback |
|
||
| mobile.de API-Änderung | Niedrig | Mittel | Service-Layer isoliert Mapping, einfach anpassbar |
|
||
| OpenRouter Kosten explosion | Mittel | Mittel | Token-Tracking in ai_interactions, Monats-Limit konfigurierbar |
|
||
| PDF-Generierung Performance | Niedrig | Niedrig | WeasyPrint ist sync, aber nur bei Bedarf (nicht realtime) |
|
||
| DSGVO-Audit | Niedrig | Hoch | Audit-Log vollständig, Verschlüsselung implementiert, keine Ausweisdaten an KI |
|
||
| Datenverlust (PostgreSQL) | Niedrig | Kritisch | Tägliche pg_dump Backups, Volume-Backups |
|
||
|
||
---
|
||
|
||
## 16. Open Questions
|
||
|
||
1. **Domain:** Genauer Domain-Name für ERP (via Coolify konfigurierbar) – *später*
|
||
2. **BZSt eVatR API:** Zugang beschaffen für automatische USt-IdNr.-Prüfung – *post-MVP*
|
||
3. **DATEV-Format:** Exaktes CSV-Format mit Steuerberater abklären – *während M5 Implementierung*
|
||
4. **Vertragsvorlagen:** Konkrete Vorlagen-Texte vom User – *während M5 Implementierung*
|
||
5. **mobile.de API-Dokumentation:** Aktuelle Seller API Spec beschaffen – *während M1 Implementierung*
|
||
|
||
---
|
||
|
||
## 17. Handoff
|
||
|
||
- **Architecture Status:** Complete – alle Module, Tabellen, Endpoints, ADRs dokumentiert
|
||
- **Ready for Task Breakdown:** YES
|
||
- **Ready for Implementation:** Pending task_graph.json approval
|