Sync Repo-docs-SERVICE-DIRECTORY-CONCEPT from project files

2026-08-01 08:56:11 +02:00
parent 331bec5239
commit 1407617e85
1 changed files with 108 additions and 0 deletions
@@ -0,0 +1,108 @@
+<!-- codex-wiki-sync:9875c2f0390afdffbaa765bc -->
+
+> Mirrored from `/mnt/DATA/git/govoplan-portal/docs/SERVICE_DIRECTORY_CONCEPT.md`.
+> Origin: `repository`.
+> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
+
+---
+# Role-Based Service Directory Concept
+
+GovOPlaN Portal should expose a role-aware service directory. The directory is
+not a marketing catalogue; it is the user-facing map of what a person can do in
+the configured institution.
+
+Portal owns presentation, discovery, entry, and channel-specific availability.
+It must not become the long-term owner of the institutional service definition.
+A shared Services contract should own the versioned promise independently so
+Cases, Forms, Workflow Engine, Reporting, external publication, and more than
+one portal surface can consume the same definition.
+
+## Purpose
+
+The service directory should help users find the right administrative action
+without knowing the internal module layout. Available services depend on
+tenant, role, organization unit, policies, installed modules, and configuration
+packages.
+
+Examples:
+
+- apply for a permit
+- submit documents for an existing case
+- request an appointment
+- send a secure postbox message
+- report an issue
+- book a resource
+- start an internal workflow
+
+## Contract
+
+A service entry should describe:
+
+- service key and label
+- owning module or configuration package
+- audience and role/function requirements
+- required installed/enabled modules
+- required capabilities
+- form, workflow, postbox, task, or external connector entry point
+- policy and availability blockers
+- user-facing explanation and required documents
+- audit and evidence expectations
+- version and effective interval
+- legal or organizational basis, deadlines, fees, remedies, and service-level
+  expectations
+- responsible organization/function, mandate/jurisdiction, result/decision,
+  publication, and records bindings
+
+The portal should request service contributions through core-mediated
+capability and UI contribution contracts. It must not import domain module
+internals.
+
+The first implementation may consume module-contributed service definitions.
+Create a separate `govoplan-services` repository only when definitions require
+independent persistence/lifecycle and are consumed outside Portal by at least
+one other procedure or publication surface. Extraction must keep stable service
+keys and compatibility for existing Portal links.
+
+Service visibility must consume access semantics through kernel capabilities:
+
+- `access.semanticDirectory` resolves the actor's identity, account,
+  organization-unit function assignments, delegations, and role mappings.
+- `access.explanation` provides the explanation shown when a service is
+  available or blocked because of a missing function, role, right, or policy.
+
+Service entries should support function requirements directly, not only role
+requirements. A function requirement may apply to one organization unit or to
+that unit and all subunits, matching the access assignment scope.
+
+## UX Rule
+
+The directory should explain unavailable services when the reason is useful:
+missing role, disabled module, tenant policy, missing connector, maintenance
+mode, or unavailable external provider. It should hide only services that are
+irrelevant or intentionally undiscoverable by policy.
+
+## Implemented Headless Slice
+
+`portal.service_directory` consumes the optional `services.definitions`
+capability. It returns only tenant-scoped definitions and distinguishes
+`available`, `unavailable`, and `hidden` states. Draft, retired,
+outside-effective-time, and audience-inapplicable services are hidden. A
+suspended service or missing required module/capability remains discoverable
+with stable reason codes and its configured explanation reference.
+
+The definition provider remains responsible for access and policy filtering.
+Portal cannot widen its result and returns an empty directory when no provider
+is installed. No service definition is persisted in Portal.
+
+Tenant/package specializations are derived before presentation through Core's
+restrictive Service rule. They carry their parent version and may narrow
+audience, channels, effective time, and publication or add prerequisites,
+required evidence, legal bases, and bindings. They cannot silently loosen the
+system/package definition.
+
+Policy, Mandate, connector, maintenance, and configuration requirements are
+evaluated through the optional `services.availability` capability. Module and
+capability requirements are checked against the active registry, and audience
+requirements against the supplied actor projection. Unknown requirements fail
+closed. Each requirement declares whether failure remains visible with an
+explanation or makes the entry undiscoverable.