feat: initial commit

2026-03-05 22:12:38 +01:00
commit bce762a783
380 changed files with 51955 additions and 0 deletions
@@ -0,0 +1,174 @@
+# 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
+
+```bash
+# 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
+
+```bash
+# 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]`