myCRM/docs/PLUGIN_QUICKSTART.md

Plugin-System: Schnellstart-Anleitung

🚀 Quick Start (5 Minuten)

1. Environment konfigurieren

# .env.local erstellen
cp .env.plugin.example .env.local

# Werte anpassen
nano .env.local

Minimal-Konfiguration:

LICENSE_SERVER_URL=https://license.mycrm.local
INSTANCE_ID=$(openssl rand -hex 16)

2. Cache leeren

php bin/console cache:clear

3. Test: System überprüfen

# Sollte keine Module zeigen (noch keine installiert)
php bin/console app:module:list

Erwartete Ausgabe:

Installierte Module
===================

 [WARNING] Keine Module installiert.

✅ Core-System ist bereit!

---

📦 Modul installieren (Beispiel)

Schritt 1: Composer-Repository hinzufügen

composer config repositories.mycrm-billing vcs https://github.com/your-org/mycrm-billing-module

Schritt 2: Modul installieren

composer require mycrm/billing-module

Schritt 3: Bundle registrieren (falls nicht automatisch)

// config/bundles.php
return [
    // ... bestehende Bundles
    MyCRM\BillingModule\BillingBundle::class => ['all' => true],
];

Schritt 4: Datenbank-Migrationen

php bin/console doctrine:migrations:migrate

Schritt 5: Cache leeren

php bin/console cache:clear

Schritt 6: Modul-Status prüfen

php bin/console app:module:list

Erwartete Ausgabe:

Installierte Module
===================

 ID       Name            Version   Lizenziert   Aktiv   Lizenz-Info
 billing  Rechnungsmodul  1.0.0     ✗            ✗       Kein Lizenzschlüssel vorhanden

Statistik
---------

Gesamt: 1 Module
Lizenziert: 0 Module
Aktiv: 0 Module

✅ Modul installiert, aber noch nicht lizenziert!

---

🔑 Lizenz aktivieren

Option A: CLI (empfohlen)

# Interaktiv (Lizenzschlüssel wird versteckt eingegeben)
php bin/console app:module:license billing

# Direkt mit Key
php bin/console app:module:license billing eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Option B: Manuell in .env.local

# .env.local
LICENSE_BILLING=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Schritt 2: Validieren

php bin/console app:module:license billing --validate

Erwartete Ausgabe:

Validiere Lizenz für Modul "billing"

 [OK] Lizenz gültig!

Lizenz-Informationen
--------------------

 Eigenschaft   Wert
 Status        ✓ Gültig
 Lizenziert an Firma GmbH
 Läuft ab      31.12.2026 23:59:59
 Verbleibend   365 Tage
 Features      invoicing, recurring_billing

Schritt 3: Cache leeren (wichtig!)

php bin/console cache:clear

Schritt 4: Status prüfen

php bin/console app:module:list

Erwartete Ausgabe:

 ID       Name            Version   Lizenziert   Aktiv   Lizenz-Info
 billing  Rechnungsmodul  1.0.0     ✓            ✓       Firma GmbH, Läuft ab: 31.12.2026

Statistik
---------

Gesamt: 1 Module
Lizenziert: 1 Module
Aktiv: 1 Module

✅ Modul ist aktiv und kann verwendet werden!

---

🌐 Admin-Interface verwenden

Schritt 1: Route hinzufügen

// assets/js/router.js
{
    path: '/admin/modules',
    name: 'module-management',
    component: () => import('@/views/ModuleManagement.vue'),
    meta: {
        requiresAuth: true,
        requiresRole: 'ROLE_ADMIN'
    }
}

Schritt 2: Menü-Eintrag hinzufügen (optional)

<!-- assets/js/layout/AppMenu.vue -->
<template v-if="hasRole('ROLE_ADMIN')">
    <li>
        <router-link to="/admin/modules">
            <i class="pi pi-box"></i>
            <span>Module</span>
        </router-link>
    </li>
</template>

Schritt 3: Frontend neu bauen

npm run build
# oder für Development:
npm run watch

Schritt 4: Admin-UI aufrufen

Navigiere zu: http://localhost:8000/admin/modules

✅ Grafische Verwaltung verfügbar!

---

🗑️ Modul entfernen

Option A: CLI (empfohlen)

# Interaktiv mit Bestätigung
php bin/console app:module:remove billing

# Ohne Bestätigung (force)
php bin/console app:module:remove billing --force

# Lizenz behalten
php bin/console app:module:remove billing --keep-license

# Permission-Datenbank-Eintrag behalten
php bin/console app:module:remove billing --keep-db-entry

Der Command führt folgende Schritte durch:

1. ✓ Modul-Informationen anzeigen (Plugin + Datenbank)
2. ✓ Bestätigung einholen (außer mit --force)
3. ✓ Lizenz widerrufen (außer mit --keep-license)
4. ✓ Datenbank-Eintrag löschen (außer mit --keep-db-entry)
5. → Composer-Command vorschlagen

Manuelle Schritte nach app:module:remove

Der Command zeigt dir die nötigen manuellen Schritte:

# 1. Composer-Package entfernen
composer remove mycrm/billing-module

# 2. Bundle aus config/bundles.php entfernen (falls vorhanden)
# Öffne config/bundles.php und entferne die Zeile:
# MyCRM\BillingModule\BillingBundle::class => ['all' => true],

# 3. Optional: Migrationen zurückrollen (falls benötigt)
php bin/console doctrine:migrations:migrate prev

# 4. Cache leeren
php bin/console cache:clear

Option B: Vollständig manuell

Falls du den Command nicht nutzen möchtest:

# 1. Lizenz widerrufen
php bin/console app:module:license billing --revoke

# 2. Composer-Package entfernen
composer remove mycrm/billing-module

# 3. Bundle aus config/bundles.php entfernen (manuell editieren)

# 4. Optional: Module-Entity aus DB löschen
# Nur nötig, wenn das Modul auch im Permission-System registriert ist
# VORSICHT: Löscht auch verknüpfte RolePermissions!

# 5. Cache leeren
php bin/console cache:clear

Beispiel-Ausgabe

Modul "billing" entfernen
=========================

Modul-Informationen
-------------------

 Eigenschaft                                       Wert
 Plugin-Informationen
   Name                                            Rechnungsmodul
   Version                                         1.0.0
   Beschreibung                                    Rechnungsverwaltung für myCRM
   Lizenziert                                      ✓ Ja
   Aktiv                                           ✓ Ja

 Datenbank-Informationen (Permission-System)
   Name                                            Rechnungen
   Code                                            billing
   Aktiv                                           ✓ Ja
   Permissions                                     3

 ! [NOTE] Möchten Sie dieses Modul wirklich entfernen? (yes/no) [no]:
 > yes

Entferne Modul
--------------

⏳ Widerrufe Lizenz...
 [OK] ✓ Lizenz erfolgreich widerrufen

⏳ Entferne Datenbank-Eintrag (Permission-System)...
 ! [WARNING] ACHTUNG: Dieses Modul hat 3 verknüpfte Permission(s). Diese werden ebenfalls gelöscht!
 ! [NOTE] Trotzdem fortfahren? (yes/no) [no]:
 > yes
 [OK] ✓ Datenbank-Eintrag erfolgreich entfernt

Zusammenfassung
---------------

 * ✓ Lizenz widerrufen
 * ✓ Datenbank-Eintrag gelöscht

Nächste Schritte (manuell)
--------------------------

 * 1. Composer-Package entfernen: composer remove mycrm/billing-module
 * 2. Bundle aus config/bundles.php entfernen (falls vorhanden)
 * 3. Optional: Migrationen zurückrollen (falls benötigt)
      php bin/console doctrine:migrations:migrate prev
 * 4. Cache leeren: php bin/console cache:clear

 [OK] Modul "billing" wurde vorbereitet zum Entfernen. Führen Sie die obigen Schritte manuell aus.

✅ Modul sicher entfernt!

---

🔧 Troubleshooting

Problem: "Modul wird nicht erkannt"

# Prüfen: Bundle registriert?
cat config/bundles.php | grep BillingBundle

# Prüfen: Autoloading aktuell?
composer dump-autoload

# Cache löschen
php bin/console cache:clear

Problem: "Lizenz ungültig"

# Validierung mit Details
php bin/console app:module:license billing --validate

# Lizenz neu eingeben
php bin/console app:module:license billing

# Cache löschen (wichtig!)
php bin/console cache:clear

Problem: "Lizenzserver nicht erreichbar"

# Prüfen: Environment-Variable gesetzt?
echo $LICENSE_SERVER_URL

# Prüfen: Server erreichbar?
curl https://license.mycrm.local/api/validate

# Offline-Modus (Grace Period): Gecachte Lizenz wird verwendet
php bin/console app:module:list
# → Sollte "Lizenz gecacht (Offline-Modus)" zeigen

Problem: "Modul bootet nicht"

# Logs prüfen
tail -f var/log/dev.log | grep -i module

# Doctrine-Schema validieren
php bin/console doctrine:schema:validate

# Alle Abhängigkeiten prüfen
php bin/console app:module:list
# → Zeigt eventuelle Boot-Fehler an

---

📚 Nächste Schritte

Für Administratoren:

1. ✅ Core-System konfiguriert
2. ✅ Erstes Modul installiert
3. ✅ Lizenz aktiviert
4. → Weitere Module installieren (siehe vollständige Anleitung)
5. → Benutzer-Rechte konfigurieren (Role-Permission-System)

Für Entwickler:

1. → Eigenes Modul entwickeln (siehe PLUGIN_SYSTEM.md)
2. → Beispiel-Code studieren (docs/example-module/)
3. → Tests schreiben (Unit, Integration, Functional)

Für DevOps:

1. → Lizenzserver implementieren (externe Komponente)
2. → Monitoring einrichten (Lizenz-Ablaufdaten)
3. → Deployment-Pipeline (Composer, Migrations, Cache)

---

📖 Weiterführende Dokumentation

• Vollständige Anleitung: docs/PLUGIN_SYSTEM.md
• Architektur-Übersicht: docs/PLUGIN_SYSTEM_SUMMARY.md
• Modul-Struktur: docs/EXAMPLE_MODULE_STRUCTURE.md
• Code-Beispiele: docs/example-module/

---

💡 Tipps

Tipp 1: Lizenzschlüssel sicher speichern

# Nie in Git committen!
echo "LICENSE_*" >> .gitignore

# In Production: Environment-Variablen nutzen
# Oder: Verschlüsselte Secrets (Vault, etc.)

Tipp 2: Development vs. Production

# Development: Test-Lizenzen mit langem Ablaufdatum
LICENSE_BILLING=dev-license-key-with-long-expiry

# Production: Produktiv-Lizenzen überwachen
# Monitoring: Alarm 30 Tage vor Ablauf

Tipp 3: Modul-Updates

# Composer-Update für einzelnes Modul
composer update mycrm/billing-module

# Migrations prüfen
php bin/console doctrine:migrations:status

# Migrations ausführen
php bin/console doctrine:migrations:migrate

# Cache leeren (wichtig!)
php bin/console cache:clear

Tipp 4: Offline-Betrieb planen

# Grace Period: 7 Tage nach letzter Validierung
# Vor längeren Offline-Phasen: Cache auffrischen
php bin/console app:module:license billing --validate

---

✅ Checkliste

Vor Produktiv-Deployment:

• .env.local mit allen Lizenzen auf Server deployed
• LICENSE_SERVER_URL korrekt konfiguriert
• INSTANCE_ID eindeutig generiert
• Alle Module installiert (composer install)
• Migrations ausgeführt (doctrine:migrations:migrate)
• Cache geleert (cache:clear)
• Lizenzen validiert (app:module:list)
• Backup-Strategie inkludiert .env.local
• Monitoring für Lizenz-Ablaufdaten eingerichtet
• Firewall erlaubt Zugriff auf Lizenzserver

---

Bei Fragen: Siehe vollständige Dokumentation in docs/PLUGIN_SYSTEM.md