erp-nutzfahrzeuge/.a0/runtime_report.md

Runtime Report — ERP Nutzfahrzeuge

Date: 2026-07-17 Phase: 5 — Runtime Verification Runtime: /opt/venv/bin/python (execution environment)

---

Summary

Check	Status
Backend startup	✅ PASS
Health endpoint	✅ PASS (200, {"status":"ok"})
Root endpoint	✅ PASS (200, app metadata)
Auth login (GET)	✅ PASS (405 Method Not Allowed — POST-only)
OpenAPI/Swagger	✅ PASS (200, full schema)
Frontend build artifacts	✅ PASS (.next/ with BUILD_ID, server/, static/)
Runtime errors	✅ NONE (clean logs, no tracebacks)
PostgreSQL	✅ Running (localhost:5432, accepting connections)
Redis	⚠️ NOT installed (JWT-based refresh tokens, no Redis storage needed)

Overall verdict: Backend starts and runs cleanly. All public endpoints respond as expected. No runtime errors detected.

---

1. Startup Verification

Start command:

cd backend && /opt/venv/bin/python -m uvicorn app.main:app --host 0.0.0.0 --port 8000

Result: Server started successfully (PID 3383733).

Startup log:

INFO:     Started server process [3383733]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

Import check: from app.main import app — OK (no ImportError)

Core dependencies verified:

• uvicorn ✅
• fastapi ✅
• sqlalchemy ✅
• asyncpg ✅

---

2. Health Check

Endpoint: GET http://localhost:8000/api/v1/health

Response:

• HTTP Status: 200 OK
• Body: {"status":"ok"}

Verdict: ✅ Health endpoint reachable and returning expected payload.

---

3. Endpoint Verification

3.1 Root Endpoint

• URL: GET http://localhost:8000/
• HTTP Status: 200 OK
• Body: {"name":"ERP Nutzfahrzeuge","version":"1.0.0","docs":"/docs"}

3.2 Auth Login (GET — should fail)

• URL: GET http://localhost:8000/api/v1/auth/login
• HTTP Status: 405 Method Not Allowed
• Body: {"detail":"Method Not Allowed"}
• Expected behavior: Login is POST-only; GET correctly rejected.

3.3 OpenAPI Schema

• URL: GET http://localhost:8000/openapi.json
• HTTP Status: 200 OK
• Schema version: OpenAPI 3.1.0
• Title: ERP Nutzfahrzeuge Backend API
• Version: 1.0.0

---

4. Available API Endpoints (from OpenAPI)

Auth (/api/v1/auth)

Method	Path	Description	Auth
POST	/api/v1/auth/login	Login with email+password → JWT tokens	No
POST	/api/v1/auth/refresh	Exchange refresh token for new token pair	No
GET	/api/v1/auth/me	Get current user profile	Bearer

Users (/api/v1/users)

Method	Path	Description	Auth
GET	/api/v1/users/	List users (paginated, admin only)	Bearer
POST	/api/v1/users/	Create user (admin only)	Bearer
PUT	/api/v1/users/{user_id}	Update user (admin only)	Bearer
DELETE	/api/v1/users/{user_id}	Soft-delete user (admin only)	Bearer

Vehicles (/api/v1/vehicles)

Method	Path	Description	Auth
GET	/api/v1/vehicles/	List vehicles (filter, sort, paginate)	Bearer
POST	/api/v1/vehicles/	Create vehicle	Bearer
GET	/api/v1/vehicles/{vehicle_id}	Get single vehicle	Bearer
PUT	/api/v1/vehicles/{vehicle_id}	Update vehicle	Bearer
DELETE	/api/v1/vehicles/{vehicle_id}	Soft-delete vehicle	Bearer
POST	/api/v1/vehicles/{vehicle_id}/mobile-de/push	Push to mobile.de (async, 202)	Bearer
GET	/api/v1/vehicles/{vehicle_id}/mobile-de/status	Get mobile.de sync status	Bearer

Contacts (/api/v1/contacts)

Method	Path	Description	Auth
GET	/api/v1/contacts/	List contacts (filter, sort, paginate)	Bearer
POST	/api/v1/contacts/	Create contact (admin/verkaeufer)	Bearer
GET	/api/v1/contacts/{contact_id}	Get contact with persons	Bearer
PUT	/api/v1/contacts/{contact_id}	Update contact	Bearer
DELETE	/api/v1/contacts/{contact_id}	Soft-delete contact	Bearer
POST	/api/v1/contacts/{contact_id}/persons	Add contact person	Bearer
DELETE	/api/v1/contacts/{contact_id}/persons/{person_id}	Remove contact person	Bearer

Files (/api/v1/vehicles/{vehicle_id}/files)

Method	Path	Description	Auth
GET	/api/v1/vehicles/{vehicle_id}/files	List files for vehicle	Bearer
POST	/api/v1/vehicles/{vehicle_id}/files	Upload file (multipart, max 20MB)	Bearer
GET	/api/v1/vehicles/{vehicle_id}/files/{file_id}	Download file	Bearer
DELETE	/api/v1/vehicles/{vehicle_id}/files/{file_id}	Delete file	Bearer

OCR (/api/v1/ocr)

Method	Path	Description	Auth
POST	/api/v1/ocr/upload	Upload scan for OCR (async, 202)	Bearer
GET	/api/v1/ocr/results/{result_id}	Get OCR result	Bearer
GET	/api/v1/ocr/results	List OCR results	Bearer
POST	/api/v1/ocr/results/{result_id}/apply	Apply OCR data to vehicle	Bearer

Sales (/api/v1/sales)

Method	Path	Description	Auth
GET	/api/v1/sales/	List sales (filter by status/date)	Bearer
POST	/api/v1/sales/	Create sale (sets vehicle to 'sold')	Bearer
GET	/api/v1/sales/{sale_id}	Get sale with nested data	Bearer
PUT	/api/v1/sales/{sale_id}	Update sale	Bearer
DELETE	/api/v1/sales/{sale_id}	Cancel sale (soft delete)	Bearer
POST	/api/v1/sales/{sale_id}/contract	Regenerate contract PDF	Bearer
GET	/api/v1/sales/{sale_id}/contract	Download contract PDF	Bearer
POST	/api/v1/sales/{sale_id}/verify-ust-id	Verify USt-IdNr. via BZSt API	Bearer

DATEV (/api/v1/datev)

Method	Path	Description	Auth
POST	/api/v1/datev/export	Create DATEV export (CSV)	Bearer
GET	/api/v1/datev/exports	List DATEV exports	Bearer
GET	/api/v1/datev/exports/{export_id}/download	Download DATEV CSV	Bearer

Copilot (/api/v1/copilot)

Method	Path	Description	Auth
POST	/api/v1/copilot/chat	Send message to AI Copilot	Bearer
POST	/api/v1/copilot/action	Execute confirmed action	Bearer
GET	/api/v1/copilot/history	Get chat history	Bearer
POST	/api/v1/copilot/voice	Voice input (base64 audio)	Bearer

Retouch (/api/v1/retouch)

Method	Path	Description	Auth
POST	/api/v1/retouch/process	Upload image for retouching (async, 202)	Bearer
GET	/api/v1/retouch/results/{result_id}	Get retouch result	Bearer
POST	/api/v1/retouch/price-compare	Compare prices for vehicle	Bearer

Health

Method	Path	Description	Auth
GET	/api/v1/health	Health check	No
GET	/	Root info	No

---

5. Frontend Build Verification

Location: frontend/.next/

Build artifacts confirmed:

• BUILD_ID — present (20 bytes)
• build-manifest.json — present
• app-build-manifest.json — present
• routes-manifest.json — present
• server/ — directory present
• static/ — directory present
• prerender-manifest.json — present
• required-server-files.json — present
• trace/ — build trace present

Verdict: ✅ Frontend build artifacts are complete and present.

---

6. Environment Verification

Required Environment Variables (from .env.example)

Variable	Required	Status	Notes
DATABASE_URL	✅ Yes	Set (local PostgreSQL)	postgresql+asyncpg://erp_test_user:***@localhost:5432/erp_test
REDIS_URL	✅ Yes	Set in .env.example	Redis NOT installed; JWT refresh tokens are stateless (no Redis storage needed)
JWT_SECRET	✅ Yes	Placeholder in .env.example	Must be set to a secure random string for production
JWT_ALGORITHM	Optional	Default HS256	—
JWT_ACCESS_TTL_MINUTES	Optional	Default 15	—
JWT_REFRESH_TTL_DAYS	Optional	Default 7	—
CORS_ORIGINS	✅ Yes	Set	http://localhost:3000,http://localhost:3001
UPLOAD_DIR	Optional	Default /tmp/uploads	Must be persistent volume in production
APP_NAME	Optional	Default ERP Nutzfahrzeuge	—
APP_ENV	Optional	Default development	Set to production for deployment
MOBILE_DE_API_KEY	Optional	Empty	Required for mobile.de integration
MOBILE_DE_SELLER_ID	Optional	Empty	Required for mobile.de integration
OPENROUTER_API_KEY	Optional	Not in .env.example	Required for AI Copilot features (currently empty/non-functional)

Infrastructure Status

Service	Status	Notes
PostgreSQL	✅ Running	localhost:5432, accepting connections
Redis	⚠️ Not installed	Not required for JWT; may be needed for async task queues (OCR, retouch, mobile.de push)
OpenRouter API	⚠️ Not configured	AI Copilot features will not work without API key

---

7. Errors Found

No errors, tracebacks, warnings, or critical messages found in runtime logs.

Log output was clean:

INFO:     Started server process [3383733]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     127.0.0.1:48688 - "GET /api/v1/health HTTP/1.1" 200 OK
INFO:     127.0.0.1:48700 - "GET / HTTP/1.1" 200 OK
INFO:     127.0.0.1:48706 - "GET /api/v1/auth/login HTTP/1.1" 405 Method Not Allowed
INFO:     127.0.0.1:48710 - "GET /openapi.json HTTP/1.1" 200 OK

---

8. Known Risks

#	Risk	Severity	Mitigation
1	Redis not installed — async task processing (OCR, retouch, mobile.de push) may fail or fall back to synchronous processing	Medium	Install Redis or verify async tasks have graceful fallback. Check if background tasks use in-memory queues.
2	OPENROUTER_API_KEY not set — AI Copilot (/api/v1/copilot/*) will not function	Medium	Set OPENROUTER_API_KEY in production environment for Copilot features.
3	JWT_SECRET is placeholder — change-me-to-a-secure-random-string in .env.example	High	Generate a cryptographically secure secret (≥256 bits) for production.
4	PostgreSQL is local only — no connection pooling or HA configured	Medium	Configure PgBouncer or use managed PostgreSQL (e.g., Coolify managed DB) for production.
5	UPLOAD_DIR = /tmp/uploads — ephemeral storage, files lost on container restart	High	Mount a persistent volume for UPLOAD_DIR in production.
6	CORS_ORIGINS — currently allows localhost:3000,3001 only	Low	Add production frontend origin to CORS_ORIGINS for deployment.
7	MOBILE_DE_API_KEY empty — mobile.de push/status endpoints will fail	Low	Set API key when mobile.de integration is needed.
8	No HTTPS/TLS — backend runs on plain HTTP	Medium	Use reverse proxy (nginx/Traefik) or Coolify proxy for TLS termination.
9	No rate limiting — no rate limiting middleware detected	Medium	Add rate limiting (e.g., slowapi) before public exposure.

---

9. Recommendations

Immediate (before deployment)

1. Generate a secure JWT_SECRET and configure in production environment
2. Set APP_ENV=production for deployment
3. Configure persistent volume for UPLOAD_DIR
4. Add production frontend origin to CORS_ORIGINS
5. Install Redis if async task processing (OCR, retouch, mobile.de) is required
6. Set OPENROUTER_API_KEY if AI Copilot features are needed

Deployment preparation

7. Create Dockerfile / docker-compose.yml for containerized deployment
8. Configure reverse proxy with TLS termination (Coolify proxy or nginx)
9. Set up PostgreSQL as managed service or with backup strategy
10. Add health check to Coolify resource configuration (GET /api/v1/health)
11. Configure log rotation and monitoring

Post-deployment

12. Run smoke tests against production endpoints
13. Verify JWT auth flow end-to-end
14. Test file upload with persistent volume
15. Monitor for async task failures (OCR, retouch)

---

10. Sign-off

Item	Status
App starts without errors	✅ Yes
Health endpoint returns 200	✅ Yes
Bounded error output shows no critical runtime failure	✅ Yes (zero errors)
Frontend build artifacts present	✅ Yes
Deployment docs ready	✅ Yes (see deploy/ directory)
Ready for deployment	⚠️ Conditional — requires secure JWT_SECRET, persistent storage, and Redis decision

Runtime verification: PASSED Deployment readiness: CONDITIONAL (env vars + infrastructure must be configured)