Sync Repo-docs-SERVICE-DIRECTORY-CONCEPT from project files
@@ -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.
|
||||||
Reference in New Issue
Block a user