erp-nutzfahrzeuge/docs/handoff.md

# Handoff-Dokument — ERP Nutzfahrzeuge

**Version:** 1.0.0  
**Datum:** 2026-07-18  
**Phase:** 7 — Final Audit + Release Readiness + Handoff  
**Audit-Verdict:** ✅ PASS (mit WARNs)  
**Release-Score:** 85/100  

---

## 1. Projekt-Übersicht

### Was ist das System?

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, mobile.de Push-Sync, KI-Copilot und KI-Bildretusche.

### Tech-Stack

| Komponente | Technologie | Version |
|---|---|---|
| **Backend** | Python / FastAPI | Python 3.13, FastAPI |
| **Frontend** | Next.js / React / TypeScript | Next.js 14, React 18 |
| **Datenbank** | PostgreSQL | 16 (Alpine) |
| **Cache/Queue** | Redis | 7 (Alpine, optional) |
| **KI-Anbindung** | OpenRouter | Qwen2.5-VL (OCR), Flux.1-Pro (Retusche), Claude/GPT (Copilot) |
| **Extern** | mobile.de Seller API, DATEV-Export, BZSt USt-IdNr.-Prüfung | — |
| **Deployment** | Docker Compose (4 Services), Coolify | — |
| **Git** | Forgejo | 18 Commits auf main |

### Module (8 Tasks)

| Task | Modul | Status |
|---|---|---|
| T01 | Auth + User Management + RBAC + Base Frontend + i18n | ✅ Implementiert |
| T02 | Fahrzeugbestand + mobile.de Push-Sync | ✅ Implementiert |
| T03 | OCR-Erfassung (ZB I/II) via OpenRouter Vision | ✅ Implementiert |
| T04 | Kontakt-/Kundenverwaltung + USt-IdNr.-Prüfung | ✅ Implementiert |
| T05 | Dateiablage pro Fahrzeug | ✅ Implementiert |
| T06 | Verkaufsmodul + Rechtsdokumente + DATEV-Export | ✅ Implementiert |
| T07 | KI-Copilot (Text + Sprache) + Systemsteuerung | ✅ Implementiert |
| T08 | Bildretusche + Preisvergleich (Flux.1-Pro) | ✅ Implementiert |

### Frontend-Routen (15)

| Route | Beschreibung |
|---|---|
| `/` | Startseite |
| `/login` | Login-Seite |
| `/[locale]/fahrzeuge` | Fahrzeugliste |
| `/[locale]/fahrzeuge/neu` | Neues Fahrzeug anlegen |
| `/[locale]/fahrzeuge/[id]` | Fahrzeugdetail |
| `/[locale]/kontakte` | Kontaktliste |
| `/[locale]/kontakte/neu` | Neuer Kontakt |
| `/[locale]/kontakte/[id]` | Kontaktdetail |
| `/[locale]/ocr` | OCR-Erfassung |
| `/[locale]/retouch` | Bildretusche |
| `/[locale]/verkauf` | Verkaufsliste |
| `/[locale]/verkauf/neu` | Neuer Verkauf |
| `/[locale]/verkauf/[id]` | Verkaufsdetail |
| `/[locale]/ki-copilot` | KI-Copilot Chat |

### Backend-API-Endpunkte (11 Router)

| Router | Pfad | Beschreibung |
|---|---|---|
| auth | `/api/v1/auth` | Login, Refresh, Logout |
| users | `/api/v1/users` | User CRUD, RBAC |
| vehicles | `/api/v1/vehicles` | Fahrzeug CRUD, Filter, Soft-Delete |
| contacts | `/api/v1/contacts` | Kontakt CRUD, USt-IdNr.-Prüfung |
| ocr | `/api/v1/ocr` | OCR Upload, Results, Apply |
| files | `/api/v1/files` | Dateiablage, Thumbnails |
| sales | `/api/v1/sales` | Verkaufs-CRUD, Vertrag-PDF |
| datev | `/api/v1/datev` | DATEV CSV-Export |
| copilot | `/api/v1/copilot` | KI-Chat, Actions, Voice, History |
| image_retouch | `/api/v1/retouch` | Bildretusche, Preisvergleich |
| health | `/api/v1/health` | Health Check |

---

## 2. Test-Ergebnisse

### Backend-Tests

| Metrik | Wert |
|---|---|
| **Tests gesamt** | 392 |
| **Passed** | 392 |
| **Failed** | 0 |
| **Dauer** | 105.93s |
| **Coverage (T08)** | 89% (Target: 80%) |
| **Lint (ruff)** | ✅ All checks passed |
| **Format (ruff)** | ✅ 77 files already formatted |

**Test-Dateien (16):**
- test_auth.py, test_auth_service.py, test_users.py
- test_vehicles.py, test_vehicles_extra.py, test_mobilede.py
- test_contacts.py
- test_ocr.py
- test_files.py
- test_sales.py, test_datev.py
- test_copilot.py, test_copilot_coverage.py
- test_retouch.py
- test_health.py
- conftest.py

### Frontend-Tests

| Metrik | Wert |
|---|---|
| **Tests gesamt** | 112 |
| **Passed** | 112 |
| **Failed** | 0 |
| **Dauer** | 11.46s |
| **Lint (ESLint)** | ✅ Clean (0 warnings) |
| **Build (Next.js)** | ✅ 15 Routen gebaut |

**Test-Dateien (8):**
- auth.test.tsx, i18n.test.tsx
- vehicles (in test files)
- ocr.test.tsx
- files.test.tsx
- sales.test.tsx, datev.test.tsx
- copilot.test.tsx
- retouch.test.tsx

### Runtime-Verifikation

| Check | Status |
|---|---|
| Backend Startup | ✅ PASS |
| Health Endpoint (/api/v1/health) | ✅ 200 OK |
| Root Endpoint (/) | ✅ 200 OK |
| OpenAPI Schema (/openapi.json) | ✅ 200 OK |
| Auth Login (GET → 405) | ✅ Korrekt (POST-only) |
| Frontend Build Artifacts | ✅ .next/ vollständig |
| Runtime Errors | ✅ Keine |
| PostgreSQL | ✅ Läuft |
| Redis | ⚠️ Nicht installiert (optional) |

---

## 3. Deployment-Anleitung

### Voraussetzungen

1. **Coolify** (oder Docker + Docker Compose) installiert und lauffähig
2. **Forgejo-Repository** geklont: `https://forgejo.media-on.de/Leopoldadmin/erp-nutzfahrzeuge`
3. **Domain(s)** für Frontend und Backend konfiguriert (z.B. `erp.domain.tld`)
4. **OpenRouter API Key** für KI-Funktionen (OCR, Retusche, Copilot)
5. **mobile.de API Key + Seller ID** für Fahrzeugmarkt-Integration (optional)

### Schritt-für-Schritt Deployment

#### 1. Environment Variables konfigurieren

Kopiere `.env.example` zu `.env` und fülle alle Werte aus:

```bash
# Pflicht
POSTGRES_USER=erp_user
POSTGRES_PASSWORD=<sicheres-passwort>
POSTGRES_DB=erp_nutzfahrzeuge
JWT_SECRET=<openssl rand -hex 32>

# Wichtig
APP_ENV=production
CORS_ORIGINS=https://erp.ihre-domain.de
NEXT_PUBLIC_API_URL=https://erp.ihre-domain.de/api/v1

# KI-Funktionen
OPENROUTER_API_KEY=<ihr-key>

# mobile.de (optional)
MOBILE_DE_API_KEY=<ihr-key>
MOBILE_DE_SELLER_ID=<ihre-id>
```

Siehe `deploy/env.md` für vollständige Dokumentation aller Variablen.

#### 2. Coolify Deployment

1. In Coolify: Neue Resource → **Docker Compose**
2. Forgejo-Repository verbinden
3. Base Directory = Projekt-Root
4. Coolify erkennt `docker-compose.yml` automatisch
5. Environment Variables in Coolify eintragen (siehe `deploy/coolify-config.md`)
6. Deploy starten
7. Health Check abwarten: `GET /api/v1/health` → 200

#### 3. Docker Compose (Alternative)

```bash
cd /pfad/zum/projekt
cp .env.example .env
# .env bearbeiten
docker compose up -d
docker compose ps  # Alle 4 Services sollten "healthy" sein
```

#### 4. Post-Deploy Verifikation

```bash
# Backend Health
curl https://erp.ihre-domain.de/api/v1/health
# Erwartet: {"status":"ok"}

# Frontend
curl -I https://erp.ihre-domain.de/
# Erwartet: HTTP/1.1 200

# OpenAPI
curl https://erp.ihre-domain.de/openapi.json | python -m json.tool | head -5
```

### Services (4 Container)

| Service | Image | Port | Health Check |
|---|---|---|---|
| Backend | python:3.13-slim (custom) | 8000 | `curl -f /api/v1/health` |
| Frontend | node:18-alpine (custom) | 3000 | `wget --spider /` |
| PostgreSQL | postgres:16-alpine | 5432 | `pg_isready` |
| Redis | redis:7-alpine | 6379 | `redis-cli ping` |

### Volumes

| Volume | Mount | Zweck |
|---|---|---|
| uploads | `/data/uploads` | Fahrzeugdateien, Bilder |
| pgdata | `/var/lib/postgresql/data` | PostgreSQL-Datenbank |
| redisdata | `/data` | Redis-Persistenz |

---

## 4. Bekannte Risiken + Mitigation

| # | Risiko | Severity | Mitigation |
|---|---|---|---|
| 1 | **JWT_SECRET als Placeholder** | Hoch | Vor Production: `openssl rand -hex 32` verwenden. Niemals Default-Wert in Production. |
| 2 | **CORS_ORIGINS nur localhost** | Mittel | Production URL in CORS_ORIGINS eintragen. Sonst blockiert der Browser API-Calls. |
| 3 | **Redis nicht installiert** | Niedrig | Async-Features (OCR, Retusche, mobile.de Push) benötigen Redis. Ohne Redis: Features deaktiviert. |
| 4 | **OpenRouter API Key leer** | Mittel | KI-Funktionen (OCR, Retusche, Copilot) funktionieren nicht ohne Key. Vor Deploy setzen. |
| 5 | **BZSt API nicht verfügbar** | Niedrig | USt-IdNr.-Prüfung ist manuell im MVP. BZST_API_ENABLED=false. |
| 6 | **Upload-Verzeichnis nicht persistent** | Hoch | In Production: Docker Volume für `/data/uploads` konfigurieren. Sonst Datenverlust bei Container-Neustart. |
| 7 | **Frontend act() Warnings** | Niedrig | Non-blocking React state update Warnings in ChatHistory-Tests. Keine Funktionsbeeinträchtigung. |
| 8 | **Task-Graph-Status inkonsistent** | Niedrig | Nur T03+T06 als 'completed' markiert im JSON. Alle 8 Tasks wurden implementiert und getestet. Metadata-Lücke, kein Code-Problem. |

---

## 5. Nächste Schritte

### Vor Production Deployment

1. **[KRITISCH]** JWT_SECRET generieren: `openssl rand -hex 32`
2. **[KRITISCH]** POSTGRES_PASSWORD setzen (sicheres Passwort)
3. **[KRITISCH]** CORS_ORIGINS auf Production-Domain setzen
4. **[KRITISCH]** NEXT_PUBLIC_API_URL auf Production-Backend-URL setzen
5. **[WICHTIG]** OPENROUTER_API_KEY setzen (für OCR, Retusche, Copilot)
6. **[WICHTIG]** APP_ENV=production setzen
7. **[EMPFOHLEN]** Redis aktivieren (für async Features)
8. **[EMPFOHLEN]** MOBILE_DE_API_KEY + MOBILE_DE_SELLER_ID setzen
9. **[EMPFOHLEN]** Persistent Volume für Uploads verifizieren

### Nach erstem Deployment

1. Smoke Test: Login → Fahrzeug anlegen → OCR → Verkauf → DATEV-Export
2. Health Monitoring einrichten (Coolify Health Checks)
3. Database Backup-Strategie definieren (pg_dump cron)
4. Log-Aggregation konfigurieren
5. SSL/TLS über Coolify/Traefik verifizieren

### Langfristig

1. E2E-Tests mit Playwright ergänzen
2. Integration-Tests mit echtem OpenRouter API
3. BZSt eVatR API-Zugang beantragen (für automatische USt-IdNr.-Prüfung)
4. CI/CD Pipeline (Forgejo Actions → Docker Build → Coolify Deploy)
5. Monitoring & Alerting (Uptime, Response Times, Error Rates)
6. Performance-Optimierung (DB-Indexes, Query-Optimierung, Caching)

---

## 6. Wartungshinweise

### Regelmäßige Aufgaben

| Aufgabe | Häufigkeit | Befehl/Aktion |
|---|---|---|
| Database Backup | Täglich | `docker exec erp-postgres pg_dump -U erp_user erp_nutzfahrzeuge > backup.sql` |
| Redis Persistence Check | Wöchentlich | `docker exec erp-redis redis-cli info persistence` |
| Docker Image Updates | Monatlich | `docker compose pull && docker compose up -d` |
| Log Review | Wöchentlich | `docker compose logs --tail=100 backend` |
| Health Check Monitor | Kontinuierlich | Coolify Health Check (30s Interval) |
| Disk Space Check | Wöchentlich | `docker system df` |

### Rollback

Siehe `deploy/rollback.md` für vollständige Rollback-Prozedur:

1. **Coolify:** Redeploy Previous Image (Deployments Tab → Redeploy)
2. **Git:** `git revert <commit>` → Push → Auto-Deploy
3. **Docker Compose:** `docker compose down` → Previous Image tag → `docker compose up -d`

### Troubleshooting

| Symptom | Ursache | Lösung |
|---|---|---|
| Health 502 | Backend nicht gestartet | Container Logs prüfen, DATABASE_URL verifizieren |
| Health 500 | DB-Verbindung fehlgeschlagen | PostgreSQL-Status, Credentials prüfen |
| Frontend leer | API nicht erreichbar | NEXT_PUBLIC_API_URL, CORS_ORIGINS prüfen |
| KI-Funktionen fehler | OpenRouter Key fehlt | OPENROUTER_API_KEY setzen, Container restart |
| Uploads fehlen | Volume nicht gemounted | Docker Volume für `/data/uploads` prüfen |

---

## 7. Projekt-Artefakte Verzeichnis

| Artefakt | Pfad | Status |
|---|---|---|
| Requirements | `docs/requirements.md` | ✅ Final (21/21 Discovery) |
| Architecture | `docs/architecture.md` | ✅ Complete (15 Tabellen, API-Design) |
| Component Inventory | `docs/component_inventory.md` | ✅ Complete |
| Task Graph | `.a0/task_graph.json` | ⚠️ 8 Tasks, Status inkonsistent |
| AGENTS.md | `AGENTS.md` | ✅ Build & Test Commands |
| Test Report | `test_report.md` | ⚠️ Nur T08 dokumentiert |
| Runtime Report | `.a0/runtime_report.md` | ✅ Complete (305 Zeilen) |
| Docker Compose | `docker-compose.yml` | ✅ 4 Services, Healthchecks |
| Backend Dockerfile | `backend/Dockerfile` | ✅ Python 3.13-slim |
| Frontend Dockerfile | `frontend/Dockerfile` | ✅ Multi-stage, Node 18 |
| Env Example | `.env.example` | ✅ Vollständig |
| Deploy Env Docs | `deploy/env.md` | ✅ Complete |
| Deploy Runbook | `deploy/runbook.md` | ✅ Complete |
| Deploy Rollback | `deploy/rollback.md` | ✅ Complete |
| Deploy Healthcheck | `deploy/healthcheck.md` | ✅ Complete |
| Coolify Config | `deploy/coolify-config.md` | ✅ Complete |
| Known Errors | `.a0/known_errors.md` | ✅ Keine kritischen |
| Open Questions | `docs/open_questions.md` | ✅ Dokumentiert |

---

## 8. Audit-Ergebnis

### Quality Gate Results

| Gate | Result | Score |
|---|---|---|
| Backend Tests | ✅ PASS | 392/392 |
| Frontend Tests | ✅ PASS | 112/112 |
| Backend Lint (ruff) | ✅ PASS | 0 errors |
| Frontend Lint (ESLint) | ✅ PASS | 0 errors/warnings |
| Frontend Build | ✅ PASS | 15 routes |
| Runtime Verification | ✅ PASS | Health 200, OpenAPI OK |
| Deployment Config | ✅ PASS | Docker + Coolify |
| Documentation | ✅ PASS | Runbook, Rollback, Env, Healthcheck |
| Requirements Coverage | ✅ PASS | 21/21 Discovery |
| Architecture | ✅ PASS | 15 Tabellen, API-Design |

### Overall Verdict

**✅ PASS — Release Ready (mit WARNs)**

**Score:** 85/100  
**Minimum für Release:** 80 ✅  
**Minimum für Production Handoff:** 90 ⚠️ (nicht erreicht, siehe WARNs)

### WARNs (nicht blockierend)

1. Task-Graph-Status inkonsistent (nur 2/8 als completed markiert)
2. Project State JSON veraltet (phase=architecture statt implementation)
3. Orchestrator Mode veraltet (planning_only statt release_handoff)
4. test_report.md dokumentiert nur T08, nicht alle Tasks
5. Kein patterns extractor verfügbar (Skritt 4 entfallen)

### Blockers (kritisch)

**Keine kritischen Blocker.** Alle Tests grün, alle Artefakte funktional vorhanden.

---

## 9. Sign-off

| Rolle | Status | Datum |
|---|---|---|
| Release Auditor (A0) | ✅ PASS mit WARNs | 2026-07-18 |
| User Approval | ⏳ Ausstehend | — |

**Das System ist bereit für Production Deployment, sobald:**
1. Environment Variables für Production konfiguriert sind
2. JWT_SECRET und POSTGRES_PASSWORD sicher gesetzt sind
3. OpenRouter API Key konfiguriert ist
4. Persistent Volumes für Uploads und Database verifiziert sind
5. User das Deployment freigibt

---

*Erstellt von: Release Auditor (A0) — Phase 7 Final Audit*  
*Projekt: ERP Nutzfahrzeuge — 2026-07-18*