300 lines
12 KiB
Python
300 lines
12 KiB
Python
from __future__ import annotations
|
|
|
|
from pathlib import Path
|
|
|
|
from govoplan_core.core.files import CAPABILITY_FILES_ARTIFACT_STORE
|
|
from govoplan_core.core.module_guards import (
|
|
drop_table_retirement_provider,
|
|
persistent_table_uninstall_guard,
|
|
)
|
|
from govoplan_core.core.modules import (
|
|
DocumentationTopic,
|
|
FrontendModule,
|
|
FrontendRoute,
|
|
MigrationSpec,
|
|
ModuleContext,
|
|
ModuleInterfaceProvider,
|
|
ModuleInterfaceRequirement,
|
|
ModuleManifest,
|
|
NavItem,
|
|
PermissionDefinition,
|
|
RoleTemplate,
|
|
)
|
|
from govoplan_core.core.provider_governance import declared_module_architecture
|
|
from govoplan_core.core.templates import (
|
|
CAPABILITY_TEMPLATE_CATALOG,
|
|
CAPABILITY_TEMPLATE_RENDERER,
|
|
)
|
|
from govoplan_core.core.views import ViewSurface
|
|
from govoplan_core.db.base import Base
|
|
from govoplan_templates.backend.db import models as template_models
|
|
|
|
|
|
MODULE_ID = "templates"
|
|
MODULE_NAME = "Templates"
|
|
MODULE_VERSION = "0.1.16"
|
|
|
|
READ_SCOPE = "templates:template:read"
|
|
WRITE_SCOPE = "templates:template:write"
|
|
PUBLISH_SCOPE = "templates:template:publish"
|
|
RENDER_SCOPE = "templates:template:render"
|
|
ADMIN_SCOPE = "templates:template:admin"
|
|
|
|
|
|
def _permission(scope: str, label: str, description: str) -> PermissionDefinition:
|
|
module_id, resource, action = scope.split(":", 2)
|
|
return PermissionDefinition(
|
|
scope=scope,
|
|
label=label,
|
|
description=description,
|
|
category=MODULE_NAME,
|
|
level="tenant",
|
|
module_id=module_id,
|
|
resource=resource,
|
|
action=action,
|
|
)
|
|
|
|
|
|
PERMISSIONS = (
|
|
_permission(READ_SCOPE, "View templates", "Read template definitions, revisions, and render evidence."),
|
|
_permission(WRITE_SCOPE, "Manage templates", "Create and revise reusable templates."),
|
|
_permission(PUBLISH_SCOPE, "Publish templates", "Publish immutable template revisions for final output."),
|
|
_permission(RENDER_SCOPE, "Render templates", "Preview and render governed output from supplied snapshots."),
|
|
_permission(ADMIN_SCOPE, "Administer templates", "Manage all tenant, group, and user templates."),
|
|
)
|
|
|
|
ROLE_TEMPLATES = (
|
|
RoleTemplate(
|
|
slug="template_manager",
|
|
name="Template manager",
|
|
description="Create, publish, and render reusable typed templates.",
|
|
permissions=(READ_SCOPE, WRITE_SCOPE, PUBLISH_SCOPE, RENDER_SCOPE),
|
|
),
|
|
)
|
|
|
|
DOCUMENTATION = (
|
|
DocumentationTopic(
|
|
id="templates.library",
|
|
title="Template library",
|
|
summary="Create versioned templates with explicit usages and required data fields.",
|
|
body=(
|
|
"Templates are reusable, scoped definitions. Every edit creates an immutable revision. "
|
|
"Publish the revision that consumers may use for final output. A compatibility check explains "
|
|
"missing fields, unsupported usages, and unavailable output formats before rendering."
|
|
),
|
|
layer="available",
|
|
documentation_types=("admin", "user"),
|
|
audience=("operator", "module_admin", "product_owner"),
|
|
metadata={
|
|
"seed": True,
|
|
"help_contexts": [
|
|
"templates.page",
|
|
"templates.library",
|
|
"templates.editor",
|
|
"templates.state.read-only",
|
|
],
|
|
},
|
|
),
|
|
DocumentationTopic(
|
|
id="templates.printable-output",
|
|
title="Printable template output",
|
|
summary="Render labels, envelopes, letters, and list layouts from frozen input snapshots.",
|
|
body=(
|
|
"Preview output may use a draft revision. Final output requires a published revision and an "
|
|
"idempotency key. Results pin the template hash, input hash, renderer version, item/page counts, "
|
|
"diagnostics, and output digest. Files stores artifacts when available and authorized; otherwise "
|
|
"Templates provides a bounded download. Browser printing is the supported baseline output path."
|
|
),
|
|
layer="available",
|
|
documentation_types=("admin", "user"),
|
|
audience=("operator", "module_admin", "product_owner"),
|
|
related_modules=("files", "dist_lists", "campaigns", "audit"),
|
|
metadata={
|
|
"seed": True,
|
|
"help_contexts": [
|
|
"templates.preview",
|
|
"templates.action.validate-preview",
|
|
"templates.action.render-final",
|
|
"templates.evidence.render",
|
|
],
|
|
},
|
|
),
|
|
DocumentationTopic(
|
|
id="templates.reference.fields-and-consequences",
|
|
title="Template fields and lifecycle consequences",
|
|
summary="Scope, usage, data contract, publication, rendering, and deletion semantics for reusable Templates.",
|
|
body=(
|
|
"Visibility determines which tenant, group, or user scope may discover the Template; inherited Templates may be read-only. "
|
|
"Usages are capability contexts that constrain where a Template may be selected. Required fields form the compatibility "
|
|
"contract checked against supplied data before rendering. Saving creates a new immutable revision. Publishing marks one "
|
|
"revision as available for final output without rewriting older revisions or evidence. Preview validates and renders bounded "
|
|
"sample output; final rendering requires the published revision and records template, input, and output hashes plus renderer "
|
|
"evidence. Files may retain the artifact when its optional capability is available. Deletion removes the Template from future "
|
|
"selection but does not rewrite retained render evidence."
|
|
),
|
|
layer="available",
|
|
documentation_types=("admin", "user"),
|
|
audience=("operator", "module_admin", "product_owner"),
|
|
related_modules=("files", "dist_lists", "campaigns", "audit", "policy"),
|
|
metadata={
|
|
"seed": True,
|
|
"help_contexts": [
|
|
"templates.field.type",
|
|
"templates.field.locale",
|
|
"templates.field.visibility",
|
|
"templates.field.usages",
|
|
"templates.field.required-data",
|
|
"templates.action.publish",
|
|
"templates.action.delete",
|
|
],
|
|
"consequence_classes": {
|
|
"save_revision": "Creates a new immutable Template revision.",
|
|
"publish_revision": "Makes the selected immutable revision eligible for final consumer output.",
|
|
"render_final": "Creates retained render evidence and may persist an artifact through Files.",
|
|
"delete_template": "Prevents future selection without rewriting retained revisions or render evidence.",
|
|
},
|
|
},
|
|
),
|
|
)
|
|
|
|
|
|
def _router(_context: ModuleContext):
|
|
from govoplan_templates.backend.router import router
|
|
|
|
return router
|
|
|
|
|
|
def _catalog(context: ModuleContext):
|
|
from govoplan_templates.backend.capabilities import catalog_capability
|
|
|
|
return catalog_capability(context)
|
|
|
|
|
|
def _renderer(context: ModuleContext):
|
|
from govoplan_templates.backend.capabilities import renderer_capability
|
|
|
|
return renderer_capability(context)
|
|
|
|
|
|
def _tenant_summary(session, tenant_id: str) -> dict[str, int]:
|
|
return {
|
|
"templates": session.query(template_models.TemplateDefinition).filter(
|
|
template_models.TemplateDefinition.tenant_id == tenant_id,
|
|
template_models.TemplateDefinition.deleted_at.is_(None),
|
|
).count(),
|
|
"template_renders": session.query(template_models.TemplateRender).filter(
|
|
template_models.TemplateRender.tenant_id == tenant_id,
|
|
).count(),
|
|
}
|
|
|
|
|
|
manifest = ModuleManifest(
|
|
id=MODULE_ID,
|
|
name=MODULE_NAME,
|
|
version=MODULE_VERSION,
|
|
dependencies=(),
|
|
optional_dependencies=("files", "dist_lists", "campaigns", "audit"),
|
|
optional_capabilities=(CAPABILITY_FILES_ARTIFACT_STORE,),
|
|
provides_interfaces=(
|
|
ModuleInterfaceProvider(name=CAPABILITY_TEMPLATE_CATALOG, version=MODULE_VERSION),
|
|
ModuleInterfaceProvider(name=CAPABILITY_TEMPLATE_RENDERER, version=MODULE_VERSION),
|
|
),
|
|
requires_interfaces=(
|
|
ModuleInterfaceRequirement(
|
|
name=CAPABILITY_FILES_ARTIFACT_STORE,
|
|
version_min="0.1.14",
|
|
version_max_exclusive="0.2.0",
|
|
optional=True,
|
|
),
|
|
),
|
|
permissions=PERMISSIONS,
|
|
role_templates=ROLE_TEMPLATES,
|
|
nav_items=(
|
|
NavItem(
|
|
path="/templates",
|
|
label=MODULE_NAME,
|
|
icon="layout-template",
|
|
required_any=(READ_SCOPE, WRITE_SCOPE, PUBLISH_SCOPE, RENDER_SCOPE, ADMIN_SCOPE),
|
|
order=75,
|
|
),
|
|
),
|
|
frontend=FrontendModule(
|
|
module_id=MODULE_ID,
|
|
package_name="@govoplan/templates-webui",
|
|
routes=(
|
|
FrontendRoute(
|
|
path="/templates",
|
|
component="TemplatesPage",
|
|
required_any=(READ_SCOPE, WRITE_SCOPE, PUBLISH_SCOPE, RENDER_SCOPE, ADMIN_SCOPE),
|
|
order=75,
|
|
),
|
|
),
|
|
nav_items=(
|
|
NavItem(
|
|
path="/templates",
|
|
label=MODULE_NAME,
|
|
icon="layout-template",
|
|
required_any=(READ_SCOPE, WRITE_SCOPE, PUBLISH_SCOPE, RENDER_SCOPE, ADMIN_SCOPE),
|
|
order=75,
|
|
),
|
|
),
|
|
view_surfaces=(
|
|
ViewSurface(id="templates.page", module_id=MODULE_ID, kind="route", label="Templates", order=75),
|
|
ViewSurface(id="templates.library", module_id=MODULE_ID, kind="section", label="Template library", order=10),
|
|
ViewSurface(id="templates.editor", module_id=MODULE_ID, kind="section", label="Template editor", order=20),
|
|
ViewSurface(id="templates.preview", module_id=MODULE_ID, kind="section", label="Template preview and output", order=30),
|
|
),
|
|
),
|
|
route_factory=_router,
|
|
capability_factories={
|
|
CAPABILITY_TEMPLATE_CATALOG: _catalog,
|
|
CAPABILITY_TEMPLATE_RENDERER: _renderer,
|
|
},
|
|
tenant_summary_providers=(_tenant_summary,),
|
|
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(
|
|
template_models.TemplateRender,
|
|
template_models.TemplateRevision,
|
|
template_models.TemplateDefinition,
|
|
label=MODULE_NAME,
|
|
),
|
|
retirement_notes=(
|
|
"Destructive retirement removes template definitions, immutable revisions, bounded outputs, "
|
|
"and render evidence after the installer captures a database snapshot."
|
|
),
|
|
),
|
|
uninstall_guard_providers=(
|
|
persistent_table_uninstall_guard(
|
|
template_models.TemplateDefinition,
|
|
template_models.TemplateRevision,
|
|
template_models.TemplateRender,
|
|
label=MODULE_NAME,
|
|
),
|
|
),
|
|
documentation=DOCUMENTATION,
|
|
architecture=declared_module_architecture(
|
|
layer="content_records_evidence",
|
|
kind="domain",
|
|
maturity="vertical_slice",
|
|
documentation_ref="docs/TEMPLATE_BOUNDARY.md",
|
|
test_ref="tests/test_templates.py",
|
|
known_limits=(
|
|
"The baseline emits safe deterministic HTML/text for browser or OS printing; PDF and printer delivery remain connector concerns.",
|
|
),
|
|
supported_authority_modes=("native_authoritative",),
|
|
owned_concepts=("template definition", "template revision", "template render evidence"),
|
|
non_owned_concepts=("recipient", "campaign", "file asset", "printer endpoint"),
|
|
recovery_docs=("docs/TEMPLATE_BOUNDARY.md",),
|
|
security_docs=("docs/TEMPLATE_BOUNDARY.md",),
|
|
operations_docs=("README.md",),
|
|
),
|
|
)
|
|
|
|
|
|
def get_manifest() -> ModuleManifest:
|
|
return manifest
|