185 lines
6.4 KiB
Markdown
185 lines
6.4 KiB
Markdown
# govoplan-workflow Concept
|
|
|
|
## Purpose
|
|
|
|
`govoplan-workflow` is the process orchestration module. It turns a configured
|
|
administrative procedure into state transitions, guards, commands, timers, and
|
|
operator-visible progress.
|
|
|
|
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
|
|
|
|
The module 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 and WebUI route contributions
|
|
|
|
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 implementation should provide:
|
|
|
|
- static workflow definition registration from configuration packages
|
|
- create/read/list workflow instances
|
|
- transition execution with permission checks
|
|
- guard hooks implemented through capability calls
|
|
- command execution records with retry/manual-resolution state
|
|
- action/effect previews for transitions that call other modules
|
|
- idempotency keys for command execution
|
|
- explicit blocked, retryable, quarantined, manual-required, and
|
|
compensation-required states
|
|
- basic WebUI instance detail and definition viewer
|
|
- 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
|
|
|
|
Candidate tables:
|
|
|
|
- `workflow_definitions`
|
|
- `workflow_definition_versions`
|
|
- `workflow_instances`
|
|
- `workflow_transition_history`
|
|
- `workflow_command_records`
|
|
- `workflow_timers`
|
|
|
|
Definitions should be immutable by version after activation. Instances should
|
|
reference the exact version used at start.
|
|
|
|
## WebUI
|
|
|
|
Initial route contributions:
|
|
|
|
- `/workflow`
|
|
- `/workflow/instances/:instanceId`
|
|
- `/workflow/definitions/:definitionId`
|
|
|
|
The UI should show current state, available transitions, pending commands,
|
|
failed handoffs, audit trace, and linked subject records. It should not import
|
|
case/task/template components directly; panels are contributed through core UI
|
|
extension points.
|
|
|
|
## 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 to implement BPMN import later or keep a GovOPlaN-native JSON model.
|
|
- How much visual workflow editing belongs in the first WebUI.
|
|
- Whether long-running timers use Celery beat, a module scheduler, or an ops
|
|
scheduler abstraction.
|
|
- How workflow variables are redacted and retained.
|