137 lines
6.5 KiB
Markdown
137 lines
6.5 KiB
Markdown
# Workflow Migration Plan
|
|
|
|
## Goal
|
|
|
|
Bring `/workflows` to full production parity with the existing legacy render pipeline without breaking the current legacy path at any time.
|
|
|
|
## Current Status
|
|
|
|
- Phase 1 completed on canonical config storage, preset migration, and legacy-safe runtime extraction.
|
|
- Phase 2 completed on backend node registry, node definitions API, and schema-driven editor palette/settings.
|
|
- Phase 3 completed: `order_line_setup`, `resolve_template`, `material_map_resolve`, `auto_populate_materials`, `glb_bbox`, `output_save`, and `notify` are extracted behind the legacy task boundary, validated with targeted backend tests, and covered by workflow executor dispatch tests.
|
|
- Phase 4 is partially completed: graph runtime dispatch now treats downstream `output_save` as the authoritative persistence boundary for still renders, turntable/video renders, and `.blend` exports, updates node results after persistence, and keeps shadow executions non-authoritative.
|
|
- The canonical still bridge path now exposes runtime-backed node settings for template overrides, material resolution, auto-population rules, GLB source selection, output-save artifact filtering, and notify arming, so `/workflows` can author the real still-render contract instead of relying on hidden legacy defaults.
|
|
- Output types now behave as explicit invocation profiles in both API and admin UI: workflow family, artifact kind, and invocation overrides are first-class, and linked workflow compatibility is enforced before dispatch.
|
|
- Canonical reference workflows now need to be managed as at least two families, not one mixed graph:
|
|
- `CAD Intake`
|
|
- `Order Rendering`
|
|
|
|
## Non-Negotiables
|
|
|
|
- The legacy render path remains operational throughout the migration.
|
|
- No existing output type or order flow may regress while the graph engine is introduced.
|
|
- Every node exposed in the workflow editor must have a backend-owned definition and a validated settings schema.
|
|
- New workflow definitions use one canonical JSON format.
|
|
|
|
## Canonical Workflow Model
|
|
|
|
```json
|
|
{
|
|
"version": 1,
|
|
"nodes": [
|
|
{
|
|
"id": "resolve_template",
|
|
"step": "resolve_template",
|
|
"params": {},
|
|
"ui": {
|
|
"type": "templateNode",
|
|
"position": { "x": 420, "y": 120 },
|
|
"label": "Resolve Template"
|
|
}
|
|
}
|
|
],
|
|
"edges": [
|
|
{ "from": "setup", "to": "resolve_template" }
|
|
]
|
|
}
|
|
```
|
|
|
|
Notes:
|
|
|
|
- `step` and `params` are the backend-owned runtime model.
|
|
- `ui` is editor-only metadata and must not change runtime semantics.
|
|
- `edges` are mandatory for graph persistence and validation.
|
|
|
|
## Architecture Direction
|
|
|
|
- Workflow nodes are orchestration wrappers, not the canonical implementation unit.
|
|
- The canonical implementation unit is a backend-owned production module with typed inputs, outputs, defaults, and execution semantics.
|
|
- Workflow definitions answer "what runs"; output types answer "which productized invocation profile of that workflow is offered".
|
|
- Workflow authoring remains split by family:
|
|
- `cad_file`
|
|
- `order_line`
|
|
- The detailed target model is captured in [`docs/workflows/NODE_BASED_PRODUCTION_ARCHITECTURE.md`](/home/hartmut/Documents/Copilot/schaefflerautomat/docs/workflows/NODE_BASED_PRODUCTION_ARCHITECTURE.md).
|
|
|
|
## Phases
|
|
|
|
### Phase 1: Canonical Model and Migration Base
|
|
|
|
- Finalize canonical workflow schema.
|
|
- Align frontend API types with backend schema.
|
|
- Add compatibility migration from preset configs to canonical DAG configs.
|
|
- Keep legacy dispatch as default.
|
|
|
|
### Phase 2: Node Registry
|
|
|
|
- Introduce a backend node registry as the single source of truth.
|
|
- Define labels, categories, descriptions, settings schemas, defaults, input contracts, and output contracts for every node.
|
|
- Expose node definitions over API for the editor.
|
|
|
|
### Phase 3: Extract Missing Legacy Steps
|
|
|
|
- Move inline legacy pipeline logic into explicit node executors/services.
|
|
- Required parity nodes:
|
|
- `order_line_setup`
|
|
- `resolve_template`
|
|
- `material_map_resolve`
|
|
- `auto_populate_materials`
|
|
- `glb_bbox`
|
|
- `output_save`
|
|
- `notify`
|
|
- Optional but planned:
|
|
- `threejs_render`
|
|
|
|
### Phase 4: Graph Runtime
|
|
|
|
- Introduce `WorkflowContext` and node-by-node execution with persistent run state.
|
|
- Support node outputs and artifact handoff across edges.
|
|
- Keep `legacy`, `graph`, and `shadow` execution modes.
|
|
- Current slice: graph dispatch executes extracted bridge nodes for order-line setup, template/material resolution, auto-material population, and bounding-box resolution before queueing render/export tasks.
|
|
- Current slice completed: still-render graphs, turntable/video graphs, and `.blend` export graphs with downstream `output_save` now disable task-level self-publish, persist authoritative output/media metadata through shared runtime services, and write the result back into `WorkflowNodeResult`.
|
|
- Next Phase 4 slice: extend the same authoritative `output_save` contract to any remaining legacy export variants and close the remaining notify/editor parity gaps.
|
|
|
|
### Phase 5: Workflow Editor Parity
|
|
|
|
- Persist and load `nodes`, `edges`, `step`, `params`, and `ui`.
|
|
- Render all node settings dynamically from backend schemas.
|
|
- Add validation, dry-run, dispatch, and run inspection.
|
|
- Organize workflows and node palette by family so the editor reflects the runtime split between `cad_file` and `order_line` contexts.
|
|
- Current state: right-click insertion, searchable family-aware palettes, auto-align, edge deletion, dry-run, dispatch, and run inspection are already in place; the remaining work is authoring clarity, node organization, and browser-verified end-to-end usability for the non-legacy still graph.
|
|
- Do not add further editor-only UX surface before node/module contracts and output-type invocation profiles are stabilized.
|
|
|
|
### Phase 6: Shadow Mode and Rollout
|
|
|
|
- Run graph executions in parallel to the legacy flow for parity comparison.
|
|
- Compare status, outputs, media assets, notifications, and logs.
|
|
- Roll out per workflow or output type.
|
|
|
|
## Execution Modes
|
|
|
|
- `legacy`: current production path only
|
|
- `graph`: graph runtime is authoritative
|
|
- `shadow`: legacy remains authoritative, graph runs for comparison and observability
|
|
|
|
## Deliverables
|
|
|
|
- Canonical workflow schema and migration tooling
|
|
- Backend node registry and API
|
|
- Full editor support for all node settings
|
|
- Graph runtime with node-level execution and tracking
|
|
- Shadow mode parity checks
|
|
|
|
## Exit Criteria
|
|
|
|
- A workflow can be authored, validated, executed, and inspected entirely via `/workflows`.
|
|
- Legacy results and graph results match for defined golden cases.
|
|
- Legacy fallback is still available after graph rollout.
|