feat(connectors): document consequential governance actions

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "govoplan-connectors"
-version = "0.1.23"
+version = "0.1.25"
 description = "Governed connector catalogue and tabular source capabilities for GovOPlaN."
 readme = "README.md"
 requires-python = ">=3.12"

src/govoplan_connectors/backend/german_structured_documentation.py

@@ -0,0 +1,77 @@
+"""German translations for public structured documentation metadata."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+GERMAN_STRUCTURED_TRANSLATIONS: dict[str, dict[str, Any]] = {'connectors.data-subject-requests': {'consequence_classes': {'exclude_connector_secrets': 'Gibt '
+                                                                                           'niemals '
+                                                                                           'Anmeldeinformationen, '
+                                                                                           'Endpunkte, '
+                                                                                           'externe '
+                                                                                           'Zeilen '
+                                                                                           'oder '
+                                                                                           'Beweisnutzlasten '
+                                                                                           'zurück.',
+                                                              'export_operator_attribution': 'Retouren '
+                                                                                             'minimierte '
+                                                                                             'Connector-Aktivität '
+                                                                                             'für '
+                                                                                             'das '
+                                                                                             'genaue '
+                                                                                             'Konto.',
+                                                              'retain_connector_evidence': 'Bewahrt '
+                                                                                           'die '
+                                                                                           'Konfiguration '
+                                                                                           'und '
+                                                                                           'die '
+                                                                                           'Rechenschaftspflicht '
+                                                                                           'für '
+                                                                                           'externe '
+                                                                                           'Operationen '
+                                                                                           'bei.'}},
+ 'connectors.governed-configuration': {'outcome': 'Das aktive Konnektorverhalten ist inspizierbar, '
+                                                  'versionengebunden, testbar und überprüfbar, '
+                                                  'bevor ein anbieterspezifisches Schreiben '
+                                                  'erfolgt.',
+                                       'prerequisites': ['Eine Konnektordefinition wurde '
+                                                         'installiert oder erstellt.',
+                                                         'Anmeldematerial wird außerhalb der '
+                                                         'Connector-URL gespeichert und durch eine '
+                                                         'genehmigte geheime Kennung '
+                                                         'referenziert.'],
+                                       'verification': 'Laden Sie die Konfiguration neu, prüfen '
+                                                       'Sie geschützte Pfade und effektiven Hash, '
+                                                       'führen Sie eine Simulation mit einem neuen '
+                                                       'idempotency-Schlüssel aus und lösen Sie '
+                                                       'alle ausstehenden Überprüfungsergebnisse.'},
+ 'connectors.mediawiki-bluespice': {'outcome': 'Externes Wissen bleibt identitätsstabil, '
+                                               'verlustsichtbar, ACL-sicher und migrationsfähig.',
+                                    'prerequisites': ['Eine aktive verwaltete MediaWiki Action '
+                                                      'API-Konfiguration existiert.',
+                                                      'Namespace-Ziele und Fallback-ACLs wurden '
+                                                      'überprüft.',
+                                                      'Die Such- und Wiki-Module sind optional und '
+                                                      'bleiben fähigkeitsgetrennt.'],
+                                    'verification': 'Entdecken Sie das Profil neu, führen Sie ein '
+                                                    'Delta mit Schlüsseln aus, inspizieren Sie '
+                                                    'Gesundheit und Diagnose, überprüfen Sie einen '
+                                                    'erlaubten und verweigerten Suchprinzipal und '
+                                                    'führen Sie einen Migrations-Dry-Run aus, '
+                                                    'bevor Sie zielseitig arbeiten.'},
+ 'connectors.znuny-otrs': {'outcome': 'Externe Tickets bleiben identitätsstabil, verlustsichtbar, '
+                                      'ACL-sicher, wiederherstellbar und semantisch getrennt von '
+                                      'GovOPlaN-Domäneneinträgen.',
+                           'prerequisites': ['Eine aktiv gesteuerte Znuny/OTRS GenericInterface '
+                                             'REST-Konfiguration existiert.',
+                                             'Bereitstellungsdefinierte Routen, '
+                                             'Warteschlangenpartitionen, Autorität und '
+                                             'Fallback-ACLs wurden überprüft.',
+                                             'Tickets, Helpdesk, Cases und Search bleiben '
+                                             'optionale funktionsgetrennte Verbraucher.'],
+                           'verification': 'Entdecke das Profil neu, beende einen Keyed-Full-Run, '
+                                           'führe ein Keyed-Delta aus, inspiziere die '
+                                           'Mapping-Diagnose, überprüfe einen erlaubten und '
+                                           'verweigerten Suchprinzipal und versöhne jedes '
+                                           'ergebnisunbekannte Update vor dem erneuten Versuch.'}}

src/govoplan_connectors/backend/manifest.py

@@ -1,5 +1,8 @@
 from __future__ import annotations
 
+from govoplan_core.core.modules import with_documentation_structured_translations
+from govoplan_connectors.backend.german_structured_documentation import GERMAN_STRUCTURED_TRANSLATIONS
+
 from pathlib import Path
 
 from govoplan_core.core.access import (
@@ -123,7 +126,7 @@ from govoplan_connectors.backend.german_documentation import (
 
 
 MODULE_ID = "connectors"
-MODULE_VERSION = "0.1.23"
+MODULE_VERSION = "0.1.25"
 TABULAR_SOURCE_INTERFACE_VERSION = "0.1.0"
 DATASOURCE_ORIGIN_INTERFACE_VERSION = "0.1.0"
 SANCTIONS_SNAPSHOT_INTERFACE_VERSION = "1.0.0"
@@ -1050,6 +1053,10 @@ manifest = ModuleManifest(
             order=39,
             metadata={
                 "kind": "reference",
+                "help_contexts": [
+                    "connectors.action.reject-ambiguous-result",
+                    "connectors.action.approve-ambiguous-result",
+                ],
                 "fields": [
                     "Direction and technical maturity",
                     "Configured source authority",
@@ -1260,6 +1267,11 @@ manifest = ModuleManifest(
 )
 
 
+manifest = with_documentation_structured_translations(
+    manifest, locale="de", translations=GERMAN_STRUCTURED_TRANSLATIONS
+)
+
+
 def get_manifest() -> ModuleManifest:
     return manifest
 

webui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@govoplan/connectors-webui",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "private": true,
   "type": "module",
   "main": "src/index.ts",

webui/src/features/ConnectorGovernancePage.tsx

@@ -483,7 +483,7 @@ export default function ConnectorGovernancePage({ settings, auth }: Props) {
             <FormField label="Endpoint URL" hint="Credentials are rejected in URLs.">
               <input value={draft.endpoint_url} disabled={!canAdmin || busy} placeholder="https://provider.example/api" onChange={(event) => setDraft({ ...draft, endpoint_url: event.target.value })} />
             </FormField>
-            <FormField label="Credential reference" hint="Reference an approved secret; do not paste a secret.">
+            <FormField label="Credential reference" hint="Reference an approved secret; do not paste a secret." helpContextId="connectors.admin.governed-configurations" helpModuleId="connectors">
               <input value={draft.credential_ref} disabled={!canAdmin || busy} placeholder="vault://connectors/provider" onChange={(event) => setDraft({ ...draft, credential_ref: event.target.value })} />
             </FormField>
             <FormField label="Ambiguous-result policy">
@@ -574,7 +574,7 @@ export default function ConnectorGovernancePage({ settings, auth }: Props) {
         <FormField label="Endpoint URL">
           <input value={newDraft.endpoint_url} disabled={busy} onChange={(event) => setNewDraft({ ...newDraft, endpoint_url: event.target.value })} />
         </FormField>
-        <FormField label="Credential reference">
+        <FormField label="Credential reference" helpContextId="connectors.admin.governed-configurations" helpModuleId="connectors">
           <input value={newDraft.credential_ref} disabled={busy} onChange={(event) => setNewDraft({ ...newDraft, credential_ref: event.target.value })} />
         </FormField>
         <FormField label="Ambiguous-result policy">
@@ -597,8 +597,8 @@ export default function ConnectorGovernancePage({ settings, auth }: Props) {
       closeDisabled={busy}
       footer={<>
         <Button onClick={() => setReviewRun(null)} disabled={busy}>Cancel</Button>
-        <Button variant="danger" onClick={() => void decideReview("rejected")} disabled={busy || reviewReason.trim().length < 5}>Reject</Button>
+        <Button variant="danger" helpContextId="connectors.action.reject-ambiguous-result" helpModuleId="connectors" onClick={() => void decideReview("rejected")} disabled={busy || reviewReason.trim().length < 5}>Reject</Button>
-        <Button variant="primary" onClick={() => void decideReview("approved")} disabled={busy || reviewReason.trim().length < 5}>Approve</Button>
+        <Button variant="primary" helpContextId="connectors.action.approve-ambiguous-result" helpModuleId="connectors" onClick={() => void decideReview("approved")} disabled={busy || reviewReason.trim().length < 5}>Approve</Button>
       </>}
     >
       <p>Review {reviewRun?.summary.ambiguous ?? 0} ambiguous effects against the retained input and configuration hashes before deciding.</p>

webui/src/features/ExternalKnowledgePage.tsx

@@ -326,7 +326,7 @@ export default function ExternalKnowledgePage({ settings, auth }: Props) {
       <Button variant="secondary" onClick={() => void sync(false)} disabled={!selected || !canSync || busy || dirty}>Run delta</Button>
       <Button variant="secondary" onClick={() => void sync(true)} disabled={!selected || !canSync || busy || dirty}>Run full backfill</Button>
       <Button variant="secondary" onClick={() => setMigrationOpen(true)} disabled={!selected || !canMigrate || busy || dirty}>Preview migration</Button>
-      <Button variant="primary" onClick={() => setPublishOpen(true)} disabled={!selected || !canPublish || busy || dirty}>Publish page</Button>
+      <Button variant="primary" helpContextId="connectors.admin.external-knowledge" helpModuleId="connectors" onClick={() => setPublishOpen(true)} disabled={!selected || !canPublish || busy || dirty}>Publish page</Button>
     </>}
     discardAction={{
       label: "Discard changes",
@@ -501,7 +501,7 @@ export default function ExternalKnowledgePage({ settings, auth }: Props) {
 
     <Dialog open={publishOpen} title="Publish provider page revision" onClose={() => !busy && setPublishOpen(false)} closeDisabled={busy} footer={<>
       <Button onClick={() => setPublishOpen(false)} disabled={busy}>Cancel</Button>
-      <Button variant="primary" onClick={() => void publish()} disabled={busy || !externalPageId.trim() || !publishTitle.trim()}>Publish revision</Button>
+      <Button variant="primary" helpContextId="connectors.admin.external-knowledge" helpModuleId="connectors" onClick={() => void publish()} disabled={busy || !externalPageId.trim() || !publishTitle.trim()}>Publish revision</Button>
     </>}>
       <p className="muted">Publication is an external effect. Supply the current provider revision where possible; an unknown outcome blocks blind retry.</p>
       <FormGrid columns={2} collapseAt="standard" className="">