Implement generic approval runtime
This commit is contained in:
@@ -1,21 +1,45 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from govoplan_core.core.access import CAPABILITY_AUTH_PERMISSION_EVALUATOR, CAPABILITY_AUTH_PRINCIPAL_RESOLVER
|
||||
from govoplan_core.core.modules import DocumentationLink, DocumentationTopic, ModuleManifest, PermissionDefinition, RoleTemplate
|
||||
from pathlib import Path
|
||||
|
||||
from govoplan_core.core.access import (
|
||||
CAPABILITY_AUTH_PERMISSION_EVALUATOR,
|
||||
CAPABILITY_AUTH_PRINCIPAL_RESOLVER,
|
||||
)
|
||||
from govoplan_core.core.approvals import CAPABILITY_APPROVAL_REQUESTS
|
||||
from govoplan_core.core.module_guards import (
|
||||
drop_table_retirement_provider,
|
||||
persistent_table_uninstall_guard,
|
||||
)
|
||||
from govoplan_core.core.modules import (
|
||||
CapabilityDocumentation,
|
||||
DocumentationLink,
|
||||
DocumentationTopic,
|
||||
FrontendModule,
|
||||
FrontendRoute,
|
||||
MigrationSpec,
|
||||
ModuleContext,
|
||||
ModuleInterfaceProvider,
|
||||
ModuleManifest,
|
||||
NavItem,
|
||||
PermissionDefinition,
|
||||
RoleTemplate,
|
||||
)
|
||||
from govoplan_core.core.provider_governance import declared_module_architecture
|
||||
from govoplan_core.core.views import ViewSurface
|
||||
from govoplan_core.db.base import Base
|
||||
from govoplan_approvals.backend.db import models as approval_models
|
||||
from govoplan_approvals.backend.service import SqlApprovalRequests
|
||||
|
||||
|
||||
MODULE_ID = "approvals"
|
||||
MODULE_NAME = "Approvals"
|
||||
MODULE_VERSION = "0.1.8"
|
||||
MODULE_VERSION = "0.1.14"
|
||||
READ_SCOPE = "approvals:workspace:read"
|
||||
WRITE_SCOPE = "approvals:workspace:write"
|
||||
DECIDE_SCOPE = "approvals:workspace:decide"
|
||||
ADMIN_SCOPE = "approvals:workspace:admin"
|
||||
OPTIONAL_DEPENDENCIES = (
|
||||
"workflow_engine",
|
||||
"audit",
|
||||
"files",
|
||||
"notifications",
|
||||
)
|
||||
OPTIONAL_DEPENDENCIES = ("workflow_engine", "audit", "files", "notifications", "policy")
|
||||
|
||||
|
||||
def _permission(scope: str, label: str, description: str) -> PermissionDefinition:
|
||||
@@ -24,7 +48,7 @@ def _permission(scope: str, label: str, description: str) -> PermissionDefinitio
|
||||
scope=scope,
|
||||
label=label,
|
||||
description=description,
|
||||
category="Approvals",
|
||||
category=MODULE_NAME,
|
||||
level="tenant",
|
||||
module_id=module_id,
|
||||
resource=resource,
|
||||
@@ -32,56 +56,28 @@ def _permission(scope: str, label: str, description: str) -> PermissionDefinitio
|
||||
)
|
||||
|
||||
|
||||
PERMISSIONS = (
|
||||
_permission(READ_SCOPE, "View approvals workspace", "Read approvals records, configuration, and workflow context."),
|
||||
_permission(WRITE_SCOPE, "Manage approvals workspace", "Create and update approvals records and workflow state."),
|
||||
_permission(ADMIN_SCOPE, "Administer approvals workspace", "Configure approvals policies, templates, and tenant-level administration."),
|
||||
)
|
||||
def _router(_context: ModuleContext):
|
||||
from govoplan_approvals.backend.router import router
|
||||
|
||||
ROLE_TEMPLATES = (
|
||||
RoleTemplate(
|
||||
slug="approvals_manager",
|
||||
name="Approvals manager",
|
||||
description="Manage approvals records and workflow state.",
|
||||
permissions=(READ_SCOPE, WRITE_SCOPE),
|
||||
),
|
||||
RoleTemplate(
|
||||
slug="approvals_viewer",
|
||||
name="Approvals viewer",
|
||||
description="Read approvals records and workflow context.",
|
||||
permissions=(READ_SCOPE,),
|
||||
),
|
||||
)
|
||||
return router
|
||||
|
||||
|
||||
def _requests(_context: ModuleContext) -> SqlApprovalRequests:
|
||||
return SqlApprovalRequests()
|
||||
|
||||
|
||||
def _tenant_summary(session, tenant_id: str) -> dict[str, int]:
|
||||
current = session.query(approval_models.ApprovalRequestRevision).filter(
|
||||
approval_models.ApprovalRequestRevision.tenant_id == tenant_id,
|
||||
approval_models.ApprovalRequestRevision.superseded_at.is_(None),
|
||||
)
|
||||
return {
|
||||
"approval_requests": current.count(),
|
||||
"approval_pending": current.filter(
|
||||
approval_models.ApprovalRequestRevision.state.in_(("pending", "escalated"))
|
||||
).count(),
|
||||
}
|
||||
|
||||
DOCUMENTATION = (
|
||||
DocumentationTopic(
|
||||
id=f"{MODULE_ID}.module-boundary",
|
||||
title=f"{MODULE_NAME} module boundary",
|
||||
summary="Generic approval and sign-off chains with delegation, substitution, four-eyes principle, escalation, and signatures.",
|
||||
body=(
|
||||
"This repository is currently a platform module seed. It registers the domain boundary, "
|
||||
"permission surface, role templates, and documentation metadata before runtime APIs, "
|
||||
"database models, migrations, and WebUI routes are introduced."
|
||||
),
|
||||
layer="available",
|
||||
documentation_types=("admin", "user"),
|
||||
audience=("user", "operator", "module_admin", "product_owner"),
|
||||
order=100,
|
||||
related_modules=OPTIONAL_DEPENDENCIES,
|
||||
links=(
|
||||
DocumentationLink(
|
||||
label="Repository domain boundary",
|
||||
href="govoplan-approvals/docs/APPROVALS_DOMAIN_BOUNDARY.md",
|
||||
kind="repository",
|
||||
),
|
||||
),
|
||||
metadata={
|
||||
"seed": True,
|
||||
"domain_objects": ['approval requests', 'sign-off chains', 'delegation and substitution facts', 'four-eyes constraints', 'escalation state', 'signature references'],
|
||||
"first_slice": "Define reusable approval request, step, actor, delegation, substitution, and decision result contracts for consuming modules.",
|
||||
},
|
||||
),
|
||||
)
|
||||
|
||||
manifest = ModuleManifest(
|
||||
id=MODULE_ID,
|
||||
@@ -89,18 +85,184 @@ manifest = ModuleManifest(
|
||||
version=MODULE_VERSION,
|
||||
dependencies=("access",),
|
||||
optional_dependencies=OPTIONAL_DEPENDENCIES,
|
||||
required_capabilities=(CAPABILITY_AUTH_PRINCIPAL_RESOLVER, CAPABILITY_AUTH_PERMISSION_EVALUATOR),
|
||||
permissions=PERMISSIONS,
|
||||
role_templates=ROLE_TEMPLATES,
|
||||
documentation=DOCUMENTATION,
|
||||
required_capabilities=(
|
||||
CAPABILITY_AUTH_PRINCIPAL_RESOLVER,
|
||||
CAPABILITY_AUTH_PERMISSION_EVALUATOR,
|
||||
),
|
||||
provides_interfaces=(
|
||||
ModuleInterfaceProvider(name=CAPABILITY_APPROVAL_REQUESTS, version="0.1.0"),
|
||||
),
|
||||
permissions=(
|
||||
_permission(
|
||||
READ_SCOPE,
|
||||
"View approval requests",
|
||||
"Read approval chains, current gates, outcomes, and history.",
|
||||
),
|
||||
_permission(
|
||||
WRITE_SCOPE,
|
||||
"Request approvals",
|
||||
"Create immutable approval chains for exact subject revisions.",
|
||||
),
|
||||
_permission(
|
||||
DECIDE_SCOPE,
|
||||
"Decide approvals",
|
||||
"Approve or reject eligible approval steps.",
|
||||
),
|
||||
_permission(
|
||||
ADMIN_SCOPE,
|
||||
"Administer approvals",
|
||||
"Escalate due approvals and configure approval policies.",
|
||||
),
|
||||
),
|
||||
role_templates=(
|
||||
RoleTemplate(
|
||||
slug="approvals_manager",
|
||||
name="Approvals manager",
|
||||
description="Create and manage approval requests.",
|
||||
permissions=(READ_SCOPE, WRITE_SCOPE, DECIDE_SCOPE),
|
||||
),
|
||||
RoleTemplate(
|
||||
slug="approver",
|
||||
name="Approver",
|
||||
description="Read and decide eligible approval steps.",
|
||||
permissions=(READ_SCOPE, DECIDE_SCOPE),
|
||||
),
|
||||
RoleTemplate(
|
||||
slug="approvals_admin",
|
||||
name="Approvals administrator",
|
||||
description="Administer approval policies and escalation.",
|
||||
permissions=(READ_SCOPE, WRITE_SCOPE, DECIDE_SCOPE, ADMIN_SCOPE),
|
||||
),
|
||||
),
|
||||
route_factory=_router,
|
||||
nav_items=(
|
||||
NavItem(
|
||||
path="/approvals",
|
||||
label="Approvals",
|
||||
icon="list-checks",
|
||||
required_any=(READ_SCOPE,),
|
||||
order=37,
|
||||
),
|
||||
),
|
||||
frontend=FrontendModule(
|
||||
module_id=MODULE_ID,
|
||||
package_name="@govoplan/approvals-webui",
|
||||
routes=(
|
||||
FrontendRoute(
|
||||
path="/approvals",
|
||||
component="ApprovalsPage",
|
||||
required_any=(READ_SCOPE,),
|
||||
order=37,
|
||||
),
|
||||
),
|
||||
nav_items=(
|
||||
NavItem(
|
||||
path="/approvals",
|
||||
label="Approvals",
|
||||
icon="list-checks",
|
||||
required_any=(READ_SCOPE,),
|
||||
order=37,
|
||||
),
|
||||
),
|
||||
view_surfaces=(
|
||||
ViewSurface(
|
||||
id="approvals.navigation",
|
||||
module_id=MODULE_ID,
|
||||
kind="navigation",
|
||||
label="Approvals navigation",
|
||||
order=10,
|
||||
),
|
||||
ViewSurface(
|
||||
id="approvals.workspace",
|
||||
module_id=MODULE_ID,
|
||||
kind="route",
|
||||
label="Approval request workspace",
|
||||
order=20,
|
||||
),
|
||||
),
|
||||
),
|
||||
capability_factories={CAPABILITY_APPROVAL_REQUESTS: _requests},
|
||||
capability_documentation={
|
||||
CAPABILITY_APPROVAL_REQUESTS: CapabilityDocumentation(
|
||||
label="Governed approval requests",
|
||||
summary="Freezes exact subject approval chains and resolves auditable sequential decisions.",
|
||||
contract_version="0.1.0",
|
||||
)
|
||||
},
|
||||
migration_spec=MigrationSpec(
|
||||
module_id=MODULE_ID,
|
||||
metadata=Base.metadata,
|
||||
script_location=str(Path(__file__).with_name("migrations") / "versions"),
|
||||
retirement_supported=True,
|
||||
retirement_provider=drop_table_retirement_provider(
|
||||
approval_models.ApprovalReplay,
|
||||
approval_models.ApprovalLifecycleEvent,
|
||||
approval_models.ApprovalDecisionRecord,
|
||||
approval_models.ApprovalRequestRevision,
|
||||
approval_models.ApprovalTemplateRevision,
|
||||
label=MODULE_NAME,
|
||||
),
|
||||
retirement_notes="Destructive retirement requires a verified snapshot and removes approval chains, decisions, signature references, and lifecycle evidence.",
|
||||
),
|
||||
uninstall_guard_providers=(
|
||||
persistent_table_uninstall_guard(
|
||||
approval_models.ApprovalRequestRevision,
|
||||
approval_models.ApprovalDecisionRecord,
|
||||
approval_models.ApprovalLifecycleEvent,
|
||||
approval_models.ApprovalReplay,
|
||||
approval_models.ApprovalTemplateRevision,
|
||||
label=MODULE_NAME,
|
||||
),
|
||||
),
|
||||
tenant_summary_providers=(_tenant_summary,),
|
||||
documentation=(
|
||||
DocumentationTopic(
|
||||
id="approvals.module-boundary",
|
||||
title="Governed approval chains",
|
||||
summary="Create exact-subject approval chains with delegation, separation of duties, escalation, and signature evidence.",
|
||||
body=(
|
||||
"An Approval request freezes its subject revision, ordered steps, eligible selectors, quorum, rejection policy, signature requirement, and governance references. "
|
||||
"Decisions are append-only, tenant-bound, optimistic-concurrency protected, and replay safe. Consuming modules verify the exact subject through the capability rather than reading Approval tables."
|
||||
),
|
||||
layer="configured",
|
||||
documentation_types=("admin", "user"),
|
||||
audience=("user", "operator", "module_admin", "product_owner", "auditor"),
|
||||
related_modules=OPTIONAL_DEPENDENCIES,
|
||||
links=(
|
||||
DocumentationLink(
|
||||
label="Approvals boundary and recovery",
|
||||
href="govoplan-approvals/docs/APPROVALS_DOMAIN_BOUNDARY.md",
|
||||
kind="repository",
|
||||
),
|
||||
),
|
||||
),
|
||||
),
|
||||
architecture=declared_module_architecture(
|
||||
layer="human_work_procedure",
|
||||
kind="governance",
|
||||
maturity="scaffold",
|
||||
maturity="vertical_slice",
|
||||
documentation_ref="docs/APPROVALS_DOMAIN_BOUNDARY.md",
|
||||
known_limits=("Runtime approval lifecycles and persistence are not implemented yet.",),
|
||||
owned_concepts=("approval request", "approval chain", "approval decision"),
|
||||
non_owned_concepts=("workflow execution", "identity", "document signature"),
|
||||
test_ref="tests/test_approvals.py",
|
||||
known_limits=(
|
||||
"Policy-authored template selection and cryptographic signature providers remain optional product depth; signature references are evidence pointers, not a cryptographic claim.",
|
||||
),
|
||||
supported_authority_modes=("native_authoritative",),
|
||||
owned_concepts=(
|
||||
"approval request",
|
||||
"approval chain",
|
||||
"approval decision",
|
||||
"approval escalation",
|
||||
),
|
||||
non_owned_concepts=(
|
||||
"workflow execution",
|
||||
"identity",
|
||||
"document signature",
|
||||
"module business outcome",
|
||||
),
|
||||
migration_docs=("docs/APPROVALS_DOMAIN_BOUNDARY.md",),
|
||||
recovery_docs=("docs/APPROVALS_DOMAIN_BOUNDARY.md",),
|
||||
security_docs=("docs/APPROVALS_DOMAIN_BOUNDARY.md",),
|
||||
operations_docs=("docs/APPROVALS_DOMAIN_BOUNDARY.md",),
|
||||
),
|
||||
)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user