> Grundsatz: Erst Plattformbasis reparieren, dann Plugin-Grenze, dann Frontend, DANACH erst Einzelbugs.
> Alle ARCH-IDs + neue Findings sind explizit einem Block zugeordnet. Nichts hängt mehr in der Luft.
## LEITBILD (bindend für alle Blöcke)
Dieses Projekt ist KEINE CRM-Anwendung, sondern eine **Business- & Agenten-Plattform**:
- Der Core ist ein **Plattform-Kernel**: Multi-Tenant, Auth/Permissions, Plugin-System, Events, Workflows, AI-Agent-Laufzeit.
- **Fachmodule (CRM heute, ERP-Module später) sind ausschließlich Plugins** — nachrüstbar, deaktivierbar, ohne Core-Änderung.
- **Agenten sollen die Software VOLL bedienen können** — jede Plugin-Funktion muss automatisch agenten-bedienbar werden, ohne dass der Core angefasst wird.
- Konsequenz als Prüfregel für JEDEN Task: *"Kann ein neues Fachmodul diese Funktion nutzen, ohne eine Core-Datei zu ändern?"* — Wenn nein, ist der Task falsch geschnitten.
---
## 0. Korrigierte Statistik (v1 war falsch)
| Angabe | v1 (falsch) | v2 (korrekt) |
|---|---|---|
| Bugs gesamt | 148 | **139 eindeutige IDs** |
| Offen | 113 | **108 eindeutig** (31 High / 56 Medium / 21 Low nach Duplikat-Entfernung) |
## 1. Was gegenüber v1 geändert wurde (ChatGPT-Review, alle 16 Punkte)
1.**Statistik korrigiert** (siehe oben), alle Duplikate entfernt.
2.**Phase 0 (Agent Zero Config) gestrichen** — deepseek-v4-pro/ministral/Vision gehören nicht in diesen Plan.
3.**Reihenfolge gedreht**: Plattformbasis ist jetzt Block A (zuerst), Einzelbugs folgen in D.
4.**Contacts-Ansatz korrigiert**: NICHT "NUR Plugin" (v1-Fehler), sondern **Core-Plugin (is_core=True, nicht deaktivierbar) OHNE Core-Hardcoding**.
5.**Workspace ARCH-004 hat jetzt eine konkrete Fixphase** (C2) mit verifizierter Ursache.
6.**Checker-Fix erweitert**: nicht nur Default, sondern ZWEI Bugs (Default + ValueError-Crash bei relativen Pfaden).
7.**Regel aufgenommen**: KEINE globalen commit→flush-Transformationen; nur nachgewiesene Einzelfälle.
8.**Regel aufgenommen**: Integration/Install-Tests ausschließlich über Alembic-Migrationen, kein pauschales `Base.metadata.create_all`.
9.**Frontend-Permission-Reihenfolge fixiert**: ERST Backend-Felder `FrontendPageRoute.permission` + `FrontendMenuItem.permission` (C1), DANN statische Routes abbauen (C4) — sonst Permission-Verlust.
10.**Settings + Dashboard als eigene Fixpunkte ergänzt** (C6/C7) — fehlten in v1 komplett.
11.**Lifecycle-Findings konkret eingeplant**: ARCH-012, 013, 015, 033–037, 042 jetzt einzeln in Block A aufgeführt.
12.**God Objects raus** aus dem Pflichtumbau → separater Track S1.
13.**i18n raus** aus dem Basisumbau → separater Track S2.
14.**Secrets/SQL-Injection = TRIAGE statt Pauschalfix** (D4): jede Stelle klassifizieren, nur echte Findings fixen.
15.**Marathon-Zahlen = Triage-Cluster** (D5), keine Bug-Anzahl, Root-Cause-Clustering.
16.**Verifikations-Gates in JEDEN Block integriert** (nicht erst am Ende) + 10 verpflichtende Integrationstests vor dem Löschen alter Wege.
## 2. Neue Findings (nicht in v1, heute code-verifiziert)
| ID | Finding | Ort | Block |
|---|---|---|---|
| SYNTAX-001 | **SyntaxError Zeile 413** (`expected 'except' or 'finally'`) in UNCOMMITTED Änderung — App startet mit aktuellem Working-Tree nicht. Einrückung von `logger.info` + `except` wurde beim if-Guard-Verschub nicht mitgenommen | app/plugins/builtins/automation/plugin.py | 0 |
| CHECK-002 | Checker crasht mit `ValueError: 'app/ai/action_mapper.py' is not in the subpath` bei relativen Pfaden — `check_file()` ruft `relative_to(PROJECT_ROOT)` ohne Resolution | scripts/check_cross_plugin_imports.py:113 | 0 |
| DT-001 | Naive `datetime.utcnow()` in mcp_client routes (fehlte in allen v1-Listen) | app/plugins/builtins/mcp_client/routes.py:173 | D2 |
-`logger.info(...)` und `except Exception:` im Cron-Job-Block auf die neue Einrücktiefe heben (innerhalb `if default_tenant_id is not None:` → `for` → `try`).
**Prinzip:** `is_core=True` bedeutet *nicht deaktivierbar* — NICHT *im Core hardcoded*. Contacts bleibt immer aktiv, aber 100% über den Plugin-Mechanismus.
1.`main.py:549``app.include_router(contacts.router)` entfernen — NACHDEM der Plugin-Route-Mechanismus identische Endpoints bereitstellt (Endpoint-Diff-Test davor!).
2. Plugin manifest: `routes=[]`-Kommentar beseitigen; Contacts-Routes über Plugin registrieren mit `require_active_plugin("contacts")`-Dependency (schützt bei versehentlicher Deaktivierung + klarer Fehler).
- Regel: Wenn ein Contract fehlt, Contract im Plugin definieren und exportieren — NIEMALS Model-Import behalten.
### B3 Entity-Registry & Custom Fields dynamisch
- **ARCH-016**: ENTITY_PERMISSIONS-Liste aus registrierten Plugin-Entities generieren (entity_permission_service.py:54, entity_permissions.py:252).
- **ARCH-017**: custom_field_definitions.py:25,42 — von contacts-Permission entkoppeln (plugin-eigene Permission je entity_type).
- **ARCH-022**: deps.py _WRITE_PERMISSIONS aus permission_registry generieren (nicht hardcoded).
### B4 Dependencies deklarieren
- **ARCH-026**: Manifest `depends_on`; Aktivierungsreihenfolge topologisch; Abhängiges nicht deaktivierbar solange Abhängiges aktiv (Fehlermeldung statt stiller Bruch).
- **ARCH-021-Vorbereitung**: Menü/Routen-Daten kommen vollständig aus active-manifests (siehe C).
### B5 ARCH-003 (früh, weil Frontend es braucht)
- plugins.py:97 — `/plugins/active-manifests` für eingeloggte User freigeben (eigene Permission `plugins:view_manifests`, Default-Rollen erhalten sie). Frontend braucht das für C.
### Gate B (vor Block C)
1.**Neues-Plugin-Test**: Minimal-Plugin mit Route+Entity+Menü — OHNE Änderung einer Core-Datei funktionsfähig.
3.**Contacts-Vertrag**: Endpoint-Vergleich alt (core route) vs. neu (plugin route) — identische Pfade/Statuscodes.
4. Dependency-Test: A hängt an B → B deaktivieren wird blockiert.
5. Cross-Plugin-Vollscan: 0 Core→Plugin-Verstöße.
---
# BLOCK C — Frontend + Workspace (erst nach A+B)
⚠️ Reihenfolge innerhalb C ist verbindlich: Backend-Felder (C1) → Store-Filter (C2) → Loader (C3) → erst DANN Route-/Menu-Umbau (C4–C7) → Production-Verify (C8) → alte Wege löschen (C9).
### C1 Backend: Permission-Felder liefern (VORAUSSETZUNG für alles Weitere)
-`FrontendPageRoute.permission: str | None` + `FrontendMenuItem.permission: str | None` in app/plugins/manifest.py ergänzen (aktuell nur `protected: bool` — verifiziert).
- active-manifests liefert die Felder aus; TypeScript-Typen (PluginMenuItem erwartet bereits `permission?` — Backend zieht nach).
- Migration der vorhandenen Plugin-Manifeste: jede Route/Menü bekommt ihre Permission.
- Test: `is_visible=false` → Modul unsichtbar in Sidebar + Route guard; Toggle im WorkspaceManager wirkt sofort.
### C3 PluginLoader Production-Build (ARCH-019)
-`@vite-ignore` Dynamic-Import-Problem lösen: Plugin-Frontends als bekannte Chunk-Map (build-time generiertes Manifest) oder importmap. Ziel: Production-Build lädt Plugin-Module wirklich.
### C4 Dynamische Routes mit Permission (ARCH-006 + ARCH-007)
- PluginRouteRenderer: PermissionGate mit `route.permission` aus C1 wrappen (gleiches Verhalten wie heutige statische `<PermissionRoute permission="calendar:read">`).
- Statische Plugin-Routes in routes/index.tsx markieren (deprecated), parallel betreiben bis C8 grün.
- singleItems reduzieren auf dashboard/login/settings(+profil). Alles andere aus pluginStore (Manifest-Menü inkl. permission, order, icon).
- Sortierreihenfolge aus Manifest `order`.
### C6 Settings-Doppelarchitektur auflösen (NEU, fehlte in v1)
- Settings.tsx:33-61: `hardcodedNavItems` + `pluginNavItems` + Dedup → EINE Quelle: Settings-Seiten als Manifest-Contribution (`parent: "/settings"` existiert bereits in FrontendPageRoute). Core behält nur Profil/Security-Basis.
- dashboard.py:14,60-66: Contact-Count nicht hardcoded — Count-Endpoint je Entity über Contract/Registry (Contacts-Plugin liefert seinen Count; Core aggregiert).
- RecentContacts/TasksSummary/CalendarUpcoming → Contributions ihrer Plugins.
### C8 Kleinere Frontend-Dedupes (funktional begründet, KEIN Refactor-Programm)
- BUG-027, 028, 029, 031, 032, 033, 034, 035, 071 (Test-Pfade/Payloads an reale API anpassen — Docs prüfen, nicht Tests verbiegen falls API falsch: dann API fixen).
- **ARCH-051**: dict-body-Routes auf Pydantic-Schemas (Liste aus test-bugs abarbeiten).
- **ARCH-055**: errors.py:124 user_agent. **ARCH-056/057**: roles.py SYSTEM_PERMISSIONS aus registry importieren; `_plugins` → öffentliche Methode. **ARCH-061** falls nicht schon in C4.
### D4 Security-TRIAGE (nicht pauschal fixen)
- BUG-019 „453 hardcoded secrets“: Klassifizieren (echtes Secret / Testdaten / Konstante / false positive) → nur echte Findings: Secret in env/Secretstore, Referenz einfügen. Ergebnis als Triage-Tabelle dokumentieren.
- BUG-020 „288 SQL-Injection-Risiken“: Nur Stellen mit User-Input-Fluss in String-SQL prüfen; parameterisieren. Scan-Finding ≠ Bug.
- **ARCH-027** hier einsortieren: config.py Default SECRET_KEY in Production hart failen lassen.
### D5 Marathon-Scanner-Triage (BUG-074–078)
- trace_api_contracts (859), stores (323), hooks (70), plugins (27), functions (3): Cluster-Analyse → wahrscheinliche Root-Causes zählen (Erfahrungswert: deutlich weniger als Issue-Zahl) → Cluster fixen, Scanner erneut laufen lassen, Delta dokumentieren.
### D6 Legacy-Migration (umsichtig)
- **ARCH-059** (+ ARCH-018-Familie): AIConversation/AIMessage → kommunikation-Conversations migrieren ODER Modul als deprecated markieren + Abschaltplan. Kein Big-Bang: erst Parität herstellen, dann Quellen umstellen, dann Tabellen droppen (eigene Migration).
# SEPARATE TRACKS (bewusst NICHT Teil dieses Umbaus)
| Track | Inhalt | Warum geschoben |
|---|---|---|
| S1 Code-Hygiene | God Objects (36 Py + 9 FE, BUG-018/081), weitere >500-Zeilen-Splits | Kein nachgewiesener Basisdefekt; Risiko von Big-Refactors bekannt |
| 9 | Fresh DB | Editor/Viewer-Permissions funktionieren nach reiner Migration+Seed |
| 10 | Contacts Core-Plugin | funktioniert ohne Contacts-Hardcodings im Core |
---
# BLOCK F — Sicherheit des Umbaus selbst + Wissenssicherung
Ziel: Der Umbau darf selbst nichts kaputt machen, und die neue Architektur muss so dokumentiert sein, dass die Fehlerklasse NIE wieder entsteht.
### F1 Rollback- & Branch-Strategie (schützt vor 'Plan macht was kaputt')
- Pro Block ein eigener Git-Branch (`fix/block-a`, `fix/block-b`, ...). Merge in main NUR nach bestandenem Block-Gate.
- Pro Task ein Commit (Conventional Commits mit Finding-ID) — jeder Commit ist einzeln revertierbar.
- DB-Migrationen additiv-first: neue Spalten/Tabellen hinzufügen, alte NICHT droppen, solange der neue Weg nicht durch Gate verifiziert ist. Drop-Migrationen erst in einem eigenen 'Cleanup-Release' nach C9.
- Feature-Flags wo machbar: dynamische Routes/Sidebar hinter einem Toggle (`DYNAMIC_PLUGIN_UI=true/false`), Default=false bis Gate C grün. Sofortiger Rollback = Flag off, kein Code-Revert.
- Deploy-Reihenfolge: Staging-Container (docker compose profile test) VOR Production. Production-Deploy nur mit grünem Gate.
- Vor jedem Block-Start: git tag `pre-block-<X>` als Restore-Punkt.
### F2 Was der Plan bewusst NICHT anfasst (Explosions-Schutz)
- Keine Schema-Änderungen an bestehenden 130 Tabellen (nur additive neue Felder: permission in Manifests ist Code, kein DB-Schema).
- Keine API-Path-Änderungen für bestehende Endpoints (Contacts-Entkopplung muss identische Pfade liefern — Endpoint-Diff-Test in B1 erzwingt das).
- Keine Auth-/Session-Logik-Änderungen (Security-Basics sind verifiziert gut — nicht anfassen).
- Keine gleichzeitige Änderung von Backend + Frontend im selben Commit (Backend erst, dann Frontend — C-Reihenfolge).
| B | Kapitel 'Dependencies': depends_on im Manifest, topologische Aktivierung, Deaktivier-Schutz. Kapitel 'Entity-Registrierung': dynamische ENTITY_PERMISSIONS, Field-Contributions (statt CORE_FIELD_DEFINITIONS) |
| C | Kapitel 'Frontend-Contributions' aktualisieren: permission-Feld in FrontendPageRoute/FrontendMenuItem (PFLICHT, nicht optional), Widget-Registry statt statischem Loader, Workspace is_visible |
| D | Kapitel 'Konventionen': datetime.now(UTC) statt utcnow, Pydantic-Schemas statt dict-bodies, Audit-Log-Pflicht bei Mutationen |
**Neuer Guide-Abschnitt 'Plugin-Checkliste' (Muss-Bestehen vor Merge jedes neuen Plugins):**
1. Kein direkter Import aus anderem Plugin — nur get_contract (Checker läuft in CI)
2. on_activate/on_deactivate symmetrisch: alles was registriert wird, wird auch deregistriert
3. Jede Route hat Permission (kein auth-only), jede Menü-Route hat permission-Feld im Manifest
4. depends_on deklariert, wenn Plugin andere nutzt
5. Entities über Plugin-Registrierung, keine Core-Annahmen
6. Frontend-Components über Manifest-Contribution, keine hardcoded Loader-Einträge
7. Migrationen folgen Namenskonvention, RLS für eigene Tabellen
8. Audit-Log bei allen Mutationen
9. datetime nur mit UTC
10. E2E-Smoke gegen Production-Build
**Enforcement:** Die Checkliste wird als CI-Template-Check + Review-Checkliste referenziert. AGENTS.md §0 (Auf bestehendem Code aufbauen) bleibt die übergeordnete Regel.
### Gate F
- Guide-Review: Jeder neue Mechanismus (Contracts, depends_on, permission-Felder, Widget-Registry) hat ein Kapitel mit Code-Beispiel aus einem REAL existierenden Plugin (nicht fiktiv).
- Checkliste als Datei (docs/plugin-checklist.md) existiert und ist in PR-Template verlinkt.
- Test: Ein Entwickler (oder Agent) baut ein Minimal-Plugin NUR mit dem Guide — ohne Fragen an den Architekten. Gelingt das nicht, ist der Guide nicht fertig.
---
# BLOCK G — Compliance & Account-Security (NEU aus Final-Check 2026-08-23)
Ziel: Rechtliche Pflichten (DSGVO) und Account-Sicherheit, die im Final-Check ans Licht kamen. Diese Punkte waren in v1, v2 UND dem ChatGPT-Review nicht enthalten.
Ein CRM mit Personendaten ohne DSGVO-Funktionen darf in DE nicht produktiv gehen:
- **Art. 15 Auskunft**: Endpunkt `GET /api/v1/me/data-export` — alle Daten einer natürlichen Person, maschinenlesbar (JSON).
- **Art. 17 Löschung**: Der von AGENTS.md geforderte Hard-Delete (`?gdpr=true`) existiert als Regel, aber KEIN Endpunkt implementiert ihn. Implementieren: anonymisiere/lösche Personendaten inkl. aller verknüpften Entities (Contacts, Addresses, Notes, Files, Mail-Verknüpfungen), respektiere Aufbewahrungspflichten (Buchhaltung), protokolliere die Löschung selbst im Audit.
- **Art. 20 Portabilität**: Strukturierter Export (JSON/CSV) der Kontaktdaten eines Tenants/Users.
- **Verarbeitungsübersicht**: doc (welche Daten, wo, wie lange) als Grundlage für den AVV.
- Aufwand: mittelgroßes Feature-Paket, eigener Track mit Tests; NICHT in die Architekturblöcke mischen.
### G2 Session-Revocation bei Passwortänderung (verifiziert: nur Logout invalidiert)
- Befund: app/routes/auth.py:105 invalidiert NUR die eigene Session beim Logout. Eine Passwortänderung löscht NICHT andere aktive Sessions des Accounts.
- Fix: Nach erfolgreichem Passwortwechsel/-reset alle Sessions des Users löschen (außer der aktuellen); optional E-Mail-Benachrichtigung über den Vorgang.
- Klein, wichtig, sofort machbar — gehört in Block 0 oder A.
### G3 Hygiene-Funde (klein)
- dump.rdb im Repo-Root: git-ignored (kein Leak, verifiziert), aber aufräumen und Redis-Workdir sauber konfigurieren.
- scripts/test_migrations.sh:70 testet `alembic downgrade base`, ignoriert aber Fehler bewusst ('not always lossless'). Entscheidung dokumentieren: Downgrade-Fähigkeit ist KEIN Release-Kriterium — dann Kommentar so lassen und in docs/test-strategy.md festhalten.
### Verifiziert GUT (nichts zu tun — explizit geprüft im Final-Check)
- Content-based MIME-Detection via python-magic (storage.py:32-34)
- CORS konfigurierbar über Settings (main.py:468-469)
- Redis: Passwort-Pflicht, Named Volume, Healthcheck (docker-compose.yaml:50-59)
---
# BLOCK H — Agent-Plattform-Kern (NEU v3: Kernprodukt, war unsichtbar)
⚠️ Höchste Priorität nach Block 0 — VOR bzw. zusammen mit Block B.
Kontext: Die Plattform soll ERP-Fachmodule per Plugin nachrüsten und Agenten müssen die Software VOLL bedienen. Code-Verifizierung zeigt: Dieser Kernanspruch ist aktuell architektonisch NICHT erfüllt.
### H1 Befunde (verifiziert 2026-08-23)
1.**Agent-Tools sind hardcoded**: `app/ai/integration_tools.py` registriert Workflow/Knowledge-Tools fest und importiert direkt aus Plugins (Core→Plugin, ARCH-011-Familie). Ein neues Fachmodul könnte seine Funktionen NICHT agenten-bedienbar machen, ohne diese Core-Datei zu ändern — direkter Verstoß gegen das Plattform-Prinzip.
2.**Agent-Laufzeit hängt an einem Plugin**: `ToolRegistry` liegt unter `app/plugins/builtins/ai_assistant/tool_registry.py`. Ist ai_assistant deaktiviert, existiert keine Registry mehr — Agent-Betrieb ohne dieses Plugin unmöglich.
3.**Manifest hat Contribution-Ansätze** (`agent_capabilities` manifest.py:200, `AgentDefinitionContribution.tool_ids` :88-94), aber keinen vollständigen Weg: BasePlugin kennt keinen register_tools-Hook; die Hardcodes umgehen das Manifest komplett.
### H2 Architektur-Entscheidung (zuerst klären, dann bauen)
- **Agent-Laufzeit = Core**: `tool_registry`, `skill_registry`, `llm_client`, `agent_loop` gehören in `app/core/` bzw. `app/ai/` (Core-Layer), NICHT ins ai_assistant-Plugin. Das ai_assistant-Plugin wird zum normalen Fachplugin, das NUR seine eigenen Tools beiträgt.
- **Tool-Contribution-API**: Manifest-Feld `tools: list[ToolContribution]` (name, description, input_schema, handler_ref, required_permission) + BasePlugin-Lifecycle: on_activate registriert Tools beim Core-Registry, on_deactivate meldet sie ab (Symmetrie-Pflicht wie alle Contributions).
- **Permission-Gebundenheit**: Jedes Agent-Tool trägt die Permission des darunterliegenden Endpoints; der Agent kann nur handeln, was der ausführende User darf (bestehendes agent_permissions.py nutzen/konsolidieren).
### H3 Umbau
1. Core-Registry nach app/core/ ziehen (Move + Alias-Import für Übergangszeit), ai_assistant nutzt sie wie jedes andere Plugin.
2.`integration_tools.py` auflösen: Die 4 Hardcoded-Tools werden zu regulären Contributions ihrer Quell-Plugins (workflows, knowledge, unified_search) via Manifest/Hook — Core-Datei verschwindet.
3. Plugin-Guide: neues Kapitel 'Agent-Tools beitragen' mit Schema + Beispiel + Test-Pflicht (Tool ohne Permission verboten).
4. ARCH-011-Core-Imports (ai/integration_tools, ai/agent_loop) lösen sich dadurch STRUKTURELL auf — nicht durch Contract-Surrogate an dieser Stelle.
### Gate H
1. Neues Fachmodul-Testplugin bringt ein Agent-Tool MIT OHNE Änderung einer Core-Datei; Agent führt es aus (Tenant-scoped, permission-geprüft).
2. ai_assistant deaktivieren → Agent-Laufzeit läuft weiter; dessen eigene Tools sind weg, alles andere bleibt.
3. Deactivate/Activate-Zyklus: Tools sauber ab-/angemeldet, keine Duplikate (EventBus-Duplikatfix greift hier analog).
4. Jeder Tool-Call landet im Audit-Log mit actor=agent, acting_user, permission.
### H4 Weitere Hardcoding-Systeme (gründlicher Nachscan 2026-08-23, alle code-verifiziert)
Gleiche Fehlerklasse wie H1 — Systeme, die Fachmodule hardcodieren statt Contribution anzubieten:
| ID | System | Ort | Befund | Fix-Richtung |
|---|---|---|---|---|
| HC-A | NL→Aktions-Mapping | app/ai/action_mapper.py:52-128 | map_query_to_actions() hat FESTE API-Pfade per Regex — neue Fachmodul-Endpunkte sind für Agenten-Vorschläge UNSICHTBAR | Aktions-Katalog aus Plugin-Manifest generieren (Endpoint-Registry existiert schon via OpenAPI) |
| HC-B | Workflow-Schritte | app/workflows/step_handlers.py:221,261,306,351,394 | Importiert 5 Contract-KLASSEN direkt (MailContract, CalendarContract, DmsContract, SearchContract, AutomationContract) statt get_contract() — neue Module können KEINE eigenen Step-Types beitragen | Step-Handler-Registry: Plugins registrieren Step-Types per Manifest; Core kennt nur Interface |
| HC-C | AI-Chat & Workflow-Notifications an kommunikation | app/ai/agent_loop.py:397 + app/workflows/engine.py:95 | CommConversation-Model direkt importiert — AI-Konversationspersistenz und Workflow-Benachrichtigung hängen am kommunikation-Plugin | Über kommunikation-Contract (besteht laut Checker-Output teilweise) oder Notification-Abstraktion |
| HC-D | Knowledge-Worker | app/core/worker.py:460 | KnowledgeExtraction-Model direkt importiert (deckt ARCH-040) | Contract oder generischer Extraction-Job über Plugin-Hook |
| HC-E | Compliance-Route | app/routes/compliance.py:22 | AgentDefinition-Model direkt importiert | Contract auf automation oder Model in Core-Schema überführen |
**POSITIV-VORBILD im eigenen Code:**`unified_search/provider_registry.py` macht es RICHTIG — dynamisches register()/unregister()/get(), graph_rag contributet seinen Provider per Contract (graph_rag/plugin.py:44-58). Dieses Muster ist die Blaupause für ALLE H-Fixes.
**Inkonsistenz gleich mitfixen:** knowledge/services.py:110 importiert provider_registry DIREKT statt den eigenen unified_search-Contract zu nutzen (Plugin→Plugin-Verstoß aus dem Vollscan).
| HC-F | Message-Block-Typen | frontend/src/components/comm/blocks/BlockRenderer.tsx:3-15,34+ | 14 Block-Typen hart im switch, darunter FACHMODUL-Blocks (TaskCardBlock, WorkflowCardBlock, KnowledgeCardBlock, ContactCardBlock, AgentResultBlock, ApprovalRequestBlock). Keine dynamische Registry (grep registerBlock/BLOCK_REGISTRY = leer). Ein ERP-Modul kann keine eigenen Message-Blocks beitragen | Block-Registry: Plugins registrieren Block-Component per Manifest-Contribution (component + block_type + permission); Core behält nur text/markdown/html/file/image/audio/video als Basis |
| HC-G | AISidebar-Tabs | frontend/src/components/layout/AISidebar.tsx:137-141 | 5 Tabs hardcodiert (chat/proactive/notifications/team/chatroom), Fachmodule können keine eigenen Sidebar-Tabs beitragen | Tab-Contribution über Manifest (wie Menü/Routes); Core behält Basis-Tabs, Plugin-Tabs kommen aus pluginStore |
**Geprüft und sauber (Frontend):** Core-Layout-Komponenten (App.tsx, routes/, components/layout/, components/common/) importieren KEINE Plugin-API-Clients direkt. Die Doppelarchitektur-Probleme (Routes, Sidebar-Menü, Settings, Dashboard) sind bereits als C4–C7 geplant.
**Gate H erweitert:**
5. Testplugin registriert einen eigenen Workflow-Step-Type OHNE Core-Änderung; Workflow führt ihn aus.
6. Agent-Query auf einen Fachmodul-Begriff schlägt dessen Aktionen vor (HC-A wirksam).
7. grep-Beweis: Keine der Dateien integration_tools/step_handlers/agent_loop/engine enthält noch Plugin-Model-Imports.
8. Testplugin contributet einen eigenen Message-Block-Typ; BlockRenderer rendert ihn dynamisch (HC-F wirksam).
9. Testplugin contributet einen AISidebar-Tab; Tab erscheint dynamisch (HC-G wirksam).
---
# BLOCK E — Production-Härtung (NEU aus Deep-Dive 2026-08-23)
Ziel: Der Unterschied zwischen 'Architektur repariert' und 'produktiv betreibbar'. Diese Punkte fehlten in v1 UND v2 komplett.
### E1 Audit-Logging-Vollständigkeit
- Befund: Nur 1 Service-Datei referenziert AuditLog (grep-verified). AGENTS.md verbietet Mutationen OHNE Audit-Eintrag.
- Fix: Systematische Prüfung ALLER schreibenden Routes/Services auf Audit-Aufruf; Lücke schließen (Middleware-/Repository-Pattern statt handgestreut); Test: jede POST/PATCH/DELETE-Route erzeugt Audit-Zeile.
### E2 E2E-Test-Realität
- Befund: BUG-012 — Playwright helpers.ts nutzt Mock-Daten. Die E2E-'Abdeckung' ist teilweise Schein.
- Fix: helpers.ts auf echte API umstellen; E2E gegen Production-Build + echte Backend-Instanz (docker compose profile test). Erst danach zählt E2E als Verifikations-Gate.
### E3 Backup/Restore-Drill
- Vorhanden: backup.py, restore.py, restore_test.sh — aber ungeprüft, ob Restore auf FRISCHER DB wirklich reproduzierbar funktioniert.
- Fix: Automatisierten Restore-Drill in CI aufnehmen (Dump → leere DB → Restore → Smoke-Checks). Monatlicher manuell getriggerte Drill zusätzlich.
- Fix: Health-Endpunkte extern erreichbar + Alerting konfiguriert? Metrics-Endpoint gefüllt? Einmal durchspielen und dokumentieren, was WIRKLICH alarmiert.
### E5 Performance-Baseline
- Keine Lasttests erkennbar; bereits ein Search-Perf-Bug (6.34s) aufgetreten.
- Fix: Baseline-Messung der Top-10-Endpoints (p95), seed_perf_data.py nutzen, Schwellwerte dokumentieren. Kein Voll-Lasttest-Programm — nur Baseline + Regressionsschwelle.
### E6 Secrets & Credential-Hygiene
- Befund: Sensible Credentials liegen lt. Projektanweisungen in docs/deploy-guide.md (privates Repo, aber Repo-Datei ≠ Secretstore).
- Fix: Triage wie D4; Ziel: Deploy-Guide referenziert Secretstore statt Werte zu enthalten. pip-audit/npm-audit-Routine in CI (aus S3 vorziehen: nur die AUTOMATISIERUNG, nicht die Altlasten).
### E7 CI als hartes Gate
- Vorhanden aber ungeprüft: ci_pipeline.sh, .forgejo/workflows, .pre-commit-cross-plugin.yaml.
- Fix: Pipeline zum Pflicht-Gate machen: Import-Check + Cross-Plugin-Vollscan (nach 0.2-Fix) + ruff (85 Auto-Fixes zuerst bereinigen, dann Regel scharf) + tsc + pytest-Smoke. Merge ohne grün = unmöglich.
### Reihenfolge von E
- E7 sofort nach Block 0 (CI braucht den funktionierenden Checker).
- E1 nach Block B (Audit braucht stabile Service-Schicht).
- E2–E6 parallel zu Block C/D, spätestens VOR Go-Live-Kandidat.
