Leopoldadmin/leocrm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Phase 3: Plugin-UI-System (WordPress-Style)

Browse Source 
Backend:
- PluginManifest um 5 neue UI-Felder erweitert: menu_items, page_routes,
  detail_tabs, settings_pages, dashboard_widgets (FrontendMenuItem,
  FrontendPageRoute, FrontendDetailTab, FrontendSettingsPage,
  FrontendDashboardWidget)
- GET /api/v1/plugins/active-manifests Endpoint liefert UI-Manifeste
  aller aktiven Plugins
- Registry.get_active_manifests() + PluginService.get_active_manifests()
- 12 Built-in Plugins mit UI-Manifest-Daten gefuellt (menu_items,
  page_routes, detail_tabs, settings_pages)
- Plugin-Install-System: POST /upload (ZIP), POST /install-url (URL)
  mit Validierung (Manifest, dangerous imports, SQL migrations)

Frontend:
- pluginStore.ts (Zustand) mit PluginUiManifest Typen + Selektoren
- useActivePluginManifests() React Query Hook
- PluginRegistry.tsx — fetcht Manifeste beim App-Start
- PluginLoader.tsx — dynamisches React.lazy() mit ErrorBoundary
- PluginRouteRenderer.tsx — Catch-all fuer Plugin-Routes
- routes/index.tsx — Catch-all Routes fuer Plugin-Pages + Settings
- Sidebar.tsx — dynamische Plugin Menu-Items mit Grouping + Icons
- Settings.tsx — dynamische Plugin Settings-Pages
- ContactDetail.tsx — dynamische Plugin Detail-Tabs mit Permissions
- AppShell.tsx — PluginRegistry Provider eingebunden
- SettingsPlugins.tsx — Install-UI (ZIP Upload + URL Install)
- plugins.ts — useUploadPlugin() + useInstallPluginFromUrl() Hooks

Docs & Templates:
- docs/plugin-development-guide.md — komplette Entwickler-Doku
- templates/plugin-template/ — Boilerplate mit allen Manifest-Feldern

Tests:
- 34 Vitest-Tests (PluginRegistry, PluginLoader, PluginRouteRenderer,
  pluginStore) — alle bestanden
- TSC: keine neuen Errors (nur pre-existing Dms.tsx)
This commit is contained in:
Agent Zero
2026-07-23 19:01:18 +02:00
parent 4f70c1d912
commit fc96a2f86c
43 changed files with 3005 additions and 204 deletions
Download Patch File Download Diff File Expand all files Collapse all files
app/plugins/builtins/ai_assistant/plugin.py
+10 -1
View File
@@ -6,7 +6,7 @@ import logging
from typing import Any
from app.plugins.base import BasePlugin
from app.plugins.manifest import PluginManifest, PluginRouteDef
from app.plugins.manifest import PluginManifest, PluginRouteDef, FrontendMenuItem, FrontendPageRoute, FrontendSettingsPage
logger = logging.getLogger(__name__)
@@ -40,6 +40,15 @@ class AIAssistantPlugin(BasePlugin):
"ai:tools",
],
is_core=True,
menu_items=[
FrontendMenuItem(label_key='nav.aiAssistant', label='AI Assistant', path='/ai-assistant', icon='Bot', order=90),
],
page_routes=[
FrontendPageRoute(path='/ai-assistant', component='@/pages/AIAssistant', protected=True),
],
settings_pages=[
FrontendSettingsPage(path='ai', label_key='settings.ai', label='AI Settings', component='@/pages/AISettings', icon='Bot', order=60),
],
)
def __init__(self) -> None:
app/plugins/builtins/ai_proactive/plugin.py
+4 -1
View File
@@ -11,7 +11,7 @@ import logging
from typing import Any
from app.plugins.base import BasePlugin
from app.plugins.manifest import PluginManifest, PluginRouteDef
from app.plugins.manifest import PluginManifest, PluginRouteDef, FrontendSettingsPage
logger = logging.getLogger(__name__)
@@ -43,6 +43,9 @@ class AIProactivePlugin(BasePlugin):
"ai_proactive:config",
],
is_core=False,
settings_pages=[
FrontendSettingsPage(path='ai-proactive', label_key='settings.aiProactive', label='Proactive AI', component='@/pages/ProactiveAISettings', icon='Sparkles', order=61),
],
)
def __init__(self) -> None:
app/plugins/builtins/calendar/plugin.py
+12 -1
View File
@@ -3,7 +3,7 @@
from __future__ import annotations
from app.plugins.base import BasePlugin
from app.plugins.manifest import PluginManifest, PluginRouteDef
from app.plugins.manifest import PluginManifest, PluginRouteDef, FrontendMenuItem, FrontendPageRoute, FrontendDetailTab
class CalendarPlugin(BasePlugin):
@@ -41,4 +41,15 @@ class CalendarPlugin(BasePlugin):
"calendar:share",
"calendar:admin",
],
menu_items=[
FrontendMenuItem(label_key='nav.calendar', label='Calendar', path='/calendar', icon='Calendar', order=20),
FrontendMenuItem(label_key='nav.calendarKanban', label='Calendar Kanban', path='/calendar/kanban', icon='KanbanSquare', group='nav.calendar', order=21),
],
page_routes=[
FrontendPageRoute(path='/calendar', component='@/pages/Calendar', protected=True),
FrontendPageRoute(path='/calendar/kanban', component='@/pages/CalendarKanban', protected=True),
],
detail_tabs=[
FrontendDetailTab(entity_type='contact', label_key='tabs.calendar', label='Calendar', component='@/components/contact/ContactCalendarTab', icon='Calendar', order=30, permission='calendar:read'),
],
)
app/plugins/builtins/dms/plugin.py
+12 -1
View File
@@ -3,7 +3,7 @@
from __future__ import annotations
from app.plugins.base import BasePlugin
from app.plugins.manifest import PluginManifest, PluginRouteDef
from app.plugins.manifest import PluginManifest, PluginRouteDef, FrontendMenuItem, FrontendPageRoute, FrontendDetailTab
class DmsPlugin(BasePlugin):
@@ -31,4 +31,15 @@ class DmsPlugin(BasePlugin):
"dms:share",
"dms:admin",
],
menu_items=[
FrontendMenuItem(label_key='nav.files', label='Files', path='/dms', icon='FolderOpen', order=40),
FrontendMenuItem(label_key='nav.trash', label='Trash', path='/dms/trash', icon='Trash2', group='nav.files', order=41),
],
page_routes=[
FrontendPageRoute(path='/dms', component='@/pages/Dms', protected=True),
FrontendPageRoute(path='/dms/trash', component='@/pages/DmsTrash', protected=True),
],
detail_tabs=[
FrontendDetailTab(entity_type='contact', label_key='tabs.files', label='Dateien', component='@/components/contact/ContactFilesTab', icon='FolderOpen', order=40, permission='dms:read'),
],
)
app/plugins/builtins/entity_links/plugin.py
+4 -1
View File
@@ -5,7 +5,7 @@ from __future__ import annotations
from typing import Any
from app.plugins.base import BasePlugin
from app.plugins.manifest import PluginManifest, PluginRouteDef
from app.plugins.manifest import PluginManifest, PluginRouteDef, FrontendDetailTab
class EntityLinksPlugin(BasePlugin):
@@ -37,6 +37,9 @@ class EntityLinksPlugin(BasePlugin):
"entity_links:delete",
],
is_core=True,
detail_tabs=[
FrontendDetailTab(entity_type='contact', label_key='tabs.links', label='Verknüpfungen', component='@/components/contact/ContactLinksTab', icon='Link', order=60, permission='entity_links:read'),
],
)
async def on_contact_deleted(self, payload: dict[str, Any]) -> None:
app/plugins/builtins/kommunikation/plugin.py
+7 -1
View File
@@ -6,7 +6,7 @@ import logging
from typing import Any
from app.plugins.base import BasePlugin
from app.plugins.manifest import PluginManifest, PluginRouteDef
from app.plugins.manifest import PluginManifest, PluginRouteDef, FrontendMenuItem, FrontendPageRoute
logger = logging.getLogger(__name__)
@@ -49,6 +49,12 @@ class KommunikationPlugin(BasePlugin):
"comm:delete",
],
is_core=True,
menu_items=[
FrontendMenuItem(label_key='nav.communication', label='Communication', path='/communication', icon='MessageSquare', order=80),
],
page_routes=[
FrontendPageRoute(path='/communication', component='@/pages/Communication', protected=True),
],
)
async def on_activate(self, db, service_container, event_bus) -> None:
app/plugins/builtins/mail/plugin.py
+15 -1
View File
@@ -7,7 +7,7 @@ import logging
from typing import Any
from app.plugins.base import BasePlugin
from app.plugins.manifest import PluginManifest, PluginRouteDef
from app.plugins.manifest import PluginManifest, PluginRouteDef, FrontendMenuItem, FrontendPageRoute, FrontendDetailTab, FrontendSettingsPage
logger = logging.getLogger(__name__)
@@ -56,6 +56,20 @@ class MailPlugin(BasePlugin):
events=[],
migrations=["0001_initial.sql", "0006_flag_type.sql", "0007_sync_queue.sql", "0008_sync_queue_deleted_at.sql", "0009_remove_mail_soft_delete.sql"],
permissions=["mail:read", "mail:send", "mail:config", "mail:share", "mail:write", "mail:delete"],
menu_items=[
FrontendMenuItem(label_key='nav.email', label='Mail', path='/mail', icon='Mail', order=30),
FrontendMenuItem(label_key='nav.emailSettings', label='Mail Settings', path='/mail/settings', icon='Settings', group='nav.email', order=31),
],
page_routes=[
FrontendPageRoute(path='/mail', component='@/pages/Mail', protected=True),
FrontendPageRoute(path='/mail/settings', component='@/pages/MailSettings', protected=True),
],
settings_pages=[
FrontendSettingsPage(path='mail', label_key='settings.mail', label='Mail', component='@/pages/MailSettings', icon='Mail', order=50),
],
detail_tabs=[
FrontendDetailTab(entity_type='contact', label_key='tabs.email', label='E-Mails', component='@/components/contact/ContactMailTab', icon='Mail', order=20, permission='mail:read'),
],
)
async def on_activate(
app/plugins/builtins/permissions/plugin.py
+6 -1
View File
@@ -3,7 +3,7 @@
from __future__ import annotations
from app.plugins.base import BasePlugin
from app.plugins.manifest import PluginManifest, PluginRouteDef
from app.plugins.manifest import PluginManifest, PluginRouteDef, FrontendSettingsPage
class PermissionsPlugin(BasePlugin):
@@ -31,4 +31,9 @@ class PermissionsPlugin(BasePlugin):
migrations=["0001_initial.sql"],
permissions=[],
is_core=True,
settings_pages=[
FrontendSettingsPage(path='roles', label_key='settings.roles', label='Roles', component='@/pages/SettingsRoles', icon='Shield', order=10, permission='permissions:read'),
FrontendSettingsPage(path='users', label_key='settings.users', label='Users', component='@/pages/SettingsUsers', icon='Users', order=11, permission='permissions:read'),
FrontendSettingsPage(path='groups', label_key='settings.groups', label='Groups', component='@/pages/SettingsGroups', icon='UsersRound', order=12, permission='permissions:read'),
],
)
app/plugins/builtins/report_generator/plugin.py
+7 -1
View File
@@ -3,7 +3,7 @@
from __future__ import annotations
from app.plugins.base import BasePlugin
from app.plugins.manifest import PluginManifest, PluginRouteDef
from app.plugins.manifest import PluginManifest, PluginRouteDef, FrontendMenuItem, FrontendPageRoute
class ReportGeneratorPlugin(BasePlugin):
@@ -26,4 +26,10 @@ class ReportGeneratorPlugin(BasePlugin):
events=["report.requested", "report.generated"],
migrations=["0001_initial.sql"],
permissions=["reports.read", "reports.generate", "reports.manage_templates"],
menu_items=[
FrontendMenuItem(label_key='nav.reports', label='Reports', path='/reports', icon='BarChart3', order=70),
],
page_routes=[
FrontendPageRoute(path='/reports', component='@/pages/Reports', protected=True),
],
)
app/plugins/builtins/system_notif/plugin.py
+4 -1
View File
@@ -6,7 +6,7 @@ import logging
from typing import Any
from app.plugins.base import BasePlugin
from app.plugins.manifest import PluginManifest
from app.plugins.manifest import PluginManifest, FrontendSettingsPage
logger = logging.getLogger(__name__)
@@ -38,6 +38,9 @@ class SystemNotifPlugin(BasePlugin):
migrations=[],
permissions=["system_notif:read"],
is_core=False,
settings_pages=[
FrontendSettingsPage(path='notifications', label_key='settings.notifications', label='Notifications', component='@/pages/SettingsNotifications', icon='Bell', order=40),
],
)
def __init__(self) -> None:
app/plugins/builtins/tags/plugin.py
+4 -1
View File
@@ -3,7 +3,7 @@
from __future__ import annotations
from app.plugins.base import BasePlugin
from app.plugins.manifest import PluginManifest, PluginRouteDef
from app.plugins.manifest import PluginManifest, PluginRouteDef, FrontendDetailTab
class TagsPlugin(BasePlugin):
@@ -31,4 +31,7 @@ class TagsPlugin(BasePlugin):
"tags:admin",
],
is_core=True,
detail_tabs=[
FrontendDetailTab(entity_type='contact', label_key='tabs.tags', label='Tags', component='@/components/contact/ContactTagsTab', icon='Tag', order=50, permission='tags:read'),
],
)
app/plugins/builtins/unified_search/plugin.py
+4 -1
View File
@@ -6,7 +6,7 @@ import logging
from typing import Any
from app.plugins.base import BasePlugin
from app.plugins.manifest import PluginManifest, PluginRouteDef
from app.plugins.manifest import PluginManifest, PluginRouteDef, FrontendPageRoute
logger = logging.getLogger(__name__)
@@ -40,6 +40,9 @@ class UnifiedSearchPlugin(BasePlugin):
migrations=["0001_initial.sql", "0002_embeddings.sql"],
permissions=["search:read", "search:admin"],
is_core=False,
page_routes=[
FrontendPageRoute(path='/search', component='@/pages/GlobalSearchResults', protected=True),
],
)
async def on_activate(self, db, service_container, event_bus) -> None:
app/plugins/manifest.py
+125
View File
@@ -24,6 +24,74 @@ class FieldDefinition(BaseModel):
sensitivity: str = Field(default="normal", description="normal|sensitive|critical")
# ── Frontend UI definition models (Phase 3) ──────────────────────────────────
class FrontendMenuItem(BaseModel):
"""A sidebar navigation item contributed by a plugin."""
label_key: str = Field(..., description="i18n key for the menu label")
label: str = Field(default="", description="Fallback label if i18n key is missing")
path: str = Field(..., description="Frontend route path, e.g. /mail")
icon: str = Field(default="FileText", description="lucide-react icon name")
group: str = Field(default="", description="Optional group label_key for tree-style nesting")
order: int = Field(default=100, description="Sort order within the sidebar")
badge_key: str = Field(default="", description="Optional store key for badge count")
class FrontendPageRoute(BaseModel):
"""A frontend page route contributed by a plugin."""
path: str = Field(..., description="Frontend route path, e.g. /mail or /mail/settings")
component: str = Field(
..., description="Dotted path to the React component, e.g. @/pages/Mail"
)
parent: str = Field(
default="",
description="Parent route path for nested routes (e.g. /settings for a settings sub-page)",
)
protected: bool = Field(default=True, description="Whether the route requires authentication")
order: int = Field(default=100, description="Sort order")
class FrontendDetailTab(BaseModel):
"""A detail tab contributed by a plugin for entity detail views."""
entity_type: str = Field(..., description="Entity type this tab applies to, e.g. 'contact'")
label_key: str = Field(..., description="i18n key for the tab label")
label: str = Field(default="", description="Fallback label")
component: str = Field(..., description="Dotted path to the React component")
icon: str = Field(default="FileText", description="lucide-react icon name")
order: int = Field(default=100, description="Sort order within the detail view")
permission: str = Field(default="", description="Optional permission required to see this tab")
class FrontendSettingsPage(BaseModel):
"""A settings sub-page contributed by a plugin."""
path: str = Field(..., description="Settings sub-route path, e.g. mail or notifications")
label_key: str = Field(..., description="i18n key for the settings nav label")
label: str = Field(default="", description="Fallback label")
component: str = Field(..., description="Dotted path to the React component")
icon: str = Field(default="Settings", description="lucide-react icon name")
order: int = Field(default=100, description="Sort order within settings nav")
permission: str = Field(default="", description="Optional permission required")
class FrontendDashboardWidget(BaseModel):
"""A dashboard widget contributed by a plugin."""
id: str = Field(..., description="Unique widget identifier")
label_key: str = Field(..., description="i18n key for the widget title")
label: str = Field(default="", description="Fallback label")
component: str = Field(..., description="Dotted path to the React component")
icon: str = Field(default="LayoutDashboard", description="lucide-react icon name")
order: int = Field(default=100, description="Sort order on the dashboard")
col_span: int = Field(default=1, description="Grid column span (1-4)")
row_span: int = Field(default=1, description="Grid row span")
permission: str = Field(default="", description="Optional permission required")
class PluginManifest(BaseModel):
"""Manifest describing a plugin's metadata, dependencies, and capabilities."""
@@ -58,6 +126,22 @@ class PluginManifest(BaseModel):
default_factory=list,
description="AI agent capabilities this plugin provides (e.g. 'contact_search', 'email_draft')",
)
# ── Frontend UI contributions (Phase 3) ──
menu_items: list[FrontendMenuItem] = Field(
default_factory=list, description="Sidebar navigation items contributed by this plugin"
)
page_routes: list[FrontendPageRoute] = Field(
default_factory=list, description="Frontend page routes contributed by this plugin"
)
detail_tabs: list[FrontendDetailTab] = Field(
default_factory=list, description="Entity detail tabs contributed by this plugin"
)
settings_pages: list[FrontendSettingsPage] = Field(
default_factory=list, description="Settings sub-pages contributed by this plugin"
)
dashboard_widgets: list[FrontendDashboardWidget] = Field(
default_factory=list, description="Dashboard widgets contributed by this plugin"
)
@field_validator("name")
@classmethod
@@ -120,6 +204,31 @@ MANIFEST_SCHEMA_DOC = ManifestSchemaResponse(
"required": "false",
"description": "Required permissions",
},
"menu_items": {
"type": "list[FrontendMenuItem]",
"required": "false",
"description": "Sidebar navigation items (label_key, path, icon, group, order)",
},
"page_routes": {
"type": "list[FrontendPageRoute]",
"required": "false",
"description": "Frontend page routes (path, component, parent, protected)",
},
"detail_tabs": {
"type": "list[FrontendDetailTab]",
"required": "false",
"description": "Entity detail tabs (entity_type, label_key, component, icon, permission)",
},
"settings_pages": {
"type": "list[FrontendSettingsPage]",
"required": "false",
"description": "Settings sub-pages (path, label_key, component, icon, permission)",
},
"dashboard_widgets": {
"type": "list[FrontendDashboardWidget]",
"required": "false",
"description": "Dashboard widgets (id, label_key, component, col_span, permission)",
},
},
example=PluginManifest(
name="example_plugin",
@@ -131,5 +240,21 @@ MANIFEST_SCHEMA_DOC = ManifestSchemaResponse(
events=["contact.created"],
migrations=["0001_initial.sql"],
permissions=["contacts.read"],
menu_items=[
FrontendMenuItem(
label_key="nav.examplePlugin",
label="Example",
path="/example",
icon="Sparkles",
order=50,
)
],
page_routes=[
FrontendPageRoute(
path="/example",
component="@/pages/Example",
protected=True,
)
],
),
)
app/plugins/registry.py
+31
View File
@@ -671,6 +671,37 @@ class PluginRegistry:
return plugins_list
# ── Active UI Manifests (Phase 3) ──
async def get_active_manifests(self, db: AsyncSession) -> list[dict[str, Any]]:
"""Return UI manifests for all active plugins.
Each entry contains the plugin name and its frontend UI contributions
(menu_items, page_routes, detail_tabs, settings_pages, dashboard_widgets).
"""
result = await db.execute(select(PluginModel).where(PluginModel.active.is_(True)))
active_records = {row.name: row for row in result.scalars().all()}
manifests: list[dict[str, Any]] = []
for name, plugin in self._plugins.items():
if name not in active_records:
continue
m = plugin.manifest
manifests.append(
{
"name": m.name,
"display_name": m.display_name,
"version": m.version,
"is_core": m.is_core,
"menu_items": [item.model_dump() for item in m.menu_items],
"page_routes": [route.model_dump() for route in m.page_routes],
"detail_tabs": [tab.model_dump() for tab in m.detail_tabs],
"settings_pages": [page.model_dump() for page in m.settings_pages],
"dashboard_widgets": [widget.model_dump() for widget in m.dashboard_widgets],
}
)
return manifests
# ── Internal Helpers ──
async def _get_plugin_record(self, db: AsyncSession, name: str) -> PluginModel | None: