From 52b48d553a2f67100eb3d5e08dbf2c63beea03a0 Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Sat, 1 Aug 2026 00:04:19 +0200 Subject: [PATCH] Sync wiki from project files --- Codex-Project-Index.md | 6 + Product govoplan-govoplan-concept-dev.md | 2062 +++++++++++++++++ Repo-README.md | 24 +- Repo-docs-ACTION-EFFECT-AUTOMATION-LAYER.md | 31 +- Repo-docs-CODEX-WORKFLOW.md | 12 +- Repo-docs-COMPATIBILITY-INVENTORY.md | 50 + Repo-docs-COMPATIBILITY-POLICY.md | 76 + Repo-docs-CONFIGURATION-PACKAGES.md | 27 +- Repo-docs-DATAGRID-SIZING-CONTRACT.md | 74 + Repo-docs-DEPLOYMENT-OPERATOR-GUIDE.md | 19 +- Repo-docs-DOCUMENTATION-MAP.md | 6 +- ...NAL-REFERENCES-AND-INTEGRATION-MATURITY.md | 22 +- Repo-docs-GOVOPLAN-MASTER-ROADMAP.md | 129 +- Repo-docs-MODULE-ARCHITECTURE.md | 163 +- Repo-docs-RELEASE-DEPENDENCIES.md | 11 +- Repo-docs-THEMING.md | 34 + Repo-docs-UI-UX-DECISION-LEDGER.md | 21 +- Repo-docs-WEBUI-BUNDLE-BUDGETS.md | 78 + 18 files changed, 2768 insertions(+), 77 deletions(-) create mode 100644 Product govoplan-govoplan-concept-dev.md create mode 100644 Repo-docs-COMPATIBILITY-INVENTORY.md create mode 100644 Repo-docs-COMPATIBILITY-POLICY.md create mode 100644 Repo-docs-DATAGRID-SIZING-CONTRACT.md create mode 100644 Repo-docs-THEMING.md create mode 100644 Repo-docs-WEBUI-BUNDLE-BUDGETS.md diff --git a/Codex-Project-Index.md b/Codex-Project-Index.md index 3f2d20a..ba854c7 100644 --- a/Codex-Project-Index.md +++ b/Codex-Project-Index.md @@ -4,13 +4,17 @@ This page is generated from repository and product-directory project files. +- [Product govoplan-govoplan-concept-dev](Product govoplan-govoplan-concept-dev) - `/mnt/DATA/Nextcloud/ADD ideas UG/Products/govoplan/govoplan_concept_dev.md` - [Product govoplan-split-concept-action-plan](Product govoplan-split-concept-action-plan) - `/mnt/DATA/Nextcloud/ADD ideas UG/Products/govoplan/split-concept-action-plan.md` - [Repo-README](Repo-README) - `/mnt/DATA/git/govoplan-core/README.md` - [Repo-docs-ACCESS-RBAC-MODEL](Repo-docs-ACCESS-RBAC-MODEL) - `/mnt/DATA/git/govoplan-core/docs/ACCESS_RBAC_MODEL.md` - [Repo-docs-ACTION-EFFECT-AUTOMATION-LAYER](Repo-docs-ACTION-EFFECT-AUTOMATION-LAYER) - `/mnt/DATA/git/govoplan-core/docs/ACTION_EFFECT_AUTOMATION_LAYER.md` - [Repo-docs-AUTOMATION-CONTRACTS](Repo-docs-AUTOMATION-CONTRACTS) - `/mnt/DATA/git/govoplan-core/docs/AUTOMATION_CONTRACTS.md` - [Repo-docs-CODEX-WORKFLOW](Repo-docs-CODEX-WORKFLOW) - `/mnt/DATA/git/govoplan-core/docs/CODEX_WORKFLOW.md` +- [Repo-docs-COMPATIBILITY-INVENTORY](Repo-docs-COMPATIBILITY-INVENTORY) - `/mnt/DATA/git/govoplan-core/docs/COMPATIBILITY_INVENTORY.md` +- [Repo-docs-COMPATIBILITY-POLICY](Repo-docs-COMPATIBILITY-POLICY) - `/mnt/DATA/git/govoplan-core/docs/COMPATIBILITY_POLICY.md` - [Repo-docs-CONFIGURATION-PACKAGES](Repo-docs-CONFIGURATION-PACKAGES) - `/mnt/DATA/git/govoplan-core/docs/CONFIGURATION_PACKAGES.md` +- [Repo-docs-DATAGRID-SIZING-CONTRACT](Repo-docs-DATAGRID-SIZING-CONTRACT) - `/mnt/DATA/git/govoplan-core/docs/DATAGRID_SIZING_CONTRACT.md` - [Repo-docs-DEPENDENCY-AUDITS](Repo-docs-DEPENDENCY-AUDITS) - `/mnt/DATA/git/govoplan-core/docs/DEPENDENCY_AUDITS.md` - [Repo-docs-DEPLOYMENT-OPERATOR-GUIDE](Repo-docs-DEPLOYMENT-OPERATOR-GUIDE) - `/mnt/DATA/git/govoplan-core/docs/DEPLOYMENT_OPERATOR_GUIDE.md` - [Repo-docs-DOCUMENTATION-MAP](Repo-docs-DOCUMENTATION-MAP) - `/mnt/DATA/git/govoplan-core/docs/DOCUMENTATION_MAP.md` @@ -28,6 +32,8 @@ This page is generated from repository and product-directory project files. - [Repo-docs-REMOTE-WEBUI-BUNDLES](Repo-docs-REMOTE-WEBUI-BUNDLES) - `/mnt/DATA/git/govoplan-core/docs/REMOTE_WEBUI_BUNDLES.md` - [Repo-docs-SECURITY-AUDIT](Repo-docs-SECURITY-AUDIT) - `/mnt/DATA/git/govoplan-core/docs/SECURITY_AUDIT.md` - [Repo-docs-SELF-HOSTED-INSTALLABILITY](Repo-docs-SELF-HOSTED-INSTALLABILITY) - `/mnt/DATA/git/govoplan-core/docs/SELF_HOSTED_INSTALLABILITY.md` +- [Repo-docs-THEMING](Repo-docs-THEMING) - `/mnt/DATA/git/govoplan-core/docs/THEMING.md` - [Repo-docs-THROTTLING](Repo-docs-THROTTLING) - `/mnt/DATA/git/govoplan-core/docs/THROTTLING.md` - [Repo-docs-UI-UX-DECISION-LEDGER](Repo-docs-UI-UX-DECISION-LEDGER) - `/mnt/DATA/git/govoplan-core/docs/UI_UX_DECISION_LEDGER.md` +- [Repo-docs-WEBUI-BUNDLE-BUDGETS](Repo-docs-WEBUI-BUNDLE-BUDGETS) - `/mnt/DATA/git/govoplan-core/docs/WEBUI_BUNDLE_BUDGETS.md` - [Repo-docs-audits-2026-07-09-dependency-audit](Repo-docs-audits-2026-07-09-dependency-audit) - `/mnt/DATA/git/govoplan-core/docs/audits/2026-07-09-dependency-audit.md` diff --git a/Product govoplan-govoplan-concept-dev.md b/Product govoplan-govoplan-concept-dev.md new file mode 100644 index 0000000..8d5fb6f --- /dev/null +++ b/Product govoplan-govoplan-concept-dev.md @@ -0,0 +1,2062 @@ + + +> Mirrored from `/mnt/DATA/Nextcloud/ADD ideas UG/Products/govoplan/govoplan_concept_dev.md`. +> Origin: `product:govoplan`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# Ableitung einer Zielarchitektur für govoplan + +## Ergebnis vorab + +Die bestehende Struktur ist der benötigten Zielarchitektur bereits deutlich näher, als es die frühere Aufteilung in `core`, `campaign`, `mail` und `files` vermuten lässt. Die GovOPlaN-Organisation umfasst inzwischen 72 Repositories. `govoplan-core` ist bereits ausdrücklich als schlanker Laufzeitkern definiert; fachliche und plattformbezogene Funktionen sollen von Modulen übernommen werden. Gleichzeitig unterscheidet die Architekturdokumentation bereits zwischen Plattform-, Dienst-, Fach- und Konnektormodulen. ([gitea@add-ideas.de][1]) + +Die wesentliche Aufgabe lautet daher nicht: + +> Möglichst viele weitere Module ergänzen. + +Sondern: + +> Die vorhandenen Module zu einer konsistenten institutionellen Architektur ordnen, ihre Zuständigkeiten schärfen und einige noch fehlende grundlegende Governance-Objekte ergänzen. + +Meine zentralen Schlussfolgerungen sind: + +1. **Der bestehende Kernansatz ist richtig:** `govoplan-core` sollte klein bleiben. +2. **Native Funktionen und externe Systeme dürfen parallel unterstützt werden.** Das sollte kein Sonderfall, sondern ein allgemeines Architekturprinzip sein. +3. **Vier grundlegende horizontale Fachkontexte fehlen noch:** Aufgaben und Mandate, Leistungen, Verfahrensbeteiligte sowie Entscheidungen. +4. **Viele vorhandene Repositories sind richtig gedacht, aber teilweise falsch klassifiziert oder noch nicht hinreichend voneinander abgegrenzt.** +5. **Logische Modularität sollte nicht automatisch ein eigenes Repository bedeuten.** +6. **Produktpakete und Sektorkonfigurationen sollten oberhalb der Module liegen und keine neuen Plattform-Forks erzeugen.** + +Die bestehende Roadmap beschreibt GovOPlaN bereits als verbindende, governancebewusste Betriebsschicht und nicht als universellen Ersatz aller vorhandenen Systeme. Sie sieht ausdrücklich unterschiedliche Quellen der Wahrheit sowie native, externe und hybride Betriebsweisen vor. Die von dir vorgeschlagene Richtung entspricht damit dem bestehenden Leitbild. ([gitea@add-ideas.de][2]) + +--- + +# 1. Das grundlegende Architekturprinzip: nicht „integriert oder angebunden“, sondern unterschiedliche Betriebsmodelle + +Für jede grundsätzlich austauschbare Fähigkeit sollte GovOPlaN mehrere Betriebsmodelle unterstützen. + +| Betriebsmodell | Bedeutung | Beispiel | +| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | +| **Nativ und führend** | GovOPlaN ist das maßgebliche System für diese Daten und Funktionen. | Organisationsfunktionen, Delegationen oder interne Projektportfolios | +| **Extern und führend** | Ein externes System bleibt alleinige Quelle der Wahrheit; GovOPlaN nutzt dessen Schnittstellen. | SAP für Buchhaltung oder ein Personalverwaltungssystem | +| **Extern mit lokaler Spiegelung** | Externe Daten werden lesend übernommen und für Suche, Verknüpfung oder Ausfallsicherheit lokal vorgehalten. | Beschäftigtendaten aus einem HR-System | +| **Gesteuerte Synchronisation** | Daten werden zwischen GovOPlaN und einem externen System abgeglichen; Konflikte und Zuständigkeiten sind definiert. | Konten- und Gruppenzuordnung über SCIM | +| **Governance-Überlagerung** | Sach- oder Stammdaten bleiben extern, während GovOPlaN Zuständigkeit, Freigabe, Nachweise, Delegationen und Regeln verwaltet. | Externes ERP plus lokale Mittelverantwortung und Beschlussverknüpfung | +| **Verknüpfung ohne Datenübernahme** | GovOPlaN kennt nur Referenz, Status und Aufrufziel. | Verweis auf einen Vorgang in einem hoch spezialisierten Fachverfahren | + +Diese Betriebsweise sollte nicht nur je Modul, sondern nötigenfalls je: + +* Mandant, +* Organisationseinheit, +* Leistung, +* Objekttyp, +* Datenfeld, +* Prozessschritt + +festgelegt werden können. + +Ein Beispiel aus dem IDM: + +* Name und Beschäftigungsstatus stammen aus dem Personalverwaltungssystem. +* Anmeldung erfolgt über einen externen OIDC-Anbieter. +* die organisatorische Funktion wird nativ in GovOPlaN geführt; +* die zeitlich begrenzte Vertretung wird nativ in GovOPlaN geführt; +* technische Gruppen werden anschließend über SCIM in ein externes Verzeichnis geschrieben; +* die fachliche Befugnis ergibt sich aus einem in GovOPlaN geführten Mandat; +* die konkrete Zugriffsentscheidung trifft `govoplan-access` zusammen mit `govoplan-policy`. + +Damit ist kein System pauschal „führend“. Die Führungsverantwortung wird nach Informationsart getrennt. + +## Gemeinsamer Vertrag für austauschbare Anbieter + +Jede hybride Fähigkeit sollte einen einheitlichen Anbieter- oder Providervertrag besitzen. Dieser muss mindestens beschreiben: + +* welche Objekte und Felder der Anbieter besitzt; +* welche Operationen er unterstützt; +* ob nur Lesen oder auch Schreiben möglich ist; +* welche Version oder Revisionskennung gilt; +* wie aktuell die Daten sind; +* ob der Anbieter erreichbar und funktionsfähig ist; +* ob Vorschau oder Probelauf möglich sind; +* wie Konflikte erkannt werden; +* wie unklare Ausführungszustände behandelt werden; +* welche Nachweise entstehen; +* wie eine Rückabwicklung oder Abstimmung erfolgt; +* welches Verhalten bei Ausfall vorgesehen ist. + +Das ist insbesondere bei öffentlichen Einrichtungen wichtig. Eine fehlgeschlagene Operation darf nicht nur als technischer Fehler erscheinen. Die Plattform muss unterscheiden können zwischen: + +1. beabsichtigter Handlung; +2. freigegebener Handlung; +3. an das externe System übermittelter Handlung; +4. möglicherweise ausgeführter Handlung; +5. bestätigter Wirkung; +6. abgestimmtem Endzustand. + +--- + +# 2. Empfohlene Zielarchitektur + +Die folgende Gliederung beschreibt **Architekturschichten**, nicht zwingend einzelne Repositories. + +## Ebene 0: System, Laufzeit und Modulverwaltung + +### Bestehende Bausteine + +* `govoplan` +* `govoplan-core` + +### Zuständigkeit + +`govoplan` bleibt das übergreifende System- und Distributionsrepository. `govoplan-core` besitzt ausschließlich: + +* Anwendungsstart und Laufzeit; +* Datenbank- und Sitzungsgrundlagen; +* Modulerkennung; +* Modulregistrierung; +* Migrationskoordination; +* Capability- und Schnittstellenverzeichnis; +* Installations- und Aktualisierungsorchestrierung; +* gemeinsame Weboberflächenhülle; +* technische Basiskontrakte. + +Diese Richtung ist in der gegenwärtigen Kernarchitektur bereits angelegt. Fachliche Funktionen sollen nicht in den Kern zurückwandern. ([gitea@add-ideas.de][3]) + +### Nicht in den Kern gehören + +* Benutzerverwaltung; +* Mandantenverwaltung; +* Rollenverwaltung; +* Organisationsmodelle; +* Fallmanagement; +* Dateiverwaltung; +* Workflows; +* Richtlinien; +* Berichte; +* Fachobjekte. + +Der Kern darf gemeinsame Datentypen und Verträge bereitstellen, aber nicht die fachliche Bedeutung dieser Objekte besitzen. + +--- + +## Ebene 1: Institutionelle Basis und Berechtigungsordnung + +### Bestehende Bausteine + +* `govoplan-tenancy` +* `govoplan-identity` +* `govoplan-organizations` +* `govoplan-idm` +* `govoplan-access` +* `govoplan-identity-trust` +* `govoplan-encryption` + +### Zu ergänzen + +* **`govoplan-mandates`** beziehungsweise ein Modul für: + + * öffentliche Aufgaben; + * Mandate; + * Zuständigkeiten; + * Befugnisse; + * Verantwortungszuordnungen; + * Jurisdiktionen. + +### Zweck dieser Ebene + +Diese Module beantworten gemeinsam: + +* Welche Institutionen und Organisationseinheiten existieren? +* Welche natürlichen oder juristischen Personen sind bekannt? +* Welche Funktionen existieren? +* Wer nimmt welche Funktion zu welchem Zeitpunkt wahr? +* Welche Aufgabe, Befugnis oder Pflicht ist mit dieser Funktion verbunden? +* Über welches Konto handelt die Person? +* Welche technischen Rechte ergeben sich daraus? +* Wie sicher ist die behauptete Identität? +* Für wen handelt die Person möglicherweise vertretungsweise? + +Diese Ebene ist das institutionelle Rückgrat von GovOPlaN. + +--- + +## Ebene 2: Governance, Regeln und Rechenschaft + +### Bestehende Bausteine + +* `govoplan-policy` +* `govoplan-audit` +* `govoplan-risk-compliance` +* `govoplan-admin` +* `govoplan-ops` +* `govoplan-docs` +* `govoplan-views` +* `govoplan-search` + +### Zu ergänzen + +* **`govoplan-decisions`** +* später gegebenenfalls ein eigenständiger Ziel- und Wirkungsdienst, zunächst jedoch besser innerhalb von `projects`, `reporting` und `evaluation` + +### Zweck dieser Ebene + +* Richtlinien und Regelwerke; +* Entscheidungskompetenzen; +* Genehmigungsgrenzen; +* Aufbewahrungs- und Datenschutzregeln; +* Risiko- und Kontrollmodelle; +* Prüfpfade; +* Nachweise; +* formale Entscheidungen; +* Maßnahmen und Feststellungen; +* Systembetrieb und Administrationsaufsicht; +* rollen- und kontextbezogene Projektionen. + +`govoplan-risk-compliance` ist gegenwärtig als fachliches Modul klassifiziert, besitzt aber mit Risiken, Kontrollen, Datenschutz-Folgenabschätzungen, Vorfällen und Maßnahmen überwiegend querschnittliche Funktionen. Die bereits implementierte Sanktionslistenprüfung ist ein erster fachlicher Vertikalschnitt innerhalb dieses allgemeineren Kontrollmodells. ([gitea@add-ideas.de][4]) + +Deshalb sollte es architektonisch als **Governance- und Assurance-Plattformmodul** behandelt werden, nicht als gewöhnliches Fachverfahren. + +--- + +## Ebene 3: Menschliche Arbeit und Verfahrensausführung + +### Bestehende Bausteine + +* `govoplan-forms` +* `govoplan-forms-runtime` +* `govoplan-cases` +* `govoplan-tasks` +* `govoplan-approvals` +* `govoplan-workflow-engine` +* `govoplan-workflow` +* `govoplan-tickets` + +### Zu ergänzen + +* **`govoplan-services`** +* **`govoplan-parties`** + +### Zweck dieser Ebene + +* Leistungen beschreiben; +* Anträge und Meldungen erfassen; +* Verfahrensbeteiligte verwalten; +* Fälle führen; +* Aufgaben verteilen; +* Freigaben einholen; +* Arbeitsschritte koordinieren; +* Entscheidungen vorbereiten; +* Fristen überwachen; +* Verfahrensstände nachvollziehen; +* Übergaben an externe Systeme steuern. + +Die Trennung zwischen `govoplan-workflow-engine` und `govoplan-workflow` ist konzeptionell sinnvoll: Der Engine-Teil besitzt das ausführbare, revisionsfeste Ablaufmodell; das zweite Modul stellt visuelle Modellierung und Inspektion bereit. ([gitea@add-ideas.de][5]) + +Der Workflow-Engine sollte allerdings nicht zum allgegenwärtigen Unterbau jedes einfachen Moduls werden. Viele Vorgänge benötigen lediglich: + +* einen Statusautomaten; +* Aufgaben; +* Fristen; +* Freigaben; +* Ereignisse. + +Die allgemeine Workflow-Engine sollte dort eingesetzt werden, wo: + +* Abläufe konfigurierbar sein müssen; +* mehrere Module beteiligt sind; +* längere Ausführungszeiten auftreten; +* Wiederaufnahme und Fehlerbehandlung notwendig sind; +* Varianten zur Laufzeit ausgewählt werden; +* externe Wirkungen orchestriert werden. + +--- + +## Ebene 4: Kommunikations- und Zugangskanäle + +### Bestehende Bausteine + +* `govoplan-portal` +* `govoplan-postbox` +* `govoplan-notifications` +* `govoplan-mail` +* `govoplan-campaign` +* `govoplan-calendar` +* `govoplan-scheduling` +* `govoplan-booking` +* `govoplan-appointments` +* `govoplan-consultation` +* `govoplan-poll` +* `govoplan-committee` +* `govoplan-addresses` +* `govoplan-dist-lists` + +### Zweck dieser Ebene + +Diese Module stellen keine institutionellen Wahrheiten her, sondern ermöglichen Interaktion: + +* Portale; +* sichere Postfächer; +* Nachrichten; +* Benachrichtigungen; +* Serienkommunikation; +* Termine; +* Ressourcenbuchungen; +* Konsultationen; +* Abstimmungen; +* Gremienarbeit; +* Kontakt- und Verteilerverwaltung. + +Die konzeptionelle Abgrenzung sollte lauten: + +| Modul | Besitzt | +| --------------- | ------------------------------------------------------------------------------------------- | +| `mail` | Transportprofile, SMTP/IMAP-Anbindung, Zustellversuche und technische Ausgangswarteschlange | +| `notifications` | Hinweise, Aufmerksamkeit, Kanalwahl und Zustellkoordination | +| `postbox` | dauerhaftes institutionelles Ein- und Ausgangspostfach | +| `campaign` | gesteuerte, nachweisbare Massen- und Zielgruppenkommunikation | +| `addresses` | normalisierte erreichbare Kontaktziele | +| `dist-lists` | regelbasierte oder explizite Empfängergruppen | +| `portal` | externer Zugangskanal und Selbstbedienungsoberfläche | + +Diese Trennung ist in den bestehenden Modulen bereits weitgehend erkennbar. `govoplan-postbox` ist ausdrücklich funktionsgebunden und soll Postfächer auch bei Vakanz, Neubesetzung oder Delegation stabil halten. `govoplan-mail` konzentriert sich dagegen auf Transportprofile und eine dauerhafte Zustellwarteschlange. ([gitea@add-ideas.de][6]) + +--- + +## Ebene 5: Inhalte, Dokumente, Akten und Nachweise + +### Bestehende Bausteine + +* `govoplan-files` +* `govoplan-templates` +* `govoplan-dms` +* `govoplan-records` +* `govoplan-wiki` +* `govoplan-transparency` +* `govoplan-certificates` + +### Empfohlene Abgrenzung + +| Modul | Kerngegenstand | +| -------------- | -------------------------------------------------------------------------------------- | +| `files` | Binärobjekte, Dateiablage, Metadaten, Freigaben, Upload und Download | +| `templates` | Vorlagen, Platzhalter, Rendering und Ausgabevarianten | +| `dms` | Dokumentidentität, Versionen, Bearbeitungsstatus, Check-in/Check-out, Renditions | +| `records` | Aktenplan, Vorgangszusammenhang, Aufbewahrung, Aussonderung, Sperre und Archivübergabe | +| `transparency` | Veröffentlichung, Schwärzung, Auskunft und Offenlegung | +| `certificates` | ausgestellte, prüfbare Bescheinigungen und Nachweise | +| `wiki` | kooperativ gepflegtes institutionelles Wissen | + +Diese Aufteilung sollte erhalten bleiben. Sie bildet unterschiedliche fachliche Verantwortungen ab. `govoplan-files` ist bereits als generischer Datei- und Metadatendienst ausgelegt, der über Capabilities konsumiert werden soll. ([gitea@add-ideas.de][7]) + +Ein kleines GovOPlaN-System darf durchaus `files`, `dms` und `records` nativ verwenden. Eine größere Behörde kann stattdessen: + +* Binärdaten in einem externen Objektspeicher halten; +* Dokumente in einem bestehenden DMS führen; +* Aufbewahrung und Archivübergabe über ein Records-Management-System steuern; +* GovOPlaN nur als Verfahrens-, Zuständigkeits- und Nachweisschicht einsetzen. + +--- + +## Ebene 6: Daten, Berichte und Integration + +### Bestehende Bausteine + +* `govoplan-connectors` +* `govoplan-datasources` +* `govoplan-dataflow` +* `govoplan-reporting` +* `govoplan-dashboard` +* `govoplan-rest` +* `govoplan-soap` +* `govoplan-xoev` +* `govoplan-xta-osci` +* `govoplan-fit-connect` +* `govoplan-xrechnung` +* `govoplan-erp` + +### Zweck dieser Ebene + +* externe Systeme katalogisieren; +* Verbindungen und technische Erreichbarkeit verwalten; +* Datenquellen beschreiben; +* Daten beziehen und zwischenspeichern; +* Transformationen reproduzierbar ausführen; +* Datenherkunft und Versionen erhalten; +* analytische Produkte erstellen; +* Dashboards und Exporte bereitstellen; +* Verwaltungsstandards anbinden. + +Die bestehende Abgrenzung von `connectors`, `datasources`, `dataflow` und `reporting` ist fachlich überzeugend: + +* Konnektoren besitzen Verbindung, Beschaffung und technischen Zustand; +* Datenquellen besitzen Quellenidentität, Staging und Materialisierungszustände; +* Datenflüsse besitzen Transformationen, Revisionen und Herkunft; +* Reporting besitzt Auswertungsprodukte, Berichte und Exporte; +* Workflow besitzt die übergreifende Orchestrierung. ([gitea@add-ideas.de][8]) + +`govoplan-erp` sollte dabei nicht als fachliches Domänenmodul, sondern als **Konnektorfamilie** beziehungsweise Integrationsdienst klassifiziert werden. Fachliche Haushalts- oder Beschaffungssemantik darf nicht vom konkreten ERP-Anbieter abhängen. + +### Notwendige Erweiterung von `datasources` + +`govoplan-datasources` sollte langfristig nicht nur technische Datenquellen, sondern einen gesteuerten Daten- und Registerkatalog abbilden: + +* fachliche Bezeichnung; +* Datenverantwortung; +* maßgebliche Quelle; +* Rechtsgrundlage; +* Verarbeitungszweck; +* Qualitätsregeln; +* Aktualität; +* Schutzklasse; +* Übermittlungsvereinbarung; +* semantisches Modell; +* Korrekturverfahren; +* betroffene Leistungen und Prozesse; +* abhängige Berichte und Entscheidungen. + +Damit würde aus einer technischen Datenquellenverwaltung ein echter Data-Governance-Baustein. + +--- + +## Ebene 7: Fach- und Betriebsdomänen + +### Bestehende Bausteine + +* `govoplan-projects` +* `govoplan-procurement` +* `govoplan-contracts` +* `govoplan-grants` +* `govoplan-resources` +* `govoplan-assets` +* `govoplan-facilities` +* `govoplan-learning` +* `govoplan-payments` +* `govoplan-ledger` +* `govoplan-permits` +* `govoplan-inspections` +* `govoplan-evaluation` +* `govoplan-helpdesk` + +Diese Module setzen die horizontalen Fähigkeiten für bestimmte Aufgabenbereiche zusammen. + +Einige sollten echte Fachmodule bleiben. Andere sind eher Produktpakete oder Referenzkonfigurationen: + +| Bestehender Bereich | Empfehlung | +| ----------------------- | --------------------------------------------------------------------------------------------- | +| `procurement` | Eigenständiges Fachmodul für Bedarf, Verfahren und Vergabeentscheidung | +| `contracts` | Eigenständiges Fachmodul für Verpflichtungen, Fristen, Leistungen und Änderungen | +| `grants` | Eigenständiges Fachmodul für Förderprogramme und Zuwendungsfälle | +| `permits` | Fachmodul auf Basis von Leistungen, Fällen, Beteiligten und Entscheidungen | +| `inspections` | Fachmodul für Prüfobjekte, Prüfpläne, Feststellungen und Maßnahmen | +| `projects` | Zu Portfolio-, Ziel-, Abhängigkeits- und Veränderungssteuerung ausbauen | +| `evaluation` | Für Wirkungsmodelle, Evaluationsaufträge, Kriterien und Erkenntnisse | +| `helpdesk` | Eher Produktpaket über `tickets`, `cases`, `tasks`, `postbox` und `notifications` | +| `appointments` | Zunächst eher Produktpaket über `booking`, `calendar` und `scheduling` | +| `ledger` | Nur dann eigenständig ausbauen, wenn ein klarer fachlicher Buchungsgegenstand entsteht | +| `resources` | Gemeinsamer Verfügbarkeits- und Kapazitätsdienst, nicht Personalwirtschaft | +| `assets` / `facilities` | Getrennt halten, falls Anlagenlebenszyklus und räumlicher Betrieb tatsächlich unabhängig sind | + +`govoplan-ledger` und Teile der Formularlandschaft befinden sich gegenwärtig noch auf Scaffold- beziehungsweise Seed-Niveau. Das ist nicht problematisch, sollte aber im Repositorykatalog sichtbar sein; die bloße Existenz eines Repositories darf nicht als Produktreife verstanden werden. ([gitea@add-ideas.de][9]) + +--- + +## Ebene 8: Produkt- und Sektorpakete + +Diese Ebene sollte **nicht aus weiteren Laufzeitmodulen** bestehen. + +Ein Paket bündelt: + +* erforderliche Module; +* Terminologie; +* Rollenmodelle; +* Datenmodelle; +* Formulare; +* Prozessdefinitionen; +* Richtlinien; +* Ansichten; +* Berichte; +* Vorlagen; +* Konnektorprofile; +* Beispieldaten; +* Abnahmetests; +* Dokumentation; +* Migrationsregeln. + +Mögliche allgemeine Produktpakete: + +1. **Governance-Grundlage** +2. **Funktionsgebundene Zusammenarbeit** +3. **Gesteuerte Kommunikation** +4. **Verwaltungsleistung vom Antrag bis zur Entscheidung** +5. **Gremien- und Beschlussmanagement** +6. **Akten, Nachweise und Transparenz** +7. **Gesteuerte Datenanalyse und Berichtswesen** +8. **Beschaffung und Vertragssteuerung** +9. **Risiko, Kontrolle und Maßnahmen** + +Darauf können Sektorpakete aufbauen: + +* Kommune; +* Hochschule und Forschung; +* Ministerium; +* Regulierungs- und Aufsichtsbehörde; +* Fördermittelgeber; +* Infrastrukturbetreiber; +* öffentliches Gesundheitswesen. + +Ein Sektorpaket ist damit eine versionierte Referenzkonfiguration, kein Fork des Plattformkerns. + +--- + +# 3. Abgleich mit den zuvor identifizierten Bedarfsfeldern + +## A. Organisation, Aufgaben und Verantwortung + +### Bereits vorhanden + +* `organizations` +* `identity` +* `idm` +* `access` +* `tenancy` +* `policy` + +### Lücke + +Die Plattform kann Organisationseinheiten, Funktionen, Identitäten, Funktionsbesetzungen und technische Zugriffe abbilden. Es fehlt aber ein eigenständiges Modell dafür: + +* welche öffentliche Aufgabe existiert; +* aufgrund welcher Norm oder Entscheidung sie wahrgenommen wird; +* welche Stelle sachlich, örtlich und zeitlich zuständig ist; +* welche Funktion entscheidungs- oder zeichnungsbefugt ist; +* wer nur mitwirkt und wer rechenschaftspflichtig ist; +* welche Zuständigkeit übertragen oder entzogen wurde. + +### Ableitung + +Neues horizontales Modul `govoplan-mandates`. + +--- + +## B. Leistungs-, Verfahrens- und Fallmanagement + +### Bereits vorhanden + +* `portal` +* `forms` +* `forms-runtime` +* `cases` +* `tasks` +* `approvals` +* `workflow-engine` +* `permits` +* `postbox` +* `payments` + +### Lücken + +* kein zentraler Leistungskatalog; +* kein allgemeines Beteiligten- und Vertretungsmodell; +* kein allgemeines Entscheidungsobjekt; +* keine durchgängige Verbindung von Leistung, Fall, Rechtsgrundlage, Entscheidung und Ergebnis. + +### Ableitung + +Ergänzung um: + +* `govoplan-services`; +* `govoplan-parties`; +* `govoplan-decisions`. + +Danach kann beispielsweise `permits` einen Genehmigungsfall definieren, ohne selbst erneut: + +* Antragsteller; +* Bevollmächtigte; +* Zuständigkeiten; +* Formulare; +* Aufgaben; +* Entscheidungen; +* Zustellungen + +implementieren zu müssen. + +--- + +## C. Prozesse und Zusammenarbeit + +### Bereits vorhanden + +* `workflow-engine` +* `workflow` +* `tasks` +* `approvals` +* `cases` +* `views` +* `notifications` + +### Bewertung + +Konzeptionell gut abgedeckt. + +### Notwendige Schärfung + +* Workflow orchestriert, besitzt aber nicht die Fachsemantik. +* Tasks besitzt Arbeitsaufträge, nicht komplette Prozesse. +* Approvals besitzt Zustimmungsschritte, nicht die abschließende institutionelle Entscheidung. +* Views besitzt Projektionen, ist aber niemals Sicherheitsgrenze. + +`govoplan-views` beschreibt sich bereits entsprechend als gesteuerte, aufgabenbezogene Projektion; Filterung in der Oberfläche darf technische Autorisierung nicht ersetzen. ([gitea@add-ideas.de][10]) + +--- + +## D. Entscheidungen, Beschlüsse und Gremien + +### Bereits vorhanden + +* `committee` +* `poll` +* `consultation` +* `approvals` +* `audit` +* `templates` + +### Lücke + +Es fehlt ein allgemeiner, fachübergreifender Entscheidungsgegenstand. + +Ein Beschluss ist nicht dasselbe wie: + +* eine Abstimmung; +* eine Freigabe; +* ein Protokoll; +* ein Workflowstatus; +* ein PDF-Dokument. + +### Ableitung + +`govoplan-decisions` sollte das verbindliche Ergebnis besitzen, einschließlich: + +* Entscheidungsgegenstand; +* Entscheidungskompetenz; +* Sachverhalt; +* Optionen; +* Rechts- und Richtliniengrundlage; +* berücksichtigte Nachweise; +* Begründung; +* entscheidende Person oder entscheidendes Gremium; +* Bedingungen und Nebenbestimmungen; +* Wirksamkeitszeitpunkt; +* resultierende Aufträge; +* Veröffentlichung; +* Berichtigung, Aufhebung oder Widerruf; +* Rechtsbehelf oder interne Überprüfung. + +--- + +## E. Akten, Dokumente und institutionelles Gedächtnis + +### Bereits vorhanden + +* `files` +* `dms` +* `records` +* `templates` +* `audit` +* `transparency` +* `search` +* `wiki` + +### Bewertung + +Die erforderlichen Bausteine sind vorhanden. Entscheidend ist die konsequente Abgrenzung von Datei, Dokument, Akte, Nachweis und Veröffentlichung. + +### Ergänzung + +Jedes Fachobjekt sollte auf Records- und Evidence-Capabilities zugreifen können, ohne selbst Dokumentenmanagement nachzubauen. + +--- + +## F. Daten, Register und Interoperabilität + +### Bereits vorhanden + +* `connectors` +* `datasources` +* `dataflow` +* `reporting` +* technische Standardkonnektoren + +### Lücke + +Der technische Datenfluss ist konzeptionell besser ausgearbeitet als die fachliche Daten-Governance. + +### Ableitung + +`datasources` sollte erweitert werden um: + +* Register- und Datenkatalog; +* Datenverantwortung; +* fachliche Begriffe; +* Rechtsgrundlage; +* Zweckbindung; +* Qualitätszusagen; +* Berichtigungswege; +* semantische Zuordnung; +* Abhängigkeiten. + +Ein separates neues Repository ist dafür zunächst nicht zwingend erforderlich. + +--- + +## G. Risiko, Compliance, Kontrolle und Prüfung + +### Bereits vorhanden + +* `risk-compliance` +* `policy` +* `audit` +* `ops` +* `inspections` +* `evaluation` + +### Bewertung + +Die horizontale Grundlage ist vorhanden. + +### Ableitung + +Keine Sammlung isolierter Spezialmodule für: + +* Datenschutz; +* Informationssicherheit; +* KI-Governance; +* Barrierefreiheit; +* Notfallmanagement; +* Korruptionsprävention. + +Stattdessen sollte ein gemeinsames Modell verwendet werden: + +> Verpflichtung → Schutz- oder Prüfobjekt → Risiko → Kontrolle → Nachweis → Feststellung → Maßnahme → Wirksamkeitsprüfung + +Die einzelnen Regelungsbereiche werden als Regel-, Kontroll- und Berichtspakete ausgeliefert. + +Nur dort, wo ein eigener fachlicher Lebenszyklus entsteht, ist ein zusätzliches Modul gerechtfertigt. + +--- + +## H. Strategie, Portfolio und Veränderung + +### Bereits vorhanden + +* `projects` +* `evaluation` +* `reporting` +* `dashboard` +* `resources` +* `contracts` +* `procurement` + +### Lücken + +* strategische Ziele; +* öffentliche Wirkungsziele; +* Nutzenhypothesen; +* Vorhabensabhängigkeiten; +* Veränderungsbetroffenheit; +* Kapazitätskonflikte; +* Architekturentscheidungen; +* Stilllegung von Altsystemen; +* Nutzenrealisierung. + +### Ableitung + +`govoplan-projects` sollte zu einem Portfolio- und Veränderungsmodul ausgebaut werden, statt sofort weitere Repositories für Strategie, Portfolio, Ziele und Change anzulegen. + +Benötigte zusätzliche Objekte: + +* Ziel; +* Ergebnis; +* Wirkung; +* Initiative; +* Programm; +* Projekt; +* Maßnahme; +* Meilenstein; +* Abhängigkeit; +* Annahme; +* Fähigkeit; +* Ressourcenbedarf; +* Veränderungsauswirkung; +* Nutzenindikator; +* Entscheidungstor. + +Erst wenn Ziele und Wirkungen auch ohne Vorhaben von mehreren anderen Modulen intensiv verwendet werden, wäre ein eigenständiges Zielmodul gerechtfertigt. + +--- + +## I. Beschaffung, Verträge und Förderungen + +### Bereits vorhanden + +* `procurement` +* `contracts` +* `grants` +* `erp` +* `xrechnung` +* `payments` +* `ledger` +* `risk-compliance` + +### Bewertung + +Funktional breit abgedeckt. + +### Zielbild + +GovOPlaN sollte nativ insbesondere besitzen: + +* Bedarf; +* Anforderung; +* Freigaben; +* Bewertungsmatrix; +* Entscheidungsnachweise; +* Interessenkonflikte; +* Vertragspflichten; +* Fristen; +* Abnahmen; +* Änderungen; +* Lieferantenrisiken; +* Förderziele; +* Bewilligungsentscheidungen; +* Mittelabrufe und Verwendungsnachweise. + +Ein ERP oder eine Vergabeplattform kann weiterhin führen: + +* Kreditoren; +* Haushaltsbuchungen; +* Bestellungen; +* Rechnungsworkflow; +* Zahlungen; +* formale elektronische Vergabekommunikation. + +--- + +## J. Finanzen, Personal und Kapazitäten + +### Bereits vorhanden + +* `erp` +* `payments` +* `ledger` +* `resources` +* `organizations` +* `idm` +* `projects` + +### Lücken + +* Budgetrahmen; +* Mittelbindungen; +* Finanzierungsquellen; +* Stellen und Kapazitäten; +* Qualifikationen; +* zeitliche Ressourcenverfügbarkeit; +* Verbindung von Haushalt, Aufgabe, Projekt und Wirkung. + +### Ableitung + +GovOPlaN sollte keine vollständige Personalabrechnung oder öffentliche Finanzbuchhaltung nachbauen. + +Sinnvoll ist jedoch eine native Governance-Überlagerung für: + +* Budgetrahmen und verfügbare Mittel; +* Finanzierungsquellen; +* Mittelverantwortung; +* Stellen und organisatorische Kapazität; +* Qualifikationsanforderungen; +* Projekt- und Aufgabenbelastung; +* Freigabe- und Zeichnungsbefugnisse; +* Verknüpfung mit Beschlüssen und Vorhaben. + +Diese Daten können entweder nativ geführt oder aus ERP- und HR-Systemen bezogen werden. + +--- + +## K. Anlagen, Liegenschaften, Geodaten und Infrastruktur + +### Bereits vorhanden + +* `assets` +* `facilities` +* `resources` +* `addresses` +* `inspections` +* `projects` +* `contracts` + +### Lücke + +Ein gemeinsamer Geobezug und ein standardisierter GIS-Anbietervertrag fehlen. + +### Ableitung + +Zunächst keine vollständige GIS-Plattform entwickeln. Stattdessen einen gemeinsamen Geo-Vertrag definieren: + +* Punkt; +* Adresse; +* Gebiet; +* Flurstücksreferenz; +* Linien- und Netzsegment; +* Gebäude- und Raumreferenz; +* Koordinatenbezugssystem; +* externe Objektkennung; +* Karten- und Feature-Service; +* räumliche Zuständigkeit. + +Ein eigenständiges `govoplan-geo` sollte erst entstehen, wenn mindestens zwei vollständige Anwendungsfälle – etwa kommunale Leistungen und Anlagenmanagement – denselben fachlichen Geodienst benötigen. + +--- + +## L. Bürger-, Unternehmens- und Beteiligtenkommunikation + +### Bereits vorhanden + +* `portal` +* `postbox` +* `mail` +* `notifications` +* `campaign` +* `appointments` +* `consultation` +* `poll` +* `transparency` +* `addresses` +* `dist-lists` + +### Bewertung + +Dies ist einer der am weitesten ausdifferenzierten Teile der bestehenden Struktur. + +### Lücke + +Es fehlt vor allem das gemeinsame Beteiligten- und Vertretungsmodell. + +Ohne dieses Modell wissen die Kommunikationsmodule zwar, wohin etwas gesendet wird, aber nicht ausreichend: + +* in welcher Verfahrensrolle die Person handelt; +* ob sie sich selbst oder eine andere Person vertritt; +* aufgrund welcher Vollmacht sie handelt; +* ob mehrere Personen gemeinsam Beteiligte sind; +* welche Zustellungs- oder Kommunikationsregeln sich daraus ergeben. + +--- + +## M. Leistung, Wirkung und Lernen + +### Bereits vorhanden + +* `reporting` +* `dashboard` +* `evaluation` +* `dataflow` +* `projects` +* `audit` + +### Lücke + +Auswertungen sind noch nicht durchgängig mit: + +* öffentlichem Auftrag; +* Ziel; +* Leistung; +* Prozess; +* Entscheidung; +* Ressourceneinsatz; +* Ergebnis; +* gesellschaftlicher Wirkung + +verbunden. + +### Ableitung + +Reporting sollte nicht lediglich Daten visualisieren. Jeder Bericht und Indikator sollte angeben: + +* welche Fragestellung er beantwortet; +* welches Ziel oder welche Verpflichtung betroffen ist; +* welche Datenquellen und Transformationen verwendet wurden; +* welche Version gilt; +* wer für Interpretation und Aktualität verantwortlich ist; +* welche Entscheidungen ihn verwendet haben. + +--- + +# 4. Die vier noch fehlenden horizontalen Kernmodule + +## 4.1 `govoplan-mandates`: Aufgaben, Mandate, Zuständigkeiten und Verantwortung + +Dieses Modul ist für eine öffentliche Governance-Plattform zentral. + +### Es besitzt + +* öffentliche und interne Aufgaben; +* gesetzliche, satzungsrechtliche oder organisatorische Mandate; +* sachliche Zuständigkeiten; +* örtliche Zuständigkeiten; +* zeitliche Zuständigkeiten; +* Entscheidungskompetenzen; +* Zeichnungs- und Freigabebefugnisse; +* Verantwortlichkeitszuordnungen; +* Beteiligungs- und Mitwirkungspflichten; +* Rechts- und Organisationsgrundlagen; +* Delegation von Befugnissen, soweit diese über bloße Funktionsvertretung hinausgeht; +* historische Zuständigkeitsstände. + +### Es besitzt nicht + +* Organisationseinheiten selbst; +* Personen; +* technische Konten; +* technische Berechtigungen; +* Richtlinieninhalte; +* Verfahrensfälle. + +### Klare Zuständigkeitskette + +| Frage | Zuständiges Modul | +| -------------------------------------------------------- | --------------------- | +| Welche Organisationseinheit oder Funktion existiert? | `organizations` | +| Welche Identität existiert? | `identity` | +| Wer besetzt oder vertritt die Funktion? | `idm` | +| Welche Aufgabe und Befugnis gehört zur Funktion? | `mandates` | +| Mit welchem Konto wird gehandelt? | `access` | +| Ist die konkrete Handlung im aktuellen Kontext zulässig? | `policy` und `access` | +| Wie wurde die Handlung nachgewiesen? | `audit` | + +Damit wird der wichtige Unterschied zwischen **organisatorischer Stellung**, **fachlicher Zuständigkeit** und **technischer Berechtigung** ausdrücklich modelliert. + +--- + +## 4.2 `govoplan-services`: Leistungen und Leistungsversprechen + +Dieses Modul beschreibt, was eine Institution gegenüber Bürgern, Unternehmen, anderen Einrichtungen oder internen Nutzern leistet. + +### Es besitzt + +* Leistung; +* Leistungsvariante; +* Zielgruppe; +* Zugangsvoraussetzung; +* Rechtsgrundlage; +* benötigte Nachweise; +* Gebühren; +* Fristen; +* Eingangskanäle; +* verantwortliche Organisation und Funktion; +* zuständige Gebietseinheit; +* Formularbezug; +* zu erzeugenden Falltyp; +* Prozess- oder Workflowbezug; +* mögliche Ergebnisse; +* Ausgabedokumente; +* Rechtsbehelfsinformationen; +* Service- und Qualitätszusagen; +* Veröffentlichungsinformationen. + +### Es besitzt nicht + +* den konkreten Fall; +* den konkreten Antrag; +* die beteiligten Personen; +* die Entscheidung; +* die Portaldarstellung selbst. + +### Nutzen + +Dieses Modul verbindet erstmals: + +> Leistungskatalog → Portal → Formular → Beteiligte → Fall → Aufgaben → Entscheidung → Zustellung → Wirkung + +Es kann Daten aus externen Leistungskatalogen importieren, aber auch nativ Leistungen führen, die nicht in übergreifenden Katalogen enthalten sind, beispielsweise: + +* universitätsinterne Verwaltungsleistungen; +* Gremienservices; +* Forschungsservices; +* Personal- und IT-Services; +* kommunale freiwillige Leistungen. + +--- + +## 4.3 `govoplan-parties`: Beteiligte, Beziehungen und Vertretung + +`identity` beantwortet, **wer** jemand ist. `parties` beantwortet, **in welcher Rolle und Beziehung** jemand an einem konkreten Vorgang beteiligt ist. + +### Es besitzt + +* Beteiligtenrolle; +* Antragsteller; +* Adressat; +* Begünstigter; +* Verpflichteter; +* Eigentümer; +* Betreiber; +* Zeuge; +* Gutachter; +* Bevollmächtigter; +* gesetzlicher Vertreter; +* Sorgeberechtigter; +* Betreuung; +* gemeinsame Antragsteller; +* Haushalts- oder Bedarfsgemeinschaft; +* Konsortium; +* Vertretungsumfang; +* Vollmachtsnachweis; +* Gültigkeitszeitraum; +* Zustellungsbevollmächtigung; +* bevorzugte und zulässige Kommunikationswege. + +### Es besitzt nicht + +* ein vollständiges Melderegister; +* ein Unternehmensregister; +* ein Kundenstammsystem; +* Authentifizierung; +* technische Rechte. + +Externe Personen- und Organisationsregister können führend bleiben. GovOPlaN führt nur die für das Verfahren erforderliche Referenz und Beteiligtenbeziehung. + +--- + +## 4.4 `govoplan-decisions`: Entscheidungen und ihre Wirkungen + +Dieses Modul macht Entscheidungen zu erstklassigen, verknüpfbaren Governance-Objekten. + +### Es besitzt + +* Entscheidungsgegenstand; +* Entscheidungstyp; +* zuständige Funktion oder zuständiges Gremium; +* Entscheidungsentwurf; +* geprüfte Optionen; +* Sachverhaltsstand; +* Nachweise; +* Rechts- und Richtliniengrundlage; +* Begründung; +* Tenor beziehungsweise Ergebnis; +* Bedingungen; +* Wirksamkeit; +* Folgeaufträge; +* externe Wirkungen; +* Zustellung; +* Veröffentlichung; +* Überprüfung; +* Berichtigung; +* Rücknahme; +* Widerruf; +* Aufhebung; +* Rechtsbehelfsbezug. + +### Abgrenzung + +| Objekt | Bedeutung | +| ----------- | ---------------------------------------------------------------------------------- | +| `approval` | Eine Person oder Funktion stimmt einem Schritt oder einer Aktion zu. | +| `poll` | Stimmen oder Meinungsbilder werden erhoben. | +| `committee` | Ein Gremium und seine Sitzungen werden organisiert. | +| `workflow` | Arbeitsschritte werden koordiniert. | +| `decision` | Ein verbindliches institutionelles Ergebnis wird festgestellt und wirksam gemacht. | + +Ein Gremienbeschluss, eine Vergabeentscheidung, eine Förderbewilligung, eine Genehmigung und eine interne Architekturentscheidung können damit dieselbe Grundstruktur verwenden. + +--- + +# 5. Konkrete IDM-Ableitung + +Die bestehende Aufteilung ist grundsätzlich tragfähig: + +* `govoplan-identity` führt normalisierte Identitäten und deren Verknüpfung mit Plattformkonten; +* `govoplan-organizations` führt Organisationsstrukturen, Einheiten und Funktionen; +* `govoplan-idm` führt Funktionszuordnungen, Delegationen und Synchronisation; +* `govoplan-access` führt Konten, Anmeldung, Sitzungen, API-Schlüssel, Rollen und technische Rechte; +* `govoplan-tenancy` führt den Mandantenlebenszyklus und die Mandantenauflösung. ([gitea@add-ideas.de][11]) + +## Erforderliche Neupositionierung von `govoplan-idm` + +`govoplan-idm` sollte nicht primär als „Konnektor zu externen IDM-Systemen“ beschrieben werden. + +Die passendere Definition lautet: + +> Verwaltung des Identitätslebenszyklus, der institutionellen Funktionszuordnungen, Delegationen und Bereitstellungsprozesse – wahlweise nativ, föderiert oder synchronisiert. + +### Native Funktionen + +* Anlegen und Zusammenführen von Identitäten; +* Eintritt, Wechsel und Austritt; +* Kontenanträge; +* Funktionsbesetzung; +* zeitliche Zuordnung; +* Vertretung; +* kommissarische Wahrnehmung; +* Delegation; +* Funktionsvakanz; +* Rollen- und Gruppenabbildung; +* Bereitstellungsaufträge; +* Genehmigung von Berechtigungsänderungen; +* Synchronisationsvorschau; +* Konflikterkennung; +* Abstimmung und Fehlerkorrektur; +* periodische Rezertifizierung; +* Entzug bei Fristablauf; +* Notfall- und Wiederherstellungsverfahren. + +### Unterstützte Betriebsweisen + +#### 1. Vollständig lokal + +Geeignet für kleine Einrichtungen oder einzelne Installationen: + +* lokale Konten; +* lokale Identitäten; +* lokale Organisationsfunktionen; +* lokale Rollen und Berechtigungen. + +#### 2. Externe Anmeldung, lokale Governance + +* Anmeldung über OIDC oder SAML; +* Identitäten werden extern bestätigt; +* Funktionen, Delegationen, Mandate und Anwendungsrechte werden lokal geführt. + +Das dürfte für viele öffentliche Einrichtungen der wichtigste Modus sein. + +#### 3. Externes Verzeichnis mit Synchronisation + +* LDAP, Active Directory oder SCIM als Quelle; +* GovOPlaN übernimmt Identitäten und Konten; +* lokale Verantwortungs- und Funktionsdaten werden ergänzt; +* Änderungen werden abgeglichen. + +#### 4. Externe Stammdaten, GovOPlaN als Governance-Überlagerung + +* HR-System ist führend für Beschäftigungsverhältnis; +* Verzeichnis ist führend für technische Konten; +* GovOPlaN ist führend für Funktion, Delegation, Mandat und fachliche Berechtigungsableitung. + +#### 5. GovOPlaN als Bereitstellungsdrehscheibe + +* Freigaben erfolgen in GovOPlaN; +* Konten und Gruppen werden extern bereitgestellt; +* GovOPlaN verfolgt Soll-, Übermittlungs- und Ist-Zustand; +* Abweichungen werden sichtbar gemacht. + +## Was GovOPlaN nicht selbst entwickeln sollte + +Auch bei einem nativen IDM sind folgende Bereiche eher integrationspflichtig: + +* vollständiger LDAP- oder Active-Directory-Ersatz; +* Endgeräteverwaltung; +* Mobile-Device-Management; +* umfassendes Privileged-Access-Management; +* vollständige Public-Key-Infrastruktur; +* Zertifizierungsstelle; +* Passworttresor; +* biometrische Authentifizierung; +* hoch spezialisierte Fraud- und Risk-Authentication; +* Personalabrechnung. + +Der Mehrwert von GovOPlaN liegt nicht in der Nachbildung aller Enterprise-IAM-Funktionen. Er liegt in der **institutionellen Bedeutung von Funktionen, Delegationen, Mandaten und daraus abgeleiteten Rechten**. + +--- + +# 6. Welche Fähigkeiten nativ, hybrid oder überwiegend extern sein sollten + +## Nativ besonders sinnvoll + +| Fähigkeit | Begründung | +| ---------------------------------------- | ------------------------------------------------------------------ | +| Organisationsstrukturen und Funktionen | Unmittelbarer Bestandteil des Governance-Modells | +| Aufgaben, Mandate und Zuständigkeiten | In Standardsoftware meist nur unzureichend abgebildet | +| Funktionsbesetzung und Delegation | Starker öffentlich-institutioneller Bezug | +| Richtlinien und Entscheidungskompetenzen | Für alle Module erforderlich | +| Leistungen und Leistungskatalog | Verbindet Portal, Verfahren, Verantwortung und Wirkung | +| Beteiligten- und Vertretungsmodell | Zentrale Voraussetzung rechtssicherer Verfahren | +| Fälle, Aufgaben und Freigaben | Allgemeine Arbeitsgrundlage | +| Entscheidungen | Kern der institutionellen Nachvollziehbarkeit | +| Funktionspostfächer | Stark an Organisation und Vertretung gebunden | +| Kampagnen-Governance | Empfängergrundlage, Freigabe und Nachweis sind plattformspezifisch | +| Risiko, Kontrollen und Maßnahmen | Querschnittlich mit allen GovOPlaN-Objekten verknüpft | +| Projekt- und Portfoliosteuerung | Benötigt institutionelle Abhängigkeiten und Verantwortung | +| Vertrags- und Fördersteuerung | Governance-Kontext ist wichtiger als reine Dokumentablage | +| Akten- und Nachweiskontext | Muss Fachobjekte und Entscheidungen verbinden | + +## Hybrid besonders sinnvoll + +| Fähigkeit | Nativer Anteil | Externer Anteil | +| ------------------------------- | ------------------------------------------------- | ----------------------------------------------- | +| IDM | Funktionen, Delegationen, Freigaben, Sollzustände | Authentifizierung, Verzeichnisse, HR-Stammdaten | +| DMS | Dokumentkontext, Status, Verknüpfungen | Speicherung, Bearbeitung, Archivsystem | +| Dateiverwaltung | Metadaten und Berechtigungen | Objekt- oder Cloudspeicher | +| Kalender | funktionsbezogene Termine und Regeln | Groupwarekalender | +| Terminvergabe | Leistung, Terminart, Berechtigung | externe Kalender und Videokonferenzsysteme | +| Beschaffung | Bedarf, Kriterien, Entscheidung, Vertrag | Vergabeplattform und ERP | +| Finanzsteuerung | Budgetrahmen, Verantwortung, Freigaben | Buchhaltung und Zahlungsverkehr | +| Personal- und Ressourcenplanung | Funktionen, Kapazität, Qualifikationen | HR- und Abrechnungssystem | +| Berichtswesen | Herkunft, Transformation und einfache Berichte | spezialisierte BI-Plattform | +| Anlagenmanagement | Verantwortung, Prüfungen, Maßnahmen | CAFM-, GIS- und technische Systeme | +| Lernverwaltung | Pflichtqualifikationen und Governance | LMS und Campusmanagement | +| Fachverfahren | Fallkontext und übergreifende Steuerung | hoch spezialisierte Sachbearbeitung | + +## Überwiegend konnektororientiert + +GovOPlaN sollte folgende vollständige Systeme regelmäßig nicht ersetzen: + +* Finanzbuchhaltung und Haushaltsrechnung; +* Entgeltabrechnung; +* umfassende Personalwirtschaft; +* klinische Systeme; +* Campusmanagement; +* gerichtliche Fachverfahren; +* Steuer- und Zollverfahren; +* polizeiliche Einsatz- und Ermittlungssysteme; +* vollständige GIS- und CAD-Plattformen; +* industrielle Leit- und Betriebstechnik; +* E-Mail-Server und vollständige Groupware; +* formale Langzeitarchive; +* umfassende elektronische Vergabeplattformen. + +Auch hier kann GovOPlaN aber Verantwortung, Regeln, Vorhaben, Risiken, Schnittstellen, Entscheidungen und Nachweise führen. + +--- + +# 7. Korrekturen an der gegenwärtigen Modulklassifikation + +Die Architekturdokumentation unterscheidet bereits: + +* Plattformmodule; +* Dienstmodule; +* Fachmodule; +* Konnektormodule. + +Der maschinenlesbare beziehungsweise tabellarische Repositoryindex verwendet dagegen derzeit im Wesentlichen nur `system`, `module` und `connector` sowie die Unterteilung `platform` und `domain`. Dadurch erscheinen wiederverwendbare Dienste und querschnittliche Governance-Funktionen teilweise als Fachdomänen. ([gitea@add-ideas.de][12]) + +## Empfohlene Metadaten + +```yaml +kind: module +module_type: service +layer: communication +maturity: vertical-slice + +source_modes: + - native + - external + - mirror + - synchronized + - governance-overlay + +owns: + - delivery_profiles + - delivery_attempts + - durable_outbox + +does_not_own: + - recipients + - campaign_semantics + - institutional_postboxes + +capabilities: + provides: + - mail.transport + - mail.delivery_status + requires: + - access.actor_context + - audit.evidence +``` + +## Sinnvolle Klassifikation + +### Plattformmodule + +* tenancy +* access +* identity +* organizations +* idm +* mandates +* policy +* audit +* risk-compliance +* admin +* ops +* views +* search + +### Wiederverwendbare Dienstmodule + +* files +* templates +* mail +* notifications +* addresses +* dist-lists +* calendar +* booking +* resources +* dataflow +* datasources +* reporting + +### Fach- und Arbeitsmodule + +* services +* parties +* cases +* tasks +* approvals +* decisions +* campaign +* committee +* consultation +* projects +* procurement +* contracts +* grants +* permits +* inspections + +### Konnektoren + +* ERP +* DMS-Anbieter +* FIT-Connect +* XÖV +* XTA/OSCI +* REST +* SOAP +* XRechnung +* LDAP +* Active Directory +* SCIM +* OIDC +* externe Kalender +* GIS +* Fachverfahren + +`ERP` sollte daher im Katalog nicht als fachliche Domäne erscheinen. Mail, Files, Templates oder Notifications sollten nicht als gewöhnliche Domainmodule geführt werden. + +--- + +# 8. Repositorygrenzen und Konsolidierung + +## Logische Modularität ist nicht gleich Repositoryzahl + +Ein eigener Capability-Vertrag oder ein eigenständiges Fachobjekt verlangt nicht automatisch ein neues Repository. + +Ein neues Repository sollte erst entstehen, wenn mindestens die meisten der folgenden Kriterien erfüllt sind: + +1. **Eigenständige Datenhoheit:** Das Modul besitzt klar definierte Objekte. +2. **Eigenständige Installierbarkeit:** Es kann sinnvoll aktiviert oder deaktiviert werden. +3. **Eigene technische Bestandteile:** Eigene Migrationen, APIs, Rechte, Hintergrundaufgaben oder Oberflächen. +4. **Eigener Veröffentlichungszyklus:** Änderungen müssen unabhängig ausgeliefert werden können. +5. **Eigenständiges Sicherheitsprofil:** Das Modul hat besondere Berechtigungs- oder Schutzanforderungen. +6. **Mehrere Verbraucher:** Andere Module nutzen seine Capabilities. +7. **Nachgewiesener Referenzprozess:** Mindestens ein vollständiger Anwendungsfall funktioniert damit. + +Andernfalls sollte die Funktion zunächst entstehen als: + +* Capability innerhalb eines bestehenden Moduls; +* Teilmodul; +* Plugin; +* Konfigurationspaket; +* Profil; +* gemeinsamer Datentyp. + +## Konkrete Fälle + +### `forms` und `forms-runtime` + +Die fachliche Trennung von Definition und Laufzeit ist sinnvoll. Solange der Runtime-Teil jedoch noch keine eigenständige, stabile Lebensdauer besitzt, können beide gemeinsam ausgeliefert werden. Ein separates Repository ist erst zwingend, wenn: + +* andere Module den Runtime-Dienst unabhängig verwenden; +* eigene Skalierung nötig ist; +* Submission-Daten getrennt geschützt werden; +* unterschiedliche Veröffentlichungszyklen entstehen. + +### `helpdesk` + +Ein Helpdesk benötigt im Wesentlichen: + +* Tickets; +* Fälle; +* Aufgaben; +* Funktionspostfach; +* Benachrichtigungen; +* Wissensartikel; +* Service-Level-Regeln; +* Auswertungen. + +Das spricht zunächst für ein **Helpdesk-Paket** und nicht für eine parallele fachliche Infrastruktur. + +### `appointments` + +Terminverwaltung kann zunächst ein Paket aus: + +* Leistung; +* Terminart; +* Kalender; +* Verfügbarkeit; +* Buchung; +* Benachrichtigung; +* Beteiligtenbezug + +sein. Ein eigenes Fachmodul ist erst erforderlich, wenn Terminserien, Vorprüfungen, Check-in, Wartelisten oder besondere rechtliche Lebenszyklen eigenständige Datenhoheit begründen. + +### `addresses` und `dist-lists` + +Beide dürfen eigenständige Capability-Anbieter bleiben. Sie müssen aber nicht zwingend als separate, für Anwender sichtbare Produktmodule erscheinen. + +--- + +# 9. Reifestufen statt bloßer Repositoryexistenz + +Die aktuelle Roadmap weist selbst darauf hin, dass die tatsächliche Reife der Module sehr unterschiedlich ist und ein Repositoryname noch keine belastbare Implementierung belegt. ([gitea@add-ideas.de][2]) + +Deshalb sollte jedes Modul eine explizite Reifestufe tragen: + +| Reifestufe | Bedeutung | +| ------------------- | ------------------------------------------------------------------------------------------------ | +| **Concept** | Domäne und Grenzen sind beschrieben. | +| **Scaffold** | Modul ist technisch auffindbar und installierbar, besitzt aber noch keinen vollständigen Ablauf. | +| **Vertical Slice** | Ein vollständiger schmaler Anwendungsfall funktioniert. | +| **Reference Ready** | Das Modul funktioniert in einem dokumentierten Referenzpaket. | +| **Supported** | Migrationen, Tests, Betrieb, Dokumentation und Upgradepfad sind zugesichert. | +| **LTS** | Langfristige Kompatibilität und Sicherheitswartung sind definiert. | + +Zusätzlich sollte erfasst werden: + +* Referenzpakete; +* unterstützte Provider; +* bekannte Beschränkungen; +* Datenmigrationsstand; +* unterstützte Upgradepfade; +* Sicherheitsklassifikation; +* Betriebsanforderungen. + +Das verhindert, dass eine Liste von 72 Repositories äußerlich wie ein fertiges Gesamtprodukt wirkt, obwohl ein Teil bewusst nur als Architekturplatzhalter existiert. + +--- + +# 10. Verbindliche querschnittliche Verträge + +Bestimmte Anforderungen sollten nicht in jedem Modul neu erfunden werden. + +## 10.1 Zeit und Historisierung + +Jedes wesentliche Governance-Objekt benötigt: + +* fachlich gültig ab; +* fachlich gültig bis; +* im System erfasst am; +* im System ersetzt am; +* Version; +* Änderungsgrund. + +Damit lässt sich unterscheiden zwischen: + +* dem damaligen institutionellen Zustand; +* dem heutigen Wissensstand über diesen Zustand. + +## 10.2 Handelnde und vertretene Identität + +Jede relevante Handlung muss unterscheiden: + +* technisches Konto; +* natürliche handelnde Person; +* wahrgenommene Funktion; +* vertretene Person oder Organisation; +* Delegation oder Vollmacht; +* zugrunde liegendes Mandat. + +## 10.3 institutioneller Kontext + +Eine Handlung sollte, soweit einschlägig, referenzieren: + +* Mandant; +* Organisationseinheit; +* Funktion; +* Aufgabe; +* Mandat; +* Zuständigkeitsbereich; +* Fall; +* Entscheidung. + +## 10.4 Rechts- und Richtliniengrundlage + +Nicht jedes Modul muss juristische Dokumente verwalten. Es muss aber auf die maßgebliche Grundlage verweisen können: + +* Rechtsnorm; +* Satzung; +* Dienstanweisung; +* Richtlinie; +* Beschluss; +* Vertrag; +* Einwilligung. + +## 10.5 Beabsichtigte und tatsächliche Wirkung + +Bei externen oder asynchronen Operationen sind mindestens getrennt zu speichern: + +* Anforderung; +* Freigabe; +* Ausführungsabsicht; +* Übermittlungsversuch; +* Rückmeldung; +* beobachtete Wirkung; +* Abstimmungszustand. + +## 10.6 Nachweis und Herkunft + +Jede wichtige Aussage benötigt: + +* Quelle; +* Erfassungsweg; +* Version; +* Ersteller; +* Zeitpunkt; +* Vertrauensniveau; +* zugehörige Nachweise. + +## 10.7 Klassifikation, Zweck und Aufbewahrung + +Gemeinsame Metadaten: + +* Schutzklasse; +* Verarbeitungszweck; +* Zugriffsgrund; +* Aufbewahrungsregel; +* Löschsperre; +* Veröffentlichungsklasse; +* Schwärzungsbedarf. + +## 10.8 Externe Quelle und Synchronisationszustand + +Bei übernommenen Daten: + +* externes System; +* externe Kennung; +* letzte erfolgreiche Synchronisation; +* Revisionskennung; +* Aktualitätszustand; +* Konfliktzustand; +* lokale Änderungen; +* verantwortlicher Provider. + +## 10.9 Barrierefreiheit, Sprache und Darstellung + +Formulare, Vorlagen, Portalinhalte und Benachrichtigungen benötigen gemeinsame Verträge für: + +* Sprache; +* leichte beziehungsweise einfache Sprache; +* alternative Darstellungen; +* barrierefreie Bezeichnungen; +* maschinenlesbare Fehler; +* kanalabhängige Ausgabe. + +Diese Verträge sollten im Kern oder in kleinen gemeinsamen Spezifikationspaketen definiert werden. Ihre fachliche Auslegung bleibt beim jeweils zuständigen Modul. + +--- + +# 11. Empfohlene Produktpakete + +## Paket 1: Governance-Grundlage + +* tenancy +* identity +* organizations +* mandates +* idm +* access +* policy +* audit +* admin +* docs +* views + +Ergebnis: + +* nachvollziehbare Organisation; +* Funktionen und Besetzungen; +* Zuständigkeiten; +* Delegationen; +* technische Rechte; +* institutioneller Prüfpfad. + +## Paket 2: Gesteuerte Kommunikation + +* campaign +* addresses +* dist-lists +* mail +* notifications +* templates +* files +* approvals +* audit +* reporting + +Ergebnis: + +* freigegebene Empfängergrundlage; +* nachvollziehbare Serienkommunikation; +* belastbare Zustellnachweise; +* revisionsfähige Auswertung. + +## Paket 3: Funktionsgebundene Zusammenarbeit + +* postbox +* organizations +* identity +* idm +* mandates +* access +* mail +* notifications +* tasks +* views + +Ergebnis: + +* institutionelle Postfächer statt persönlicher Schattenablagen; +* stabile Zuständigkeit bei Wechsel und Vakanz; +* Delegation und Vertretung; +* aufgabenbezogene Sichten. + +## Paket 4: Leistung vom Eingang bis zur Entscheidung + +* services +* parties +* portal +* forms +* forms-runtime +* cases +* tasks +* approvals +* decisions +* postbox +* templates +* files +* records +* payments +* audit + +Ergebnis: + +* veröffentlichte Leistung; +* Antrag oder Meldung; +* Beteiligten- und Vertretungsmodell; +* Fallbearbeitung; +* Entscheidung; +* Zustellung; +* Akten- und Nachweiszusammenhang. + +## Paket 5: Beschaffung und Vertragssteuerung + +* procurement +* contracts +* parties +* decisions +* approvals +* risk-compliance +* files +* records +* ERP- und XRechnung-Konnektoren +* reporting + +## Paket 6: Gesteuerte Datenanalyse + +* datasources +* connectors +* dataflow +* reporting +* dashboard +* policy +* audit +* organizations +* mandates + +Ergebnis: + +* verantwortete Datenquellen; +* reproduzierbare Transformationen; +* nachvollziehbare Berichte; +* institutionell zugeordnete Kennzahlen. + +--- + +# 12. Sektorspezifische Pakete + +## Kommunalverwaltung + +Zusätzlich zu den horizontalen Grundlagen: + +* services +* parties +* forms-runtime +* cases +* permits +* appointments +* payments +* records +* transparency +* Geo-Provider +* Register- und Fachverfahrenskonnektoren + +## Hochschule und Forschung + +* organizations +* mandates +* identity +* idm +* committee +* projects +* grants +* learning +* certificates +* risk-compliance +* reporting +* HIS-, Campus-, Forschungs- und HR-Konnektoren + +Besonders relevant: + +* akademische Funktionen; +* Gremienmitgliedschaften; +* zeitlich begrenzte Projektrollen; +* Drittmittelverantwortung; +* Exportkontrolle; +* Berufungs- und Prüfungsverfahren. + +## Ministerium und Programmverwaltung + +* mandates +* projects +* decisions +* committee +* consultation +* grants +* contracts +* reporting +* evaluation +* records +* transparency + +## Aufsichts- und Regulierungsbehörde + +* parties +* services +* permits +* inspections +* cases +* decisions +* risk-compliance +* reporting +* records +* transparency + +--- + +# 13. Abgleich mit der bestehenden Roadmap + +Die gegenwärtige Roadmap priorisiert im Wesentlichen: + +1. Campaign als belastbaren Referenzpfad; +2. funktionsgebundene Postfächer; +3. Vorlagen und Reporting; +4. Hochschul-BI; +5. kollaborativen Dokumentenlebenszyklus; +6. eine bewusst begrenzte und optionale Workflow-Entwicklung. ([gitea@add-ideas.de][2]) + +Diese Reihenfolge sollte nicht verworfen, sondern um die fehlenden Governance-Grundobjekte ergänzt werden. + +## Phase 0: Architektur- und Portfoliobereinigung + +* Repositorybeschreibungen korrigieren; +* Modulklassen vereinheitlichen; +* Datenhoheit je Modul dokumentieren; +* Reifestufen einführen; +* Provider- und Betriebsmodelle standardisieren; +* direkte Modulimporte durch Capability-Verträge ersetzen; +* Referenzpakete maschinenlesbar beschreiben. + +Konkrete Korrekturen: + +* `tenancy` nicht mehr mit Organisationsstrukturen beschreiben; +* `organizations` nicht mehr als Eigentümer der Funktionsbesetzung darstellen; +* `identity` und `access` sprachlich klar trennen; +* `idm` als Lifecycle-, Assignment- und Provisioning-Modul positionieren; +* `risk-compliance` als querschnittliches Governance-Modul einordnen; +* `erp` als Konnektorfamilie klassifizieren. + +## Phase 1: Campaign-Referenzpaket abschließen + +Keine neue Breite erzeugen, sondern den vorhandenen End-to-End-Pfad belastbar machen: + +* Empfängerherkunft; +* Vorschau; +* Freigabe; +* dauerhafte Ausführungsabsicht; +* Versand; +* unklare Zustände; +* Abstimmung; +* Nachweise; +* Reporting; +* Wiederherstellung. + +Dieser Pfad liefert Muster für alle späteren externen Wirkungen. + +## Phase 2: Institutionelle Identitäts- und Funktionsbasis + +Zusammenführen und stabilisieren: + +* identity; +* organizations; +* idm; +* access; +* tenancy; +* postbox. + +Parallel ein minimales `mandates` einführen: + +* Aufgabe; +* Zuständigkeit; +* verantwortliche Funktion; +* rechtliche oder organisatorische Grundlage; +* Gültigkeitszeitraum. + +Damit kann das Postbox-Paket bereits auf echten institutionellen Zuständigkeiten aufbauen. + +## Phase 3: Entscheidung und Nachweis + +* `decisions` als schmalen Vertikalschnitt einführen; +* templates und reporting stabilisieren; +* Beschluss, Freigabe und externe Wirkung verbinden; +* Entscheidungskontext in Campaign, Committee und Procurement erproben. + +## Phase 4: Hochschul-BI und Data Governance + +* datasources; +* connectors; +* dataflow; +* reporting; +* dashboard. + +Ergänzen um: + +* Datenverantwortung; +* Rechtsgrundlage; +* Qualitätsstatus; +* Herkunft; +* Version; +* Verwendung in Berichten und Entscheidungen. + +## Phase 5: Dokumenten- und Aktenlebenszyklus + +* files; +* dms; +* records; +* templates; +* transparency; +* search. + +Nicht nur gemeinsame Dokumentbearbeitung umsetzen, sondern den gesamten Zusammenhang von: + +> Fachobjekt → Dokument → Version → Nachweis → Akte → Aufbewahrung → Veröffentlichung + +abbilden. + +## Phase 6: Erste allgemeine Verwaltungsleistung + +Dann erst die fehlenden Bausteine gemeinsam vertikal implementieren: + +* services; +* parties; +* forms-runtime; +* cases; +* tasks; +* approvals; +* decisions; +* portal; +* postbox; +* records. + +Als Referenzfall sollte ein überschaubares, aber vollständiges Verfahren gewählt werden, beispielsweise: + +* interne Genehmigung; +* Förderantrag; +* Veranstaltungs- oder Raumnutzungsantrag; +* einfache kommunale Erlaubnis; +* universitäre Serviceleistung. + +Damit wird nicht nur ein weiteres Modul demonstriert, sondern erstmals die allgemeine Plattformthese. + +--- + +# 14. Zusammengeführtes Zielbild + +GovOPlaN sollte selbst besitzen: + +* die institutionelle Struktur; +* Aufgaben, Mandate und Zuständigkeiten; +* Funktionen, Besetzungen und Delegationen; +* Leistungen; +* Beteiligtenbeziehungen; +* Fälle und Aufgaben; +* Entscheidungen; +* Richtlinien und Kontrollen; +* Vorhaben und Abhängigkeiten; +* Nachweis- und Aktenkontext; +* Herkunft und Wirkung externer Operationen. + +GovOPlaN sollte optional nativ ausführen: + +* Identitäts- und Berechtigungsverwaltung; +* einfache Datei- und Dokumentenverwaltung; +* Formulare; +* Fallbearbeitung; +* Workflows; +* Funktionspostfächer; +* Kommunikation; +* Termine und Buchungen; +* Projekt-, Vertrags- und Fördersteuerung; +* einfache Berichte; +* einfache Ressourcen- und Budgetrahmenverwaltung. + +GovOPlaN sollte regelmäßig anbinden: + +* ERP; +* Personalwirtschaft; +* Verzeichnisdienste; +* DMS und Archive; +* Groupware; +* GIS; +* BI-Systeme; +* Fachverfahren; +* Zahlungsdienste; +* Campus-, Klinik-, Justiz- und Infrastruktursysteme. + +Die entscheidende Produktgrenze verläuft damit nicht zwischen „in GovOPlaN“ und „außerhalb von GovOPlaN“, sondern zwischen: + +> **institutioneller Governance, die GovOPlaN verstehen und erhalten muss, und spezialisierter Ausführung, die GovOPlaN wahlweise selbst erbringt oder gesteuert an andere Systeme übergibt.** + +Für die unmittelbare Architekturarbeit würde ich daher vier neue fachliche Kernkontexte priorisieren – `mandates`, `services`, `parties` und `decisions` – und gleichzeitig die vorhandenen 72 Repositories über ein einheitliches Schema für Datenhoheit, Modultyp, Reifegrad und Betriebsmodus neu ordnen. Das schließt die entscheidenden semantischen Lücken, ohne die Plattform durch weitere unverbundene Funktionsmodule auszudehnen. + +[1]: https://git.add-ideas.de/GovOPlaN "https://git.add-ideas.de/GovOPlaN" +[2]: https://git.add-ideas.de/GovOPlaN/govoplan/src/branch/main/docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md "https://git.add-ideas.de/GovOPlaN/govoplan/src/branch/main/docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md" +[3]: https://git.add-ideas.de/add-ideas/govoplan-core "https://git.add-ideas.de/add-ideas/govoplan-core" +[4]: https://git.add-ideas.de/GovOPlaN/govoplan-risk-compliance "https://git.add-ideas.de/GovOPlaN/govoplan-risk-compliance" +[5]: https://git.add-ideas.de/GovOPlaN/govoplan-workflow "https://git.add-ideas.de/GovOPlaN/govoplan-workflow" +[6]: https://git.add-ideas.de/GovOPlaN/govoplan-postbox "https://git.add-ideas.de/GovOPlaN/govoplan-postbox" +[7]: https://git.add-ideas.de/add-ideas/govoplan-files "https://git.add-ideas.de/add-ideas/govoplan-files" +[8]: https://git.add-ideas.de/GovOPlaN/govoplan-dataflow "https://git.add-ideas.de/GovOPlaN/govoplan-dataflow" +[9]: https://git.add-ideas.de/GovOPlaN/govoplan-forms-runtime "https://git.add-ideas.de/GovOPlaN/govoplan-forms-runtime" +[10]: https://git.add-ideas.de/GovOPlaN/govoplan-views "https://git.add-ideas.de/GovOPlaN/govoplan-views" +[11]: https://git.add-ideas.de/GovOPlaN/govoplan-tenancy "https://git.add-ideas.de/GovOPlaN/govoplan-tenancy" +[12]: https://git.add-ideas.de/GovOPlaN/govoplan-core/src/branch/main/docs/MODULE_ARCHITECTURE.md "https://git.add-ideas.de/GovOPlaN/govoplan-core/src/branch/main/docs/MODULE_ARCHITECTURE.md" diff --git a/Repo-README.md b/Repo-README.md index b24f2fa..cfebc53 100644 --- a/Repo-README.md +++ b/Repo-README.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/README.md`. > Origin: `repository`. @@ -23,6 +23,9 @@ Core owns: - kernel APIs for platform metadata, module lifecycle, health, and development diagnostics - `@govoplan/core-webui`, including login, CSRF/API helpers, shell layout, generic UI components, IconRail, DataGrid, access boundaries, and module route/nav contracts +The shared DataGrid sizing and resize invariants are specified in +[`docs/DATAGRID_SIZING_CONTRACT.md`](docs/DATAGRID_SIZING_CONTRACT.md). + Platform and feature modules own their backend routers, models, migrations, permissions, frontend packages, nav items, and route contributions. Access, tenancy, policy, audit, and admin behavior live in their owning platform @@ -74,6 +77,21 @@ ENABLED_MODULES=access,campaigns /mnt/DATA/git/govoplan/.venv/bin/python -m govo The runner loads the same `GovoplanServerConfig` as `govoplan_core.server.app:app`, builds the platform registry, and passes core plus enabled module source roots to uvicorn as reload directories. After reinstalling the editable package, the same command is also available as `govoplan-devserver`. +For focused backend work, keep the complete module graph active while watching +only the module being edited. Core/config sources and explicit `--reload-dir` +paths remain watched: + +```bash +/mnt/DATA/git/govoplan/.venv/bin/python -m govoplan_core.devserver \ + --reload-module calendar \ + --reload-module campaign +``` + +Use `--reload-core-only` when no optional module source tree should trigger a +restart. Omitting both options preserves the broad default and watches every +enabled module. Startup, migration, and compatibility checks still run against +the complete enabled graph whenever the backend restarts. + The default development database is PostgreSQL at `postgresql+psycopg://govoplan_dev@127.0.0.1:5432/govoplan_dev`. Store the password in `~/.pgpass`. To force the disposable SQLite fallback, run with `GOVOPLAN_DEV_DATABASE_BACKEND=sqlite`; that database lives below `runtime/`. Local devserver runs do not require Redis. `CELERY_ENABLED` defaults to `false`, so campaign queue actions update database state without publishing Celery tasks. Use the synchronous send flow for local send tests, or set `CELERY_ENABLED=true` only when a Redis broker and worker are running. @@ -143,6 +161,10 @@ PATH=/home/zemion/.nvm/versions/node/v22.22.3/bin:$PATH /home/zemion/.nvm/versio The local host links sibling module WebUI packages through local file dependencies and Vite filesystem allowances. Release builds should use `webui/package.release.json`, which points WebUI module packages at tagged git refs. See [RELEASE_DEPENDENCIES.md](docs/RELEASE_DEPENDENCIES.md). +Production builds lazy-load enabled module descriptors and enforce initial and +asynchronous JavaScript budgets. See +[WEBUI_BUNDLE_BUDGETS.md](docs/WEBUI_BUNDLE_BUDGETS.md). + ## Module contract Backend modules register through the `govoplan.modules` entry point and return a `ModuleManifest`. A manifest can contribute: diff --git a/Repo-docs-ACTION-EFFECT-AUTOMATION-LAYER.md b/Repo-docs-ACTION-EFFECT-AUTOMATION-LAYER.md index 5705d58..a765405 100644 --- a/Repo-docs-ACTION-EFFECT-AUTOMATION-LAYER.md +++ b/Repo-docs-ACTION-EFFECT-AUTOMATION-LAYER.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/ACTION_EFFECT_AUTOMATION_LAYER.md`. > Origin: `repository`. @@ -12,7 +12,7 @@ only linear screen flows. Workflows, schedules, imports, connectors, policies, and external events all need to request governed actions without bypassing the same safety rules that apply to human users. -The first implementation should live in `govoplan-workflow` and core contracts. +The first implementation lives in `govoplan-workflow-engine` and Core contracts. Create a separate `govoplan-automation` module only if action planning, schedulers, rule execution, or cross-module automation become too broad for workflow ownership. @@ -36,6 +36,10 @@ of module capabilities. ## Action Definition An `ActionDefinition` describes something a human or system actor can request. +The versioned runtime DTOs and provider protocol live in +`govoplan_core.core.automation`; domain modules implement the protocol and +Workflow resolves providers through module capabilities rather than importing +their implementations. Recommended fields: @@ -102,6 +106,22 @@ The runner must never advance workflow state past a required side effect unless the action definition explicitly allows asynchronous completion and the pending state is visible. +For external and asynchronous effects, providers must preserve the distinction +between: + +1. requested intent; +2. approved intent; +3. dispatched command; +4. possibly executed but unconfirmed outcome; +5. confirmed observed effect; +6. reconciled, corrected, or compensated outcome. + +An API timeout after dispatch is not a failed effect and must not be retried as +a fresh command. The actor context should retain the real identity/account, +represented function or party, delegation or power, and mandate/jurisdiction +references when applicable. Domain modules remain responsible for deciding +which of those references are required for their action. + ## Failure States Automation should use explicit failure states: @@ -117,10 +137,15 @@ Automation should use explicit failure states: These states should be visible in workflow, task, and admin diagnostics. +The contract names these states explicitly as `ActionExecutionState`, alongside +`pending`, `running`, and `completed`. A provider returns observed effects even +for partial failures; the runner, not the provider, owns durable attempts, +recovery decisions, and workflow advancement. + ## Boundary Core may own stable DTOs, registry contracts, and generic audit/event hooks. -`govoplan-workflow` should own the first runner because workflow is the first +`govoplan-workflow-engine` owns the first runner because workflow is the first module that coordinates cross-module process actions. Domain modules own their own action providers. For example, templates own diff --git a/Repo-docs-CODEX-WORKFLOW.md b/Repo-docs-CODEX-WORKFLOW.md index 82b1a23..8f5d8da 100644 --- a/Repo-docs-CODEX-WORKFLOW.md +++ b/Repo-docs-CODEX-WORKFLOW.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/CODEX_WORKFLOW.md`. > Origin: `repository`. @@ -56,6 +56,15 @@ The broad writable root reduces approval churn. The explicit project trust entri Each active repository has an `AGENTS.md` file. These files define ownership, module boundaries, and focused commands for Codex. Keep durable project conventions there instead of repeating them in every prompt. +Documentation is part of the completion criteria for every behavior change. The +owning module must update its manifest-driven `DocumentationTopic` contributions +for affected user and administrator workflows, settings, permissions, +limitations, and operational consequences. Feature documentation remains in the +feature module; the optional `govoplan-docs` module projects those contributions +without importing feature internals. Every module manifest must retain a static +user and administrator baseline even when runtime providers add configured-state +details. + Use `~/.codex/config.toml` for personal defaults, auth/runtime settings, writable roots, and trust decisions. Avoid checking in absolute-path writable roots or model preferences unless they are intentionally team-wide. Use Gitea issues as the canonical backlog and state log. See `docs/GITEA_ISSUES.md` for label setup, TODO import, and Codex issue update commands. Durable docs should describe stable behavior; changing work state belongs on the issue. @@ -88,5 +97,6 @@ PATH=/mnt/DATA/git/govoplan-core/webui/node_modules/.bin:/home/zemion/.nvm/versi - Avoid broad recursive scans and full builds unless the change warrants them. - Keep generated build/test folders ignored. - Keep optional module behavior behind core registry/capability/module metadata boundaries. +- Run `tools/checks/check-manifest-shapes.py` after module behavior or manifest changes so user/admin documentation coverage remains complete. - Create or update Gitea issues for TODOs, follow-ups, blockers, and feature requests instead of keeping local backlog files. - Do not start persistent dev servers unless the user asks. diff --git a/Repo-docs-COMPATIBILITY-INVENTORY.md b/Repo-docs-COMPATIBILITY-INVENTORY.md new file mode 100644 index 0000000..2d9ddd5 --- /dev/null +++ b/Repo-docs-COMPATIBILITY-INVENTORY.md @@ -0,0 +1,50 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-core/docs/COMPATIBILITY_INVENTORY.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# GovOPlaN Compatibility Inventory + +This inventory classifies compatibility paths covered by +`COMPATIBILITY_POLICY.md`. It is intentionally limited to behavior that changes +accepted data, imports, permissions, or migration state. Operational fallbacks +such as Redis degradation and language fallback are not compatibility paths. + +## Database Bridges + +| Path | Purpose | Retention | Removal | +| --- | --- | --- | --- | +| `govoplan_core.db.migrations.reconcile_legacy_create_all_schema` | Reconciles databases created before Alembic ownership was recorded. | At least one major release after runtime aliases are removed. | Review after `1.0`; keep release-baseline tests. | +| Migration table/column aliases in `govoplan_core.db.migrations` | Detect and reconcile pre-split table ownership and migration tracks. | All tagged `0.1.x` upgrade origins plus one major release cycle. | Remove only after the corresponding baseline leaves support. | +| Access and module migration backfills for legacy permission names | Converts persisted role assignments without dropping authority. | Same as the database upgrade origin that contains the old role. | Keep migrations immutable; remove only runtime expansion at `0.2`. | + +## Portable-Schema Readers + +| Path | Purpose | Retention | Removal | +| --- | --- | --- | --- | +| `govoplan_core.mail.config.normalize_split_transport_credentials` | Reads pre-split SMTP/IMAP credentials and emits the split representation. | Current and previous two configuration schema versions. | Version-gate once Mail writes an explicit current schema version; reject inputs older than the two-version window. | +| `ImapServerConfig.discard_legacy_enabled` | Reads the former nested IMAP `enabled` field without writing it. | Current and previous two configuration schema versions. | Remove with the oldest accepted Mail configuration schema. | +| `govoplan_core.core.configuration_packages` readers | Reads explicitly versioned configuration-package manifests. | Current and previous two schema versions. | Retire individual readers as their version leaves the window. | + +## Runtime And API Aliases + +| Path | Purpose | Retention | Removal | +| --- | --- | --- | --- | +| `govoplan_core.security.scope_aliases.LEGACY_SCOPE_ALIASES` | Expands pre-granular permission names. | Tagged `0.1.x` runtime/API window. | Remove at `0.2` after role backfills and migration notes are verified. | +| `govoplan_core.security.module_permissions.LEGACY_TO_MODULE_SCOPES` | Maps pre-module-split scopes to canonical owning-module scopes. | Tagged `0.1.x` runtime/API window. | Remove at `0.2`; keep database migration evidence for one major cycle. | +| `govoplan_core.privacy.retention` | Stable import facade delegating policy-owned behavior through a capability. | Tagged `0.1.x` import window. | Remove at `0.2` after all in-tree callers use the policy contract and release notes name the replacement. | +| Legacy tenant aliases in API response schemas | Preserves active-tenant response fields used by `0.1.x` clients. | Tagged `0.1.x` API window. | Remove at `0.2` with response-schema migration notes. | +| Optional fields in Poll response references | Accepts providers built against the earlier Poll contract. | Tagged `0.1.x` runtime contract window. | Remove or require a new interface version at `0.2`. | +| Legacy single-tenant summary providers | Allows modules without the batch provider introduced in `0.1.x`. | Tagged `0.1.x` module contract window. | Remove at `0.2` after manifests advertise the batch provider contract. | + +## Removed Paths + +| Path | Reason | Removed | +| --- | --- | --- | +| `govoplan_core.core.module_installer._run_restart_command_legacy` | Private wrapper had no callers and never represented a persisted or published contract. | Current development line | +| Retired `govoplan_core.api.admin` and pre-split core model imports | In-tree callers and module packages use their owning modules; regression tests prohibit reintroduction. | Before `0.1.10` | + +Every new compatibility path must be added here with its classification, +diagnostic, test owner, and planned removal release. diff --git a/Repo-docs-COMPATIBILITY-POLICY.md b/Repo-docs-COMPATIBILITY-POLICY.md new file mode 100644 index 0000000..72baab4 --- /dev/null +++ b/Repo-docs-COMPATIBILITY-POLICY.md @@ -0,0 +1,76 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-core/docs/COMPATIBILITY_POLICY.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# GovOPlaN Compatibility Policy + +This document defines the compatibility window that release tooling, module +owners, migration authors, import/export providers, and API maintainers must +preserve. It is the source of truth for deciding whether compatibility code can +be removed. + +## Database Upgrades + +- A released installation from every tagged `0.1.x` version is a supported + database upgrade origin. +- The recorded public release-baseline ledger starts at `v0.1.7`; earlier + `0.1.x` tags predate production installations. If an earlier tagged database + is encountered, the release must provide or document a compatibility bridge + instead of silently treating the database as a fresh installation. +- Released migration revision IDs and recorded release heads are immutable. +- Each release must prove an upgrade from every still-supported recorded + baseline, as well as a fresh installation, before its tag is published. +- Migration-only reconciliation needed by an old database remains available for + at least one subsequent major release cycle after the corresponding runtime + compatibility path is removed. + +The release-baseline format and commands are documented in +`RELEASE_DEPENDENCIES.md`. + +## Configuration And Export Schemas + +- Writers emit only the current schema version. +- Readers accept the current schema version and the previous two schema + versions. +- Older input is rejected with a diagnostic that identifies its version and the + required staged upgrade or conversion path. +- A module-owned configuration provider must version its input and output + schema explicitly. It must not infer an old schema from missing fields once a + versioned schema has shipped. +- Round-trip and upgrade tests must cover all three readable versions before a + schema change is released. + +This window applies to configuration packages, module-owned exports, and other +portable GovOPlaN configuration artifacts. Domain interchange standards with +their own compatibility rules remain governed by the owning module. + +## Runtime And API Aliases + +- Compatibility aliases must emit an explicit deprecation diagnostic and point + to the supported replacement. +- New callers must use the canonical contract. In-tree callers may not add new + uses of a deprecated alias. +- Runtime imports, request fields, response fields, routes, and scope aliases + carried for the `0.1.x` split line are retired at `0.2`, with migration notes. +- An alias may be removed earlier only when it never shipped in a tag or when a + security fix requires removal. The release notes must state the exception. +- Database reconciliation code is not a runtime/API alias and follows the + longer database window above. + +## Removal Checklist + +Compatibility code can be removed only when all of the following are true: + +1. The path is inventoried as a database bridge, portable-schema reader, or + runtime/API alias. +2. Its minimum retention window has elapsed. +3. In-tree callers and published module manifests use the replacement. +4. Upgrade, import, or API regression tests cover the retained window. +5. Diagnostics and migration notes identify any staged action operators must + take. + +If one condition is not met, version-gate the compatibility path and record its +planned removal release instead of deleting it. diff --git a/Repo-docs-CONFIGURATION-PACKAGES.md b/Repo-docs-CONFIGURATION-PACKAGES.md index 8278be5..8a2dfa5 100644 --- a/Repo-docs-CONFIGURATION-PACKAGES.md +++ b/Repo-docs-CONFIGURATION-PACKAGES.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/CONFIGURATION_PACKAGES.md`. > Origin: `repository`. @@ -55,6 +55,23 @@ interface = how configured parts connect data = what the operator must provide for this deployment ``` +## Package Classes + +The same signed package mechanism supports several explicitly named classes: + +| Class | Purpose | +| --- | --- | +| `reference` | Prove a bounded journey, degraded states, recovery, and target-environment acceptance. | +| `product` | Provide a reusable operating capability such as governed communication, service-to-decision, procurement/contracts, or governed BI. | +| `sector` | Specialize terminology, forms, rules, process baselines, controls, reports, and integrations for an institutional sector without forking modules. | +| `deployment_profile` | Declare a supported infrastructure topology, operational assumptions, health gates, and recovery evidence. | +| `integration_profile` | Declare external systems, provider bindings, source-authority modes, maturity, required health, and reconciliation behavior. | + +Package class is metadata and validation context, not additional authority. A +sector package does not become a module and cannot write another module's +tables. Packages may extend other packages only through versioned fragments and +must preserve provenance and parent constraints. + ## Package Model A configuration package should be a signed, portable manifest plus module-owned @@ -75,6 +92,14 @@ Required package metadata: - preflight checks and post-import health checks - migration or transformation rules for older package versions - provenance, export source metadata, and signature metadata +- package class and optional parent package/version constraints +- source-authority bindings and provider-operation expectations for every + external integration used by the package + +Portable configuration schemas follow `COMPATIBILITY_POLICY.md`: providers +write only their current schema version and read that version plus the previous +two versions. Older input must produce a version-specific staged-upgrade +diagnostic. Configuration fragments are interpreted only by the module that owns them. For example, workflow imports workflow definitions; forms imports form schemas; diff --git a/Repo-docs-DATAGRID-SIZING-CONTRACT.md b/Repo-docs-DATAGRID-SIZING-CONTRACT.md new file mode 100644 index 0000000..b4edfce --- /dev/null +++ b/Repo-docs-DATAGRID-SIZING-CONTRACT.md @@ -0,0 +1,74 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-core/docs/DATAGRID_SIZING_CONTRACT.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# DataGrid Sizing Contract + +`DataGrid` turns every declared track into a deterministic pixel layout after +its container has a measurable width. The same contract is used on initial +layout, container resize, persisted-layout restore, and pointer resize. + +## Column Declarations + +- `width: number` or `Npx` is the preferred pixel width. +- `width: N%` is a preferred share of the measured container. +- `width: Nfr` shares residual width by fraction weight. +- `width: minmax(Npx, preferred)` combines a hard lower bound with any + supported preferred width. +- An omitted width and the legacy `fill` flag are one-fraction flexible tracks. +- `minWidth` is a hard floor. Header sort, filter, and resize controls may raise + the effective accessible floor. +- `maxWidth` bounds direct user growth and free/constrained compensation. In a + cover layout it is a preferred maximum: passive tracks may exceed it when + that is necessary to keep the table flush with its container. + +## Layout Modes + +| `initialFit` | `resizeBehavior` | Initial layout | Pointer resize | +| --- | --- | --- | --- | +| `container` | `cover` | Real columns fill the container. Hard-minimum excess scrolls horizontally. | Growth may create horizontal overflow. Shrink first consumes overflow, then grows resizable columns to the right; it stops before underflow. | +| `content` | `cover` | After measurement, the same cover invariant applies. | Same as cover above. | +| `container` | `constrained` | Real columns fill the container. | Peer compensation respects every hard min/max and stops the active resize when capacity is exhausted. | +| `content` | `free` | Declared content widths are retained. | Only the active column changes, so underflow or horizontal overflow is allowed. | +| `container` | `free` | The initial layout fills the container. | Later user resizing is free. A right-sticky column promotes this mode to cover so its edge remains stable. | + +Sticky columns do not absorb ordinary cover residuals and are not resize +compensation targets. A last resizable column may grow into overflow. It may +shrink only by the current overflow, because shrinking farther would require a +blank filler track. Dragging farther past that stop does not bank width changes: +the column remains stopped until the pointer crosses the same boundary again. + +## Persistence + +Only the pixel layout resulting from an explicit user resize is persisted. +Persisted widths are keyed by a signature containing column IDs, declared +widths and bounds, resize affordances, sticky placement, initial fit, and resize +behavior. A changed signature discards the old override and recomputes the +declared layout. + +Container reconciliation is suspended while a pointer drag is active. On +release, the already-rendered pixel layout becomes the persisted preference. +Reconciliation may grow it to prevent underflow, but never shrinks intentional +user overflow, so there is no drag-end snap. + +## Regression Matrix + +`webui/tests/data-grid-sizing.test.ts` covers: + +- pixel, percentage, fraction, `minmax`, omitted, and legacy-fill tracks; +- preferred max exhaustion without a synthetic filler column; +- hard-minimum horizontal overflow; +- fixed-only cover grids; +- persisted overrides under growth and viewport pressure; +- stale layout signatures; +- first and middle-column right-side compensation; +- last-resizable-column overflow, underflow stop, and reverse-pointer boundary; +- free, cover, and constrained resizing; +- cover-expanded tracks that already exceed preferred maxima; and +- preservation of the pointer layout across the commit fit. + +`webui/tests/data-grid-actions.test.tsx` also verifies the rendered fixed-cover +shape and guards against reintroducing a synthetic buffer cell. diff --git a/Repo-docs-DEPLOYMENT-OPERATOR-GUIDE.md b/Repo-docs-DEPLOYMENT-OPERATOR-GUIDE.md index 5f9740c..307b31e 100644 --- a/Repo-docs-DEPLOYMENT-OPERATOR-GUIDE.md +++ b/Repo-docs-DEPLOYMENT-OPERATOR-GUIDE.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/DEPLOYMENT_OPERATOR_GUIDE.md`. > Origin: `repository`. @@ -164,13 +164,15 @@ release evidence. | --- | --- | --- | | `REDIS_URL` | `redis://redis:6379/0` | Celery broker/result backend when async workers are enabled. | | `CELERY_ENABLED` | `false` | Local/dev can send synchronously. Production campaign delivery should run workers and set this to `true`. | -| `CELERY_QUEUES` | `send_email,append_sent,notifications,calendar,default` | Queue list expected by worker/process manager definitions. The Calendar queue drains durable external-calendar operations. | +| `CELERY_QUEUES` | `send_email,append_sent,notifications,mail,calendar,dataflow,workflow,postbox,events,idm,default` | Queue list expected by worker/process manager definitions. Keep this aligned with every enabled module task route; Ops reports missing worker queue consumers. | +| `PLATFORM_EVENT_OUTBOX_MAX_ATTEMPTS` | `8` | Failed durable consumer deliveries are quarantined after this many attempts. | +| `PLATFORM_EVENT_OUTBOX_TERMINAL_RETENTION_DAYS` | `90` | Successful event envelopes older than this are removed by the daily retention task. Quarantined evidence is retained. | Worker command: ```bash python -m celery -A govoplan_core.celery_app:celery worker \ - --queues send_email,append_sent,notifications,calendar,default \ + --queues send_email,append_sent,notifications,mail,calendar,dataflow,workflow,postbox,events,idm,default \ --loglevel INFO ``` @@ -194,6 +196,11 @@ python -m celery -A govoplan_core.celery_app:celery beat --loglevel INFO | `FILE_STORAGE_S3_ACCESS_KEY_ID` | empty | Secret; inject through deployment environment. | | `FILE_STORAGE_S3_SECRET_ACCESS_KEY` | empty | Secret; inject through deployment environment. | | `FILE_STORAGE_S3_BUCKET` | `files` | Managed-file object bucket. | +| `FILE_STORAGE_S3_DEPLOYMENT_MANAGED` | `false` | Reserved for the installer-owned `http://garage:3900` service. It does not authorize arbitrary internal or external S3 endpoints. | +| `FILE_ARCHIVE_MAX_ENTRIES` | `10000` | Maximum declared entries accepted during archive preview and confirmation. | +| `FILE_ARCHIVE_MAX_EXPANDED_BYTES` | `2147483648` | Maximum actual expanded bytes across selected archive content. | +| `FILE_ARCHIVE_MAX_EXPANSION_RATIO` | `100` | Maximum expanded-to-compressed archive ratio. | +| `FILE_ARCHIVE_PREVIEW_TTL_SECONDS` | `1800` | Lifetime of the sealed actor/archive/destination-bound preview token. | Legacy `S3_*` settings remain for older storage paths but new deployments should prefer `FILE_STORAGE_*`. @@ -343,7 +350,7 @@ the checked in `.env.example`. It runs: - explicit `ENABLED_MODULES` - explicit migrations and `--with-dev-data` bootstrap - API via the module-aware devserver -- a Celery worker for `send_email,append_sent,notifications,calendar,default` +- a Celery worker for `send_email,append_sent,notifications,mail,calendar,dataflow,workflow,postbox,events,idm,default` - WebUI through the Vite dev server - durable local files under `runtime/production-like/files` @@ -462,7 +469,9 @@ Run the rollback drill before relying on installer automation in a new environment: ```bash -/mnt/DATA/git/govoplan/tools/checks/module-installer-rollback-drill.py --format json +/mnt/DATA/git/govoplan/tools/checks/module-installer-rollback-drill.py \ + --format json \ + --evidence-path runtime/module-installer/restore-drill-evidence.json ``` The drill uses temporary SQLite databases and simulated package commands. It diff --git a/Repo-docs-DOCUMENTATION-MAP.md b/Repo-docs-DOCUMENTATION-MAP.md index 7debb16..8b863b3 100644 --- a/Repo-docs-DOCUMENTATION-MAP.md +++ b/Repo-docs-DOCUMENTATION-MAP.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/DOCUMENTATION_MAP.md`. > Origin: `repository`. @@ -16,11 +16,13 @@ operator, and roadmap pages. | Topic | Canonical document | Notes | | --- | --- | --- | | Module architecture and kernel contracts | `MODULE_ARCHITECTURE.md` | Stable module contracts, API efficiency contracts, durable boundary decisions, lifecycle, and WebUI contribution rules. | +| Compatibility policy | `COMPATIBILITY_POLICY.md` | Supported database upgrade origins, portable-schema read/write windows, runtime/API alias retirement, and compatibility-code removal criteria. | | RBAC and resource access | `ACCESS_RBAC_MODEL.md` | Current permission, role, API-key, and resource-access model. | | Governance hierarchy | `GOVERNANCE_MODEL.md` | System, tenant, user/group, campaign policy inheritance and admin UI structure. | | Policy decision DTOs and provenance | `POLICY_CONTRACTS.md` | Shared explain/provenance shape; module-specific policy docs should link here. | | Events and audit trace context | `EVENTS_AND_AUDIT.md` | Event dispatch semantics and audit payload conventions. | | Action/effect automation layer | `ACTION_EFFECT_AUTOMATION_LAYER.md` | Action/effect contracts, consequence preview, runner semantics, and module boundary for automation. | +| External references and integration maturity | `EXTERNAL_REFERENCES_AND_INTEGRATION_MATURITY.md` | Stable external identity and cumulative connector maturity; configured source authority is defined by the meta target architecture. | | Postbox E2EE target architecture | `POSTBOX_E2EE_ARCHITECTURE.md` | Strategic encrypted postbox/mailbox model, key ownership, role mailbox semantics, and retraction limits. | ## Release And Operations @@ -32,12 +34,14 @@ operator, and roadmap pages. | Release dependencies and catalogs | `RELEASE_DEPENDENCIES.md` | Release package refs, migration baselines, release lockfiles, catalog trust/licensing, catalog publishing, and release checklist. | | Dependency vulnerability audits | `DEPENDENCY_AUDITS.md` | Local and CI audit commands plus dated audit result notes. | | Remote WebUI bundle design | `REMOTE_WEBUI_BUNDLES.md` | Experimental controlled-deployment design; normal releases still use package builds. | +| WebUI loading and bundle budgets | `WEBUI_BUNDLE_BUDGETS.md` | Installed-module lazy boundaries, enforced initial/async budgets, and baseline measurements. | ## Product And Module Planning | Topic | Canonical document | Notes | | --- | --- | --- | | Product roadmap and module routing | `GOVOPLAN_MASTER_ROADMAP.md` | Product-level sequencing, implementation gates, issue routing, and missing-module decisions. | +| Institutional governance target | `govoplan/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md` | Cross-product semantic layers, source-authority modes, candidate Mandates/Services/Parties/Decisions boundaries, and migration sequence. | | UI/UX decisions | `UI_UX_DECISION_LEDGER.md` | Binding guided-UI decisions, open decisions, impact index, and review checklist. | | Interface ethics and design doctrine | `INTERFACE_ETHICS_AND_DESIGN_DOCTRINE.md` | Product-level doctrine for context, decision, consequence, contestability, responsibility, and traceability. | | Public-sector integration posture | `PUBLIC_SECTOR_INTEGRATION_STRATEGY.md` | Strategy index; executable target inventory lives in `govoplan-connectors`. | diff --git a/Repo-docs-EXTERNAL-REFERENCES-AND-INTEGRATION-MATURITY.md b/Repo-docs-EXTERNAL-REFERENCES-AND-INTEGRATION-MATURITY.md index 9d795dd..678e84c 100644 --- a/Repo-docs-EXTERNAL-REFERENCES-AND-INTEGRATION-MATURITY.md +++ b/Repo-docs-EXTERNAL-REFERENCES-AND-INTEGRATION-MATURITY.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/EXTERNAL_REFERENCES_AND_INTEGRATION_MATURITY.md`. > Origin: `repository`. @@ -42,6 +42,26 @@ Connectors must declare and document the maturity they actually implement. handling, deletion semantics, and observable failures. A link-only connector must not imply that GovOPlaN holds an authoritative copy. +## Source Authority Is A Separate Dimension + +Integration maturity states what an adapter is capable of doing. It does not +decide which system owns truth for a configured object or field group. A +binding separately selects one of the source-authority modes defined by the +[institutional governance target architecture](../../govoplan/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md): + +- `native_authoritative` +- `external_authoritative` +- `external_mirror` +- `governed_sync` +- `governance_overlay` +- `linked_reference` + +A connector can therefore support `synchronize` while a tenant deliberately +uses it only as an external mirror. Conversely, a native GovOPlaN object may +retain link-only references to several external systems. Authority may be +narrowed by tenant, organization, service, object type, object, field group, or +process step and must be visible in provenance and configuration preflight. + ## Domain Ownership - Domain modules own native GovOPlaN objects and their authorization. diff --git a/Repo-docs-GOVOPLAN-MASTER-ROADMAP.md b/Repo-docs-GOVOPLAN-MASTER-ROADMAP.md index 56f6067..884a087 100644 --- a/Repo-docs-GOVOPLAN-MASTER-ROADMAP.md +++ b/Repo-docs-GOVOPLAN-MASTER-ROADMAP.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/GOVOPLAN_MASTER_ROADMAP.md`. > Origin: `repository`. @@ -23,6 +23,9 @@ service and operating configurations, connected outcome stories, and capability horizons. The selected five-stage delivery sequence and its gates are in the meta repository's [Reference Journey Program](https://git.add-ideas.de/GovOPlaN/govoplan/src/branch/main/docs/REFERENCE_JOURNEY_PROGRAM.md). +The semantic target, source-authority modes, and reconciliation with the +implemented platform are in the meta repository's +[Institutional Governance Target Architecture](https://git.add-ideas.de/GovOPlaN/govoplan/src/branch/main/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md). Those product documents are canonical; this Core roadmap remains their technical sequencing and module-routing companion. @@ -71,8 +74,9 @@ verify or reverse those effects. `INTERFACE_ETHICS_AND_DESIGN_DOCTRINE.md`. - Automation must use governed action/effect contracts, not hidden side effects. The first automation layer is defined in - `ACTION_EFFECT_AUTOMATION_LAYER.md` and should start in `govoplan-workflow` - unless a separate automation module becomes justified. + `ACTION_EFFECT_AUTOMATION_LAYER.md`; its first runner lives in + `govoplan-workflow-engine`. Create a separate automation module only if the + scheduler/action runtime outgrows workflow coordination. - Encrypted postboxes are a strategic target. Early postbox, access, and identity-trust contracts should stay compatible with the E2EE architecture in `POSTBOX_E2EE_ARCHITECTURE.md`. @@ -151,8 +155,9 @@ pattern exists. | Structured forms and validation | `govoplan-forms` | | Uploaded files and managed storage | `govoplan-files` | | Case record and lifecycle | `govoplan-cases` | -| Workflow transitions and automation | `govoplan-workflow` | -| Action/effect catalogue and automation runner | first `govoplan-workflow`; possible future `govoplan-automation` if it outgrows workflow | +| Workflow runtime, transitions, and automation | `govoplan-workflow-engine` | +| Workflow definition editing | optional `govoplan-workflow` | +| Action/effect catalogue and automation runner | first `govoplan-workflow-engine`; possible future `govoplan-automation` only if it outgrows workflow | | Internal work queues and tasks | `govoplan-tasks` | | Appointment proposals and booking | `govoplan-appointments`, `govoplan-calendar` | | Postbox, email, and notifications | `govoplan-postbox`, `govoplan-mail`, `govoplan-notifications` | @@ -160,13 +165,18 @@ pattern exists. | Organizational structures, units, and functions | `govoplan-organizations` | | Identity-to-function assignments and directory synchronization | `govoplan-idm` | | Identity trust, device keys, and encrypted postbox key contracts | `govoplan-identity-trust`, `govoplan-access`, `govoplan-postbox` | -| Service directory/catalog | `govoplan-portal` | +| Service directory presentation | `govoplan-portal` | +| Versioned institutional service definition | shared service contract first; candidate `govoplan-services` after reuse proof | +| Mandate, jurisdiction, and institutional authority | shared mandate contract first; candidate `govoplan-mandates` after reuse proof | +| Procedure-local parties and representation | shared party contract first; candidate `govoplan-parties` after reuse proof | +| Formal institutional decisions | shared decision contract first; candidate `govoplan-decisions` after reuse proof | | Permit/document generation | `govoplan-templates`, `govoplan-dms` | | Payment capture and accounting handoff | `govoplan-payments`, `govoplan-ledger` | | Authentication projection, roles, permissions, acting context | `govoplan-access` | | Tenants, policy, and audit | `govoplan-tenancy`, `govoplan-policy`, `govoplan-audit` | | External software integration | `govoplan-connectors` | -| Recurring extraction and transformation | possible future `govoplan-datasources`, possible future `govoplan-dataflow` | +| Governed data/register catalogue | `govoplan-datasources` | +| Recurring extraction and transformation | `govoplan-dataflow` over Datasources and Connectors contracts | | Reports, BI, and management visibility | `govoplan-reporting` | ## Configuration And Safety Target @@ -211,8 +221,9 @@ an editor applies a high-impact configuration change. ## Reference Journeys -The active sequence is selected. Workflow remains deliberately deferred and is -not a dependency of these journeys. +The active sequence is selected. Workflow Engine and its optional editor are +now available foundations, but a reference journey does not depend on Workflow +unless its package explicitly composes and proves it. ### Journey 1: Campaign Demonstration Composition @@ -263,9 +274,11 @@ The result must preserve official-key mappings, organizational and reporting date semantics, quality findings, quarantine/replay, transparent calculation, and reproducible promotion between development, test, and production. -Reporting consumes the product. Create `govoplan-datasources` or -`govoplan-dataflow` only after the concrete path proves repeated ownership that -does not belong to connectors, Reporting, or the producing domain module. +Reporting consumes the product. Datasources owns the governed source and +materialization lifecycle; Dataflow owns typed transformation/run lineage; +Connectors owns external transport. The concrete path must now prove those +implemented boundaries and expose any missing contracts instead of recreating +them inside Reporting or a producing domain module. ### Journey 5: Collaborative Document Lifecycle @@ -343,8 +356,9 @@ Create or refine in this order: access. 4. `govoplan-cases`: case record, status, assignments, deadlines, and case evidence. -5. `govoplan-workflow`: state machine, transitions, commands, and module - handoff. +5. `govoplan-workflow-engine`: state machine, transitions, commands, module + handoff, and resumable execution; optional `govoplan-workflow` supplies the + editor. 6. `govoplan-tasks`: work queues, assignments, due dates, and follow-ups. 7. `govoplan-templates`: permit/decision document generation. 8. `govoplan-postbox`, `govoplan-mail`, `govoplan-notifications`: applicant and @@ -533,31 +547,34 @@ Refine: dashboard data. - `govoplan-search`: permissioned cross-module discovery. -Create only when justified: +Refine the existing owners: -- `govoplan-datasources`: source catalog, connection profiles, schema discovery, - freshness, provenance. -- `govoplan-dataflow`: transformations, validation, lineage, scheduled runs, - publication outputs. -- `govoplan-projects`: only if OpenProject connectors and existing cases/tasks - cannot cover the required semantics. +- `govoplan-datasources`: governed data/register catalog, live/cached/static + sources, staging, immutable materializations, freshness, quality, legal and + organizational context, and provenance. Connector profiles and credentials + remain in Connectors. +- `govoplan-dataflow`: typed transformations, validation, lineage, manual, + scheduled and event-triggered runs, reusable definitions, and publication + outputs. +- `govoplan-projects`: native projects, portfolios, milestones, goals, + dependencies, capacity, outcomes, and external OpenProject references; + Connectors owns OpenProject transport and synchronization. Reference journey: monthly data extraction, transformation, validation, approval, publication, and reporting. -Recurring extraction/transformation should start as a configuration package -across connectors, files, workflow, reporting, and templates. The package should -register sources, declare schemas, define mapping/validation versions, schedule -runs, produce previewable diffs, write governed outputs, and preserve lineage, -hashes, operator actions, and audit evidence. Create `govoplan-datasources` or -`govoplan-dataflow` only after this work exposes repeated contracts that do not -belong to existing modules. +Recurring extraction/transformation should be delivered as a configuration +package across Connectors, Datasources, Dataflow, Workflow Engine, Reporting, +Files, and Templates. The package should register sources, declare schemas, +define mapping/validation versions, schedule runs, produce previewable diffs, +write governed outputs, and preserve lineage, hashes, operator actions, and +audit evidence. Exit criteria: - connector catalog exists before building many adapters -- dataflow is created only after recurring transformation becomes product - behavior +- datasource and dataflow ownership remains provider-neutral and is proved by + the recurring transformation package - reporting consumes governed sources with provenance ## Implementation Gates @@ -598,23 +615,25 @@ in the capability waves: 4. Implement one data-backed Templates/Reporting path and safe HIS-style deep launch. 5. Extend that concrete source into one governed university analytical data - product before generalizing data-source or dataflow ownership. + product and use it to harden the existing Datasources/Dataflow ownership, + quality, lineage, and promotion contracts. 6. Implement Files-backed DMS versions and one provider-neutral collaborative editing lifecycle, then connect Records handoff. 7. Maintain already integrated Calendar/Scheduling/Poll and other foundations; activate another capability cluster only when the current journey needs it or the product roadmap explicitly reprioritizes it. -8. Resume Workflow only by explicit product decision and constrain it with - stable actions from one demonstrated package. +8. Extend Workflow Engine and the optional editor only through stable actions + and one demonstrated package at a time. ## Deliberate Deferrals Defer these until a reference journey proves the need: - full ERP replacement -- native project management beyond connector support -- an unbounded general-purpose dataflow platform; the bounded governed BI - reference journey is selected +- unsupported breadth in native project management before the Projects/OpenProject + boundary is proved in a reference journey +- unbounded Dataflow operators or execution engines without golden-flow, + quality, lineage, resource-limit, and recovery evidence - every possible public-sector protocol adapter - rich LMS behavior beyond training administration - full qualified digital signing/trust services beyond the identity-trust and @@ -637,16 +656,16 @@ repositories or to explicit missing-module decisions. | Fully UI-managed configuration with safety controls | `govoplan-admin`, `govoplan-core`, `govoplan-policy`, `govoplan-access`, `govoplan-audit` | `GovOPlaN/govoplan-core#218` | | Access as a module | `govoplan-access` | `GovOPlaN/govoplan-access#7` | | Interface ethics and decision-consequence doctrine | `govoplan-core` plus all UI-owning modules | `GovOPlaN/govoplan-core#227` | -| Action/effect automation layer | first `govoplan-workflow`; possible future `govoplan-automation` | `GovOPlaN/govoplan-workflow#1` | +| Action/effect automation layer | `govoplan-workflow-engine`; possible future `govoplan-automation` only after boundary proof | `GovOPlaN/govoplan-workflow#1` | | E2EE role/function postbox architecture | `govoplan-postbox`, `govoplan-identity-trust`, `govoplan-access`, `govoplan-policy`, `govoplan-audit` | `GovOPlaN/govoplan-postbox#15`, `GovOPlaN/govoplan-identity-trust#1` | | Identity, account, function, role, right semantic model | `govoplan-access` | `GovOPlaN/govoplan-access#9` | -| Role-based service directory/catalog | `govoplan-portal` | `GovOPlaN/govoplan-portal#1` | +| Role-based service directory presentation | `govoplan-portal`; reusable service definition is a shared contract and candidate `govoplan-services` | `GovOPlaN/govoplan-portal#1` | | Unified inbox across tasks, postbox, notifications, and portal | `govoplan-core` coordination plus owning modules | `GovOPlaN/govoplan-tasks#1`, `GovOPlaN/govoplan-notifications#1` | | OpenProject API / project management connector | `govoplan-connectors` | `GovOPlaN/govoplan-connectors#1` | -| Native project-management module decision | connector-first through `govoplan-connectors`; no native project module yet | `GovOPlaN/govoplan-core#196`, `GovOPlaN/govoplan-connectors#1` | -| Datasources for databases, CSV, files, APIs | no repository yet; start with connectors/files/reporting and create `govoplan-datasources` only after the first package proves shared source-catalog ownership | `GovOPlaN/govoplan-core#197` | -| Dataflow for pipelines, BI, publication | no repository yet; start with workflow/reporting/connectors and create `govoplan-dataflow` only after repeated pipeline/lineage contracts emerge | `GovOPlaN/govoplan-core#198` | -| Monthly datasource and transformation workflows | first as configuration package across connectors, files, workflow, reporting, and templates | `GovOPlaN/govoplan-core#216` | +| Native project-management module | `govoplan-projects`; OpenProject transport remains connector-owned | `GovOPlaN/govoplan-projects#1`, `GovOPlaN/govoplan-connectors#12` | +| Datasources for databases, CSV, files, APIs | `govoplan-datasources`, with external protocol and credential ownership in Connectors | `GovOPlaN/govoplan-datasources#1` | +| Dataflow for pipelines, BI, publication | `govoplan-dataflow` over Datasources and module-owned providers | `GovOPlaN/govoplan-dataflow#1` | +| Monthly datasource and transformation workflows | configuration package across Connectors, Datasources, Dataflow, Workflow Engine, Reporting, Files, and Templates | `GovOPlaN/govoplan#8`, `GovOPlaN/govoplan-dataflow#17` | | Templates for letters, emails, forms, reports | `govoplan-templates`, separate from reporting | `GovOPlaN/govoplan-core#190`, `GovOPlaN/govoplan-templates#1` | | Reporting and BI | `govoplan-reporting`, separate from templates | `GovOPlaN/govoplan-core#190`, `GovOPlaN/govoplan-reporting#1` | | File connectors: Nextcloud, Seafile, SMB, NFS | `govoplan-files` | `GovOPlaN/govoplan-files#15` | @@ -656,7 +675,7 @@ repositories or to explicit missing-module decisions. | Workflow module concept | `govoplan-workflow` | `GovOPlaN/govoplan-core#175` | | Connectors module concept | `govoplan-connectors` | `GovOPlaN/govoplan-core#176` | | Adrema-style address and distribution-list management | `govoplan-addresses` | `GovOPlaN/govoplan-addresses#1` | -| Consume sources and become a governed source | `govoplan-connectors` plus possible future `govoplan-dataflow` | `GovOPlaN/govoplan-connectors#3`, `GovOPlaN/govoplan-core#198` | +| Consume sources and become a governed source | Connectors acquires, Datasources governs/materializes, Dataflow transforms/publishes | `GovOPlaN/govoplan-connectors#3`, `GovOPlaN/govoplan-datasources#3` | | Governed connector configuration, dry-run, and simulation runtime | `govoplan-connectors` | `GovOPlaN/govoplan-connectors#6` | | Terminfindung and meeting scheduling polls | `govoplan-scheduling`; calendar primitives remain in calendar | `GovOPlaN/govoplan-core#193`, `GovOPlaN/govoplan-scheduling#1` | | Terminplaner and calendar primitives | `govoplan-calendar` | `GovOPlaN/govoplan-core#193`, `GovOPlaN/govoplan-calendar#1` | @@ -678,27 +697,23 @@ repositories or to explicit missing-module decisions. Boundary rationale lives in `MODULE_ARCHITECTURE.md`. Current decisions: - templates and reporting are separate modules -- RSS/source consume-publish starts in connectors; datasources/dataflow are not - repositories yet +- RSS/source consume-publish starts in Connectors; governed source identity and + snapshots belong to Datasources and transformations belong to Dataflow - calendar, scheduling, and appointments are three separate modules - forms definitions and forms runtime are separate responsibilities - OpenDesk is an integration profile across modules, not a monolithic module -- OpenProject is connector-first; no native projects module yet +- OpenProject transport is connector-owned; native portfolio/project semantics + belong to Projects - public-sector integration strategy stays in core; executable catalogue work lives in connectors - encrypted postbox and identity-trust are strategic contracts, not mail-module behavior -- automation starts as workflow-owned action/effect execution and may split into - a dedicated module only after the runner becomes broader than workflow - -The following modules are intentionally not created yet: - -- `govoplan-datasources` -- `govoplan-dataflow` -- `govoplan-projects` - -Create a repository only after a concrete implementation package proves that -existing connector, files, reporting, workflow, or task ownership is too narrow. +- automation starts in Workflow Engine and may split into a dedicated module + only after the runner becomes broader than workflow +- Mandates, Services, Parties, and Decisions begin as shared semantic contracts; + create repositories only after independent persistence, lifecycle, security, + and multiple-consumer evidence passes the repository threshold in the + institutional governance target architecture Core keeps the strategy index in `PUBLIC_SECTOR_INTEGRATION_STRATEGY.md`: integration postures, default diff --git a/Repo-docs-MODULE-ARCHITECTURE.md b/Repo-docs-MODULE-ARCHITECTURE.md index 88809bf..0c91e38 100644 --- a/Repo-docs-MODULE-ARCHITECTURE.md +++ b/Repo-docs-MODULE-ARCHITECTURE.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/MODULE_ARCHITECTURE.md`. > Origin: `repository`. @@ -20,6 +20,10 @@ Policy decision, source provenance, and explain-response contracts are tracked in [`POLICY_CONTRACTS.md`](POLICY_CONTRACTS.md). The experimental remote WebUI bundle loading design is tracked in [`REMOTE_WEBUI_BUNDLES.md`](REMOTE_WEBUI_BUNDLES.md). +The cross-product semantic layers, source-authority modes, and candidate +Mandates, Services, Parties, and Decisions boundaries are canonical in the +meta repository's +[`INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md`](../../govoplan/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md). ## Layer Model @@ -31,6 +35,36 @@ The experimental remote WebUI bundle loading design is tracked in | Business modules | Public-sector workflows | campaigns, cases, forms, approvals, appointments | | Connector modules | External system integration | FIT-Connect, XÖV/XTA, DMS/eAkte, ERP, IDM | +This table is the technical composition model. The product portfolio uses a +more detailed institutional layer model, but it does not change dependency +direction: Core provides contracts and composition; modules own semantics; +packages compose modules. + +## Institutional Semantic Boundaries + +Cross-module references must keep these answers distinct: + +- Organizations owns where structures, units, and functions exist. +- Identity owns who a subject is; Access owns accounts, roles, permissions, + and authorization decisions; IDM owns effective function assignments. +- A Mandates capability will answer why a unit or function is competent for a + task, jurisdiction, subject, or period. It must not become another RBAC + system. +- A Services capability will own versioned institutional service definitions; + Portal presents and starts them. +- A Parties capability will own procedure-local participant roles, + representation, and delivery authority; it must reference rather than copy + Identity, Organizations, and Addresses subjects. +- A Decisions capability will own formal institutional outcomes and their + authority, facts, rules, reasoning, effects, correction, and review. + Approvals owns review gates, Committee owns deliberation/votes, and Workflow + Engine owns coordination. + +Start each missing concept as a versioned DTO/provider contract used by a +bounded journey. A repository is justified only when the concept gains +independent persistence, lifecycle, security/operations behavior, release +reason, and reuse. Core must not store these domain objects. + ## Kernel Responsibilities The kernel target owns: @@ -81,6 +115,10 @@ The compatibility/deprecation plan for the current split line is: - reject new cross-module imports that bypass manifests, capabilities, events, or public module APIs +The retention windows and removal checklist for database bridges, +configuration/export schemas, and runtime/API aliases are defined in +`COMPATIBILITY_POLICY.md`. + ## Stable Kernel Contracts The following contracts are the baseline API that modules can rely on: @@ -94,20 +132,55 @@ The following contracts are the baseline API that modules can rely on: - capability factory contract - access DTO/protocol contracts in `govoplan_core.core.access` - resource ACL provider contract -- tenant summary provider contract +- bounded reference-option search provider contract +- single-tenant and optional batched tenant summary provider contracts - tenant delete-veto provider contract - WebUI module contribution contract - navigation metadata contract - command/event envelope contract - policy decision and source provenance contract in `govoplan_core.core.policy` +- external object reference and integration-maturity contract in + `govoplan_core.core.external_references` +- action/effect preview and execution contract in + `govoplan_core.core.automation` +- workflow definition contribution and runtime-worker contracts Changes to these contracts must be versioned or accompanied by compatibility shims. +Tenant list pages prefer `tenant_summary_batch_providers`. A batch provider +receives the unique tenant IDs on the current page and returns count mappings +keyed by tenant ID. Missing tenant keys mean that the provider has no counts for +that tenant; provider errors remain visible. Modules that expose only the +single-tenant contract remain compatible through a per-tenant fallback. +Destructive tenant lifecycle planning deliberately continues to use the +single-tenant path so it invokes every registered provider for the target +tenant, independent of ordinary list-page projections. + This list is the Milestone A kernel-contract freeze baseline. New module work may extend the kernel by adding explicit contracts, but existing contracts must remain source-compatible through the 0.1.x split line unless a migration shim and deprecation note are provided. +### Architecture Metadata Target + +`ModuleManifest` currently describes executable composition. It does not yet +declare the complete product-portfolio meaning of a module. A backward- +compatible manifest extension should add validated architecture metadata for: + +- module kind and institutional architecture layer; +- evidence-backed maturity claim (`concept`, `scaffold`, `vertical_slice`, + `reference_ready`, `supported`, or `lts`); +- owned and explicitly non-owned concepts; +- supported source-authority modes; +- reference packages, tested providers, and known limits; +- migration, upgrade, recovery, security, operations, and documentation + evidence references. + +Core should validate shape and project it through platform metadata. The meta +repository and release tooling should verify evidence and cross-repository +consistency. Docs and Ops may display the result. A module cannot make itself +supported solely by changing its maturity string. + Known access-related capability names are defined in `govoplan_core.core.access`, including: @@ -141,6 +214,16 @@ Other stable runtime capabilities currently include: - `calendar.outbox` and `calendar.scheduling` - `poll.scheduling` - `notifications.dispatch` +- `workflow.definitionContributions` and `workflow.runtimeWorker` + +Modules contribute reusable process baselines through +`ModuleManifest.workflow_definitions`. Each contribution pins its origin module +and version, stable key, schema and content hash, native graph/BPMN content, +governance ceilings, execution mode, and required capabilities/interfaces. +`govoplan-workflow-engine` reconciles these declarations idempotently. A module +upgrade appends a baseline revision without replacing the active revision or +mutating a local override; the optional `govoplan-workflow` package supplies +the comparison, derivation, and reset UI. ### Named Interface Contracts @@ -163,6 +246,24 @@ intended for SemVer major-version lines. Missing optional interfaces are allowed, but an installed provider with an incompatible version blocks activation because the integration would otherwise bind to an unsafe API. +### Source Authority And Provider Operations + +Integration maturity and configured authority are independent. The existing +external-reference maturity ladder describes whether an adapter can discover, +link, search, read, publish, synchronize, migrate, or replace. A binding must +also state whether GovOPlaN is native authoritative, the external system is +authoritative, GovOPlaN keeps a mirror, both sides use governed sync, GovOPlaN +adds only a governance overlay, or the object is link-only. + +A future provider declaration should compose existing contracts rather than +replace them. It will describe owned object/field groups, authority modes, +operations, revisions, freshness, health, limits, idempotency, conflicts, +outcome-unknown handling, evidence, correction/compensation, reconciliation, +outage behavior, classification, purpose, retention, and secret requirements. +Core owns the typed declaration and validation. Connectors and domain modules +own the actual protocol and domain behavior; configuration packages select the +effective mode; Docs and Ops explain the result. + Current named interfaces, generated from the source manifests by the workspace contract checks, are: @@ -270,6 +371,23 @@ unsafe methods. This avoids retransmitting unchanged snapshots. It does not identify which row changed inside a collection. +### Mutation Preconditions + +Weak response ETags are cache validators only. Mutable aggregates expose a +separate positive, monotonic revision and an opaque strong ETag generated by +`govoplan_core.core.concurrency.strong_resource_etag`. HTTP mutations send that +strong ETag in `If-Match`; capability and worker calls carry the equivalent +typed `expected_revision`. + +Core's compare-and-set primitive advances the revision in the same transaction +as the domain mutation. A missing HTTP precondition is `428 Precondition +Required`, a stale HTTP precondition is `412 Precondition Failed`, and a +domain/reconciliation conflict is `409 Conflict`. Conflict responses contain +bounded resource and revision metadata rather than the complete current +object. Modules may opt into the conservative three-way merge helper, but must +declare protected workflow, delivery, ownership, lock, evidence, signature, +and cryptographic paths that can never be merged automatically. + ### Delta Collections Collection endpoints that can expose row-level changes should use the shared @@ -340,6 +458,31 @@ full snapshot with `full: true`. A first-use `seq:0` watermark remains valid until such a floor exists, even if unrelated collections have advanced the global sequence. +### Bounded Reference Selectors + +Cross-module selectors use the module-neutral contract in +`govoplan_core.core.references`; consumers must not load an optional module's +complete directory and filter it in memory. + +- Providers receive a normalized `ReferenceSearchRequest` with `kind`, + `tenant_id`, `query`, `selected_values`, `limit`, optional opaque `cursor`, + and policy context. +- Providers apply visibility and text filtering before materializing rows and + return `ReferenceSearchPage(options, next_cursor, has_more)`. +- A page contains at most the requested bounded search results. Already-selected + references are retained in addition to that bound so historical values remain + readable and removable even when they are inactive, deleted, or outside the + current search page. +- API consumers expose `next_cursor` and `has_more`. The current searchable + selector requests the first bounded page for each query; later load-more UI + can use the same cursor without changing the provider contract. +- `access.reference_options` supplies SQL-backed account, membership, and group + searches. When it is absent, Core degrades to the legacy Access directory or + to principal-only/unavailable references without importing Access. +- The shared WebUI `apiReferenceOptionProvider` resolves selected values in + chunks of at most 200, preventing a large existing selection from turning + into an unbounded request. + ### Cursor/Keyset Pages Offset pagination remains supported for compatibility and for first page loads, @@ -592,11 +735,18 @@ Uninstall remains non-destructive unless the operator explicitly requests ## WebUI Contract -A WebUI module exports a `PlatformWebModule` from its package. The object contributes local/fallback metadata and route render functions. +A WebUI module exports a `PlatformWebModule` from its package. The object +contributes local/fallback metadata and route render functions. The package +must ship `src/module.ts` with the default contribution export: Core's Vite +host imports that descriptor directly after the backend reports the module as +enabled. This keeps package-root re-exports from pulling page implementations +into the initial shell. Example: ```ts +const FilesPage = lazy(() => import("./features/files/FilesPage")); + export const filesModule: PlatformWebModule = { id: "files", label: "Files", @@ -611,6 +761,11 @@ export const filesModule: PlatformWebModule = { }; ``` +Route pages and substantial panels must use stable lazy imports. Core supplies +the shared loading and retryable error state around route rendering. The +initial static import closure and largest asynchronous chunk are enforced by +the budgets documented in [WEBUI_BUNDLE_BUDGETS.md](WEBUI_BUNDLE_BUDGETS.md). + WebUI modules receive only the core route context: - `settings` @@ -828,7 +983,7 @@ First slice: - `govoplan-files` owns file-backed governed locations and uploaded/stored file evidence. - `govoplan-reporting` owns report/data views and scheduled outputs. -- `govoplan-workflow` owns process state, approvals, scheduling of process +- `govoplan-workflow-engine` owns process state, approvals, scheduling of process steps, and human review. Future `govoplan-datasources` is justified when GovOPlaN needs a broad source diff --git a/Repo-docs-RELEASE-DEPENDENCIES.md b/Repo-docs-RELEASE-DEPENDENCIES.md index 46ad3aa..d3cf066 100644 --- a/Repo-docs-RELEASE-DEPENDENCIES.md +++ b/Repo-docs-RELEASE-DEPENDENCIES.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/RELEASE_DEPENDENCIES.md`. > Origin: `repository`. @@ -158,7 +158,8 @@ Current tag-only module repositories: - `govoplan-search` - `govoplan-tasks` - `govoplan-templates` -- `govoplan-workflow` +- `govoplan-workflow-engine` (headless definitions, migrations, and execution) +- `govoplan-workflow` (optional authoring and inspection WebUI) - `govoplan-xoev` - `govoplan-xrechnung` - `govoplan-xta-osci` @@ -810,6 +811,12 @@ collecting release evidence. ## Migration Baselines +Release migration support follows `COMPATIBILITY_POLICY.md`: every tagged +`0.1.x` installation is a supported upgrade origin, released revision IDs are +immutable, and migration-only reconciliation remains available for at least one +subsequent major release cycle after the matching runtime compatibility path is +removed. + Development migrations may be small and numerous while a feature is moving. GovOPlaN keeps those detailed migrations on an explicit development track and publishes reviewed release shortcuts on the release track. Before a stable diff --git a/Repo-docs-THEMING.md b/Repo-docs-THEMING.md new file mode 100644 index 0000000..7179e63 --- /dev/null +++ b/Repo-docs-THEMING.md @@ -0,0 +1,34 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-core/docs/THEMING.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# WebUI Theme Contract + +GovOPlaN supports `system`, `light`, and `dark` as persisted user preferences. +`system` follows `prefers-color-scheme` live; it is not resolved permanently at +save time. Core applies the resolved mode through `data-theme` on the document +root and exposes the selected preference through `data-theme-preference`. + +## Ownership + +- Core owns semantic CSS tokens, native `color-scheme`, preference persistence, + the Settings selector, and the shared shell. +- Modules consume semantic tokens such as `--surface`, `--text`, `--line`, and + the status token families. They may define domain aliases whose values resolve + to shared tokens. +- User preference selects the mode. Tenant and system policy may provide a + future default, but must not silently replace an explicit user choice. +- Tenant branding is a separate policy surface and must preserve contrast and + status semantics in both modes. + +Do not introduce fixed foreground/background colors in a module merely to make +one mode look correct. Add or reuse a semantic Core token, then define both +light and dark values. Bitmap content and externally authored HTML are exempt, +but their surrounding controls must still use the shared tokens. + +`npm run test:theme-contract` verifies the root behavior and representative +Campaign, Calendar, Files, and Mail token consumption. The check runs before a +production WebUI build. diff --git a/Repo-docs-UI-UX-DECISION-LEDGER.md b/Repo-docs-UI-UX-DECISION-LEDGER.md index 98c2244..3dc157e 100644 --- a/Repo-docs-UI-UX-DECISION-LEDGER.md +++ b/Repo-docs-UI-UX-DECISION-LEDGER.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/UI_UX_DECISION_LEDGER.md`. > Origin: `repository`. @@ -252,6 +252,25 @@ instead of reproducing their behavior. - Feedback and confirmation use `Dialog`, `ConfirmDialog`, or `DismissibleAlert`. They never fall back to `window.alert`. +### DUE-012: Rich HTML Editing Contract + +Decision: modules that edit persisted HTML use the central +`WysiwygEditor` exported from `@govoplan/core-webui/wysiwyg`. + +- The dedicated subpath is intentional: the editor and its engine remain a + shared Core contract without adding their code to module combinations that + never consume rich-text editing. +- Consumers provide controlled HTML and domain-specific token labels. The + editor owns visual/source switching, formatting, links, images, safe URL + handling, and atomic inline token rendering; it does not own template + semantics or persistence. +- Existing HTML outside the supported visual subset opens in source mode. + Rendering the value must not rewrite it, and users receive an explicit + warning before choosing the visual surface. +- Domain placeholders remain their original serialized text. Atomic token + presentation is an editing aid only, so backend renderers and existing + templates do not need a new storage format. + #### FieldLabel Omission Register Every Core field surface that intentionally does not render `FieldLabel` is diff --git a/Repo-docs-WEBUI-BUNDLE-BUDGETS.md b/Repo-docs-WEBUI-BUNDLE-BUDGETS.md new file mode 100644 index 0000000..91c05b6 --- /dev/null +++ b/Repo-docs-WEBUI-BUNDLE-BUDGETS.md @@ -0,0 +1,78 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-core/docs/WEBUI_BUNDLE_BUDGETS.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# WebUI Loading And Bundle Budgets + +The Core WebUI host owns the loading boundary for installed module packages. +Vite discovers configured packages at build time, but emits an asynchronous +loader for each package's `src/module.ts` contribution descriptor. At runtime, +Core imports only descriptors whose backend manifests are enabled and identify +the matching `frontend.package_name`. + +The direct descriptor entry is intentional. A package root may re-export pages +for consumers; importing that barrel as module wiring can cause those pages to +be evaluated before navigation. Route pages and substantial panels should use +`React.lazy`, and Core wraps routes in the shared loading/error boundary. + +## Enforced Budgets + +`webui/bundle-budget.json` contains the production limits: + +| Measurement | Raw limit | Gzip limit | +| --- | ---: | ---: | +| Initial JavaScript static import closure | 512 KiB | 160 KiB | +| Largest individual asynchronous JavaScript chunk | 384 KiB | 110 KiB | + +`npm run build` writes a Vite manifest, measures the entry and its recursive +static imports, writes `dist/bundle-metrics.json`, and fails when either budget +is exceeded. `npm run test:module-permutations` applies the same gate to every +permutation and records the collected results in +`dist/module-permutation-bundle-metrics.json`. In CI, each result is also added +to the step summary. + +Budgets are limits, not targets. A change that approaches a limit should add a +new lazy boundary or remove unnecessary entry code instead of raising the +limit without measurement and review. + +## 2026-07-30 Baseline + +Measurements use the same full-product source tree and Node 22 runtime. The +post-change build additionally includes the Search module in the default and +full-product sets. + +| Initial-load measurement | Before | After | Reduction | +| --- | ---: | ---: | ---: | +| JavaScript assets in initial static closure | 1 | 1 | 0% | +| Raw JavaScript | 1,387,043 B | 453,769 B | 67.3% | +| Gzip level 9 | 364,767 B | 141,725 B | 61.1% | +| Brotli quality 11 | 254,797 B | 106,701 B | 58.1% | +| Parse proxy median | 18.776 ms | 7.750 ms | 58.7% | +| Parse proxy p95 | 21.980 ms | 8.739 ms | 60.2% | + +The parse proxy constructs a fresh `node:vm` `SourceTextModule` from the entry +source 30 times with a randomized source marker. It is useful for a controlled +before/after comparison, but is not enforced in CI because absolute timings +vary across runners. Transfer budgets use deterministic raw and gzip byte +counts. + +The first budgeted full-product build reported: + +- initial JavaScript: 453,769 B raw / 141,725 B gzip; +- largest async chunk: `CampaignWorkspace`, 353,724 B raw / 98,142 B gzip. + +## Verification + +```bash +cd /mnt/DATA/git/govoplan-core/webui +npm run build +npm run check:bundle-budget +npm run test:module-permutations +``` + +The build gate also catches accidental eager imports: a page pulled into the +entry closure consumes the initial budget, while an oversized page or module +descriptor consumes the asynchronous chunk budget.