Code revision

2026-07-07 09:38:39 +02:00
parent 9133103e82
commit f6f999a153
20 changed files with 2407 additions and 0 deletions
@@ -0,0 +1,192 @@
+# Workflow Engine -- Execution Model (Explanation)
+
+## Purpose
+
+This document explains how the workflow engine operates at runtime: -
+how steps are executed - how data flows between steps - how decisions
+determine the next step
+
+------------------------------------------------------------------------
+
+## High-Level Flow
+
+1.  User triggers a workflow (e.g., button)
+2.  Engine loads the workflow and its start step
+3.  Engine creates an empty context object
+4.  Steps are executed sequentially
+5.  Each step may branch to another step based on its result
+6.  Execution ends when no next step is defined
+
+------------------------------------------------------------------------
+
+## Core Components
+
+### 1. Workflow
+
+Defines: - name - start step
+
+### 2. Step
+
+Defines: - function to execute - input mapping - parameters - output key
+
+### 3. Function
+
+Implements the actual logic: - UI interaction (dialog, selection) -
+system action (call, camera, scan) - computation
+
+### 4. Transition
+
+Maps a result to the next step.
+
+### 5. Context
+
+Shared data store during execution.
+
+------------------------------------------------------------------------
+
+## Context Model
+
+The context is a key-value store:
+
+``` json
+{
+  "SelectedContact": "Peter",
+  "Answer": "YES"
+}
+```
+
+Rules: - Steps write results using `output_key` - Later steps read
+values via `input_mapping`
+
+------------------------------------------------------------------------
+
+## Step Execution Lifecycle
+
+For each step:
+
+1.  Resolve input values from context
+2.  Merge with static parameters
+3.  Call function
+4.  Receive result:
+    -   `value`
+    -   `result_code`
+5.  Store result in context
+6.  Determine next step via transitions
+
+------------------------------------------------------------------------
+
+## Result Handling
+
+A function returns:
+
+``` json
+{
+  "value": "...",
+  "result_code": "YES"
+}
+```
+
+The `result_code` is used for branching.
+
+Examples: - YES / NO - OK / CANCEL - PETER / NOT_PETER - ERROR
+
+------------------------------------------------------------------------
+
+## Transition Resolution
+
+Order: 1. Find transition with matching `result_code` 2. If none → use
+`is_default` 3. If none → end workflow
+
+------------------------------------------------------------------------
+
+## Example Walkthrough
+
+### Scenario: Call Workflow
+
+#### Step 1 -- Select Contact
+
+Result:
+
+``` json
+{
+  "value": "Peter",
+  "result_code": "PETER"
+}
+```
+
+→ Next step: Ask confirmation
+
+------------------------------------------------------------------------
+
+#### Step 2 -- Ask Confirmation
+
+User selects YES
+
+``` json
+{
+  "value": true,
+  "result_code": "YES"
+}
+```
+
+→ Next step: Call
+
+------------------------------------------------------------------------
+
+#### Step 3 -- Call Contact
+
+Uses:
+
+``` json
+SelectedContact = "Peter"
+```
+
+→ Executes call → End
+
+------------------------------------------------------------------------
+
+## Error Handling
+
+If a function fails: - return `result_code = ERROR` - transition can
+handle it - or workflow stops
+
+Optional: - retry step - fallback step - log error
+
+------------------------------------------------------------------------
+
+## Persistence (Optional)
+
+During execution: - store workflow_runs - store workflow_run_steps
+
+Benefits: - debugging - history - resume execution
+
+------------------------------------------------------------------------
+
+## Design Principles
+
+-   Data-driven (no hardcoded flows)
+-   Extensible (new functions)
+-   Reusable (functions used in multiple workflows)
+-   UI-independent (engine separated from UI)
+
+------------------------------------------------------------------------
+
+## Summary
+
+Execution is a loop:
+
+``` text
+Step → Function → Result → Transition → Next Step
+```
+
+Data flows via:
+
+``` text
+Context (key-value store)
+```
+
+Control flow is defined by:
+
+``` text
+Transitions (result_code → next step)
+```