# Projekt-Learnings — HartOMat

## Format
**Datum | Kategorie | Problem → Lösung**

---

## Learnings

### 2026-03-15 | Architecture | Per-order-line render overrides via JSONB
Render overrides (JSONB) on OrderLine allow overriding any output type render setting (format, resolution, samples, engine, etc.) at order time without duplicating output types. Applied AFTER output type render_settings AND after transparent_bg/cycles_device_val assignment, so they take final priority. Also affects dispatch queue routing (width/height overrides change light vs heavy queue routing).

### 2026-03-14 | Blender | OBJ-Rotation Turntable: Reparenting von USD-Parts verschiebt Geometrie
USD-importierte Parts haben existierende Eltern-Objekte (Xform-Nodes). `part.parent = pivot; part.matrix_parent_inverse = pivot.matrix_world.inverted()` verliert den Beitrag des alten Parents zur Welt-Position → Parts verschieben sich ~14m. Fix: World-Matrix vor Reparenting sichern, dann via `part.matrix_local = pivot.inverted() @ saved_world` wiederherstellen. Zusätzlich `bpy.context.view_layer.update()` vor dem Parenting aufrufen, damit `pivot.matrix_world` aktuell ist.

### 2026-03-13 | Blender/USD | USD-Import erzeugt leere Material-Stubs → schwarze Renders
Blender's `bpy.ops.wm.usd_import()` erstellt leere Material-Stubs (use_nodes=True, nodes=0) aus USD MaterialBinding-Referenzen. Wenn `apply_material_library_direct` dann die echten Materialien aus der .blend-Bibliothek laden will, findet es die Stubs bereits in `bpy.data.materials` und nutzt sie direkt — ohne die echten Shader-Node-Trees zu laden. Leere Materialien rendern in Cycles als pures Schwarz (RGB max=1). Fix: `_find_material_with_nodes()` Hilfsfunktion, die `.NNN`-Suffix-Kollisionen auflöst und nur Materialien mit echten Nodes zurückgibt.

### 2026-03-12 | Caching | Composite Cache Keys für Tessellierung
Hash-basiertes Caching in Celery Tasks muss alle relevanten Parameter einschließen, nicht nur den Datei-Hash. Bei `generate_gltf_geometry_task` und `generate_usd_master_task` wurde der Cache-Key auf `{hash}:{linear}:{angular}:{engine}` erweitert. Außerdem: immer Disk-Existenz des gecachten Assets prüfen (`storage_key.exists()`) bevor ein Cache-Hit zurückgegeben wird — der Asset-Record kann existieren, die Datei aber nicht.

### 2026-03-12 | React | Modal in <tr> braucht createPortal
Ein Modal-Dialog, der aus einer `<tr>`-Tabellenzeile gerendert wird, erzeugt invalides HTML (`<div>` in `<tr>` nicht erlaubt). Fix: `createPortal(modal, document.body)` — rendert das Modal am Body-Root, außerhalb der Tabellen-Hierarchie.

### 2026-03-12 | Prozess | ROADMAP war dem Code weit hinterher
Pre-flight code audit vor dem Schreiben eines Plans ist zwingend erforderlich. Beim Sprint vom 2026-03-12 zeigte sich: P1 (dead-code cleanup, blender_render.py split), P5 (USD render wiring), P8 (Celery tenant context) und P10 (UI polish) waren bereits größtenteils im Code implementiert, aber nicht im ROADMAP.md reflektiert. Lesson: Immer zuerst grep/ls-Gates und Line-Count-Checks laufen lassen, bevor Tasks geplant werden.

### 2026-03-12 | Material | SQLAlchemy Mapper-Fehler bei isoliertem Domain-Import
Wenn eine Celery-Task nur `from app.domains.orders.models import Order` importiert (ohne `app.models`), kann SQLAlchemy die String-Referenzen `relationship("Template", ...)` und `relationship("User", ...)` nicht auflösen — alle Mapper-Initialisierungen schlagen fehl. Fix: `import app.models as _all_models` am Modul-Level von `beat_tasks.py` eintragen. So werden alle Models geladen bevor irgendeine Task-Funktion die Mapper initialisiert. Gilt für alle Tasks die Domain-Models direkt importieren.

### 2026-03-12 | Material | OCC-Part-Namen vs. USD-Part-Keys beim Material-Matching
OCC XCAF-Namen enthalten Bindestriche und _AF\d+-Suffixe (z.B. `GE360-HF-0011-EIN_HAELFTE_AF0_1_AF0`). Das USD-Export-Tool slugifiziert den Namen: `[^a-z0-9]+` → `_` (d.h. `ge360_hf_0011_ein_haelfte_af0_1_af0`). Blender importiert das USD-Objekt als `ge360_hf_0011_ein_haelfte` (base-name aus XCAF). Das Mat-Map aus der DB ist lowercased mit Bindestrichen. Fix: In `build_mat_map_lower()` auch eine slug-normierte Variante jeden Keys hinzufügen (`re.sub(r'[^a-z0-9]+', '_', kl).strip('_')`). Der bestehende Prefix-Fallback (`key.startswith(part_key)`) fangt dann den Rest ab.

### 2026-03-12 | USD | Stale USD-Master-Assets invalidieren
USD-Assets die vor dem `elif shape_has_loc`-Fix (Commit `de7f97b`, 2026-03-12 16:43) generiert wurden, haben fehlerhafte Geometrie (double-transform). Fix: `DELETE FROM media_assets WHERE asset_type='usd_master' AND created_at < '2026-03-12 16:43:33'` + `UPDATE cad_files SET step_file_hash = NULL WHERE id IN (...)`. Nächster Render generiert neue korrekte USD-Datei.

### 2026-03-12 | USD | Mesh-Prim-Benennung für Blender 5.0
Blender 5.0 importiert USD und kollabiert single-child Xform+Mesh-Hierarchien zu einem einzigen Objekt. Der Objektname entspricht dabei dem Leaf-Namen des Mesh-Prims (nicht dem Xform). Die Lösung: `mesh_path = f"{part_path}/{part_key}"` statt `f"{part_path}/Mesh"`. Damit importiert Blender jedes Objekt direkt mit dem korrekten part_key als Namen — kein Post-Import-Rename nötig. Blender setzt `obj["usd:path"]` nicht, daher ist der pfadbasierte Rename-Ansatz nicht funktionsfähig.

### 2026-01-15 | Architektur | Backend-Port-Konflikt
Port 8000 war belegt → Port 8888 in `docker-compose.yml` + Vite-Proxy. Früh festlegen und in CLAUDE.md dokumentieren.

### 2026-01-20 | Datenbank | SQLAlchemy trackt key-value-Store-Mutations nicht
Admin-Settings via ORM gespeichert → Änderungen nicht persistiert. SQLAlchemy erkennt keine Mutation an geladenen Value-Feldern.
**Lösung:** Direktes `session.execute(update(...))` statt ORM-Mutation. Key-Value-Stores immer mit direktem SQL verwalten.

### 2026-01-25 | Render-Pipeline | Blender ignoriert STEP-Einheiten (mm vs. m)
STEP in mm, Blender in m → 50mm-Lager erscheint 50m breit. `_scale_mm_to_m(parts)` in allen 3 Render-Scripts: `part.scale = (0.001, 0.001, 0.001)` + Transform anwenden, direkt nach STL-Import vor Kamera-Kalkulation.

### 2026-01-28 | Render-Pipeline | Blender 5.0 hat `scene.node_tree` entfernt
`_setup_bg_compositor()` → Python-Exception → Blender exit code 0 → Task fälschlicherweise "completed".
**Lösung:** Compositing entfernt; bg_color via FFmpeg (`-f lavfi -i color=...` + overlay). Pflicht: `try: main() except SystemExit: raise except Exception: traceback; sys.exit(1)` in allen Blender-Scripts.

### 2026-02-05 | Material-System | Material-Alias-Lookup-Reihenfolge falsch
`Steel--Stahl` war sowohl `Material.name` als auch Alias für `HARTOMAT_010101_Steel-Bare`. Lookup fand zuerst den Namen → Blender konnte ihn nicht in der Library finden.
**Lösung:** `material_service.py`: **Aliases zuerst**, dann exakter Name, dann Pass-through.

### 2026-02-10 | Render-Pipeline | Blender-Template überschreibt HDRI/World
Im Template-Modus (Mode B) lief Auto-Licht/World-Setup bedingungslos → überschrieb HDRI aus .blend-Template.
**Lösung:** In Template-Mode Lights, World und Color-Management-Override vollständig überspringen; nur Kamera ggf. neu berechnen.

### 2026-02-15 | Celery | Blender-Queue-Flooding durch falsche Concurrency
Alle Tasks auf `step_processing` (concurrency=8) → 8 Workers gleichzeitig an blender-renderer (max 1) → 7× Timeout.
**Lösung:** `process_step_file` (step_processing, concurrency=8) nur schnelle Metadata; `render_step_thumbnail` (asset_pipeline, concurrency=1) für Blender. HTTP-Services mit max 1 Request immer auf eigener Queue mit concurrency=1.

### 2026-02-18 | Frontend | Tailwind CSS-Variablen inkompatibel mit opacity-Syntax
`bg-surface/50` erzeugt `rgb(var(--color-bg-surface) / 0.5)` — invalides CSS wenn Variable ein Hex-Wert ist.
**Lösung:** `style={{ backgroundColor: 'var(--color-bg-surface)' }}`. Alternativ: CSS-Vars im RGB-Channel-Format definieren (`255 255 255`).

### 2026-02-20 | STL-Cache | Three.js-Renderer nutzte tempfile → kein Download
Three.js schrieb STL in tempfile und löschte es → Download-Endpoint fand nichts.
**Lösung:** Persistent cache: `step_path.parent / f"{step_path.stem}_low.stl"`, Cache-Hit-Check vor Konvertierung, kein `unlink()`. Konvention `{stem}_{quality}.stl` neben STEP-Datei von Anfang an in allen Renderern.

### 2026-02-20 | STL-Cache | blender-renderer fehlte /convert-stl Endpoint
Blender renderte + konvertierte in einem Schritt, persistierte STL nicht.
**Lösung:** Neuer `/convert-stl` Endpoint (STEP→STL ohne Render), Celery-Task `generate_stl_cache` auf `asset_pipeline`, Admin-Batch-Funktion "Generate Missing STLs".

### 2026-02-22 | Material-System | Fehlender Alias blockiert Material-Replacement
`"Stahl v2"` in DB nicht in materials noch in material_aliases → keine Ersetzung, Silent-Fail.
**Lösung:** Alias direkt in DB eintragen. Bei Render ohne Materialersetzung immer zuerst `resolve_material_map()` debuggen, Alias-Tabelle prüfen.

### 2026-02-25 | Frontend | canDispatch-Bedingung zu restriktiv
`canDispatch` enthielt `&& hasRetryable` → Button fehlte wenn alle Zeilen initial "pending".
**Lösung:** `hasRetryable` entfernt; Validierung im Backend. Aktions-Buttons nicht zu stark von abgeleiteten Zuständen abhängig machen.

### 2026-02-28 | Frontend | MaterialInput-Dropdown ohne Hintergrund
`bg-surface` mit CSS-Hex-Variable → transparenter Dropdown (siehe 2026-02-18).
**Lösung:** `style={{ backgroundColor: 'var(--color-bg-surface)' }}` für Dropdown-Container, Group-Header, Sticky-Button. Datei: `frontend/src/components/shared/MaterialInput.tsx`.

### 2026-03-06 | Refactor | .gitignore `core` trifft Verzeichnisse
`core` in `.gitignore` ignorierte `backend/app/core/` Verzeichnis.
**Lösung:** `/core` (root-relativ) — trifft nur Datei im Root, nicht verschachtelte Verzeichnisse.

### 2026-03-06 | Architektur | Blender-HTTP-Service vs. direkter Subprocess
Flask-HTTP-Microservice = Single-Point-of-Failure, kein Scaling, HTTP-Overhead.
**Lösung:** Celery render-worker Container — Blender direkt via `subprocess.run`. `is_blender_available()` prüft `BLENDER_BIN` env var; Backend-Container fallen auf Pillow zurück. Subprocess > HTTP für blocking compute tasks.

### 2026-03-06 | Refactor | Bash CWD-Problem durch Hook-Pfad-Auflösung
Nach `cd frontend` im Bash-Tool blieb CWD in `frontend/` → Hook-Pfad nicht gefunden → alle Tool-Calls blockiert.
**Lösung:** Symlink `frontend/.claude → .claude`. Hooks mit absoluten Pfaden konfigurieren; `cd` nur mit `&&` am Ende der Command-Chain.

### 2026-03-06 | Multi-Tenancy | PostgreSQL RLS mit current_setting und Null-Safety
`current_setting('app.current_tenant_id')` wirft Exception wenn nicht gesetzt.
**Lösung:** `current_setting('app.current_tenant_id', true)` — zweites Argument macht Funktion Null-safe. Admin-Bypass: separate Policy mit `SET LOCAL app.current_tenant_id = 'bypass'`.

### 2026-03-11 | Tessellation | GMSH CharacteristicLength ≠ OCC linear_deflection
OCC `linear_deflection` ist ein **Oberflächenabweichungs-Toleranzwert** (max. Abstand Mesh→echte Fläche). GMSH `CharacteristicLengthMax` ist eine **Kantenlängenvorgabe**. Gleicher Wert (0.1) erzeugt bei GMSH 50× mehr Dreiecke → 231MB statt 3MB.
**Lösung:** `CharacteristicLengthMax = linear_deflection * 15.0` (15× Faktor). `MinimumCirclePoints = min(20, ceil(2π/angular_deflection))` — ohne Cap liefert `angular_deflection=0.1rad` → 63 Punkte/Kreis (10× zu dicht). Mit Cap 20: ~20MB statt 231MB, OCC-ähnliche Dichte bei 0 Fan-Dreiecken.

### 2026-03-11 | Tessellation | BRep_Builder.UpdateFace — richtige Signatur
OCP Python API: `BRep_Builder.UpdateFace(face, triangulation)` — 2-Argumente-Form, NICHT `(face, tri, loc, tolerance)` wie in C++-Doku. Falsche Signatur führt zu Silent-Exception, alle Faces fallen auf BRepMesh zurück.

### 2026-03-11 | Tessellation | GMSH OOM bei Assembly-Compound
GMSH verarbeitet ganzen Compound auf einmal → 25-teilige Lager-Baugruppe: 2.3GB RAM → OOM-Kill (exit -9).
**Lösung:** Per-Solid-Iteration via `TopExp_Explorer(root_shape, TopAbs_SOLID)`. `BRep_Builder.UpdateFace` aktualisiert Face-Objekte in-place; Parent-Compound sieht Updates automatisch.

### 2026-03-11 | Celery | Timeout in Worker-Code ≠ Running Worker liest neue Version
`export_glb.py` mit 600s-Timeout in Container-Datei — aber Celery-Worker hatte Code beim Start geladen. Fehler zeigt `timeout=120` obwohl Datei 600 enthält.
**Lösung:** `docker compose restart render-worker` nach Datei-Update. Celery lädt Module beim Start, nicht bei Task-Ausführung.

### 2026-03-06 | Refactor | Domain-Driven Migration: Compat-Shims statt Big-Bang
Vollständige Migration in einem Schritt bricht alle Imports.
**Lösung:** Alte Dateien werden Re-Export-Shims: `from app.domains.auth.models import User; __all__ = ["User"]`. Erst nach vollständiger Import-Migration Shims entfernen.

### 2026-03-06 | Workflow-System | Celery Canvas vs. Custom Workflow-Engine
Custom Graph-Traversal-Engine = 2-3 Wochen Eigenentwicklung.
**Lösung:** Celery Canvas (`chain`, `group`, `chord`) als Execution-Engine. `dispatch_workflow(type, order_line_id, params)` baut Canvas dynamisch aus Config. Kein Backward-Compat nötig: Celery Canvas reicht für parallele/sequentielle Workflows.

### 2026-03-06 | Circular Import | template_service ↔ domains/rendering/service
Beide Module waren Shims die aufeinander zeigten → `resolve_template()` nie aufrufbar → alle Renders crashten mit ImportError.
**Lösung:** `template_service.py` aus git-History wiederhergestellt (echte Implementierung). `domains/rendering/service.py` importiert nur davon. Nach Refactoring: `grep -rn "def resolve_template"` muss ≥1 Treffer liefern.

### 2026-03-06 | Multi-Tenancy | audit_log.tenant_id NOT NULL blockiert alle Notifications
Migration 036 machte `audit_log.tenant_id NOT NULL`, aber `emit_notification` setzt kein `tenant_id` → INSERT schlägt fehl → 500 bei Order-Submit.
**Lösung:** `ALTER TABLE audit_log ALTER COLUMN tenant_id DROP NOT NULL`. Broadcast-Notifications (system-weit) dürfen NULL tenant_id haben.

### 2026-03-06 | Frontend | GET /api/tenants gibt 307 Redirect zurück
FastAPI registriert `/tenants/` (trailing slash) → `GET /tenants` → 307. Axios folgt, verliert Authorization-Header → 401.
**Lösung:** `getTenants()` auf `/tenants/` (mit trailing slash). Generell: FastAPI 307-Redirects verlieren Auth-Header in Axios. Immer trailing slash im Frontend verwenden.

### 2026-03-06 | Celery Canvas | workflow_builder: order_line_id als step_path übergeben
`render_still_task.si(order_line_id, **params)` — Task erwartet `step_path: str`. Blender versuchte UUID als Pfad → crash.
**Lösung:** Separate `render_order_line_still_task` die intern OrderLine→Product→CadFile auflöst. Workflow-Builder-Tasks dürfen nie Domain-IDs als file-path-Argumente verwenden.

### 2026-03-06 | Docker | docker compose in Container braucht multi-stage CLI-Copy
`python:3.11-slim` hat kein `docker` binary.
**Lösung:** `COPY --from=docker:cli /usr/local/bin/docker /usr/local/bin/docker` + cli-plugins. Docker-Socket mounten (`/var/run/docker.sock`), Compose-File als Volume, `COMPOSE_PROJECT_DIR` env var.

### 2026-03-06 | Docker | `COPY --from=docker-cli cli-plugins` schlägt fehl
`docker:cli` Image hat kein `/usr/local/lib/docker/cli-plugins` Verzeichnis.
**Lösung:** Nur `/usr/local/bin/docker` kopieren — neuere docker:cli Images enthalten `compose` bereits im Binary.

### 2026-03-06 | Docker | apt-Paketname libgdk-pixbuf2.0-0 vs libgdk-pixbuf-2.0-0
Auf Debian bookworm heißt das Paket `libgdk-pixbuf-2.0-0` (mit Bindestrichen). `apt-get install` mit falschem Namen → exit 100.
**Regel:** Immer `apt-cache search libgdk` im Container prüfen.

### 2026-03-06 | React Three Fiber | Wireframe-Toggle über Material-Clone
GLTF-Materialien sind shared objects — direkte Mutation von `child.material.wireframe` beeinflusst alle Instanzen.
**Lösung:** `child.material = child.material.clone()` vor Wireframe-Mutation. GLTF-Materialien bei Runtime-Modifikationen immer zuerst clonen.

### 2026-03-06 | pytest | Backend ohne dev-Dependencies
`pip install -e .` ohne `[dev]` → kein pytest → `ModuleNotFoundError`.
**Lösung:** `pip install -e ".[dev]"`. Dev-Extras immer im Dockerfile angeben wenn Tests im Container laufen sollen.

### 2026-03-06 | Celery | `@shared_task` verbindet sich mit localhost statt Redis-Container
`@shared_task` aus `celery` ohne App-Kontext → Default-Broker `localhost:6379` → `kombu.exceptions.OperationalError`.
**Lösung:** Immer `from app.tasks.celery_app import celery_app` + `@celery_app.task(...)`. `@shared_task` nur wenn Modul garantiert nach `celery_app.py` geladen wird.

### 2026-03-06 | SQLAlchemy | Relationship-Auflösung schlägt fehl wenn Models nicht importiert
Celery-Task importierte nur `AssetLibrary` → `Material.creator` → String-Ref `"User"` nicht im Mapper → `InvalidRequestError`.
**Lösung:** `import app.models  # noqa: F401` vor erstem DB-Zugriff in Celery-Tasks — `__init__.py` registriert alle 14 Modelle.

### 2026-03-06 | MinIO / Storage | `storage.upload()` erwartet `Path`, nicht `str`
`storage.upload(str_path, key)` → `AttributeError: 'str' has no attribute 'name'` → STLs lokal gespeichert aber nie in MinIO.
**Lösung:** `storage.upload(Path(stl_path), key)` — alle `upload()`-Aufrufe mit `Path()`-Cast absichern.

### 2026-03-06 | Blender / Scripts | `catalog_assets.py` Pfad in Docker falsch
`Path(__file__).parent` zeigt auf Backend-Container-Pfad, nicht auf render-worker `/render-scripts/`.
**Lösung:** `RENDER_SCRIPTS_DIR` Env-Var: `Path(os.environ.get("RENDER_SCRIPTS_DIR", "/render-scripts")) / "catalog_assets.py"`.

### 2026-03-06 | Alembic | Migration exit code 100 bei enum-Konflikt
`Enum(create_type=False)` unzuverlässig mit asyncpg.
**Lösung:** Raw SQL: `DO $$ BEGIN CREATE TYPE ...; EXCEPTION WHEN duplicate_object THEN NULL; END $$;`. Für Tabellen: `CREATE TABLE IF NOT EXISTS`.

### 2026-03-06 | Render-Pipeline | Circular Shim blockiert alle Order-Renders
`dispatch_order_line_render` → Shim A→B→A → Render startet nie.
**Lösung:** `dispatch_order_line_render` direkt auf `render_order_line_task.delay()`. Den echten Aufruf-Pfad API→Task vor Refactoring dokumentieren.

### 2026-03-06 | Render-Pipeline | render_order_line_task auf falschem Worker (kein Blender)
Task auf `step_processing` → `worker`-Container (kein Blender) → `is_blender_available()` = False → Pillow-Placeholder, kein Fehler.
**Lösung:** Queue auf `asset_pipeline` → `render-worker`-Container (Blender 5.0.1 + cadquery). Blender-Tasks IMMER auf `asset_pipeline`.

### 2026-03-06 | Docker | worker-thumbnail vs render-worker — beide auf asset_pipeline
Zwei Services unterschiedlicher Capabilities auf gleicher Queue → round-robin → 50% Silent-Fail.
**Lösung:** `worker-thumbnail` aus docker-compose entfernt. `render-worker` ist alleiniger Consumer. Nie zwei Services mit unterschiedlichen Fähigkeiten auf dieselbe Queue.

### 2026-03-06 | Multi-Tenancy | tenant_id NOT NULL verletzt bei Order-Erstellung
Migration 036 machte `tenant_id NOT NULL` auf orders/order_lines/order_items → alle Create-Endpoints übergaben das Feld nicht.
**Lösung:** `tenant_id=getattr(user, 'tenant_id', None)` in allen Model-Konstruktoren. Nach jeder RLS-Migration alle Create-Endpoints auf neue Pflichtfelder prüfen.

### 2026-03-06 | Workflow-Dispatch | dispatch_render_with_workflow als Drop-in
Legacy `dispatch_order_line_render.delay()` wurde nie durch Workflow-Engine ersetzt.
**Lösung:** `dispatch_render_with_workflow(order_line_id)` lädt `OutputType.workflow_definition_id`, nutzt Canvas wenn gesetzt, fällt sonst auf Legacy zurück.

### 2026-03-06 | OCC | `RWMesh_CoordinateSystemConverter` nicht als Python-Binding verfügbar
`writer.ChangeCoordinateSystemConverter()` → `TypeError: Unregistered type`.
**Lösung:** Shapes vor Export mit `BRepBuilderAPI_Transform(shape, trsf, True)` um Faktor 0.001 skalieren. `RWGltf_CafWriter` direkt ohne Koordinatensystem-Konverter aufrufen.

### 2026-03-06 | OCC | `XCAFDoc_ShapeTool.GetComponents` → `GetComponents_s`
In OCP alle XCAF static-Methoden mit `_s`-Suffix. Gilt für alle `XCAFDoc_*`-Klassen.

### 2026-03-06 | Pipeline | OCC-native STEP→GLB ersetzt STL-Intermediary
STL verliert Materialien/Farben, doppelter Aufwand, Dateiflut.
**Lösung:** `RWGltf_CafWriter` + `STEPCAFControl_Reader`: STEP→GLB direkt. `BRepMesh_IncrementalMesh` tesselliert vor Export. OCP (cadquery's Bindings, NICHT `OCC.Core`), statische Methoden mit `_s`-Suffix.

### 2026-03-06 | Celery | generate_gltf_geometry_task als Subprocess
OCP + bpy können nicht im selben Python-Prozess koexistieren (native C++ Konflikt).
**Lösung:** `export_step_to_gltf.py` via `subprocess.run([sys.executable, script, ...], timeout=120)` — OCC läuft isoliert.

### 2026-03-06 | OCC | Dihedralwinkel für sharp-edge Extraktion aus STEP
`topexp.MapShapesAndAncestors(shape, TopAbs_EDGE, TopAbs_FACE, map)` → Face-Paare pro Edge. `BRepAdaptor_Surface.DN()` für Normalen. Medianwinkel → `suggested_smooth_angle`, Midpunkte → `sharp_edge_midpoints` für KD-Tree in Blender. Nur im render-worker verfügbar.

### 2026-03-06 | Blender | UV-Seams aus sharp edges ableiten
Nach `edges_select_sharp(sharpness=radians(angle))` → `mark_sharp()` → `mark_seam(clear=False)`. Optional: bmesh KD-Tree für OCC-Midpoints (Toleranz 0.5mm vor scale(0.001)).

### 2026-03-06 | Multi-Tenancy | audit_log.tenant_id NOT NULL — Broadcast-Events
`emit_notification` setzt kein `tenant_id` → INSERT fehlschlägt → 500 bei Order-Submit.
**Lösung:** `tenant_id DROP NOT NULL`. Broadcast-Notifications (kein konkreter Tenant) brauchen nullable tenant_id.

### 2026-03-06 | Bbox | GLB statt STL für Bounding-Box Extraktion
`_bbox_from_stl()` obsolet nach Pipeline-Umbau.
**Lösung:** `_bbox_from_glb()` mit trimesh: `scene.bounds * 1000` für mm. Fallback auf `_bbox_from_step_cadquery()`.

### 2026-03-06 | Workflow | Turntable-Workflow brauchte step_path zur Laufzeit
`WorkflowDefinition.config` ist statisch → kein `step_path` → `ValueError`.
**Lösung:** `dispatch_render_with_workflow()` löst `step_path` + `output_dir` aus `OrderLine→Product→CadFile` auf und injiziert sie vor Dispatch. Statische (engine, samples) von laufzeit-abhängigen (Pfade, IDs) trennen.

### 2026-03-06 | Blender | Asset Library link=True — Assets müssen markiert sein
`bpy.data.libraries.load(blend_path, link=True, assets_only=True)` liefert nur via "Mark as Asset" markierte Datenblöcke.
**Lösung:** In .blend: jedes Material/Node-Group via "Mark as Asset" markieren. `catalog_assets.py` filtert via `m.asset_data is not None`.

### 2026-03-06 | Celery Inspect | active_queues() zum Worker-Capability-Check
`celery_app.control.inspect().active_queues()` zeigt pro Worker welche Queues er konsumiert. Besser als Worker-Namen-Heuristiken für `render_worker_connected`/`blender_available`-Detection.

### 2026-03-06 | TypeScript | Test-Dateien aus Haupt-tsconfig ausschließen
`vitest`/`msw`-Imports in `src/__tests__/` → TypeScript-Fehler in `tsc --noEmit` (Types nur im Test-Kontext).
**Lösung:** `"exclude": ["src/__tests__"]` in `tsconfig.json`. Vitest prüft eigene Typen intern.

### 2026-03-06 | ffmpeg | Turntable hängt ohne `shortest=1`
`lavfi color`-Stream hat unendliche Dauer → ffmpeg wartet nach PNG-Sequenz-Ende unbegrenzt.
**Lösung:** `overlay=0:0:shortest=1`. Bei ffmpeg-Overlays mit lavfi/nullsrc als Input IMMER `shortest=1`.

### 2026-03-06 | Architektur | WebSocket Auth via Query-Parameter (JWT)
Browser-WebSocket-API kann keine `Authorization`-Header senden.
**Lösung:** JWT als Query-Parameter: `ws://host/api/ws?token=<jwt>`. Token ist in Logs sichtbar — für v3: kurzlebigen WS-Token (TTL 30s) generieren.

### 2026-03-07 | Security | Media-Endpoints ohne Auth
`list_assets`, `download_asset`, `zip_download` ohne `get_current_user`-Dep → unauthentifizierte Requests. RLS schützt nur DB, nicht HTTP.
**Lösung:** `_user: User = Depends(get_current_user)` zu allen drei. Jeder neue Endpoint braucht expliziten Auth-Dep — RLS ist Defense-in-Depth, kein Ersatz.

### 2026-03-07 | MediaAsset | `is_animation` Flag entscheidet Asset-Type — falsches Design
`is_animation == True` setzte `asset_type = turntable` auch für `.jpg` Poster-Frames → Broken-Video-Icons.
**Lösung:** Extension entscheidet: `.mp4`/`.webm` → `turntable`, alles andere → `still`. MIME-Typ/Extension immer als primäre Typ-Quelle.

### 2026-03-07 | OCC | Bounding-Box aus STEP mit `Bnd_Box` + `brepbndlib.Add()`
```python
bbox = Bnd_Box(); brepbndlib.Add(shape, bbox)
xmin,ymin,zmin,xmax,ymax,zmax = bbox.Get()
```
Werte in mm (STEP-Einheit). In `mesh_attributes` JSONB speichern — kein neues DB-Feld nötig.

### 2026-03-07 | Storage | `storage_key` absolute Pfade brachen Volume-Moves
Absolute Pfade in `storage_key` → nach Volume-Umzug 398 Assets nicht erreichbar.
**Lösung:** `_normalize_key()` strippt `UPLOAD_DIR`-Prefix. Legacy-Remapping als Fallback. Neue Assets immer relativ: `renders/{uuid}/{filename}`.

### 2026-03-07 | SQLAlchemy Async | db.refresh() lädt keine Relationships
`await db.refresh(invoice)` lädt nur skalare Spalten → `invoice.lines` → lazy-load außerhalb Greenlet → `MissingGreenlet`, HTTP 500.
**Lösung:** Nach `db.commit()` separate select-Query mit `selectinload` statt `db.refresh()`.

### 2026-03-07 | Frontend Auth | Bearer-Token bei direktem Link-Download fehlt
`<a href="/api/billing/invoices/{id}/pdf">` sendet keinen Authorization-Header → 401.
**Lösung:** `api.get(..., { responseType: 'blob' })` → `URL.createObjectURL()` + programmatischer `<a>.click()`. Gilt für alle geschützten Download-Endpoints.

### 2026-03-07 | PostgreSQL RLS | SET LOCAL muss in jeder Transaktion gesetzt werden
`GRANT BYPASSRLS TO hartomat` schlug still fehl → Admin-Endpoints bekamen 0 Zeilen.
**Lösung:** `await db.execute(text("SET LOCAL app.current_tenant_id = 'bypass'"))` direkt vor jede RLS-geschützte Query in internen/Admin-Endpoints.

### 2026-03-07 | trimesh | GLB-Export-Scale: STL in mm → Three.js in Metern
`mesh.apply_scale(0.001)` nach `trimesh.load()` vor Export. Bei `trimesh.Scene` über `scene.geometry.values()` iterieren. Optional: `trimesh.smoothing.filter_laplacian(mesh, lamb=0.5, iterations=5)` für smooth normals.

### 2026-03-07 | React Dashboard | Responsive CSS-Grid mit matchMedia
Inline-Styles für Grid-Positioning haben keine Medienabfrage-Unterstützung.
**Lösung:** `useLargeScreen()` Hook mit `window.matchMedia('(min-width: 1024px)')` + Change-Listener → `isLarge`-Boolean bedingt Inline-Styles.

### 2026-03-07 | Media Browser | ZIP-Download 22-Byte-Korruption
`storage_key` absolute Pfade + `except Exception: pass` → Silent-Fail → leere Archive.
**Lösung:** Pfad-Check vor MinIO-Fallback; `except` loggt jetzt `logger.warning()`. In Generator-Funktionen für Streaming IMMER loggen.

### 2026-03-07 | Frontend | Fehlende React-Imports crashen die gesamte App
`useEffect` hinzugefügt ohne Import → `ReferenceError` → Blank Page. ErrorBoundary auf Root-Level fängt nicht ab.
**Regel:** Nach jedem neuen Hook sofort Import-Zeile prüfen. `tsc --noEmit` als Quality Gate im Container.

### 2026-03-07 | Storage Keys | Absolute Pfade in DB brechen nach Infrastruktur-Änderung
Flamenco-Outputs in `/shared/renders/...` → nach Flamenco-Entfernung 396 Assets nicht erreichbar (absoluter Pfad + MinIO-Fallback beide leer).
**Lösung:** Bulk-UPDATE auf relative Keys + Safety-Net-Remapping im Code. `storage_key` IMMER relativ zu `UPLOAD_DIR`: `renders/{uuid}/{filename}`.

### 2026-03-07 | Config | Pydantic Settings: Attributname case-sensitive
`settings.UPLOAD_DIR` → `AttributeError`. Korrekt: `settings.upload_dir` (lowercase wie in config.py).
**Smoke-Test:** `docker compose exec backend python -c "from app.config import settings; print(settings.upload_dir)"`.

### 2026-03-07 | Media ZIP | MIME-Type-basierte Extension → ".bin" statt ".png"
`(mime_type or "").split("/")[-1]` → `"bin"` für Assets ohne MIME-Type.
**Lösung:** Extension primär aus `Path(storage_key).suffix` lesen. MIME-Type nur als Fallback. Duplikat-Filenames mit `_1`, `_2` deduplizieren.

### 2026-03-07 | Blender 5.0 | `export_colors` in bpy.ops.export_scene.gltf entfernt
`export_colors=False` → `keyword unrecognized` → exit 1 → immer Trimesh-Fallback, nie Materialien.
**Lösung:** Parameter entfernen. Gültige Blender-5.0-Parameter: `export_format`, `export_apply`, `use_selection`, `export_materials`, `export_image_format`. Nach Blender-Major-Updates alle bpy.ops.*-Parameter prüfen.

### 2026-03-07 | React | useRef mit if(!ref.current) Guard reagiert nicht auf Prop-Änderungen
`GlbModel` klonte `scene` in `useRef` einmalig → bei neuem `url`-Prop blieb altes Mesh.
**Lösung:** `key={glbBlobUrl}` auf `<GlbModel>` → React remountet, frischer useRef. Alternativ: `useMemo` mit URL-Dependency.

### 2026-03-07 | React | staleTime zu hoch verzögert Erkennung neuer API-Daten
`staleTime: 30_000` + `qc.invalidateQueries()` → trotzdem 30s Verzögerung bis neue GLB-URL ankam.
**Lösung:** `staleTime: 0` für Queries die nach Mutations sofort aktuell sein müssen.

### 2026-03-07 | GLB Export | Trimesh kennt keine Materialien — Blender-Pipeline ist Pflicht
Trimesh = reine Geometrie, keine Material-Libraries, kein Asset-Library-Support → graue, facettierte GLBs.
**Lösung:** `generate_gltf_geometry_task` auf Blender headless (`export_gltf.py`) umgestellt. Trimesh nur als Fallback. Skript vorhanden ≠ Skript verdrahtet — Aufruf-Pfad immer prüfen.

### 2026-03-07 | Frontend | `<img src>` kann keine Auth-Header senden — useAuthBlob Hook nötig
`<img src="/api/media/{id}/download">` → kein Authorization-Header → 401 → graues Icon.
**Lösung:** `useAuthBlob(url, enabled)`: `fetch(url, { headers: { Authorization } })` → `URL.createObjectURL(blob)` als src. Cleanup via `revokeObjectURL` + `cancelled`-Flag. Gilt für alle browser-nativen Media-Elemente (`<img>`, `<video>`, `<audio>`).

### 2026-03-07 | Backend | publish_asset fehlte product_id + cad_file_id
`MediaAsset` ohne `product_id`/`cad_file_id` → `get_thumbnail_url()` konnte keinen Thumbnail-Fallback berechnen → graue Icons.
**Lösung:** In `publish_asset`: `Product` laden, `product_id=line.product_id` + `cad_file_id=product.cad_file_id` setzen. MediaAssets immer mit allen verfügbaren Referenz-FKs erstellen.

### 2026-03-07 | Frontend | Inline 3D Viewer — GLB mit Auth via Blob URL laden
`useGLTF(url)` aus `@react-three/drei` kann keine Auth-Header senden.
**Lösung:** `fetch(url, { headers: { Authorization } })` → `.blob()` → `URL.createObjectURL(blob)` → String-URL an `useGLTF(blobUrl)`. Revoke in useEffect-Cleanup. Three.js / drei kennen kein Auth-Konzept.

### 2026-03-07 | Backend | trimesh in optionalem [cad]-Extra — nicht im Docker-Build installiert
`pip install -e ".[dev]"` installiert kein `trimesh` → `ModuleNotFoundError` beim ersten Aufruf.
**Lösung:** `pip install -e ".[dev,cad]"`. Beim Hinzufügen optionaler Extras immer prüfen ob alle relevanten Container-Images das Extra installieren.

### 2026-03-07 | Frontend | URL.revokeObjectURL sofort nach click() → Race Condition
`revokeObjectURL(url)` synchron nach `a.click()` → Download manchmal leer (click() ist in manchen Browsern asynchron).
**Lösung:** `setTimeout(() => URL.revokeObjectURL(url), 100)` für alle programmatischen Blob-Downloads.

### 2026-03-07 | Media Import | Falsche asset_type-Klassifizierung durch Dateinamen-Matching
Dateiname enthielt "Turntable" → `asset_type=turntable` auch für `.jpg` Poster-Frames → Browser versuchte JPGs als `<video>` zu rendern.
**Lösung:** Daten-Fix: `UPDATE media_assets SET asset_type='still' WHERE asset_type='turntable' AND storage_key LIKE '%.jpg'`. Code-Fix: `isVideoAsset()` nutzt `mime_type` zusätzlich. Asset-Typ IMMER aus mime_type + Dateiendung, nie nur aus Dateiname.

### 2026-03-08 | Render | OptiX BVH cache ephemeral → first render slow after rebuild
Nach `docker compose up --build render-worker`: erstes Render 130–150s statt 22s. `/root/.nv/ComputeCache/` liegt im ephemeren Container-Dateisystem → wird bei jedem Rebuild geleert.
**Lösung:** Named volume: `optix-cache:/root/.nv` in docker-compose.yml. Detection: Render 1 >> Render 2+3 nach Rebuild → OptiX cold-start.

### 2026-03-10 | R3F | Invisible meshes: check `e.object.visible` in handlers causes regression
`mesh.visible = false` + Guard `if (!e.object.visible) return` in Event-Handlern blockiert alle Folge-Events — R3F's Event-Tracking feuert events mit `e.object` auf Meshes die nach dem Tracking unsichtbar wurden.
**Lösung:** `mesh.raycast = () => {}` wenn `mesh.visible = false`; restore mit `THREE.Mesh.prototype.raycast` beim Einblenden. Meshes vom Raycasting ausschließen an der Quelle, nicht im Handler.
**Regel:** Nie `e.object.visible` in R3F pointer/click-Handlern prüfen.

### 2026-03-10 | Three.js/GLTF | `mesh.name` wird durch sanitizeNodeName verändert — `mesh.userData.name` nutzen
Three.js `GLTFLoader.createUniqueName()` ruft `PropertyBinding.sanitizeNodeName()` auf, welches reservierte Zeichen `[]:./` **entfernt**. Blender-Dedup-Suffixe `.001`, `.012` etc. werden zu `001`, `012` — ohne Punkt.
Unser `normalizeMeshName` strippte `\.\d{3}$` (mit Punkt), aber der Punkt ist bereits weg → `GE360-HF-0051-EIN_1.012` → (Three.js sanitize) → `GE360-HF-0051-EIN_1012` → kein Match in partMaterials → fälschlich "unassigned".
**Fix:** `mesh.userData.name` verwenden statt `mesh.name`. Three.js speichert den Original-GLTF-Node-Namen (unsanitized, mit Punkten) in `node.userData.name = nodeDef.name` **bevor** `node.name = sanitize(...)` gesetzt wird. Pattern: `(mesh.userData?.name as string) || mesh.name`.
**Gilt für:** handleClick, handlePointerOver/Out, visibility/glow/color effects, onReady callback, glbMeshNames-Traversal in InlineCadViewer + ThreeDViewer.

### 2026-03-10 | OCC/GLTF | Assembly containers have no geometry → no mesh in GLB
`cad_part_materials` enthält Keys für Assembly-Nodes (`_ASM_1`, `_BASIS_ASM_1`), die in cadquery geparst werden, aber keine Geometrie haben → nicht im GLB. Debug-Log "matched: 4 of 9 stored keys" = 5 Keys sind Assembly-Container, kein Bug.
**Regel:** Für assigned/total-Zählung immer `glbMeshNames` (Set aus scene traversal) nutzen, nie `Object.keys(partMaterials).length`.

### 2026-03-10 | Debug-Workflow | GLB-Geometrie-Analyse direkt per Python — ohne Browser-DevTools
Bei Mesh-Name-Mismatch-Bugs: GLB-Datei direkt parsen statt im Browser debuggen. Spart viele Iterationen.

**Schritt 1 — GLB-Download-URL holen:**
```python
import urllib.request, json, struct
# Login
data = json.dumps({'email':'admin@hartomat.com','password':'Admin1234!'}).encode()
req = urllib.request.Request('http://localhost:8888/api/auth/login', data=data, headers={'Content-Type':'application/json'})
token = json.load(urllib.request.urlopen(req))['access_token']
# Media-Assets für CAD-File
assets = json.load(urllib.request.urlopen(urllib.request.Request(
    f'http://localhost:8888/api/media/?cad_file_id={CAD_FILE_ID}&asset_types=gltf_production&asset_types=gltf_geometry',
    headers={'Authorization': f'Bearer {token}'})))
```

**Schritt 2 — GLB parsen und Mesh-/Node-Namen ausgeben:**
```python
req = urllib.request.Request(DOWNLOAD_URL, headers={'Authorization': f'Bearer {token}'})
glb = urllib.request.urlopen(req).read()
chunk_len, _ = struct.unpack('<II', glb[12:20])
gltf = json.loads(glb[20:20+chunk_len])
nodes, meshes = gltf['nodes'], gltf['meshes']
for n in nodes:
    if n.get('mesh') is not None:
        print(f"node={repr(n['name'])}  mesh_def={repr(meshes[n['mesh']]['name'])}")
```

**Schritt 3 — normalizeMeshName + resolvePartMaterial in Python nachbauen und alle Namen durchlaufen:**
So lässt sich der vollständige Matching-Status (ASSIGNED/UNASSIGNED) offline prüfen, ohne den Browser zu öffnen. Ggf. gespeicherte `cad_part_materials` via `GET /api/cad/{id}/part-materials` dazuladen.

**Produkt-ID → CAD-File-ID:** `GET /api/products/{product_id}` → Feld `cad_file_id`.
**CAD-File-ID für Media-Assets:** `GET /api/media/?cad_file_id={id}&asset_types=gltf_production` (nutzt `listMediaAssets`, nicht `getMediaAssets`).

### 2026-03-11 | Render-Pipeline | Production GLB: Koordinaten OCC→Blender falsch
OCC STEP-Koordinaten (Z-up, mm) werden von `export_step_to_gltf.py` auf Y-up (glTF) rotiert, dann vom Blender-Importer wieder auf Z-up. Netto: `Blender(X, Y, Z) = OCC(X×0.001, -Z×0.001, Y×0.001)` — Y und Z tauschen plus Z-Negierung. Einfach mm→m skalieren (X=X, Y=Y, Z=Z) ist FALSCH.
**Lösung:** In allen `_apply_sharp_edges_from_occ()`-Funktionen: `v = Vector((p[0]*0.001, -p[2]*0.001, p[1]*0.001))`.
**Diagnose:** `DEBUG first_vert_local=[0.0, -0.1175, 0.26]` vs `occ_pair=[0.0, 0.26, 0.1175]` zeigte eindeutig Y↔Z-Swap + Z-Negierung.

### 2026-03-11 | Render-Pipeline | Production GLB: Mesh-Data-Sharing bei Material-Zuweisung
Nach GLB-Import teilen sich mehrere Blender-Objekte denselben Mesh-Datablock (z.B. Instanzen). `obj.data.materials.clear()` auf geteilten Daten löscht Materialien für ALLE Objekte, die diesen Mesh teilen.
**Lösung:** Vor `obj.data.materials.clear()` immer: `if obj.data.users > 1: obj.data = obj.data.copy()` (single-user machen).

### 2026-03-11 | Render-Pipeline | Production GLB: Name-Mismatch cadquery vs. RWGltf
cadquery-Parser und RWGltf_CafWriter lesen dieselbe STEP-Datei, erzeugen aber unterschiedliche Part-Namen (z.B. cadquery: `GE360-HF-0011-EIN_HAELFTE_AF0_1_AF0` vs. RWGltf: `GE360-HF-0021-EIN`). Material-Mapping via Namen deckt nur 2/25 Objekte ab.
**Lösung 1:** Prefix-Match: `key.startswith(lower_base)` oder `lower_base.startswith(key)`.
**Lösung 2:** Single-Material-Fallback: wenn `len(appended) == 1` (nur 1 Bibliotheks-Material geladen), alle ungematchten Objekte ebenfalls mit diesem Material belegen.
**Generell:** Part-Namen aus zwei verschiedenen OCC-Lese-Pfaden NIE direkt vergleichen.

### 2026-03-11 | Python/Blender | `id(bpy_object)` über Iterationen hinweg unzuverlässig
Blender-Objekte sind Python-Wrapper über C++-Objekte. Nach einer Schleife können gleiche C++-Objekte neue Python-Wrapper bekommen → `id()` ändert sich. Tracking mit `id(obj)` in einem Set und Prüfung in einer zweiten Schleife funktioniert NICHT.
**Lösung:** `obj.name` als stabiler Identifier (Blender-Namen sind innerhalb der Szene eindeutig und bleiben stabil).

### 2026-03-11 | Python/Blender | `bmesh.edges.get((v0, v1))` schlägt fehl bei idx0==idx1
Wenn KD-Tree für beide Endpunkte denselben Vertex findet (z.B. degenerate/zero-length edge), wirft `edges.get((v, v))` `ValueError: found the same (BMVert) used multiple times`.
**Lösung:** Guard: `if idx0 == idx1: continue` direkt nach dem `kd.find()` für Endpunkt 2.

### 2026-03-11 | Workflow | System-Daten direkt lesen — kein docker exec nötig
Für den `/plan`-Agent: alle relevanten System-Daten sind OHNE docker-Befehle zugänglich:
- **Datenbankmodelle:** `backend/app/models/` und `backend/app/domains/*/models.py` direkt lesen
- **API-Endpoints:** `backend/app/api/routers/` und `backend/app/domains/*/routers.py` lesen — kein curl/docker exec nötig
- **Celery-Tasks:** `backend/app/tasks/step_tasks.py` und `backend/app/domains/pipeline/tasks/` lesen
- **Render-Scripts:** `render-worker/scripts/` lesen — `blender_render.py`, `export_gltf.py` etc.
- **Frontend-API:** `frontend/src/api/*.ts` zeigt alle API-Calls und Typen
- **Gespeicherte Daten:** `CadFile.mesh_attributes`, `Product.cad_part_materials`, `SystemSetting` in Modellen beschrieben
- **Docker-Logs nur für Debugging:** `docker compose logs --since 5m render-worker 2>&1 | grep -E "pattern"` — sparsam einsetzen, nicht für Codeanalyse
- **Kein `docker exec backend python3 -c`** für Code-Exploration — dauert lang und braucht laufende Container
- **MEMORY.md** enthält Container-Capabilities: OCP nur in `render-worker`, nicht in `worker` oder `backend`

### 2026-03-11 | Render-Pipeline | Production GLB: edit-mode mark_sharp+mark_seam für korrekte GLB Sharp Edges
In Blender 5.0: `shade_smooth_by_angle()` allein reicht nicht für scharfe Kanten im GLB-Export.
**Lösung:** Edit-mode-Operators verwenden: `edges_select_sharp(sharpness=angle)` → `mark_sharp()` → `mark_seam()`.
Der glTF-Exporter erstellt an den als sharp markierten Edges Vertex-Splits (duplizierte Vertices mit verschiedenen Normalen).
**Verifizierung:** 543 sharp+seam Edges markiert → production GLB hat 812 extra Vertices + 6027 Positionen mit mehreren Normalen = scharfe Kanten korrekt enkodiert.
**Wichtig:** `calc_normals_split()` wurde in Blender 5.0 entfernt (→ AttributeError). Nicht mehr nötig: `export_apply=True` triggert Vertex-Splitting automatisch.

### 2026-03-11 | Render-Pipeline | MediaAsset DELETE+INSERT erzeugt neue UUID → 404 auf gecachte URLs
`generate_gltf_production_task` und `generate_gltf_geometry_task` löschten alten MediaAsset-Record und erstellten neuen mit neuer UUID.
Gecachte Download-URLs (z.B. im Frontend-State) zeigten auf die alte, gelöschte UUID → 404.
**Lösung:** UPSERT: existierenden Record aktualisieren (`existing.storage_key = _key`) statt DELETE+INSERT. UUID bleibt stabil.

### 2026-03-11 | Render-Pipeline | Production GLB: OCC custom_normal überschreibt Blender-Normalen
`export_step_to_gltf.py` (RWGltf_CafWriter) embedded per-corner normals from OCC tessellation as a `custom_normal` attribute (CORNER, INT16_2D) in the geometry GLB. Blender's glTF importer preserves this as a custom attribute. The glTF exporter then re-exports these pre-baked normals **unchanged**, ignoring `shade_smooth_by_angle` processing and explicit `edge.smooth=False` sharp marks — sharp edges are invisible in the production GLB.
**Lösung:** In `export_gltf.py` und `blender_render.py`: nach GLB-Import das `custom_normal`-Attribut von allen Mesh-Objekten entfernen, BEVOR `shade_smooth_by_angle()` aufgerufen wird. Dann berechnet Blender die Normalen neu aus den sharp-edge-Marks.
**Diagnose:** File-Size-Test: WITH custom_normal=1218960 Bytes, WITHOUT=1137944 Bytes. Re-import zeigte `has_custom_normals=True`. GLB-JSON-Inspektion mit `struct.unpack` + `json.loads` direkt auf `.glb`-Datei.
```python
for obj in mesh_objects:
    if "custom_normal" in obj.data.attributes:
        obj.data.attributes.remove(obj.data.attributes["custom_normal"])
```

### 2026-03-11 | Render-Pipeline | OCC B-rep sharp edges: BRep_Tool.Polygon3D_s() gibt None zurück
`BRep_Tool.Polygon3D_s(edge, loc)` und `PolygonOnTriangulation_s()` geben in XCAF-Compound-Kontext immer `None` zurück — Tessellation-Polygon-Daten liegen auf Component-Instanzen, nicht auf den Compound-Edges. Ergebnis: 612 scharfe Kanten erkannt, 0 Segment-Paare extrahiert.
**Lösung:** `GCPnts_UniformAbscissa(curve3d, step_mm=0.3, tol=1e-6)` auf der analytischen B-rep-Kurve (`BRepAdaptor_Curve`) samplen. 0.3mm-Schritt garantiert dass konsekutive Sample-Paare die Tessellations-Kanten (~0.78-1.55mm) straddeln — die KD-Tree-Suche (TOL=0.5mm) findet dann die richtigen Blender-Mesh-Edges. Ergebnis: 17.129 Segment-Paare, 1.364 Kanten in Blender markiert.
**Imports:** `from OCP.GCPnts import GCPnts_UniformAbscissa; from OCP.BRepAdaptor import BRepAdaptor_Curve`

### 2026-03-12 | OCC/USD | export_step_to_usd.py: face_loc == shape_loc → Doppel-Transform → falsche Mesh-Positionen
`BRepMesh_IncrementalMesh` auf dem Root-Compound tesselliert alle Instanzen. `BRep_Tool.Triangulation_s(face, face_loc)` liefert dabei einen `face_loc`, der exakt die Instance-Platzierung des shape kodiert (identisch zu `shape.Location()`). In `_extract_mesh()` wurden beide Transforms nacheinander angewendet: erst `face_loc.Transformation()`, dann `shape_trsf` — was eine Doppel-Rotation ergibt. Für einen Zylinder-Rollensatz (12 Rollen à 30° Abstand) führt das dazu, dass mehrere Rollen auf dieselbe falsche Position kollabieren (z.B. -75° × 2 = -150° = +105° × 2 mod 360° → Rollen 3 und 9 landen identisch).
**Lösung:** `if face_has_loc: ... elif shape_has_loc: ...` statt `if face_has_loc: ... if shape_has_loc: ...`. `shape_loc` ist nur ein Fallback für direkt tessellierte Shapes (nicht als Teil eines Compounds), bei denen `face_loc` identity ist.
**Beweis:** Mit `face_only`-Extraktion (nur face_loc, kein shape_loc) erscheinen alle 10 Rollen bei genau 223,9mm Radius, gleichmäßig 30° verteilt.

---

## Offene Fragen
(keine offenen Fragen)

### 2026-03-11 | OCP/Python | id(solid.TShape()) ist nicht stabil
In OCP (pybind11-basiert) gibt jeder Aufruf von `solid.TShape()` ein neues Python-Wrapper-Objekt zurück, das dieselbe C++ TShape-Instanz wrapet. `id()` gibt daher jedes Mal einen anderen Wert → Deduplizierung per `id()` schlägt immer fehl. **Lösung:** `solid.IsSame(other_solid)` verwenden (vergleicht TShape-Zeiger intern, liefert True für gleiche TShape mit unterschiedlicher Location/Orientation).

### 2026-03-11 | GMSH | TopExp_Explorer(SOLID) übersieht freie Faces und Shells
`TopExp_Explorer(root, SOLID)` findet nur `TopoDS_Solid`-Shapes, nicht freie `TopoDS_Shell`- oder `TopoDS_Face`-Shapes auf Compound-Ebene. OCC's `BRepMesh_IncrementalMesh` auf dem Root-Compound tesselliert alle Typen rekursiv. **Lösung:** BRepMesh-Baseline zuerst auf den vollen Root-Compound, dann GMSH als Override nur für SOLID-Shapes. So werden keine Shapes übersprungen.

### 2026-03-11 | GMSH | CharacteristicLengthMax vs. OCC linear_deflection
OCC `linear_deflection=0.1mm` auf einem 50mm-Zylinder → Kantenlänge ~5mm. GMSH `CharacteristicLengthMax=0.1×15=1.5mm` → 3× mehr Unterteilungen → 9× mehr Dreiecke → GLB 7× größer. **Lösung:** `CharacteristicLengthMax = linear_deflection × 50` (≈5mm), `MinimumCirclePoints = min(12, ...)` statt min(20). Ergebnis: GMSH 91% von OCC-Größe (Ziel ≤120% ✓).

### 2026-03-12 | GMSH | Priority 3 vollständig — GMSH-Pipeline Status
GMSH 4.15.1 in render-worker installiert. `tessellation_engine=gmsh` ist der aktive DB-Default. `_tessellate_with_gmsh()` in `export_step_to_gltf.py` vollständig: `CharacteristicLengthMax = linear_deflection × 50`, `MinimumCirclePoints = min(12, ...)`, REVERSED Solids bleiben erhalten (kein invertierter Jacobian). Produktion-GLB nutzt Cache-Reuse (kein Re-Tessellieren bei Materialwechsel). Sharp-Edge-Extraktion läuft nach Tessellierung unabhängig vom Engine-Typ — `Injected N segment pairs into GLB extras` gilt für beide Pfade.

### 2026-03-12 | OCC | BRepMesh auf Compound: Triangulation in Definition-Space, Face-loc = Instance-Placement
`BRepMesh_IncrementalMesh(compound)` tesselliert alle Faces in Definition-Space-Koordinaten. Für Instanzen mit Placement enthält `face.Location()` (= `TopoDS_Shape`-Location) die Instance-Transformation. `BRep_Tool.Triangulation_s(face, loc)` gibt die Triangulation-Knoten in Definition-Space zurück, `loc` enthält die Face-Location (= Instance-Placement). `BRep_Builder.UpdateFace(face_def, tri)` mit einer aus `solid.Located(TopLoc_Location())` gewonnenen Face schreibt auf das geteilte TShape — ALLE Instanzen der gleichen Geometrie sehen die neue Triangulation, da sie IsPartner teilen.

### 2026-03-12 | OCC/XCAF | IsSame() vs IsPartner() — Deduplizierung bei Assembly-Instanzen
`IsSame()` prüft TShape-Pointer UND Location → für 16 Instanzen desselben Wälzkörpers sind alle 16 "unique" (unterschiedliche Location). `IsPartner()` prüft nur TShape-Pointer → gibt 9 tatsächlich unterschiedliche Geometrien. In `export_step_to_gltf.py` GMSH-Schleife: `IsSame()`-Deduplizierung tesselliert alle 16 Instanzen separat, aber da sie das gleiche TShape teilen, werden alle 16 mal auf dasselbe TShape geschrieben (idempotent, korrekt). `RWGltf_CafWriter` traversiert XCAF-Labelhierarchie und liest Triangulation von Definition-Labels (Identity-Location) — kein Double-Transform.

### 2026-03-12 | Debugging | Stale GLB-Cache maskiert Code-Fixes
Bug "Wälzkörper an falscher Position" war in Code durch commit 638b93b (IsSame-Fix) bereits behoben. Aber gecachtes Produktions-GLB (vor dem Fix generiert) zeigte weiterhin falsche Positionen im Viewer. Lösung: Geometry-GLB manuell neu generieren oder `step_file_hash = NULL` in DB um Cache-Invalidierung zu erzwingen. Nach Code-Fixes an Tessellierung/Export IMMER alle betroffenen GLB-Caches invalidieren.

### 2026-03-13 | OCC/GLB | BRepBuilderAPI_Transform zerstört Tessellierung + RWGltf_CafWriter MergeFaces
**Problem**: GLB-Dateien hatten nur ~164 Vertices pro Bauteil statt ~7000. Zwei Ursachen:
1. `BRepBuilderAPI_Transform(shape, trsf, copy=True)` zerstört **alle** `Poly_Triangulation`-Daten. Die mm→m-Skalierung vor dem Export löschte die BRepMesh-Tessellierung.
2. `RWGltf_CafWriter` mit `MergeFaces=False` (Default) findet keine per-Face-Tessellierung aus der XCAF-Komponentenhierarchie und produziert degenerierte Meshes.
**Lösung**:
- `BRepBuilderAPI_Transform` komplett entfernt — `RWGltf_CafWriter` konvertiert intern mm→m und Z-up→Y-up.
- `writer.SetMergeFaces(True)` hinzugefügt — composited Face-Triangulationen zu korrekten Shape-Buffern (1.212 → 46.573 Vertices).
**Merke**: OCC `TopLoc_Location` kann keine Skalierung (wirft `Standard_DomainError`). Für Skalierung entweder den Writer intern konvertieren lassen oder GLB post-process.