From cf8b42266b433af693a05b8dc5fc0c6f9f7a5f0c Mon Sep 17 00:00:00 2001 From: ValueOn AG Date: Mon, 8 Jun 2026 23:35:52 +0200 Subject: [PATCH] cleaned servicebag and removed servicehub --- b-reference/platform-core/architecture.md | 103 ++++++++++++++++------ 1 file changed, 76 insertions(+), 27 deletions(-) diff --git a/b-reference/platform-core/architecture.md b/b-reference/platform-core/architecture.md index c4876ba..e334608 100644 --- a/b-reference/platform-core/architecture.md +++ b/b-reference/platform-core/architecture.md @@ -1,6 +1,6 @@ - - + + # Gateway -- Architektur @@ -21,13 +21,14 @@ Unter `platform-core/modules/` (Kontext-Audit): | `features/` | Feature-Module (autonome Domänen): workspace, graphicalEditor, commcoach, neutralization, realEstate, trustee, teamsbot | | `interfaces/` | DB-Interfaces (App, Billing, Chat, Knowledge, Management, Subscription), AI-Objects, RBAC, Features, Messaging | | `dbHelpers/` | DB-Hilfsfunktionen (Registry, Audit-Logger, FK-Resolver, Pagination, Multi-Tenant-Optimierungen) | +| `nodeCatalog/` | Neutraler Container (L2): nodeDefinitions, portTypes, nodeAdapter, entryPoints | | `routes/` | REST-API-Routen (u. a. Admin, Billing, DataFiles, DataSources, i18n, Security, Store, System) | | `security/` | RBAC (`rbac.py`, `rbacCatalog.py`), Root-Access | -| `serviceCenter/` | Zentrale Service-Orchestrierung (Registry, Resolver, Kontext, Haupt-Services) | -| `serviceHub/` | Service-Registry und Dependency Injection (u. a. `PublicService`-Wrapper) | +| `serviceCenter/` | Zentrale Service-Orchestrierung (Registry, Resolver, Kontext, Haupt-Services, **ServicesBag**) | | `shared/` | Gemeinsame Utilities (attributeUtils, i18nRegistry, Konfiguration, Logging, …) | | `system/` | System-Konfiguration, Feature-Discovery (`registry.py`: `loadFeatureMainModules`, `loadFeatureRouters`) | -| `workflows/` | Workflow-Engine mit Methoden, Aktionen, Execution Engine und konsolidiertem Scheduler | +| `workflows/` | Workflow-Engine mit Methoden, Aktionen und konsolidiertem Scheduler | +| `workflowAutomation/` | System-Komponente (L5b Orchestrator): Graph-Editor, Execution Engine, Run-Scheduler | ## ServiceCenter (Kern-Orchestrierung) @@ -58,7 +59,51 @@ Die öffentliche API umfasst u. a. `getService(key, context)` zur Auflösung ein ### Einordnung (Framework) -Daten- und Steuerfluss: **Client oder Workflow → Service Center → Service → Interface → Connector → externes System**. Das Service Center bündelt dabei Erkennbarkeit (Registry), Konfiguration und querschnittliche Aspekte wie Logging, RBAC-Objekt-Registrierung (`registerServiceObjects`) und konsistente Service-Lebenszyklen; **`serviceHub`** ergänzt dies mit **`PublicService`**, sodass nur bewusst exponierte Methoden nach außen sichtbar sind. +Daten- und Steuerfluss: **Client oder Workflow → Service Center → Service → Interface → Connector → externes System**. Das Service Center bündelt dabei Erkennbarkeit (Registry), Konfiguration und querschnittliche Aspekte wie Logging, RBAC-Objekt-Registrierung (`registerServiceObjects`) und konsistente Service-Lebenszyklen. + +### ServicesBag (kanonischer Service-Zugriff) + +> **ARCHITEKTUR-REGEL: Es gibt genau EINEN Service-Bag -- `ServicesBag` in `serviceCenter/services/serviceAgent/mainServiceAgent.py`, exportiert via `serviceCenter/__init__.py`. KEINE Parallelstrukturen erstellen!** + +Der `ServicesBag` ist das einzige Objekt, ueber das Code auf Services zugreift. Er wird als `self.services` in Workflows, Agent-Tools, und Processing-Modulen propagiert. + +| Attribut | Typ | Zugriff | +|----------|-----|---------| +| `user` | `User` | Direkt | +| `mandateId` | `str` | Direkt | +| `featureInstanceId` | `str` | Direkt | +| `chat` | `ChatService` | Property (lazy) | +| `extraction` | `ExtractionService` | Property (lazy) | +| `rbac` | `RbacClass` | Property (lazy) | +| `getService(key)` | Service | Methode (dynamisch) | +| `canAccessService(key)` | `bool` | Methode | + +**Verbotene Patterns (NICHT verwenden):** + +1. **KEIN `ServiceHub`** -- Die alte `ServiceHub`-Klasse (`serviceCenter/serviceHub.py`) wurde eliminiert (2026-06-08). Sie exponierte rohe DB-Interfaces (`interfaceDbApp`, `interfaceDbComponent`, `interfaceDbChat`) als blanke Attribute -- unkontrollierter Zugriff ohne Service-Kapselung. +2. **KEIN `_WorkflowAutomationServiceHub`** -- Die alte parallele Service-Bag-Klasse in `workflowAutomation/` wurde eliminiert und durch `ServicesBag` ersetzt. +3. **KEIN `_ServicesAdapter`** -- Der alte Name fuer `ServicesBag`. Umbenannt 2026-06-08. +4. **KEINE blanken Interface-Properties** auf Service-Bags (z.B. `services.interfaceDbComponent`). Zugriff auf DB-Operationen erfolgt AUSSCHLIESSLICH ueber Service-Methoden (z.B. `services.chat.getFile()`, `services.chat.createFile()`). +5. **KEIN defensiver `getattr`** fuer garantierte Attribute (z.B. `getattr(services, "chat", None)` ist verboten wenn `chat` garantiert existiert). +6. **KEINE manuellen `ServiceCenterContext`-Konstruktionen** in Consumer-Code. Der Kontext wird vom ServicesBag propagiert. + +**ChatService als Kapselungsschicht:** + +Der `ChatService` (`serviceCenter/services/serviceChat/mainServiceChat.py`) kapselt alle File/Folder-CRUD-Operationen und Workflow-Listing. Consumer greifen NIE direkt auf `interfaceDbComponent` oder `interfaceDbChat` zu, sondern immer ueber `services.chat.*`: + +| Methode | Kapselt | +|---------|---------| +| `getFile(fileId)` | `interfaceDbComponent.getFile` | +| `getFileData(fileId)` | `interfaceDbComponent.getFileData` | +| `createFile(name, mime, content)` | `interfaceDbComponent.createFile` | +| `createFileData(fileId, data)` | `interfaceDbComponent.createFileData` | +| `saveUploadedFile(content, name)` | `interfaceDbComponent.saveUploadedFile` | +| `deleteFile(fileId)` | `interfaceDbComponent.deleteFile` | +| `copyFile(sourceId, newName)` | `interfaceDbComponent.copyFile` | +| `createFolder(name, parentId)` | `interfaceDbComponent.createFolder` | +| `getWorkflows(pagination)` | `interfaceDbChat.getWorkflows` | +| `getMessages(workflowId, pagination)` | `interfaceDbChat.getMessages` | +| `createActionItem(actionData)` | `interfaceDbChat._separateObjectFields` + `db.recordCreate` | ## Interfaces (DB-Schicht) @@ -173,7 +218,7 @@ Die Workflow-Engine-Models leben kanonisch in `datamodels/datamodelWorkflowAutom | `AutoStepLog` | Protokoll pro Knoten-Ausfuehrung | poweron_graphicaleditor | | `AutoTask` | Human Tasks (Formulare, Approvals) | poweron_graphicaleditor | -Die DB-Konstante `GRAPHICAL_EDITOR_DATABASE = "poweron_graphicaleditor"` ist ebenfalls dort definiert. Feature-interne Re-Exports in `features/graphicalEditor/datamodelFeatureGraphicalEditor.py` existieren fuer Backward-Kompatibilitaet. +Die DB-Konstante `WORKFLOW_AUTOMATION_DATABASE = "poweron_graphicaleditor"` ist ebenfalls dort definiert (DB-Name ist historisch, Konstante wurde umbenannt 2026-06-08). Feature-interne Re-Exports in `features/graphicalEditor/datamodelFeatureGraphicalEditor.py` existieren fuer Backward-Kompatibilitaet. ## Schlüssel-Dateien @@ -184,7 +229,7 @@ Die DB-Konstante `GRAPHICAL_EDITOR_DATABASE = "poweron_graphicaleditor"` ist ebe | `platform-core/modules/serviceCenter/context.py` | `ServiceCenterContext` pro Request | | `platform-core/modules/serviceCenter/registry.py` | Service-Registry (CORE / IMPORTABLE) | | `platform-core/modules/serviceCenter/resolver.py` | Auflösung von Service-Instanzen inkl. Cache | -| `platform-core/modules/serviceHub/__init__.py` | Hub / DI, `PublicService`-Wrapper für kontrollierte Oberflächen | +| `platform-core/modules/serviceCenter/services/serviceAgent/mainServiceAgent.py` | `ServicesBag` -- kanonischer Service-Bag fuer Workflows/Agent/Processing | | `platform-core/modules/routes/*.py` | HTTP-Endpunkte, Aufruf in Richtung Service Center / Features (inkl. `routeI18n.py` für DB-backed i18n mit AI-Übersetzung) | | `platform-core/modules/interfaces/*.py` | Stabile Verträge und DB-Zugriffe (keine direkte Vendor-Logik in Services) | | `platform-core/modules/connectors/*.py` | Vendor-spezifische Adapter (Auth, Transport, Mapping) | @@ -193,8 +238,8 @@ Die DB-Konstante `GRAPHICAL_EDITOR_DATABASE = "poweron_graphicaleditor"` ist ebe | `platform-core/modules/shared/*` | Querschnitt: Konfiguration, Audit-Logging, Events, Utilities | | `platform-core/modules/system/registry.py` | Feature-Discovery, Router-Laden, Katalog-Registrierung beim App-Start | | `platform-core/modules/workflows/workflowManager.py` | Zentrale Workflow-Steuerung (Workspace/Chat Workflows) | -| `platform-core/modules/workflows/automation2/executionEngine.py` | Graph-Execution-Engine: topoSort, Transit-Routing, `_normalizeToSchema` nach Execute, `flow.merge`-Wait, Resume-Schema-Validierung | -| `platform-core/modules/workflows/scheduler/mainScheduler.py` | Konsolidierter Workflow-Scheduler | +| `platform-core/modules/workflowAutomation/engine/executionEngine.py` | Graph-Execution-Engine: topoSort, Transit-Routing, `_normalizeToSchema` nach Execute, `flow.merge`-Wait, Resume-Schema-Validierung | +| `platform-core/modules/workflowAutomation/scheduler/mainScheduler.py` | Konsolidierter Workflow-Scheduler | | `platform-core/modules/interfaces/interfaceBootstrap.py` | System-Bootstrap (Templates, Billing, Stripe) | | `platform-core/modules/interfaces/interfaceVoiceObjects.py` | Fassade Google STT/TTS, Billing-Callback Streaming | | `platform-core/modules/connectors/connectorVoiceGoogle.py` | Google Speech v1 + Translation + TTS-Client | @@ -323,10 +368,10 @@ Seit Phase 1-5 (April 2026) folgt jede Workflow-Aktion einem strikten 4-Schichte | Schicht | Modul / Verantwortung | Type-Anker | |---------|-----------------------|------------| -| **1. Editor (Frontend)** | `ui-nyla/src/components/FlowEditor/nodes/shared/` -- `RequiredAttributePicker`, `DataPicker` (strict-mode + Object-Drill-Down mit `*`-Wildcard), `paramValidation.ts` | Action-Signaturen aus dem Catalog (`/api/automation2/catalog`) | +| **1. Editor (Frontend)** | `ui-nyla/src/components/FlowEditor/nodes/shared/` -- `RequiredAttributePicker`, `DataPicker` (strict-mode + Object-Drill-Down mit `*`-Wildcard), `paramValidation.ts` | Action-Signaturen aus dem Catalog (`/api/workflow-automation/catalog`) | | **2. Action / Method** | `platform-core/modules/workflows/methods/method/actions/*.py` (`extractFromFiles`, `processDocuments`, `syncToAccounting`, ...) | Typisierte Pydantic-Eingabe + `ActionResult`-Output, `FeatureInstanceRef` als Discriminator-Envelope | -| **3. Adapter** | `platform-core/modules/features/graphicalEditor/nodeDefinitions/registerNodeWithMethod` -- leitet Node-Definitions aus Action-Signaturen ab, liefert Snapshot fuer den Editor (`adapter_validator`) | Snapshot-Test `test_staticNodesHaveNoDriftAgainstLiveMethods` (`_KNOWN_ADAPTER_DRIFTS = frozenset()`) | -| **4. Runtime** | `platform-core/modules/workflows/automation2/executionEngine.py` -- `executeGraph` mit `materializeFeatureInstanceRefs` + `materializeConnectionRefs`, `_unwrapTypedRef` fuer Action-Calls | Migrations-Helper in `automation2/featureInstanceRefMigration.py` + DB-CLI `scripts/script_migrate_feature_instance_refs.py` | +| **3. Adapter** | `platform-core/modules/nodeCatalog/nodeDefinitions/registerNodeWithMethod` -- leitet Node-Definitions aus Action-Signaturen ab, liefert Snapshot fuer den Editor (`adapter_validator`) | Snapshot-Test `test_staticNodesHaveNoDriftAgainstLiveMethods` (`_KNOWN_ADAPTER_DRIFTS = frozenset()`) | +| **4. Runtime** | `platform-core/modules/workflowAutomation/engine/executionEngine.py` -- `executeGraph` mit `materializeFeatureInstanceRefs` + `materializeConnectionRefs`, `_unwrapTypedRef` fuer Action-Calls | Migrations-Helper in `workflowAutomation/engine/featureInstanceRefMigration.py` + DB-CLI `scripts/script_migrate_feature_instance_refs.py` | Konsequenzen: @@ -338,22 +383,26 @@ Konsequenzen: ## Layer-Hierarchie (strikte Importrichtung) ``` -shared (L0) → 0 ausgehende Imports -datamodels (L1) → nur shared -connectors (L2) → shared, datamodels -dbHelpers (L3) → shared, datamodels, connectors -interfaces (L4) → L0-L3 + security, system -system (L4) → L0-L3 -security (L4) → L0-L3 -auth (L4) → L0-L4 -serviceCenter (L5) → L0-L4 -workflows (L5) → L0-L4 + features (Deferred: WorkflowAutomation) -features (L5) → L0-L4 + serviceCenter, workflows -routes (L6) → L0-L5 -app (L7) → alle (Composition Root) +shared (L0) → 0 ausgehende Imports +datamodels (L1) → nur shared +connectors (L2) → shared, datamodels +nodeCatalog (L2) → shared, datamodels +dbHelpers (L3) → shared, datamodels, connectors +aicore (L3) → shared, datamodels, connectors +interfaces (L4) → L0-L3 + security, system, nodeCatalog +system (L4) → L0-L3 + nodeCatalog +security (L4) → L0-L3 +auth (L4) → L0-L4 +serviceCenter (L5a) → L0-L4 +workflows (L5a) → L0-L4 +features (L5a) → L0-L4 + serviceCenter, workflows +workflowAutomation (L5b) → L0-L5a (Orchestrator, darf von L5a importieren) +routes (L6) → L0-L5b +demoConfigs (L6) → L0-L5b +app (L7) → alle (Composition Root) ``` -Jede Schicht importiert NUR von niedrigeren Schichten. Ausnahmen (z.B. workflows→features) sind dokumentiert und haben einen Refactoring-Plan. +Jede Schicht importiert NUR von niedrigeren Schichten. `workflowAutomation` (L5b) ist der Orchestrator ueber `workflows`/`serviceCenter`/`features` — Imports VON L5a NACH L5b sind VERBOTEN (keine Rueckkanten). Alle frueheren Violations (interfaces→WA, system→WA, serviceCenter→WA, workflows↔serviceCenter bidirektional) sind seit 2026-06-08 geloest. ## Regeln / Invarianten