HartOMat/plan.md

# Plan: Priority 1 — Pipeline Cleanup (M1 Dead Code + M3 blender_render Split)

## Context

ROADMAP Priority 1 is "In Progress". M2 (`step_tasks.py` decomposed to `domains/pipeline/tasks/`) is **done**. Two milestones remain:

- **M1**: Delete dead-code directories, remove `stl_quality` from admin/frontend surface, remove dead functions
- **M3**: Decompose `blender_render.py` (920 lines) into focused submodules

---

## Affected Files

| File | Change |
|------|--------|
| `blender-renderer/` | DELETE directory |
| `threejs-renderer/` | DELETE directory |
| `renderproblems_tmp/` | DELETE directory |
| `backend/app/api/routers/admin.py` | Remove `stl_quality` + `VALID_STL_QUALITIES` (7 locations) |
| `frontend/src/api/orders.ts` | Remove `stl_quality?: string` |
| `frontend/src/api/worker.ts` | Remove `stl_quality?: string` |
| `frontend/src/pages/WorkerActivity.tsx` | Remove STL quality KV row |
| `frontend/src/components/renders/RenderInfoModal.tsx` | Remove STL quality display row |
| `frontend/src/help/helpTexts.ts` | Remove `setting.stl_quality` entry |
| `backend/app/services/step_processor.py` | Remove `_render_via_service()` + dead `elif renderer == "threejs"` |
| `render-worker/scripts/blender_render.py` | Remove `_mark_sharp_and_seams()`; thin to entry-point after submodule extraction |
| `render-worker/scripts/_blender_gpu.py` | CREATE — `activate_gpu()` |
| `render-worker/scripts/_blender_import.py` | CREATE — `import_glb()`, `apply_rotation()` |
| `render-worker/scripts/_blender_materials.py` | CREATE — `build_mat_map_lower()`, `apply_material_library()`, `assign_failed_material()` |
| `render-worker/scripts/_blender_camera.py` | CREATE — `setup_auto_camera()`, `setup_auto_lights()` |
| `render-worker/scripts/_blender_scene.py` | CREATE — `ensure_collection()`, `apply_smooth_batch()`, `apply_sharp_edges_from_occ()`, `setup_shadow_catcher()` |

---

## Tasks (in order)

### [x] Task M1-1: Delete obsolete directories

- **What**: `rm -rf blender-renderer/ threejs-renderer/ renderproblems_tmp/`
- **Acceptance gate**: `ls blender-renderer/ threejs-renderer/ renderproblems_tmp/` → all "No such file"
- **Dependencies**: none
- **Risk**: Zero — no active source files

---

### [x] Task M1-2: Remove stl_quality from admin.py

- **File**: `backend/app/api/routers/admin.py`
- **What**: Delete all 7 references:
  1. `VALID_STL_QUALITIES = {"low", "high"}` constant
  2. `"stl_quality": "low"` from `SETTINGS_DEFAULTS`
  3. `stl_quality: str = "low"` from `SettingsOut`
  4. `stl_quality: str | None = None` from `SettingsUpdate`
  5. `stl_quality=raw["stl_quality"],` from `_settings_to_out()`
  6. `if body.stl_quality is not None and body.stl_quality not in VALID_STL_QUALITIES:` validation block
  7. `if body.stl_quality is not None: updates["stl_quality"] = body.stl_quality` update block
- **Acceptance gate**: `grep -n "stl_quality\|VALID_STL_QUALITIES" backend/app/api/routers/admin.py` → 0 matches
- **Dependencies**: none
- **Risk**: Low — the DB key remains (harmless); pipeline internally still uses `gltf_*_linear_deflection`

---

### [x] Task M1-3: Remove stl_quality from frontend

- **Files**:
  - `frontend/src/api/orders.ts` — remove `stl_quality?: string`
  - `frontend/src/api/worker.ts` — remove `stl_quality?: string`
  - `frontend/src/pages/WorkerActivity.tsx` — remove STL quality KV row
  - `frontend/src/components/renders/RenderInfoModal.tsx` — remove STL quality row
  - `frontend/src/help/helpTexts.ts` — remove `setting.stl_quality` entry
- **Acceptance gate**: `grep -rn "stl_quality" frontend/src/` → 0 matches; `npx tsc --noEmit` passes
- **Dependencies**: M1-2
- **Risk**: Low — all uses are optional fields (`?:`)

---

### [x] Task M1-4: Remove dead _mark_sharp_and_seams from blender_render.py

- **File**: `render-worker/scripts/blender_render.py`
- **What**: Delete the `_mark_sharp_and_seams()` function (lines 196–256 approx). It is defined but never called — `_apply_sharp_edges_from_occ()` is the active implementation.
- **Acceptance gate**: `grep -n "_mark_sharp_and_seams" render-worker/scripts/blender_render.py` → 0 matches
- **Dependencies**: none
- **Risk**: Zero — verifiably never called

---

### [x] Task M1-5: Remove dead code from step_processor.py

- **File**: `backend/app/services/step_processor.py`
- **What**: Delete `_render_via_service()` function and the `elif renderer == "threejs":` branch (which only logs a warning and falls through)
- **Acceptance gate**: `grep -n "_render_via_service\|renderer == .threejs" backend/app/services/step_processor.py` → 0 matches
- **Dependencies**: M1-1
- **Risk**: Low — function is only referenced from within the dead branch

---

### [x] Task M3-1: Create _blender_gpu.py

- **File**: `render-worker/scripts/_blender_gpu.py` (NEW)
- **What**: Extract `_activate_gpu()` from `blender_render.py` into a standalone module. Refactor to accept `cycles_device: str` parameter instead of reading a module-level global. Rename to `activate_gpu()`.
- **Key signature**: `def activate_gpu(cycles_device: str = "auto") -> str | None`
- **Acceptance gate**: `grep -c "def _activate_gpu" render-worker/scripts/blender_render.py` → 0; function callable as `from _blender_gpu import activate_gpu`
- **Dependencies**: M1-4
- **Risk**: Medium — must pass `sys.path` correctly so Blender Python finds the module

---

### [x] Task M3-2: Create _blender_import.py

- **File**: `render-worker/scripts/_blender_import.py` (NEW)
- **What**: Extract `_import_glb()` and `_apply_rotation()` into module. Rename to `import_glb()` / `apply_rotation()`.
- **Acceptance gate**: `grep -c "def _import_glb\|def _apply_rotation" render-worker/scripts/blender_render.py` → 0
- **Dependencies**: M1-4
- **Risk**: Low — no hidden globals beyond `bpy`, `math`, `Vector`

---

### [x] Task M3-3: Create _blender_materials.py

- **File**: `render-worker/scripts/_blender_materials.py` (NEW)
- **What**: Extract `_assign_failed_material()`, `_apply_material_library()`, and the `mat_map_lower` building loop. Consolidate the duplicated `mat_map_lower` logic (currently in Mode A and Mode B) into a single `build_mat_map_lower()` helper. `FAILED_MATERIAL_NAME` constant lives here.
- **Acceptance gate**: `grep -c "def _assign_failed_material\|def _apply_material_library" render-worker/scripts/blender_render.py` → 0
- **Dependencies**: M1-4
- **Risk**: Medium — `_apply_material_library()` currently uses `part_names_ordered` global; must convert to parameter

---

### [x] Task M3-4: Create _blender_camera.py

- **File**: `render-worker/scripts/_blender_camera.py` (NEW)
- **What**: Extract auto-camera placement block (bounding sphere computation, isometric positioning, clip plane setup, `ELEVATION_DEG`/`AZIMUTH_DEG` constants) and `setup_auto_lights()`.
- **Key signatures**: `def setup_auto_camera(parts, width, height) -> tuple[Vector, float]` (returns center + radius for reuse by lights); `def setup_auto_lights(bbox_center, bsphere_radius) -> None`
- **Acceptance gate**: `grep -c "ELEVATION_DEG\|AZIMUTH_DEG\|bsphere_radius" render-worker/scripts/blender_render.py` → 0
- **Dependencies**: M3-2
- **Risk**: Low — camera block is self-contained

---

### [x] Task M3-5: Create _blender_scene.py

- **File**: `render-worker/scripts/_blender_scene.py` (NEW)
- **What**: Extract `_ensure_collection()`, `_apply_smooth_batch()`, `_apply_sharp_edges_from_occ()`, shadow catcher setup into module.
- **Acceptance gate**: `grep -c "def _ensure_collection\|def _apply_smooth_batch\|def _apply_sharp_edges_from_occ" render-worker/scripts/blender_render.py` → 0
- **Dependencies**: M1-4
- **Risk**: Low

---

### [x] Task M3-6: Thin blender_render.py to entry-point

- **File**: `render-worker/scripts/blender_render.py`
- **What**: Replace all extracted function bodies with imports from submodules. Add `sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))` before imports so Blender Python finds the submodules. Result: argument parsing + Mode A/B orchestration + timing only. Target: < 200 lines.
- **Acceptance gate**: `wc -l render-worker/scripts/blender_render.py` → < 200; upload `81113-l_cut.stp` → thumbnail renders correctly
- **Dependencies**: M3-1, M3-2, M3-3, M3-4, M3-5
- **Risk**: High (integration step) — test immediately after deploy

---

## Migration Check

**No migration required.** `stl_quality` key stays in DB (harmless). No new columns or tables.

---

## Order Recommendation

```
M1-1 (delete dirs) → M1-4 (dead func blender) → M1-5 (dead func step_processor)
→ M1-2 (admin.py) → M1-3 (frontend)
→ M3-1..M3-5 (create submodules in parallel where possible)
→ M3-6 (thin blender_render.py — integration, highest risk, test immediately)
```

Deploy after M1: `docker compose up -d --build backend`
Deploy after M3-6: `docker compose up -d --build render-worker`

---

## Risks / Open Questions

1. **Blender `sys.path`**: Submodule files must be at `/render-scripts/` (the volume mount path). `sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))` is the safe way to ensure this regardless of CWD.
2. **`part_names_ordered` global**: Currently used across multiple functions in `blender_render.py`. Must be explicitly passed as a parameter to `apply_material_library()` in M3-3.
3. **M3 scope**: M3 is a pure refactor — no behaviour change. If time is limited, M1 (dead code removal) delivers clean value on its own. M3 can be deferred to a separate session.