feat: extract headless workflow engine
This commit is contained in:
+201
@@ -0,0 +1,201 @@
|
||||
# govoplan-workflow Concept
|
||||
|
||||
## Purpose
|
||||
|
||||
`govoplan-workflow-engine` is the headless process orchestration module.
|
||||
`govoplan-workflow` is its optional authoring and inspection surface. See
|
||||
`ENGINE_EDITOR_SPLIT.md`.
|
||||
|
||||
Workflow does not own business records. A case, task, file, appointment,
|
||||
template, payment, or postbox message remains owned by its domain module.
|
||||
Workflow coordinates those modules through stable contracts.
|
||||
|
||||
Workflow is also the first home for GovOPlaN's action/effect automation layer.
|
||||
That layer must keep automated actions governed, previewable, idempotent,
|
||||
auditable, and recoverable. If action catalogues, schedules, rule execution, or
|
||||
cross-module automation grow beyond workflow ownership, the runner can later be
|
||||
split into a dedicated `govoplan-automation` module without changing the
|
||||
action/effect contracts.
|
||||
|
||||
## Ownership
|
||||
|
||||
Workflow Engine owns:
|
||||
|
||||
- workflow definitions and versions
|
||||
- workflow instances and current state
|
||||
- transitions, guards, and transition history
|
||||
- timers, deadlines, and wait states that belong to process execution
|
||||
- command plans and command execution records
|
||||
- retry/manual-intervention state for failed command handoffs
|
||||
- action/effect execution records for workflow-triggered automation
|
||||
- workflow audit/event emission
|
||||
- workflow diagram metadata
|
||||
|
||||
Workflow owns visual authoring, catalogue, comparison, activation, inspection,
|
||||
override, and reset surfaces. It owns no process tables or transition runtime.
|
||||
|
||||
The module does not own:
|
||||
|
||||
- case records and case evidence
|
||||
- task queues and task completion semantics
|
||||
- form schemas or submissions
|
||||
- file storage, documents, mail, notifications, appointments, payments, ledgers,
|
||||
or records
|
||||
- external protocol adapters
|
||||
|
||||
## Workflow Model
|
||||
|
||||
A workflow definition should contain:
|
||||
|
||||
- definition id, version, tenant scope, status
|
||||
- states with labels, categories, and terminal markers
|
||||
- transitions with from/to states, required scopes, guards, and commands
|
||||
- input/output data schema references
|
||||
- timers and escalation rules
|
||||
- extension metadata for diagrams and operator UI
|
||||
|
||||
Instances should contain:
|
||||
|
||||
- instance id, tenant id, definition id/version
|
||||
- subject references such as `case_id` or `submission_id`
|
||||
- current state and previous state
|
||||
- process variables with strict redaction rules
|
||||
- transition history
|
||||
- pending commands and manual actions
|
||||
|
||||
## Core Contracts
|
||||
|
||||
The module should integrate through:
|
||||
|
||||
- module manifest metadata, route factories, permissions, and migrations
|
||||
- events such as `workflow.instance_started`, `workflow.transitioned`,
|
||||
`workflow.command_requested`, `workflow.command_failed`, and
|
||||
`workflow.instance_completed`
|
||||
- commands such as `workflow.start`, `workflow.transition`,
|
||||
`workflow.retry_command`, and `workflow.cancel`
|
||||
- capability lookups for domain commands, for example cases, tasks, templates,
|
||||
appointments, and payments
|
||||
- configuration-package fragments that install workflow definitions
|
||||
|
||||
Command handoff must be explicit. A transition should record which module
|
||||
capability was requested, with input payload, result summary, and failure reason.
|
||||
|
||||
The shared action/effect doctrine lives in
|
||||
`govoplan-core/docs/ACTION_EFFECT_AUTOMATION_LAYER.md`.
|
||||
|
||||
## Reference Journey
|
||||
|
||||
Permit-to-payment MVP:
|
||||
|
||||
1. A form submission starts a workflow instance.
|
||||
2. Workflow commands cases to create a case.
|
||||
3. Workflow commands tasks to create an intake task.
|
||||
4. Completion of the task transitions the instance to appointment proposal.
|
||||
5. Appointment acceptance transitions to review/decision.
|
||||
6. Workflow commands templates to generate a permit or decision.
|
||||
7. Workflow commands payments/ledger handoff.
|
||||
8. Workflow closes the case and emits evidence events.
|
||||
|
||||
## MVP Slice
|
||||
|
||||
The first executable slice now provides:
|
||||
|
||||
- a versioned, workflow-specific graphical node library
|
||||
- shared Core graph DTO and validation primitives also consumed by Dataflow
|
||||
- workflow constraints that permit loops while requiring one trigger and one or
|
||||
more outcomes
|
||||
- trigger, activity, review, decision, wait, module-action, Dataflow, and outcome
|
||||
nodes
|
||||
- API discovery and validation endpoints
|
||||
- revision-pinned, idempotent Workflow instances
|
||||
- persisted steps and append-only transition evidence
|
||||
- durable Dataflow handoff, progress reconciliation, output references,
|
||||
retries, cancellation, and warning/review paths
|
||||
- manual activity, review, and wait handoffs with comments and evidence
|
||||
- a worker capability with current-authorization rechecks
|
||||
- an operator dialog for starting, inspecting, and advancing instances
|
||||
|
||||
The next execution slices should provide:
|
||||
|
||||
- static workflow definition registration from configuration packages
|
||||
- event, API, schedule, and parent-workflow start dispatchers
|
||||
- guard hooks implemented through capability calls
|
||||
- registry-driven generic module-action execution records
|
||||
- action/effect previews for transitions that call other modules
|
||||
- explicit blocked, retryable, quarantined, manual-required, and
|
||||
compensation-required states
|
||||
- dashboard summary provider
|
||||
- event emission and audit integration
|
||||
|
||||
## Permissions
|
||||
|
||||
Candidate scopes:
|
||||
|
||||
- `workflow:definition:read`
|
||||
- `workflow:definition:write`
|
||||
- `workflow:instance:read`
|
||||
- `workflow:instance:start`
|
||||
- `workflow:instance:transition`
|
||||
- `workflow:instance:admin`
|
||||
|
||||
State transitions may require both workflow scopes and domain-module permission
|
||||
checks for the command being executed.
|
||||
|
||||
Workflow guard evaluation should consume access semantics through kernel
|
||||
capabilities instead of importing access internals:
|
||||
|
||||
- `access.semanticDirectory` resolves identity, account, organization unit,
|
||||
function assignment, delegation, and role facts.
|
||||
- `access.explanation` records why a transition was allowed or denied in terms
|
||||
of identity/account/function/role/right provenance.
|
||||
|
||||
Transitions that allow a person to act in place of another function holder must
|
||||
require an explicit acting context and must record both the real actor account
|
||||
and the represented account/function assignment in transition history and audit
|
||||
details.
|
||||
|
||||
## Data Model Sketch
|
||||
|
||||
Current tables:
|
||||
|
||||
- `workflow_definitions`
|
||||
- `workflow_definition_revisions`
|
||||
- `workflow_instances`
|
||||
- `workflow_instance_steps`
|
||||
- `workflow_instance_events`
|
||||
|
||||
Future generic action execution and timers may add:
|
||||
|
||||
- `workflow_command_records`
|
||||
- `workflow_timers`
|
||||
|
||||
Definitions should be immutable by version after activation. Instances should
|
||||
reference the exact version used at start.
|
||||
|
||||
## WebUI
|
||||
|
||||
Current route contribution:
|
||||
|
||||
- `/workflow`
|
||||
|
||||
The route combines the definition editor and a fixed run dialog showing current
|
||||
state, available transitions, failed handoffs, comments/evidence, immutable
|
||||
event history, and linked Dataflow results. It does not import Dataflow or other
|
||||
domain UI components.
|
||||
|
||||
## Tests
|
||||
|
||||
Minimum tests:
|
||||
|
||||
- core starts with workflow installed but cases/tasks/templates absent
|
||||
- workflow definition versioning is immutable after activation
|
||||
- transition guard denial is recorded and visible
|
||||
- command failure is retryable and does not partially advance state
|
||||
- events are emitted for start/transition/completion
|
||||
- configuration package can install a simple workflow definition
|
||||
|
||||
## Open Decisions
|
||||
|
||||
- Whether long-running timers use Celery beat, a module scheduler, or an ops
|
||||
scheduler abstraction.
|
||||
- How workflow variables are redacted and retained.
|
||||
Reference in New Issue
Block a user