chore: sync GovOPlaN module split state
This commit is contained in:
184
docs/CONCEPT.md
Normal file
184
docs/CONCEPT.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user