docs: Core Plugin & Dependency concept — is_core flag, topological sort, report_generator, ERP roadmap

docs/core-plugin-concept.md

@@ -0,0 +1,336 @@
+# LeoCRM — Core Plugin & Dependency Konzept
+
+## 1. Ziel
+
+LeoCRM soll modular zu einem ERP ausgebaut werden. Die Plugin-Architektur ist bereits vorhanden (Manifest, BasePlugin, Registry), aber es fehlen:
+
+1. **Core Plugins** — unverzichtbare Basis-Plugins die immer aktiv sind
+2. **Dependency Resolution** — Plugins können Abhängigkeiten deklarieren und diese werden durchgesetzt
+3. **ERP-Module** — fachliche Erweiterungen die auf Core-Plugins aufbauen
+
+## 2. Plugin-Kategorien
+
+### 2.1 Core Plugins (`is_core: true`)
+
+- **Immer aktiv** — können nicht deaktiviert oder deinstalliert werden
+- **Werden als erste geladen** — vor allen Nicht-Core-Plugins
+- **Basis-Funktionalität** die andere Plugins voraussetzen
+- **Beispiele:**
+  - `permissions` — RBAC-System
+  - `entity_links` — Querverweise zwischen Entitäten
+  - `tags` — Tagging-System
+  - `report_generator` — Report- & Dokumentgenerator
+  - `audit` — Audit-Log (bereits im Core, nicht als Plugin)
+
+### 2.2 Builtin Plugins
+
+- **Mitgeliefert aber optional** — können deaktiviert werden
+- **Dürfen Core-Dependencies deklarieren**
+- **Beispiele:** `dms`, `mail`, `calendar`
+
+### 2.3 Custom Plugins
+
+- **Nutzer-/Drittanbieter-Plugins** — zur Laufzeit installierbar
+- **Müssen Dependencies explizit deklarieren**
+- **Beispiele:** ERP-Module (Invoicing, Inventory, HR, etc.)
+
+## 3. Manifest-Erweiterung
+
+```python
+class PluginManifest(BaseModel):
+    # ... bestehende Felder ...
+    
+    # NEU: Core-Plugin Flag
+    is_core: bool = Field(
+        default=False,
+        description="Core plugins cannot be deactivated and load first"
+    )
+    
+    # NEU: Mindestversion für Dependencies
+    dependencies: list[str] = Field(
+        default_factory=list,
+        description="Plugin names this plugin requires (must be installed and active)"
+    )
+    
+    # ERWEITERT: Semantic dependency with version
+    # dependency: str = "permissions>=1.0.0"
+    # Format: plugin_name[>=|>|<=|<|==version]
+```
+
+## 4. Dependency Resolution
+
+### 4.1 Topological Sort
+
+Die Registry muss Plugins in Abhängigkeits-Reihenfolge laden:
+
+```
+1. permissions (is_core, keine deps)
+2. entity_links (is_core, deps: [permissions])
+3. tags (is_core, deps: [permissions])
+4. report_generator (is_core, deps: [permissions, entity_links])
+5. dms (deps: [permissions])
+6. mail (deps: [permissions])
+7. calendar (deps: [permissions])
+8. invoicing (deps: [permissions, report_generator])  ← ERP-Modul
+```
+
+### 4.2 Algorithmus
+
+```python
+def resolve_load_order(plugins: dict[str, BasePlugin]) -> list[str]:
+    """Topological sort: Core first, then by dependency order."""
+    # 1. Kahn's Algorithm oder DFS-based topo sort
+    # 2. Core-Plugins bekommen Priorität bei gleichrangigen Abhängigkeiten
+    # 3. Zyklus-Erkennung: RuntimeError bei zirkulären Dependencies
+    # 4. Fehlende Dependency: RuntimeError mit klarer Meldung
+```
+
+### 4.3 Validierung beim Installieren
+
+```python
+async def validate_dependencies(plugin: BasePlugin, db: AsyncSession) -> None:
+    """Prüft vor Installation ob alle Dependencies erfüllt sind."""
+    for dep_name in plugin.manifest.dependencies:
+        dep = await get_plugin_record(db, dep_name)
+        if dep is None:
+            raise PluginDependencyError(
+                f"Plugin '{plugin.name}' requires '{dep_name}' which is not installed"
+            )
+        if not dep.active:
+            raise PluginDependencyError(
+                f"Plugin '{plugin.name}' requires '{dep_name}' to be active"
+            )
+```
+
+### 4.4 Deaktivierungs-Schutz
+
+```python
+async def deactivate_plugin(name: str, db: AsyncSession) -> None:
+    """Verhindert Deaktivierung wenn andere Plugins abhängen."""
+    # 1. Prüfe ob Plugin is_core → Fehler
+    # 2. Prüfe ob andere aktive Plugins dieses Plugin als Dependency haben → Fehler
+    dependents = await get_dependent_plugins(db, name)
+    if dependents:
+        raise PluginDependencyError(
+            f"Cannot deactivate '{name}': {dependents} still depend on it"
+        )
+```
+
+## 5. Report Generator als Core Plugin
+
+### 5.1 Konzept
+
+Der Report Generator ist ein **Core Plugin** das Dokumente und Reports erzeugt. ERP-Module (Invoicing, Inventory, etc.) nutzen ihn als Dependency.
+
+### 5.2 Manifest
+
+```python
+class ReportGeneratorPlugin(BasePlugin):
+    manifest = PluginManifest(
+        name="report_generator",
+        version="1.0.0",
+        display_name="Report Generator",
+        description="Generates PDF/Excel/CSV reports from templates and data sources",
+        is_core=True,
+        dependencies=["permissions", "entity_links"],
+        routes=[
+            PluginRouteDef(
+                path="/api/v1/reports",
+                module="app.plugins.builtins.report_generator.routes",
+                router_attr="router",
+            ),
+        ],
+        events=["report.requested", "report.generated"],
+        migrations=["0001_initial.sql"],
+        permissions=["reports.read", "reports.generate", "reports.manage_templates"],
+    )
+```
+
+### 5.3 Funktionalität
+
+- **Template Engine** — Jinja2-basierte Templates für PDF/Excel/CSV
+- **Data Sources** — SQL-Queries oder Python-Funktionen als Datenquelle
+- **Scheduling** — Cron-basierte Report-Generierung
+- **Output** — PDF (WeasyPrint), Excel (openpyxl), CSV, JSON
+- **Storage** — Reports werden im DMS gespeichert (wenn DMS aktiv)
+- **Distribution** — E-Mail-Versand, Download, API
+
+### 5.4 API Endpoints
+
+```
+GET    /api/v1/reports/templates          — Liste aller Templates
+POST   /api/v1/reports/templates          — Template erstellen
+GET    /api/v1/reports/templates/{id}     — Template Details
+PUT    /api/v1/reports/templates/{id}     — Template aktualisieren
+DELETE /api/v1/reports/templates/{id}     — Template löschen
+
+POST   /api/v1/reports/generate           — Report generieren (async)
+GET    /api/v1/reports/{id}               — Report Status/Download
+GET    /api/v1/reports/{id}/download      — Report herunterladen
+
+GET    /api/v1/reports/scheduled           — Geplante Reports
+POST   /api/v1/reports/scheduled           — Report planen
+DELETE /api/v1/reports/scheduled/{id}     — Geplanten Report löschen
+```
+
+### 5.5 ERP-Nutzung
+
+Ein ERP-Modul "Invoicing" würde den Report Generator nutzen:
+
+```python
+class InvoicingPlugin(BasePlugin):
+    manifest = PluginManifest(
+        name="invoicing",
+        version="1.0.0",
+        display_name="Invoicing",
+        description="Invoice management with PDF generation",
+        dependencies=["permissions", "report_generator", "currencies", "taxes"],
+        routes=[
+            PluginRouteDef(
+                path="/api/v1/invoicing",
+                module="app.plugins.builtins.invoicing.routes",
+                router_attr="router",
+            ),
+        ],
+        events=["invoice.created", "invoice.sent", "invoice.paid"],
+    )
+    
+    async def on_invoice_created(self, payload: dict) -> None:
+        """When an invoice is created, generate PDF via report_generator."""
+        # Ruft report_generator API auf: POST /api/v1/reports/generate
+        # Template: "invoice_template"
+        # Data: payload (invoice data)
+        # Output: PDF
+```
+
+## 6. ERP-Aufbau-Strategie
+
+### 6.1 Phasen
+
+| Phase | Plugins | Funktionalität |
+|---|---|---|
+| **Phase 1** | `report_generator` (Core) | Report- & Dokumentgenerator |
+| **Phase 2** | `invoicing` | Rechnungen mit PDF-Generierung |
+| **Phase 3** | `inventory` | Lagerverwaltung, Bestandsführung |
+| **Phase 4** | `purchase_orders` | Bestellungen, Lieferanten |
+| **Phase 5** | `hr` | Mitarbeiter, Gehalt, Urlaub |
+| **Phase 6** | `accounting` | Buchhaltung, Buchungen, Bilanz |
+
+### 6.2 Abhängigkeits-Graph
+
+```
+permissions (Core)
+├── entity_links (Core)
+├── tags (Core)
+├── report_generator (Core)
+│   ├── invoicing
+│   │   └── accounting
+│   ├── purchase_orders
+│   │   └── accounting
+│   └── hr
+├── currencies (Core, bereits als Basis-Feature)
+├── taxes (Core, bereits als Basis-Feature)
+├── dms (Builtin)
+├── mail (Builtin)
+└── calendar (Builtin)
+```
+
+### 6.3 Implementierungs-Prinzipien
+
+1. **Jedes ERP-Modul ist ein Plugin** — kein festcodiertes ERP
+2. **Core-Plugins sind stabil** — brechen nie andere Plugins
+3. **Versionierte Dependencies** — `dependencies=["report_generator>=1.0.0"]`
+4. **Event-Driven** — Plugins kommunizieren über Events, nicht direkte Aufrufe
+5. **Tenant-Isolated** — Jedes Plugin respektiert Tenant-Grenzen
+6. **Frontend-Modular** — Plugin-Frontends werden dynamisch geladen
+
+## 7. Technische Umsetzung
+
+### 7.1 Registry-Erweiterung
+
+```python
+# app/plugins/registry.py — neue Methoden
+
+class PluginRegistry:
+    # ... bestehend ...
+    
+    def resolve_load_order(self) -> list[str]:
+        """Topological sort of all discovered plugins."""
+        # 1. Build dependency graph
+        # 2. Core-Plugins first
+        # 3. Topological sort (Kahn's algorithm)
+        # 4. Cycle detection
+        # 5. Missing dependency detection
+    
+    async def validate_dependencies(
+        self, plugin_name: str, db: AsyncSession
+    ) -> list[str]:
+        """Check if all dependencies are installed and active."""
+        # Returns list of missing/unmet dependencies
+    
+    async def get_dependents(
+        self, plugin_name: str, db: AsyncSession
+    ) -> list[str]:
+        """Find all plugins that depend on this one."""
+        # For deactivation protection
+```
+
+### 7.2 Plugin Model Erweiterung
+
+```python
+# app/models/plugin.py — neues Feld
+class Plugin(BaseModel):
+    # ... bestehende Felder ...
+    is_core: Mapped[bool] = mapped_column(Boolean, default=False)
+```
+
+### 7.3 Startup-Sequenz (main.py)
+
+```python
+# Aktuell: Alle Builtins werden automatisch installiert+aktiviert
+# Neu:
+# 1. Discover all plugins
+# 2. resolve_load_order() → [permissions, entity_links, tags, report_generator, dms, mail, calendar]
+# 3. For each in order:
+#    a. Check if in DB → if not, create record (is_core=True for core plugins)
+#    b. Run migrations
+#    c. Activate (skip for non-core if deactivated by admin)
+#    d. Register routes
+```
+
+## 8. Frontend-Anpassung
+
+### 8.1 Sidebar dynamisch
+
+Die Sidebar sollte Plugins nicht mehr hardcoded listen, sondern dynamisch aus der Plugin-API laden:
+
+```typescript
+// GET /api/v1/plugins/active → [{name, display_name, icon, route_prefix, is_core}]
+// Sidebar rendert nur aktive Plugins
+```
+
+### 8.2 Plugin-Frontend-Laden
+
+Jedes Plugin kann ein Frontend-Modul mitbringen:
+
+```
+app/plugins/builtins/invoicing/
+├── __init__.py
+├── plugin.py          # Backend Plugin
+├── routes.py          # API Routes
+├── manifest.py        # (in plugin.py)
+├── migrations/        # SQL Migrations
+└── frontend/          # Frontend Module
+    ├── index.tsx      # Plugin Entry Point
+    ├── pages/         # Plugin Pages
+    └── components/    # Plugin Components
+```
+
+## 9. Nächste Schritte
+
+1. **Manifest erweitern** — `is_core` Feld hinzufügen
+2. **Registry erweitern** — `resolve_load_order()`, `validate_dependencies()`, `get_dependents()`
+3. **Plugin Model erweitern** — `is_core` Spalte
+4. **Startup-Sequenz anpassen** — Core-First, Topological Sort
+5. **Report Generator Plugin bauen** — Templates, PDF/Excel, Scheduling
+6. **ERP-Module starten** — Invoicing als erstes Modul