chore: snapshot workflow migration progress
This commit is contained in:
@@ -0,0 +1,399 @@
|
||||
# Next Batch Orchestration
|
||||
|
||||
## Goal
|
||||
|
||||
Define the next sensible implementation batch after the export/CAD contract audit, with work split for parallel execution and an integration order that keeps the legacy workflow operational.
|
||||
|
||||
## Current Batch
|
||||
|
||||
### Batch B1: Test Infrastructure Recovery
|
||||
|
||||
Purpose:
|
||||
Restore deterministic backend test execution so workflow parity work can be validated against real DB-backed tests again.
|
||||
|
||||
Why now:
|
||||
|
||||
- current targeted DB-backed tests fail on missing tables such as `users` and `cad_files`
|
||||
- this blocks trustworthy validation for further workflow runtime work
|
||||
|
||||
Primary ownership:
|
||||
|
||||
- `backend/tests/**`
|
||||
- `backend/app/database.py`
|
||||
- `backend/app/config.py` only if required for test bootstrapping
|
||||
|
||||
Acceptance:
|
||||
|
||||
- targeted workflow tests create their schema reliably
|
||||
- DB-backed pytest runs do not fail due to missing core tables
|
||||
- no production runtime behavior changes unless strictly required for test setup correctness
|
||||
|
||||
### Batch B2: Workflow Editor Authoring Organization
|
||||
|
||||
Purpose:
|
||||
Reduce authoring friction in `/workflows` by tightening node organization around family, module, and execution role while reclaiming canvas space.
|
||||
|
||||
Why now:
|
||||
|
||||
- the editor already has the needed primitives
|
||||
- the remaining gap is structural clarity, not missing mechanics
|
||||
|
||||
Primary ownership:
|
||||
|
||||
- `frontend/src/components/workflows/**`
|
||||
- `frontend/src/pages/WorkflowEditor.tsx`
|
||||
- `frontend/src/__tests__/components/workflowEditorUi.test.tsx`
|
||||
|
||||
Acceptance:
|
||||
|
||||
- top-area clutter is reduced
|
||||
- node discovery is cleaner by family/module grouping
|
||||
- right-click insertion, edge deletion, align, dry-run, and run inspection still work
|
||||
|
||||
### Batch B3: Canonical Still Path Smoke-Harness Closure
|
||||
|
||||
Purpose:
|
||||
Move the non-legacy still workflow closer to a runnable, documented smoke path without weakening legacy fallback.
|
||||
|
||||
Why now:
|
||||
|
||||
- backend graph/runtime coverage is already substantial
|
||||
- the next risk is proving that the canonical still graph can be exercised as a stable rollout candidate
|
||||
|
||||
Primary ownership:
|
||||
|
||||
- `backend/app/domains/rendering/**`
|
||||
- `backend/app/domains/pipeline/tasks/**`
|
||||
- `backend/tests/domains/test_workflow_*.py`
|
||||
- `scripts/test_render_pipeline.py`
|
||||
- `docs/workflows/**` where needed
|
||||
|
||||
Acceptance:
|
||||
|
||||
- canonical still graph path has a bounded smoke route
|
||||
- graph-vs-legacy safety remains explicit
|
||||
- remaining blockers are documented as concrete runtime or fixture issues, not vague parity claims
|
||||
|
||||
## Updated Immediate Next Batch
|
||||
|
||||
The next implementation batch should now be cut along contract and root-cause boundaries instead of UI-only slices.
|
||||
|
||||
### Batch N1: Node-Contract Closure
|
||||
|
||||
Purpose:
|
||||
Make the backend node registry and workflow schema the authoritative source for graph family safety, parameter validity, and editor-visible node settings.
|
||||
|
||||
Why now:
|
||||
|
||||
- authoring UX is already good enough to build on
|
||||
- remaining parity work depends on trustworthy backend-owned contracts
|
||||
|
||||
Primary ownership:
|
||||
|
||||
- `backend/app/domains/rendering/workflow_node_registry.py`
|
||||
- `backend/app/domains/rendering/workflow_schema.py`
|
||||
- `backend/tests/domains/test_workflow_node_registry.py`
|
||||
- `backend/tests/domains/test_workflow_schema.py`
|
||||
|
||||
Acceptance:
|
||||
|
||||
- unknown node param keys are rejected deterministically
|
||||
- family drift is blocked by schema validation
|
||||
- every production-facing node has either a justified field schema or an explicit no-settings contract
|
||||
- existing canonical still graph remains valid
|
||||
|
||||
### Batch N2: Output-Type / Invocation Model Closure
|
||||
|
||||
Purpose:
|
||||
Finish the shift from legacy renderer flags to a real workflow invocation model with explicit family, artifact, and override semantics.
|
||||
|
||||
Why now:
|
||||
|
||||
- new output types and workflow-linked variants still depend on this contract being airtight
|
||||
- this is the clean boundary between product configuration and runtime dispatch
|
||||
|
||||
Primary ownership:
|
||||
|
||||
- `backend/app/domains/rendering/output_type_contracts.py`
|
||||
- `backend/app/api/routers/output_types.py`
|
||||
- `backend/app/domains/rendering/schemas.py`
|
||||
- `backend/app/domains/rendering/models.py`
|
||||
- `frontend/src/api/outputTypes.ts`
|
||||
- `frontend/src/components/admin/OutputTypeTable.tsx`
|
||||
|
||||
Acceptance:
|
||||
|
||||
- impossible workflow/artifact/family combinations are rejected early
|
||||
- new output types can be created top-to-bottom as invocation profiles
|
||||
- legacy-safe output types continue to render
|
||||
|
||||
### Batch N3: CAD / Material Parity Root-Cause Closure
|
||||
|
||||
Purpose:
|
||||
Close the remaining instance- and part-key-related drift between CAD exporter, GLTF viewer, preview, and downstream render consumption.
|
||||
|
||||
Why now:
|
||||
|
||||
- this is still a real production blocker, not a polish item
|
||||
- workflow parity stays superficial until geometry/material identity is stable
|
||||
|
||||
Primary ownership:
|
||||
|
||||
- `backend/app/domains/pipeline/tasks/export_glb.py`
|
||||
- `backend/app/domains/pipeline/tasks/extract_metadata.py`
|
||||
- `backend/app/services/part_key_service.py`
|
||||
- `frontend/src/components/cad/cadUtils.ts`
|
||||
- `frontend/src/components/cad/ThreeDViewer.tsx`
|
||||
- `frontend/src/components/cad/InlineCadViewer.tsx`
|
||||
|
||||
Acceptance:
|
||||
|
||||
- viewer and manifest resolve the same authoritative material identity
|
||||
- unresolved nodes are surfaced explicitly instead of silently using pseudo keys
|
||||
- legacy preview and render behavior remain intact
|
||||
|
||||
## Parallelization Rule
|
||||
|
||||
These three blocks should be prepared in parallel, but merged in order:
|
||||
|
||||
1. `N1` first, because it establishes the source of truth for the other two.
|
||||
2. `N2` second, because it builds directly on those contracts.
|
||||
3. `N3` can be investigated in parallel, but should merge after `N1` unless it proves fully isolated.
|
||||
|
||||
## Gate For The Following Batch
|
||||
|
||||
For the updated immediate next batch, the following gate applies:
|
||||
|
||||
- `N1` has deterministic backend validation and focused tests
|
||||
- `N2` preserves legacy-safe output types while tightening impossible combinations
|
||||
- `N3` proves the authoritative part/material identity chain with a focused low-RAM verification sequence
|
||||
|
||||
## Current Execution Status
|
||||
|
||||
- `N1` verified
|
||||
- focused checks green on April 10, 2026:
|
||||
- `backend/tests/domains/test_workflow_schema.py`
|
||||
- `backend/tests/domains/test_workflow_node_registry.py`
|
||||
- `N2` verified
|
||||
- focused checks green on April 10, 2026:
|
||||
- `backend/tests/domains/test_output_types_api.py`
|
||||
- `frontend/src/__tests__/api/outputTypes.test.ts`
|
||||
- `N3` in progress
|
||||
- April 10, 2026:
|
||||
- scene-manifest alias coverage expanded for exporter `_af*` suffix keys
|
||||
- order-line runtime now prefers authoritative scene-manifest assignments where manifest metadata exists
|
||||
- inline and fullscreen viewers now share the same manifest-plus-fallback merge contract
|
||||
- unresolved meshes are now surfaced explicitly in both viewers instead of silently disappearing behind pseudo keys
|
||||
- output-type authoring now consumes a backend-authored contract catalog for family/artifact/format/override constraints
|
||||
- next action: manual product-level parity check plus B04 node/module contract completion
|
||||
|
||||
## Executable Block List
|
||||
|
||||
Die naechste sinnvolle Abarbeitung ist nicht mehr nach einzelnen Features, sondern nach stabilen Vertrags- und Produktionsgrenzen geschnitten.
|
||||
|
||||
### Batch Wave W1: Identity And Contract Closure
|
||||
|
||||
- `B01` CAD manifest alias closure
|
||||
- Ziel: scene-manifest und viewer auf denselben kanonischen semantischen part keys bringen
|
||||
- Fokus: exporter-style suffixe wie `_af6`, `_af0_asm`, dedup keys, alias inheritance
|
||||
- Status: abgeschlossen am April 10, 2026
|
||||
- Gate: `backend/tests/test_part_key_service.py`, `backend/tests/test_export_step_to_gltf.py`, `frontend/src/__tests__/components/cadUtils.test.ts`
|
||||
- `B02` CAD viewer/manifest convergence
|
||||
- Ziel: unresolved parts explizit sichtbar halten, aber alle autoritativ aufloesbaren parts im Viewer korrekt materialisieren
|
||||
- Fokus: `ThreeDViewer`, `InlineCadViewer`, logical part keys, reconciliation UX
|
||||
- Parallel zu: `B03`, `B04`
|
||||
- Status: abgeschlossen am April 10, 2026
|
||||
- April 10, 2026:
|
||||
- inline und fullscreen viewer auf denselben `buildEffectiveViewerMaterials(...)` contract gezogen
|
||||
- unresolved meshes werden explizit gezaehlt und sichtbar angezeigt statt pseudo-keys zu synthetisieren
|
||||
- focused gates gruen:
|
||||
- `frontend/src/__tests__/components/cadUtils.test.ts`
|
||||
- `npm run build`
|
||||
- `./scripts/workflow_sequential_gates.sh`
|
||||
- Gate: manueller Produktcheck gegen reales CAD-Beispiel
|
||||
- `B03` Output-type authoring closure
|
||||
- Ziel: neue output types workflow-first und ohne hidden legacy assumptions anlegbar machen
|
||||
- Fokus: form-state, invocation overrides, artifact/family guards, defaults
|
||||
- Parallel zu: `B02`, `B04`
|
||||
- Status: abgeschlossen am April 10, 2026
|
||||
- April 10, 2026:
|
||||
- backend publiziert `GET /api/output-types/contract-catalog` als read-only Source of Truth fuer Family-, Artifact-, Format- und Override-Regeln
|
||||
- `frontend/src/api/outputTypes.ts` nutzt den Catalog mit lokalem Fallback statt Hardcode-Regeltabellen als primaere Truth
|
||||
- `OutputTypeTable` speist Family-, Artifact- und Rollout-Auswahl jetzt aus dem Backend-Catalog
|
||||
- focused gates gruen:
|
||||
- `backend/tests/domains/test_output_types_api.py`
|
||||
- `frontend/src/__tests__/api/outputTypes.test.ts`
|
||||
- `frontend npm run build`
|
||||
- `./scripts/workflow_sequential_gates.sh`
|
||||
- Gate: `backend/tests/domains/test_output_types_api.py`, `frontend/src/__tests__/api/outputTypes.test.ts`
|
||||
- `B04` Node/module contract completion
|
||||
- Ziel: jede produktionsrelevante node hat einen klaren backend-owned settings/input/output contract
|
||||
- Fokus: registry metadata, no-settings contracts, family-safe validation
|
||||
- Gate: `backend/tests/domains/test_workflow_schema.py`, `backend/tests/domains/test_workflow_node_registry.py`
|
||||
|
||||
### Batch Wave W2: Canonical Authoring Surface
|
||||
|
||||
- `B05` Family-scoped node organization
|
||||
- Ziel: CAD, Bridge und Graph nodes im Editor klar trennen und suchbar halten
|
||||
- Fokus: family/module grouping, right-click search, low-noise discovery
|
||||
- Abhaengigkeit: `B04`
|
||||
- Status: abgeschlossen am April 10, 2026
|
||||
- April 10, 2026:
|
||||
- raw node catalog ist jetzt family-first organisiert: family -> module -> stage -> category
|
||||
- family/module runtime chips und stage scopes bleiben sichtbar, ohne zur stage-first Navigation zurueckzufallen
|
||||
- focused gates gruen:
|
||||
- `frontend/src/__tests__/components/workflowNodeCatalog.test.ts`
|
||||
- `frontend/src/__tests__/components/workflowEditorUi.test.tsx`
|
||||
- `frontend npm run build`
|
||||
- `B06` Authoring surface simplification
|
||||
- Ziel: eine gemeinsame authoring surface fuer canvas-menu, sidebar und starter paths
|
||||
- Fokus: shared controller/model statt mehrfacher UI-Sonderlogik
|
||||
- Abhaengigkeit: `B04`
|
||||
- Status: abgeschlossen am April 10, 2026
|
||||
- April 10, 2026:
|
||||
- `workflowAuthoringSurface.ts` kapselt jetzt shared section resolution, active-section validity und insert bindings als gemeinsame Surface-Controller-Logik
|
||||
- `NodeCommandMenu` und `NodeDefinitionsPanel` nutzen denselben Controller statt paralleler lokaler Section-/Insert-State-Implementierungen
|
||||
- focused gates gruen:
|
||||
- `frontend/src/__tests__/components/workflowEditorUi.test.tsx`
|
||||
- `frontend/src/__tests__/components/workflowAuthoringGuidance.test.ts`
|
||||
- `frontend npm run build`
|
||||
- `B07` Canvas ergonomics closure
|
||||
- Ziel: edge deletion, auto-align, reduced top-area clutter, faster insertion paths sauber zusammenziehen
|
||||
- Fokus: interaction consistency statt punktuelle UX-Patches
|
||||
- Abhaengigkeit: `B06`
|
||||
- Status: in Arbeit am April 10, 2026
|
||||
- April 10, 2026:
|
||||
- `WorkflowCanvasToolbar` auf kompaktere, wiederverwendbare Action-/Field-/Badge-Bausteine gezogen
|
||||
- Top-Area auf zwei dichtere Informationsreihen reduziert: Identitaet/Status oben, Context/Hint-Rail unten
|
||||
- focused gates gruen:
|
||||
- `frontend/src/__tests__/components/workflowEditorUi.test.tsx`
|
||||
- `frontend npm run build`
|
||||
- `B08` Starter graph and module bundle normalization
|
||||
- Ziel: starter blueprints, reference bundles und seed workflows auf dieselben kanonischen module paths ziehen
|
||||
- Fokus: still graph, CAD intake graph, bundle drift verhindern
|
||||
- Parallel zu: `B07`
|
||||
|
||||
### Batch Wave W3: Runtime And Production Parity
|
||||
|
||||
- `B09` Template-aware runtime unification
|
||||
- Ziel: legacy und graph nutzen dieselbe template/material/output orchestration
|
||||
- Fokus: template resolution, samples/transparency, publish semantics
|
||||
- Abhaengigkeit: `B03`, `B04`, `B08`
|
||||
- `B10` Non-legacy still smoke closure
|
||||
- Ziel: der kanonische still graph wird als wiederholbarer smoke path belastbar
|
||||
- Fokus: preflight, dispatch, authoritative output_save, failure visibility
|
||||
- Abhaengigkeit: `B09`
|
||||
- `B11` Template parity matrix
|
||||
- Ziel: graph vs legacy mit echten render-templates, output-varianten und alpha/sample settings vergleichen
|
||||
- Fokus: echte parity-beweise statt pillow-only checks
|
||||
- Abhaengigkeit: `B09`
|
||||
- `B12` CAD intake moduleization
|
||||
- Ziel: CAD import/extract/export/bbox/material-steps als echte workflow-module verfuegbar machen
|
||||
- Fokus: node-based production fuer intake workflows
|
||||
- Abhaengigkeit: `B04`, `B08`
|
||||
|
||||
### Batch Wave W4: Operational Rollout
|
||||
|
||||
- `B13` Rollout and fallback controls
|
||||
- Ziel: graph/shadow/legacy pro workflow und pro output type sicher steuerbar halten
|
||||
- Fokus: rollout mode, immediate rollback, operator clarity
|
||||
- Abhaengigkeit: `B10`, `B11`
|
||||
- `B14` Sequential E2E gates
|
||||
- Ziel: low-RAM, reproduzierbare smoke/golden/browser gates fuer `/workflows`
|
||||
- Fokus: sequenzielle statt parallele Verifikation
|
||||
- Abhaengigkeit: `B10`, `B11`, `B13`
|
||||
- `B15` Repo hygiene root-cause closure
|
||||
- Ziel: generated artifacts, root-owned caches und compose-side effects ursachenseitig schliessen
|
||||
- Fokus: ownership, pycache, build artifacts, helper script cleanup
|
||||
- Kann parallel laufen zu: `B10` bis `B14`
|
||||
|
||||
## Recommended Immediate Parallel Batch
|
||||
|
||||
Die naechste sinnvolle Batch mit minimalen Konflikten ist:
|
||||
|
||||
1. `B02` lokal auf explizite unresolved-state-Fuehrung und viewer-level parity checks ziehen
|
||||
2. `B03` parallel als contract-catalog dedup zwischen Backend und Admin-UI bearbeiten
|
||||
3. `B15` parallel als Hygiene-Nebenstrang treiben
|
||||
|
||||
Danach:
|
||||
|
||||
1. `B04`
|
||||
2. `B05` bis `B08` als Authoring-Welle
|
||||
3. `B09` bis `B12` als Runtime-/Produktionswelle
|
||||
|
||||
## Latest Verification
|
||||
|
||||
- April 10, 2026:
|
||||
- `./scripts/workflow_sequential_gates.sh` gruen
|
||||
- backend runtime gates: `34 passed`
|
||||
- frontend workflow/editor gates: `23 passed`
|
||||
|
||||
## Executable Next Queue
|
||||
|
||||
Die naechsten 12 Blöcke werden ab jetzt als eine gemeinsame Queue gefahren. Parallel bedeutet hier: Analyse, Vorbereitung und isolierte Teilpatches koennen parallel laufen. Merge und Verifikation bleiben bewusst sequentiell.
|
||||
|
||||
### Queue Q2: Merge Order
|
||||
|
||||
1. `B04-a` Node text-contract validation
|
||||
- Ziel: unvalidierte produktionsrelevante Text-Inputs im Registry-/Schema-Layer schliessen
|
||||
- Scope: `workflow_node_registry.py`, `workflow_schema.py`, `test_workflow_schema.py`
|
||||
- Gate: neue Schema-Tests fuer UUID, absolute Pfade, float-string, hex-color, suffix-format
|
||||
- Status: abgeschlossen am April 10, 2026
|
||||
2. `B04-b` Node registry invariants
|
||||
- Ziel: defaults/fields/module_key/input-output-contracts als Registry-Invarianten pruefen
|
||||
- Scope: `test_workflow_node_registry.py`
|
||||
- Gate: registryweite Invariant-Tests gruen
|
||||
- Status: abgeschlossen am April 10, 2026
|
||||
3. `B06` Shared authoring surface
|
||||
- Ziel: gemeinsame Authoring-Schicht fuer Canvas-Menu, Sidebar und Starter-Aktionen
|
||||
- Why now: verhindert doppelte UI-Logik in `NodeCommandMenu` und `NodeDefinitionsPanel`
|
||||
- Status: abgeschlossen am April 10, 2026
|
||||
4. `B05` Family-scoped node organization
|
||||
- Ziel: modul-/family-basierte Node-Organisation auf der gemeinsamen Authoring-Schicht
|
||||
- Status: abgeschlossen am April 10, 2026
|
||||
5. `B07` Canvas ergonomics closure
|
||||
- Ziel: reduzierte Top-Area, konsistente Edge-/Insert-Interaktionen, Auto-Align sauber abschliessen
|
||||
6. `B08` Starter graph and module bundle normalization
|
||||
- Ziel: Blueprints, Bundles und New-Workflow-Einstieg auf dieselben kanonischen Pfade ziehen
|
||||
7. `B09` Template-aware runtime unification
|
||||
- Ziel: Graph und Legacy durch dieselbe Template-/Output-Orchestrierung fuehren
|
||||
8. `B10` Non-legacy still smoke closure
|
||||
- Ziel: kanonischer Still-Graph als wiederholbarer Smoke-Pfad mit klarer Fehlerflaeche
|
||||
9. `B11` Template parity matrix
|
||||
- Ziel: echte Graph-vs-Legacy-Vergleiche mit Render-Templates, Varianten und Alpha/Samples
|
||||
10. `B12` CAD intake moduleization
|
||||
- Ziel: CAD-Import/Extract/Export/BBox als echte Production-Module im Editor und in der Runtime
|
||||
11. `B13` Rollout and fallback controls
|
||||
- Ziel: Graph/Shadow/Legacy pro Workflow und Output-Type operativ steuerbar halten
|
||||
12. `B14` Sequential E2E gates
|
||||
- Ziel: Low-RAM Golden-/Smoke-/Browser-Gates fuer `/workflows`
|
||||
13. `B15` Repo hygiene root-cause closure
|
||||
- Ziel: generated artifacts, root-owned caches und compose side effects ursachenseitig schliessen
|
||||
- Parallel vorbereitbar zu `B09` bis `B14`
|
||||
|
||||
### Queue Q2: Parallel Preparation Tracks
|
||||
|
||||
- Track A: Backend contracts
|
||||
- aktiv: `B04-a`, danach `B04-b`
|
||||
- Merge-Blocker fuer fast alle Folgearbeiten
|
||||
- Track B: Frontend authoring refactor
|
||||
- Vorbereitung jetzt, Merge erst nach `B04`
|
||||
- Reihenfolge laut Analyse: `B06` -> `B05` -> `B07` -> `B08`
|
||||
- Track C: Runtime and parity
|
||||
- Investigation parallel moeglich
|
||||
- Merge-Reihenfolge: `B09` -> `B10` -> `B11` -> `B12` -> `B13` -> `B14`
|
||||
- Track D: Hygiene
|
||||
- Root-cause Sammlung und Script-Haertung parallel
|
||||
- Merge spaet, solange keine produktionskritische Blockade sichtbar wird
|
||||
|
||||
### Queue Q2: Immediate Start
|
||||
|
||||
- Aktiver Implementierungsblock: `B07`
|
||||
- Bereits abgeschlossene Merge-Slices in dieser Queue:
|
||||
- `B04-a`
|
||||
- `B04-b`
|
||||
- `B06`
|
||||
- `B05`
|
||||
- Vorbereitete Folgeblöcke:
|
||||
- `B07`
|
||||
- `B08`
|
||||
Reference in New Issue
Block a user