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

14 KiB
Raw Blame History

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:

# 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)

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

# 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

Reference in New Issue View Git Blame Copy Permalink