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,
    FrontendModule,
    FrontendRoute,
    ModuleContext,
    ModuleManifest,
    NavItem,
    PermissionDefinition,
    RoleTemplate,
)

DOCS_READ_SCOPE = "docs:documentation:read"
DOCS_READ_SCOPES = (DOCS_READ_SCOPE, "system:settings:read", "admin:settings:read")


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.8",
    required_capabilities=(CAPABILITY_AUTH_PRINCIPAL_RESOLVER, CAPABILITY_AUTH_PERMISSION_EVALUATOR),
    optional_dependencies=("policy", "audit", "ops", "workflow", "search"),
    permissions=(
        _permission(
            DOCS_READ_SCOPE,
            "View configured documentation",
            "Read documentation generated from installed modules, visible routes, permissions, and evidence sources.",
        ),
    ),
    role_templates=(
        RoleTemplate(
            slug="docs_reader",
            name="Documentation reader",
            description="Read the configured-system documentation browser.",
            permissions=(DOCS_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.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,
            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"},
                ],
            },
        ),
    ),
)


def get_manifest() -> ModuleManifest:
    return manifest