340 lines
15 KiB
Python
340 lines
15 KiB
Python
from __future__ import annotations
|
|
|
|
from govoplan_core.core.access import (
|
|
CAPABILITY_AUTH_PERMISSION_EVALUATOR,
|
|
CAPABILITY_AUTH_PRINCIPAL_RESOLVER,
|
|
)
|
|
from govoplan_core.core.modules import (
|
|
DocumentationCondition,
|
|
DocumentationLink,
|
|
DocumentationSourceDefinition,
|
|
DocumentationTopic,
|
|
FrontendModule,
|
|
FrontendRoute,
|
|
ModuleContext,
|
|
ModuleManifest,
|
|
NavItem,
|
|
PermissionDefinition,
|
|
RoleTemplate,
|
|
)
|
|
from govoplan_core.core.provider_governance import (
|
|
ModuleArchitectureDeclaration,
|
|
ModuleArchitectureDocumentation,
|
|
ModuleMaturityEvidence,
|
|
)
|
|
|
|
DOCS_READ_SCOPE = "docs:documentation:read"
|
|
DOCS_ADMIN_READ_SCOPE = "docs:documentation:admin"
|
|
DOCS_ADMIN_READ_SCOPES = (
|
|
DOCS_ADMIN_READ_SCOPE,
|
|
"system:settings:read",
|
|
"admin:settings:read",
|
|
)
|
|
DOCS_READ_SCOPES = (DOCS_READ_SCOPE, *DOCS_ADMIN_READ_SCOPES)
|
|
|
|
ARCHITECTURE = ModuleArchitectureDeclaration(
|
|
layer="governance_accountability",
|
|
kind="presentation",
|
|
maturity="vertical_slice",
|
|
evidence=(
|
|
ModuleMaturityEvidence(
|
|
kind="test",
|
|
reference="tests/test_docs_context.py",
|
|
summary="Tests audience-safe configured documentation and architecture projections.",
|
|
),
|
|
ModuleMaturityEvidence(
|
|
kind="documentation",
|
|
reference="docs/DOCUMENTATION_LAYER_CONCEPT.md",
|
|
summary="Defines the manifest-driven documentation boundary.",
|
|
),
|
|
),
|
|
known_limits=(
|
|
"Architecture declarations are in staged adoption, so undeclared modules remain visible as pending.",
|
|
),
|
|
owned_concepts=("configured documentation projection", "documentation audience filtering"),
|
|
non_owned_concepts=("module feature behavior", "module evidence generation"),
|
|
documentation=ModuleArchitectureDocumentation(
|
|
security=("docs/DOCUMENTATION_LAYER_CONCEPT.md",),
|
|
operations=("docs/DOCUMENTATION_LAYER_CONCEPT.md",),
|
|
),
|
|
)
|
|
|
|
|
|
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="Documentation",
|
|
level="tenant",
|
|
module_id=module_id,
|
|
resource=resource,
|
|
action=action,
|
|
)
|
|
|
|
|
|
def _route_factory(context: ModuleContext):
|
|
del context
|
|
from govoplan_docs.backend.api.v1.routes import router
|
|
|
|
return router
|
|
|
|
|
|
manifest = ModuleManifest(
|
|
id="docs",
|
|
name="Docs",
|
|
version="0.1.10",
|
|
required_capabilities=(
|
|
CAPABILITY_AUTH_PRINCIPAL_RESOLVER,
|
|
CAPABILITY_AUTH_PERMISSION_EVALUATOR,
|
|
),
|
|
optional_dependencies=("policy", "audit", "ops", "workflow_engine", "search"),
|
|
permissions=(
|
|
_permission(
|
|
DOCS_READ_SCOPE,
|
|
"View configured documentation",
|
|
"Read user documentation generated for the current actor from installed modules and effective configuration.",
|
|
),
|
|
_permission(
|
|
DOCS_ADMIN_READ_SCOPE,
|
|
"View administrative documentation",
|
|
"Read technical module, route, permission, configuration, and evidence documentation.",
|
|
),
|
|
),
|
|
role_templates=(
|
|
RoleTemplate(
|
|
slug="docs_reader",
|
|
name="Documentation reader",
|
|
description="Read the configured-system documentation browser. This role is granted automatically to every authenticated tenant member while Docs is installed.",
|
|
permissions=(DOCS_READ_SCOPE,),
|
|
default_authenticated=True,
|
|
),
|
|
RoleTemplate(
|
|
slug="docs_admin",
|
|
name="Documentation administrator",
|
|
description="Read user guidance and the technical configured-system documentation projection.",
|
|
permissions=(DOCS_READ_SCOPE, DOCS_ADMIN_READ_SCOPE),
|
|
),
|
|
),
|
|
route_factory=_route_factory,
|
|
nav_items=(
|
|
NavItem(
|
|
path="/docs",
|
|
label="Docs",
|
|
icon="reports",
|
|
required_any=DOCS_READ_SCOPES,
|
|
order=880,
|
|
),
|
|
),
|
|
frontend=FrontendModule(
|
|
module_id="docs",
|
|
package_name="@govoplan/docs-webui",
|
|
routes=(
|
|
FrontendRoute(
|
|
path="/docs",
|
|
component="DocsPage",
|
|
required_any=DOCS_READ_SCOPES,
|
|
order=880,
|
|
),
|
|
),
|
|
nav_items=(
|
|
NavItem(
|
|
path="/docs",
|
|
label="Docs",
|
|
icon="reports",
|
|
required_any=DOCS_READ_SCOPES,
|
|
order=880,
|
|
),
|
|
),
|
|
),
|
|
documentation=(
|
|
DocumentationTopic(
|
|
id="docs.configured-system-documentation",
|
|
title="Configured system documentation",
|
|
summary="This documentation page starts with installed modules, active configuration, visible routes, and permissions for the current actor.",
|
|
body="Module manifests can contribute durable documentation topics. Modules can also register runtime documentation providers when content depends on tenant policy, installed integrations, or operational settings.",
|
|
layer="always",
|
|
documentation_types=("admin", "user"),
|
|
audience=("tenant_admin", "operator", "module_admin"),
|
|
order=10,
|
|
i18n_key="docs.topic.configured_system_documentation",
|
|
translations={
|
|
"de": {
|
|
"title": "Dokumentation dieses Systems",
|
|
"summary": "Diese Dokumentation beginnt mit den installierten Modulen, der aktiven Konfiguration und den Funktionen, die fuer diese Rolle sichtbar sind.",
|
|
"body": "Module koennen feste Dokumentationsabschnitte beitragen. Wenn Inhalte von Tenant-Regeln, installierten Integrationen oder Betriebsoptionen abhaengen, kann ein Modul laufzeitbasierte Dokumentation registrieren.",
|
|
},
|
|
},
|
|
links=(
|
|
DocumentationLink(
|
|
label="Public GovOPlaN module documentation",
|
|
href="https://govplan.add-ideas.de/",
|
|
kind="public",
|
|
),
|
|
DocumentationLink(
|
|
label="Documentation layer concept",
|
|
href="govoplan-docs/docs/DOCUMENTATION_LAYER_CONCEPT.md",
|
|
kind="repository",
|
|
),
|
|
DocumentationLink(
|
|
label="Instance-aware documentation contract",
|
|
href="govoplan-docs/docs/INSTANCE_AWARE_DOCUMENTATION.md",
|
|
kind="repository",
|
|
),
|
|
),
|
|
metadata={"kind": "system"},
|
|
),
|
|
DocumentationTopic(
|
|
id="docs.reference.institutional-governance-architecture",
|
|
title="Institutional governance architecture",
|
|
summary="GovOPlaN models institutional responsibility, governed work, formal outcomes, evidence, and external-system authority without turning every concept into Core or one monolithic application.",
|
|
body=(
|
|
"Organizations, Identity, IDM, Access, and Policy answer different parts of who may act. "
|
|
"Mandate, service, procedure-party, and formal-decision semantics are being introduced as shared contracts and become modules only after independent lifecycle and reuse are proven. "
|
|
"External integrations separately declare technical maturity and whether GovOPlaN is authoritative, mirrors an external source, synchronizes under governance, adds an overlay, or retains only a link."
|
|
),
|
|
layer="always",
|
|
documentation_types=("admin",),
|
|
audience=("tenant_admin", "operator", "module_admin", "product_owner"),
|
|
order=15,
|
|
translations={
|
|
"de": {
|
|
"title": "Architektur der institutionellen Steuerung",
|
|
"summary": "GovOPlaN modelliert institutionelle Verantwortung, gesteuerte Arbeit, formale Ergebnisse, Nachweise und die Datenhoheit externer Systeme, ohne alle Begriffe in den Kern oder eine monolithische Anwendung zu ziehen.",
|
|
"body": "Organisationen, Identitaeten, IDM, Zugriff und Richtlinien beantworten unterschiedliche Teile der Frage, wer handeln darf. Mandate, Leistungen, Verfahrensbeteiligte und formale Entscheidungen beginnen als gemeinsame Vertraege und werden erst bei nachgewiesenem eigenstaendigem Lebenszyklus zu Modulen. Integrationen erklaeren technische Reife und Datenhoheit getrennt.",
|
|
},
|
|
},
|
|
links=(
|
|
DocumentationLink(
|
|
label="Institutional governance target architecture",
|
|
href="govoplan/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md",
|
|
kind="repository",
|
|
),
|
|
DocumentationLink(
|
|
label="Core module architecture",
|
|
href="govoplan-core/docs/MODULE_ARCHITECTURE.md",
|
|
kind="repository",
|
|
),
|
|
),
|
|
metadata={
|
|
"kind": "reference",
|
|
"architecture_topics": [
|
|
"institutional context",
|
|
"module ownership",
|
|
"source authority",
|
|
"integration maturity",
|
|
"product packages",
|
|
],
|
|
},
|
|
),
|
|
DocumentationTopic(
|
|
id="docs.pattern.field-help",
|
|
title="Field help marker",
|
|
summary="A small help marker next to a label gives local context without turning dense forms into manuals.",
|
|
body="Use the marker for short explanations of a field, option, or compact term. Link to a workflow or reference topic when the reader needs steps, API mapping, policy provenance, or operational detail.",
|
|
layer="always",
|
|
documentation_types=("admin", "user"),
|
|
audience=("user", "tenant_admin", "operator", "module_admin"),
|
|
order=20,
|
|
i18n_key="docs.topic.pattern.field_help",
|
|
links=(
|
|
DocumentationLink(
|
|
label="Documentation experience concept",
|
|
href="govoplan-docs/docs/DOCUMENTATION_EXPERIENCE_CONCEPT.md",
|
|
kind="repository",
|
|
),
|
|
),
|
|
metadata={
|
|
"kind": "pattern",
|
|
"pattern_id": "field-help-marker",
|
|
"purpose": "Keep labels scannable while making short explanations available on demand.",
|
|
"when_used": "Form labels, toggle labels, effective-value rows, and compact admin terms.",
|
|
"user_explanation": "Open the marker when a label is unclear. It should explain the local choice in one or two sentences.",
|
|
"admin_explanation": "Field help stays local. Longer procedural, API, or policy explanations belong in linked workflow or reference topics.",
|
|
"component_refs": [
|
|
"govoplan-core/webui/src/components/help/FieldLabel.tsx",
|
|
"govoplan-core/webui/src/components/help/InlineHelp.tsx",
|
|
"govoplan-core/webui/src/utils/fieldHelp.ts",
|
|
],
|
|
"related_topic_ids": [
|
|
"access.reference.admin-access-fields",
|
|
"access.workflow.grant-user-access",
|
|
],
|
|
},
|
|
),
|
|
DocumentationTopic(
|
|
id="docs.reference.organization-identity-idm-access-boundary",
|
|
title="Organization, identity, IDM, and access boundary",
|
|
summary="Organizations defines structures and functions. Identity defines people and accounts. IDM links identities to functions. Access turns accepted facts into roles and rights.",
|
|
body=(
|
|
"Use Organizations to model units, structures, relations, and function definitions. "
|
|
"Use Identity to maintain normalized identities and account links. "
|
|
"Use IDM to link an identity or account to a function in an organization unit, including delegated or acting-for cases. "
|
|
"Use Access to map accepted function facts to roles and permissions. "
|
|
"This split keeps organization modeling separate from identity lifecycle and keeps authorization decisions explicit."
|
|
),
|
|
layer="configured",
|
|
documentation_types=("admin", "user"),
|
|
audience=("tenant_admin", "access_admin", "operator", "user"),
|
|
related_modules=("organizations", "identity", "idm", "access"),
|
|
order=21,
|
|
conditions=(
|
|
DocumentationCondition(
|
|
required_modules=("organizations", "identity", "idm", "access"),
|
|
),
|
|
),
|
|
links=(
|
|
DocumentationLink(
|
|
label="Organizations", href="/organizations", kind="runtime"
|
|
),
|
|
DocumentationLink(label="IDM assignments", href="/idm", kind="runtime"),
|
|
DocumentationLink(
|
|
label="Access administration", href="/admin", kind="runtime"
|
|
),
|
|
),
|
|
metadata={
|
|
"kind": "reference",
|
|
"admin_explanation": "Function-to-role effects are owned by Access. IDM assignment changes can be governed independently from organization model changes.",
|
|
"user_explanation": "A person can hold a function because IDM links their identity to the organization function. Access decides which application permissions that function gives.",
|
|
"module_boundaries": [
|
|
{
|
|
"module": "organizations",
|
|
"owns": "unit types, structures, relations, units, and function definitions",
|
|
},
|
|
{"module": "identity", "owns": "identities and account links"},
|
|
{
|
|
"module": "idm",
|
|
"owns": "identity-to-function assignments, delegation, acting-for links, and synchronization mapping",
|
|
},
|
|
{
|
|
"module": "access",
|
|
"owns": "roles, permissions, and accepted function-to-role mappings",
|
|
},
|
|
],
|
|
},
|
|
),
|
|
),
|
|
documentation_sources=(
|
|
DocumentationSourceDefinition(
|
|
id="docs.project.wiki",
|
|
kind="wiki",
|
|
label="GovOPlaN Docs wiki",
|
|
provenance={"source": "gitea_wiki"},
|
|
link=DocumentationLink(
|
|
label="GovOPlaN Docs wiki",
|
|
href="https://git.add-ideas.de/GovOPlaN/govoplan-docs/wiki",
|
|
kind="wiki",
|
|
),
|
|
inspection={
|
|
"href": "https://git.add-ideas.de/GovOPlaN/govoplan-docs/wiki",
|
|
},
|
|
),
|
|
),
|
|
architecture=ARCHITECTURE,
|
|
)
|
|
|
|
|
|
def get_manifest() -> ModuleManifest:
|
|
return manifest
|