docs: add workflow migration plan and checkpoint current state

2026-04-07 08:38:16 +02:00
parent 2a00abe91f
commit bc9ab5f864
5 changed files with 322 additions and 15 deletions
@@ -0,0 +1,108 @@
+# 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.
+
+## 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.
+
+## 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.
+
+### 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.
+
+### 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.