HartOMat/CLAUDE.md

Schaeffler Automat

Ziel

Automatisiertes Render-System für Schaeffler-Produktbilder. Kunden (intern) laden Excel-Auftragslisten hoch, das System extrahiert Produktdaten, verknüpft STEP-CAD-Dateien, rendert Thumbnails und Animationen über Blender (Cycles/EEVEE) oder Flamenco, und liefert fertige PNG/MP4-Ausgaben.

Tech Stack

• Backend: Python 3.11, FastAPI (async), SQLAlchemy 2 (async), Alembic, Celery, Pydantic v2
• Frontend: React 18, TypeScript, Vite, Tailwind CSS, lucide-react
• Datenbank: PostgreSQL 16
• Queue/Cache: Redis 7 (Celery Broker + Backend)
• Renderer: Blender 5.0.1 (headless), cadquery (STEP→STL), Three.js (Playwright)
• Render Farm: Flamenco 3.8 (Manager + Worker, für Animationen)
• Deployment: Docker Compose (11 Services)

Services (docker-compose.yml)

Service	Port	Funktion
postgres	5432	Primärdatenbank
redis	6379	Celery Broker
backend	8888	FastAPI App (uvicorn)
worker	–	Celery Worker, Queue: step_processing, concurrency=8
worker-thumbnail	–	Celery Worker, Queue: thumbnail_rendering, concurrency=1
beat	–	Celery Beat (Scheduler)
blender-renderer	8100	Blender HTTP-Service (STEP→PNG, STEP→STL)
threejs-renderer	8101	Three.js/Playwright HTTP-Service
flamenco-manager	8080	Flamenco Job Manager
flamenco-worker	–	Flamenco Render Worker (GPU)
frontend	5173	React/Vite Dev Server

Starten / Stoppen

# Alle Services starten
docker compose up -d

# Logs einzelner Services
docker compose logs -f backend
docker compose logs -f worker
docker compose logs -f worker-thumbnail
docker compose logs -f blender-renderer

# Neubauen nach Codeänderungen (Backend/Worker)
docker compose up -d --build backend worker worker-thumbnail

# Frontend-Änderungen: Hot-Reload aktiv, kein Rebuild nötig

Standard-Zugangsdaten (Entwicklung)

• Admin: admin@schaeffler.com / Admin1234!
• Backend API: http://localhost:8888/docs
• Frontend: http://localhost:5173
• Flamenco Manager: http://localhost:8080

Projektstruktur

schaefflerautomat/
├── backend/
│   ├── app/
│   │   ├── api/routers/     # FastAPI Router (admin, cad, orders, products, ...)
│   │   ├── models/          # SQLAlchemy ORM-Modelle (14 Modelle)
│   │   ├── schemas/         # Pydantic In/Out-Schemas
│   │   ├── services/        # Business-Logik (excel_parser, step_processor, ...)
│   │   ├── tasks/           # Celery Tasks (step_tasks.py, flamenco_tasks.py)
│   │   └── utils/           # Auth, Seeding
│   ├── alembic/versions/    # DB-Migrationen (001–026+)
│   └── start.sh             # Entrypoint: migrate → seed → uvicorn
├── frontend/src/
│   ├── api/                 # API-Client-Funktionen (axios-basiert)
│   ├── components/          # Wiederverwendbare UI-Komponenten
│   └── pages/               # Seitenkomponenten
├── blender-renderer/        # Blender HTTP-Microservice (Python Flask)
├── threejs-renderer/        # Three.js/Playwright Microservice (Python Flask)
├── flamenco/                # Flamenco Dockerfile + Job-Type-Scripts (.js)
└── docker-compose.yml

Coding-Standards

• Sprache im Code: Englisch (Variablen, Kommentare, Commits)
• Commits: Conventional Commits (feat:, fix:, refactor:, docs:)
• Python: async/await durchgehend im Backend, sync-Wrapper für Celery-Tasks
• TypeScript: Interfaces für alle API-Responses in frontend/src/api/*.ts
• Keine Tests: Aktuell kein automatisiertes Test-Suite vorhanden

Datenbank-Migrationen

# Neue Migration erstellen
docker compose exec backend alembic revision --autogenerate -m "beschreibung"

# Migrationen anwenden
docker compose exec backend alembic upgrade head

# Status prüfen
docker compose exec backend alembic current

Celery Task-Queues

Queue	Worker	Concurrency	Tasks
step_processing	worker	8	process_step_file, render_order_line_task, dispatch_order_line_render
thumbnail_rendering	worker-thumbnail	1	render_step_thumbnail, regenerate_thumbnail, generate_stl_cache
ai_validation	worker	8	Azure AI Validierung

Wichtig: thumbnail_rendering läuft mit concurrency=1, weil der blender-renderer nur 1 Request gleichzeitig verarbeiten kann. Mehr parallele Requests führen zu Timeouts.

STEP-Processing-Pipeline

1. Upload: STEP-Datei hochladen → CadFile-Record erstellt → process_step_file Task eingereiht
2. Metadata (process_step_file auf step_processing):
   • STEP-Objekte extrahieren (cadquery, ~0.1s)
   • parsed_objects in DB speichern
   • glTF konvertieren (falls konfiguriert)
   • Status: processing → queut render_step_thumbnail
3. Thumbnail (render_step_thumbnail auf thumbnail_rendering):
   • Blender oder Three.js renderer aufrufen
   • STL-Cache erstellen: {step_stem}_low.stl, {step_stem}_high.stl
   • Status: completed oder failed
   • Materialien auto-populated

STL-Cache-Konvention

STL-Dateien liegen neben der STEP-Datei:

uploads/{cad_file_id}/filename_low.stl
uploads/{cad_file_id}/filename_high.stl

Beim nächsten Render-Aufruf wird der Cache genutzt (keine Neu-Konvertierung).

Material-Alias-System

• Materialien werden per STEP-Part-Name auf Schaeffler-Bibliotheksmaterialien (SCHAEFFLER_...) gemappt
• Lookup-Reihenfolge: Alias-Tabelle zuerst, dann exakter Material.name-Match, dann Pass-through
• Alias-Seeding: Admin → "Seed Aliases" oder via POST /api/materials/seed-aliases
• Neue Aliases direkt in DB oder über Material-Detail-UI hinzufügen

Rollen

Rolle	Berechtigungen
admin	Vollzugriff, Admin-Panel, alle Einstellungen
project_manager	Aufträge, Analytics, Render-Trigger, STL-Download
client	Eigene Aufträge anlegen und einsehen

Wichtige API-Endpoints

• POST /api/uploads/excel — Excel-Auftragsliste importieren
• POST /api/orders/{id}/submit — Auftrag einreichen
• POST /api/orders/{id}/dispatch-renders — Alle Render-Zeilen dispatchen
• GET /api/cad/{id}/thumbnail — Thumbnail (kein Auth, UUID opaque)
• POST /api/cad/{id}/generate-stl/{quality} — STL-Generierung manuell triggern
• POST /api/admin/settings/regenerate-thumbnails — Alle Thumbnails neu rendern
• POST /api/admin/settings/process-unprocessed — Unverarbeitete STEP-Dateien queuen
• POST /api/admin/settings/generate-missing-stls — Fehlende STL-Caches erstellen
• GET /api/worker/activity — Letzte 30 STEP-Verarbeitungen (Status, Timing)

Bekannte Eigenheiten

• Backend-Port 8888 (nicht 8000 — war belegt)
• Tailwind CSS-Variablen: bg-surface etc. funktionieren nicht mit / opacity-Syntax wenn CSS-Variable einen Hex-Wert enthält. Stattdessen style={{ backgroundColor: 'var(--color-bg-surface)' }} verwenden.
• Blender mm→m: STEP-Dateien sind in mm, Blender intern in m. Alle Import-Scripts skalieren mit 0.001.
• Flamenco GPU: deploy.resources.reservations.devices in docker-compose für NVIDIA-Support.
• settings_persistence: Admin-Einstellungen werden via direktem SQL-UPDATE gespeichert (nicht ORM-Mutation), da SQLAlchemy bei key-value-Stores keine Mutation trackt.

Learnings-Pflicht

Nach jedem gelösten Problem oder jeder wichtigen Entscheidung: → Trag das Learning in LEARNINGS.md ein (Format: Datum | Kategorie | Problem → Lösung) → Commitiere LEARNINGS.md zusammen mit dem Fix: docs: learning erfasst - [kurzbeschreibung]