PowerOn/wiki
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

cleaned servicebag and removed servicehub

Browse source
This commit is contained in:
ValueOn AG 2026-06-08 23:35:52 +02:00
parent 16760e9c89
commit cf8b42266b
1 changed files with 76 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

103
b-reference/platform-core/architecture.md
View file

@ -1,6 +1,6 @@
<!-- status: canonical -->
<!-- lastReviewed: 2026-06-05 -->
<!-- verifiedAgainst: gateway (codebase audit 2026-04-07, post Automation Unification) + Typed Action Architecture Phasen 1-5 + Infomaniak-Connector (2026-04-28) + MSFT/Google Calendar+Contacts + Reconnect (2026-04-28) + Google Voice STT/TTS (2026-05-10) + BackgroundJob i18n payload (2026-05-17) + Feature Lifecycle Hooks (2026-06-05) -->
<!-- lastReviewed: 2026-06-08 -->
<!-- verifiedAgainst: gateway (codebase audit 2026-04-07, post Automation Unification) + Typed Action Architecture Phasen 1-5 + Infomaniak-Connector (2026-04-28) + MSFT/Google Calendar+Contacts + Reconnect (2026-04-28) + Google Voice STT/TTS (2026-05-10) + BackgroundJob i18n payload (2026-05-17) + Feature Lifecycle Hooks (2026-06-05) + ServicesBag Consolidation + ServiceHub Elimination + Import Cleanup (2026-06-08) -->
# 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<Feature>/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